8c7d8ee34f
* Setup mkdocs-redirects * Restructure existing documentation * Move client OS support into the documentation * Move existing Client OS support table into its own documentation page * Link from README.md to the rendered documentation * Document minimum Tailscale client version * Reuse CONTRIBUTING.md" in the documentation * Include "CONTRIBUTING.md" from the repository root * Update FAQ and index page and link to the contributing docs * Add configuration reference * 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 * Document requirements and assumptions * Document packages provided by the community * Move deb install guide to official releases * Move manual install guide to official releases * Move container documentation to setup section * Move sealos documentation to cloud install page * Move OpenBSD docs to build from source * Simplify DNS documentation * Add sponsor page * Add releases page * Add features page * Add help page * Add upgrading page * Adjust mkdocs nav * Update wording Use the term headscale for the project, Headscale on the beginning of a sentence and `headscale` when refering to the CLI. * Welcome to headscale * Link to existing documentation in the FAQ * Remove the goal header and use the text as opener * Indent code block in OIDC * Make a few pages linter compatible Also update ignored files for prettier * Recommend HTTPS on port 443 Fixes: #2164 * Use hosts in acl documentation thx @efficacy38 for noticing this Ref: #1863 * Use mkdocs-macros to set headscale version once
3.4 KiB
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. 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, Apple or Windows devices.
Normal, interactive login
On a client machine, run the tailscale up command and provide the FQDN of your headscale instance as argument:
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:
tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>