From 40e226c9eecef8bb66f0c7b5b712fa0d75897f74 Mon Sep 17 00:00:00 2001 From: Florian Preinstorfer Date: Thu, 26 Sep 2024 18:45:56 +0200 Subject: [PATCH] Add a getting started page and explain the first steps with headscale * 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 --- docs/running-headscale-linux-manual.md | 34 ------- docs/running-headscale-linux.md | 37 ------- docs/running-headscale-openbsd.md | 34 ------- docs/running-headscale-sealos.md | 35 ------- docs/usage/getting-started.md | 132 +++++++++++++++++++++++++ 5 files changed, 132 insertions(+), 140 deletions(-) create mode 100644 docs/usage/getting-started.md diff --git a/docs/running-headscale-linux-manual.md b/docs/running-headscale-linux-manual.md index 3a0d91e0..9ec39b36 100644 --- a/docs/running-headscale-linux-manual.md +++ b/docs/running-headscale-linux-manual.md @@ -75,40 +75,6 @@ describing how to make `headscale` run properly in a server environment. curl http://127.0.0.1:9090/metrics ``` -1. Create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)): - - ```shell - headscale users create myfirstuser - ``` - -### 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 nodes register --user myfirstuser --key -``` - -### Register machine using a pre authenticated key - -Generate a key using the command line: - -```shell -headscale preauthkeys create --user myfirstuser --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 This section demonstrates how to run `headscale` as a service in the background with [systemd](https://systemd.io/). diff --git a/docs/running-headscale-linux.md b/docs/running-headscale-linux.md index ffa510a6..69687ef4 100644 --- a/docs/running-headscale-linux.md +++ b/docs/running-headscale-linux.md @@ -58,40 +58,3 @@ configuration (`/etc/headscale/config.yaml`). ```shell systemctl status headscale ``` - -## Using Headscale - -### Create a user - -```shell -headscale users create myfirstuser -``` - -### Register a machine (normal login) - -On a client machine, run the `tailscale` login command: - -```shell -tailscale up --login-server -``` - -Register the machine: - -```shell -headscale nodes register --user myfirstuser --key -``` - -### Register machine using a pre authenticated key - -Generate a key using the command line: - -```shell -headscale preauthkeys create --user myfirstuser --reusable --expiration 24h -``` - -This will return a pre-authenticated key that is used to -connect a node to `headscale` during the `tailscale` command: - -```shell -tailscale up --login-server --authkey -``` diff --git a/docs/running-headscale-openbsd.md b/docs/running-headscale-openbsd.md index 449034ba..dd55e544 100644 --- a/docs/running-headscale-openbsd.md +++ b/docs/running-headscale-openbsd.md @@ -112,40 +112,6 @@ describing how to make `headscale` run properly in a server environment. curl http://127.0.0.1:9090/metrics ``` -1. Create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)): - - ```shell - headscale users create myfirstuser - ``` - -### 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 nodes register --user myfirstuser --key -``` - -### Register machine using a pre authenticated key - -Generate a key using the command line: - -```shell -headscale preauthkeys create --user myfirstuser --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 rc.d This section demonstrates how to run `headscale` as a service in the background with [rc.d](https://man.openbsd.org/rc.d). diff --git a/docs/running-headscale-sealos.md b/docs/running-headscale-sealos.md index 52f5c7ec..c735276f 100644 --- a/docs/running-headscale-sealos.md +++ b/docs/running-headscale-sealos.md @@ -23,41 +23,6 @@ This documentation has the goal of showing a user how-to run `headscale` on Seal ![](./images/headscale-sealos-url.png) -5. Click on 'Terminal' button on the right side of the details to access the Terminal of the headscale application. then create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)): - - ```bash - headscale users create myfirstuser - ``` - -### Register a machine (normal login) - -On a client machine, execute the `tailscale` login command: - -```bash -# replace with the public domain provided by Sealos -tailscale up --login-server YOUR_HEADSCALE_URL -``` - -To register a machine when running headscale in [Sealos](https://sealos.io), click on 'Terminal' button on the right side of the headscale application's detail page to access the Terminal of the headscale application, then take the headscale command: - -```bash -headscale nodes register --user myfirstuser --key -``` - -### Register machine using a pre authenticated key - -click on 'Terminal' button on the right side of the headscale application's detail page to access the Terminal of the headscale application, then generate a key using the command line: - -```bash -headscale preauthkeys create --user myfirstuser --reusable --expiration 24h -``` - -This will return a pre-authenticated key that can be used to connect a node to `headscale` during the `tailscale` command: - -```bash -tailscale up --login-server --authkey -``` - ## Controlling headscale with remote CLI This documentation has the goal of showing a user how-to set control a headscale instance from a remote machine with the headscale command line binary. diff --git a/docs/usage/getting-started.md b/docs/usage/getting-started.md new file mode 100644 index 00000000..d344156b --- /dev/null +++ b/docs/usage/getting-started.md @@ -0,0 +1,132 @@ +# Getting started + +This page helps you get started with headscale and provides a few usage examples for the headscale command line tool +`headscale`. + +!!! note "Prerequisites" + + * Headscale is installed and running as system service. Read the [setup section](../setup/requirements.md) for + installation instructions. + * The configuration file exists and is adjusted to suit your environment, see + [Configuration](../ref/configuration.md) for details. + * The Tailscale client is installed, see [Client and operating system support](../about/clients.md) for more + information. + +## Getting help + +The `headscale` command line tool provides built-in help. To show available commands along with their arguments and +options, run: + +=== "Native" + + ```shell + # Show help + headscale help + + # Show help for a specific command + headscale --help + ``` + +=== "Container" + + ```shell + # Show help + docker exec -it headscale \ + headscale help + + # Show help for a specific command + docker exec -it headscale \ + headscale --help + ``` + +## Manage users + +In headscale, a node (also known as machine or device) is always assigned to a specific user, a +[tailnet](https://tailscale.com/kb/1136/tailnet/). Such users can be managed with the `headscale users` command. Invoke +the built-in help for more information: `headscale users --help`. + +### Create a user + +=== "Native" + + ```shell + headscale users create + ``` + +=== "Container" + + ```shell + docker exec -it headscale \ + headscale users create + ``` + +### List existing users + +=== "Native" + + ```shell + headscale users list + ``` + +=== "Container" + + ```shell + docker exec -it headscale \ + headscale users list + ``` + +## Register a node + +One has to register a node first to use headscale as coordination with Tailscale. The following examples work for the +Tailscale client on Linux/BSD operating systems. Alternatively, follow the instructions to connect +[Android](connect/android.md), [Apple](connect/apple.md) or [Windows](connect/windows.md) devices. + +### Normal, interactive login + +On a client machine, run the `tailscale up` command and provide the FQDN of your headscale instance as argument: + +```shell +tailscale up --login-server +``` + +Usually, a browser window with further instructions is opened and contains the value for ``. Approve +and register the node on your headscale server: + +=== "Native" + + ```shell + headscale nodes register --user --key + ``` + +=== "Container" + + ```shell + docker exec -it headscale \ + headscale nodes register --user --key + ``` + +### Using a preauthkey + +It is also possible to generate a preauthkey and register a node non-interactively. First, generate a preauthkey on the +headscale instance. By default, the key is valid for one hour and can only be used once (see `headscale preauthkeys +--help` for other options): + +=== "Native" + + ```shell + headscale preauthkeys create --user + ``` + +=== "Container" + + ```shell + docker exec -it headscale \ + headscale preauthkeys create --user + ``` + +The command returns the preauthkey on success which is used to connect a node to the headscale instance via the +`tailscale up` command: + +```shell +tailscale up --login-server --authkey +```