Webfactor VPN Network

Пълна документация за нашата self-hosted mesh VPN мрежа

Какво е Headscale?

Headscale е open-source, self-hosted имплементация на Tailscale координатора. Tailscale е mesh VPN базиран на WireGuard, който позволява на всички машини в мрежата да комуникират директно помежду си, без да минават през централен сървър.

Tailscale vs Headscale

Архитектура

Важно: Координаторът (Headscale на s13) НЕ рутира трафик. Той само казва на машините как да се намерят една друга. След това комуникацията е директна (peer-to-peer) по WireGuard тунели. Ако s13 падне, вече свързаните машини продължават да работят помежду си.

Информация за мрежата

Бързи линкове

Бързо присъединяване

curl -sL https://vpn.s13.webfactor.com/join.sh | sudo bash -s -- <hostname>

Генериране на auth key

Auth key се генерира на s13 (координатора). SSH до s13:

# Еднократен ключ (валиден 1 час)
docker exec headscale headscale preauthkeys create --user 1 --expiration 1h

# Многократен ключ (за няколко машини)
docker exec headscale headscale preauthkeys create --user 1 --reusable --expiration 24h

# Ключ за ephemeral nodes (автоматично се махат при disconnect)
docker exec headscale headscale preauthkeys create --user 1 --ephemeral --expiration 1h

# Виж всички ключове
docker exec headscale headscale preauthkeys list --user 1

Linux

Автоматично (с join.sh)

curl -sL https://vpn.s13.webfactor.com/join.sh | sudo bash -s -- my-server

Ръчно

# Debian / Ubuntu
curl -fsSL https://tailscale.com/install.sh | sh

# Fedora / CentOS / RHEL
curl -fsSL https://tailscale.com/install.sh | sh

# Arch Linux
sudo pacman -S tailscale

# Alpine
sudo apk add tailscale

sudo systemctl enable --now tailscaled

sudo tailscale up \
    --login-server https://head.webfactor.com \
    --authkey <auth-key> \
    --hostname <hostname> \
    --accept-routes \
    --accept-dns

tailscale status
ping s13.webfactor.internal

macOS

CLI (препоръчително)

brew install tailscale
sudo tailscaled &
sudo tailscale up --login-server https://head.webfactor.com --authkey KEY --hostname my-mac

GUI App

1. Инсталирай Tailscale от App Store
2. Отвори приложението
3. Отиди на Settings > Use an alternate server
4. Въведи: https://head.webfactor.com
5. Ще се отвори браузър за регистрация

docker exec headscale headscale nodes list
docker exec headscale headscale nodes register --user 1 --key <nodekey:xxx>

Windows

& "C:\Program Files\Tailscale\tailscale.exe" up --login-server https://head.webfactor.com --authkey KEY --hostname my-pc

iOS / Android

1. Инсталирай Tailscale от App Store / Google Play
2. Отвори приложението
3. Натисни три точки (...) или Settings
4. Намери "Use an alternate server" или "Custom coordination server"
5. Въведи: https://head.webfactor.com
6. Ще се отвори уеб страница - одобри регистрацията от s13

Docker контейнери

За да свържеш Docker контейнер към VPN мрежата:

# docker-compose.yml пример
services:
  my-app:
    image: my-app:latest
    network_mode: "service:tailscale"

  tailscale:
    image: tailscale/tailscale:latest
    hostname: my-app-ts
    environment:
      - TS_AUTHKEY=<auth-key>
      - TS_EXTRA_ARGS=--login-server=https://head.webfactor.com --hostname=my-app
      - TS_STATE_DIR=/var/lib/tailscale
    volumes:
      - ts-state:/var/lib/tailscale
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - net_admin
      - sys_module
    restart: unless-stopped

volumes:
  ts-state:

Headplane Web UI

Headplane позволява:

• Преглед на всички свързани машини и техния статус
• Преименуване и изтриване на машини
• Управление на маршрути (routes)
• Настройка на DNS записи
• Редактиране на ACL политики
• Рестартиране на Headscale

CLI команди (на s13)

Машини (Nodes)

# Списък машини
docker exec headscale headscale nodes list

# Подробна информация за машина
docker exec headscale headscale nodes list -o json

# Изтрий машина
docker exec headscale headscale nodes delete --identifier <ID>

# Преименувай машина
docker exec headscale headscale nodes rename <ID> new-name

# Регистрирай машина ръчно (без auth key)
docker exec headscale headscale nodes register --user 1 --key nodekey:xxxx

# Expire (принуди ре-автентикация)
docker exec headscale headscale nodes expire --identifier <ID>

Auth ключове

# Създай еднократен ключ
docker exec headscale headscale preauthkeys create --user 1 --expiration 1h

# Създай многократен ключ
docker exec headscale headscale preauthkeys create --user 1 --reusable --expiration 24h

# Списък ключове
docker exec headscale headscale preauthkeys list --user 1

API ключове

# Създай API ключ (за Headplane или API достъп)
docker exec headscale headscale apikeys create --expiration 9999d

# Списък API ключове
docker exec headscale headscale apikeys list

Потребители

# Списък потребители
docker exec headscale headscale users list

# Създай нов потребител
docker exec headscale headscale users create <name>

# Изтрий потребител
docker exec headscale headscale users destroy <ID>

# Преименувай
docker exec headscale headscale users rename <ID> new-name

ACL (Access Control)

ACL политиките определят коя машина с коя може да комуникира. Без ACL, всички машини на един потребител имат пълен достъп помежду си.

# Пример ACL политика (JSON)
{
  "acls": [
    {
      "action": "accept",
      "src": ["admin"],
      "dst": ["admin:*"]
    }
  ]
}

ACL може да се управлява от Headplane UI или чрез API.

Exit nodes и маршрути

Всяка машина може да обяви маршрути (routes) или да бъде exit node:

# Обяви маршрут (напр. цяла подмрежа)
sudo tailscale set --advertise-routes=192.168.1.0/24

# Направи машината exit node (целият трафик минава през нея)
sudo tailscale set --advertise-exit-node

# Одобри маршрут от s13
docker exec headscale headscale routes list
docker exec headscale headscale routes enable -r <route-id>

Как работи MagicDNS

MagicDNS позволява достъп до всяка машина по име вместо по IP адрес.

DNS имена

# Провери DNS от всяка свързана машина
tailscale status                    # виж всички машини
ping s13.webfactor.internal         # пинг по пълно име
ping s13                            # пинг по кратко име
nslookup s13.webfactor.internal     # DNS lookup

Claude Code интеграция

# Стъпка 1: Инсталирай Tailscale
curl -fsSL https://tailscale.com/install.sh | sh
systemctl enable --now tailscaled

# Стъпка 2: Свържи се (замени AUTH_KEY и HOSTNAME)
tailscale up \
    --login-server https://head.webfactor.com \
    --authkey AUTH_KEY \
    --hostname HOSTNAME \
    --accept-routes --accept-dns

# Стъпка 3: Провери
tailscale status

curl -sL https://vpn.s13.webfactor.com/join.sh | AUTHKEY=KEY bash -s -- HOSTNAME

Скриптове

join.sh

Автоматичен скрипт за присъединяване: /join.sh

# Интерактивен режим
curl -sL https://vpn.s13.webfactor.com/join.sh | sudo bash -s -- my-server

# С auth key като environment variable
curl -sL https://vpn.s13.webfactor.com/join.sh | sudo AUTHKEY=hskey-auth-xxx bash -s -- my-server

API

Headscale има REST API достъпно на https://head.webfactor.com/api/v1/

# Примерна заявка
API_KEY="hskey-api-xxx"

# Списък машини
curl -s -H "Authorization: Bearer $API_KEY" \
    https://head.webfactor.com/api/v1/node | python3 -m json.tool

# Списък потребители
curl -s -H "Authorization: Bearer $API_KEY" \
    https://head.webfactor.com/api/v1/user | python3 -m json.tool

# Създай preauthkey
curl -s -X POST -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"user":"1","reusable":true,"expiration":"2026-02-09T00:00:00Z"}' \
    https://head.webfactor.com/api/v1/preauthkey | python3 -m json.tool

Проблеми и решения

sudo chattr -i /etc/resolv.conf
sudo systemctl restart tailscaled
sudo tailscale up --login-server https://head.webfactor.com --accept-dns

sudo tailscale set --hostname new-name

# На самата машина:
sudo tailscale logout

# От s13 (изтрий напълно):
docker exec headscale headscale nodes delete --identifier <ID>

Логове

# Headscale логове
docker logs headscale --tail 50 -f

# Headplane логове
docker logs headplane --tail 50 -f

# Tailscale клиент логове (на всяка машина)
journalctl -u tailscaled -f

# Tailscale debug info
tailscale bugreport

Backup

# Backup на Headscale данни
cp -a /opt/apps/headscale /opt/apps/headscale-backup-$(date +%Y%m%d)

# Важни файлове за backup:
# /opt/apps/headscale/data/db.sqlite     - базата данни
# /opt/apps/headscale/data/noise_private.key - private key
# /opt/apps/headscale/config/config.yaml  - конфигурация

Обновяване

# 1. Backup
cp -a /opt/apps/headscale /opt/apps/headscale-backup-$(date +%Y%m%d)

# 2. Смени версията в docker-compose.yml
#    image: headscale/headscale:v0.28.0 -> v0.29.0

# 3. Pull и рестартирай
cd /opt/apps
docker compose pull headscale
docker compose up -d headscale

# 4. Провери
docker exec headscale headscale version
docker exec headscale headscale nodes list

Файлове и пътища (на s13)

Портове

Полезни команди

# === На всяка свързана машина ===
tailscale status                # статус и списък peers
tailscale ip                    # моят VPN IP
tailscale ping <host>           # пинг до друга машина
tailscale netcheck              # мрежова диагностика
tailscale whois <ip>            # кой е на този IP
tailscale set --hostname <name> # смени hostname
tailscale down                  # временно изключи VPN
tailscale up                    # включи обратно
tailscale logout                # напусни мрежата

# === На s13 (координатора) ===
docker exec headscale headscale nodes list          # всички машини
docker exec headscale headscale users list           # всички потребители
docker exec headscale headscale preauthkeys create --user 1 --expiration 1h  # нов auth key
docker exec headscale headscale routes list          # маршрути
docker logs headscale --tail 20                      # последни логове