headscale/docs/running-headscale-linux-manual.md

Running headscale on Linux

!!! warning "Outdated and advanced"

This documentation is considered the "legacy"/advanced/manual version of the documentation, you most likely do not
want to use this documentation and rather look at the [distro specific documentation](./running-headscale-linux.md).

Goal

This documentation has the goal of showing a user how-to set up and run headscale on Linux. In additional to the "get up and running section", there is an optional SystemD section describing how to make headscale run properly in a server environment.

Configure and run headscale

1. Download the latest headscale binary from GitHub's release page:

   wget --output-document=/usr/local/bin/headscale \
   https://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>
   

2. Make headscale executable:

   chmod +x /usr/local/bin/headscale
   

3. Prepare a directory to hold headscale configuration and the SQLite database:

   # Directory for configuration
   
   mkdir -p /etc/headscale
   
   # Directory for Database, and other variable data (like certificates)
   mkdir -p /var/lib/headscale
   # or if you create a headscale user:
   useradd \
     --create-home \
     --home-dir /var/lib/headscale/ \
     --system \
     --user-group \
     --shell /usr/sbin/nologin \
     headscale
   

4. Create a headscale configuration:

   touch /etc/headscale/config.yaml
   

   (Strongly Recommended) Download a copy of the example configuration from the headscale repository.

5. Start the headscale server:

   headscale serve
   

   This command will start headscale in the current terminal session.

   ---

   To continue the tutorial, open a new terminal and let it run in the background. Alternatively use terminal emulators like tmux or screen.

   To run headscale in the background, please follow the steps in the SystemD section before continuing.

6. Verify headscale is running: Verify headscale is available:

   curl http://127.0.0.1:9090/metrics
   

7. Create a user (tailnet):

   headscale users create myfirstuser
   

Register a machine (normal login)

On a client machine, execute the tailscale login command:

tailscale up --login-server YOUR_HEADSCALE_URL

Register the machine:

headscale --user myfirstuser nodes register --key <YOUR_MACHINE_KEY>

Register machine using a pre authenticated key

Generate a key using the command line:

headscale --user myfirstuser preauthkeys create --reusable --expiration 24h

This will return a pre-authenticated key that can be used to connect a node to headscale during the tailscale command:

tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>

Running headscale in the background with SystemD

⚠️ Deprecated: This part is very outdated and you should use the pre-packaged Headscale for this

This section demonstrates how to run headscale as a service in the background with SystemD. This should work on most modern Linux distributions.

1. Create a SystemD service configuration at /etc/systemd/system/headscale.service containing:

   [Unit]
   Description=headscale controller
   After=syslog.target
   After=network.target
   
   [Service]
   Type=simple
   User=headscale
   Group=headscale
   ExecStart=/usr/local/bin/headscale serve
   Restart=always
   RestartSec=5
   
   # Optional security enhancements
   NoNewPrivileges=yes
   PrivateTmp=yes
   ProtectSystem=strict
   ProtectHome=yes
   WorkingDirectory=/var/lib/headscale
   ReadWritePaths=/var/lib/headscale /var/run/headscale
   AmbientCapabilities=CAP_NET_BIND_SERVICE
   RuntimeDirectory=headscale
   
   [Install]
   WantedBy=multi-user.target
   

   Note that when running as the headscale user ensure that, either you add your current user to the headscale group:

   usermod -a -G headscale current_user
   

   or run all headscale commands as the headscale user:

   su - headscale
   

2. In /etc/headscale/config.yaml, override the default headscale unix socket with path that is writable by the headscale user or group:

   unix_socket: /var/run/headscale/headscale.sock
   

3. Reload SystemD to load the new configuration file:

   systemctl daemon-reload
   

4. Enable and start the new headscale service:

   systemctl enable --now headscale
   

5. Verify the headscale service:

   systemctl status headscale
   

   Verify headscale is available:

   curl http://127.0.0.1:9090/metrics
   

headscale will now run in the background and start at boot.