2022-01-02 11:11:36 -07:00
# Running headscale on Linux
2024-09-03 05:04:20 -06:00
!!! warning "Outdated and advanced"
2023-04-19 09:06:50 -06:00
2024-09-03 05:04:20 -06:00
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 ).
2023-04-19 08:49:10 -06:00
2022-01-02 11:11:36 -07:00
## Goal
This documentation has the goal of showing a user how-to set up and run `headscale` on Linux.
2022-01-02 12:48:57 -07:00
In additional to the "get up and running section", there is an optional [SystemD section ](#running-headscale-in-the-background-with-systemd )
2022-01-02 11:11:36 -07:00
describing how to make `headscale` run properly in a server environment.
## Configure and run `headscale`
2022-01-02 12:48:57 -07:00
1. Download the latest [`headscale` binary from GitHub's release page ](https://github.com/juanfont/headscale/releases ):
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
```shell
wget --output-document=/usr/local/bin/headscale \
https://github.com/juanfont/headscale/releases/download/v< HEADSCALE VERSION > /headscale_< HEADSCALE VERSION > _linux_< ARCH >
```
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
1. Make `headscale` executable:
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
```shell
chmod +x /usr/local/bin/headscale
```
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
1. Prepare a directory to hold `headscale` configuration and the [SQLite ](https://www.sqlite.org/ ) database:
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
```shell
# Directory for configuration
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
mkdir -p /etc/headscale
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
# 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
```
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
1. Create a `headscale` configuration:
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
```shell
touch /etc/headscale/config.yaml
```
2022-01-02 11:11:36 -07:00
2024-05-28 10:11:39 -06:00
** (Strongly Recommended)** Download a copy of the [example configuration ](https://github.com/juanfont/headscale/blob/main/config-example.yaml ) from the headscale repository.
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
1. Start the headscale server:
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
```shell
headscale serve
```
2022-01-02 12:55:38 -07:00
2024-03-22 12:55:20 -06:00
This command will start `headscale` in the current terminal session.
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
---
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
To continue the tutorial, open a new terminal and let it run in the background.
Alternatively use terminal emulators like [tmux ](https://github.com/tmux/tmux ) or [screen ](https://www.gnu.org/software/screen/ ).
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
To run `headscale` in the background, please follow the steps in the [SystemD section ](#running-headscale-in-the-background-with-systemd ) before continuing.
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
1. Verify `headscale` is running:
Verify `headscale` is available:
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
```shell
curl http://127.0.0.1:9090/metrics
```
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
1. Create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)):
```shell
headscale users create myfirstuser
```
2022-01-02 11:11:36 -07:00
### Register a machine (normal login)
On a client machine, execute the `tailscale` login command:
```shell
tailscale up --login-server YOUR_HEADSCALE_URL
```
Register the machine:
```shell
2024-09-04 06:38:38 -06:00
headscale nodes register --user myfirstuser --key < YOUR_MACHINE_KEY >
2022-01-02 11:11:36 -07:00
```
### Register machine using a pre authenticated key
Generate a key using the command line:
```shell
2024-09-04 06:38:38 -06:00
headscale preauthkeys create --user myfirstuser --reusable --expiration 24h
2022-01-02 11:11:36 -07:00
```
This will return a pre-authenticated key that can be used to connect a node to `headscale` during the `tailscale` command:
```shell
tailscale up --login-server < YOUR_HEADSCALE_URL > --authkey < YOUR_AUTH_KEY >
```
## Running `headscale` in the background with SystemD
2024-03-22 12:55:20 -06:00
:warning: **Deprecated** : This part is very outdated and you should use the [pre-packaged Headscale for this ](./running-headscale-linux.md )
2023-04-19 08:49:10 -06:00
2022-01-15 00:32:52 -07:00
This section demonstrates how to run `headscale` as a service in the background with [SystemD ](https://www.freedesktop.org/wiki/Software/systemd/ ).
2022-01-02 11:11:36 -07:00
This should work on most modern Linux distributions.
1. Create a SystemD service configuration at `/etc/systemd/system/headscale.service` containing:
2024-03-22 12:55:20 -06:00
```systemd
[Unit]
Description=headscale controller
After=syslog.target
After=network.target
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
[Service]
Type=simple
User=headscale
Group=headscale
ExecStart=/usr/local/bin/headscale serve
Restart=always
RestartSec=5
2022-02-01 17:32:13 -07:00
2024-03-22 12:55:20 -06:00
# 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
2022-02-01 17:32:13 -07:00
2024-03-22 12:55:20 -06:00
[Install]
WantedBy=multi-user.target
```
2022-02-01 12:23:18 -07:00
2024-03-22 12:55:20 -06:00
Note that when running as the headscale user ensure that, either you add your current user to the headscale group:
2022-02-01 12:23:18 -07:00
2024-03-22 12:55:20 -06:00
```shell
usermod -a -G headscale current_user
```
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
or run all headscale commands as the headscale user:
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
```shell
su - headscale
```
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
1. In `/etc/headscale/config.yaml` , override the default `headscale` unix socket with path that is writable by the `headscale` user or group:
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
```yaml
unix_socket: /var/run/headscale/headscale.sock
```
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
1. Reload SystemD to load the new configuration file:
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
```shell
systemctl daemon-reload
```
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
1. Enable and start the new `headscale` service:
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
```shell
systemctl enable --now headscale
```
2022-01-02 11:11:36 -07:00
2024-03-22 12:55:20 -06:00
1. Verify the headscale service:
```shell
systemctl status headscale
```
Verify `headscale` is available:
```shell
curl http://127.0.0.1:9090/metrics
```
2022-01-02 11:11:36 -07:00
`headscale` will now run in the background and start at boot.