Tailscale / Headscale Network Documentation

Environment: Production

Control Plane Host: prod-bastion

Deployment Directory: /var/opt/headscale

Deployment Method: Docker Compose

Management UI: Headplane

1. Introduction

This document describes the architecture, management, and operational procedures for the SEIR's private network built using Tailscale with a self-hosted Headscale control plane and Headplane management interface.

The network provides:

Secure Zero-Trust connectivity between engineers and infrastructure
Controlled SSH access using identity-based policies
Segregated environments (Dev, Staging, Production)
Centralized access control using ACL policies
Auditable and secure remote administration

The system replaces traditional VPN access with device-level authentication and encrypted peer-to-peer communication.

All traffic is:

Encrypted using WireGuard
Authenticated using user identity
Authorized using ACL policies

2. Network

Control Plane

Headscale and Headplane are deployed on the bastion server using Docker.

Services:

headscale (control plane)
headplane (web UI)
PostgreSQL (Headscale database)
DERP / coordination services

Management URL: https://headplane.seirpk.com

Tailnet login URL: https://headscale.seirpk.com

Logical Network Topology (Current Production)

                           Internet
                               |
                               |
                     +----------------------+
                     |     prod-bastion     |
                     |----------------------|
                     |  Headscale           |
                     |  Headplane (Web UI)  |
                     +----------+-----------+
                                |
                                |
                      Tailscale / Headscale Network

----------------------------------------------------------------------------------
|                                                                                |
|                         USER WORKSTATIONS                                      |
|                                                                                |
|  bilal-admin      areej-dev        asad-dev        mahad-dev        shahid     |
|                                                                                |
----------------------------------------------------------------------------------
                                |
                                |
==================================================================================
                                |
                                |
                        PRODUCTION ENVIRONMENT

        +--------------------+        +--------------------+
        |   prod-seir-app    |        |   prod-monitoring  |
        |--------------------|        |--------------------|
        | tag:prod           |        | tag:prod           |
        | tag:servers-app    |        | Monitoring / Logs  |
        +---------+----------+        +---------+----------+
                  |                             |
                  |                             |
        +--------------------+        +--------------------+
        | prod-db-primary    |        | prod-db-replica    |
        |--------------------|        |--------------------|
        | tag:prod           |        | tag:prod           |
        | tag:servers-db     |        | tag:servers-db     |
        +---------+----------+        +---------+----------+
                  |
                  |
        +--------------------+
        |    prod-backups    |
        |--------------------|
        | tag:prod           |
        | Backup Server      |
        +--------------------+

==================================================================================
                                |
                                |
                         STAGING ENVIRONMENT

        +--------------------+
        |     stg-seir-app   |
        |--------------------|
        | tag:staging        |
        | tag:servers-app    |
        +---------+----------+
                  |
                  |
        +--------------------+        +--------------------+
        | stg-db-primary     |        | stg-db-replica     |
        |--------------------|        |--------------------|
        | tag:staging        |        | tag:staging        |
        | tag:servers-db     |        | tag:servers-db     |
        +---------+----------+        +---------+----------+
                  |
                  |
        +--------------------+
        |     stg-bastion    |
        |--------------------|
        | tag:staging        |
        | tag:stg-bastion    |
        | External Access    |
        +---------+----------+
                  |
                  |
            External AKU Team Access
                  |
        ---------------------------------
        |  SSH (22)                      |
        |  PostgreSQL (5432)             |
        ---------------------------------

==================================================================================

Environment Tags

Infrastructure is organized using tags:

Tag	Purpose
tag:prod	Production systems
tag:staging	Staging systems
tag:dev	Development systems
tag:servers-app	Application servers
tag:servers-db	Database servers

Tags are centrally managed by administrator via Headplane.

3. Headplane Overview and ACLs (Updated Access Control Model)

Access Control Philosophy

The network uses a strict role-based Zero Trust model implemented through Tailscale ACL policies managed centrally by Headplane.

Access is granted based on:

User identity group
Machine tag
Service port
SSH authorization rules

Machine tags are the primary mechanism used to define infrastructure roles and enforce access control boundaries.

For example:

tag:prod identifies production systems
tag:staging identifies staging systems
tag:servers-db identifies database servers
tag:servers-app identifies application servers
tag:stg-bastion identifies the controlled entry point for external collaborators (AKU AI Team)
tag:dev identifies development environment servers

Users never receive direct network-wide access.

Instead, they are granted permission to interact only with machines whose tags match allowed policies.

This design allows infrastructure changes without modifying user permissions.

Current Machine Inventory

Tailscale IP	Machine Name	Owner	Platform	Role / Tag
100.64.0.2	bilal-admin	bilal.ghouri	macOS	Admin workstation
100.64.0.9	areej-dev	areej.ilyas	macOS	Developer workstation
100.64.0.11	asad-dev	asad.hussain	macOS	Developer workstation
100.64.0.7	bilal-dev	bilalghouri	macOS	Developer workstation
100.64.0.10	mahad-dev	mahad.ahmed	macOS	Developer workstation
100.64.0.6	prod-backups	admin	Linux	Backup server (tag:prod)
100.64.0.3	prod-db-primary	admin	Linux	Database Primary (tag:prod, tag:servers-db)
100.64.0.4	prod-db-replica	admin	Linux	Database Replica (tag:prod, tag:servers-db)
100.64.0.16	prod-monitoring	admin	Linux	Monitoring server (tag:prod)
100.64.0.5	prod-seir-app	admin	Linux	Application server (tag:prod, tag:servers-app)
100.64.0.8	shahid-rasool	shahidrasool	Windows	Admin workstation
100.64.0.12	stg-bastion	admin	Linux	Staging gateway (tag:staging, tag:stg-bastion)
100.64.0.14	stg-db-primary	admin	Linux	Staging DB Primary (tag:staging, tag:servers-db)
100.64.0.15	stg-db-replica	admin	Linux	Staging DB Replica (tag:staging, tag:servers-db)
100.64.0.13	stg-seir-app	admin	Linux	Staging application server (tag:staging, tag:servers-app)
100.64.0.17	usva-testing	usva.suleman	Android	QA device

User Groups (Current)

The following identity groups define access privileges:

group:root

System owner with full administrative authority.

group:admin

Infrastructure administrators responsible for system operations.

Privileges:

SSH to all production, staging, and development systems through ubuntu (root level) user.
Full database server access
Tag assignment and infrastructure control

group:dev

Software engineers and developers.

Privileges:

SSH to development and staging systems
Restricted SSH access to production application server only through dev user with elevated sudo access using their password.
Controlled database access on prod servers, no SSH, only port 3306.

group:qa

Quality assurance testers.

Privileges:

Application testing access via HTTP/HTTPS
No SSH access to any server
Device-to-device connectivity

group:external-aku

External AI research team with tightly scoped staging access.

Privileges:

SSH access only to staging bastion
PostgreSQL access to staging environment
No production access

External Collaboration Security Model

External partners never receive direct access to production systems.

Instead:

External User → Connects to stg-bastion → Accesses staging database

Ports allowed: 22 SSH 5432 PostgreSQL

All other infrastructure remains isolated.

Device-to-Device Communication

Internal users can communicate directly with each other's logged-in machines.

This enables:

Remote troubleshooting
Peer development collaboration
Secure file transfer

Infrastructure servers remain protected by tag-based restrictions.

SSH Authorization Model

SSH access is managed by Tailscale identity certificates.

Access is granted only when:

User Group matches

AND

Machine Tag matches

AND

Allowed system user matches (dev or ubuntu)

Example Authorization Logic

Developer attempting:

ssh dev@prod-seir-app

Evaluation:

User Group → group:dev

Destination Tag → tag:servers-app

Allowed User → dev

Result: Access Allowed

What is Headplane

Headplane is the web-based administrative interface used to manage the Headscale network.

It provides:

User management
Device visibility
Tag assignment
Node approval
Policy inspection
Troubleshooting

Accessing Headplane

Open in browser:

https://headplane.seirpk.com

Tag Ownership

Only administrators can assign infrastructure tags.

tag:prod

tag:staging

tag:dev

tag:servers-app

tag:servers-db

Owned by:

group:admin

Usage Guides

4.1 Onboarding a New User

Step 1 — Create user in Headplane

Then:

Users → Create User

Assign:

Email
Group

Example:

User:

bilal.ghouri@seirpk.com

Group:

group:dev

Step 2 — Install Tailscale on client device

Official guide:

https://tailscale.com/download

Supported platforms:

macOS
Windows
Linux

Step 3 — Login to Network

User runs:

tailscale up \
  --login-server https://headscale.seirpk.com

An authorization key will be generated.

Administrator then registers the client's node by entering the authorization key provided by the client.

Step 4 — Verify Connection

Client runs:

tailscale status

4.2 Onboarding a New Server

Step 1 — Install Tailscale

curl -fsSL https://tailscale.com/install.sh | sh

Step 2 — Connect Server to Headscale

tailscale up \
  --login-server https://headscale.seirpk.com \
  --advertise-tags tag:prod

An authorization key will be generated.

Step 3 — Approve Node

Administrator registers the client's node by entering the authorization key provided by the client.

Step 4 — Verify Tag

Run:

tailscale status

4.3 SSH Into a Server

tailscale ssh ubuntu@server-name

Examples:

tailscale ssh ubuntu@prod-seir-app

tailscale ssh dev@stg-seir-app

4.4 Troubleshooting

Check connection:

tailscale status

Restart service:

sudo systemctl restart tailscaled

Headscale / Headplane Operations

All services are deployed using Docker Compose on the bastion host.

Start Services

cd /var/opt/headscale
docker compose up -d

Restart Services

cd /var/opt/headscale
docker compose restart

View Logs

docker compose logs -f

Official Documentation

Tailscale Documentation: https://tailscale.com/docs

Headscale Documentation: https://headscale.net

Headplane Documentation: https://github.com/tale/headplane

1. Introduction

2. Network

Control Plane​

Logical Network Topology (Current Production)​

Environment Tags​

3. Headplane Overview and ACLs (Updated Access Control Model)

Access Control Philosophy​

Current Machine Inventory​

User Groups (Current)​

group:root​

group:admin​

group:dev​

group:qa​

group:external-aku​

External Collaboration Security Model​

Device-to-Device Communication​

SSH Authorization Model​

Example Authorization Logic​

What is Headplane​

Accessing Headplane​

Tag Ownership​

Usage Guides

4.1 Onboarding a New User

4.2 Onboarding a New Server

4.3 SSH Into a Server

4.4 Troubleshooting

Headscale / Headplane Operations

Start Services​

Restart Services​

View Logs​

Official Documentation

Control Plane

Logical Network Topology (Current Production)

Environment Tags

Access Control Philosophy

Current Machine Inventory

User Groups (Current)

group:root

group:admin

group:dev

group:qa

group:external-aku

External Collaboration Security Model

Device-to-Device Communication

SSH Authorization Model

Example Authorization Logic

What is Headplane

Accessing Headplane

Tag Ownership

Start Services

Restart Services

View Logs