Simplify windows setup instructions (#2114)
* Simplify /windows to the bare minimum. Also remove the /windows/tailscale.reg endpoint as its generated file is no longer valid for current Tailscale versions. * Update and simplify the windows documentation accordingly. * Add a "Unattended mode" section to the troubleshooting section explaining how to enable "Unattended mode" in the via the Tailscale tray icon. * Add infobox about /windows to the docs Tested on Windows 10, 22H2 with Tailscale 1.72.0 Replaces: #1995 See: #2096
This commit is contained in:
nblock
GitHub
parent
5597edac1e
commit
bac7ea67f4
Binary file not shown.
|
Before Width: | Height: | Size: 101 KiB |
|
|
@ -4,39 +4,41 @@
|
|||
|
||||
This documentation has the goal of showing how a user can use the official Windows [Tailscale](https://tailscale.com) client with `headscale`.
|
||||
|
||||
## Add registry keys
|
||||
|
||||
To make the Windows client behave as expected and to run well with `headscale`, two registry keys **must** be set:
|
||||
|
||||
- `HKLM:\SOFTWARE\Tailscale IPN\UnattendedMode` must be set to `always` as a `string` type, to allow Tailscale to run properly in the background
|
||||
- `HKLM:\SOFTWARE\Tailscale IPN\LoginURL` must be set to `<YOUR HEADSCALE URL>` as a `string` type, to ensure Tailscale contacts the correct control server.
|
||||
|
||||
You can set these using the Windows Registry Editor:
|
||||
|
||||
|
||||
|
||||
Or via the following Powershell commands (right click Powershell icon and select "Run as administrator"):
|
||||
|
||||
```
|
||||
New-Item -Path "HKLM:\SOFTWARE\Tailscale IPN"
|
||||
New-ItemProperty -Path 'HKLM:\Software\Tailscale IPN' -Name UnattendedMode -PropertyType String -Value always
|
||||
New-ItemProperty -Path 'HKLM:\Software\Tailscale IPN' -Name LoginURL -PropertyType String -Value https://YOUR-HEADSCALE-URL
|
||||
```
|
||||
|
||||
The Tailscale Windows client has been observed to reset its configuration on logout/reboot and these two keys [resolves that issue](https://github.com/tailscale/tailscale/issues/2798).
|
||||
|
||||
For a guide on how to edit registry keys, [check out Computer Hope](https://www.computerhope.com/issues/ch001348.htm).
|
||||
|
||||
## Installation
|
||||
|
||||
Download the [Official Windows Client](https://tailscale.com/download/windows) and install it.
|
||||
|
||||
When the installation has finished, start Tailscale and log in (you might have to click the icon in the system tray).
|
||||
## Configuring the headscale URL
|
||||
|
||||
The log in should open a browser Window and direct you to your `headscale` instance.
|
||||
!!! info "Instructions on your headscale instance"
|
||||
|
||||
An endpoint with information on how to connect your Windows device
|
||||
is also available at `/windows` on your running instance.
|
||||
|
||||
Open a Command Prompt or Powershell and use Tailscale's login command to connect with your headscale instance (e.g
|
||||
`https://headscale.example.com`):
|
||||
|
||||
```
|
||||
tailscale login --login-server <YOUR_HEADSCALE_URL>
|
||||
```
|
||||
|
||||
Follow the instructions in the opened browser window to finish the configuration.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Unattended mode
|
||||
|
||||
By default, Tailscale's Windows client is only running when the user is logged in. If you want to keep Tailscale running
|
||||
all the time, please enable "Unattended mode":
|
||||
|
||||
- Click on the Tailscale tray icon and select `Preferences`
|
||||
- Enable `Run unattended`
|
||||
- Confirm the "Unattended mode" message
|
||||
|
||||
See also [Keep Tailscale running when I'm not logged in to my computer](https://tailscale.com/kb/1088/run-unattended)
|
||||
|
||||
### Failing node registration
|
||||
|
||||
If you are seeing repeated messages like:
|
||||
|
||||
```
|
||||
|
|
@ -53,8 +55,7 @@ This typically means that the registry keys above was not set appropriately.
|
|||
|
||||
To reset and try again, it is important to do the following:
|
||||
|
||||
1. Ensure the registry keys from the previous guide is correctly set.
|
||||
2. Shut down the Tailscale service (or the client running in the tray)
|
||||
3. Delete Tailscale Application data folder, located at `C:\Users\<USERNAME>\AppData\Local\Tailscale` and try to connect again.
|
||||
4. Ensure the Windows node is deleted from headscale (to ensure fresh setup)
|
||||
5. Start Tailscale on the windows machine and retry the login.
|
||||
1. Shut down the Tailscale service (or the client running in the tray)
|
||||
2. Delete Tailscale Application data folder, located at `C:\Users\<USERNAME>\AppData\Local\Tailscale` and try to connect again.
|
||||
3. Ensure the Windows node is deleted from headscale (to ensure fresh setup)
|
||||
4. Start Tailscale on the Windows machine and retry the login.
|
||||
|
|
|
|||
|
|
@ -437,8 +437,6 @@ func (h *Headscale) createRouter(grpcMux *grpcRuntime.ServeMux) *mux.Router {
|
|||
router.HandleFunc("/apple/{platform}", h.ApplePlatformConfig).
|
||||
Methods(http.MethodGet)
|
||||
router.HandleFunc("/windows", h.WindowsConfigMessage).Methods(http.MethodGet)
|
||||
router.HandleFunc("/windows/tailscale.reg", h.WindowsRegConfig).
|
||||
Methods(http.MethodGet)
|
||||
|
||||
// TODO(kristoffer): move swagger into a package
|
||||
router.HandleFunc("/swagger", headscale.SwaggerUI).Methods(http.MethodGet)
|
||||
|
|
|
|||
|
|
@ -59,46 +59,6 @@ func (h *Headscale) WindowsConfigMessage(
|
|||
}
|
||||
}
|
||||
|
||||
// WindowsRegConfig generates and serves a .reg file configured with the Headscale server address.
|
||||
func (h *Headscale) WindowsRegConfig(
|
||||
writer http.ResponseWriter,
|
||||
req *http.Request,
|
||||
) {
|
||||
config := WindowsRegistryConfig{
|
||||
URL: h.cfg.ServerURL,
|
||||
}
|
||||
|
||||
var content bytes.Buffer
|
||||
if err := windowsRegTemplate.Execute(&content, config); err != nil {
|
||||
log.Error().
|
||||
Str("handler", "WindowsRegConfig").
|
||||
Err(err).
|
||||
Msg("Could not render Apple macOS template")
|
||||
|
||||
writer.Header().Set("Content-Type", "text/plain; charset=utf-8")
|
||||
writer.WriteHeader(http.StatusInternalServerError)
|
||||
_, err := writer.Write([]byte("Could not render Windows registry template"))
|
||||
if err != nil {
|
||||
log.Error().
|
||||
Caller().
|
||||
Err(err).
|
||||
Msg("Failed to write response")
|
||||
}
|
||||
|
||||
return
|
||||
}
|
||||
|
||||
writer.Header().Set("Content-Type", "text/x-ms-regedit; charset=utf-8")
|
||||
writer.WriteHeader(http.StatusOK)
|
||||
_, err := writer.Write(content.Bytes())
|
||||
if err != nil {
|
||||
log.Error().
|
||||
Caller().
|
||||
Err(err).
|
||||
Msg("Failed to write response")
|
||||
}
|
||||
}
|
||||
|
||||
// AppleConfigMessage shows a simple message in the browser to point the user to the iOS/MacOS profile and instructions for how to install it.
|
||||
func (h *Headscale) AppleConfigMessage(
|
||||
writer http.ResponseWriter,
|
||||
|
|
@ -305,10 +265,6 @@ func (h *Headscale) ApplePlatformConfig(
|
|||
}
|
||||
}
|
||||
|
||||
type WindowsRegistryConfig struct {
|
||||
URL string
|
||||
}
|
||||
|
||||
type AppleMobileConfig struct {
|
||||
UUID uuid.UUID
|
||||
URL string
|
||||
|
|
@ -320,14 +276,6 @@ type AppleMobilePlatformConfig struct {
|
|||
URL string
|
||||
}
|
||||
|
||||
var windowsRegTemplate = textTemplate.Must(
|
||||
textTemplate.New("windowsconfig").Parse(`Windows Registry Editor Version 5.00
|
||||
|
||||
[HKEY_LOCAL_MACHINE\SOFTWARE\Tailscale IPN]
|
||||
"UnattendedMode"="always"
|
||||
"LoginURL"="{{.URL}}"
|
||||
`))
|
||||
|
||||
var commonTemplate = textTemplate.Must(
|
||||
textTemplate.New("mobileconfig").Parse(`<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
|
|
|
|||
|
|
@ -25,75 +25,21 @@
|
|||
|
||||
<body>
|
||||
<h1>headscale: Windows configuration</h1>
|
||||
<h2>Recent Tailscale versions (1.34.0 and higher)</h2>
|
||||
<p>
|
||||
Tailscale added Fast User Switching in version 1.34 and you can now use
|
||||
the new login command to connect to one or more headscale (and Tailscale)
|
||||
servers. The previously used profiles does not have an effect anymore.
|
||||
</p>
|
||||
<p>Use Tailscale's login command to add your profile:</p>
|
||||
<pre><code>tailscale login --login-server {{.URL}}</code></pre>
|
||||
|
||||
<h2>Windows registry configuration (1.32.0 and lower)</h2>
|
||||
<p>
|
||||
This page provides Windows registry information for the official Windows
|
||||
Tailscale client.
|
||||
</p>
|
||||
|
||||
<p></p>
|
||||
<p>
|
||||
The registry file will configure Tailscale to use <code>{{.URL}}</code> as
|
||||
its control server.
|
||||
</p>
|
||||
|
||||
<p></p>
|
||||
<h3>Caution</h3>
|
||||
<p>
|
||||
You should always download and inspect the registry file before installing
|
||||
it:
|
||||
</p>
|
||||
<pre><code>curl {{.URL}}/windows/tailscale.reg</code></pre>
|
||||
|
||||
<h2>Installation</h2>
|
||||
<p>
|
||||
Headscale can be set to the default server by running the registry file:
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<a href="/windows/tailscale.reg" download="tailscale.reg"
|
||||
>Windows registry file</a
|
||||
Download
|
||||
<a
|
||||
href="https://tailscale.com/download/windows"
|
||||
rel="noreferrer noopener"
|
||||
target="_blank"
|
||||
>Tailscale for Windows</a
|
||||
>
|
||||
and install it.
|
||||
</p>
|
||||
|
||||
<ol>
|
||||
<li>Download the registry file, then run it</li>
|
||||
<li>Follow the prompts</li>
|
||||
<li>Install and run the official windows Tailscale client</li>
|
||||
<li>
|
||||
When the installation has finished, start Tailscale, and log in by
|
||||
clicking the icon in the system tray
|
||||
</li>
|
||||
</ol>
|
||||
<p>Or using REG:</p>
|
||||
<p>
|
||||
Open command prompt with Administrator rights. Issue the following
|
||||
commands to add the required registry entries:
|
||||
Open a Command Prompt or Powershell and use Tailscale's login command to
|
||||
connect with headscale:
|
||||
</p>
|
||||
<pre>
|
||||
<code>REG ADD "HKLM\Software\Tailscale IPN" /v UnattendedMode /t REG_SZ /d always
|
||||
REG ADD "HKLM\Software\Tailscale IPN" /v LoginURL /t REG_SZ /d "{{.URL}}"</code>
|
||||
</pre>
|
||||
<p>Or using Powershell</p>
|
||||
<p>
|
||||
Open Powershell with Administrator rights. Issue the following commands to
|
||||
add the required registry entries:
|
||||
</p>
|
||||
<pre>
|
||||
<code>New-ItemProperty -Path 'HKLM:\Software\Tailscale IPN' -Name UnattendedMode -PropertyType String -Value always
|
||||
New-ItemProperty -Path 'HKLM:\Software\Tailscale IPN' -Name LoginURL -PropertyType String -Value "{{.URL}}"</code>
|
||||
</pre>
|
||||
<p>Finally, restart Tailscale and log in.</p>
|
||||
|
||||
<p></p>
|
||||
<pre><code>tailscale login --login-server {{.URL}}</code></pre>
|
||||
</body>
|
||||
</html>
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ repo_name: juanfont/headscale
|
|||
repo_url: https://github.com/juanfont/headscale
|
||||
|
||||
# Copyright
|
||||
copyright: Copyright © 2023 Headscale authors
|
||||
copyright: Copyright © 2024 Headscale authors
|
||||
|
||||
# Configuration
|
||||
theme:
|
||||
|
|
|
|||
Loading…
Reference in New Issue