diff --git a/config-example.yaml b/config-example.yaml index 29b2f3f..aceb8ad 100644 --- a/config-example.yaml +++ b/config-example.yaml @@ -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: "" diff --git a/docs/README.md b/docs/README.md index 111b3bc..66bde26 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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) diff --git a/docs/Running.md b/docs/Running.md deleted file mode 100644 index 9613e16..0000000 --- a/docs/Running.md +++ /dev/null @@ -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 - ``` - - - -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 \ - 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 \ - 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 \ - 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. diff --git a/docs/running-headscale-container.md b/docs/running-headscale-container.md new file mode 100644 index 0000000..996070a --- /dev/null +++ b/docs/running-headscale-container.md @@ -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: \ + 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 +``` + +### 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 --authkey +``` + +## 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. diff --git a/docs/running-headscale-linux.md b/docs/running-headscale-linux.md new file mode 100644 index 0000000..0f0d570 --- /dev/null +++ b/docs/running-headscale-linux.md @@ -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__linux_ +``` + +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 +``` + +### 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 --authkey +``` + +## 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.