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と状態を保持します。
