Headscale

介绍

Headscale 是一个开源的、自托管的 Tailscale 控制服务器（Control Server）。Tailscale 是一个基于 WireGuard 协议的虚拟专用网络（VPN）工具，而 Headscale 则允许你在自己的服务器上运行 Tailscale 的控制平面，从而完全掌控你的网络环境，而不依赖 Tailscale 的官方云服务。

核心功能

自托管 你可以在自己的服务器上运行 Headscale，完全控制你的网络和数据。
兼容 Tailscale 客户端 Headscale 与 Tailscale 客户端完全兼容，你可以使用 Tailscale 客户端连接到 Headscale 服务器。
多用户支持 Headscale 支持多用户管理，可以为不同的用户或团队分配独立的网络权限。
灵活的网络配置 你可以自定义 DNS、子网路由、访问控制列表（ACL）等网络配置。
轻量级 Headscale 设计简洁，资源占用低，适合在小型服务器或容器中运行。

工作原理

控制服务器：Headscale 作为控制服务器，负责管理设备注册、认证和网络配置。
客户端连接：设备通过 Tailscale 客户端连接到 Headscale 服务器。
点对点通信：设备之间通过 WireGuard 协议直接通信，数据不经过 Headscale 服务器。

快速开始

搭建 Headscale

docker-compose

yaml

version: "3.8"

services:
  headscale:
    image: headscale/headscale:0.22.3
    container_name: headscale
    volumes:
      - ./data:/etc/headscale
      - /var/run/headscale/:/var/run/headscale/
    ports:
      - 8080:8080
      - 3478:3478/udp
    command: headscale serve
    restart: unless-stopped

config.yaml

yaml

---
# headscale will look for a configuration file named `config.yaml` (or `config.json`) in the following order:
#
# - `/etc/headscale`
# - `~/.headscale`
# - current working directory

# The url clients will connect to.
# Typically this will be a domain like:
#
# https://myheadscale.example.com:443
#  使用说明页面显示的地址
server_url: http://127.0.0.1:8080

# Address to listen to / bind to on the server
#
# For production:
# listen_addr: 0.0.0.0:8080。
listen_addr: 0.0.0.0:8080

# Address to listen to /metrics, you may want
# to keep this endpoint private to your internal
# network
#
metrics_listen_addr: 127.0.0.1:9090

# Address to listen for gRPC.
# gRPC is used for controlling a headscale server
# remotely with the CLI
# Note: Remote access _only_ works if you have
# valid certificates.
#
# For production:
# grpc_listen_addr: 0.0.0.0:50443
grpc_listen_addr: 127.0.0.1:50443

# Allow the gRPC admin interface to run in INSECURE
# mode. This is not recommended as the traffic will
# be unencrypted. Only enable if you know what you
# are doing.
grpc_allow_insecure: false

# Private key used to encrypt the traffic between headscale
# and Tailscale clients.
# The private key file will be autogenerated if it's missing.
#
private_key_path: /etc/headscale/private.key

# The Noise section includes specific configuration for the
# TS2021 Noise protocol
noise:
  # The Noise private key is used to encrypt the
  # traffic between headscale and Tailscale clients when
  # using the new Noise-based protocol. It must be different
  # from the legacy private key.
  private_key_path: /etc/headscale/noise_private.key

# List of IP prefixes to allocate tailaddresses from.
# Each prefix consists of either an IPv4 or IPv6 address,
# and the associated prefix length, delimited by a slash.
# It must be within IP ranges supported by the Tailscale
# client - i.e., subnets of 100.64.0.0/10 and fd7a:115c:a1e0::/48.
# See below:
# IPv6: https://github.com/tailscale/tailscale/blob/22ebb25e833264f58d7c3f534a8b166894a89536/net/tsaddr/tsaddr.go#LL81C52-L81C71
# IPv4: https://github.com/tailscale/tailscale/blob/22ebb25e833264f58d7c3f534a8b166894a89536/net/tsaddr/tsaddr.go#L33
# Any other range is NOT supported, and it will cause unexpected issues.
ip_prefixes:
  - fd7a:115c:a1e0::/48
  - 100.64.0.0/10

# DERP is a relay system that Tailscale uses when a direct
# connection cannot be established.
# https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp
#
# headscale needs a list of DERP servers that can be presented
# to the clients.
# 内嵌的derp，建议关闭
derp:
  server:
    # If enabled, runs the embedded DERP server and merges it into the rest of the DERP config
    # The Headscale server_url defined above MUST be using https, DERP requires TLS to be in place
    enabled: true

    # Region ID to use for the embedded DERP server.
    # The local DERP prevails if the region ID collides with other region ID coming from
    # the regular DERP config.
    region_id: 999

    # Region code and name are displayed in the Tailscale UI to identify a DERP region
    region_code: "headscale"
    region_name: "Headscale Embedded DERP"

    # Listens over UDP at the configured address for STUN connections - to help with NAT traversal.
    # When the embedded DERP server is enabled stun_listen_addr MUST be defined.
    #
    # For more details on how this works, check this great article: https://tailscale.com/blog/how-tailscale-works/
    stun_listen_addr: "0.0.0.0:3478"

  # List of externally available DERP maps encoded in JSON
  urls:
    - https://controlplane.tailscale.com/derpmap/default

  # Locally available DERP map files encoded in YAML
  #
  # This option is mostly interesting for people hosting
  # their own DERP servers:
  # https://tailscale.com/kb/1118/custom-derp-servers/
  #
  # paths:
  #   - /etc/headscale/derp-example.yaml
  # derp 路径
  paths:
  #   - /etc/headscale/derp.yaml

  # If enabled, a worker will be set up to periodically
  # refresh the given sources and update the derpmap
  # will be set up.
  auto_update_enabled: true

  # How often should we check for DERP updates?
  update_frequency: 24h

# Disables the automatic check for headscale updates on startup
disable_check_updates: false

# Time before an inactive ephemeral node is deleted?
ephemeral_node_inactivity_timeout: 30m

# Period to check for node updates within the tailnet. A value too low will severely affect
# CPU consumption of Headscale. A value too high (over 60s) will cause problems
# for the nodes, as they won't get updates or keep alive messages frequently enough.
# In case of doubts, do not touch the default 10s.
node_update_check_interval: 10s

# SQLite config
db_type: sqlite3

# For production:
db_path: /etc/headscale/db.sqlite

# # Postgres config
# If using a Unix socket to connect to Postgres, set the socket path in the 'host' field and leave 'port' blank.
# db_type: postgres
# db_host: localhost
# db_port: 5432
# db_name: headscale
# db_user: foo
# db_pass: bar

# If other 'sslmode' is required instead of 'require(true)' and 'disabled(false)', set the 'sslmode' you need
# in the 'db_ssl' field. Refers to https://www.postgresql.org/docs/current/libpq-ssl.html Table 34.1.
# db_ssl: false

### TLS configuration
#
## Let's encrypt / ACME
#
# headscale supports automatically requesting and setting up
# TLS for a domain with Let's Encrypt.
#
# URL to ACME directory
acme_url: https://acme-v02.api.letsencrypt.org/directory

# Email to register with ACME provider
acme_email: ""

# Domain name to request a TLS certificate for:
tls_letsencrypt_hostname: ""

# Path to store certificates and metadata needed by
# letsencrypt
# For production:
tls_letsencrypt_cache_dir: /var/lib/headscale/cache

# Type of ACME challenge to use, currently supported types:
# HTTP-01 or TLS-ALPN-01
# See [docs/tls.md](docs/tls.md) for more information
tls_letsencrypt_challenge_type: HTTP-01
# When HTTP-01 challenge is chosen, letsencrypt must set up a
# verification endpoint, and it will be listening on:
# :http = port 80
tls_letsencrypt_listen: ":http"

## Use already defined certificates:
tls_cert_path: ""
tls_key_path: ""

log:
  # Output formatting for logs: text or json
  format: text
  level: info

# Path to a file containg ACL policies.
# ACLs can be defined as YAML or HUJSON.
# https://tailscale.com/kb/1018/acls/
acl_policy_path: ""

## DNS
#
# headscale supports Tailscale's DNS configuration and MagicDNS.
# Please have a look to their KB to better understand the concepts:
#
# - https://tailscale.com/kb/1054/dns/
# - https://tailscale.com/kb/1081/magicdns/
# - https://tailscale.com/blog/2021-09-private-dns-with-magicdns/
#
dns_config:
  # Whether to prefer using Headscale provided DNS or use local.
  override_local_dns: true

  # List of DNS servers to expose to clients.
  nameservers:
    - 1.1.1.1

  # NextDNS (see https://tailscale.com/kb/1218/nextdns/).
  # "abc123" is example NextDNS ID, replace with yours.
  #
  # With metadata sharing:
  # nameservers:
  #   - https://dns.nextdns.io/abc123
  #
  # Without metadata sharing:
  # nameservers:
  #   - 2a07:a8c0::ab:c123
  #   - 2a07:a8c1::ab:c123

  # Split DNS (see https://tailscale.com/kb/1054/dns/),
  # list of search domains and the DNS to query for each one.
  #
  # restricted_nameservers:
  #   foo.bar.com:
  #     - 1.1.1.1
  #   darp.headscale.net:
  #     - 1.1.1.1
  #     - 8.8.8.8

  # Search domains to inject.
  domains: []

  # Extra DNS records
  # so far only A-records are supported (on the tailscale side)
  # See https://github.com/juanfont/headscale/blob/main/docs/dns-records.md#Limitations
  # extra_records:
  #   - name: "grafana.myvpn.example.com"
  #     type: "A"
  #     value: "100.64.0.3"
  #
  #   # you can also put it in one line
  #   - { name: "prometheus.myvpn.example.com", type: "A", value: "100.64.0.3" }

  # Whether to use [MagicDNS](https://tailscale.com/kb/1081/magicdns/).
  # Only works if there is at least a nameserver defined.
  magic_dns: true

  # Defines the base domain to create the hostnames for MagicDNS.
  # `base_domain` must be a FQDNs, without the trailing dot.
  # The FQDN of the hosts will be
  # `hostname.user.base_domain` (e.g., _myhost.myuser.example.com_).
  base_domain: example.com

# Unix socket used for the CLI to connect without authentication
# Note: for production you will want to set this to something like:
unix_socket: /var/run/headscale/headscale.sock
unix_socket_permission: "0770"
#
# headscale supports experimental OpenID connect support,
# it is still being tested and might have some bugs, please
# help us test it.
# OpenID Connect
# oidc:
#   only_start_if_oidc_is_available: true
#   issuer: "https://your-oidc.issuer.com/path"
#   client_id: "your-oidc-client-id"
#   client_secret: "your-oidc-client-secret"
#   # Alternatively, set `client_secret_path` to read the secret from the file.
#   # It resolves environment variables, making integration to systemd's
#   # `LoadCredential` straightforward:
#   client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
#   # client_secret and client_secret_path are mutually exclusive.
#
#   # The amount of time from a node is authenticated with OpenID until it
#   # expires and needs to reauthenticate.
#   # Setting the value to "0" will mean no expiry.
#   expiry: 180d
#
#   # Use the expiry from the token received from OpenID when the user logged
#   # in, this will typically lead to frequent need to reauthenticate and should
#   # only been enabled if you know what you are doing.
#   # Note: enabling this will cause `oidc.expiry` to be ignored.
#   use_expiry_from_token: false
#
#   # Customize the scopes used in the OIDC flow, defaults to "openid", "profile" and "email" and add custom query
#   # parameters to the Authorize Endpoint request. Scopes default to "openid", "profile" and "email".
#
#   scope: ["openid", "profile", "email", "custom"]
#   extra_params:
#     domain_hint: example.com
#
#   # List allowed principal domains and/or users. If an authenticated user's domain is not in this list, the
#   # authentication request will be rejected.
#
#   allowed_domains:
#     - example.com
#   # Note: Groups from keycloak have a leading '/'
#   allowed_groups:
#     - /headscale
#   allowed_users:
#     - alice@example.com
#
#   # If `strip_email_domain` is set to `true`, the domain part of the username email address will be removed.
#   # This will transform `first-name.last-name@example.com` to the user `first-name.last-name`
#   # If `strip_email_domain` is set to `false` the domain part will NOT be removed resulting to the following
#   user: `first-name.last-name.example.com`
#
#   strip_email_domain: true

# Logtail configuration
# Logtail is Tailscales logging and auditing infrastructure, it allows the control panel
# to instruct tailscale nodes to log their activity to a remote server.
logtail:
  # Enable logtail for this headscales clients.
  # As there is currently no support for overriding the log server in headscale, this is
  # disabled by default. Enabling this will make your clients send logs to Tailscale Inc.
  enabled: false

# Enabling this option makes devices prefer a random port for WireGuard traffic over the
# default static port 41641. This option is intended as a workaround for some buggy
# firewall devices. See https://tailscale.com/kb/1181/firewalls/ for more information.
randomize_client_port: false

常用命令

命令列表

shell

root@e06309da4422:/# headscale help

Usage:
  headscale [command]

Available Commands:
  apikeys     Handle the Api keys in Headscale
  completion  Generate the autocompletion script for the specified shell
  configtest  Test the configuration.
  debug       debug and testing commands
  generate    Generate commands
  help        Help about any command
  mockoidc    Runs a mock OIDC server for testing
  nodes       Manage the nodes of Headscale
  preauthkeys Handle the preauthkeys in Headscale
  routes      Manage the routes of Headscale
  serve       Launches the headscale server
  users       Manage the users of Headscale
  version     Print the version.

Flags:
  -c, --config string   config file (default is /etc/headscale/config.yaml)
      --force           Disable prompts and forces the execution
  -h, --help            help for headscale
  -o, --output string   Output format. Empty for human-readable, 'json', 'json-line' or 'yaml'

Use "headscale [command] --help" for more information about a command.

用户管理

shell

# 创建用户：在 Headscale 中，用户（user）用于组织和隔离不同的节点。
headscale users create <username>

# 列出所有用户：查看当前存在的所有用户。
headscale users list

# 删除用户：移除指定的用户。
headscale users destroy <username>

# 重命名用户：修改现有用户的名称。
headscale users rename <old_username> <new_username>

预授权密钥管理

shell

# 创建预授权密钥：生成一个可重复使用且具有特定过期时间的预授权密钥。
headscale preauthkeys create -e 365d --reusable -u <username>

# 列出预授权密钥：查看所有已创建的预授权密钥。
headscale preauthkeys list

节点管理

shell

# 列出所有节点：显示所有已注册的节点及其详细信息。
headscale nodes list

# 删除节点：根据节点 ID 删除特定节点。
headscale nodes delete -i <id>

# 注册节点：使用节点密钥将节点注册到指定的用户。
headscale -u <username> nodes register --key <node_key>

路由管理

shell

# 列出路由：查看所有已知路由及其状态。
headscale routes list

# 启用路由：根据路由 ID 启用特定路由。
headscale routes enable -r <route_id>

# 禁用路由：根据路由 ID 禁用特定路由。
headscale routes disable -r <route_id>

Headscale 配置 ACL 的方法

要想在 Headscale 中配置 ACL，只需使用 HuJSON 或者 YAML 编写相应的 ACL 规则（HuJSON 格式的文件名后缀为 hujson），然后在 Headscale 的配置文件中引用 ACL 规则文件即可。

yaml

# Path to a file containg ACL policies.
# ACLs can be defined as YAML or HUJSON.
# https://tailscale.com/kb/1018/acls/
acl_policy_path: "./acl.yaml"

ACL 规则示例

允许所有流量

默认的 ACL 规则允许所有访问流量，规则内容如下：

yaml

# acl.yaml
acls:
  - action: accept
    src:
      - "*"
    dst:
      - "*:*"

允许特定 ns 访问所有流量

假设 Headscale 有两个 namesapce：default 和 guest。管理员的设备都在 default namespace 中，访客的设备都在 guest namespace 中。

bash

$ headscale ns ls
ID | Name    | Created
1  | default | 2022-08-20 06:15:17
2  | guest   | 2022-11-27 09:20:25

$ headscale -n default node ls
ID | Hostname               | Name                            | NodeKey | Namespace | IP addresses | Ephemeral | Last seen           | Online  | Expired
2  | OpenWrt                | openwrt-njprohi0                | [7LdVc] | default   | 10.1.0.2,    | false     | 2022-08-26 04:18:43 | offline | no
5  | tailscale              | tailscale-home                  | [pwlFE] | default   | 10.1.0.5,    | false     | 2022-11-27 10:02:35 | online  | no
10 | k3s-worker05           | share                           | [5Z38M] | default   | 10.1.0.9,    | false     | 2022-11-22 18:49:25 | offline | no
11 | Galaxy a52s            | galaxy-a52s-arg5owsh            | [U+0qY] | default   | 10.1.0.1,    | false     | 2022-11-27 10:02:34 | online  | no

$ headscale -n guest node ls
ID | Hostname  | Name      | NodeKey | Namespace | IP addresses | Ephemeral | Last seen           | Online | Expired
12 | guest-1 | guest-1 | [75qSK] | guest     | 10.1.0.10,   | false     | 2022-11-27 10:05:33 | online | no
13 | guest-2 | guest-2 | [8lONp] | guest     | 10.1.0.11,   | false     | 2022-11-27 10:05:31 | online | no

现在我想让 default namespace 中的设备可以访问所有设备，而 guest namespace 中的设备只能访问 guest namespace 中的设备，那么规则应该这么写：

yaml

# acl.yaml
acls:
  - action: accept
    src:
      - "default"
    dst:
      - "*:*"
      - "guest:*"
  - action: accept
    src:
      - "guest"
    dst:
      - "guest:*"

在 guest-1 上查看 Tailscale 状态：

bash

$ tailscale status
10.1.0.10       ks-node-2            guest        linux   -
                desktop-aoulurh-j7dfnsul.default.example.com default      windows offline
                galaxy-a52s-arg5owsh.default.example.com default      android active; relay "hs", tx 12112 rx 11988
                guest-3            guest        linux   active; direct 172.31.73.176:41641, tx 2552 rx 2440
                openwrt-njprohi0.default.example.com default      linux   offline
                tailscale-home.default.example.com default      linux   active; direct 60.184.243.56:41641, tx 3416 rx 25576

看起来 guest-1 可以看到所有的设备，但事实上它只能 ping 通 guest-2，我们来验证一下：

bash

$ ping 10.1.0.1
PING 10.1.0.1 (10.1.0.1) 56(84) bytes of data.
^C
--- 10.1.0.1 ping statistics ---
9 packets transmitted, 0 received, 100% packet loss, time 8169ms

果然是 ping 不通的。但是 10.1.0.1 这个设备是可以反向 ping 通 guest-1 的：

bash

# 在 10.1.0.1 所在的设备操作
$ ping 10.1.0.10
PING 10.1.0.10 (10.1.0.10) 56(84) bytes of data.
64 bytes from 10.1.0.10: icmp_seq=1 ttl=64 time=68.9 ms
64 bytes from 10.1.0.10: icmp_seq=2 ttl=64 time=91.5 ms
64 bytes from 10.1.0.10: icmp_seq=3 ttl=64 time=85.3 ms
64 bytes from 10.1.0.10: icmp_seq=4 ttl=64 time=79.7 ms
^C
--- 10.1.0.10 ping statistics ---
4 packets transmitted, 4 received, 0% packet loss, time 3005ms
rtt min/avg/max/mdev = 68.967/81.389/91.551/8.306 ms

ssh 测试一下：

bash

$ ssh root@10.1.0.10
root@10.1.0.10's password:

完美。

下面再来看看 guest-1 能不能 ping 通 guest-2：

bash

# 在 guest-1 设备上操作
$ ping 10.1.0.11
PING 10.1.0.11 (10.1.0.11) 56(84) bytes of data.
64 bytes from 10.1.0.11: icmp_seq=1 ttl=64 time=2.93 ms
64 bytes from 10.1.0.11: icmp_seq=2 ttl=64 time=1.33 ms
^C
--- 10.1.0.11 ping statistics ---
2 packets transmitted, 2 received, 0% packet loss, time 1001ms
rtt min/avg/max/mdev = 1.325/2.128/2.931/0.803 ms

和我在上面预测的效果一样，ACL 规则生效了。

神奇的 tag

tag 有一个非常神奇的功效：它可以让 src 和 dst 中的元素失效。具体什么意思呢？假设你的 src 或 dst 中指定了 namespace 或者 group，那么这个规则只对这个 namespace 或者 group 中（没有分配 tag 的设备）生效。

举个例子你就明白了，现在我给 guest-2 打上一个 tag：

bash

$ headscale node tag -i 13 -t tag:test
Machine updated

$ headscale -n guest node ls -t
ID | Hostname  | Name      | NodeKey | Namespace | IP addresses | Ephemeral | Last seen           | Online | Expired | ForcedTags | InvalidTags | ValidTags
12 | ks-node-2 | ks-node-2 | [75qSK] | guest     | 10.1.0.10,   | false     | 2022-11-27 10:18:35 | online | no      |            |             |
13 | ks-node-3 | ks-node-3 | [8lONp] | guest     | 10.1.0.11,   | false     | 2022-11-27 10:18:31 | online | no      | tag:test   |             |

此时 guest-1 就 ping 不通 guest-2 了：

bash

# 在 guest-1 设备上操作
$ ping 10.1.0.11
PING 10.1.0.11 (10.1.0.11) 56(84) bytes of data.
^C
--- 10.1.0.11 ping statistics ---
4 packets transmitted, 0 received, 100% packet loss, time 3070ms

这就说明 guest-2 并不包含在 guest:* 这个访问目标中，也就是说打了 tag 的设备并不包含在 guest:* 这个访问目标中。

此时其他设备如果还想继续 guest-2，必须在 dst 中指定 tag:test：

yaml

acls:
  - action: accept
    src:
      - "default"
    dst:
      - "*:*"
      - "guest:*"
      - "tag:test:*"
  - action: accept
    src:
      - "guest"
    dst:
      - "guest:*"
      - "tag:test:*"

再次测试访问：

bash

# 在 guest-1 设备上操作
$ ping 10.1.0.11
PING 10.1.0.11 (10.1.0.11) 56(84) bytes of data.
64 bytes from 10.1.0.11: icmp_seq=1 ttl=64 time=1.31 ms
64 bytes from 10.1.0.11: icmp_seq=2 ttl=64 time=3.40 ms
^C
--- 10.1.0.11 ping statistics ---
2 packets transmitted, 2 received, 0% packet loss, time 1002ms
rtt min/avg/max/mdev = 1.314/2.355/3.397/1.041 ms

果然可以 ping 通了。

Headscale ​

介绍 ​

核心功能 ​

工作原理 ​

快速开始 ​

搭建 Headscale ​

docker-compose ​

config.yaml ​

常用命令 ​

命令列表 ​

用户管理 ​

预授权密钥管理 ​

节点管理 ​

路由管理 ​

Headscale 配置 ACL 的方法 ​

ACL 规则示例 ​

允许所有流量 ​

允许特定 ns 访问所有流量 ​

神奇的 tag ​

Headscale

介绍

核心功能

工作原理

快速开始

搭建 Headscale

docker-compose

config.yaml

常用命令

命令列表

用户管理

预授权密钥管理

节点管理

路由管理

Headscale 配置 ACL 的方法

ACL 规则示例

允许所有流量

允许特定 ns 访问所有流量

神奇的 tag