Mirrors/juanfont.headscale
1
0
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2025-10-10 11:14:24 +02:00
Code Issues Projects Releases Wiki Activity

Add a getting started page and explain the first steps with headscale

Browse Source 
* 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
This commit is contained in:
Florian Preinstorfer 2024-09-26 18:45:56 +02:00
parent 35f8395df7
commit 40e226c9ee
5 changed files with 132 additions and 140 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
docs/running-headscale-linux-manual.md
View File

@ -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 <YOUR_MACHINE_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 <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
```
## 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/).

37
docs/running-headscale-linux.md
View File

@ -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 <YOUR_HEADSCALE_URL>
```
Register the machine:
```shell
headscale nodes register --user myfirstuser --key <YOUR_MACHINE_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 <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
```

34
docs/running-headscale-openbsd.md
View File

@ -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 <YOUR_MACHINE_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 <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
```
## 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).

35
docs/running-headscale-sealos.md
View File

@ -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 <YOUR_HEADSCALE_URL> 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 <YOUR_MACHINE_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 <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
```
## 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.

132
docs/usage/getting-started.md Normal file
View File

@ -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 <COMMAND> --help
```
=== "Container"
```shell
# Show help
docker exec -it headscale \
headscale help
# Show help for a specific command
docker exec -it headscale \
headscale <COMMAND> --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 <USER>
```
=== "Container"
```shell
docker exec -it headscale \
headscale users create <USER>
```
### 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 <YOUR_HEADSCALE_URL>
```
Usually, a browser window with further instructions is opened and contains the value for `<YOUR_MACHINE_KEY>`. Approve
and register the node on your headscale server:
=== "Native"
```shell
headscale nodes register --user <USER> --key <YOUR_MACHINE_KEY>
```
=== "Container"
```shell
docker exec -it headscale \
headscale nodes register --user <USER> --key <YOUR_MACHINE_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 <USER>
```
=== "Container"
```shell
docker exec -it headscale \
headscale preauthkeys create --user <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 <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
```