Headscale

https://headscale.net
Admin
Headscale is an open source, self-hosted implementation of the Tailscale control server for managing...
Tokens:50,943
Snippets:520
Trust Score:8.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Download example configuration with wget

Source: https://headscale.net/stable/ref/configuration?q=

Downloads the example configuration file for the development version or version 0.29.3 using wget. Use the version matching your installed Headscale release.

```bash
# Development version
wget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml

# Version 0.29.3
wget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/v0.29.3/config-example.yaml

```

--------------------------------

### Download example configuration with curl

Source: https://headscale.net/stable/ref/configuration?q=

Downloads the example configuration file for the development version or version 0.29.3 using curl. Use the version matching your installed Headscale release.

```bash
# Development version
curl -o config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml

# Version 0.29.3
curl -o config.yaml https://raw.githubusercontent.com/juanfont/headscale/v0.29.3/config-example.yaml

```

--------------------------------

### Install headscale from source on OpenBSD

Source: https://headscale.net/stable/setup/install/source?q=

Installs prerequisites with pkg_add, clones the headscale repository, optionally checks out a release tag, builds the binary with version and commit hash ldflags, and installs it to /usr/local/sbin. Requires Go and git. The latest tag may be a beta release.

```shell
# Install prerequisites
pkg_add go git

git clone https://github.com/juanfont/headscale.git

cd headscale

# optionally checkout a release
# option a. you can find official release at https://github.com/juanfont/headscale/releases/latest
# option b. get latest tag, this may be a beta release
latestTag=$(git describe --tags `git rev-list --tags --max-count=1`)

git checkout $latestTag

go build -ldflags="-s -w -X github.com/juanfont/headscale/hscontrol/types.Version=$latestTag" -X github.com/juanfont/headscale/hscontrol/types.GitCommitHash=HASH" github.com/juanfont/headscale

# make it executable
chmod a+x headscale

# copy it to /usr/local/sbin
cp headscale /usr/local/sbin

```

--------------------------------

### Backup standard installation files

Source: https://headscale.net/stable/setup/upgrade?q=

Backs up the configuration and data directories for a standard installation using a timestamped suffix.

```bash
TIMESTAMP=$(date +%Y%m%d%H%M%S)
cp -aR /etc/headscale /etc/headscale.backup-$TIMESTAMP
cp -aR /var/lib/headscale /var/lib/headscale.backup-$TIMESTAMP
```

--------------------------------

### Backup standard installation

Source: https://headscale.net/stable/setup/upgrade

Creates a timestamped backup of the configuration file and data directory for a standard Headscale installation. The backup includes the SQLite database file.

```bash
TIMESTAMP=$(date +%Y%m%d%H%M%S)
cp -aR /etc/headscale /etc/headscale.backup-$TIMESTAMP
cp -aR /var/lib/headscale /var/lib/headscale.backup-$TIMESTAMP

```

--------------------------------

### Install headscale DEB package

Source: https://headscale.net/stable/setup/install/official

Installs the downloaded headscale .deb package using apt.

```bash
sudo apt install ./headscale.deb
```

--------------------------------

### Enable and start headscale service

Source: https://headscale.net/stable/setup/install/official

Enables and starts the headscale service.

```bash
systemctl enable --now headscale
```

--------------------------------

### Install headscale on OpenBSD with pkg_add

Source: https://headscale.net/stable/setup/install/community?q=

Install headscale using the OpenBSD package manager. The port installs headscale as a system service with rc.d and provides usage instructions upon installation.

```bash
pkg_add headscale

```

--------------------------------

### Install headscale on Gentoo with emerge

Source: https://headscale.net/stable/setup/install/community?q=

Install headscale using the Gentoo package manager. The package is available as net-vpn/headscale. Gentoo-specific documentation is available at the provided link.

```bash
emerge --ask net-vpn/headscale

```

--------------------------------

### Policy example for tagOwners

Source: https://headscale.net/stable/ref/registration?q=

Example policy configuration allowing user 'alice' to register nodes tagged with 'tag:server'. The 'tagOwners' section must be present in the policy file.

```json
{
  "tagOwners": {
    "tag:server": ["alice@"]
  },
  // more rules
}

```

--------------------------------

### Backup container installation

Source: https://headscale.net/stable/setup/upgrade

Creates a timestamped backup of the entire headscale volume directory for a container-based installation, which contains the configuration file, data directory, and SQLite database.

```bash
cp -aR /path/to/headscale /path/to/headscale.backup-$(date +%Y%m%d%H%M%S)

```

--------------------------------

### Backup container installation volume

Source: https://headscale.net/stable/setup/upgrade?q=

Backs up the entire source volume directory for a containerized Headscale installation.

```bash
cp -aR /path/to/headscale /path/to/headscale.backup-$(date +%Y%m%d%H%M%S)
```

--------------------------------

### Install headscale on Arch Linux with pacman

Source: https://headscale.net/stable/setup/install/community?q=

Install headscale using the Arch Linux package manager. The package is provided by Arch Linux and may be outdated; use official releases for the current stable version.

```bash
pacman -S headscale

```

--------------------------------

### Run headscale with Docker

Source: https://headscale.net/stable/setup/install/container

Starts the headscale container with Docker, mounting configuration and data directories, publishing ports 8080 and 9090, and running the serve command. Use 0.0.0.0:8080:8080 to expose externally.

```bash
docker run \
  --name headscale \
  --detach \
  --read-only \
  --tmpfs /var/run/headscale \
  --volume "$(pwd)/config:/etc/headscale:ro" \
  --volume "$(pwd)/lib:/var/lib/headscale" \
  --publish 127.0.0.1:8080:8080 \
  --publish 127.0.0.1:9090:9090 \
  --health-cmd "CMD headscale health" \
  docker.io/headscale/headscale:<VERSION> \
  serve

```

--------------------------------

### Edit headscale configuration file

Source: https://headscale.net/stable/setup/install/official

Opens the headscale configuration file for editing. An example configuration is available at /usr/share/doc/headscale/examples/config-example.yaml.

```bash
sudo nano /etc/headscale/config.yaml
```

--------------------------------

### Set up debug key for debug interface

Source: https://headscale.net/stable/ref/debug?q=

Generate a debug key, set the TS_DEBUG_KEY_PATH environment variable, and start Headscale. The debug key must be sent as the debugkey parameter with each request.

```bash
openssl rand -hex 32 | tee debugkey.txt
export TS_DEBUG_KEY_PATH=debugkey.txt
headscale serve

```

--------------------------------

### autogroup:internet policy example

Source: https://headscale.net/stable/ref/policy

Allows access to the internet through exit nodes. Can only be used in policy destinations.

```json
{
  "grants": [
    {
      "src": ["alice@"],
      "dst": ["autogroup:internet"],
      "ip": ["*"]
    }
  ]
}
```

--------------------------------

### REST API: Get details for all users

Source: https://headscale.net/stable/ref/api

Retrieves details for all users via the REST API. Requires an API key in the Authorization header.

```bash
curl -H "Authorization: Bearer <API_KEY>" \
    https://headscale.example.com/api/v1/user

```

--------------------------------

### Show headscale help (Native)

Source: https://headscale.net/stable/usage/getting-started

Display available commands and arguments for the headscale CLI.

```bash
# Show help
headscale help

# Show help for a specific command
headscale <COMMAND> --help
```

--------------------------------

### Show headscale help (Docker)

Source: https://headscale.net/stable/usage/getting-started

Display available commands and arguments for the headscale CLI running inside a Docker container.

```bash
# Show help
docker exec -it headscale \
  headscale help

# Show help for a specific command
docker exec -it headscale \
  headscale <COMMAND> --help
```

--------------------------------

### Create headscale configuration and data directories

Source: https://headscale.net/stable/setup/install/container

Creates the directory structure for headscale configuration and SQLite database on the container host.

```bash
mkdir -p ./headscale/{config,lib}
cd ./headscale

```

--------------------------------

### Login personal device with tailscale up

Source: https://headscale.net/stable/ref/registration?q=

Initiates web authentication for a personal device. A browser window opens with further instructions and prints the Auth ID needed for approval.

```bash
tailscale up --login-server <YOUR_HEADSCALE_URL>

```

--------------------------------

### autogroup:member policy example

Source: https://headscale.net/stable/ref/policy

Includes all personal (untagged) devices.

```json
{
  "grants": [
    {
      "src": ["autogroup:member"],
      "dst": ["tag:prod-app-servers"],
      "ip": ["80,443"]
    }
  ]
}
```

--------------------------------

### autogroup:tagged policy example

Source: https://headscale.net/stable/ref/policy

Includes all devices that have at least one tag.

```json
{
  "grants": [
    {
      "src": ["autogroup:tagged"],
      "dst": ["tag:monitoring"],
      "ip": ["9090"]
    }
  ]
}
```

--------------------------------

### Login personal device via Tailscale

Source: https://headscale.net/stable/ref/registration

Initiate the registration process for a personal device by pointing it to your Headscale server.

```bash
tailscale up --login-server <YOUR_HEADSCALE_URL>
```

--------------------------------

### GET /api/v1/user

Source: https://headscale.net/stable/ref/api?q=

Retrieves details for all users via the Headscale REST API.

```APIDOC
## [GET] /api/v1/user

### Description
Get details for all users.

### Method
GET

### Endpoint
/api/v1/user

### Authentication
HTTP Bearer authentication with API key: `Authorization: Bearer <API_KEY>`

### Request Example
```
curl -H "Authorization: Bearer <API_KEY>" \
    https://headscale.example.com/api/v1/user
```

```

--------------------------------

### Launch shell in debug container

Source: https://headscale.net/stable/setup/install/container

Starts an interactive shell in the debug headscale container.

```bash
docker run -it docker.io/headscale/headscale:x.x.x-debug sh

```

--------------------------------

### Create a headscale user (Docker)

Source: https://headscale.net/stable/usage/getting-started

Create a new user in headscale running inside a Docker container.

```bash
docker exec -it headscale \
  headscale users create <USER>
```

--------------------------------

### Create headscale config directory and edit config

Source: https://headscale.net/stable/setup/install/official

Creates the /etc/headscale directory and opens the configuration file for editing.

```bash
sudo mkdir -p /etc/headscale
sudo nano /etc/headscale/config.yaml
```

--------------------------------

### GET /api/v1/user

Source: https://headscale.net/stable/ref/api

Retrieves details for all users. Requires HTTP Bearer authentication with a valid API key.

```APIDOC
## GET /api/v1/user

### Description
Retrieves details for all users.

### Method
GET

### Endpoint
/api/v1/user

### Parameters
#### Query Parameters
- **name** (string) - Optional - Filter by user name.

### Request Example
```
curl -H "Authorization: Bearer <API_KEY>" \
    https://headscale.example.com/api/v1/user
```

### Response
#### Success Response (200)
Returns details for all users.

#### Response Example
```
{
  "users": []
}
```
```

--------------------------------

### Verify running containers

Source: https://headscale.net/stable/setup/install/container

Lists running containers to verify headscale is running.

```bash
docker ps

```

--------------------------------

### Execute command in debug container

Source: https://headscale.net/stable/setup/install/container

Runs a command directly in the debug container, for example listing the /ko-app directory.

```bash
docker run docker.io/headscale/headscale:x.x.x-debug ls /ko-app

```

--------------------------------

### Restore default IP prefixes and update node addresses with SQL

Source: https://headscale.net/stable/about/faq?q=

Shows the recommended IP prefixes for Tailscale and SQL to update the database columns 'nodes.ipv4' and 'nodes.ipv6' based on node ID. Only for migration back to supported prefixes (100.64.0.0/10 and fd7a:115c:a1e0::/48) after a backup and testing in a demo environment.

```yaml
prefixes:
  v4: 100.64.0.0/10
  v6: fd7a:115c:a1e0::/48

```

```sql
UPDATE nodes
SET ipv4=concat('100.64.', id/256, '.', id%256),
    ipv6=concat('fd7a:115c:a1e0::', format('%x', id));

```

--------------------------------

### GET /api/v1/user?name={name}

Source: https://headscale.net/stable/ref/api?q=

Retrieves details for a specific user by name via the Headscale REST API.

```APIDOC
## [GET] /api/v1/user?name={name}

### Description
Get details for a specific user by name.

### Method
GET

### Endpoint
/api/v1/user?name={name}

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the user to retrieve.

### Authentication
HTTP Bearer authentication with API key: `Authorization: Bearer <API_KEY>`

### Request Example
```
curl -H "Authorization: Bearer <API_KEY>" \
    https://headscale.example.com/api/v1/user?name=bob
```

```

--------------------------------

### Configure NGINX reverse proxy

Source: https://headscale.net/stable/ref/dns?q=

Example NGINX configuration to route traffic for a specific domain to a local service port.

```nginx
server {
    listen 80;
    listen [::]:80;

    server_name grafana.myvpn.example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

}
```

--------------------------------

### Login tagged device with tailscale up

Source: https://headscale.net/stable/ref/registration?q=

Initiates web authentication for a tagged device. The user must be authorized to register the specified tag. A browser window opens with further instructions and prints the Auth ID.

```bash
tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags tag:<TAG>

```

--------------------------------

### REST API: Get details for user 'bob'

Source: https://headscale.net/stable/ref/api

Retrieves details for a specific user by name using the REST API.

```bash
curl -H "Authorization: Bearer <API_KEY>" \
    https://headscale.example.com/api/v1/user?name=bob

```

--------------------------------

### Advertise routes when registering a node

Source: https://headscale.net/stable/ref/routes

Register a node as a subnet router by advertising the routes it should handle as a comma-separated list. Replace <YOUR_HEADSCALE_URL> with the actual Headscale server URL.

```bash
$ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-routes=10.0.0.0/8,192.168.0.0/24

```

--------------------------------

### GET /api/v1/user?name=bob

Source: https://headscale.net/stable/ref/api

Retrieves details for a specific user by name. Requires HTTP Bearer authentication with a valid API key.

```APIDOC
## GET /api/v1/user?name=bob

### Description
Retrieves details for the user named 'bob'.

### Method
GET

### Endpoint
/api/v1/user?name=bob

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the user to retrieve.

### Request Example
```
curl -H "Authorization: Bearer <API_KEY>" \
    https://headscale.example.com/api/v1/user?name=bob
```

### Response
#### Success Response (200)
Returns details for the specified user.

#### Response Example
```
{
  "user": {}
}
```
```

--------------------------------

### Register node via web authentication (Docker)

Source: https://headscale.net/stable/usage/getting-started

Approve a node registration on the headscale server running in Docker using the Auth ID.

```bash
docker exec -it headscale \
  headscale auth register --user <USER> --auth-id <AUTH_ID>
```

--------------------------------

### Set headscale unix_socket in config.yaml

Source: https://headscale.net/stable/setup/install/official?q=

Configures the headscale Unix socket to a path writable by the headscale user, as required for systemd to start the service.

```yaml
unix_socket: /var/run/headscale/headscale.sock

```

--------------------------------

### Create pre-authenticated key with tags

Source: https://headscale.net/stable/ref/registration?q=

Creates a pre-authenticated key with at least one tag. The key is printed with default settings: can be used once and is valid for one hour.

```bash
headscale preauthkeys create --tags tag:<TAG>

```

--------------------------------

### autogroup:self policy example

Source: https://headscale.net/stable/ref/policy

Includes devices where the same user is authenticated on both the source and destination. Does not include tagged devices. Can only be used in policy destinations.

```json
{
  "grants": [
    {
      "src": ["autogroup:member"],
      "dst": ["autogroup:self"],
      "ip": ["*"]
    }
  ]
}
```

--------------------------------

### List Headscale API keys

Source: https://headscale.net/stable/ref/api?q=

Displays all API keys currently associated with the server.

```bash
headscale apikeys list
```

--------------------------------

### Cross-compile Headscale for OpenBSD

Source: https://headscale.net/stable/setup/install/source

Commands to clone the repository and use the Makefile to cross-compile the binary for the OpenBSD target.

```bash
# Install prerequisites
# 1. go v1.20+: headscale newer than 0.21 needs go 1.20+ to compile
# 2. gmake: Makefile in the headscale repo is written in GNU make syntax

git clone https://github.com/juanfont/headscale.git

cd headscale

# optionally checkout a release
# option a. you can find official release at https://github.com/juanfont/headscale/releases/latest
# option b. get latest tag, this may be a beta release
latestTag=$(git describe --tags `git rev-list --tags --max-count=1`)

git checkout $latestTag

make build GOOS=openbsd

# copy headscale to openbsd machine and put it in /usr/local/sbin
```

--------------------------------

### Access debug interface directly with curl

Source: https://headscale.net/stable/ref/debug?q=

Query the debug interface directly on the server where Headscale is installed. The debug interface is available at http://localhost:9090/debug/.

```bash
curl http://localhost:9090/debug/

```

--------------------------------

### Allow All policy file

Source: https://headscale.net/stable/ref/policy

Defines a policy file that allows all traffic between nodes. This is the minimal policy file to start using access control in Headscale.

```huJSON
{
  "acls": [
    {"action": "accept", "src": ["*"], "dst": ["*"]}
  ]
}
```

--------------------------------

### Make headscale executable

Source: https://headscale.net/stable/setup/install/official?q=

Makes the headscale binary executable.

```bash
sudo chmod +x /usr/bin/headscale

```

--------------------------------

### Headscale output showing successful registration

Source: https://headscale.net/stable/usage/connect/windows?q=

Example of headscale output showing a successful registration request. This is not an error; it indicates a POST request to /machine/redacted.

```text
[GIN] 2022/02/10 - 16:39:34 | 200 |    1.105306ms |       127.0.0.1 | POST     "/machine/redacted"

```

--------------------------------

### Download headscale standalone binary

Source: https://headscale.net/stable/setup/install/official

Downloads the headscale binary from GitHub releases. Replace <HEADSCALE VERSION> and <ARCH> with the desired version and architecture.

```bash
sudo wget --output-document=/usr/bin/headscale \
https://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>
```

--------------------------------

### autogroup:nonroot SSH rule example

Source: https://headscale.net/stable/ref/policy

Used in Tailscale SSH rules to allow access to any user except root. Can only be used in the users field of SSH rules.

```json
{
  "ssh": [
    {
      "action": "accept",
      "src": ["autogroup:member"],
      "dst": ["autogroup:self"],
      "users": ["autogroup:nonroot"]
    }
  ]
}
```
Tokens:
Raw