Headscale: свой сервер координации Tailscale

Сети и VPN
Headscale: свой сервер координации Tailscale

Headscale установка нужна тем, кто любит клиенты Tailscale, но хочет держать плоскость управления у себя. Это открытая реализация координатора: свой tailscale без облака вендора, без лимита на 3 пользователя и с полным контролем над ключами. В этом гайде поднимем Headscale на VPS, подключим первые узлы и настроим ACL. Всё, что нужно, — небольшой сервер с публичным доступом и 15 минут времени.

Что такое Headscale и зачем он нужен

Tailscale состоит из двух частей: клиентов (демон tailscaled, который вы ставите на устройства) и координационного сервера. Координатор не гоняет трафик — он раздаёт узлам ключи, маршруты и правила, помогает им найти друг друга и пробить NAT. Сам трафик идёт напрямую между устройствами по WireGuard.

Headscale заменяет только эту управляющую часть. Клиенты остаются официальные, а «мозг» сети переезжает на ваш сервер. Это даёт несколько плюсов:

  • Нет привязки к аккаунту и лимитам бесплатного тарифа Tailscale.
  • Ключи и логи подключений остаются у вас.
  • Можно поднять сеть в изолированном контуре, где облако вендора недоступно.

Минус честный: вы сами отвечаете за доступность координатора и его бэкапы. Если сервер с Headscale упадёт, новые узлы не подключатся, хотя уже установленные соединения продолжат работать какое-то время.

Требования и выбор сервера

Headscale нетребователен к ресурсам. Он написан на Go, работает одним бинарником и спокойно живёт на самой скромной машине. Для координатора на 10-50 узлов хватит небольшого NAT VPS: нагрузка на CPU близка к нулю, память измеряется десятками мегабайт.

Ключевой момент — координатору нужен стабильный публичный вход по HTTPS. Клиенты подключаются к нему по доменному имени, поэтому понадобится домен и валидный TLS-сертификат. Порт по умолчанию — 8080 для API и 443 для входящих HTTPS, плюс UDP-порт для DERP, если поднимаете свой релей.

Что нужноЗначение
ОСDebian 12 / Ubuntu 22.04+
RAMот 512 МБ
Доменобязательно (для TLS)
Порты443/TCP, 3478/UDP (STUN, опционально)
Праваroot или sudo

Для домашней лаборатории и небольшой команды отлично подходит NAT VPS с пробросом портов: координатору достаточно проброшенного 443-го порта. Если планируете держать в этой же сети exit-node, посмотрите отдельный разбор про Tailscale exit node на VPS.

Установка Headscale

Ставим свежий релиз из официальных deb-пакетов. Сначала узнаём последнюю версию на странице релизов проекта, затем скачиваем пакет под свою архитектуру.

# скачиваем deb-пакет (подставьте актуальную версию и arch)
VER="0.23.0"
wget https://github.com/juanfont/headscale/releases/download/v${VER}/headscale_${VER}_linux_amd64.deb

# устанавливаем
sudo apt install ./headscale_${VER}_linux_amd64.deb

Пакет кладёт бинарник в /usr/bin/headscale, конфиг в /etc/headscale/config.yaml и готовый unit для systemd. Проверим, что бинарник на месте:

headscale version

Если предпочитаете ручную установку без пакета, можно просто скачать бинарник, положить его в /usr/local/bin и создать systemd-юнит самостоятельно. Deb-пакет удобнее тем, что делает это за вас.

Конфигурация координатора

Открываем /etc/headscale/config.yaml. Разберём ключевые параметры, которые точно надо поправить под себя.

# адрес, по которому клиенты будут находить координатор
server_url: https://vpn.example.com

# на каком интерфейсе слушать (0.0.0.0 — все)
listen_addr: 0.0.0.0:8080

# метрики Prometheus, можно оставить на localhost
metrics_listen_addr: 127.0.0.1:9090

# диапазоны адресов для tailnet
prefixes:
  v4: 100.64.0.0/10
  v6: fd7a:115c:a1e0::/48

# DNS для узлов сети
dns:
  base_domain: tailnet.example.com
  magic_dns: true
  nameservers:
    global:
      - 1.1.1.1
      - 8.8.8.8

Обратите внимание на server_url: это ровно тот адрес, который потом укажут клиенты в --login-server. Он должен совпадать с доменом, на который выписан TLS-сертификат.

Хранилище по умолчанию — SQLite, и для большинства сценариев этого достаточно. База лежит в /var/lib/headscale/db.sqlite. Для крупных сетей поддерживается PostgreSQL, но начинать с SQLite проще и надёжнее.

TLS: получаем сертификат

Headscale умеет сам запрашивать сертификат Let's Encrypt, но на практике удобнее и надёжнее поставить перед ним обратный прокси. Возьмём Nginx: он терминирует HTTPS и проксирует запросы на локальный 8080.

server {
    listen 443 ssl;
    server_name vpn.example.com;

    ssl_certificate     /etc/letsencrypt/live/vpn.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/vpn.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Real-IP $remote_addr;
        proxy_buffering off;
    }
}

Заголовки Upgrade и Connection обязательны: Headscale держит долгоживущие соединения с узлами, и без правильного проксирования WebSocket-подобных стримов узлы будут постоянно переподключаться. Сертификат получаем стандартно через certbot:

sudo apt install certbot
sudo certbot certonly --standalone -d vpn.example.com

Запускаем сам Headscale через systemd и проверяем статус:

sudo systemctl enable --now headscale
sudo systemctl status headscale

Первый пользователь и подключение узла

Headscale группирует узлы по пользователям (namespace). Создаём пользователя:

sudo headscale users create alice

Теперь подключаем клиента. На устройстве с установленным Tailscale запускаем tailscale up, указывая наш координатор:

sudo tailscale up --login-server https://vpn.example.com

Клиент выведет URL с командой регистрации. Копируем ключ из этой ссылки и регистрируем узел на сервере:

sudo headscale nodes register --user alice --key <ключ-из-браузера>

После регистрации узел появится в списке. Проверить состояние сети можно так:

sudo headscale nodes list

Чтобы не регистрировать каждый узел вручную, удобнее выпустить preauth-ключ. Он позволяет узлам подключаться автоматически — полезно для серверов и CI.

# ключ на 24 часа, многоразовый
sudo headscale preauthkeys create --user alice --reusable --expiration 24h

Дальше на клиенте просто передаём его в --authkey:

sudo tailscale up --login-server https://vpn.example.com --authkey <preauth-ключ>

Маршруты и ACL

Одна из сильных сторон Tailscale — subnet routes: один узел может анонсировать целую подсеть, давая доступ к устройствам, на которые сам Tailscale не поставить. На клиенте это выглядит так:

sudo tailscale up --login-server https://vpn.example.com \
  --advertise-routes=192.168.1.0/24

Анонсированный маршрут надо одобрить на координаторе, иначе он не заработает:

sudo headscale nodes list-routes
sudo headscale nodes approve-routes --identifier 1 --routes 192.168.1.0/24

Доступ между узлами регулируется ACL-политикой. По умолчанию все видят всех, но в проде это лучше ограничить. Политика описывается в JSON/HuJSON и подключается в конфиге через policy.path.

policy:
  mode: file
  path: /etc/headscale/acl.json

Пример простой политики: группа admins ходит куда угодно, остальные — только к веб-серверам по 443.

{
  "groups": {
    "group:admins": ["alice"]
  },
  "acls": [
    { "action": "accept", "src": ["group:admins"], "dst": ["*:*"] },
    { "action": "accept", "src": ["*"], "dst": ["tag:web:443"] }
  ]
}

После правки политики перезапустите сервис, чтобы правила применились.

Бэкапы и обслуживание

Всё состояние Headscale — это файл конфига, база SQLite и приватные ключи. Регулярный бэкап этих трёх вещей полностью восстанавливает координатор на новом сервере.

# останавливаем на время снимка, чтобы БД была консистентной
sudo systemctl stop headscale
sudo tar czf headscale-backup-$(date +%F).tar.gz \
  /etc/headscale/ /var/lib/headscale/
sudo systemctl start headscale

Держите этот архив вне сервера — например, копируйте его на другую машину по SSH. Если вам нужен надёжный удалённый узел для хранения бэкапов и одновременно точка входа в сеть, разберитесь с темой доступа к домашнему ПК через VPS: те же принципы работают и для сервера с бэкапами.

Частые вопросы

Чем Headscale отличается от WireGuard напрямую?

WireGuard — это транспорт: он шифрует и гоняет трафик, но не умеет сам находить пиров и раздавать ключи. Headscale добавляет плоскость управления: автообнаружение узлов, пробивку NAT, MagicDNS и ACL. Под капотом трафик всё равно идёт по WireGuard. Если вам нужна ручная точечная настройка без координатора, посмотрите разбор WireGuard на VPS.

Нужен ли Headscale публичный IP?

Нужен стабильный публичный вход по HTTPS, но это не обязательно выделенный IP. NAT VPS с проброшенным 443-м портом и доменом справляется: клиенты обращаются к координатору по имени, а не по адресу. Главное, чтобы порт был доступен снаружи и на домене был валидный сертификат.

Работает ли своя сеть, если координатор упадёт?

Уже установленные соединения между узлами продолжат жить какое-то время, потому что трафик идёт напрямую. Но новые узлы подключиться не смогут, обновления маршрутов и ACL не разъедутся, а истёкшие ключи не переоформятся. Поэтому координатор стоит держать на сервере с хорошим аптаймом и делать бэкапы.

Можно ли использовать официальные приложения Tailscale?

Да, десктопные и мобильные клиенты работают с Headscale, если в них можно указать custom login server. На десктопе это делается флагом --login-server, на мобильных — через настройку альтернативного сервера в приложении. Совместимость зависит от версии клиента, поэтому держите их относительно свежими.

Сколько ресурсов ест Headscale?

Очень мало. Для сети до нескольких десятков узлов достаточно 512 МБ RAM и минимальной доли CPU: координатор не проксирует трафик, а лишь обслуживает управляющие запросы. Диск тратится в основном на базу SQLite, которая для небольшой сети остаётся в пределах мегабайтов.

Итог

Свой координатор снимает зависимость от облака и лимитов, а стоит недорого: Headscale прекрасно живёт на маленьком сервере. Для координатора на несколько десятков узлов возьмите тариф NAT Base за 99₽/мес — общий IPv4, проброс нужных TCP/UDP портов и выдача сервера за минуту. Поднимите координатор один раз и управляйте всей своей mesh-сетью без чужих серверов между вами и вашими устройствами.

Читайте также