Coordination server (HCS)

The coordination server (HCS) connects zones via a mesh VPN and hosts shared services. It is a small public server (a VPS is sufficient).

Declare the HCS

Enable coordination and declare the host profile: hcs:

etc/config.yaml

network:
  coordination:
    enable: true
    hostname: "hcs"
    domain: "headscale"          # → headscale.domain.tld

hosts:
  - hostname: "hcs"
    name: "Coordination server"
    profile: "hcs"
    ipv4:
      external: "203.0.113.10"   # Public IP of the VPS
      internal: "100.64.0.2"     # IP in the tailnet
    services:
      headscale:                 # VPN coordination
      idm:                       # identities (Kanidm)
      vaultwarden:               # vault

Installation follows the same procedure as a gateway (just install / configure / apply).

Global services

A service marked global: true is exposed on the HCS with a public DNS (<name>.domain.tld): it is reachable from anywhere, including the Internet.

    services:
      forgejo:
        domain: "git"
        global: true             # → https://git.domain.tld

Create a user account

Each user will have…

• An identifier and a master password (vault).
• An authentication key for all services (SSO).
• A recovery password in case the key is lost.

1. Create the system account

   Add the user in etc/config.yaml, then generate, commit, and apply:

   etc/config.yaml

   users:
     bob:
       uid: 1001
       name: "Bob"
       profile: "normal"
       groups: ["global"]

   POSIX account (optional)

   This declaration creates an account on designated Linux machines. Users can also be created only in Vaultwarden and Kanidm.

2. Vaultwarden account

   1. Admin: send an invitation.
   2. User: receives an email to set their master password.
   3. Admin: confirm the user.

3. Kanidm account (on the HCS)

   just enter hcs
   kanidm person credential create-reset-token <login> --name idm_admin

   Forward the link or QR code to the user, who creates their key and recovery password.

4. Bitwarden

   Installing Bitwarden on browsers and smartphones simplifies access.

   Be sure to choose “self-hosted”

   Enter the Vaultwarden URL before the master password, otherwise it goes to bitwarden.com!

5. Service access

   SSO opens all services with a single authentication. Rights are defined by Kanidm groups.

Connect from outside

Outside a zone, access to services goes through a Tailscale VPN client, validated by the administrator.

1. User side

   • Install the Tailscale client.
   • Request to join the network headscale.domain.tld.

2. Admin side

   just enter hcs
   
   # Reusable temporary key (multiple clients)
   sudo headscale preauthkeys create --reusable --expiration 1h --user 1
   
   # Or validate an already connected client
   sudo headscale nodes register --key <key> --user nix