Ansible 角色: Headscale

这是一个用于安装和配置 Headscale 的 Ansible 角色，Headscale 是一个开源的自托管 Tailscale 控制服务器实现。

它非常棒，快来看看: juanfont/Headscale

免责声明

本项目的作者与 Headscale 项目或 Tailscale Inc. 没有任何关联。

本软件是“按原样”提供，没有任何形式的保证，包括但不限于适销性、特定目的的适用性和不侵权的保证。在任何情况下，作者对因使用本软件或与本软件相关的行为（包括合同、侵权等）造成的任何索赔、损害或其他责任不承担责任。

使用风险自负

兼容性

此角色已在以下平台上进行测试：

• CentOS 8 x64
• Debian 10 x64
• Debian 11 x64
• Ubuntu Server 20.04 x64
• Ubuntu Server 22.04 x64

安装

ansible-galaxy

ansible-galaxy install hampusstrom.headscale

手动安装

当前用户安装：

git clone https://github.com/hampusstrom/ansible-role-headscale.git ~/.ansible/roles/hampusstrom.headscale

系统范围安装：

git clone https://github.com/hampusstrom/ansible-role-headscale.git /etc/ansible/roles/hampusstrom.headscale

需求

此角色没有特别的要求，应在支持 Ansible、Headscale 和 Systemd 的任何地方正常工作。

GitHub API

此角色使用 GitHub API。

GitHub API 有请求限制。

未认证用户每小时只能进行 60 次请求。

如果您是开发者，可能会轻易达到此限制。

要解决此问题，您可以在此处获取个人访问令牌: https://github.com/settings/tokens/new

在 headscale_github_api_* 变量中填写访问令牌详细信息。

headscale_github_api_username: 你的_GitHub_用户名

headscale_github_api_password: 你的_个人访问令牌

headscale_github_api_auth: true

初始化系统: systemd

需要权限: 是

因为需要权限，请在全局定义为 become:yes 的剧本中使用此角色，或者使用 become: yes 关键字调用此角色。

- hosts: headscale
  become: yes
  roles:
    - role: hampusstrom.headscale

# 或者

- hosts: headscale
  roles:
    - role: hampusstrom.headscale
      become: yes

角色变量

所有可用变量的完整描述可以在 defaults/main.yaml 中找到。

变量命名规范

与此角色相关的变量总是以 headscale_ 开头。

headscale_version

定义要下载和安装在目标机器上的 Headscale 版本。 可以是版本号（无 'v' 前缀）。例如 0.16.4 或 latest

最新版本将自动检索 juanfont/headscale GitHub 仓库中的最新发布标签。

默认值：latest

headscale_config

Headscale config.yaml 文件的内容，以 yaml 对象表示。 查看 Headscale 项目中的默认配置以获取灵感。 截至目前，Headscale 版本 0.20.0 所需的以下最小值：

headscale_config:
  server_url: "http://127.0.01:8080"
  listen_addr: 127.0.0.1:8080
  private_key_path: "{{ headscale_lib_dir_path }}/private.key"
  db_type: sqlite3
  unix_socket: "{{ headscale_run_dir_path }}/headscale.sock"
  ip_prefixes:
    - 100.64.0.0/10
  noise:
    private_key_path: "{{ headscale_lib_dir_path }}/noise_private.key"

headscale_acl

Headscale acl.yaml 文件的内容，以 yaml 对象表示。

headscale_github_repository

定义在查找和下载 Headscale 二进制文件时使用的用户/仓库。 可以更改为其他仓库，允许安装分叉版本。

默认值：juanfont/headscale

headscale_remove_unmanaged_users

如果设置为 true，任何未在 headscale_users 中指定的用户将被永久删除。

使用风险自负

默认值：false

headscale_users

应该创建的用户列表，并且在与 headscale_remove_unmanaged_users 一起使用时不会被删除。

默认值：[]

headscale_binary_path

定义 Headscale 二进制文件将要下载并安装到的位置。

默认值：/usr/local/bin/headscale

headscale_user_name

定义应运行 Headscale systemd 守护进程的系统用户名称。 如果该用户不存在，将会被创建。

默认值：headscale

headscale_user_group

定义 headscale_user_name 用户的主要组名称。

默认值：{{ headscale_user_name }}

headscale_user_uid

定义 headscale_user_name 用户的用户 ID。

默认值：777

headscale_user_gid

定义 headscale_user_group 组的组 ID。

默认值：{{ headscale_user_uid }}

headscale_etc_dir_path

定义 Headscale 配置数据应驻留的路径。 通常你不需要更改此路径，但对于一些自定义配置/分叉，有这个选项。

默认值：/etc/headscale

headscale_lib_dir_path

定义 Headscale 库数据应驻留的路径。 通常你不需要更改此路径，但对于一些自定义配置/分叉，有这个选项。

默认值：/var/lib/headscale

headscale_run_dir_path

定义 Headscale UNIX 套接字应驻留的路径。 通常你不需要更改此路径，但对于一些自定义配置/分叉，有这个选项。 unix_socket 配置条目应该指向此目录下的 .sock 文件。 例如 unix_socket: /var/run/headscale/headscale.sock

默认值：/var/run/headscale

headscale_db_path

SQLite 数据库文件的路径。

默认值：{{ headscale_lib_dir_path }}/db.sqlite

headscale_backup_dir_path

数据库备份存储的路径。 在任何升级 Headscale 之前，备份会自动创建。 如果你选择降级 Headscale，强烈建议你恢复你的数据库。 要做到这一点，只需停止 Headscale，将 db 文件复制到 headscale_db_path 并重启 Headscale。

默认值：{{ headscale_lib_dir_path }}/backups

示例剧本

请注意，你应该始终检查官方 Headscale 文档，以确保为你的 Headscale 版本填写必要的所有值。 我强烈建议复制 官方配置示例 并将其作为你配置的基础。

---
---
# 运行命令:
# ansible-playbook -i "你的库存文件" -K example-playbook.yml
- hosts: all
  become: yes
  vars:
    headscale_version: 0.20.0
    headscale_config:
    # headscale 将查找名为 `config.yaml`（或 `config.json`）的配置文件，顺序如下：
    #
    # - `/etc/headscale`
    # - `~/.headscale`
    # - 当前工作目录

    # 客户端将连接的 URL。
    # 通常这将是一个域名，如：
    #
    # https://myheadscale.example.com:443
    #
    server_url: http://127.0.0.1:8080

    # 服务器的监听地址
    #
    # 对于生产环境：
    # listen_addr: 0.0.0.0:8080
    listen_addr: 127.0.0.1:8080

    # 监听 /metrics 的地址，你可能希望将该端点保持私有于内部网络
    #
    metrics_listen_addr: 127.0.0.1:9090

    # gRPC 的监听地址。
    # gRPC 用于远程控制 Headscale 服务器
    # 注意：远程访问_仅在你有有效证书时工作。
    #
    # 对于生产环境：
    # grpc_listen_addr: 0.0.0.0:50443
    grpc_listen_addr: 127.0.0.1:50443

    # 允许 gRPC 管理界面在不安全的模式下运行。建议不要启用，因为流量将未加密。仅当你知道自己在做什么时才启用。
    grpc_allow_insecure: false

    # 用于加密 Headscale 与 Tailscale 客户端之间流量的私钥。
    # 如果缺失，将会自动生成私钥文件。
    #
    # 对于生产环境：
    # /var/lib/headscale/private.key
    private_key_path: ./private.key

    # Noise 部分包含 TS2021 Noise 协议的特定配置
    noise:
      # Noise 私钥用于在使用新的 baseado 在 Headscale 和 Tailscale 客户端之间加密流量。
      # 它必须不同于遗留私钥。
      #
      # 对于生产环境：
      # private_key_path: /var/lib/headscale/noise_private.key
      private_key_path: ./noise_private.key

    # 从中分配尾地址的 IP 前缀列表。
    # 每个前缀包含 IPv4 或 IPv6 地址和相关的前缀长度，以斜杠分隔。
    # 虽然这看起来可以接受任意值，但必须在 Tailscale 客户端支持的 IP 范围内。
    ip_prefixes:
      - fd7a:115c:a1e0::/48
      - 100.64.0.0/10

    # DERP 是 Tailscale 在无法建立直接连接时使用的中继系统。
    # https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp
    #
    # headscale 需要一组 DERP 服务器的列表，以便呈现给客户端。
    derp:
      server:
        # 如果启用，运行嵌入的 DERP 服务器并将其合并到其余的 DERP 配置中。
        # 上面定义的 Headscale server_url 必须使用 https，DERP 需要 TLS。
        enabled: false

        # 用于嵌入的 DERP 服务器的区域 ID。
        # 如果区域 ID 与常规 DERP 配置中来的其他区域 ID 冲突，则本地 DERP 优先。
        region_id: 999

        # 区域代码和名称在 Tailscale UI 中显示，以识别 DERP 区域
        region_code: "headscale"
        region_name: "Headscale 嵌入 DERP"

        # 通过配置的地址监听 UDP 以进行 STUN 连接，以帮助 NAT 穿透。
        # 启用嵌入的 DERP 服务器时，在此定义 stun_listen_addr。
        #
        # 有关此如何工作的信息，请查看此优秀文章: https://tailscale.com/blog/how-tailscale-works/
        stun_listen_addr: "0.0.0.0:3478"

      # 以 JSON 编码的外部可用 DERP 映射列表
      urls:
        - https://controlplane.tailscale.com/derpmap/default

      # 以 YAML 编码的本地可用 DERP 映射文件
      #
      # 此选项对托管自己 DERP 服务器的人尤其有趣：
      # https://tailscale.com/kb/1118/custom-derp-servers/
      #
      # paths:
      #   - /etc/headscale/derp-example.yaml
      paths: []

      # 如果启用，将设置一个工作程序以定期刷新给定的源并更新 derpmap
      auto_update_enabled: true

      # 我们多久检查一次 DERP 更新？
      update_frequency: 24h

    # 启动时禁用 headscale 更新的自动检查
    disable_check_updates: false

    # 删除不活动的短期节点之前的时间？
    ephemeral_node_inactivity_timeout: 30m

    # 检查 tailnet 中节点更新的时间间隔。值太低会严重影响 Headscale 的 CPU 消耗。值过高（超过 60s）将导致节点的问题，因为它们不会频繁地获得更新或保持活动消息。
    # 如果不确定，请保持默认的 10s。
    node_update_check_interval: 10s

    # SQLite 配置
    db_type: sqlite3

    # 对于生产：
    # db_path: /var/lib/headscale/db.sqlite
    db_path: ./db.sqlite

    # # Postgres 配置
    # 如果使用 Unix 套接字连接到 Postgres，请在 'host' 字段中设置套接字路径，'port' 为空。
    # db_type: postgres
    # db_host: localhost
    # db_port: 5432
    # db_name: headscale
    # db_user: foo
    # db_pass: bar

    # 如果需要其他 'sslmode' 而不是 'require(true)' 和 'disabled(false)'，请在 'db_ssl' 字段中设置需要的 'sslmode'。
    # 参考 https://www.postgresql.org/docs/current/libpq-ssl.html 表 34.1。
    # db_ssl: false

    ### TLS 配置
    #
    ## Let's encrypt / ACME
    #
    # headscale 支持自动请求和设置
    # TLS 证书。
    #
    # ACME 目录的 URL
    acme_url: https://acme-v02.api.letsencrypt.org/directory

    # 注册 ACME 供应商的电子邮件
    acme_email: ""

    # 请求 TLS 证书的域名：
    tls_letsencrypt_hostname: ""

    # 存储证书和 letsencrypt 所需元数据的路径
    # 对于生产：
    # tls_letsencrypt_cache_dir: /var/lib/headscale/cache
    tls_letsencrypt_cache_dir: ./cache

    # 使用的 ACME 挑战类型，目前支持的类型：
    # HTTP-01 或 TLS-ALPN-01
    # 详情请见 [docs/tls.md](docs/tls.md)
    tls_letsencrypt_challenge_type: HTTP-01
    # 当选择 HTTP-01 挑战时，letsencrypt 将设置一个
    # 验证端点，并将监听：
    # :http = 80 端口
    tls_letsencrypt_listen: ":http"

    ## 使用已定义的证书：
    tls_cert_path: ""
    tls_key_path: ""

    log:
      # 日志输出格式：文本或 JSON
      format: text
      level: info

    # 包含 ACL 策略的文件路径。
    # ACL 可以定义为 YAML 或 HUJSON。
    # https://tailscale.com/kb/1018/acls/
    acl_policy_path: ""

    ## DNS
    #
    # headscale 支持 Tailscale 的 DNS 配置和 MagicDNS。
    # 请查看 Tailscale 的知识库，以更好地理解这些概念：
    #
    # - https://tailscale.com/kb/1054/dns/
    # - https://tailscale.com/kb/1081/magicdns/
    # - https://tailscale.com/blog/2021-09-private-dns-with-magicdns/
    #
    dns_config:
      # 是否优先使用 Headscale 提供的 DNS 或使用本地 DNS。
      override_local_dns: true

      # 要向客户端公开的 DNS 服务器列表。
      nameservers:
        - 1.1.1.1

      # NextDNS（见 https://tailscale.com/kb/1218/nextdns/）。
      # "abc123" 为示例 NextDNS ID，请替换为你的。
      #
      # 启用元数据共享时：
      # nameservers:
      #   - https://dns.nextdns.io/abc123
      #
      # 无元数据共享：
      # nameservers:
      #   - 2a07:a8c0::ab:c123
      #   - 2a07:a8c1::ab:c123

      # 分离 DNS（见 https://tailscale.com/kb/1054/dns/），
      # 搜索域和针对每个域进行查询的 DNS 列表。
      #
      # restricted_nameservers:
      #   foo.bar.com:
      #     - 1.1.1.1
      #   darp.headscale.net:
      #     - 1.1.1.1
      #     - 8.8.8.8

      # 要注入的搜索域。
      domains: []

      # 额外的 DNS 记录
      # 目前只支持 A 记录（在 Tailscale 端）
      # 请参见 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"
      #
      #   # 也可以将其放在一行中
      #   - { name: "prometheus.myvpn.example.com", type: "A", value: "100.64.0.3" }

      # 是否使用 [MagicDNS](https://tailscale.com/kb/1081/magicdns/)。
      # 仅在定义至少一个 DNS 服务器时有效。
      magic_dns: true

      # 定义为 MagicDNS 创建主机名的基础域。
      # `base_domain` 必须是 FQDN，无需尾部点。
      # 主机的 FQDN 将为
      # `hostname.user.base_domain`（例如，_myhost.myuser.example.com_）。
      base_domain: example.com

    # 为 CLI 连接而使用的 UNIX 套接字，无需身份验证
    # 注意：对于生产环境，你会希望将其设置为类似：
    # unix_socket: /var/run/headscale.sock
    unix_socket: ./headscale.sock
    unix_socket_permission: "0770"
    #
    # headscale 支持实验性的 OpenID 连接支持，
    # 目前仍在测试中，可能会有一些错误，请帮助我们进行测试。
    # 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"
    #   # 或者，设置 `client_secret_path` 从文件中读取密钥。
    #   # 它解析环境变量，使其与 systemd 的
    #   # `LoadCredential` 集成变得简单：
    #   client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
    #   # client_secret 和 client_secret_path 是互斥的。
    #
    #   # 从节点用 OpenID 进行身份验证到过期并需要重新身份验证的时间。
    #   # 将值设置为 "0" 将表示没有过期。
    #   expiry: 180d
    #
    #   # 使用用户登录时从 OpenID 获取的令牌的过期，通常会导致频繁需要重新身份验证，此选项
    #   # 应仅在你知道自己在做什么时启用。
    #   # 注意：启用此选项将忽略 `oidc.expiry`。
    #   use_expiry_from_token: false
    #
    #   # 自定义 OIDC 流程中使用的作用域，默认为 "openid"、"profile" 和 "email"，并添加自定义查询
    #   #  参数到授权端点请求。作用域默认为 "openid"、"profile" 和 "email"。
    #
    #   scope: ["openid", "profile", "email", "custom"]
    #   extra_params:
    #     domain_hint: example.com
    #
    #   # 列出允许的主体域和/或用户。如果经过身份验证的用户的域不在此列表中，将拒绝身份验证请求。
    #
    #   allowed_domains:
    #     - example.com
    #   # 注意：来自 Keycloak 的组前面有一个 '/'。
    #   allowed_groups:
    #     - /headscale
    #   allowed_users:
    #     - [email protected]
    #
    #   # 如果将 `strip_email_domain` 设置为 `true`，则将删除用户名电子邮件地址的域部分。
    #   # 这将把 `[email protected]` 转换为用户 `first-name.last-name`
    #   # 如果将 `strip_email_domain` 设置为 `false`，域部分将不会被删除，结果将是：
    #   用户：`first-name.last-name.example.com`
    #
    #   strip_email_domain: true

    # Logtail 配置
    # Logtail 是 Tailscale 的日志和审计基础设施，允许控制面板指示 Tailscale 节点将其活动日志发送到远程服务器。
    logtail:
      # 为此 headscale 客户端启用 logtail。
      # 目前没有支持重写 headscale 中的日志服务器，因此默认为禁用。启用此选项将使你的客户端将日志发送到 Tailscale Inc.
      enabled: false

    # 启用此选项使设备优先使用随机端口进行 WireGuard 流量，而不是默认静态端口 41641。此选项旨在作为某些存在 Bug 的防火墙设备的解决方法。有关更多信息，请参见 https://tailscale.com/kb/1181/firewalls/
    randomize_client_port: false

  roles:
    - hampusstrom.headscale

标签

install

完整安装和配置 Headscale 及其命名空间。

configure

仅更新配置文件和/或 systemd 单元文件。

users

仅配置命名空间。

许可证

MIT 许可证