mirror of
https://github.com/juanfont/headscale.git
synced 2024-11-27 12:05:26 +00:00
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
133 lines
3.4 KiB
Markdown
133 lines
3.4 KiB
Markdown
# 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>
|
|
```
|