Rewrite main documentation
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
parent
0bd4250a53
commit
f9e6722635
5 changed files with 332 additions and 201 deletions
|
|
@ -8,7 +8,7 @@ listen_addr: 0.0.0.0:8080
|
|||
|
||||
# Private key file which will be
|
||||
# autogenerated if it's missing
|
||||
private_key_path: private.key
|
||||
private_key_path: /var/lib/headscale/private.key
|
||||
|
||||
derp:
|
||||
# List of externally available DERP maps encoded in JSON
|
||||
|
|
@ -16,8 +16,8 @@ derp:
|
|||
- https://controlplane.tailscale.com/derpmap/default
|
||||
|
||||
# Locally available DERP map files encoded in YAML
|
||||
paths:
|
||||
- derp-example.yaml
|
||||
# paths:
|
||||
# - /etc/headscale/derp-example.yaml
|
||||
|
||||
# If enabled, a worker will be set up to periodically
|
||||
# refresh the given sources and update the derpmap
|
||||
|
|
@ -33,7 +33,7 @@ ephemeral_node_inactivity_timeout: 30m
|
|||
|
||||
# SQLite config
|
||||
db_type: sqlite3
|
||||
db_path: db.sqlite
|
||||
db_path: /var/lib/headscale/db.sqlite
|
||||
|
||||
# # Postgres config
|
||||
# db_type: postgres
|
||||
|
|
@ -48,7 +48,7 @@ acme_email: ""
|
|||
|
||||
tls_letsencrypt_hostname: ""
|
||||
tls_letsencrypt_listen: ":http"
|
||||
tls_letsencrypt_cache_dir: ".cache"
|
||||
tls_letsencrypt_cache_dir: /var/lib/headscale/cache
|
||||
tls_letsencrypt_challenge_type: HTTP-01
|
||||
|
||||
tls_cert_path: ""
|
||||
|
|
|
|||
|
|
@ -1,7 +1,28 @@
|
|||
# Official headscale documentation
|
||||
# headscale documentation
|
||||
|
||||
- [Configuration](Configuration.md)
|
||||
- [Running](Running.md)
|
||||
This page contains the official and community contributed documentation for `headscale`.
|
||||
|
||||
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)
|
||||
- [TLS](TLS.md)
|
||||
|
||||
### References
|
||||
|
||||
- [Configuration](Configuration.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
193
docs/Running.md
|
|
@ -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
133
docs/running-headscale-container.md
Normal 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
170
docs/running-headscale-linux.md
Normal 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.
|
||||
Loading…
Reference in a new issue