The source post captures the core pieces needed to make a Tailscale Docker client on ZimaOS register with a self-hosted Headscale control plane: persistent state, a one-time/pre-auth key, the custom Headscale URL, TUN access, and the required container capabilities.
Current Tailscale and Headscale documentation now provide a clearer upstream contract. Tailscale officially supports a custom control server URL, and Headscale documents both interactive registration and pre-auth-key registration. Use those upstream methods to validate the current command/URL rather than relying only on a 2025 screenshot.
Headscale Replaces the Tailscale Coordination Control Plane
Headscale is a self-hosted implementation of the Tailscale control server protocol. Tailscale clients still create encrypted peer-to-peer tunnels, but registration and coordination are handled by the user's Headscale instance instead of the default Tailscale control plane.
Persist the Tailscale State Directory
The source created /DATA/AppData/tailscale/state and mapped it to /var/lib/tailscale. This is important because the node identity/state should survive container recreation and host reboot.
The source also recommended restrictive permissions on the host state directory. That is sensible because the state is part of the node's identity and should not be world-readable.
Use the Headscale URL as the Custom Control Server
Current Tailscale documentation supports custom control servers through:
tailscale login --login-server=<URL>Headscale 자체 문서에서도 다음과 같은 방식을 사용합니다. tailscale up --login-server <YOUR_HEADSCALE_URL>.
Tailscale의 최신 사용자 지정 제어 서버 안내를 참조하세요.
비대화형 등록에 사전 인증 키 사용
소스에서는 일시적으로 다음을 추가했습니다. TS_AUTHKEY노드를 등록한 후 변수를 삭제했습니다. 현재 Headscale 문서에서는 사전 인증 키를 생성하고 이를 다음과 함께 사용하는 방법을 설명합니다. --authkey 비대화형 등록을 위해 사용합니다.
Headscale의 현재 등록 방법을 사용하세요.
재사용 가능한 인증 키를 앱 정의에 남겨 두지 마세요
키를 재사용할 수 있거나 수명이 긴 경우, ZimaOS 앱 환경에 남겨 두면 불필요하게 노출됩니다. 노드 ID가 성공적으로 저장된 후 등록 비밀 키가 더 이상 필요하지 않다면 제거하세요.
키를 공개 포럼이나 스크린샷에 붙여 넣었다면 해당 키를 폐기하고 새 키를 만드세요.
커널 TUN과 기능은 네트워킹 모드에 영향을 줍니다
소스는 다음을 매핑합니다 /dev/net/tun 그리고 다음을 부여합니다 NET_ADMIN/NET_RAW이는 순수한 사용자 공간 네트워킹이 아니라 커널 네트워킹 방식입니다.
현재 Tailscale 컨테이너는 사용자 공간 모드로도 작동할 수 있으므로, 서브넷 라우팅, 출구 노드 동작 또는 완전한 커널 네트워킹이 필요한지에 따라 모드를 신중하게 선택하세요.
호스트 네트워킹은 강력합니다
소스에서는 Docker 호스트 네트워킹을 사용합니다. 이 방식은 일반적인 컨테이너 포트 격리를 제거하고 Tailscale이 호스트 네트워크 네임스페이스에서 직접 작동하도록 합니다.
현재 Tailscale 앱이 경로, 리스너, 광고된 서비스를 저장하는 방식을 이해하지 못한 상태에서 호스트 네트워크와 브리지 네트워크를 서로 변경하지 마세요.
Headscale URL은 안정적으로 연결 가능하고 적절히 보호되어야 합니다
자체 호스팅 제어 서버는 핵심 인프라가 됩니다. 안정적인 DNS, 유효한 TLS 구성, Headscale 데이터베이스/구성의 백업을 사용하세요. 제어 서버가 사라지면 기존 피어는 일시적으로 계속 통신할 수 있지만, 새 등록과 조정 변경은 사용할 수 없게 됩니다.
소스는 작동하는 하나의 구성일 뿐, IceWhale의 지원 계약이 아닙니다
해당 게시물에는 IceWhale 직원의 확인이 없습니다. 이는 커뮤니티에서 작성한 구성으로, Tailscale/Headscale의 업스트림 개념과 잘 부합하지만 현재 ZimaOS Tailscale 패키지에서 테스트해야 합니다.
ZimaOS의 Headscale FAQ
Tailscale 클라이언트가 사용자 지정 Headscale 제어 서버를 사용할 수 있나요?
예. 현재 Tailscale 문서에서는 사용자 지정 제어 서버 URL을 공식적으로 지원합니다.
TS_AUTHKEY를 앱에 영구적으로 남겨 두어야 하나요?
아니요. 소스에서는 등록 후 해당 항목을 제거했으며, 장기간 사용하는 등록 비밀 키를 불필요하게 노출된 상태로 두어서는 안 됩니다.
왜 /var/lib/tailscale을 유지해야 하나요?
컨테이너를 다시 만들거나 재부팅해도 노드의 Tailscale ID/상태를 유지합니다.
