myriation/headscale
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity

Rewrite main documentation

Browse source 
This commit starts restructuring the documentation and updating it to be
compliant with 0.12.x+ releases.

The main change is that the documentation has been rewritten for the
ground up, and hopefully simplified.

The documentation has been split into an official documentation for
running headscale as a binary under Linux with SystemD and a "community"
provided documentation for Docker.

This should make the two documents a lot easier to read and follow than
the mishmash document we had.
This commit is contained in:
Kristoffer Dalby 2022-01-02 19:11:36 +01:00
parent 0bd4250a53
commit f9e6722635
5 changed files with 332 additions and 201 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
config-example.yaml
View file

@ -8,7 +8,7 @@ listen_addr: 0.0.0.0:8080
# Private key file which will be # Private key file which will be
# autogenerated if it's missing # autogenerated if it's missing
private_key_path: private.key private_key_path: /var/lib/headscale/private.key
derp: derp:
# List of externally available DERP maps encoded in JSON # List of externally available DERP maps encoded in JSON
@ -16,8 +16,8 @@ derp:
- https://controlplane.tailscale.com/derpmap/default - https://controlplane.tailscale.com/derpmap/default
# Locally available DERP map files encoded in YAML # Locally available DERP map files encoded in YAML
paths: # paths:
- derp-example.yaml # - /etc/headscale/derp-example.yaml
# If enabled, a worker will be set up to periodically # If enabled, a worker will be set up to periodically
# refresh the given sources and update the derpmap # refresh the given sources and update the derpmap
@ -33,7 +33,7 @@ ephemeral_node_inactivity_timeout: 30m
# SQLite config # SQLite config
db_type: sqlite3 db_type: sqlite3
db_path: db.sqlite db_path: /var/lib/headscale/db.sqlite
# # Postgres config # # Postgres config
# db_type: postgres # db_type: postgres
@ -48,7 +48,7 @@ acme_email: ""
tls_letsencrypt_hostname: "" tls_letsencrypt_hostname: ""
tls_letsencrypt_listen: ":http" tls_letsencrypt_listen: ":http"
tls_letsencrypt_cache_dir: ".cache" tls_letsencrypt_cache_dir: /var/lib/headscale/cache
tls_letsencrypt_challenge_type: HTTP-01 tls_letsencrypt_challenge_type: HTTP-01
tls_cert_path: "" tls_cert_path: ""

27
docs/README.md
View file

@ -1,7 +1,28 @@
# Official headscale documentation # headscale documentation
- [Configuration](Configuration.md) This page contains the official and community contributed documentation for `headscale`.
- [Running](Running.md)
If you are having trouble with following the documentation or get unexpected results,
please ask on [Discord](https://discord.gg/XcQxk2VHjx) instead of opening an Issue.
## Official documentation
### How-to
- [Running headscale on Linux](running-headscale-linux.md)
- [DNS](DNS.md) - [DNS](DNS.md)
- [TLS](TLS.md) - [TLS](TLS.md)
### References
- [Configuration](Configuration.md)
- [Glossary](Glossary.md) - [Glossary](Glossary.md)
## Community documentation
Community documentation is not actively maintained by the headscale authors and is
written by community members. It is _not_ verified by `headscale` developers.
**It might be outdated and it might miss necessary steps**.
- [Running headscale in container](running-headscale-container.md)

193
docs/Running.md
View file

@ -1,193 +0,0 @@
# Running headscale
**Note:** The docs are currently out of date with the new 0.12.x releases, we are working on this. The _main_ change is that `headscale` must be running before using the CLI.
## Server configuration
1. Download the headscale binary https://github.com/juanfont/headscale/releases, and place it somewhere in your $PATH or use the docker container
```shell
docker pull headscale/headscale:x.x.x
```
<!--
or
```shell
docker pull ghrc.io/juanfont/headscale:x.x.x
``` -->
2. When running headscale in a docker container, prepare a directory to hold all configuration
```shell
mkdir config
```
3. Get yourself a DB
a) Get a Postgres DB running in Docker:
```shell
docker run --name headscale \
-e POSTGRES_DB=headscale \
-e POSTGRES_USER=foo \
-e POSTGRES_PASSWORD=bar \
-p 5432:5432 \
-d postgres
```
or b) Prepare a SQLite DB file:
```shell
touch config/db.sqlite
```
4. Create a headscale configuration, and a DERP map file. Refer to [tailscale sample](https://raw.githubusercontent.com/tailscale/tailscale/main/net/dnsfallback/dns-fallback-servers.json) for more guidance.
```shell
cp config.yaml.[sqlite|postgres].example config/config.yaml
cp derp-example.yaml config/derp.yaml
```
5. Create a namespace
```shell
headscale namespaces create myfirstnamespace
```
or Docker:
```shell
docker run \
-v $(pwd)/config:/etc/headscale/ \
-p 127.0.0.1:8080:8080 \
headscale/headscale:x.x.x \
headscale namespaces create myfirstnamespace
```
or if your server is already running in Docker:
```shell
docker exec <container_name> \
headscale namespaces create myfirstnamespace
```
6. Run the server
```shell
headscale serve
```
or Docker:
```shell
docker run \
-v $(pwd)/config:/etc/headscale/ \
-p 127.0.0.1:8080:8080 \
headscale/headscale:x.x.x \
headscale serve
```
## Nodes configuration
If you used tailscale.com before in your nodes, make sure you clear the tailscaled data folder
```shell
systemctl stop tailscaled
rm -fr /var/lib/tailscale
systemctl start tailscaled
```
### Adding node based on MACHINEKEY
1. Add your first machine
```shell
tailscale up --login-server YOUR_HEADSCALE_URL
```
2. Navigate to the URL returned by `tailscale up`, where you'll find your machine key.
3. In the server, register your machine to a namespace with the CLI
```shell
headscale -n myfirstnamespace nodes register -k YOURMACHINEKEY
```
or Docker:
```shell
docker run \
-v $(pwd)/config:/etc/headscale/ \
headscale/headscale:x.x.x \
headscale -n myfirstnamespace nodes register -k YOURMACHINEKEY
```
or if your server is already running in Docker:
```shell
docker exec <container_name> \
headscale -n myfirstnamespace nodes register -k YOURMACHINEKEY
```
### Alternative: adding node with AUTHKEY
1. Create an authkey
```shell
headscale -n myfirstnamespace preauthkeys create --reusable --expiration 24h
```
or Docker:
```shell
docker run \
-v $(pwd)/config:/etc/headscale/ \
headscale/headscale:x.x.x \
headscale -n myfirstnamespace preauthkeys create --reusable --expiration 24h
```
or if your server is already running in Docker:
```shell
docker exec <container_name> \
headscale -n myfirstnamespace preauthkeys create --reusable --expiration 24h
```
2. Use the authkey on your node to register it:
```shell
tailscale up --login-server YOUR_HEADSCALE_URL --authkey YOURAUTHKEY
```
If you create an authkey with the `--ephemeral` flag, that key will create ephemeral nodes. This implies that `--reusable` is true.
Please bear in mind that all headscale commands support adding `-o json` or `-o json-line` to get nicely JSON-formatted output.
## Debugging headscale running in Docker
The `headscale/headscale` Docker container is based on a "distroless" image that does not contain a shell or any other debug tools. If you need to debug your application running in the Docker container, you can use the `-debug` variant, for example `headscale/headscale:x.x.x-debug`.
### Running the debug Docker container
To run the debug Docker container, use the exact same commands as above, but replace `headscale/headscale:x.x.x` with `headscale/headscale:x.x.x-debug` (`x.x.x` is the version of headscale). The two containers are compatible with each other, so you can alternate between them.
### Executing commands in the debug container
The default command in the debug container is to run `headscale`, which is located at `/bin/headscale` inside the container.
Additionally, the debug container includes a minimalist Busybox shell.
To launch a shell in the container, use:
```
docker run -it headscale/headscale:x.x.x-debug sh
```
You can also execute commands directly, such as `ls /bin` in this example:
```
docker run headscale/headscale:x.x.x-debug ls /bin
```
Using `docker exec` allows you to run commands in an existing container.

133
docs/running-headscale-container.md Normal file
View file

@ -0,0 +1,133 @@
# Running headscale in a container
**Note:** the container documentation is maintained by the \*_community_ and there is no guarentee
it is up to date, or working.
## Goal
This documentation has the goal of showing a user how-to set up and run `headscale` in a container.
[Docker]() is used as the reference container implementation, but there is no reason that it should
not work with alternatives like [Podman]().
## Configure and run `headscale`
1. Prepare a direction to hold `headscale` configuration and the [SQlite]() database:
```shell
mkdir config
```
1. Create an empty SQlite datebase:
```shell
touch config/db.sqlite
```
1. Create a `headscale` configuration:
```shell
touch config/config.yaml
```
It is strongly recommended to copy the [example configuration](../config.yaml) from the [headscale repository](../)
1. Start the headscale server:
```shell
docker run \
--name headscale \
--detach \
--rm \
--volume $(pwd)/config:/etc/headscale/ \
--publish 127.0.0.1:8080:8080 \
headscale/headscale:<VERSION> \
headscale serve
```
This command will mount `config/` under `/etc/headscale`, forward port 8080 out of the container so the
`headscale` instance becomes available and then detach so headscale runs in the background.
1. Verify `headscale` is running:
Follow the container logs:
```shell
docker logs --follow headscale
```
Verify running containers:
```shell
docker ps
```
Verify `headscale` is available:
```shell
curl http://127.0.0.1:8080/metrics
```
1. Create a namespace ([tailnet]()):
```shell
docker exec headscale -- headscale namespaces create myfirstnamespace
```
### Register a machine (normal login)
On a client machine, execute the `tailscale` login command:
```shell
tailscale up --login-server YOUR_HEADSCALE_URL
```
To register a machine when running `headscale` in a container, take the headscale command and pass it to the container:
```shell
docker exec headscale -- \
headscale --namespace myfirstnamespace nodes register --key <YOU_+MACHINE_KEY>
```
### Register machine using a pre authenticated key
Generate a key using the command line:
```shell
docker exec headscale -- \
headscale --namespace myfirstnamespace 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:
```shell
tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
```
## Debugging headscale running in Docker
The `headscale/headscale` Docker container is based on a "distroless" image that does not contain a shell or any other debug tools. If you need to debug your application running in the Docker container, you can use the `-debug` variant, for example `headscale/headscale:x.x.x-debug`.
### Running the debug Docker container
To run the debug Docker container, use the exact same commands as above, but replace `headscale/headscale:x.x.x` with `headscale/headscale:x.x.x-debug` (`x.x.x` is the version of headscale). The two containers are compatible with each other, so you can alternate between them.
### Executing commands in the debug container
The default command in the debug container is to run `headscale`, which is located at `/bin/headscale` inside the container.
Additionally, the debug container includes a minimalist Busybox shell.
To launch a shell in the container, use:
```
docker run -it headscale/headscale:x.x.x-debug sh
```
You can also execute commands directly, such as `ls /bin` in this example:
```
docker run headscale/headscale:x.x.x-debug ls /bin
```
Using `docker exec` allows you to run commands in an existing container.

170
docs/running-headscale-linux.md Normal file
View file

@ -0,0 +1,170 @@
# Running headscale on Linux
## 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]():
```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 direction to hold `headscale` configuration and the [SQlite]() database:
```shell
# Directory for configuration
mkdir -p /etc/headscale
# Directory for Database, and other variable data (like certificates)
mkdir -p /var/lib/headscale
```
1. Create an empty SQlite datebase:
```shell
touch /var/lib/headscale/db.sqlite
```
1. Create a `headscale` configuration:
```shell
touch /etc/headscale/config.yaml
```
It is strongly recommended to copy and modifiy the [example configuration](../config.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]() or [screen]().
To run `headscale` in the background, please follow the steps in the [SystemD section]() before continuing.
1. Verify `headscale` is running:
Verify `headscale` is available:
```shell
curl http://127.0.0.1:8080/metrics
```
1. Create a namespace ([tailnet]()):
```shell
headscale namespaces create myfirstnamespace
```
### 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
headscale --namespace myfirstnamespace nodes register --key <YOU_+MACHINE_KEY>
```
### Register machine using a pre authenticated key
Generate a key using the command line:
```shell
headscale --namespace myfirstnamespace 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:
```shell
tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
```
## Running `headscale` in the background with SystemD
In this section it will be demonstrated 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:
```systemd
[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
ReadWritePaths=/var/lib/headscale /var/run/headscale
AmbientCapabilities=CAP_NET_BIND_SERVICE
RuntimeDirectory=headscale
[Install]
WantedBy=multi-user.target
```
1. In `/etc/headscale/config.yaml`, override the default `headscale` unix socket with a SystemD friendly path:
```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 headscale
systemctl start headscale
```
1. Verify the headscale service:
```shell
systemctl status headscale
```
Verify `headscale` is available:
```shell
curl http://127.0.0.1:8080/metrics
```
`headscale` will now run in the background and start at boot.