System & Network Headscale VPN
Bài 20 · Giai đoạn 3 — Bảo mật & Truy cập

Triển khai Headscale Mesh VPN

Mesh VPN nội bộ — kết nối an toàn mọi VM qua Tailscale protocol.

VM232 · node2 Ubuntu Server 24.04 LTS 10.11.35.10 2 vCPU · 2 GB · 20 GB

Bối cảnh & Lý do triển khai

Vị trí trong chuỗi bài: Bài 20 thuộc Giai đoạn 3 — Bảo mật & Truy cập, nối tiếp Bài 19. Vaultwarden và đứng trước Bài 21. Harbor OCI Registry.
Mức độ cần thiết: 🟡 Quan trọng — Remote access zero-trust không cần mở port

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ụcNội dung
Ứng dụng trong DNRemote 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ínhWireGuard 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 khaiPhả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 đâyAdmin 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ủIPVLAN · NodeVai trò trong bài này
headscale (Headscale VPN) · VM23210.11.35.1035 (DMZ) · node2Má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.21145 (MGMT) · cluster HOATRANHUBNode Proxmox chứa VM232; tạo VM tại đây.
FortiGate (firewall)10.100.100.1Quản trị 10.100.100.0/24 · thiết bị mạngPort 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) · VM24210.11.25.4225 (SEC) · node1Cấ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) · VM24710.11.45.5345 (MGMT) · node3DNS 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) · VM23510.11.45.3545 (MGMT) · node2Scrape 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) · VM23410.11.25.4025 (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) · VM10110.11.45.1745 (MGMT) · node4Nhậ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) · VM29010.11.45.2045 (MGMT) · node2Ví 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.

01

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ínhGiá trị
VMID232
Hostnameheadscale
Nodenode2 (10.11.45.211)
VLANVLAN_DMZ tag=35
IP10.11.35.10/24
Gateway10.11.35.1
DNS10.11.45.53 (Pi-hole)
vCPU2
RAM2 GB
Disk20 GB (vm-ceph)
OSUbuntu Server 24.04 LTS (24.04.5)

Phương án triển khai:

Phương ánCách chạy HeadscaleKhi nào chọnGhi 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 + systemdapt 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 VMGó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ềnContainer LXC Ubuntu 24.04 (pct create ... --unprivileged 1, rootfs trên vm-ceph) cài gói .debMuố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
Đang chạy Headscale 0.23.0? Không nâng thẳng lên 0.29.5: Headscale bắt buộc nâng từng minor (0.24 → 0.25 → 0.26 → 0.27 → 0.28 → 0.29), sao lưu 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ầnPhiên bảnGhi chú
Ubuntu Server24.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
Headscale0.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 + ComposeDocker 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
Nginx1.24.0 (kho Ubuntu noble)Dùng listen 443 ssl http2; (http2 on; cần Nginx 1.25.1 trở lên)
step-cli0.31.0Gói .deb từ GitHub smallstep/cli
Tailscale client1.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
certbot2.9.0 (kho Ubuntu noble)Chỉ dùng cho tên public ở mục 13.2
proxmox-backup-clientproxmox-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_exporter1.12.1Cài bằng script ở bài 15

Ports:

PortProtocolMục đích
443TCPHTTPS control plane (qua Nginx trên host)
80TCPNginx: 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)
8080TCPHeadscale HTTP: container chỉ publish ở 127.0.0.1 để Nginx proxy vào
9090TCPPrometheus 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)
50443TCPgRPC của CLI từ xa: chỉ nghe localhost trong container, KHÔNG publish; CLI cục bộ dùng unix socket
3478UDPSTUN, 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ở
Server Headscale chỉ cần mở HTTPS (443/TCP) ra ngoài. Cổng 41641/UDP là cổng WireGuard của từng client Tailscale (kết nối P2P giữa các client), server Headscale không listen cổng này; STUN 3478/UDP chỉ cần khi bật DERP nhúng (derp.server.enabled), còn bài này dùng DERP công cộng của Tailscale.
02

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)

1
Đăng nhập Proxmox Web UI → chọn Node: node2 → nhấn Create VM (góc trên phải)
2
General:
  • VM ID: 232
  • Name: headscale
  • Bỏ tick Start after created
3
OS:
  • 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
4
System:
  • Machine: q35
  • SCSI Controller: VirtIO SCSI single
  • BIOS: SeaBIOS
  • Qemu Agent: ☑
5
Disks:
  • Bus/Device: SCSI 0, Storage: vm-ceph
  • Disk size: 20 GiB, Cache: Write back, Discard: ☑
6
CPU:
  • Sockets: 1, Cores: 2, Type: x86-64-v2-AES
7
Memory:
  • Memory (MiB): 2048
8
Network:
  • Bridge: vmbr0, VLAN Tag: 35, Model: VirtIO (paravirtualized), Firewall: ☐
9
Confirm: Xem lại → Finish → Start VM → Console để bắt đầu cài Ubuntu.
Proxmox Create VM → tab Confirm: VM 232 headscale trên node2, 2 core, 2048 MiB, đĩa vm-ceph 20 GiB, VLAN tag 35 (VLAN_DMZ).
Proxmox Create VM → tab Confirm: VM 232 headscale trên node2, 2 core, 2048 MiB, đĩa vm-ceph 20 GiB, VLAN tag 35 (VLAN_DMZ).

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ặc enp6s18 trên VM q35; kiểm tra bằng ip -br link): Manual → IP 10.11.35.10/24, GW 10.11.35.1, DNS 10.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
03

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"
  }'
FortiGate GUI → Policy & Objects → Virtual IPs: VIP-Headscale-443 (static NAT, interface wan1, TCP 443 ánh xạ tới 10.11.35.10:443), vừa tạo bằng API.
FortiGate GUI → Policy & Objects → Virtual IPs: VIP-Headscale-443 (static NAT, interface wan1, TCP 443 ánh xạ tới 10.11.35.10:443), vừa tạo bằng API.

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"
  }'
FortiGate GUI → Policy & Objects → Firewall Policy: Allow-Headscale-Inbound, wan1 → VLAN_DMZ, đích VIP-Headscale-443, service HTTPS, action ACCEPT.
FortiGate GUI → Policy & Objects → Firewall Policy: Allow-Headscale-Inbound, wan1 → VLAN_DMZ, đích VIP-Headscale-443, service HTTPS, action ACCEPT.

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"
  }'
04

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
Cert này chỉ do Nginx trên host dùng (Nginx kết thúc TLS, mục 7); Headscale nghe HTTP nội bộ nên không cần đọc file cert. Lệnh 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).
05

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
Terminal VM232: sau khi tạo /opt/headscale/docker-compose.yml, ls -ln /var/lib/headscale cho thấy thư mục thuộc UID 65532 và cat docker-compose.yml hiển thị image docker.io/headscale/headscale:0.29.5.
Terminal VM232: sau khi tạo /opt/headscale/docker-compose.yml, ls -ln /var/lib/headscale cho thấy thư mục thuộc UID 65532 và cat docker-compose.yml hiển thị image docker.io/headscale/headscale:0.29.5.

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ụcDocker (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 container127.0.0.1:8080 / 0.0.0.0:9090
trusted_proxies (mục 6.1)để trống127.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 640headscale:headscale, mode 640
Khởi động / restart (mục 8)docker compose up -d / docker compose restart headscalesystemctl enable --now headscale / systemctl restart headscale
Nạp lại policy (mục 12)docker kill --signal=HUP headscalesystemctl reload headscale
Logdocker compose logs headscalejournalctl -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
CLIwrapper /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:

  1. Đọc ghi chú phát hành của bản đích (https://github.com/juanfont/headscale/releases và CHANGELOG.md).
  2. 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
  1. Đổi tag image sang bản kế tiếp trong /opt/headscale/docker-compose.yml (hoặc cài .deb của bản đó, chọn giữ config.yaml hiện tại khi dpkg hỏi), rồi docker compose pull && docker compose up -d.
  2. Đối chiếu config.yaml với config-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 tra docker 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ênCần làm / thay đổi chính
0.24.3Ngườ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.1Luồ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.1Policy 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.1Migration 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.0Tag 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.5Ký 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.

06

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ự:

  1. 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 flow default-provider-authorization-implicit-consent, Client type Confidential, Redirect URIs kiểu Strict, loại Authorization: https://headscale.hoatranlabs.local/oidc/callback (nếu đã đổi server_url sang tên public ở mục 13.2 thì dùng https://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: Name Headscale, Slug headscale (khớp issuer ở mục 6.1), Provider headscale-oidc, Launch URL https://headscale.hoatranlabs.local. Ghi lại Client ID và Client Secret.
  2. Trên VM232: bỏ comment khối oidc: trong /etc/headscale/config.yaml, điền client_id và client_secret vừa ghi (hoặc để secret ngoài file: client_secret_path, hoặc biến môi trường HEADSCALE_OIDC_CLIENT_SECRET), rồi cd /opt/headscale && docker compose restart headscale và kiểm tra bằng docker compose logs --tail 50 headscale | grep -i oidc (phương án .deb: systemctl restart headscale và journalctl -u headscale -n 30 --no-pager | grep -i oidc). Từ 0.29.4, oidc.issuer sai hoặc thiếu client_id/client_secret làm Headscale không khởi động.
  3. 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à claim preferred_username của Authentik (thường là username, ví dụ akadmin), thay cho lệnh headscale 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ì đặt email_verified_required: false. Bộ lọc tùy chọn: allowed_domains, allowed_users, allowed_groups (tên nhóm Authentik, claim groups nằm trong scope profile; 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ằng headscale users rename trướ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 (rule Allow-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.

07

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
08

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
Terminal VM232: docker compose ps hiện headscale ở trạng thái Up (healthy), sudo headscale version trả về v0.29.5 và sudo headscale nodes list chạy không lỗi.
Terminal VM232: docker compose ps hiện headscale ở trạng thái Up (healthy), sudo headscale version trả về v0.29.5 và sudo headscale nodes list chạy không lỗi.

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.

09

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>
Terminal VM232: sudo headscale preauthkeys list: key dùng 1 lần (Reusable=false) hết hạn sau 24h thuộc remote-staff, và key gắn tag:lab-router của subnet router (che bớt key).
Terminal VM232: sudo headscale preauthkeys list: key dùng 1 lần (Reusable=false) hết hạn sau 24h thuộc remote-staff, và key gắn tag:lab-router của subnet router (che bớt key).

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àmLệ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 nodesudo headscale nodes rename --identifier <ID> <tên-mới>
Xóa nodesudo headscale nodes delete --identifier <ID>
Gắn tag cho nodesudo headscale nodes tag --identifier <ID> --tags tag:lab-router
Xem / duyệt routesudo 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>.

10

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
Terminal VM232: sudo headscale nodes list-routes hiện route 10.11.0.0/16 của node lab ở cột Approved và Serving (Primary) sau khi approve-routes.
Terminal VM232: sudo headscale nodes list-routes hiện route 10.11.0.0/16 của node lab ở cột Approved và Serving (Primary) sau khi approve-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>
11

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à đặt server_url sang 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
Terminal client: tailscale ip cấp IP 100.64.x.x, ping 10.11.45.53 và 10.11.25.43 qua VPN thành công, tailscale status liệt kê peer.
Terminal client: tailscale ip cấp IP 100.64.x.x, ping 10.11.45.53 và 10.11.25.43 qua VPN thành công, tailscale status liệt kê peer.
12

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ó @: user devops viết devops@.
  • Từ 0.29.0, * chỉ là dải tailnet (100.64.0.0/10 và 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 lab 10.11.0.0/16 qua 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ùng autogroup:danger-all (chỉ làm nguồn) hoặc CIDR cụ thể.
  • proto:icmp/icmp chỉ gồm ICMPv4; ICMPv6 dùng ipv6-icmp.
  • Không có policy thì cho phép mọi lưu lượng; đã khai báo grants/acls thì 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
Terminal VM232: headscale policy check báo Policy is valid; sau khi khai báo policy.path trong config.yaml và restart container, headscale policy get in ra nội dung policy.hujson (grants cho hoatv/devops, remote-staff, DNS và ICMP).
Terminal VM232: headscale policy check báo Policy is valid; sau khi khai báo policy.path trong config.yaml và restart container, headscale policy get in ra nội dung policy.hujson (grants cho hoatv/devops, remote-staff, DNS và ICMP).

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/.

13

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)
Lưu ý: chứng chỉ step-CA ở mục 4 chỉ dùng cho tên nội bộ (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).
  1. 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"
  }'
  1. 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"
  1. 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
14

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
Docker và UFW: cổng container được publish đi qua chuỗi riêng của Docker và bỏ qua luật UFW (tài liệu Docker), nên cổng 9090 không thể giới hạn nguồn bằng 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"}
Máy ngoài mạng (điện thoại 4G): curl -v https://vpn.hoatranlab.io.vn/health trả HTTP 200 và body {"status": "pass"}.
Máy ngoài mạng (điện thoại 4G): curl -v https://vpn.hoatranlab.io.vn/health trả HTTP 200 và body {"status": "pass"}.
15

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
Prometheus nằm ở VM235 (khác VM232) nên cần 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
16

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.

17

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).

18

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 version trả về 5.x
  • /opt/headscale/docker-compose.yml dùng image docker.io/headscale/headscale:0.29.5, /var/lib/headscale thuộc UID 65532
  • /etc/headscale/config.yaml cấu hình đúng server_url, docker compose run --rm --no-deps headscale configtest pass
  • docker compose ps → headscale Up ... (healthy); sudo headscale version trả về v0.29.5
  • Port 8080 TCP (127.0.0.1) và 9090 TCP (10.11.35.10) đang listen
  • Nginx config nginx -t pass, HTTPS trả về /health = 200
  • DNS record headscale.hoatranlabs.local → 10.11.35.10 trong 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.vn cấp xong, certbot renew --dry-run OK (mục 13.2)
  • Users hoatv, devops, remote-staff tạ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/16 approve (nodes list-routes thấy cột Serving), client ping được 10.11.45.53
  • Policy HuJSON load xong (headscale policy check pass, headscale policy get trả về đúng)
  • (Nếu dùng OIDC) Provider/Application headscale trên Authentik tạo xong, đăng nhập tailscale up khô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.gz tạo ra và snapshot xuất hiện trong namespace vm-headscale trên PBS
  • Prometheus metrics scrape được (nếu đã cấu hình)
Zalo