Triển khai Headscale Mesh VPN
Mesh VPN nội bộ — kết nối an toàn mọi VM qua Tailscale protocol.
Bối cảnh & Lý do triển khai
Mô hình truyền thống mở port VPN ra internet tạo attack surface lớn. Headscale (control plane của Tailscale) dùng WireGuard mesh: mỗi thiết bị kết nối trực tiếp P2P qua UDP, không cần server trung gian. Admin có thể quản trị toàn bộ lab từ điện thoại ở bất kỳ đâu mà không lo bị scan/tấn công.
| Mục | Nội dung |
|---|---|
| Ứng dụng trong DN | Remote work cho IT admin, site-to-site VPN giữa văn phòng/chi nhánh, zero-trust network access |
| Tác dụng chính | WireGuard mesh VPN, subnet route expose toàn bộ 10.11.0.0/16, policy (ACL/grants) theo user và tag, multi-platform |
| Nếu không triển khai | Phải mở port ra internet (nguy hiểm) hoặc không có remote access vào lab |
| Các service phụ thuộc vào đây | Admin tools, remote troubleshooting; đăng nhập người dùng qua OIDC Authentik (bài 14, tùy chọn) |
Ngày cập nhật: 2026-10-15 (hệ điều hành Ubuntu Server 24.04 LTS; phiên bản phần mềm đã xác minh ngày 2026-10-15, xem bảng "Phiên bản phần mềm sử dụng" ở mục 1)
Người thực hiện: hoatv
Môi trường: HOATRANLABS – PVE 9.2.20
Danh sách máy chủ & IP liên quan
Bảng dưới liệt kê các máy chủ mà bài này tạo hoặc kết nối tới. Địa chỉ, VMID, VLAN và node lấy từ bảng quy hoạch chung của lab, dùng thống nhất cho cả bộ bài lab.
| Máy chủ | IP | VLAN · Node | Vai trò trong bài này |
|---|---|---|---|
| headscale (Headscale VPN) · VM232 | 10.11.35.10 | 35 (DMZ) · node2 | Máy chủ của bài — Headscale 0.29.5 chạy Docker Compose sau Nginx TLS: HTTPS cổng 443, metrics cổng 9090; không cần cổng UDP vì client kết nối P2P hoặc qua DERP công cộng. |
| node2 (Proxmox VE) | 10.11.45.211 | 45 (MGMT) · cluster HOATRANHUB | Node Proxmox chứa VM232; tạo VM tại đây. |
| FortiGate (firewall) | 10.100.100.1 | Quản trị 10.100.100.0/24 · thiết bị mạng | Port forward WAN vào Headscale (VIP TCP 443, thêm VIP 80 cho cert Let's Encrypt) kèm policy Allow-Headscale-Inbound; policy Allow-Prometheus-Headscale lọc nguồn cổng 9090 (mục 3, 13.2). |
| step-ca (step-CA PKI) · VM242 | 10.11.25.42 | 25 (SEC) · node1 | Cấp chứng chỉ TLS cho tên nội bộ headscale.hoatranlabs.local bằng step ca certificate, gia hạn qua systemd timer; tên public dùng Let's Encrypt, không dùng step-CA (bài 13). |
| pihole (Pi-hole DNS) · VM247 | 10.11.45.53 | 45 (MGMT) · node3 | DNS nội bộ cho client VPN qua split DNS hoatranlabs.local; chứa bản ghi headscale.hoatranlabs.local về 10.11.35.10 (bài 12). |
| prometheus (Prometheus + Alertmanager) · VM235 | 10.11.45.35 | 45 (MGMT) · node2 | Scrape job headscale tại cổng 9090 (/metrics); Docker bỏ qua UFW nên FortiGate chỉ cho Prometheus từ VLAN_MGMT sang VLAN_DMZ (bài 15). |
| authentik (Authentik SSO) · VM234 | 10.11.25.40 | 25 (SEC) · node1 | Đăng nhập người dùng qua OIDC là tùy chọn; khối oidc trong config.yaml trỏ tới cổng 9443, để comment và bật theo mục 6.3 (bài 14). |
| pbs01 (PBS Primary) · VM101 | 10.11.45.17 | 45 (MGMT) · node4 | Nhận sao lưu file-level từ VM232 (token vm-backup@pbs!headscale, namespace vm-headscale, datastore syno-primary) theo bài 04 mục 5.7. |
| ops01 (Ansible/OpenTofu + bastion) · VM290 | 10.11.45.20 | 45 (MGMT) · node2 | Ví dụ VM làm subnet router quảng bá toàn bộ dải lab (mục 10); đã nằm trong mgmt-admins của bài 05 (bài 07). |
Gateway của mỗi VLAN là địa chỉ .1. Tên DNS nội bộ do Pi-hole phân giải (bài 12). Tên in đậm là hostname; FQDN = hostname + .hoatranlabs.local.
Tổng quan
Headscale là implementation mã nguồn mở của Tailscale control plane. Thay vì phụ thuộc vào cloud của Tailscale, toàn bộ server điều phối VPN mesh nằm trong hạ tầng nội bộ.
Kiến trúc hoạt động:
[Laptop nhân viên] ──Tailscale client──► [Headscale VM232]
│
┌────────────────┤
│ │
WireGuard tunnel DNS + Routes
│ │
[HOATRANLABS Lab] [10.11.0.0/16]
- Headscale quản lý key exchange, node registration, policy (ACL/grants) và route
- Data plane: WireGuard peer-to-peer trực tiếp giữa các nodes (không qua server; khi NAT chặn thì đi qua DERP relay)
- Không cần public IP trực tiếp trên VM — FortiGate forward port vào
- Clients dùng Tailscale app (Windows/macOS/Linux/iOS/Android) — không cần cài gì đặc biệt
Thông số VM:
| Thuộc tính | Giá trị |
|---|---|
| VMID | 232 |
| Hostname | headscale |
| Node | node2 (10.11.45.211) |
| VLAN | VLAN_DMZ tag=35 |
| IP | 10.11.35.10/24 |
| Gateway | 10.11.35.1 |
| DNS | 10.11.45.53 (Pi-hole) |
| vCPU | 2 |
| RAM | 2 GB |
| Disk | 20 GB (vm-ceph) |
| OS | Ubuntu Server 24.04 LTS (24.04.5) |
Phương án triển khai:
| Phương án | Cách chạy Headscale | Khi nào chọn | Ghi chú |
|---|---|---|---|
| Docker Compose (khuyến nghị, bài này làm theo cách này) | Image docker.io/headscale/headscale:0.29.5 chạy bằng Docker Engine + Compose plugin trên VM232; Nginx và cert step-CA chạy trên host (mục 5.1 – 5.3) | Mặc định của series cho dịch vụ có image: ghim tag, nâng cấp từng minor chỉ cần đổi tag, dữ liệu nằm ở bind mount /etc/headscale và /var/lib/headscale nên PBS in-VM sao lưu trực tiếp (mục 16) | Dự án Headscale chỉ hỗ trợ chính thức binary và gói DEB; trang hướng dẫn container trên headscale.net là tài liệu cộng đồng (FAQ: "we don't officially support deploying headscale using Docker"). Image do chính dự án phát hành trên Docker Hub và GHCR |
Gói .deb + systemd | apt install ./headscale_0.29.5_linux_amd64.deb, dịch vụ headscale.service (mục 5.4) | Muốn đúng cách "recommended" của tài liệu Headscale, hoặc không muốn cài Docker trên VM | Gói tạo user headscale và unit systemd có hardening; CLI chạy trực tiếp. Dùng chung đường dẫn dữ liệu với phương án Docker nên chuyển qua lại chỉ cần dừng phương án này, chạy phương án kia (và chown lại thư mục dữ liệu) |
| LXC không đặc quyền | Container LXC Ubuntu 24.04 (pct create ... --unprivileged 1, rootfs trên vm-ceph) cài gói .deb | Muốn nhẹ hơn VM; control plane là một tiến trình Go, không cần /dev/net/tun và không cần Docker (Docker không chạy trong LXC theo khuyến nghị Proxmox) | Không cài Tailscale client trong cùng container (Headscale ghi rõ không hỗ trợ chạy chung với Tailscale trên một máy). Bài giữ VM232 nên không trình bày từng bước tạo CT |
db.sqlite + config trước mỗi bước và rà lại cấu hình/lệnh theo ghi chú từng bản. Xem mục 5.5.
Phiên bản phần mềm sử dụng (đã xác minh ngày 2026-10-15; số bản sẽ tăng theo thời gian, bài ghi lại bản đã kiểm để các bước khớp nhau):
| Thành phần | Phiên bản | Ghi chú |
|---|---|---|
| Ubuntu Server | 24.04.5 LTS (noble) | ISO ubuntu-24.04.5-live-server-amd64.iso (https://releases.ubuntu.com/24.04/); hỗ trợ chuẩn tới 04/2029 |
| Headscale | 0.29.5 (phát hành 2026-10-13, bản stable mới nhất) | Image docker.io/headscale/headscale:0.29.5 (tag có trên Docker Hub) hoặc gói headscale_0.29.5_linux_amd64.deb; gói .deb hỗ trợ Ubuntu 22.04 trở lên nên chạy được trên 24.04. Client Tailscale tối thiểu v1.80.0. Nhánh 0.30.0 chưa phát hành, bài không dùng. Nguồn: https://github.com/juanfont/headscale/releases và https://headscale.net/stable/ |
| Docker Engine + Compose | Docker 29.9.1, Compose plugin 5.6.0 (kho download.docker.com/linux/ubuntu, suite noble) | Bản stable mới nhất trong kho noble lúc kiểm (cùng bản ở bài 19); dùng lệnh docker compose |
| Nginx | 1.24.0 (kho Ubuntu noble) | Dùng listen 443 ssl http2; (http2 on; cần Nginx 1.25.1 trở lên) |
| step-cli | 0.31.0 | Gói .deb từ GitHub smallstep/cli |
| Tailscale client | 1.104.1 (kho pkgs.tailscale.com/stable/ubuntu, suite noble) | Bản stable mới nhất lúc kiểm; Windows, macOS, iOS, Android lấy bản mới nhất từ https://tailscale.com/download hoặc cửa hàng ứng dụng |
| certbot | 2.9.0 (kho Ubuntu noble) | Chỉ dùng cho tên public ở mục 13.2 |
| proxmox-backup-client | proxmox-backup-client-static từ repo pbs-client (suite trixie) | Cách cài chuẩn của series trên Ubuntu 24.04 (mục 16); chạy trên noble cần kiểm lại trên máy thật |
| node_exporter | 1.12.1 | Cài bằng script ở bài 15 |
Ports:
| Port | Protocol | Mục đích |
|---|---|---|
| 443 | TCP | HTTPS control plane (qua Nginx trên host) |
| 80 | TCP | Nginx: chuyển hướng sang HTTPS, /generate_204, thử thách HTTP-01 của Let's Encrypt cho tên public (mục 13.2) |
| 8080 | TCP | Headscale HTTP: container chỉ publish ở 127.0.0.1 để Nginx proxy vào |
| 9090 | TCP | Prometheus metrics (container publish ở 10.11.35.10; chỉ cho Prometheus VM235 10.11.45.35, lọc nguồn ở FortiGate, mục 3.3 và 14.1) |
| 50443 | TCP | gRPC của CLI từ xa: chỉ nghe localhost trong container, KHÔNG publish; CLI cục bộ dùng unix socket |
| 3478 | UDP | STUN, chỉ cần khi bật DERP nhúng (mục 6.4); bài này dùng DERP công cộng nên không mở |
derp.server.enabled), còn bài này dùng DERP công cộng của Tailscale.
Tạo VM trên Proxmox
Tạo VM trên Proxmox · Khởi động và cài Ubuntu · Cấu hình sau cài xong
2.1 Tạo VM trên Proxmox
Cách 1: Web UI Proxmox (GUI)
- VM ID:
232 - Name:
headscale - Bỏ tick Start after created
- Storage:
local(hoặc nơi chứa ISO) - ISO Image:
ubuntu-24.04.5-live-server-amd64.iso - Guest OS Type:
Linux, Version:6.x - 2.6 Kernel
- Machine:
q35 - SCSI Controller:
VirtIO SCSI single - BIOS:
SeaBIOS - Qemu Agent: ☑
- Bus/Device:
SCSI 0, Storage:vm-ceph - Disk size:
20 GiB, Cache:Write back, Discard: ☑
- Sockets:
1, Cores:2, Type:x86-64-v2-AES
- Memory (MiB):
2048
- Bridge:
vmbr0, VLAN Tag:35, Model:VirtIO (paravirtualized), Firewall: ☐
Cách 2: CLI (qm create)
qm create 232 --name headscale \
--memory 2048 \
--cores 2 \
--net0 virtio,bridge=vmbr0,tag=35 \
--scsi0 vm-ceph:20 \
--scsihw virtio-scsi-pci \
--ide2 local:iso/ubuntu-24.04.5-live-server-amd64.iso,media=cdrom \
--boot "order=ide2;scsi0" \
--ostype l26 \
--agent enabled=1
2.2 Khởi động và cài Ubuntu
qm start 232
qm terminal 232
Trong installer Ubuntu Server:
- Hostname:
headscale - Username:
sysadmin - Network: card mạng (thường
ens18, hoặcenp6s18trên VM q35; kiểm tra bằngip -br link): Manual → IP10.11.35.10/24, GW10.11.35.1, DNS10.11.45.53 - Bật OpenSSH server
2.3 Cấu hình sau cài xong
ssh [email protected]
# Update hệ thống (Ubuntu 24.04: nếu needrestart hiện hộp thoại "Daemons using outdated libraries" thì nhấn Enter)
sudo apt update && sudo apt upgrade -y
# Cài tools cơ bản
sudo apt install -y qemu-guest-agent curl wget nginx sqlite3 net-tools
# Enable QEMU guest agent
sudo systemctl enable --now qemu-guest-agent
# Timezone
sudo timedatectl set-timezone Asia/Ho_Chi_Minh
# Tăng bộ đệm UDP của kernel (hữu ích khi sau này bật DERP nhúng/STUN ở mục 6.4; vô hại nếu không dùng)
sudo tee /etc/sysctl.d/99-wireguard.conf << 'EOF'
net.core.rmem_max = 2500000
net.core.wmem_max = 2500000
EOF
sudo sysctl --system
Cấu hình Port Forwarding trên FortiGate
Tạo VIP objects · Tạo Firewall Policy · Policy cho Prometheus scrape metrics (VLAN_MGMT → VLAN_DMZ)
Headscale nằm trong VLAN_DMZ, cần FortiGate forward từ WAN vào.
3.1 Tạo VIP objects
Đăng nhập FortiGate web UI hoặc dùng API:
# <WAN_IP> = địa chỉ IP công cộng (WAN) của FortiGate trên wan1
# VIP cho HTTPS control plane (port 443)
curl -k -X POST "https://10.100.100.1/api/v2/cmdb/firewall/vip" \
-H "Authorization: Bearer <fortigate_api_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "VIP-Headscale-443",
"type": "static-nat",
"extip": "<WAN_IP>",
"extintf": "wan1",
"portforward": "enable",
"extport": "443",
"mappedip": [{"range": "10.11.35.10"}],
"mappedport": "443"
}'
3.2 Tạo Firewall Policy
# Policy WAN → VLAN_DMZ cho Headscale
curl -k -X POST "https://10.100.100.1/api/v2/cmdb/firewall/policy" \
-H "Authorization: Bearer <fortigate_api_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Allow-Headscale-Inbound",
"srcintf": [{"name": "wan1"}],
"dstintf": [{"name": "VLAN_DMZ"}],
"srcaddr": [{"name": "all"}],
"dstaddr": [{"name": "VIP-Headscale-443"}],
"action": "accept",
"schedule": "always",
"service": [{"name": "HTTPS"}],
"logtraffic": "all"
}'
3.3 Policy cho Prometheus scrape metrics (VLAN_MGMT → VLAN_DMZ)
Prometheus (VM235, 10.11.45.35, VLAN_MGMT) scrape 10.11.35.10:9090 của Headscale ở VLAN_DMZ (mục 15.1) nên lưu lượng đi qua FortiGate; không có policy này thì job headscale luôn ở trạng thái down dù cổng 9090 đã được publish trên VM232. Cổng 9090 do Docker publish nên UFW trên VM232 không lọc được (mục 14.1); policy FortiGate dưới đây là lớp lọc nguồn chính cho cổng này. Tạo hai address object, một service object và một policy, chiều MGMT → DMZ:
# Address object cho Prometheus và Headscale
curl -k -X POST "https://10.100.100.1/api/v2/cmdb/firewall/address" \
-H "Authorization: Bearer <fortigate_api_token>" \
-H "Content-Type: application/json" \
-d '{"name": "Prometheus-VM235", "subnet": "10.11.45.35 255.255.255.255"}'
curl -k -X POST "https://10.100.100.1/api/v2/cmdb/firewall/address" \
-H "Authorization: Bearer <fortigate_api_token>" \
-H "Content-Type: application/json" \
-d '{"name": "Headscale-VM232", "subnet": "10.11.35.10 255.255.255.255"}'
# Service TCP 9090 (cổng metrics_listen_addr ở mục 6.1)
curl -k -X POST "https://10.100.100.1/api/v2/cmdb/firewall.service/custom" \
-H "Authorization: Bearer <fortigate_api_token>" \
-H "Content-Type: application/json" \
-d '{"name": "TCP-9090", "tcp-portrange": "9090"}'
# Policy: chỉ Prometheus được vào cổng 9090 của Headscale
curl -k -X POST "https://10.100.100.1/api/v2/cmdb/firewall/policy" \
-H "Authorization: Bearer <fortigate_api_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Allow-Prometheus-Headscale",
"srcintf": [{"name": "VLAN_MGMT"}],
"dstintf": [{"name": "VLAN_DMZ"}],
"srcaddr": [{"name": "Prometheus-VM235"}],
"dstaddr": [{"name": "Headscale-VM232"}],
"action": "accept",
"schedule": "always",
"service": [{"name": "TCP-9090"}],
"logtraffic": "all"
}'
Cấp Chứng chỉ TLS từ step-CA
# Cài step-cli (gói .deb, cài ra /usr/bin/step)
STEP_VERSION="0.31.0"
wget https://github.com/smallstep/cli/releases/download/v${STEP_VERSION}/step-cli_${STEP_VERSION}-1_amd64.deb
sudo dpkg -i step-cli_${STEP_VERSION}-1_amd64.deb
step version
command -v step # kỳ vọng /usr/bin/step (đường dẫn dùng trong ExecStart bên dưới; cần kiểm lại trên máy thật)
# Tải và trust Root CA (giống bài 13 Bước 9) - tạo file hoatranlabs-root.crt dùng cho --root bên dưới
sudo step ca root /usr/local/share/ca-certificates/hoatranlabs-root.crt \
--ca-url https://step-ca.hoatranlabs.local:9000 \
--fingerprint <fingerprint-from-vm242>
sudo update-ca-certificates
# Tạo cert cho headscale
sudo mkdir -p /etc/ssl/headscale
sudo step ca certificate "headscale.hoatranlabs.local" \
/etc/ssl/headscale/headscale.crt \
/etc/ssl/headscale/headscale.key \
--ca-url https://step-ca.hoatranlabs.local:9000 \
--root /usr/local/share/ca-certificates/hoatranlabs-root.crt \
--san "headscale.hoatranlabs.local" \
--san "10.11.35.10"
sudo chmod 640 /etc/ssl/headscale/headscale.key
sudo chown root:www-data /etc/ssl/headscale/headscale.key
# Setup auto-renewal
sudo tee /etc/systemd/system/headscale-cert-renew.service << 'EOF'
[Unit]
Description=Renew Headscale TLS certificate
[Service]
Type=oneshot
ExecStart=/usr/bin/step ca renew \
/etc/ssl/headscale/headscale.crt \
/etc/ssl/headscale/headscale.key \
--force \
--ca-url https://step-ca.hoatranlabs.local:9000 \
--root /usr/local/share/ca-certificates/hoatranlabs-root.crt
ExecStartPost=/bin/systemctl reload nginx
EOF
sudo tee /etc/systemd/system/headscale-cert-renew.timer << 'EOF'
[Unit]
Description=Daily Headscale cert renewal
[Timer]
OnCalendar=daily
RandomizedDelaySec=2h
Persistent=true
[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now headscale-cert-renew.timer
update-ca-certificates ở trên ghi root CA step-CA vào /etc/ssl/certs/ca-certificates.crt; file này được mount vào container Headscale (mục 5.2) để OIDC gọi được Authentik qua HTTPS (mục 6.3).
Cài đặt Headscale
Cài Docker Engine và Compose plugin · Tạo thư mục và file docker-compose.yml · Lệnh headscale chạy qua container
5.1 Cài Docker Engine và Compose plugin
Cách cài giống bài 19 (kho chính thức của Docker, dạng deb822 + Signed-By, không dùng apt-key):
# Gỡ gói xung đột nếu có (máy mới cài thường chưa có gói nào trong danh sách)
sudo apt remove $(dpkg --get-selections docker.io docker-compose docker-compose-v2 docker-doc docker-buildx podman-docker containerd runc | cut -f1)
# Cài prerequisites
sudo apt update
sudo apt install -y ca-certificates curl
# Thêm Docker GPG key (dạng .asc, dùng với Signed-By)
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
# Thêm Docker repo (deb822, suite noble của Ubuntu 24.04)
sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null << EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
# Cài Docker Engine
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
docker-buildx-plugin docker-compose-plugin
# Thêm user vào group docker (chỉ có hiệu lực sau khi đăng xuất và đăng nhập lại)
sudo usermod -aG docker sysadmin
# Kiểm tra (kỳ vọng Docker 29.x và Compose plugin 5.x)
docker --version
docker compose version
Dòng Suites: được shell thay bằng noble nhờ heredoc không đặt nháy (<< EOF); mở /etc/apt/sources.list.d/docker.sources kiểm tra lại trước khi apt update. Docker 29.9.1 và Compose plugin 5.6.0 là bản mới nhất trong kho noble lúc kiểm (2026-10-15).
5.2 Tạo thư mục và file docker-compose.yml
Dữ liệu và cấu hình nằm ở thư mục host /etc/headscale (cấu hình + file policy, mount chỉ đọc) và /var/lib/headscale (SQLite, khóa Noise); file compose ở /opt/headscale. Image dựng trên gcr.io/distroless/base-debian13 (theo .goreleaser.yml của dự án) nên mặc định chạy bằng root; bài chạy bằng UID 65532 (user nonroot của distroless). Đây là tùy chỉnh của bài, tài liệu Headscale không hướng dẫn chạy non-root nên cần kiểm lại trên máy thật; thư mục dữ liệu phải thuộc UID này:
sudo mkdir -p /opt/headscale /etc/headscale /var/lib/headscale
sudo chown 65532:65532 /var/lib/headscale
sudo chmod 750 /var/lib/headscale
sudo tee /opt/headscale/docker-compose.yml > /dev/null << 'EOF'
name: headscale
services:
headscale:
image: docker.io/headscale/headscale:0.29.5 # ghim phiên bản; nâng cấp từng minor (mục 5.5)
container_name: headscale
restart: unless-stopped
command: serve
user: "65532:65532" # không chạy bằng root
read_only: true
tmpfs:
- /var/run/headscale # unix socket cho CLI (unix_socket trong config.yaml)
cap_drop:
- ALL
security_opt:
- no-new-privileges:true
ports:
- "127.0.0.1:8080:8080" # HTTP control plane: chỉ Nginx trên host (mục 7) vào được
- "10.11.35.10:9090:9090" # metrics cho Prometheus VM235 (mục 15); lọc nguồn ở FortiGate (mục 3.3)
volumes:
- /etc/headscale:/etc/headscale:ro
- /var/lib/headscale:/var/lib/headscale
# Tin root CA step-CA trong container (OIDC gọi https://authentik.hoatranlabs.local:9443, mục 6.3).
# Sau khi cập nhật CA trên host phải restart container để nhận file mới
- /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt:ro
healthcheck:
test: ["CMD", "headscale", "health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 30s
logging:
driver: json-file
options:
max-size: "10m"
max-file: "5"
networks:
- headscale-net
networks:
headscale-net:
driver: bridge
EOF
Giải thích nhanh: read_only + tmpfs + cap_drop: ALL + no-new-privileges là cấu hình cứng hóa theo hướng dẫn container của Headscale (image distroless không có shell). Healthcheck dùng lệnh headscale health của chính binary. Cổng 8080 chỉ gắn vào 127.0.0.1, cổng 9090 gắn vào IP của VM; gRPC 50443 không publish.
Chưa chạy docker compose up ở bước này: cần file cấu hình ở mục 6 trước.
5.3 Lệnh headscale chạy qua container
Image không có shell nên CLI chạy bằng docker exec (trong container, CLI nói chuyện với server qua unix socket). Tạo wrapper để mọi lệnh trong bài viết sudo headscale ... giống nhau ở cả hai phương án triển khai:
sudo tee /usr/local/bin/headscale > /dev/null << 'EOF'
#!/bin/sh
# Chạy CLI headscale bên trong container "headscale"; giữ TTY khi chạy tương tác để lệnh có hỏi xác nhận vẫn dùng được
if [ -t 0 ] && [ -t 1 ]; then
exec docker exec -it headscale headscale "$@"
else
exec docker exec -i headscale headscale "$@"
fi
EOF
sudo chmod +x /usr/local/bin/headscale
Dùng sudo headscale ... (hoặc không cần sudo nếu sysadmin đã thuộc nhóm docker). Lệnh gốc tương đương: docker exec -it headscale headscale <lệnh>. Trong script/cron không có TTY, thêm cờ toàn cục --force để bỏ qua câu hỏi xác nhận.
5.4 Phương án thay thế: gói .deb + systemd
Dùng khi không muốn chạy Docker trên VM232. Gói .deb hỗ trợ Ubuntu 22.04 trở lên và Debian 12 trở lên (https://headscale.net/stable/setup/install/official/):
HEADSCALE_VERSION="0.29.5"
wget https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_amd64.deb
# Verify checksum (optional nhưng nên làm)
wget https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/checksums.txt
sha256sum --check --ignore-missing checksums.txt
# Cài package (apt tự xử lý phụ thuộc, đúng cách của tài liệu Headscale)
sudo apt install -y ./headscale_${HEADSCALE_VERSION}_linux_amd64.deb
# Kiểm tra (kỳ vọng: headscale v0.29.5)
headscale version
Gói tự tạo: binary /usr/bin/headscale, user/group headscale, thư mục /etc/headscale/ (kèm config.yaml mẫu, ví dụ đầy đủ ở /usr/share/doc/headscale/examples/config-example.yaml), /var/lib/headscale/, unit headscale.service (có StateDirectory/RuntimeDirectory nên không cần tự tạo /var/lib/headscale và /var/run/headscale như bản cũ). Gói bật và chạy dịch vụ ngay sau khi cài với cấu hình mẫu; ghi đè config.yaml rồi sudo systemctl restart headscale.
Khác biệt so với các bước Docker trong bài:
| Hạng mục | Docker (mặc định của bài) | .deb + systemd |
|---|---|---|
listen_addr / metrics_listen_addr (mục 6.1) | 0.0.0.0:8080 / 0.0.0.0:9090 trong container | 127.0.0.1:8080 / 0.0.0.0:9090 |
trusted_proxies (mục 6.1) | để trống | 127.0.0.1/32 và ::1/128 (Nginx cùng máy) |
| Owner file cấu hình (mục 6.2) | root:65532, mode 640 | headscale:headscale, mode 640 |
| Khởi động / restart (mục 8) | docker compose up -d / docker compose restart headscale | systemctl enable --now headscale / systemctl restart headscale |
| Nạp lại policy (mục 12) | docker kill --signal=HUP headscale | systemctl reload headscale |
| Log | docker compose logs headscale | journalctl -u headscale |
| Lọc cổng 9090 (mục 14.1) | FortiGate (Docker bỏ qua UFW) | UFW: ufw allow from 10.11.45.35 to any port 9090/tcp |
| CLI | wrapper /usr/local/bin/headscale (mục 5.3) | /usr/bin/headscale (xóa wrapper nếu chuyển từ Docker sang) |
Chuyển từ Docker sang .deb (hoặc ngược lại): dừng phương án cũ, giữ nguyên /etc/headscale và /var/lib/headscale, chown -R về chủ sở hữu của phương án mới (headscale:headscale hoặc 65532:65532) rồi chạy phương án mới.
5.5 Nâng cấp từ Headscale 0.23.0 (hoặc bản cũ hơn)
Bài này dựng mới thẳng 0.29.5 nên người làm mới không cần mục này. Ai đang chạy 0.23.0 phải theo hướng dẫn chính thức (https://headscale.net/stable/setup/upgrade/): nâng từng bản minor ổn định, mỗi minor chọn bản vá mới nhất; từ 0.29 Headscale tự chặn việc nhảy cóc minor và hạ cấp. Lộ trình:
0.23.0 → 0.24.3 → 0.25.1 → 0.26.1 → 0.27.1 → 0.28.0 → 0.29.5
Quy trình cho MỖI bước:
- Đọc ghi chú phát hành của bản đích (https://github.com/juanfont/headscale/releases và
CHANGELOG.md). - Dừng Headscale và sao lưu cả cấu hình lẫn dữ liệu (Headscale chạy migration database khi nâng cấp, không đảo ngược được):
cd /opt/headscale && docker compose stop # .deb: sudo systemctl stop headscale
TS=$(date +%Y%m%d%H%M%S)
sudo cp -aR /etc/headscale /etc/headscale.backup-$TS
sudo cp -aR /var/lib/headscale /var/lib/headscale.backup-$TS # gồm db.sqlite, db.sqlite-wal, db.sqlite-shm, noise_private.key
- Đổi tag image sang bản kế tiếp trong
/opt/headscale/docker-compose.yml(hoặc cài.debcủa bản đó, chọn giữconfig.yamlhiện tại khi dpkg hỏi), rồidocker compose pull && docker compose up -d. - Đối chiếu
config.yamlvớiconfig-example.yamlđúng tag (https://raw.githubusercontent.com/juanfont/headscale/v<phiên bản>/config-example.yaml), sửa theo bảng dưới; kiểm tradocker compose logs --tail 100 headscale(thấy migration chạy xong),sudo headscale nodes list,curl -s http://127.0.0.1:8080/health, rồi mới sang bước kế tiếp.
Khi cần quay lại bản trước: phục hồi bản sao lưu ở bước 2 và đặt lại tag cũ (không hạ cấp tại chỗ).
Thay đổi liên quan trực tiếp tới cấu hình và lệnh của bài (rút gọn từ changelog, đã đối chiếu 2026-10-15):
| Nâng lên | Cần làm / thay đổi chính |
|---|---|
| 0.24.3 | Người dùng OIDC được nhận diện bằng iss + sub (không còn theo email); migration oidc.map_legacy_users bật mặc định và đổi username thành preferred_username (có thể làm hỏng policy tham chiếu username). Bỏ dns.use_username_in_magic_dns. CLI users nhận --identifier. Thêm PKCE cho OIDC, dns.extra_records_path |
| 0.25.1 | Luồng đăng ký node viết lại (đăng ký với user mới tạo node mới); bỏ hỗ trợ client Tailscale cũ hơn 1.62; oidc.map_legacy_users mặc định false; pre-auth key đã dùng không xóa được |
| 0.26.1 | Policy v2: tên user trong policy phải có @ (devops → devops@); route chuyển sang headscale nodes list-routes và nodes approve-routes (bỏ headscale routes ...); oidc.strip_email_domain và oidc.map_legacy_users bị bỏ (còn trong file thì Headscale không khởi động); pre-auth key CLI dùng ID của user; phải có dns.nameservers.global khi dns.override_local_dns bật (mặc định bật); server_url không được trùng/nằm dưới dns.base_domain |
| 0.27.1 | Migration SQLite lớn: bắt buộc sao lưu trước (kèm -wal, -shm); DERP map cập nhật mặc định 3h; thêm autogroup:member, autogroup:tagged, autogroup:self; kiểm tra hostname chặt hơn; gói DEB tái cấu trúc, bỏ Ubuntu 20.04 |
| 0.28.0 | Tag là danh tính của node (node gắn tag không còn thuộc user); pre-auth key hash bcrypt, định dạng hskey-auth-..., preauthkeys expire/delete --id, preauthkeys list không lọc theo user, create không bắt buộc --user; bỏ headscale nodes move; thêm oidc.email_verified_required; SSH policy bỏ đích *; không còn migrate database trước 0.25 |
| 0.29.5 | Ký tự * trong policy chỉ còn là dải tailnet 100.64.0.0/10 và fd7a:115c:a1e0::/48 (không còn là mọi IP; mục 12); proto:icmp chỉ gồm ICMPv4; thêm grants, autogroup:danger-all, nodeAttrs; khóa randomize_client_port bị bỏ (còn trong file thì không khởi động, chuyển sang policy); headscale nodes register deprecated, dùng headscale auth register; bỏ cờ --namespace và alias namespace/machine; oidc.expiry bị bỏ, dùng node.expiry; ephemeral_node_inactivity_timeout deprecated, dùng node.ephemeral.inactivity_timeout; thêm trusted_proxies; tên MagicDNS của node trùng hostname đổi cách đặt hậu tố; client Tailscale tối thiểu 1.80.0 |
Sau khi lên 0.29.5 cần rà thêm: (1) policy cũ dùng *:* mất quyền vào lab 10.11.0.0/16 (mục 12); (2) tên user trong policy; (3) user OIDC đổi tên theo preferred_username; (4) pre-auth key cũ (định dạng trước 0.28) còn dùng được nhưng nên tạo lại; (5) client Tailscale cũ hơn 1.80.0 phải nâng cấp. Phần chuyển từ .deb sang Docker làm sau cùng, khi đã ở 0.29.5 và hệ thống ổn định.
Cấu hình Headscale
Tạo file cấu hình chính · Phân quyền file config · Bật đăng nhập OIDC bằng Authentik (tùy chọn)
6.1 Tạo file cấu hình chính
Bản dưới là cấu hình Docker (listen_addr và metrics_listen_addr phải nghe 0.0.0.0 bên trong container thì cổng publish mới tới được); khác biệt của phương án .deb xem bảng ở mục 5.4. Khóa cấu hình đã đối chiếu với config-example.yaml của tag v0.29.5:
sudo tee /etc/headscale/config.yaml << 'EOF'
# Headscale 0.29.5 - HOATRANLABS Lab - VM232 (chạy trong container, xem /opt/headscale/docker-compose.yml)
server_url: https://headscale.hoatranlabs.local
# Trong container phải nghe 0.0.0.0; cổng được giới hạn ở docker-compose.yml (8080 -> 127.0.0.1, 9090 -> 10.11.35.10)
listen_addr: 0.0.0.0:8080
metrics_listen_addr: 0.0.0.0:9090 # Prometheus VM235 (10.11.45.35) scrape từ xa; lọc nguồn ở FortiGate (mục 3.3)
grpc_listen_addr: 127.0.0.1:50443 # gRPC từ xa: không publish; CLI cục bộ dùng unix_socket bên dưới
grpc_allow_insecure: false
# CIDR của reverse proxy có quyền gửi header True-Client-IP / X-Real-IP / X-Forwarded-For.
# Docker: để trống (Nginx tới container qua cổng publish nên nguồn thấy thường là gateway của mạng bridge Docker, không phải 127.0.0.1;
# header bị bỏ qua, log hiện IP của gateway; cần kiểm lại trên máy thật). Phương án .deb: ["127.0.0.1/32", "::1/128"].
trusted_proxies: []
# Khóa Noise (giao thức TS2021) giữa Headscale và client Tailscale
noise:
private_key_path: /var/lib/headscale/noise_private.key
# Dải IP cấp cho client VPN: phải nằm trong 100.64.0.0/10 và fd7a:115c:a1e0::/48 (dải ngoài CGNAT/ULA không được hỗ trợ)
prefixes:
v4: 100.64.0.0/10
v6: fd7a:115c:a1e0::/48
allocation: sequential
# DERP (relay): dùng DERP công cộng của Tailscale; tự host DERP nhúng xem mục 6.4
derp:
server:
enabled: false
urls:
- https://controlplane.tailscale.com/derpmap/default
paths: []
auto_update_enabled: true
update_frequency: 3h # mặc định 3h từ 0.27 (bản 0.23 là 24h)
# Vòng đời node (thay cho ephemeral_node_inactivity_timeout và oidc.expiry của bản cũ)
node:
expiry: 0 # 0 = node không tự hết hạn; đặt 180d nếu muốn buộc đăng nhập lại định kỳ (node gắn tag không hết hạn)
ephemeral:
inactivity_timeout: 30m
# Database SQLite (Headscale khuyến nghị SQLite; PostgreSQL chỉ ở chế độ bảo trì)
database:
type: sqlite
sqlite:
path: /var/lib/headscale/db.sqlite
write_ahead_log: true
wal_autocheckpoint: 1000
# TLS: Nginx (mục 7) kết thúc TLS nên Headscale nghe HTTP; để trống 2 khóa này
tls_cert_path: ""
tls_key_path: ""
# DNS
# - base_domain: hậu tố MagicDNS của tailnet; phải khác và không phải miền cha của server_url
# - override_local_dns: false => không ghi đè DNS của máy khách; chỉ miền hoatranlabs.local đi tới Pi-hole (split DNS).
# Nếu để true (mặc định) thì bắt buộc có nameservers.global và MỌI truy vấn DNS của client phải tới được máy chủ đó,
# trong khi Pi-hole 10.11.45.53 chỉ tới được khi subnet route (mục 10) đang hoạt động.
dns:
magic_dns: true
base_domain: vpn.hoatranlabs.local
override_local_dns: false
nameservers:
global: []
split:
hoatranlabs.local:
- 10.11.45.53
search_domains:
- hoatranlabs.local
# unix socket cho CLI (nằm trong tmpfs của container)
unix_socket: /var/run/headscale/headscale.sock
unix_socket_permission: "0770"
# OIDC - tích hợp Authentik (tùy chọn; cách bật ở mục 6.3)
# oidc:
# only_start_if_oidc_is_available: false # mặc định true: Authentik tắt thì Headscale không khởi động
# issuer: https://authentik.hoatranlabs.local:9443/application/o/headscale/
# client_id: <CLIENT_ID_TU_AUTHENTIK>
# client_secret: <CLIENT_SECRET_TU_AUTHENTIK>
# scope: ["openid", "profile", "email"]
# pkce:
# enabled: true
# method: S256
# Logging
log:
level: info
format: text
# Không gửi log của client lên Tailscale Inc (mặc định đã là false)
logtail:
enabled: false
# Policy (ACL/grants): bật ở mục 12 (khối "policy:" được thêm vào cuối file)
EOF
Kiểm tra cú pháp và các ràng buộc (ví dụ dns.nameservers.global bắt buộc khi override_local_dns bật, server_url không trùng base_domain) trước khi chạy: docker compose run --rm --no-deps headscale configtest (ở mục 8; phương án .deb: headscale configtest).
So với cấu hình 0.23.0 của bài trước: thêm trusted_proxies; ephemeral_node_inactivity_timeout thành node.ephemeral.inactivity_timeout (và thêm node.expiry thay cho oidc.expiry); database.sqlite có thêm write_ahead_log; prefixes có thêm v6 và allocation; derp.update_frequency 24h thành 3h; khối dns dùng override_local_dns và split DNS thay cho một nameserver toàn cục; oidc.strip_email_domain không còn tồn tại; policy chuyển sang khai báo ở mục 12 (HuJSON, grants).
6.2 Phân quyền file config
# Docker: container chạy UID 65532 và đọc cấu hình qua nhóm 65532 (mount chỉ đọc)
sudo chown root:65532 /etc/headscale/config.yaml
sudo chmod 640 /etc/headscale/config.yaml
# Phương án .deb: sudo chown headscale:headscale /etc/headscale/config.yaml && sudo chmod 640 /etc/headscale/config.yaml
6.3 Bật đăng nhập OIDC bằng Authentik (tùy chọn)
Headscale 0.29.5 hỗ trợ OIDC (callback là <server_url>/oidc/callback; Authentik được liệt kê "fully supported" trong tài liệu Headscale). Khối oidc: ở mục 6.1 để comment vì chỉ cần khi muốn người dùng đăng nhập bằng tài khoản Authentik (bài 14); pre-auth key ở mục 9.2 vẫn dùng bình thường. Muốn bật thì làm theo thứ tự:
- Trên Authentik (VM234, cách làm giống mục 8 của bài 14): Applications → Providers → Create → OAuth2/OpenID Provider, Name
headscale-oidc, Authorization flowdefault-provider-authorization-implicit-consent, Client typeConfidential, Redirect URIs kiểu Strict, loại Authorization:https://headscale.hoatranlabs.local/oidc/callback(nếu đã đổiserver_urlsang tên public ở mục 13.2 thì dùnghttps://vpn.hoatranlab.io.vn/oidc/callback), Signing Key chọn một key có sẵn, Encryption Key để trống (Headscale không hỗ trợ JWE), Advanced protocol settings → Selected Scopes giữopenid,email,profile. Sau đó Applications → Applications → Create: NameHeadscale, Slugheadscale(khớpissuerở mục 6.1), Providerheadscale-oidc, Launch URLhttps://headscale.hoatranlabs.local. Ghi lại Client ID và Client Secret. - Trên VM232: bỏ comment khối
oidc:trong/etc/headscale/config.yaml, điềnclient_idvàclient_secretvừa ghi (hoặc để secret ngoài file:client_secret_path, hoặc biến môi trườngHEADSCALE_OIDC_CLIENT_SECRET), rồicd /opt/headscale && docker compose restart headscalevà kiểm tra bằngdocker compose logs --tail 50 headscale | grep -i oidc(phương án.deb:systemctl restart headscalevàjournalctl -u headscale -n 30 --no-pager | grep -i oidc). Từ 0.29.4,oidc.issuersai hoặc thiếuclient_id/client_secretlàm Headscale không khởi động. - Trên client chạy
tailscale up --login-server=https://headscale.hoatranlabs.local(không cần--authkey): trình duyệt chuyển sang Authentik, đăng nhập xong Headscale hiện trang xác nhận (tên máy, vân tay machine key) rồi node được đăng ký vào user có tên là claimpreferred_usernamecủa Authentik (thường là username, ví dụakadmin), thay cho lệnhheadscale auth register.
Lưu ý khi dùng OIDC từ 0.24 trở lên:
- Người dùng được nhận diện bằng cặp
iss+sub, không còn bằng email;oidc.strip_email_domainđã bị bỏ, tên user làpreferred_username(tối thiểu 2 ký tự, bắt đầu bằng chữ cái, chỉ gồm chữ, số,-,.,_và tối đa một@). Policy tham chiếu user theo dạng<username>@(mục 12). Nếu người dùng tự đổi username/email ở IdP thì policy có thể thôi khớp, nên đặt quyền chỉnh sửa hồ sơ cho phù hợp. - Chỉ email đã xác minh (
email_verified: true) được đồng bộ vào hồ sơ; khi Authentik không gửi claim này thì đặtemail_verified_required: false. Bộ lọc tùy chọn:allowed_domains,allowed_users,allowed_groups(tên nhóm Authentik, claimgroupsnằm trong scopeprofile; cần kiểm lại trên máy thật). Theo docs Headscale, nhóm OIDC không dùng được trong policy (mục 12), policy vẫn gắn theo user. - Nếu đã tạo user bằng CLI trùng với username Authentik (ví dụ
hoatvở mục 9.1) thì đăng nhập OIDC lần đầu có thể báo trùng tên (không tự ghép với user tạo bằng CLI; cần kiểm lại trên máy thật). Dùng tên khác hoặc đổi tên user CLI bằngheadscale users renametrước. - Container phải tin root CA step-CA vì Authentik chạy HTTPS cổng 9443 với cert do step-CA cấp (bài 14): file bundle của host được mount ở mục 5.2 nên phải làm mục 4 (
update-ca-certificates) trước khi khởi động container. FortiGate phải cho phép VLAN_DMZ → Authentik cổng 9443 (ruleAllow-Authentik-SSOở bài 14).
6.4 DERP nhúng và STUN 3478/UDP (tùy chọn)
Bài dùng DERP công cộng của Tailscale (derp.urls). Muốn tự host relay trong chính Headscale: đặt derp.server.enabled: true (cần server_url dùng https), giữ stun_listen_addr: "0.0.0.0:3478", khai báo derp.server.ipv4 là <WAN_IP> để client kết nối ổn định, mở 3478/udp từ FortiGate (thêm VIP UDP 3478 và policy tương tự mục 3) tới VM232 và publish cổng này trong Docker (- "3478:3478/udp" ở ports của docker-compose.yml). Phần DERP qua HTTPS đi chung cổng 443 của Nginx; STUN thì không qua Nginx được. Muốn chỉ dùng DERP của mình thì đặt derp.urls: [], nhưng khi đó chỉ còn một relay (điểm lỗi duy nhất). Kiểm tra bằng tailscale debug derp-map và tailscale debug derp headscale trên client (khi dùng mã vùng mặc định headscale). Chưa dựng thử tại lab, cần kiểm lại trên máy thật.
Cấu hình Nginx Reverse Proxy
Headscale lắng nghe HTTP ở port 8080 (container publish ở 127.0.0.1; phương án .deb nghe 127.0.0.1:8080). Nginx làm TLS termination. Theo tài liệu Headscale, reverse proxy phải hỗ trợ WebSocket (giao thức điều khiển của Tailscale nâng cấp kết nối bằng POST và header Upgrade: tailscale-control-protocol), đồng thời không dùng được Cloudflare Proxy/Tunnel phía trước.
sudo rm -f /etc/nginx/sites-enabled/default
sudo tee /etc/nginx/sites-available/headscale << 'EOF'
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
listen 80;
server_name headscale.hoatranlabs.local;
# Tailscale captive portal detection
location = /generate_204 {
return 204;
}
location / {
return 301 https://$host$request_uri;
}
}
server {
# Nginx 1.24.0 của Ubuntu 24.04 dùng cú pháp "ssl http2" này; "http2 on;" chỉ có từ Nginx 1.25.1
listen 443 ssl http2;
server_name headscale.hoatranlabs.local;
ssl_certificate /etc/ssl/headscale/headscale.crt;
ssl_certificate_key /etc/ssl/headscale/headscale.key;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
# Security headers
add_header Strict-Transport-Security "max-age=31536000" always;
# Headscale control plane
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header True-Client-IP $remote_addr;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_buffering off;
}
}
EOF
sudo ln -s /etc/nginx/sites-available/headscale /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
Khởi động Headscale
cd /opt/headscale
# Kiểm tra cấu hình bằng container tạm (cùng mount/user như dịch vụ; không publish cổng)
docker compose run --rm --no-deps headscale configtest
# Tải image đã ghim và khởi động (restart: unless-stopped tự chạy lại sau khi reboot)
docker compose pull
docker compose up -d
# Kiểm tra trạng thái: cột STATUS phải là "Up ... (healthy)" sau khoảng 30 giây
docker compose ps
# Xem logs
docker compose logs -f --tail 50 headscale
# Kiểm tra version và trạng thái
curl -s http://127.0.0.1:8080/health # {"status":"pass"}
sudo headscale version # kỳ vọng v0.29.5
sudo headscale nodes list
Kiểm tra port đang listen:
ss -tlnp | grep 8080
# LISTEN ... 127.0.0.1:8080 ...
ss -tlnp | grep 9090
# LISTEN ... 10.11.35.10:9090 ...
Phương án .deb: sudo systemctl enable --now headscale, sudo systemctl status headscale, sudo journalctl -u headscale -f --no-pager; cổng 9090 nghe 0.0.0.0:9090.
Tạo Users và Pre-auth Keys
Tạo users (namespaces) · Tạo pre-auth keys cho remote staff · Đăng ký node bằng web authentication (không dùng key)
Từ 0.26 trở lên, nhiều lệnh nhận ID (số) thay vì tên; xem cột ID trong headscale users list và headscale nodes list.
9.1 Tạo users (namespaces)
# Tạo user cho từng nhóm
sudo headscale users create hoatv
sudo headscale users create devops
sudo headscale users create remote-staff
# Liệt kê users (ghi lại cột ID, ví dụ hoatv=1, devops=2, remote-staff=3)
sudo headscale users list
Tên user không được kết thúc bằng @ (policy tham chiếu user bằng ten@, mục 12). Xóa/đổi tên: sudo headscale users destroy --identifier <ID> (user còn node thì phải xóa node trước), sudo headscale users rename --identifier <ID> --new-name <tên mới>.
9.2 Tạo pre-auth keys cho remote staff
# Key dùng 1 lần, hết hạn sau 24 giờ (--user nhận ID của user: remote-staff = 3 ở ví dụ trên)
sudo headscale preauthkeys create \
--user 3 \
--expiration 24h
# Key dùng nhiều lần (reusable) cho testing (devops = 2)
sudo headscale preauthkeys create \
--user 2 \
--reusable \
--expiration 720h
# Key gắn tag cho subnet router của lab (mục 10): node nhận tag thay vì thuộc một user
sudo headscale preauthkeys create \
--tags tag:lab-router \
--expiration 1h
# Liệt kê tất cả key (từ 0.28 không còn lọc theo user)
sudo headscale preauthkeys list
# Thu hồi hoặc xóa key theo ID (cột ID của lệnh trên)
sudo headscale preauthkeys expire --id <ID>
sudo headscale preauthkeys delete --id <ID>
Mặc định key dùng một lần và hết hạn sau 1 giờ. Từ 0.28 key chỉ hiện đầy đủ MỘT lần lúc tạo (sau đó list chỉ hiện tiền tố), nên ghi lại ngay. Khi chưa có tag trong policy thì --tags tag:lab-router vẫn tạo được key; quyền sở hữu tag khai báo ở mục 12 (tagOwners).
9.3 Đăng ký node bằng web authentication (không dùng key)
tailscale up --login-server=... (hoặc tailscale login trên Windows/macOS) mở trang trình duyệt in sẵn lệnh kèm Auth ID; chạy trên VM232:
sudo headscale auth register --user remote-staff --auth-id <AUTH_ID>
Từ 0.29 lệnh headscale nodes register --key ... đã deprecated, dùng headscale auth register (cờ --user nhận tên user). Node tagged đăng ký bằng tailscale up --advertise-tags tag:<tên> thì user thực hiện phải nằm trong tagOwners của policy.
9.4 Quản trị node thường dùng
| Việc cần làm | Lệnh (Headscale 0.29.5) |
|---|---|
| Liệt kê node (lọc theo user) | sudo headscale nodes list / sudo headscale nodes list --user remote-staff |
| Buộc đăng nhập lại (expire) | sudo headscale nodes expire --identifier <ID> (thêm --disable thì ngược lại: tắt hết hạn cho node) |
| Đổi tên node | sudo headscale nodes rename --identifier <ID> <tên-mới> |
| Xóa node | sudo headscale nodes delete --identifier <ID> |
| Gắn tag cho node | sudo headscale nodes tag --identifier <ID> --tags tag:lab-router |
| Xem / duyệt route | sudo headscale nodes list-routes / sudo headscale nodes approve-routes --identifier <ID> --routes <CIDR> (mục 10) |
Lệnh headscale nodes move đã bị bỏ từ 0.28 (node gắn với user hoặc tag ngay lúc đăng ký). Dùng API key khi cần tích hợp (tùy chọn): sudo headscale apikeys create --expiration 90d, sudo headscale apikeys list, sudo headscale apikeys expire --prefix <PREFIX>; API REST ở /api/v1 (tài liệu /swagger), xác thực bằng Authorization: Bearer <API_KEY>.
Cấu hình Subnet Routes
Trên node lab muốn làm subnet router · Phê duyệt route trên Headscale server · Exit node (tùy chọn)
Để các VPN client truy cập được toàn bộ lab (10.11.0.0/16) qua một subnet router trong lab. Cần hai bước chấp thuận: node quảng bá route (10.1) và Headscale phê duyệt route (10.2).
10.1 Trên node lab muốn làm subnet router
Dùng một VM Linux trong lab, ví dụ VM trong VLAN_MGMT (có thể là ops01, VM290 10.11.45.20 của bài 07, đã nằm trong mgmt-admins của bài 05). Không cài Tailscale trên chính VM232 (Headscale không hỗ trợ chạy chung với Tailscale client trên một máy). Cài Tailscale theo mục 11.1 (kho apt dạng deb822), rồi:
# Bật IP forwarding (bắt buộc để node này làm subnet router)
sudo tee /etc/sysctl.d/99-tailscale.conf << 'EOF'
net.ipv4.ip_forward = 1
net.ipv6.conf.all.forwarding = 1
EOF
sudo sysctl -p /etc/sysctl.d/99-tailscale.conf
# Kết nối vào Headscale bằng pre-auth key gắn tag (tạo ở mục 9.2) và quảng bá route
sudo tailscale up \
--login-server=https://headscale.hoatranlabs.local \
--authkey=<preauth_key_tagged_from_step_9.2> \
--advertise-routes=10.11.0.0/16 \
--accept-dns=false
Subnet router trên Linux mặc định SNAT: gói từ VPN client vào Proxmox/PBS (cổng 8006/22/8007...) xuất hiện với nguồn là IP của router. Vì vậy IP này phải nằm trong mgmt-admins (bài 05). Muốn thấy IP thật của client thì tắt SNAT bằng --snat-subnet-routes=false và thêm route về 100.64.0.0/10 trên các máy đích (cần kiểm lại trên máy thật).
10.2 Phê duyệt route trên Headscale server
Từ 0.26 route do node quản lý (lệnh headscale routes list/enable cũ đã bị bỏ):
# Liệt kê route node quảng bá (cột Available) và route đã duyệt (cột Approved)
sudo headscale nodes list-routes
# Duyệt route (thay <ID> bằng ID node ở cột ID); danh sách --routes là toàn bộ route được duyệt
sudo headscale nodes approve-routes --identifier <ID> --routes 10.11.0.0/16
# Kiểm tra route đã active (cột Serving)
sudo headscale nodes list-routes
Có thể duyệt tự động bằng autoApprovers trong policy (mục 12): router gắn tag tag:lab-router quảng bá 10.11.0.0/16 sẽ được duyệt ngay khi kết nối. Nếu có hai node quảng bá cùng một prefix thì Headscale bật chế độ HA (health probe mỗi 10 giây, node.routes.ha trong config) để tự chuyển sang node còn sống.
10.3 Exit node (tùy chọn)
Exit node cho phép client định tuyến toàn bộ lưu lượng Internet qua một node trong lab (khác với subnet router chỉ chuyển lưu lượng vào lab):
# Trên node làm exit node (đã bật IP forwarding như mục 10.1)
sudo tailscale set --advertise-exit-node
# Trên VM232: node quảng bá 0.0.0.0/0 và ::/0; duyệt một trong hai là đủ, route còn lại tự được duyệt
sudo headscale nodes list-routes
sudo headscale nodes approve-routes --identifier <ID> --routes 0.0.0.0/0
# Trên client muốn dùng exit node (policy cần cấp quyền tới autogroup:internet, mục 12)
sudo tailscale set --exit-node=<tên-node>
Client Setup
Linux client · Windows client · macOS client
Headscale 0.29.5 yêu cầu client Tailscale từ v1.80.0 trở lên và nhắm hỗ trợ 10 bản client gần nhất (https://headscale.net/stable/about/clients/). Cài bản mới nhất của từng nền tảng. Máy khách trong lab phải tin root CA step-CA (mục 17) khi dùng tên nội bộ headscale.hoatranlabs.local; thiết bị ngoài Internet dùng tên public có cert Let's Encrypt (mục 13.2).
11.1 Linux client
# Kho apt chính thức của Tailscale cho Ubuntu 24.04 (noble), dạng deb822 + Signed-By (không dùng apt-key)
# Nếu trước đó đã chạy tailscale.com/install.sh thì xóa file kho cũ để tránh trùng nguồn:
# sudo rm -f /etc/apt/sources.list.d/tailscale.list
sudo install -m 0755 -d /usr/share/keyrings
curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/noble.noarmor.gpg | sudo tee /usr/share/keyrings/tailscale-archive-keyring.gpg > /dev/null
sudo tee /etc/apt/sources.list.d/tailscale.sources > /dev/null << 'EOF'
Types: deb
URIs: https://pkgs.tailscale.com/stable/ubuntu
Suites: noble
Components: main
Signed-By: /usr/share/keyrings/tailscale-archive-keyring.gpg
EOF
sudo apt update
sudo apt install -y tailscale # kỳ vọng 1.104.1 hoặc mới hơn
# Kết nối vào Headscale
sudo tailscale up \
--login-server=https://headscale.hoatranlabs.local \
--authkey=<preauth_key> \
--accept-routes \
--accept-dns
# Kiểm tra trạng thái
tailscale version
tailscale status
tailscale ip
Trên Linux phải có --accept-routes mới dùng được subnet route; các nền tảng khác (Windows, macOS, iOS, Android) nhận route mặc định.
11.2 Windows client
# Tải Tailscale installer từ https://tailscale.com/download/windows rồi cài đặt
# Mở Command Prompt hoặc PowerShell (nếu báo thiếu quyền thì chạy bằng Administrator):
tailscale login --login-server https://headscale.hoatranlabs.local
# Trình duyệt mở trang đăng ký: trang in lệnh "headscale auth register --auth-id <AUTH_ID> --user <USER>" để chạy trên VM232 (mục 9.3)
# Hoặc dùng pre-auth key trực tiếp:
tailscale up --login-server https://headscale.hoatranlabs.local --authkey <preauth_key>
Muốn Tailscale chạy cả khi chưa đăng nhập Windows: biểu tượng khay → Preferences → bật Run unattended. Máy chủ Headscale còn có trang hướng dẫn tại https://headscale.hoatranlabs.local/windows.
11.3 macOS client
Cài Tailscale cho macOS từ https://tailscale.com/download/mac (Mac App Store hoặc gói standalone), rồi trỏ về Headscale bằng một trong hai cách:
# Dòng lệnh
tailscale login --login-server https://headscale.hoatranlabs.local
# Hoặc dùng pre-auth key và nhận route
tailscale up \
--login-server https://headscale.hoatranlabs.local \
--authkey <preauth_key> \
--accept-routes
Cách GUI: nhấn giữ Option rồi bấm biểu tượng Tailscale trên thanh menu → Debug → Custom Login Server → Add Account... → nhập https://headscale.hoatranlabs.local → đăng nhập theo trình duyệt. Trang hướng dẫn tại /apple của máy chủ.
11.4 iOS và Android
- iOS: cài Tailscale từ App Store, mở app → biểu tượng tài khoản góc phải → Log in… → menu tùy chọn góc phải → Use custom coordination server → nhập
https://vpn.hoatranlab.io.vn(thiết bị di động ở ngoài Internet nên dùng tên public có cert Let's Encrypt; chỉ dùng được sau khi đã làm mục 13.2 và đặtserver_urlsang tên public, vì Headscale tạo liên kết đăng ký từserver_url) → đăng nhập. - Android: cài Tailscale từ Google Play hoặc F-Droid → Settings → Accounts → menu ba chấm → Use an alternate server → nhập URL → làm theo hướng dẫn trên trang đăng ký. Dùng pre-auth key: sau khi đặt URL, menu ba chấm → Use an auth key → dán key.
11.5 Kiểm tra kết nối từ client
# Xem IP được cấp (dải 100.64.x.x)
tailscale ip
# Ping một VM trong lab qua VPN (user devops/hoatv; remote-staff chỉ tới VLAN 65 và 35, mục 12)
ping 10.11.45.53 # Pi-hole
ping 10.11.25.43 # Vaultwarden
# Xem tất cả nodes trong mesh
tailscale status
ACL Policies (Access Control Lists)
Headscale dùng file policy HuJSON (JSON có chú thích) cùng định dạng với Tailscale, khai báo bằng policy.path trong config.yaml (policy.mode: file). Tài liệu Headscale khuyến nghị viết bằng grants; acls vẫn được hỗ trợ (Tailscale coi là cách cũ) và hai kiểu dùng chung được trong một file. Trước 0.29 bài dùng acls; bản này chuyển sang grants. Những điểm đổi so với 0.23:
- Tên user phải có
@: userdevopsviếtdevops@. - Từ 0.29.0,
*chỉ là dải tailnet (100.64.0.0/10vàfd7a:115c:a1e0::/48), KHÔNG còn là mọi địa chỉ IP. Rule cũ"dst": ["*:*"]không còn mở đường vào lab10.11.0.0/16qua subnet router; phải ghi tường minh CIDR của lab. Muốn khớp mọi IP kể cả ngoài tailnet thì dùngautogroup:danger-all(chỉ làm nguồn) hoặc CIDR cụ thể. -
proto:icmp/icmpchỉ gồm ICMPv4; ICMPv6 dùngipv6-icmp. - Không có policy thì cho phép mọi lưu lượng; đã khai báo
grants/aclsthì mọi thứ không khớp rule bị từ chối. - Nhóm OIDC không dùng được trong policy (mục 6.3).
sudo tee /etc/headscale/policy.hujson << 'EOF'
{
// Policy cho HOATRANLABS VPN - Headscale 0.29 (HuJSON: cho phép chú thích)
// Tên user có dấu @ ở cuối; không có rule nào khớp thì bị từ chối.
// "*" chỉ gồm dải tailnet 100.64.0.0/10 và fd7a:115c:a1e0::/48, KHÔNG gồm lab 10.11.0.0/16
// Chủ sở hữu tag của subnet router (mục 9.2 và 10)
"tagOwners": {
"tag:lab-router": ["devops@"]
},
// Tự duyệt route lab khi router gắn tag:lab-router quảng bá 10.11.0.0/16 (mục 10.2)
"autoApprovers": {
"routes": {
"10.11.0.0/16": ["tag:lab-router"]
}
},
"grants": [
// Quản trị viên và DevOps: toàn bộ lab (10.11.0.0/16 qua subnet router) và mọi node trong tailnet
{
"src": ["hoatv@", "devops@"],
"dst": ["10.11.0.0/16", "*"],
"ip": ["*"]
},
// Remote staff chỉ được truy cập VLAN_SRV (65) và VLAN_DMZ (35)
{
"src": ["remote-staff@"],
"dst": ["10.11.65.0/24", "10.11.35.0/24"],
"ip": ["*"]
},
// Mọi thiết bị cá nhân được hỏi DNS của Pi-hole (split DNS cho hoatranlabs.local, mục 6.1)
{
"src": ["autogroup:member"],
"dst": ["10.11.45.53"],
"ip": ["tcp:53", "udp:53"]
},
// Tất cả nodes trong tailnet có thể ping nhau (ICMPv4 và ICMPv6)
{
"src": ["*"],
"dst": ["*"],
"ip": ["icmp:*", "ipv6-icmp:*"]
}
]
}
EOF
sudo chown root:65532 /etc/headscale/policy.hujson # phương án .deb: headscale:headscale
sudo chmod 640 /etc/headscale/policy.hujson
# Kiểm tra cú pháp và tham chiếu user/tag trước khi áp dụng (cần Headscale đang chạy; user trong policy phải tồn tại)
sudo headscale policy check --file /etc/headscale/policy.hujson
# Khai báo file policy trong config.yaml rồi khởi động lại để nạp
sudo tee -a /etc/headscale/config.yaml << 'EOF'
# Policy (ACL/grants) dạng HuJSON
policy:
mode: file
path: /etc/headscale/policy.hujson
EOF
cd /opt/headscale && docker compose restart headscale # phương án .deb: sudo systemctl restart headscale
# Kiểm tra policy đang áp dụng (chế độ file: in nội dung file)
sudo headscale policy get
Sửa policy về sau không cần restart: chỉnh file, chạy lại sudo headscale policy check --file /etc/headscale/policy.hujson, rồi nạp lại bằng tín hiệu SIGHUP: docker kill --signal=HUP headscale (phương án .deb: sudo systemctl reload headscale). Headscale ghi kết quả xử lý policy vào log sau mỗi lần nạp. headscale policy set chỉ dùng khi policy.mode: database.
Cùng rule đầu tiên viết bằng acls (dạng cũ, chuyển từ 0.23 sang): { "action": "accept", "src": ["devops@"], "dst": ["*:*", "10.11.0.0/16:*"] } — chú ý phải thêm CIDR của lab vào dst.
Muốn cho một nhóm dùng exit node (mục 10.3) thêm một grant, ví dụ { "src": ["devops@"], "dst": ["autogroup:internet"], "ip": ["*"] }; muốn tự duyệt exit node thêm "exitNode": ["tag:lab-router"] vào khối autoApprovers. Headscale 0.29 còn có khối tests và sshTests (beta) để khai báo kiểm thử tự động cho policy; xem https://headscale.net/stable/ref/policy/.
DNS và DNS Record
Thêm record DNS nội bộ · DNS Public (nếu cần remote access từ internet) · Kiểm tra MagicDNS và split DNS trên client
13.1 Thêm record DNS nội bộ
ssh [email protected]
# Pi-hole chạy trong Docker (bài 12): thêm A record bằng Admin UI → Settings → Local DNS Records
# headscale.hoatranlabs.local → 10.11.35.10
# hoặc chạy script ở bài 12 (đã có sẵn record headscale):
/opt/pihole/scripts/add_dns_records.sh
docker exec pihole pihole reloaddns
13.2 DNS Public (nếu cần remote access từ internet)
Thêm A record vào DNS public của domain:
vpn.hoatranlab.io.vn → <FortiGate WAN IP> # tên PUBLIC duy nhất, chỉ dùng cho truy cập từ Internet (nội bộ dùng headscale.hoatranlabs.local)
headscale.hoatranlabs.local, 10.11.35.10); client ngoài Internet không tin root CA nội bộ. Tên public vpn.hoatranlab.io.vn là tên công cộng thật nên dùng chứng chỉ Let's Encrypt, cấp bằng certbot theo thử thách HTTP-01 (Let's Encrypt kết nối vào cổng 80 của <WAN_IP> để xác thực). Nếu không muốn mở cổng 80 thì dùng thử thách DNS-01 (certbot cần plugin DNS của nhà cung cấp domain).
- FortiGate: mở thêm cổng 80 (chỉ phục vụ cấp và gia hạn cert, cùng cách tạo như mục 3):
curl -k -X POST "https://10.100.100.1/api/v2/cmdb/firewall/vip" \
-H "Authorization: Bearer <fortigate_api_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "VIP-Headscale-80",
"type": "static-nat",
"extip": "<WAN_IP>",
"extintf": "wan1",
"portforward": "enable",
"extport": "80",
"mappedip": [{"range": "10.11.35.10"}],
"mappedport": "80"
}'
curl -k -X POST "https://10.100.100.1/api/v2/cmdb/firewall/policy" \
-H "Authorization: Bearer <fortigate_api_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Allow-Headscale-ACME",
"srcintf": [{"name": "wan1"}],
"dstintf": [{"name": "VLAN_DMZ"}],
"srcaddr": [{"name": "all"}],
"dstaddr": [{"name": "VIP-Headscale-80"}],
"action": "accept",
"schedule": "always",
"service": [{"name": "HTTP"}],
"logtraffic": "all"
}'
- VM232: server block cổng 80 cho tên public rồi cấp cert (UFW đã mở cổng 80 ở mục 14.1):
sudo apt install -y certbot # Ubuntu 24.04: certbot 2.9.0
sudo mkdir -p /var/www/html
sudo tee /etc/nginx/sites-available/headscale-public << 'EOF'
server {
listen 80;
server_name vpn.hoatranlab.io.vn;
location /.well-known/acme-challenge/ { root /var/www/html; }
location = /generate_204 { return 204; }
location / { return 301 https://$host$request_uri; }
}
EOF
sudo ln -s /etc/nginx/sites-available/headscale-public /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
# <email_quản_trị>: email thật (Let's Encrypt kiểm tra domain của email)
sudo certbot certonly --webroot -w /var/www/html -d vpn.hoatranlab.io.vn \
-m <email_quản_trị> --agree-tos --no-eff-email \
--deploy-hook "systemctl reload nginx"
- thêm server block HTTPS dùng cert Let's Encrypt cho tên public (khối
map $connection_upgradeđã khai báo ở mục 7 nên không khai báo lại):
sudo tee -a /etc/nginx/sites-available/headscale-public << 'EOF'
server {
listen 443 ssl http2;
server_name vpn.hoatranlab.io.vn;
ssl_certificate /etc/letsencrypt/live/vpn.hoatranlab.io.vn/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/vpn.hoatranlab.io.vn/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header True-Client-IP $remote_addr;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_buffering off;
}
}
EOF
sudo nginx -t && sudo systemctl reload nginx
# Gói certbot của Ubuntu tự cài certbot.timer để gia hạn; kiểm tra bằng:
sudo certbot renew --dry-run
Client trong lab nên phân giải vpn.hoatranlab.io.vn về 10.11.35.10 (Local DNS trong Pi-hole, bài 12) để không phải đi vòng ra <WAN_IP> rồi quay lại.
Cập nhật server_url trong /etc/headscale/config.yaml:
server_url: https://vpn.hoatranlab.io.vn # URL public, chỉ đặt khi cần remote access từ Internet
cd /opt/headscale && docker compose restart headscale # phương án .deb: sudo systemctl restart headscale
server_url mới không được là miền con của dns.base_domain (vpn.hoatranlabs.local); vpn.hoatranlab.io.vn là miền khác nên hợp lệ. Client đã đăng ký bằng URL cũ phải đăng nhập lại với URL mới.
13.3 Kiểm tra MagicDNS và split DNS trên client
tailscale dns status # xem DNS do Headscale cấp: miền hoatranlabs.local → 10.11.45.53 (cần subnet route đã duyệt)
nslookup node1.hoatranlabs.local # phải ra 10.11.45.210 qua Pi-hole
tailscale status # tên MagicDNS dạng <máy>.vpn.hoatranlabs.local
Cấu hình Firewall
UFW trên VM232 · Kiểm tra FortiGate forwarding
14.1 UFW trên VM232
sudo ufw allow ssh
sudo ufw allow 80/tcp comment "HTTP redirect"
sudo ufw allow 443/tcp comment "HTTPS Headscale"
sudo ufw enable
sudo ufw status numbered
ufw allow from 10.11.45.35 .... Bài dùng ba lớp thay thế: cổng 8080 chỉ gắn vào 127.0.0.1, cổng 9090 chỉ gắn vào IP 10.11.35.10, và FortiGate chỉ cho Prometheus vào cổng này (mục 3.3). Máy khác trong cùng VLAN_DMZ không đi qua FortiGate nên vẫn truy cập được /metrics (chỉ là số liệu; trang /debug được Headscale bảo vệ riêng); cần chặn triệt để thì dùng chuỗi DOCKER-USER (https://docs.docker.com/engine/network/packet-filtering-firewalls/). Nginx (80/443) chạy trên host nên UFW lọc bình thường. Phương án .deb: thêm sudo ufw allow from 10.11.45.35 to any port 9090/tcp comment "Prometheus".
14.2 Kiểm tra FortiGate forwarding
# Từ client bên ngoài (có thể dùng điện thoại 4G)
curl -v https://vpn.hoatranlab.io.vn/health
# Expected: HTTP 200, body: {"status": "pass"}
Monitoring và Metrics
Cấu hình Prometheus scrape (trên VM235) · Kiểm tra metrics
Headscale expose Prometheus metrics tại :9090/metrics (container nghe 0.0.0.0:9090 theo metrics_listen_addr ở mục 6.1, publish ở 10.11.35.10:9090; chỉ Prometheus VM235 10.11.45.35 được phép vào qua FortiGate, mục 3.3). Từ 0.29.4 các metric http_requests_total và http_request_duration_seconds đếm đúng toàn bộ request.
15.1 Cấu hình Prometheus scrape (trên VM235)
Thêm vào /opt/prometheus/prometheus.yml:
# Thêm job này vào danh sách scrape_configs (bài 15 hiện chỉ có node_exporter 10.11.35.10:9100 của VM232 trong job vlan-dmz-vms, chưa có job headscale)
scrape_configs:
- job_name: 'headscale'
static_configs:
- targets: ['10.11.35.10:9090']
metrics_path: /metrics
metrics_listen_addr: 0.0.0.0:9090 trong container (mục 6.1) và cổng 9090 được publish ở IP của VM (mục 5.2); nếu để 127.0.0.1 thì Prometheus không scrape được. Lọc nguồn cổng này ở FortiGate (mục 3.3); phương án .deb thêm luật UFW (mục 14.1). Sau khi sửa prometheus.yml, nạp lại Prometheus theo cách ở bài 15.
15.2 Kiểm tra metrics
# Trên VM232 (cổng được publish ở IP của VM, không phải 127.0.0.1)
curl -s http://10.11.35.10:9090/metrics | grep headscale_
# Từ VM235 (kiểm tra cả policy FortiGate)
curl -s http://10.11.35.10:9090/metrics | head
Backup
Cài proxmox-backup-client trên Ubuntu 24.04 · Script sao lưu và lịch chạy
Dữ liệu cần giữ: /var/lib/headscale (db.sqlite cùng db.sqlite-wal và db.sqlite-shm, noise_private.key), /etc/headscale (config và policy.hujson) và /opt/headscale/docker-compose.yml. Script dưới đây dừng container trong vài giây (client đang kết nối P2P không bị ảnh hưởng; client mới và đổi route tạm thời chờ) để SQLite chế độ WAL nhất quán, tạo bản .tar.gz cục bộ rồi đẩy lên PBS theo quy ước file-level trong VM (bài 04 mục 5.7: user vm-backup@pbs, token vm-backup@pbs!headscale, namespace vm-headscale trong datastore syno-primary).
16.1 Cài proxmox-backup-client trên Ubuntu 24.04
# Cách chuẩn của series: repo client-only pbs-client, suite trixie, dạng deb822 + Signed-By.
# Gói proxmox-backup-client-static là bản tĩnh (chỉ phụ thuộc qrencode) nên không vướng glibc của noble.
# (Cần kiểm lại trên máy thật: apt trên Ubuntu 24.04 nhận repo suite trixie và chạy được binary static.)
sudo wget https://enterprise.proxmox.com/debian/proxmox-archive-keyring-trixie.gpg \
-O /usr/share/keyrings/proxmox-archive-keyring.gpg
sudo tee /etc/apt/sources.list.d/pbs-client.sources > /dev/null << 'EOF'
Types: deb
URIs: http://download.proxmox.com/debian/pbs-client
Suites: trixie
Components: main
Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpg
EOF
sudo apt update && sudo apt install -y proxmox-backup-client-static
16.2 Script sao lưu và lịch chạy
# Token và namespace tạo sẵn theo bài 04 mục 5.7 (ACL DatastoreBackup tại /datastore/syno-primary/vm-headscale)
sudo tee /etc/headscale-backup.env > /dev/null << 'EOF'
PBS_PASSWORD='<TOKEN_SECRET>'
PBS_FINGERPRINT='<FINGERPRINT>'
EOF
sudo chmod 600 /etc/headscale-backup.env
# <TOKEN_SECRET>: secret của token vm-backup@pbs!headscale; <FINGERPRINT>: fingerprint của pbs01 (bài 04 mục 5.3), cần khi chứng chỉ PBS là tự ký
sudo tee /opt/headscale-backup.sh << 'EOF'
#!/bin/bash
# Phương án .deb: thay 3 lệnh $COMPOSE bên dưới bằng systemctl stop/start headscale
set -euo pipefail
BACKUP_DIR="/var/backups/headscale"
DATE=$(date +%Y%m%d_%H%M%S)
COMPOSE="docker compose -f /opt/headscale/docker-compose.yml"
mkdir -p "$BACKUP_DIR"
# Dừng headscale để SQLite (WAL) nhất quán; luôn chạy lại dù có lỗi giữa chừng
trap '$COMPOSE start' EXIT
$COMPOSE stop
# 1) Bản sao cục bộ: dữ liệu (db.sqlite + -wal/-shm, khóa Noise), cấu hình + policy, file compose
tar czf "${BACKUP_DIR}/headscale_${DATE}.tar.gz" \
/var/lib/headscale \
/etc/headscale \
/opt/headscale/docker-compose.yml
# 2) Đẩy lên PBS (file-level, namespace vm-headscale)
set -a
. /etc/headscale-backup.env
set +a
proxmox-backup-client backup \
headscale-lib.pxar:/var/lib/headscale \
headscale-etc.pxar:/etc/headscale \
headscale-compose.pxar:/opt/headscale \
--repository 'vm-backup@[email protected]:syno-primary' \
--ns vm-headscale
# 3) Xóa bản cục bộ cũ hơn 30 ngày
find "$BACKUP_DIR" -name "*.tar.gz" -mtime +30 -delete
echo "Headscale backup done: ${DATE}"
EOF
sudo chmod +x /opt/headscale-backup.sh
# Cron: backup lúc 2:00 AM mỗi ngày
echo "0 2 * * * root /opt/headscale-backup.sh >> /var/log/headscale-backup.log 2>&1" | \
sudo tee /etc/cron.d/headscale-backup
Khôi phục từ bản cục bộ: cd /opt/headscale && docker compose stop, giải nén sudo tar xzf /var/backups/headscale/headscale_<DATE>.tar.gz -C /, sudo chown -R 65532:65532 /var/lib/headscale, docker compose up -d. Khôi phục từ PBS: liệt kê snapshot bằng proxmox-backup-client snapshot list --repository ... --ns vm-headscale, rồi proxmox-backup-client restore archive headscale-lib.pxar (cú pháp theo bài 04 mục 5.7). Nâng cấp phiên bản luôn sao lưu trước (mục 5.5). Chưa chạy thử trên máy thật, cần kiểm lại.
Troubleshooting
Headscale service không start · Headscale từ chối khởi động sau khi nâng cấp / hạ cấp · Client không kết nối được (connection refused port 443)
Headscale service không start
cd /opt/headscale
docker compose ps
docker compose logs --tail 100 headscale
# Lỗi thường gặp:
# - "Fatal config error ..." hoặc khóa bị bỏ (strip_email_domain, map_legacy_users, oidc.expiry, randomize_client_port): sửa theo mục 5.5
# - "permission denied" khi ghi /var/lib/headscale: sudo chown -R 65532:65532 /var/lib/headscale
# - cổng bị chiếm hoặc "cannot assign requested address" (10.11.35.10 chưa có): sudo ss -tlnp | grep -E '8080|9090'
docker compose run --rm --no-deps headscale configtest
# Nếu nghi do chạy bằng UID 65532 (mục 5.2): bỏ dòng "user:" trong docker-compose.yml, chown -R 0:0 /var/lib/headscale, docker compose up -d
Phương án .deb: sudo journalctl -u headscale -n 50 --no-pager, sudo headscale configtest.
Headscale từ chối khởi động sau khi nâng cấp / hạ cấp
Từ 0.29 Headscale chặn nhảy cóc minor và hạ cấp, và từ 0.30 chỉ chấp nhận database của 0.29.x. Quay lại bản trước bằng cách phục hồi bản sao lưu ở mục 5.5 rồi đặt tag cũ.
Client không kết nối được (connection refused port 443)
# Kiểm tra Nginx có đang chạy và listen port 443
sudo systemctl status nginx
sudo ss -tlnp | grep 443
# Test từ máy trong lab
curl -v https://headscale.hoatranlabs.local/health
# Kiểm tra container có healthy không và Nginx proxy tới đúng cổng 8080
docker compose -f /opt/headscale/docker-compose.yml ps
curl -s http://127.0.0.1:8080/health
# Kiểm tra FortiGate VIP có đúng destination không (VIP-Headscale-443 → 10.11.35.10:443)
curl -vk https://<WAN_IP>/health # chạy từ máy ngoài Internet
Client bị từ chối đăng ký vì phiên bản cũ
Headscale 0.29.5 từ chối client Tailscale cũ hơn v1.80.0. Nâng cấp client (mục 11.1) rồi đăng ký lại.
Client kết nối nhưng không ping được lab IPs
# Kiểm tra routes đã được approve chưa (cột Approved và Serving)
sudo headscale nodes list-routes
# Kiểm tra client đã accept routes chưa
tailscale status
# Force accept routes trên client Linux
tailscale set --accept-routes
# Policy: user của client có được phép vào CIDR đó không (mục 12). Từ 0.29.0 "*" không gồm 10.11.0.0/16
sudo headscale policy get
# Subnet router: IP forwarding đã bật chưa
sysctl net.ipv4.ip_forward
WireGuard UDP không xuyên qua NAT
# Kiểm tra điều kiện mạng và DERP relay trên client
tailscale netcheck
tailscale debug derp-map
# Nếu NAT strict, lưu lượng đi qua DERP công cộng của Tailscale (hoặc DERP nhúng, mục 6.4)
# Kiểm tra kết nối qua DERP hay trực tiếp
tailscale ping <peer-ip> --verbose
Node đăng ký rồi nhưng không thấy trong headscale nodes list
# Pre-auth key hết hạn, đã dùng (key mặc định chỉ dùng 1 lần) hay chưa tồn tại?
sudo headscale preauthkeys list
# Đăng ký bằng web authentication: lấy Auth ID ở trang trình duyệt của client rồi duyệt thủ công
sudo headscale auth register --user <username> --auth-id <AUTH_ID>
# Trên client, đăng ký lại sạch
sudo tailscale logout
sudo tailscale up --login-server=https://headscale.hoatranlabs.local --authkey=<preauth_key>
Lệnh CLI báo "unknown flag" hoặc "user not found" sau khi nâng cấp
Các lệnh đã đổi: preauthkeys create --user <ID> (số, không phải tên), preauthkeys list không còn --user, preauthkeys expire/delete --id, nodes delete/expire/rename --identifier, nodes list-routes và nodes approve-routes thay cho routes list/enable, auth register thay cho nodes register. Xem bảng ở mục 9.4.
Policy không áp dụng hoặc báo lỗi user
sudo headscale policy check --file /etc/headscale/policy.hujson
# Lỗi thường gặp: tên user thiếu "@" (devops thay vì devops@); user hoặc tag chưa khai báo; "*" dùng như mọi IP (mục 12)
docker kill --signal=HUP headscale # nạp lại policy; phương án .deb: sudo systemctl reload headscale
docker compose -f /opt/headscale/docker-compose.yml logs --tail 50 headscale
Cert bị từ chối (SSL handshake failure)
# Kiểm tra cert hạn dùng
openssl x509 -in /etc/ssl/headscale/headscale.crt -noout -dates
# Kiểm tra client có trust root CA không
# Trên client cần import cert root từ step-CA:
step ca root root.crt --ca-url https://step-ca.hoatranlabs.local:9000
sudo cp root.crt /usr/local/share/ca-certificates/hoatranlabs-root.crt
sudo update-ca-certificates
OIDC báo lỗi chứng chỉ khi gọi Authentik
Log container có x509: certificate signed by unknown authority nghĩa là container chưa thấy root CA step-CA: chạy sudo update-ca-certificates trên host (mục 4) rồi docker compose restart headscale (file bind mount cần restart để nhận bản mới).
Checklist Triển khai
- VM232 tạo thành công, Ubuntu Server 24.04 LTS cài xong
- Network: IP 10.11.35.10, ping gateway 10.11.35.1 và DNS 10.11.45.53 OK
- Kernel UDP buffer params cấu hình xong
- step-CA cert cấp xong tại
/etc/ssl/headscale/ - Docker Engine + Compose plugin cài xong từ kho
download.docker.com(suite noble),docker compose versiontrả về 5.x -
/opt/headscale/docker-compose.ymldùng imagedocker.io/headscale/headscale:0.29.5,/var/lib/headscalethuộc UID 65532 -
/etc/headscale/config.yamlcấu hình đúngserver_url,docker compose run --rm --no-deps headscale configtestpass -
docker compose ps→ headscaleUp ... (healthy);sudo headscale versiontrả về v0.29.5 - Port 8080 TCP (127.0.0.1) và 9090 TCP (10.11.35.10) đang listen
- Nginx config
nginx -tpass, HTTPS trả về/health= 200 - DNS record
headscale.hoatranlabs.local → 10.11.35.10trong Pi-hole - FortiGate VIP và policy tạo xong, test curl từ ngoài OK
- Policy
Allow-Prometheus-Headscale(VLAN_MGMT → VLAN_DMZ, TCP 9090) tạo xong (mục 3.3) - (Nếu dùng tên public) cert Let's Encrypt cho
vpn.hoatranlab.io.vncấp xong,certbot renew --dry-runOK (mục 13.2) - Users
hoatv,devops,remote-stafftạo xong - Pre-auth key generate xong, client Linux kết nối được (kho Tailscale deb822, bản 1.104.1 hoặc mới hơn)
- Subnet route
10.11.0.0/16approve (nodes list-routesthấy cột Serving), client ping được 10.11.45.53 - Policy HuJSON load xong (
headscale policy checkpass,headscale policy gettrả về đúng) - (Nếu dùng OIDC) Provider/Application
headscaletrên Authentik tạo xong, đăng nhậptailscale upkhông cần key thành công (mục 6.3) - UFW bật, các ports cần thiết mở (80, 443, ssh)
- Cert renewal timer chạy (
systemctl status headscale-cert-renew.timer) - Backup script test chạy OK, file
.tar.gztạo ra và snapshot xuất hiện trong namespacevm-headscaletrên PBS - Prometheus metrics scrape được (nếu đã cấu hình)