mirror of
https://github.com/juanfont/headscale.git
synced 2025-10-10 11:14:24 +02:00
40e226c9ee
* Use the existing "Using headscale" sections and combine them into a single getting started guide with a little bit more explanation. * Explain how to get help from the command line client. * Remove duplicated sections from existing installation guides
130 lines
3.9 KiB
Markdown
130 lines
3.9 KiB
Markdown
# 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](#running-headscale-in-the-background-with-systemd)
|
|
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](https://github.com/juanfont/headscale/releases):
|
|
|
|
```shell
|
|
wget --output-document=/usr/local/bin/headscale \
|
|
https://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>
|
|
```
|
|
|
|
1. Make `headscale` executable:
|
|
|
|
```shell
|
|
chmod +x /usr/local/bin/headscale
|
|
```
|
|
|
|
1. Prepare a directory to hold `headscale` configuration and the [SQLite](https://www.sqlite.org/) database:
|
|
|
|
```shell
|
|
# 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
|
|
```
|
|
|
|
1. Create a `headscale` configuration:
|
|
|
|
```shell
|
|
touch /etc/headscale/config.yaml
|
|
```
|
|
|
|
**(Strongly Recommended)** Download a copy of the [example configuration](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository.
|
|
|
|
1. Start the headscale server:
|
|
|
|
```shell
|
|
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](https://github.com/tmux/tmux) or [screen](https://www.gnu.org/software/screen/).
|
|
|
|
To run `headscale` in the background, please follow the steps in the [systemd section](#running-headscale-in-the-background-with-systemd) before continuing.
|
|
|
|
1. Verify `headscale` is running:
|
|
Verify `headscale` is available:
|
|
|
|
```shell
|
|
curl http://127.0.0.1:9090/metrics
|
|
```
|
|
|
|
## Running `headscale` in the background with systemd
|
|
|
|
This section demonstrates how to run `headscale` as a service in the background with [systemd](https://systemd.io/).
|
|
This should work on most modern Linux distributions.
|
|
|
|
1. Copy [headscale's systemd service file](./packaging/headscale.systemd.service) to
|
|
`/etc/systemd/system/headscale.service` and adjust it to suit your local setup. The following parameters likely need
|
|
to be modified: `ExecStart`, `WorkingDirectory`, `ReadWritePaths`.
|
|
|
|
Note that when running as the headscale user ensure that, either you add your current user to the headscale group:
|
|
|
|
```shell
|
|
usermod -a -G headscale current_user
|
|
```
|
|
|
|
or run all headscale commands as the headscale user:
|
|
|
|
```shell
|
|
su - headscale
|
|
```
|
|
|
|
1. In `/etc/headscale/config.yaml`, override the default `headscale` unix socket with path that is writable by the `headscale` user or group:
|
|
|
|
```yaml
|
|
unix_socket: /var/run/headscale/headscale.sock
|
|
```
|
|
|
|
1. Reload systemd to load the new configuration file:
|
|
|
|
```shell
|
|
systemctl daemon-reload
|
|
```
|
|
|
|
1. Enable and start the new `headscale` service:
|
|
|
|
```shell
|
|
systemctl enable --now headscale
|
|
```
|
|
|
|
1. Verify the headscale service:
|
|
|
|
```shell
|
|
systemctl status headscale
|
|
```
|
|
|
|
Verify `headscale` is available:
|
|
|
|
```shell
|
|
curl http://127.0.0.1:9090/metrics
|
|
```
|
|
|
|
`headscale` will now run in the background and start at boot.
|