headscale
Ansible Роль: 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
Необходимы права суперпользователя: да
Поскольку требуется root, используйте эту роль в плейбуке, который имеет глобально определённый 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.
Latest автоматически извлечет последнюю метку релиза из juanfont/headscale репозитория GitHub.
по умолчанию: latest
headscale_config
Содержимое файла конфигурации headscale config.yaml, выраженное как объект yaml. Проверьте стандартную конфигурацию в проекте headscale для вдохновения. На момент написания следующие минимальные значения требуются для версии 0.20.0 headscale.
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
Определяет пользователя/repo, которые будут использоваться при поиске и скачивании бинарного файла 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.
по умолчанию: 777
headscale_user_gid
Определяет идентификатор группы группы headscale_user_group.
по умолчанию: {{ headscale_user_uid }}
headscale_etc_dir_path
Определяет путь, в котором должны находиться конфигурационные данные headscale. Вы обычно не должны изменять это, но опция есть для некоторых пользовательских конфигураций/форков.
по умолчанию: /etc/headscale
headscale_lib_dir_path
Определяет путь, в котором должны находиться библиотеки headscale. Вы обычно не должны изменять это, но опция есть для некоторых пользовательских конфигураций/форков.
по умолчанию: /var/lib/headscale
headscale_run_dir_path
Определяет путь, в котором должен находиться UNIX-сокет headscale. Вы обычно не должны изменять это, но опция есть для некоторых пользовательских конфигураций/форков. Параметр конфигурации 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, скопируйте файл базы данных в 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_listen_addr: 127.0.0.1:9090
# Адрес для прослушивания gRPC.
# gRPC используется для удалённого управления сервером headscale
# с помощью CLI
# Примечание: удаленный доступ _только_ работает, если у вас есть
# действительные сертификаты.
#
# Для производственной версии:
# 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 используется для шифрования
# трафика между headscale и клиентами Tailscale при
# использовании нового протокола на основе Noise. Он должен отличаться
# от обычного закрытого ключа.
#
# Для производственной версии:
# private_key_path: /var/lib/headscale/noise_private.key
private_key_path: ./noise_private.key
# Список префиксов IP для аллокации tailaddresses.
# Каждый префикс состоит либо из IPv4, либо из IPv6,
# и связанной длины префикса, разделенной косой чертой.
# Хотя это выглядит так, будто это может принимать произвольные значения, это
# должно быть в пределах поддерживаемых диапазонов IP клиентом Tailscale.
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
# URL сервера Headscale, определяемый выше, должен использовать https, DERP требует наличия TLS
enabled: false
# Идентификатор региона для использования встроенного DERP-сервера.
# Локальный DERP преобладает, если идентификатор региона совпадает с другим идентификатором региона из
# регулярной конфигурации DERP.
region_id: 999
# Код региона и название отображаются в интерфейсе Tailscale для идентификации региона DERP
region_code: "headscale"
region_name: "Headscale Embedded DERP"
# Слушает по UDP на настроенном адресе для STUN-подключений - чтобы помочь с транзитом через NAT.
# Когда встроенный DERP-сервер включен, stun_listen_addr ДОЛЖЕН быть определён.
#
# Для получения дополнительной информации о том, как это работает, ознакомьтесь с этой отличной статьёй: https://tailscale.com/blog/how-tailscale-works/
stun_listen_addr: "0.0.0.0:3478"
# Список доступных DERP-карт, закодированных в JSON
urls:
- https://controlplane.tailscale.com/derpmap/default
# Локально доступные файлы карт DERP, закодированные в YAML
#
# Эта опция в основном интересует людей, размещающих
# свои собственные 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. Слишком низкое значение значительно повлияет на
# потребление CPU Headscale. Слишком высокое значение (более 60 секунд) может вызвать проблемы
# для нод, поскольку они не будут получать обновления или сообщения о жизнеспособности достаточно часто.
# В случае сомнений не трогайте стандартные 10 секунд.
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)', установите необходимый 'sslmode' в поле 'db_ssl'. Ссылается на https://www.postgresql.org/docs/current/libpq-ssl.html таблицу 34.1.
# db_ssl: false
### Конфигурация TLS
#
## Let's Encrypt / ACME
#
# headscale поддерживает автоматическую заявку и настройку
# TLS для домена с Let's Encrypt.
#
# URL для директории ACME
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 поддерживает настройку DNS Tailscale и MagicDNS.
# Пожалуйста, ознакомьтесь с их базой знаний, чтобы лучше понять концепции:
#
# - https://tailscale.com/kb/1054/dns/
# - https://tailscale.com/kb/1081/magicdns/
# - https://tailscale.com/blog/2021-09-private-dns-with-magicdns/
#
dns_config:
# Предпочитать использование DNS, предоставляемого Headscale, или локального.
override_local_dns: true
# Список DNS-серверов, выставляемых клиентам.
nameservers:
- 1.1.1.1
# NextDNS (см. https://tailscale.com/kb/1218/nextdns/).
# "abc123" — пример ID NextDNS, замените на свой.
#
# С совместным использованием метаданных:
# 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/).
# Работает только если определён хотя бы один nameserver.
magic_dns: true
# Определяет основной домен для создания имен хостов для MagicDNS.
# `base_domain` должен быть FQDN, без завершающей точки.
# FQDN хостов будет
# `hostname.user.base_domain` (например, _myhost.myuser.example.com_).
base_domain: example.com
# Unix-сокет, используемый для подключения CLI без аутентификации
# Примечание: для производственной версии вам потребуется установить это на что-то вроде:
# unix_socket: /var/run/headscale.sock
unix_socket: ./headscale.sock
unix_socket_permission: "0770"
#
# headscale поддерживает экспериментальную поддержку OpenID connect,
# она всё ещё тестируется и может иметь некоторые ошибки, пожалуйста,
# помогите нам протестировать это.
# 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's
# # `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:
# Включить logtail для этих клиентов headscale.
# Поскольку в headscale в настоящее время нет поддержки переопределения сервера журнала, это
# по умолчанию отключено. Включение этого заставит ваших клиентов отправлять журналы в Tailscale Inc.
enabled: false
# Включение этой опции заставляет устройства предпочитать случайный порт для трафика WireGuard вместо
# стандартного статического порта 41641. Эта опция предназначена как обходное решение для некоторых неправильных
# сетевых устройств. См. https://tailscale.com/kb/1181/firewalls/ для получения дополнительной информации.
randomize_client_port: false
roles:
- hampusstrom.headscale
Теги
install
Полная установка и конфигурация headscale и его пространств имен.
configure
Только обновляет файл конфигурации и/или файл юнита systemd.
users
Только настраивает пространства имен.
Лицензия
MIT Лицензия
Deploys Headscale, An open source, self-hosted implementation of the Tailscale control server.
ansible-galaxy install hampusstrom/ansible-role-headscale