juanfont/headscale
1
1
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2024-09-20 15:26:35 +08:00
Code Issues Packages Projects Releases Wiki Activity

Simplify windows setup instructions (#2114)

Browse source 
* 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 2024-09-09 13:18:16 +02:00 committed by GitHub
parent 5597edac1e
commit bac7ea67f4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
6 changed files with 42 additions and 149 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
docs/images/windows-registry.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 101 KiB

61
docs/windows-client.md
View file

@ -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`. 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:
![windows-registry](./images/windows-registry.png)
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 ## Installation
Download the [Official Windows Client](https://tailscale.com/download/windows) and install it. 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 ## 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: 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: To reset and try again, it is important to do the following:
1. Ensure the registry keys from the previous guide is correctly set. 1. Shut down the Tailscale service (or the client running in the tray)
2. 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. 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. Ensure the Windows node is deleted from headscale (to ensure fresh setup) 4. Start Tailscale on the Windows machine and retry the login.
5. Start Tailscale on the windows machine and retry the login.

2
hscontrol/app.go
View file

@ -437,8 +437,6 @@ func (h *Headscale) createRouter(grpcMux *grpcRuntime.ServeMux) *mux.Router {
router.HandleFunc("/apple/{platform}", h.ApplePlatformConfig). router.HandleFunc("/apple/{platform}", h.ApplePlatformConfig).
Methods(http.MethodGet) Methods(http.MethodGet)
router.HandleFunc("/windows", h.WindowsConfigMessage).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 // TODO(kristoffer): move swagger into a package
router.HandleFunc("/swagger", headscale.SwaggerUI).Methods(http.MethodGet) router.HandleFunc("/swagger", headscale.SwaggerUI).Methods(http.MethodGet)

52
hscontrol/platform_config.go
View file

@ -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. // 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( func (h *Headscale) AppleConfigMessage(
writer http.ResponseWriter, writer http.ResponseWriter,
@ -305,10 +265,6 @@ func (h *Headscale) ApplePlatformConfig(
} }
} }
type WindowsRegistryConfig struct {
URL string
}
type AppleMobileConfig struct { type AppleMobileConfig struct {
UUID uuid.UUID UUID uuid.UUID
URL string URL string
@ -320,14 +276,6 @@ type AppleMobilePlatformConfig struct {
URL string 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( var commonTemplate = textTemplate.Must(
textTemplate.New("mobileconfig").Parse(`<?xml version="1.0" encoding="UTF-8"?> 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"> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

74
hscontrol/templates/windows.html
View file

@ -25,75 +25,21 @@
<body> <body>
<h1>headscale: Windows configuration</h1> <h1>headscale: Windows configuration</h1>
<h2>Recent Tailscale versions (1.34.0 and higher)</h2>
<p> <p>
Tailscale added Fast User Switching in version 1.34 and you can now use Download
the new login command to connect to one or more headscale (and Tailscale) <a
servers. The previously used profiles does not have an effect anymore. href="https://tailscale.com/download/windows"
</p> rel="noreferrer noopener"
<p>Use Tailscale's login command to add your profile:</p> target="_blank"
<pre><code>tailscale login --login-server {{.URL}}</code></pre> >Tailscale for Windows</a
<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
> >
and install it.
</p> </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> <p>
Open command prompt with Administrator rights. Issue the following Open a Command Prompt or Powershell and use Tailscale's login command to
commands to add the required registry entries: connect with headscale:
</p> </p>
<pre> <pre><code>tailscale login --login-server {{.URL}}</code></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>
</body> </body>
</html> </html>

2
mkdocs.yml
View file

@ -10,7 +10,7 @@ repo_name: juanfont/headscale
repo_url: https://github.com/juanfont/headscale repo_url: https://github.com/juanfont/headscale
# Copyright # Copyright
copyright: Copyright &copy; 2023 Headscale authors copyright: Copyright &copy; 2024 Headscale authors
# Configuration # Configuration
theme: theme: