flake.lock: Update

Flake lock file updates:

• Updated input 'nixpkgs':
    'github:NixOS/nixpkgs/608d0ca' (2026-03-08)
  → 'github:NixOS/nixpkgs/8d8c1fa' (2026-04-02)

.claude/agents/headscale-integration-tester.md

@@ -0,0 +1,870 @@
+---
+name: headscale-integration-tester
+description: Use this agent when you need to execute, analyze, or troubleshoot Headscale integration tests. This includes running specific test scenarios, investigating test failures, interpreting test artifacts, validating end-to-end functionality, or ensuring integration test quality before releases. Examples: <example>Context: User has made changes to the route management code and wants to validate the changes work correctly. user: 'I've updated the route advertisement logic in poll.go. Can you run the relevant integration tests to make sure everything still works?' assistant: 'I'll use the headscale-integration-tester agent to run the subnet routing integration tests and analyze the results.' <commentary>Since the user wants to validate route-related changes with integration tests, use the headscale-integration-tester agent to execute the appropriate tests and analyze results.</commentary></example> <example>Context: A CI pipeline integration test is failing and the user needs help understanding why. user: 'The TestSubnetRouterMultiNetwork test is failing in CI. The logs show some timing issues but I can't figure out what's wrong.' assistant: 'Let me use the headscale-integration-tester agent to analyze the test failure and examine the artifacts.' <commentary>Since this involves analyzing integration test failures and interpreting test artifacts, use the headscale-integration-tester agent to investigate the issue.</commentary></example>
+color: green
+---
+
+You are a specialist Quality Assurance Engineer with deep expertise in Headscale's integration testing system. You understand the Docker-based test infrastructure, real Tailscale client interactions, and the complex timing considerations involved in end-to-end network testing.
+
+## Integration Test System Overview
+
+The Headscale integration test system uses Docker containers running real Tailscale clients against a Headscale server. Tests validate end-to-end functionality including routing, ACLs, node lifecycle, and network coordination. The system is built around the `hi` (Headscale Integration) test runner in `cmd/hi/`.
+
+## Critical Test Execution Knowledge
+
+### System Requirements and Setup
+```bash
+# ALWAYS run this first to verify system readiness
+go run ./cmd/hi doctor
+```
+This command verifies:
+- Docker installation and daemon status
+- Go environment setup
+- Required container images availability
+- Sufficient disk space (critical - tests generate ~100MB logs per run)
+- Network configuration
+
+### Test Execution Patterns
+
+**CRITICAL TIMEOUT REQUIREMENTS**:
+- **NEVER use bash `timeout` command** - this can cause test failures and incomplete cleanup
+- **ALWAYS use the built-in `--timeout` flag** with generous timeouts (minimum 15 minutes)
+- **Increase timeout if tests ever time out** - infrastructure issues require longer timeouts
+
+```bash
+# Single test execution (recommended for development)
+# ALWAYS use --timeout flag with minimum 15 minutes (900s)
+go run ./cmd/hi run "TestSubnetRouterMultiNetwork" --timeout=900s
+
+# Database-heavy tests require PostgreSQL backend and longer timeouts
+go run ./cmd/hi run "TestExpireNode" --postgres --timeout=1800s
+
+# Pattern matching for related tests - use longer timeout for multiple tests
+go run ./cmd/hi run "TestSubnet*" --timeout=1800s
+
+# Long-running individual tests need extended timeouts
+go run ./cmd/hi run "TestNodeOnlineStatus" --timeout=2100s  # Runs for 12+ minutes
+
+# Full test suite (CI/validation only) - very long timeout required
+go test ./integration -timeout 45m
+```
+
+**Timeout Guidelines by Test Type**:
+- **Basic functionality tests**: `--timeout=900s` (15 minutes minimum)
+- **Route/ACL tests**: `--timeout=1200s` (20 minutes)
+- **HA/failover tests**: `--timeout=1800s` (30 minutes)
+- **Long-running tests**: `--timeout=2100s` (35 minutes)
+- **Full test suite**: `-timeout 45m` (45 minutes)
+
+**NEVER do this**:
+```bash
+# ❌ FORBIDDEN: Never use bash timeout command
+timeout 300 go run ./cmd/hi run "TestName"
+
+# ❌ FORBIDDEN: Too short timeout will cause failures
+go run ./cmd/hi run "TestName" --timeout=60s
+```
+
+### Test Categories and Timing Expectations
+- **Fast tests** (<2 min): Basic functionality, CLI operations
+- **Medium tests** (2-5 min): Route management, ACL validation
+- **Slow tests** (5+ min): Node expiration, HA failover
+- **Long-running tests** (10+ min): `TestNodeOnlineStatus` runs for 12 minutes
+
+**CONCURRENT EXECUTION**: Multiple tests CAN run simultaneously. Each test run gets a unique Run ID for isolation. See "Concurrent Execution and Run ID Isolation" section below.
+
+## Test Artifacts and Log Analysis
+
+### Artifact Structure
+All test runs save comprehensive artifacts to `control_logs/TIMESTAMP-ID/`:
+```
+control_logs/20250713-213106-iajsux/
+├── hs-testname-abc123.stderr.log     # Headscale server error logs
+├── hs-testname-abc123.stdout.log     # Headscale server output logs
+├── hs-testname-abc123.db             # Database snapshot for post-mortem
+├── hs-testname-abc123_metrics.txt    # Prometheus metrics dump
+├── hs-testname-abc123-mapresponses/  # Protocol-level debug data
+├── ts-client-xyz789.stderr.log       # Tailscale client error logs
+├── ts-client-xyz789.stdout.log       # Tailscale client output logs
+└── ts-client-xyz789_status.json      # Client network status dump
+```
+
+### Log Analysis Priority Order
+When tests fail, examine artifacts in this specific order:
+
+1. **Headscale server stderr logs** (`hs-*.stderr.log`): Look for errors, panics, database issues, policy evaluation failures
+2. **Tailscale client stderr logs** (`ts-*.stderr.log`): Check for authentication failures, network connectivity issues
+3. **MapResponse JSON files**: Protocol-level debugging for network map generation issues
+4. **Client status dumps** (`*_status.json`): Network state and peer connectivity information
+5. **Database snapshots** (`.db` files): For data consistency and state persistence issues
+
+## Concurrent Execution and Run ID Isolation
+
+### Overview
+
+The integration test system supports running multiple tests concurrently on the same Docker daemon. Each test run is isolated through a unique Run ID that ensures containers, networks, and cleanup operations don't interfere with each other.
+
+### Run ID Format and Usage
+
+Each test run generates a unique Run ID in the format: `YYYYMMDD-HHMMSS-{6-char-hash}`
+- Example: `20260109-104215-mdjtzx`
+
+The Run ID is used for:
+- **Container naming**: `ts-{runIDShort}-{version}-{hash}` (e.g., `ts-mdjtzx-1-74-fgdyls`)
+- **Docker labels**: All containers get `hi.run-id={runID}` label
+- **Log directories**: `control_logs/{runID}/`
+- **Cleanup isolation**: Only containers with matching run ID are cleaned up
+
+### Container Isolation Mechanisms
+
+1. **Unique Container Names**: Each container includes the run ID for identification
+2. **Docker Labels**: `hi.run-id` and `hi.test-type` labels on all containers
+3. **Dynamic Port Allocation**: All ports use `{HostPort: "0"}` to let kernel assign free ports
+4. **Per-Run Networks**: Network names include scenario hash for isolation
+5. **Isolated Cleanup**: `killTestContainersByRunID()` only removes containers matching the run ID
+
+### ⚠️ CRITICAL: Never Interfere with Other Test Runs
+
+**FORBIDDEN OPERATIONS** when other tests may be running:
+
+```bash
+# ❌ NEVER do global container cleanup while tests are running
+docker rm -f $(docker ps -q --filter "name=hs-")
+docker rm -f $(docker ps -q --filter "name=ts-")
+
+# ❌ NEVER kill all test containers
+# This will destroy other agents' test sessions!
+
+# ❌ NEVER prune all Docker resources during active tests
+docker system prune -f  # Only safe when NO tests are running
+```
+
+**SAFE OPERATIONS**:
+
+```bash
+# ✅ Clean up only YOUR test run's containers (by run ID)
+# The test runner does this automatically via cleanup functions
+
+# ✅ Clean stale (stopped/exited) containers only
+# Pre-test cleanup only removes stopped containers, not running ones
+
+# ✅ Check what's running before cleanup
+docker ps --filter "name=headscale-test-suite" --format "{{.Names}}"
+```
+
+### Running Concurrent Tests
+
+```bash
+# Start multiple tests in parallel - each gets unique run ID
+go run ./cmd/hi run "TestPingAllByIP" &
+go run ./cmd/hi run "TestACLAllowUserDst" &
+go run ./cmd/hi run "TestOIDCAuthenticationPingAll" &
+
+# Monitor running test suites
+docker ps --filter "name=headscale-test-suite" --format "table {{.Names}}\t{{.Status}}"
+```
+
+### Agent Session Isolation Rules
+
+When working as an agent:
+
+1. **Your run ID is unique**: Each test you start gets its own run ID
+2. **Never clean up globally**: Only use run ID-specific cleanup
+3. **Check before cleanup**: Verify no other tests are running if you need to prune resources
+4. **Respect other sessions**: Other agents may have tests running concurrently
+5. **Log directories are isolated**: Your artifacts are in `control_logs/{your-run-id}/`
+
+### Identifying Your Containers
+
+Your test containers can be identified by:
+- The run ID in the container name
+- The `hi.run-id` Docker label
+- The test suite container: `headscale-test-suite-{your-run-id}`
+
+```bash
+# List containers for a specific run ID
+docker ps --filter "label=hi.run-id=20260109-104215-mdjtzx"
+
+# Get your run ID from the test output
+# Look for: "Run ID: 20260109-104215-mdjtzx"
+```
+
+## Common Failure Patterns and Root Cause Analysis
+
+### CRITICAL MINDSET: Code Issues vs Infrastructure Issues
+
+**⚠️ IMPORTANT**: When tests fail, it is ALMOST ALWAYS a code issue with Headscale, NOT infrastructure problems. Do not immediately blame disk space, Docker issues, or timing unless you have thoroughly investigated the actual error logs first.
+
+### Systematic Debugging Process
+
+1. **Read the actual error message**: Don't assume - read the stderr logs completely
+2. **Check Headscale server logs first**: Most issues originate from server-side logic
+3. **Verify client connectivity**: Only after ruling out server issues
+4. **Check timing patterns**: Use proper `EventuallyWithT` patterns
+5. **Infrastructure as last resort**: Only blame infrastructure after code analysis
+
+### Real Failure Patterns
+
+#### 1. Timing Issues (Common but fixable)
+```go
+// ❌ Wrong: Immediate assertions after async operations
+client.Execute([]string{"tailscale", "set", "--advertise-routes=10.0.0.0/24"})
+nodes, _ := headscale.ListNodes()
+require.Len(t, nodes[0].GetAvailableRoutes(), 1) // WILL FAIL
+
+// ✅ Correct: Wait for async operations
+client.Execute([]string{"tailscale", "set", "--advertise-routes=10.0.0.0/24"})
+require.EventuallyWithT(t, func(c *assert.CollectT) {
+    nodes, err := headscale.ListNodes()
+    assert.NoError(c, err)
+    assert.Len(c, nodes[0].GetAvailableRoutes(), 1)
+}, 10*time.Second, 100*time.Millisecond, "route should be advertised")
+```
+
+**Timeout Guidelines**:
+- Route operations: 3-5 seconds
+- Node state changes: 5-10 seconds
+- Complex scenarios: 10-15 seconds
+- Policy recalculation: 5-10 seconds
+
+#### 2. NodeStore Synchronization Issues
+Route advertisements must propagate through poll requests (`poll.go:420`). NodeStore updates happen at specific synchronization points after Hostinfo changes.
+
+#### 3. Test Data Management Issues
+```go
+// ❌ Wrong: Assuming array ordering
+require.Len(t, nodes[0].GetAvailableRoutes(), 1)
+
+// ✅ Correct: Identify nodes by properties
+expectedRoutes := map[string]string{"1": "10.33.0.0/16"}
+for _, node := range nodes {
+    nodeIDStr := fmt.Sprintf("%d", node.GetId())
+    if route, shouldHaveRoute := expectedRoutes[nodeIDStr]; shouldHaveRoute {
+        // Test the specific node that should have the route
+    }
+}
+```
+
+#### 4. Database Backend Differences
+SQLite vs PostgreSQL have different timing characteristics:
+- Use `--postgres` flag for database-intensive tests
+- PostgreSQL generally has more consistent timing
+- Some race conditions only appear with specific backends
+
+## Resource Management and Cleanup
+
+### Disk Space Management
+Tests consume significant disk space (~100MB per run):
+```bash
+# Check available space before running tests
+df -h
+
+# Clean up test artifacts periodically
+rm -rf control_logs/older-timestamp-dirs/
+
+# Clean Docker resources
+docker system prune -f
+docker volume prune -f
+```
+
+### Container Cleanup
+- Successful tests clean up automatically
+- Failed tests may leave containers running
+- Manually clean if needed: `docker ps -a` and `docker rm -f <containers>`
+
+## Advanced Debugging Techniques
+
+### Protocol-Level Debugging
+MapResponse JSON files in `control_logs/*/hs-*-mapresponses/` contain:
+- Network topology as sent to clients
+- Peer relationships and visibility
+- Route distribution and primary route selection
+- Policy evaluation results
+
+### Database State Analysis
+Use the database snapshots for post-mortem analysis:
+```bash
+# SQLite examination
+sqlite3 control_logs/TIMESTAMP/hs-*.db
+.tables
+.schema nodes
+SELECT * FROM nodes WHERE name LIKE '%problematic%';
+```
+
+### Performance Analysis
+Prometheus metrics dumps show:
+- Request latencies and error rates
+- NodeStore operation timing
+- Database query performance
+- Memory usage patterns
+
+## Test Development and Quality Guidelines
+
+### Proper Test Patterns
+```go
+// Always use EventuallyWithT for async operations
+require.EventuallyWithT(t, func(c *assert.CollectT) {
+    // Test condition that may take time to become true
+}, timeout, interval, "descriptive failure message")
+
+// Handle node identification correctly
+var targetNode *v1.Node
+for _, node := range nodes {
+    if node.GetName() == expectedNodeName {
+        targetNode = node
+        break
+    }
+}
+require.NotNil(t, targetNode, "should find expected node")
+```
+
+### Quality Validation Checklist
+- ✅ Tests use `EventuallyWithT` for asynchronous operations
+- ✅ Tests don't rely on array ordering for node identification
+- ✅ Proper cleanup and resource management
+- ✅ Tests handle both success and failure scenarios
+- ✅ Timing assumptions are realistic for operations being tested
+- ✅ Error messages are descriptive and actionable
+
+## Real-World Test Failure Patterns from HA Debugging
+
+### Infrastructure vs Code Issues - Detailed Examples
+
+**INFRASTRUCTURE FAILURES (Rare but Real)**:
+1. **DNS Resolution in Auth Tests**: `failed to resolve "hs-pingallbyip-jax97k": no DNS fallback candidates remain`
+   - **Pattern**: Client containers can't resolve headscale server hostname during logout
+   - **Detection**: Error messages specifically mention DNS/hostname resolution
+   - **Solution**: Docker networking reset, not code changes
+
+2. **Container Creation Timeouts**: Test gets stuck during client container setup
+   - **Pattern**: Tests hang indefinitely at container startup phase
+   - **Detection**: No progress in logs for >2 minutes during initialization
+   - **Solution**: `docker system prune -f` and retry
+
+3. **Docker Resource Exhaustion**: Too many concurrent tests overwhelming system
+   - **Pattern**: Container creation timeouts, OOM kills, slow test execution
+   - **Detection**: System load high, Docker daemon slow to respond
+   - **Solution**: Reduce number of concurrent tests, wait for completion before starting more
+
+**CODE ISSUES (99% of failures)**:
+1. **Route Approval Process Failures**: Routes not getting approved when they should be
+   - **Pattern**: Tests expecting approved routes but finding none
+   - **Detection**: `SubnetRoutes()` returns empty when `AnnouncedRoutes()` shows routes
+   - **Root Cause**: Auto-approval logic bugs, policy evaluation issues
+
+2. **NodeStore Synchronization Issues**: State updates not propagating correctly
+   - **Pattern**: Route changes not reflected in NodeStore or Primary Routes
+   - **Detection**: Logs show route announcements but no tracking updates
+   - **Root Cause**: Missing synchronization points in `poll.go:420` area
+
+3. **HA Failover Architecture Issues**: Routes removed when nodes go offline
+   - **Pattern**: `TestHASubnetRouterFailover` fails because approved routes disappear
+   - **Detection**: Routes available on online nodes but lost when nodes disconnect
+   - **Root Cause**: Conflating route approval with node connectivity
+
+### Critical Test Environment Setup
+
+**Pre-Test Cleanup**:
+
+The test runner automatically handles cleanup:
+- **Before test**: Removes only stale (stopped/exited) containers - does NOT affect running tests
+- **After test**: Removes only containers belonging to the specific run ID
+
+```bash
+# Only clean old log directories if disk space is low
+rm -rf control_logs/202507*
+df -h  # Verify sufficient disk space
+
+# SAFE: Clean only stale/stopped containers (does not affect running tests)
+# The test runner does this automatically via cleanupStaleTestContainers()
+
+# ⚠️ DANGEROUS: Only use when NO tests are running
+docker system prune -f
+```
+
+**Environment Verification**:
+```bash
+# Verify system readiness
+go run ./cmd/hi doctor
+
+# Check what tests are currently running (ALWAYS check before global cleanup)
+docker ps --filter "name=headscale-test-suite" --format "{{.Names}}"
+```
+
+### Specific Test Categories and Known Issues
+
+#### Route-Related Tests (Primary Focus)
+```bash
+# Core route functionality - these should work first
+# Note: Generous timeouts are required for reliable execution
+go run ./cmd/hi run "TestSubnetRouteACL" --timeout=1200s
+go run ./cmd/hi run "TestAutoApproveMultiNetwork" --timeout=1800s
+go run ./cmd/hi run "TestHASubnetRouterFailover" --timeout=1800s
+```
+
+**Common Route Test Patterns**:
+- Tests validate route announcement, approval, and distribution workflows
+- Route state changes are asynchronous - may need `EventuallyWithT` wrappers
+- Route approval must respect ACL policies - test expectations encode security requirements
+- HA tests verify route persistence during node connectivity changes
+
+#### Authentication Tests (Infrastructure-Prone)
+```bash
+# These tests are more prone to infrastructure issues
+# Require longer timeouts due to auth flow complexity
+go run ./cmd/hi run "TestAuthKeyLogoutAndReloginSameUser" --timeout=1200s
+go run ./cmd/hi run "TestAuthWebFlowLogoutAndRelogin" --timeout=1200s
+go run ./cmd/hi run "TestOIDCExpireNodesBasedOnTokenExpiry" --timeout=1800s
+```
+
+**Common Auth Test Infrastructure Failures**:
+- DNS resolution during logout operations
+- Container creation timeouts
+- HTTP/2 stream errors (often symptoms, not root cause)
+
+### Security-Critical Debugging Rules
+
+**❌ FORBIDDEN CHANGES (Security & Test Integrity)**:
+1. **Never change expected test outputs** - Tests define correct behavior contracts
+   - Changing `require.Len(t, routes, 3)` to `require.Len(t, routes, 2)` because test fails
+   - Modifying expected status codes, node counts, or route counts
+   - Removing assertions that are "inconvenient"
+   - **Why forbidden**: Test expectations encode business requirements and security policies
+
+2. **Never bypass security mechanisms** - Security must never be compromised for convenience
+   - Using `AnnouncedRoutes()` instead of `SubnetRoutes()` in production code
+   - Skipping authentication or authorization checks
+   - **Why forbidden**: Security bypasses create vulnerabilities in production
+
+3. **Never reduce test coverage** - Tests prevent regressions
+   - Removing test cases or assertions
+   - Commenting out "problematic" test sections
+   - **Why forbidden**: Reduced coverage allows bugs to slip through
+
+**✅ ALLOWED CHANGES (Timing & Observability)**:
+1. **Fix timing issues with proper async patterns**
+   ```go
+   // ✅ GOOD: Add EventuallyWithT for async operations
+   require.EventuallyWithT(t, func(c *assert.CollectT) {
+       nodes, err := headscale.ListNodes()
+       assert.NoError(c, err)
+       assert.Len(c, nodes, expectedCount) // Keep original expectation
+   }, 10*time.Second, 100*time.Millisecond, "nodes should reach expected count")
+   ```
+   - **Why allowed**: Fixes race conditions without changing business logic
+
+2. **Add MORE observability and debugging**
+   - Additional logging statements
+   - More detailed error messages
+   - Extra assertions that verify intermediate states
+   - **Why allowed**: Better observability helps debug without changing behavior
+
+3. **Improve test documentation**
+   - Add godoc comments explaining test purpose and business logic
+   - Document timing requirements and async behavior
+   - **Why encouraged**: Helps future maintainers understand intent
+
+### Advanced Debugging Workflows
+
+#### Route Tracking Debug Flow
+```bash
+# Run test with detailed logging and proper timeout
+go run ./cmd/hi run "TestSubnetRouteACL" --timeout=1200s > test_output.log 2>&1
+
+# Check route approval process
+grep -E "(auto-approval|ApproveRoutesWithPolicy|PolicyManager)" test_output.log
+
+# Check route tracking
+tail -50 control_logs/*/hs-*.stderr.log | grep -E "(announced|tracking|SetNodeRoutes)"
+
+# Check for security violations
+grep -E "(AnnouncedRoutes.*SetNodeRoutes|bypass.*approval)" test_output.log
+```
+
+#### HA Failover Debug Flow
+```bash
+# Test HA failover specifically with adequate timeout
+go run ./cmd/hi run "TestHASubnetRouterFailover" --timeout=1800s
+
+# Check route persistence during disconnect
+grep -E "(Disconnect|NodeWentOffline|PrimaryRoutes)" control_logs/*/hs-*.stderr.log
+
+# Verify routes don't disappear inappropriately
+grep -E "(removing.*routes|SetNodeRoutes.*empty)" control_logs/*/hs-*.stderr.log
+```
+
+### Test Result Interpretation Guidelines
+
+#### Success Patterns to Look For
+- `"updating node routes for tracking"` in logs
+- Routes appearing in `announcedRoutes` logs
+- Proper `ApproveRoutesWithPolicy` calls for auto-approval
+- Routes persisting through node connectivity changes (HA tests)
+
+#### Failure Patterns to Investigate
+- `SubnetRoutes()` returning empty when `AnnouncedRoutes()` has routes
+- Routes disappearing when nodes go offline (HA architectural issue)
+- Missing `EventuallyWithT` causing timing race conditions
+- Security bypass attempts using wrong route methods
+
+### Critical Testing Methodology
+
+**Phase-Based Testing Approach**:
+1. **Phase 1**: Core route tests (ACL, auto-approval, basic functionality)
+2. **Phase 2**: HA and complex route scenarios
+3. **Phase 3**: Auth tests (infrastructure-sensitive, test last)
+
+**Per-Test Process**:
+1. Clean environment before each test
+2. Monitor logs for route tracking and approval messages
+3. Check artifacts in `control_logs/` if test fails
+4. Focus on actual error messages, not assumptions
+5. Document results and patterns discovered
+
+## Test Documentation and Code Quality Standards
+
+### Adding Missing Test Documentation
+When you understand a test's purpose through debugging, always add comprehensive godoc:
+
+```go
+// TestSubnetRoutes validates the complete subnet route lifecycle including
+// advertisement from clients, policy-based approval, and distribution to peers.
+// This test ensures that route security policies are properly enforced and that
+// only approved routes are distributed to the network.
+//
+// The test verifies:
+// - Route announcements are received and tracked
+// - ACL policies control route approval correctly
+// - Only approved routes appear in peer network maps
+// - Route state persists correctly in the database
+func TestSubnetRoutes(t *testing.T) {
+    // Test implementation...
+}
+```
+
+**Why add documentation**: Future maintainers need to understand business logic and security requirements encoded in tests.
+
+### Comment Guidelines - Focus on WHY, Not WHAT
+
+```go
+// ✅ GOOD: Explains reasoning and business logic
+// Wait for route propagation because NodeStore updates are asynchronous
+// and happen after poll requests complete processing
+require.EventuallyWithT(t, func(c *assert.CollectT) {
+    // Check that security policies are enforced...
+}, timeout, interval, "route approval must respect ACL policies")
+
+// ❌ BAD: Just describes what the code does
+// Wait for routes
+require.EventuallyWithT(t, func(c *assert.CollectT) {
+    // Get routes and check length
+}, timeout, interval, "checking routes")
+```
+
+**Why focus on WHY**: Helps maintainers understand architectural decisions and security requirements.
+
+## EventuallyWithT Pattern for External Calls
+
+### Overview
+EventuallyWithT is a testing pattern used to handle eventual consistency in distributed systems. In Headscale integration tests, many operations are asynchronous - clients advertise routes, the server processes them, updates propagate through the network. EventuallyWithT allows tests to wait for these operations to complete while making assertions.
+
+### External Calls That Must Be Wrapped
+The following operations are **external calls** that interact with the headscale server or tailscale clients and MUST be wrapped in EventuallyWithT:
+- `headscale.ListNodes()` - Queries server state
+- `client.Status()` - Gets client network status
+- `client.Curl()` - Makes HTTP requests through the network
+- `client.Traceroute()` - Performs network diagnostics
+- `client.Execute()` when running commands that query state
+- Any operation that reads from the headscale server or tailscale client
+
+### Five Key Rules for EventuallyWithT
+
+1. **One External Call Per EventuallyWithT Block**
+   - Each EventuallyWithT should make ONE external call (e.g., ListNodes OR Status)
+   - Related assertions based on that single call can be grouped together
+   - Unrelated external calls must be in separate EventuallyWithT blocks
+
+2. **Variable Scoping**
+   - Declare variables that need to be shared across EventuallyWithT blocks at function scope
+   - Use `=` for assignment inside EventuallyWithT, not `:=` (unless the variable is only used within that block)
+   - Variables declared with `:=` inside EventuallyWithT are not accessible outside
+
+3. **No Nested EventuallyWithT**
+   - NEVER put an EventuallyWithT inside another EventuallyWithT
+   - This is a critical anti-pattern that must be avoided
+
+4. **Use CollectT for Assertions**
+   - Inside EventuallyWithT, use `assert` methods with the CollectT parameter
+   - Helper functions called within EventuallyWithT must accept `*assert.CollectT`
+
+5. **Descriptive Messages**
+   - Always provide a descriptive message as the last parameter
+   - Message should explain what condition is being waited for
+
+### Correct Pattern Examples
+
+```go
+// CORRECT: Single external call with related assertions
+var nodes []*v1.Node
+var err error
+
+assert.EventuallyWithT(t, func(c *assert.CollectT) {
+    nodes, err = headscale.ListNodes()
+    assert.NoError(c, err)
+    assert.Len(c, nodes, 2)
+    // These assertions are all based on the ListNodes() call
+    requireNodeRouteCountWithCollect(c, nodes[0], 2, 2, 2)
+    requireNodeRouteCountWithCollect(c, nodes[1], 1, 1, 1)
+}, 10*time.Second, 500*time.Millisecond, "nodes should have expected route counts")
+
+// CORRECT: Separate EventuallyWithT for different external call
+assert.EventuallyWithT(t, func(c *assert.CollectT) {
+    status, err := client.Status()
+    assert.NoError(c, err)
+    // All these assertions are based on the single Status() call
+    for _, peerKey := range status.Peers() {
+        peerStatus := status.Peer[peerKey]
+        requirePeerSubnetRoutesWithCollect(c, peerStatus, expectedPrefixes)
+    }
+}, 10*time.Second, 500*time.Millisecond, "client should see expected routes")
+
+// CORRECT: Variable scoping for sharing between blocks
+var routeNode *v1.Node
+var nodeKey key.NodePublic
+
+// First EventuallyWithT to get the node
+assert.EventuallyWithT(t, func(c *assert.CollectT) {
+    nodes, err := headscale.ListNodes()
+    assert.NoError(c, err)
+
+    for _, node := range nodes {
+        if node.GetName() == "router" {
+            routeNode = node
+            nodeKey, _ = key.ParseNodePublicUntyped(mem.S(node.GetNodeKey()))
+            break
+        }
+    }
+    assert.NotNil(c, routeNode, "should find router node")
+}, 10*time.Second, 100*time.Millisecond, "router node should exist")
+
+// Second EventuallyWithT using the nodeKey from first block
+assert.EventuallyWithT(t, func(c *assert.CollectT) {
+    status, err := client.Status()
+    assert.NoError(c, err)
+
+    peerStatus, ok := status.Peer[nodeKey]
+    assert.True(c, ok, "peer should exist in status")
+    requirePeerSubnetRoutesWithCollect(c, peerStatus, expectedPrefixes)
+}, 10*time.Second, 100*time.Millisecond, "routes should be visible to client")
+```
+
+### Incorrect Patterns to Avoid
+
+```go
+// INCORRECT: Multiple unrelated external calls in same EventuallyWithT
+assert.EventuallyWithT(t, func(c *assert.CollectT) {
+    // First external call
+    nodes, err := headscale.ListNodes()
+    assert.NoError(c, err)
+    assert.Len(c, nodes, 2)
+
+    // Second unrelated external call - WRONG!
+    status, err := client.Status()
+    assert.NoError(c, err)
+    assert.NotNil(c, status)
+}, 10*time.Second, 500*time.Millisecond, "mixed operations")
+
+// INCORRECT: Nested EventuallyWithT
+assert.EventuallyWithT(t, func(c *assert.CollectT) {
+    nodes, err := headscale.ListNodes()
+    assert.NoError(c, err)
+
+    // NEVER do this!
+    assert.EventuallyWithT(t, func(c2 *assert.CollectT) {
+        status, _ := client.Status()
+        assert.NotNil(c2, status)
+    }, 5*time.Second, 100*time.Millisecond, "nested")
+}, 10*time.Second, 500*time.Millisecond, "outer")
+
+// INCORRECT: Variable scoping error
+assert.EventuallyWithT(t, func(c *assert.CollectT) {
+    nodes, err := headscale.ListNodes() // This shadows outer 'nodes' variable
+    assert.NoError(c, err)
+}, 10*time.Second, 500*time.Millisecond, "get nodes")
+
+// This will fail - nodes is nil because := created a new variable inside the block
+require.Len(t, nodes, 2) // COMPILATION ERROR or nil pointer
+
+// INCORRECT: Not wrapping external calls
+nodes, err := headscale.ListNodes() // External call not wrapped!
+require.NoError(t, err)
+```
+
+### Helper Functions for EventuallyWithT
+
+When creating helper functions for use within EventuallyWithT:
+
+```go
+// Helper function that accepts CollectT
+func requireNodeRouteCountWithCollect(c *assert.CollectT, node *v1.Node, available, approved, primary int) {
+    assert.Len(c, node.GetAvailableRoutes(), available, "available routes for node %s", node.GetName())
+    assert.Len(c, node.GetApprovedRoutes(), approved, "approved routes for node %s", node.GetName())
+    assert.Len(c, node.GetPrimaryRoutes(), primary, "primary routes for node %s", node.GetName())
+}
+
+// Usage within EventuallyWithT
+assert.EventuallyWithT(t, func(c *assert.CollectT) {
+    nodes, err := headscale.ListNodes()
+    assert.NoError(c, err)
+    requireNodeRouteCountWithCollect(c, nodes[0], 2, 2, 2)
+}, 10*time.Second, 500*time.Millisecond, "route counts should match expected")
+```
+
+### Operations That Must NOT Be Wrapped
+
+**CRITICAL**: The following operations are **blocking/mutating operations** that change state and MUST NOT be wrapped in EventuallyWithT:
+- `tailscale set` commands (e.g., `--advertise-routes`, `--accept-routes`)
+- `headscale.ApproveRoute()` - Approves routes on server
+- `headscale.CreateUser()` - Creates users
+- `headscale.CreatePreAuthKey()` - Creates authentication keys
+- `headscale.RegisterNode()` - Registers new nodes
+- Any `client.Execute()` that modifies configuration
+- Any operation that creates, updates, or deletes resources
+
+These operations:
+1. Complete synchronously or fail immediately
+2. Should not be retried automatically
+3. Need explicit error handling with `require.NoError()`
+
+### Correct Pattern for Blocking Operations
+
+```go
+// CORRECT: Blocking operation NOT wrapped
+status := client.MustStatus()
+command := []string{"tailscale", "set", "--advertise-routes=" + expectedRoutes[string(status.Self.ID)]}
+_, _, err = client.Execute(command)
+require.NoErrorf(t, err, "failed to advertise route: %s", err)
+
+// Then wait for the result with EventuallyWithT
+assert.EventuallyWithT(t, func(c *assert.CollectT) {
+    nodes, err := headscale.ListNodes()
+    assert.NoError(c, err)
+    assert.Contains(c, nodes[0].GetAvailableRoutes(), expectedRoutes[string(status.Self.ID)])
+}, 10*time.Second, 100*time.Millisecond, "route should be advertised")
+
+// INCORRECT: Blocking operation wrapped (DON'T DO THIS)
+assert.EventuallyWithT(t, func(c *assert.CollectT) {
+    _, _, err = client.Execute([]string{"tailscale", "set", "--advertise-routes=10.0.0.0/24"})
+    assert.NoError(c, err) // This might retry the command multiple times!
+}, 10*time.Second, 100*time.Millisecond, "advertise routes")
+```
+
+### Assert vs Require Pattern
+
+When working within EventuallyWithT blocks where you need to prevent panics:
+
+```go
+assert.EventuallyWithT(t, func(c *assert.CollectT) {
+    nodes, err := headscale.ListNodes()
+    assert.NoError(c, err)
+
+    // For array bounds - use require with t to prevent panic
+    assert.Len(c, nodes, 6)  // Test expectation
+    require.GreaterOrEqual(t, len(nodes), 3, "need at least 3 nodes to avoid panic")
+
+    // For nil pointer access - use require with t before dereferencing
+    assert.NotNil(c, srs1PeerStatus.PrimaryRoutes)  // Test expectation
+    require.NotNil(t, srs1PeerStatus.PrimaryRoutes, "primary routes must be set to avoid panic")
+    assert.Contains(c,
+        srs1PeerStatus.PrimaryRoutes.AsSlice(),
+        pref,
+    )
+}, 5*time.Second, 200*time.Millisecond, "checking route state")
+```
+
+**Key Principle**:
+- Use `assert` with `c` (*assert.CollectT) for test expectations that can be retried
+- Use `require` with `t` (*testing.T) for MUST conditions that prevent panics
+- Within EventuallyWithT, both are available - choose based on whether failure would cause a panic
+
+### Common Scenarios
+
+1. **Waiting for route advertisement**:
+```go
+client.Execute([]string{"tailscale", "set", "--advertise-routes=10.0.0.0/24"})
+
+assert.EventuallyWithT(t, func(c *assert.CollectT) {
+    nodes, err := headscale.ListNodes()
+    assert.NoError(c, err)
+    assert.Contains(c, nodes[0].GetAvailableRoutes(), "10.0.0.0/24")
+}, 10*time.Second, 100*time.Millisecond, "route should be advertised")
+```
+
+2. **Checking client sees routes**:
+```go
+assert.EventuallyWithT(t, func(c *assert.CollectT) {
+    status, err := client.Status()
+    assert.NoError(c, err)
+
+    // Check all peers have expected routes
+    for _, peerKey := range status.Peers() {
+        peerStatus := status.Peer[peerKey]
+        assert.Contains(c, peerStatus.AllowedIPs, expectedPrefix)
+    }
+}, 10*time.Second, 100*time.Millisecond, "all peers should see route")
+```
+
+3. **Sequential operations**:
+```go
+// First wait for node to appear
+var nodeID uint64
+assert.EventuallyWithT(t, func(c *assert.CollectT) {
+    nodes, err := headscale.ListNodes()
+    assert.NoError(c, err)
+    assert.Len(c, nodes, 1)
+    nodeID = nodes[0].GetId()
+}, 10*time.Second, 100*time.Millisecond, "node should register")
+
+// Then perform operation
+_, err := headscale.ApproveRoute(nodeID, "10.0.0.0/24")
+require.NoError(t, err)
+
+// Then wait for result
+assert.EventuallyWithT(t, func(c *assert.CollectT) {
+    nodes, err := headscale.ListNodes()
+    assert.NoError(c, err)
+    assert.Contains(c, nodes[0].GetApprovedRoutes(), "10.0.0.0/24")
+}, 10*time.Second, 100*time.Millisecond, "route should be approved")
+```
+
+## Your Core Responsibilities
+
+1. **Test Execution Strategy**: Execute integration tests with appropriate configurations, understanding when to use `--postgres` and timing requirements for different test categories. Follow phase-based testing approach prioritizing route tests.
+   - **Why this priority**: Route tests are less infrastructure-sensitive and validate core security logic
+
+2. **Systematic Test Analysis**: When tests fail, systematically examine artifacts starting with Headscale server logs, then client logs, then protocol data. Focus on CODE ISSUES first (99% of cases), not infrastructure. Use real-world failure patterns to guide investigation.
+   - **Why this approach**: Most failures are logic bugs, not environment issues - efficient debugging saves time
+
+3. **Timing & Synchronization Expertise**: Understand asynchronous Headscale operations, particularly route advertisements, NodeStore synchronization at `poll.go:420`, and policy propagation. Fix timing with `EventuallyWithT` while preserving original test expectations.
+   - **Why preserve expectations**: Test assertions encode business requirements and security policies
+   - **Key Pattern**: Apply the EventuallyWithT pattern correctly for all external calls as documented above
+
+4. **Root Cause Analysis**: Distinguish between actual code regressions (route approval logic, HA failover architecture), timing issues requiring `EventuallyWithT` patterns, and genuine infrastructure problems (DNS, Docker, container issues).
+   - **Why this distinction matters**: Different problem types require completely different solution approaches
+   - **EventuallyWithT Issues**: Often manifest as flaky tests or immediate assertion failures after async operations
+
+5. **Security-Aware Quality Validation**: Ensure tests properly validate end-to-end functionality with realistic timing expectations and proper error handling. Never suggest security bypasses or test expectation changes. Add comprehensive godoc when you understand test business logic.
+   - **Why security focus**: Integration tests are the last line of defense against security regressions
+   - **EventuallyWithT Usage**: Proper use prevents race conditions without weakening security assertions
+
+6. **Concurrent Execution Awareness**: Respect run ID isolation and never interfere with other agents' test sessions. Each test run has a unique run ID - only clean up YOUR containers (by run ID label), never perform global cleanup while tests may be running.
+   - **Why this matters**: Multiple agents/users may run tests concurrently on the same Docker daemon
+   - **Key Rule**: NEVER use global container cleanup commands - the test runner handles cleanup automatically per run ID
+
+**CRITICAL PRINCIPLE**: Test expectations are sacred contracts that define correct system behavior. When tests fail, fix the code to match the test, never change the test to match broken code. Only timing and observability improvements are allowed - business logic expectations are immutable.
+
+**ISOLATION PRINCIPLE**: Each test run is isolated by its unique Run ID. Never interfere with other test sessions. The system handles cleanup automatically - manual global cleanup commands are forbidden when other tests may be running.
+
+**EventuallyWithT PRINCIPLE**: Every external call to headscale server or tailscale client must be wrapped in EventuallyWithT. Follow the five key rules strictly: one external call per block, proper variable scoping, no nesting, use CollectT for assertions, and provide descriptive messages.
+
+**Remember**: Test failures are usually code issues in Headscale that need to be fixed, not infrastructure problems to be ignored. Use the specific debugging workflows and failure patterns documented above to efficiently identify root causes. Infrastructure issues have very specific signatures - everything else is code-related.

.dockerignore

@@ -3,6 +3,7 @@
 // development
 integration_test.go
 integration_test/
+!integration_test/etc_embedded_derp/tls/server.crt
 
 Dockerfile*
 docker-compose*
@@ -16,3 +17,7 @@ LICENSE
 .vscode
 
 *.sock
+
+node_modules/
+package-lock.json
+package.json

.editorconfig

@@ -0,0 +1,16 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+max_line_length = 120
+
+[*.go]
+indent_style = tab
+
+[Makefile]
+indent_style = tab

.envrc

@@ -0,0 +1 @@
+use flake

.github/CODEOWNERS

@@ -0,0 +1,10 @@
+* @juanfont @kradalby
+
+*.md @ohdearaugustin @nblock
+*.yml @ohdearaugustin @nblock
+*.yaml @ohdearaugustin @nblock
+Dockerfile* @ohdearaugustin @nblock
+.goreleaser.yaml @ohdearaugustin @nblock
+/docs/ @ohdearaugustin @nblock
+/.github/workflows/ @ohdearaugustin @nblock
+/.github/renovate.json @ohdearaugustin @nblock

.github/FUNDING.yml

@@ -1,2 +1,3 @@
-ko_fi: kradalby
-github: [kradalby]
+# These are supported funding model platforms
+
+ko_fi: headscale

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,28 +0,0 @@
----
-name: "Bug report"
-about: "Create a bug report to help us improve"
-title: ""
-labels: ["bug"]
-assignees: ""
----
-
-**Bug description**
-
-<!-- A clear and concise description of what the bug is. Describe the expected bahavior
-  and how it is currently different. If you are unsure if it is a bug, consider discussing
-  it on our Discord server first. -->
-
-**To Reproduce**
-
-<!-- Steps to reproduce the behavior. -->
-
-**Context info**
-
-<!-- Please add relevant information about your system. For example:
-- Version of headscale used
-- Version of tailscale client
-- OS (e.g. Linux, Mac, Cygwin, WSL, etc.) and version
-- Kernel version
-- The relevant config parameters you used
-- Log output
--->

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -0,0 +1,106 @@
+name: 🐞 Bug
+description: File a bug/issue
+title: "[Bug] <title>"
+labels: ["bug", "needs triage"]
+body:
+  - type: checkboxes
+    attributes:
+      label: Is this a support request?
+      description: This issue tracker is for bugs and feature requests only. If you need
+        help, please use ask in our Discord community
+      options:
+        - label: This is not a support request
+          required: true
+  - type: checkboxes
+    attributes:
+      label: Is there an existing issue for this?
+      description: Please search to see if an issue already exists for the bug you
+        encountered.
+      options:
+        - label: I have searched the existing issues
+          required: true
+  - type: textarea
+    attributes:
+      label: Current Behavior
+      description: A concise description of what you're experiencing.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Expected Behavior
+      description: A concise description of what you expected to happen.
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Steps To Reproduce
+      description: Steps to reproduce the behavior.
+      placeholder: |
+        1. In this environment...
+        1. With this config...
+        1. Run '...'
+        1. See error...
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Environment
+      description: |
+        Please provide information about your environment.
+        If you are using a container, always provide the headscale version and not only the Docker image version.
+        Please do not put "latest".
+
+        Describe your "headscale network". Is there a lot of nodes, are the nodes all interconnected, are some subnet routers?
+
+        If you are experiencing a problem during an upgrade, please provide the versions of the old and new versions of Headscale and Tailscale.
+
+        examples:
+          - **OS**: Ubuntu 24.04
+          - **Headscale version**: 0.24.3
+          - **Tailscale version**: 1.80.0
+          - **Number of nodes**: 20
+      value: |
+        - OS:
+        - Headscale version:
+        - Tailscale version:
+      render: markdown
+    validations:
+      required: true
+  - type: checkboxes
+    attributes:
+      label: Runtime environment
+      options:
+        - label: Headscale is behind a (reverse) proxy
+          required: false
+        - label: Headscale runs in a container
+          required: false
+  - type: textarea
+    attributes:
+      label: Debug information
+      description: |
+        Please have a look at our [Debugging and troubleshooting
+        guide](https://headscale.net/development/ref/debug/) to learn about
+        common debugging techniques.
+
+        Links? References? Anything that will give us more context about the issue you are encountering.
+        If **any** of these are omitted we will likely close your issue, do **not** ignore them.
+
+        - Client netmap dump (see below)
+        - Policy configuration
+        - Headscale configuration
+        - Headscale log (with `trace` enabled)
+
+        Dump the netmap of tailscale clients:
+        `tailscale debug netmap > DESCRIPTIVE_NAME.json`
+
+        Dump the status of tailscale clients:
+        `tailscale status --json > DESCRIPTIVE_NAME.json`
+
+        Get the logs of a Tailscale client that is not working as expected.
+        `tailscale debug daemon-logs`
+
+        Tip: You can attach images or log files by clicking this area to highlight it and then dragging files in.
+        **Ensure** you use formatting for files you attach.
+        Do **not** paste in long files.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -3,9 +3,9 @@ blank_issues_enabled: false
 
 # Contact links
 contact_links:
-  - name: "headscale usage documentation"
-    url: "https://github.com/juanfont/headscale/blob/main/docs"
-    about: "Find documentation about how to configure and run headscale."
   - name: "headscale Discord community"
-    url: "https://discord.com/invite/XcQxk2VHjx"
+    url: "https://discord.gg/c84AZQhmpx"
     about: "Please ask and answer questions about usage of headscale here."
+  - name: "headscale usage documentation"
+    url: "https://headscale.net/"
+    about: "Find documentation about how to configure and run headscale."

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,15 +0,0 @@
----
-name: "Feature request"
-about: "Suggest an idea for headscale"
-title: ""
-labels: ["enhancement"]
-assignees: ""
----
-
-**Feature request**
-
-<!-- A clear and precise description of what new or changed feature you want. -->
-
-<!-- Please include the reason, why you would need the feature. E.g. what problem
-  does it solve? Or which workflow is currently frustrating and will be improved by
-  this? -->

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -0,0 +1,36 @@
+name: 🚀 Feature Request
+description: Suggest an idea for Headscale
+title: "[Feature] <title>"
+labels: [enhancement]
+body:
+  - type: textarea
+    attributes:
+      label: Use case
+      description: Please describe the use case for this feature.
+      placeholder: |
+        <!-- Include the reason, why you would need the feature. E.g. what problem
+          does it solve? Or which workflow is currently frustrating and will be improved by
+          this? -->
+    validations:
+      required: true
+  - type: textarea
+    attributes:
+      label: Description
+      description: A clear and precise description of what new or changed feature you want.
+    validations:
+      required: true
+  - type: checkboxes
+    attributes:
+      label: Contribution
+      description: Are you willing to contribute to the implementation of this feature?
+      options:
+        - label: I can write the design doc for this feature
+          required: false
+        - label: I can contribute this feature
+          required: false
+  - type: textarea
+    attributes:
+      label: How can it be implemented?
+      description: Free text for your ideas on how this feature could be implemented.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/other_issue.md

@@ -1,28 +0,0 @@
----
-name: "Other issue"
-about: "Report a different issue"
-title: ""
-labels: ["bug"]
-assignees: ""
----
-
-<!-- If you have a question, please consider using our Discord for asking questions -->
-
-**Issue description**
-
-<!-- Please add your issue description. -->
-
-**To Reproduce**
-
-<!-- Steps to reproduce the behavior. -->
-
-**Context info**
-
-<!-- Please add relevant information about your system. For example:
-- Version of headscale used
-- Version of tailscale client
-- OS (e.g. Linux, Mac, Cygwin, WSL, etc.) and version
-- Kernel version
-- The relevant config parameters you used
-- Log output
--->

.github/label-response/needs-more-info.md

@@ -0,0 +1,80 @@
+Thank you for taking the time to report this issue.
+
+To help us investigate and resolve this, we need more information. Please provide the following:
+
+> [!TIP]
+> Most issues turn out to be configuration errors rather than bugs. We encourage you to discuss your problem in our [Discord community](https://discord.gg/c84AZQhmpx) **before** opening an issue. The community can often help identify misconfigurations quickly, saving everyone time.
+
+## Required Information
+
+### Environment Details
+
+- **Headscale version**: (run `headscale version`)
+- **Tailscale client version**: (run `tailscale version`)
+- **Operating System**: (e.g., Ubuntu 24.04, macOS 14, Windows 11)
+- **Deployment method**: (binary, Docker, Kubernetes, etc.)
+- **Reverse proxy**: (if applicable: nginx, Traefik, Caddy, etc. - include configuration)
+
+### Debug Information
+
+Please follow our [Debugging and Troubleshooting Guide](https://headscale.net/stable/ref/debug/) and provide:
+
+1. **Client netmap dump** (from affected Tailscale client):
+
+   ```bash
+   tailscale debug netmap > netmap.json
+   ```
+
+2. **Client status dump** (from affected Tailscale client):
+
+   ```bash
+   tailscale status --json > status.json
+   ```
+
+3. **Tailscale client logs** (if experiencing client issues):
+
+   ```bash
+   tailscale debug daemon-logs
+   ```
+
+   > [!IMPORTANT]
+   > We need logs from **multiple nodes** to understand the full picture:
+   >
+   > - The node(s) initiating connections
+   > - The node(s) being connected to
+   >
+   > Without logs from both sides, we cannot diagnose connectivity issues.
+
+4. **Headscale server logs** with `log.level: trace` enabled
+
+5. **Headscale configuration** (with sensitive values redacted - see rules below)
+
+6. **ACL/Policy configuration** (if using ACLs)
+
+7. **Proxy/Docker configuration** (if applicable - nginx.conf, docker-compose.yml, Traefik config, etc.)
+
+## Formatting Requirements
+
+- **Attach long files** - Do not paste large logs or configurations inline. Use GitHub file attachments or GitHub Gists.
+- **Use proper Markdown** - Format code blocks, logs, and configurations with appropriate syntax highlighting.
+- **Structure your response** - Use the headings above to organize your information clearly.
+
+## Redaction Rules
+
+> [!CAUTION]
+> **Replace, do not remove.** Removing information makes debugging impossible.
+
+When redacting sensitive information:
+
+- ✅ **Replace consistently** - If you change `alice@company.com` to `user1@example.com`, use `user1@example.com` everywhere (logs, config, policy, etc.)
+- ✅ **Use meaningful placeholders** - `user1@example.com`, `bob@example.com`, `my-secret-key` are acceptable
+- ❌ **Never remove information** - Gaps in data prevent us from correlating events across logs
+- ❌ **Never redact IP addresses** - We need the actual IPs to trace network paths and identify issues
+
+**If redaction rules are not followed, we will be unable to debug the issue and will have to close it.**
+
+---
+
+**Note:** This issue will be automatically closed in 3 days if no additional information is provided. Once you reply with the requested information, the `needs-more-info` label will be removed automatically.
+
+If you need help gathering this information, please visit our [Discord community](https://discord.gg/c84AZQhmpx).

.github/label-response/support-request.md

@@ -0,0 +1,15 @@
+Thank you for reaching out.
+
+This issue tracker is used for **bug reports and feature requests** only. Your question appears to be a support or configuration question rather than a bug report.
+
+For help with setup, configuration, or general questions, please visit our [Discord community](https://discord.gg/c84AZQhmpx) where the community and maintainers can assist you in real-time.
+
+**Before posting in Discord, please check:**
+
+- [Documentation](https://headscale.net/)
+- [FAQ](https://headscale.net/stable/faq/)
+- [Debugging and Troubleshooting Guide](https://headscale.net/stable/ref/debug/)
+
+If after troubleshooting you determine this is actually a bug, please open a new issue with the required debug information from the troubleshooting guide.
+
+This issue has been automatically closed.

.github/pull_request_template.md

@@ -1,10 +1,22 @@
+<!--
+Headscale is "Open Source, acknowledged contribution", this means that any
+contribution will have to be discussed with the Maintainers before being submitted.
+
+This model has been chosen to reduce the risk of burnout by limiting the
+maintenance overhead of reviewing and validating third-party code.
+
+Headscale is open to code contributions for bug fixes without discussion.
+
+If you find mistakes in the documentation, please submit a fix to the documentation.
+-->
+
 <!-- Please tick if the following things apply. You… -->
 
-- [] read the [CONTRIBUTING guidelines](README.md#user-content-contributing)
-- [] raised a GitHub issue or discussed it on the projects chat beforehand
-- [] added unit tests
-- [] added integration tests
-- [] updated documentation if needed
-- [] updated CHANGELOG.md
+- [ ] have read the [CONTRIBUTING.md](./CONTRIBUTING.md) file
+- [ ] raised a GitHub issue or discussed it on the projects chat beforehand
+- [ ] added unit tests
+- [ ] added integration tests
+- [ ] updated documentation if needed
+- [ ] updated CHANGELOG.md
 
 <!-- If applicable, please reference the issue using `Fixes #XXX` and add tests to cover your new code. -->

.github/renovate.json

@@ -0,0 +1,34 @@
+{
+  "baseBranches": ["main"],
+  "username": "renovate-release",
+  "gitAuthor": "Renovate Bot <bot@renovateapp.com>",
+  "branchPrefix": "renovateaction/",
+  "onboarding": false,
+  "extends": ["config:base", ":rebaseStalePrs"],
+  "ignorePresets": [":prHourlyLimit2"],
+  "enabledManagers": ["dockerfile", "gomod", "github-actions", "regex"],
+  "includeForks": true,
+  "repositories": ["juanfont/headscale"],
+  "platform": "github",
+  "packageRules": [
+    {
+      "matchDatasources": ["go"],
+      "groupName": "Go modules",
+      "groupSlug": "gomod",
+      "separateMajorMinor": false
+    },
+    {
+      "matchDatasources": ["docker"],
+      "groupName": "Dockerfiles",
+      "groupSlug": "dockerfiles"
+    }
+  ],
+  "regexManagers": [
+    {
+      "fileMatch": [".github/workflows/.*.yml$"],
+      "matchStrings": ["\\s*go-version:\\s*\"?(?<currentValue>.*?)\"?\\n"],
+      "datasourceTemplate": "golang-version",
+      "depNameTemplate": "actions/go-version"
+    }
+  ]
+}

.github/workflows/build.yml

@@ -5,47 +5,96 @@ on:
     branches:
       - main
   pull_request:
-    branches:
-      - main
+
+concurrency:
+  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
 
 jobs:
-  build:
+  build-nix:
     runs-on: ubuntu-latest
-
+    permissions: write-all
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 2
-
       - name: Get changed files
         id: changed-files
-        uses: tj-actions/changed-files@v14.1
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
         with:
-          files: |
-            go.*
-            **/*.go
-            integration_test/
-            config-example.yaml
-
-      - name: Setup Go
-        if: steps.changed-files.outputs.any_changed == 'true'
-        uses: actions/setup-go@v2
+          filters: |
+            files:
+              - '*.nix'
+              - 'go.*'
+              - '**/*.go'
+              - 'integration_test/'
+              - 'config-example.yaml'
+      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+        if: steps.changed-files.outputs.files == 'true'
+      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+        if: steps.changed-files.outputs.files == 'true'
         with:
-          go-version: "1.17.7"
+          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
+            '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
 
-      - name: Install dependencies
-        if: steps.changed-files.outputs.any_changed == 'true'
+      - name: Run nix build
+        id: build
+        if: steps.changed-files.outputs.files == 'true'
         run: |
-          go version
-          sudo apt update
-          sudo apt install -y make
+          nix build |& tee build-result
+          BUILD_STATUS="${PIPESTATUS[0]}"
 
-      - name: Run build
-        if: steps.changed-files.outputs.any_changed == 'true'
-        run: make build
+          OLD_HASH=$(cat build-result | grep specified: | awk -F ':' '{print $2}' | sed 's/ //g')
+          NEW_HASH=$(cat build-result | grep got: | awk -F ':' '{print $2}' | sed 's/ //g')
 
-      - uses: actions/upload-artifact@v2
-        if: steps.changed-files.outputs.any_changed == 'true'
+          echo "OLD_HASH=$OLD_HASH" >> $GITHUB_OUTPUT
+          echo "NEW_HASH=$NEW_HASH" >> $GITHUB_OUTPUT
+
+          exit $BUILD_STATUS
+
+      - name: Nix gosum diverging
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        if: failure() && steps.build.outcome == 'failure'
+        with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          script: |
+            github.rest.pulls.createReviewComment({
+              pull_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: 'Nix build failed with wrong gosum, please update "vendorSha256" (${{ steps.build.outputs.OLD_HASH }}) for the "headscale" package in flake.nix with the new SHA: ${{ steps.build.outputs.NEW_HASH }}'
+            })
+
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        if: steps.changed-files.outputs.files == 'true'
         with:
           name: headscale-linux
-          path: headscale
+          path: result/bin/headscale
+  build-cross:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        env:
+          - "GOARCH=arm64 GOOS=linux"
+          - "GOARCH=amd64 GOOS=linux"
+          - "GOARCH=arm64 GOOS=darwin"
+          - "GOARCH=amd64 GOOS=darwin"
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+        with:
+          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
+            '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
+
+      - name: Run go cross compile
+        env:
+          CGO_ENABLED: 0
+        run: env ${{ matrix.env }} nix develop --command -- go build -o "headscale"
+          ./cmd/headscale
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: "headscale-${{ matrix.env }}"
+          path: "headscale"

.github/workflows/check-generated.yml

@@ -0,0 +1,55 @@
+name: Check Generated Files
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  check-generated:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 2
+      - name: Get changed files
+        id: changed-files
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        with:
+          filters: |
+            files:
+              - '*.nix'
+              - 'go.*'
+              - '**/*.go'
+              - '**/*.proto'
+              - 'buf.gen.yaml'
+              - 'tools/**'
+      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+        if: steps.changed-files.outputs.files == 'true'
+      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+        if: steps.changed-files.outputs.files == 'true'
+        with:
+          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix', '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
+
+      - name: Run make generate
+        if: steps.changed-files.outputs.files == 'true'
+        run: nix develop --command -- make generate
+
+      - name: Check for uncommitted changes
+        if: steps.changed-files.outputs.files == 'true'
+        run: |
+          if ! git diff --exit-code; then
+            echo "❌ Generated files are not up to date!"
+            echo "Please run 'make generate' and commit the changes."
+            exit 1
+          else
+            echo "✅ All generated files are up to date."
+          fi

.github/workflows/check-tests.yaml

@@ -0,0 +1,45 @@
+name: Check integration tests workflow
+
+on: [pull_request]
+
+concurrency:
+  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  check-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 2
+      - name: Get changed files
+        id: changed-files
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        with:
+          filters: |
+            files:
+              - '*.nix'
+              - 'go.*'
+              - '**/*.go'
+              - 'integration_test/'
+              - 'config-example.yaml'
+      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+        if: steps.changed-files.outputs.files == 'true'
+      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+        if: steps.changed-files.outputs.files == 'true'
+        with:
+          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
+            '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
+
+      - name: Generate and check integration tests
+        if: steps.changed-files.outputs.files == 'true'
+        run: |
+          nix develop --command bash -c "cd .github/workflows && go generate"
+          git diff --exit-code .github/workflows/test-integration.yaml
+
+      - name: Show missing tests
+        if: failure()
+        run: |
+          git diff .github/workflows/test-integration.yaml

.github/workflows/container-main.yml

@@ -0,0 +1,112 @@
+---
+name: Build (main)
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "*.nix"
+      - "go.*"
+      - "**/*.go"
+      - ".github/workflows/container-main.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  container:
+    if: github.repository == 'juanfont/headscale'
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - name: Login to DockerHub
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Login to GHCR
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+        with:
+          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
+            '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
+
+      - name: Set commit timestamp
+        run: echo "SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)" >> $GITHUB_ENV
+
+      - name: Build and push to GHCR
+        env:
+          KO_DOCKER_REPO: ghcr.io/juanfont/headscale
+          KO_DEFAULTBASEIMAGE: gcr.io/distroless/base-debian13
+          CGO_ENABLED: "0"
+        run: |
+          nix develop --command -- ko build \
+            --bare \
+            --platform=linux/amd64,linux/arm64 \
+            --tags=main-${GITHUB_SHA::7} \
+            ./cmd/headscale
+
+      - name: Push to Docker Hub
+        env:
+          KO_DOCKER_REPO: headscale/headscale
+          KO_DEFAULTBASEIMAGE: gcr.io/distroless/base-debian13
+          CGO_ENABLED: "0"
+        run: |
+          nix develop --command -- ko build \
+            --bare \
+            --platform=linux/amd64,linux/arm64 \
+            --tags=main-${GITHUB_SHA::7} \
+            ./cmd/headscale
+
+  binaries:
+    if: github.repository == 'juanfont/headscale'
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - goos: linux
+            goarch: amd64
+          - goos: linux
+            goarch: arm64
+          - goos: darwin
+            goarch: amd64
+          - goos: darwin
+            goarch: arm64
+    steps:
+      - name: Checkout
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+        with:
+          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
+            '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
+
+      - name: Build binary
+        env:
+          CGO_ENABLED: "0"
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+        run: nix develop --command -- go build -o headscale ./cmd/headscale
+
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: headscale-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: headscale

.github/workflows/contributors.yml

@@ -1,24 +0,0 @@
-name: Contributors
-
-on:
-  push:
-    branches:
-      - main
-
-jobs:
-  add-contributors:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: BobAnkh/add-contributors@master
-        with:
-          CONTRIBUTOR: "## Contributors"
-          COLUMN_PER_ROW: "6"
-          ACCESS_TOKEN: ${{secrets.GITHUB_TOKEN}}
-          IMG_WIDTH: "100"
-          FONT_SIZE: "14"
-          PATH: "/README.md"
-          COMMIT_MESSAGE: "docs(README): update contributors"
-          AVATAR_SHAPE: "round"
-          BRANCH: "update-contributors"
-          PULL_REQUEST: "main"

.github/workflows/docs-deploy.yml

@@ -0,0 +1,51 @@
+name: Deploy docs
+
+on:
+  push:
+    branches:
+      # Main branch for development docs
+      - main
+
+      # Doc maintenance branches
+      - doc/[0-9]+.[0-9]+.[0-9]+
+    tags:
+      # Stable release tags
+      - v[0-9]+.[0-9]+.[0-9]+
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 0
+      - name: Install python
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        with:
+          python-version: 3.x
+      - name: Setup cache
+        uses: actions/cache@a7833574556fa59680c1b7cb190c1735db73ebf0 # v5.0.0
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - name: Setup dependencies
+        run: pip install -r docs/requirements.txt
+      - name: Configure git
+        run: |
+          git config user.name github-actions
+          git config user.email github-actions@github.com
+      - name: Deploy development docs
+        if: github.ref == 'refs/heads/main'
+        run: mike deploy --push development unstable
+      - name: Deploy stable docs from doc branches
+        if: startsWith(github.ref, 'refs/heads/doc/')
+        run: mike deploy --push ${GITHUB_REF_NAME##*/}
+      - name: Deploy stable docs from tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        # This assumes that only newer tags are pushed
+        run: mike deploy --push --update-aliases ${GITHUB_REF_NAME#v} stable latest

.github/workflows/docs-test.yml

@@ -0,0 +1,27 @@
+name: Test documentation build
+
+on: [pull_request]
+
+concurrency:
+  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - name: Install python
+        uses: actions/setup-python@83679a892e2d95755f2dac6acb0bfd1e9ac5d548 # v6.1.0
+        with:
+          python-version: 3.x
+      - name: Setup cache
+        uses: actions/cache@a7833574556fa59680c1b7cb190c1735db73ebf0 # v5.0.0
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - name: Setup dependencies
+        run: pip install -r docs/requirements.txt
+      - name: Build docs
+        run: mkdocs build --strict

.github/workflows/gh-action-integration-generator.go

@@ -0,0 +1,143 @@
+package main
+
+//go:generate go run ./gh-action-integration-generator.go
+
+import (
+	"bytes"
+	"fmt"
+	"log"
+	"os/exec"
+	"strings"
+)
+
+// testsToSplit defines tests that should be split into multiple CI jobs.
+// Key is the test function name, value is a list of subtest prefixes.
+// Each prefix becomes a separate CI job as "TestName/prefix".
+//
+// Example: TestAutoApproveMultiNetwork has subtests like:
+//   - TestAutoApproveMultiNetwork/authkey-tag-advertiseduringup-false-pol-database
+//   - TestAutoApproveMultiNetwork/webauth-user-advertiseduringup-true-pol-file
+//
+// Splitting by approver type (tag, user, group) creates 6 CI jobs with 4 tests each:
+//   - TestAutoApproveMultiNetwork/authkey-tag.* (4 tests)
+//   - TestAutoApproveMultiNetwork/authkey-user.* (4 tests)
+//   - TestAutoApproveMultiNetwork/authkey-group.* (4 tests)
+//   - TestAutoApproveMultiNetwork/webauth-tag.* (4 tests)
+//   - TestAutoApproveMultiNetwork/webauth-user.* (4 tests)
+//   - TestAutoApproveMultiNetwork/webauth-group.* (4 tests)
+//
+// This reduces load per CI job (4 tests instead of 12) to avoid infrastructure
+// flakiness when running many sequential Docker-based integration tests.
+var testsToSplit = map[string][]string{
+	"TestAutoApproveMultiNetwork": {
+		"authkey-tag",
+		"authkey-user",
+		"authkey-group",
+		"webauth-tag",
+		"webauth-user",
+		"webauth-group",
+	},
+}
+
+// expandTests takes a list of test names and expands any that need splitting
+// into multiple subtest patterns.
+func expandTests(tests []string) []string {
+	var expanded []string
+	for _, test := range tests {
+		if prefixes, ok := testsToSplit[test]; ok {
+			// This test should be split into multiple jobs.
+			// We append ".*" to each prefix because the CI runner wraps patterns
+			// with ^...$ anchors. Without ".*", a pattern like "authkey$" wouldn't
+			// match "authkey-tag-advertiseduringup-false-pol-database".
+			for _, prefix := range prefixes {
+				expanded = append(expanded, fmt.Sprintf("%s/%s.*", test, prefix))
+			}
+		} else {
+			expanded = append(expanded, test)
+		}
+	}
+	return expanded
+}
+
+func findTests() []string {
+	rgBin, err := exec.LookPath("rg")
+	if err != nil {
+		log.Fatalf("failed to find rg (ripgrep) binary")
+	}
+
+	args := []string{
+		"--regexp", "func (Test.+)\\(.*",
+		"../../integration/",
+		"--replace", "$1",
+		"--sort", "path",
+		"--no-line-number",
+		"--no-filename",
+		"--no-heading",
+	}
+
+	cmd := exec.Command(rgBin, args...)
+	var out bytes.Buffer
+	cmd.Stdout = &out
+	err = cmd.Run()
+	if err != nil {
+		log.Fatalf("failed to run command: %s", err)
+	}
+
+	tests := strings.Split(strings.TrimSpace(out.String()), "\n")
+	return tests
+}
+
+func updateYAML(tests []string, jobName string, testPath string) {
+	testsForYq := fmt.Sprintf("[%s]", strings.Join(tests, ", "))
+
+	yqCommand := fmt.Sprintf(
+		"yq eval '.jobs.%s.strategy.matrix.test = %s' %s -i",
+		jobName,
+		testsForYq,
+		testPath,
+	)
+	cmd := exec.Command("bash", "-c", yqCommand)
+
+	var stdout bytes.Buffer
+	var stderr bytes.Buffer
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+	err := cmd.Run()
+	if err != nil {
+		log.Printf("stdout: %s", stdout.String())
+		log.Printf("stderr: %s", stderr.String())
+		log.Fatalf("failed to run yq command: %s", err)
+	}
+
+	fmt.Printf("YAML file (%s) job %s updated successfully\n", testPath, jobName)
+}
+
+func main() {
+	tests := findTests()
+
+	// Expand tests that should be split into multiple jobs
+	expandedTests := expandTests(tests)
+
+	quotedTests := make([]string, len(expandedTests))
+	for i, test := range expandedTests {
+		quotedTests[i] = fmt.Sprintf("\"%s\"", test)
+	}
+
+	// Define selected tests for PostgreSQL
+	postgresTestNames := []string{
+		"TestACLAllowUserDst",
+		"TestPingAllByIP",
+		"TestEphemeral2006DeletedTooQuickly",
+		"TestPingAllByIPManyUpDown",
+		"TestSubnetRouterMultiNetwork",
+	}
+
+	quotedPostgresTests := make([]string, len(postgresTestNames))
+	for i, test := range postgresTestNames {
+		quotedPostgresTests[i] = fmt.Sprintf("\"%s\"", test)
+	}
+
+	// Update both SQLite and PostgreSQL job matrices
+	updateYAML(quotedTests, "sqlite", "./test-integration.yaml")
+	updateYAML(quotedPostgresTests, "postgres", "./test-integration.yaml")
+}

.github/workflows/gh-actions-updater.yaml

@@ -0,0 +1,23 @@
+name: GitHub Actions Version Updater
+
+on:
+  schedule:
+    # Automatically run on every Sunday
+    - cron: "0 0 * * 0"
+
+jobs:
+  build:
+    if: github.repository == 'juanfont/headscale'
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          # [Required] Access token with `workflow` scope.
+          token: ${{ secrets.WORKFLOW_SECRET }}
+
+      - name: Run GitHub Actions Version Updater
+        uses: saadmk11/github-actions-version-updater@d8781caf11d11168579c8e5e94f62b068038f442 # v0.9.0
+        with:
+          # [Required] Access token with `workflow` scope.
+          token: ${{ secrets.WORKFLOW_SECRET }}

.github/workflows/integration-test-template.yml

@@ -0,0 +1,130 @@
+name: Integration Test Template
+
+on:
+  workflow_call:
+    inputs:
+      test:
+        required: true
+        type: string
+      postgres_flag:
+        required: false
+        type: string
+        default: ""
+      database_name:
+        required: true
+        type: string
+
+jobs:
+  test:
+    runs-on: ubuntu-24.04-arm
+    env:
+      # Github does not allow us to access secrets in pull requests,
+      # so this env var is used to check if we have the secret or not.
+      # If we have the secrets, meaning we are running on push in a fork,
+      # there might be secrets available for more debugging.
+      # If TS_OAUTH_CLIENT_ID and TS_OAUTH_SECRET is set, then the job
+      # will join a debug tailscale network, set up SSH and a tmux session.
+      # The SSH will be configured to use the SSH key of the Github user
+      # that triggered the build.
+      HAS_TAILSCALE_SECRET: ${{ secrets.TS_OAUTH_CLIENT_ID }}
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 2
+      - name: Tailscale
+        if: ${{ env.HAS_TAILSCALE_SECRET }}
+        uses: tailscale/github-action@a392da0a182bba0e9613b6243ebd69529b1878aa # v4.1.0
+        with:
+          oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
+          oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
+          tags: tag:gh
+      - name: Setup SSH server for Actor
+        if: ${{ env.HAS_TAILSCALE_SECRET }}
+        uses: alexellis/setup-sshd-actor@master
+      - name: Download headscale image
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        with:
+          name: headscale-image
+          path: /tmp/artifacts
+      - name: Download tailscale HEAD image
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        with:
+          name: tailscale-head-image
+          path: /tmp/artifacts
+      - name: Download hi binary
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        with:
+          name: hi-binary
+          path: /tmp/artifacts
+      - name: Download Go cache
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        with:
+          name: go-cache
+          path: /tmp/artifacts
+      - name: Download postgres image
+        if: ${{ inputs.postgres_flag == '--postgres=1' }}
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        with:
+          name: postgres-image
+          path: /tmp/artifacts
+      - name: Pin Docker to v28 (avoid v29 breaking changes)
+        run: |
+          # Docker 29 breaks docker build via Go client libraries and
+          # docker load/save with certain tarball formats.
+          # Pin to Docker 28.x until our tooling is updated.
+          # https://github.com/actions/runner-images/issues/13474
+          sudo install -m 0755 -d /etc/apt/keyrings
+          curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
+            | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+          echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
+            https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
+            | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+          sudo apt-get update -qq
+          VERSION=$(apt-cache madison docker-ce | grep '28\.5' | head -1 | awk '{print $3}')
+          sudo apt-get install -y --allow-downgrades \
+            "docker-ce=${VERSION}" "docker-ce-cli=${VERSION}"
+          sudo systemctl restart docker
+          docker version
+      - name: Load Docker images, Go cache, and prepare binary
+        run: |
+          gunzip -c /tmp/artifacts/headscale-image.tar.gz | docker load
+          gunzip -c /tmp/artifacts/tailscale-head-image.tar.gz | docker load
+          if [ -f /tmp/artifacts/postgres-image.tar.gz ]; then
+            gunzip -c /tmp/artifacts/postgres-image.tar.gz | docker load
+          fi
+          chmod +x /tmp/artifacts/hi
+          docker images
+          # Extract Go cache to host directories for bind mounting
+          mkdir -p /tmp/go-cache
+          tar -xzf /tmp/artifacts/go-cache.tar.gz -C /tmp/go-cache
+          ls -la /tmp/go-cache/ /tmp/go-cache/.cache/
+      - name: Run Integration Test
+        env:
+          HEADSCALE_INTEGRATION_HEADSCALE_IMAGE: headscale:${{ github.sha }}
+          HEADSCALE_INTEGRATION_TAILSCALE_IMAGE: tailscale-head:${{ github.sha }}
+          HEADSCALE_INTEGRATION_POSTGRES_IMAGE: ${{ inputs.postgres_flag == '--postgres=1' && format('postgres:{0}', github.sha) || '' }}
+          HEADSCALE_INTEGRATION_GO_CACHE: /tmp/go-cache/go
+          HEADSCALE_INTEGRATION_GO_BUILD_CACHE: /tmp/go-cache/.cache/go-build
+        run: /tmp/artifacts/hi run --stats --ts-memory-limit=300 --hs-memory-limit=1500 "^${{ inputs.test }}$" \
+          --timeout=120m \
+          ${{ inputs.postgres_flag }}
+      # Sanitize test name for artifact upload (replace invalid characters: " : < > | * ? \ / with -)
+      - name: Sanitize test name for artifacts
+        if: always()
+        id: sanitize
+        run: echo "name=${TEST_NAME//[\":<>|*?\\\/]/-}" >> $GITHUB_OUTPUT
+        env:
+          TEST_NAME: ${{ inputs.test }}
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        if: always()
+        with:
+          name: ${{ inputs.database_name }}-${{ steps.sanitize.outputs.name }}-logs
+          path: "control_logs/*/*.log"
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        if: always()
+        with:
+          name: ${{ inputs.database_name }}-${{ steps.sanitize.outputs.name }}-artifacts
+          path: control_logs/
+      - name: Setup a blocking tmux session
+        if: ${{ env.HAS_TAILSCALE_SECRET }}
+        uses: alexellis/block-with-tmux-action@master

.github/workflows/lint.yml

@@ -1,74 +1,93 @@
----
-name: CI
+name: Lint
 
-on: [push, pull_request]
+on: [pull_request]
+
+concurrency:
+  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
 
 jobs:
   golangci-lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 2
-
       - name: Get changed files
         id: changed-files
-        uses: tj-actions/changed-files@v14.1
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
         with:
-          files: |
-            go.*
-            **/*.go
-            integration_test/
-            config-example.yaml
+          filters: |
+            files:
+              - '*.nix'
+              - 'go.*'
+              - '**/*.go'
+              - 'integration_test/'
+              - 'config-example.yaml'
+      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+        if: steps.changed-files.outputs.files == 'true'
+      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+        if: steps.changed-files.outputs.files == 'true'
+        with:
+          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
+            '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
 
       - name: golangci-lint
-        if: steps.changed-files.outputs.any_changed == 'true'
-        uses: golangci/golangci-lint-action@v2
-        with:
-          version: latest
-
-          # Only block PRs on new problems.
-          # If this is not enabled, we will end up having PRs
-          # blocked because new linters has appared and other
-          # parts of the code is affected.
-          only-new-issues: true
+        if: steps.changed-files.outputs.files == 'true'
+        run: nix develop --command -- golangci-lint run
+          --new-from-rev=${{github.event.pull_request.base.sha}}
+          --output.text.path=stdout
+          --output.text.print-linter-name
+          --output.text.print-issued-lines
+          --output.text.colors
 
   prettier-lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 2
-
       - name: Get changed files
         id: changed-files
-        uses: tj-actions/changed-files@v14.1
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
         with:
-          files: |
-            **/*.md
-            **/*.yml
-            **/*.yaml
-            **/*.ts
-            **/*.js
-            **/*.sass
-            **/*.css
-            **/*.scss
-            **/*.html
+          filters: |
+            files:
+              - '*.nix'
+              - '**/*.md'
+              - '**/*.yml'
+              - '**/*.yaml'
+              - '**/*.ts'
+              - '**/*.js'
+              - '**/*.sass'
+              - '**/*.css'
+              - '**/*.scss'
+              - '**/*.html'
+      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+        if: steps.changed-files.outputs.files == 'true'
+      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+        if: steps.changed-files.outputs.files == 'true'
+        with:
+          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
+            '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
 
       - name: Prettify code
-        if: steps.changed-files.outputs.any_changed == 'true'
-        uses: creyD/prettier_action@v4.0
-        with:
-          prettier_options: >-
-            --check **/*.{ts,js,md,yaml,yml,sass,css,scss,html}
-          only_changed: false
-          dry: true
+        if: steps.changed-files.outputs.files == 'true'
+        run: nix develop --command -- prettier --no-error-on-unmatched-pattern
+          --ignore-unknown --check **/*.{ts,js,md,yaml,yml,sass,css,scss,html}
 
   proto-lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: bufbuild/buf-setup-action@v0.7.0
-      - uses: bufbuild/buf-lint-action@v1
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
         with:
-          input: "proto"
+          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
+            '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
+
+      - name: Buf lint
+        run: nix develop --command -- buf lint proto

.github/workflows/needs-more-info-comment.yml

@@ -0,0 +1,28 @@
+name: Needs More Info - Post Comment
+
+on:
+  issues:
+    types: [labeled]
+
+jobs:
+  post-comment:
+    if: >-
+      github.event.label.name == 'needs-more-info' &&
+      github.repository == 'juanfont/headscale'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          sparse-checkout: .github/label-response/needs-more-info.md
+          sparse-checkout-cone-mode: false
+
+      - name: Post instruction comment
+        run: gh issue comment "$NUMBER" --body-file .github/label-response/needs-more-info.md
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          NUMBER: ${{ github.event.issue.number }}

.github/workflows/needs-more-info-timer.yml

@@ -0,0 +1,98 @@
+name: Needs More Info - Timer
+
+on:
+  schedule:
+    - cron: "0 0 * * *" # Daily at midnight UTC
+  issue_comment:
+    types: [created]
+  workflow_dispatch:
+
+jobs:
+  # When a non-bot user comments on a needs-more-info issue, remove the label.
+  remove-label-on-response:
+    if: >-
+      github.repository == 'juanfont/headscale' &&
+      github.event_name == 'issue_comment' &&
+      github.event.comment.user.type != 'Bot' &&
+      contains(github.event.issue.labels.*.name, 'needs-more-info')
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - name: Remove needs-more-info label
+        run: gh issue edit "$NUMBER" --remove-label needs-more-info
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          NUMBER: ${{ github.event.issue.number }}
+
+  # On schedule, close issues that have had no human response for 3 days.
+  close-stale:
+    if: >-
+      github.repository == 'juanfont/headscale' &&
+      github.event_name != 'issue_comment'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - uses: hustcer/setup-nu@920172d92eb04671776f3ba69d605d3b09351c30 # v3.22
+        with:
+          version: "*"
+
+      - name: Close stale needs-more-info issues
+        shell: nu {0}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          let issues = (gh issue list
+            --repo $env.GH_REPO
+            --label "needs-more-info"
+            --state open
+            --json number
+            | from json)
+
+          for issue in $issues {
+            let number = $issue.number
+            print $"Checking issue #($number)"
+
+            # Find when needs-more-info was last added
+            let events = (gh api $"repos/($env.GH_REPO)/issues/($number)/events"
+              --paginate | from json | flatten)
+            let label_event = ($events
+              | where event == "labeled" and label.name == "needs-more-info"
+              | last)
+            let label_added_at = ($label_event.created_at | into datetime)
+
+            # Check for non-bot comments after the label was added
+            let comments = (gh api $"repos/($env.GH_REPO)/issues/($number)/comments"
+              --paginate | from json | flatten)
+            let human_responses = ($comments
+              | where user.type != "Bot"
+              | where { ($in.created_at | into datetime) > $label_added_at })
+
+            if ($human_responses | length) > 0 {
+              print $"  Human responded, removing label"
+              gh issue edit $number --repo $env.GH_REPO --remove-label needs-more-info
+              continue
+            }
+
+            # Check if 3 days have passed
+            let elapsed = (date now) - $label_added_at
+            if $elapsed < 3day {
+              print $"  Only ($elapsed | format duration day) elapsed, skipping"
+              continue
+            }
+
+            print $"  No response for ($elapsed | format duration day), closing"
+            let message = [
+              "This issue has been automatically closed because no additional information was provided within 3 days."
+              ""
+              "If you have the requested information, please open a new issue and include the debug information requested above."
+              ""
+              "Thank you for your understanding."
+            ] | str join "\n"
+            gh issue comment $number --repo $env.GH_REPO --body $message
+            gh issue close $number --repo $env.GH_REPO --reason "not planned"
+            gh issue edit $number --repo $env.GH_REPO --remove-label needs-more-info
+          }

.github/workflows/nix-module-test.yml

@@ -0,0 +1,55 @@
+name: NixOS Module Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  nix-module-check:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 2
+
+      - name: Get changed files
+        id: changed-files
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        with:
+          filters: |
+            nix:
+              - 'nix/**'
+              - 'flake.nix'
+              - 'flake.lock'
+            go:
+              - 'go.*'
+              - '**/*.go'
+              - 'cmd/**'
+              - 'hscontrol/**'
+
+      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+        if: steps.changed-files.outputs.nix == 'true' || steps.changed-files.outputs.go == 'true'
+
+      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+        if: steps.changed-files.outputs.nix == 'true' || steps.changed-files.outputs.go == 'true'
+        with:
+          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
+            '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
+
+      - name: Run NixOS module tests
+        if: steps.changed-files.outputs.nix == 'true' || steps.changed-files.outputs.go == 'true'
+        run: |
+          echo "Running NixOS module integration test..."
+          nix build .#checks.x86_64-linux.headscale -L

.github/workflows/release.yml

@@ -1,5 +1,5 @@
 ---
-name: release
+name: Release
 
 on:
   push:
@@ -9,215 +9,54 @@ on:
 
 jobs:
   goreleaser:
-    runs-on: ubuntu-18.04 # due to CGO we need to user an older version
+    if: github.repository == 'juanfont/headscale'
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 0
-      - name: Set up Go
-        uses: actions/setup-go@v2
-        with:
-          go-version: 1.17.7
 
-      - name: Install dependencies
+      - name: Pin Docker to v28 (avoid v29 breaking changes)
         run: |
-          sudo apt update
-          sudo apt install -y gcc-aarch64-linux-gnu
-      - name: Run GoReleaser
-        uses: goreleaser/goreleaser-action@v2
+          # Docker 29 breaks docker build via Go client libraries and
+          # docker load/save with certain tarball formats.
+          # Pin to Docker 28.x until our tooling is updated.
+          # https://github.com/actions/runner-images/issues/13474
+          sudo install -m 0755 -d /etc/apt/keyrings
+          curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
+            | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+          echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
+            https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
+            | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+          sudo apt-get update -qq
+          VERSION=$(apt-cache madison docker-ce | grep '28\.5' | head -1 | awk '{print $3}')
+          sudo apt-get install -y --allow-downgrades \
+            "docker-ce=${VERSION}" "docker-ce-cli=${VERSION}"
+          sudo systemctl restart docker
+          docker version
+
+      - name: Login to DockerHub
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
         with:
-          distribution: goreleaser
-          version: latest
-          args: release --rm-dist
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Login to GHCR
+        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+        with:
+          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
+            '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
+
+      - name: Run goreleaser
+        run: nix develop --command -- goreleaser release --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-  docker-release:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v2
-        with:
-          fetch-depth: 0
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v1
-      - name: Set up QEMU for multiple platforms
-        uses: docker/setup-qemu-action@master
-        with:
-          platforms: arm64,amd64
-      - name: Cache Docker layers
-        uses: actions/cache@v2
-        with:
-          path: /tmp/.buildx-cache
-          key: ${{ runner.os }}-buildx-${{ github.sha }}
-          restore-keys: |
-            ${{ runner.os }}-buildx-
-      - name: Docker meta
-        id: meta
-        uses: docker/metadata-action@v3
-        with:
-          # list of Docker images to use as base name for tags
-          images: |
-            ${{ secrets.DOCKERHUB_USERNAME }}/headscale
-            ghcr.io/${{ github.repository_owner }}/headscale
-          tags: |
-            type=semver,pattern={{version}}
-            type=semver,pattern={{major}}.{{minor}}
-            type=semver,pattern={{major}}
-            type=raw,value=latest
-            type=sha
-      - name: Login to DockerHub
-        uses: docker/login-action@v1
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-      - name: Login to GHCR
-        uses: docker/login-action@v1
-        with:
-          registry: ghcr.io
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-      - name: Build and push
-        id: docker_build
-        uses: docker/build-push-action@v2
-        with:
-          push: true
-          context: .
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          platforms: linux/amd64,linux/arm64
-          cache-from: type=local,src=/tmp/.buildx-cache
-          cache-to: type=local,dest=/tmp/.buildx-cache-new
-      - name: Prepare cache for next build
-        run: |
-          rm -rf /tmp/.buildx-cache
-          mv /tmp/.buildx-cache-new /tmp/.buildx-cache
-
-  docker-debug-release:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v2
-        with:
-          fetch-depth: 0
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v1
-      - name: Set up QEMU for multiple platforms
-        uses: docker/setup-qemu-action@master
-        with:
-          platforms: arm64,amd64
-      - name: Cache Docker layers
-        uses: actions/cache@v2
-        with:
-          path: /tmp/.buildx-cache-debug
-          key: ${{ runner.os }}-buildx-debug-${{ github.sha }}
-          restore-keys: |
-            ${{ runner.os }}-buildx-debug-
-      - name: Docker meta
-        id: meta-debug
-        uses: docker/metadata-action@v3
-        with:
-          # list of Docker images to use as base name for tags
-          images: |
-            ${{ secrets.DOCKERHUB_USERNAME }}/headscale
-            ghcr.io/${{ github.repository_owner }}/headscale
-          flavor: |
-            latest=false
-          tags: |
-            type=semver,pattern={{version}}-debug
-            type=semver,pattern={{major}}.{{minor}}-debug
-            type=semver,pattern={{major}}-debug
-            type=raw,value=latest-debug
-            type=sha,suffix=-debug
-      - name: Login to DockerHub
-        uses: docker/login-action@v1
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-      - name: Login to GHCR
-        uses: docker/login-action@v1
-        with:
-          registry: ghcr.io
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-      - name: Build and push
-        id: docker_build
-        uses: docker/build-push-action@v2
-        with:
-          push: true
-          context: .
-          file: Dockerfile.debug
-          tags: ${{ steps.meta-debug.outputs.tags }}
-          labels: ${{ steps.meta-debug.outputs.labels }}
-          platforms: linux/amd64,linux/arm64
-          cache-from: type=local,src=/tmp/.buildx-cache-debug
-          cache-to: type=local,dest=/tmp/.buildx-cache-debug-new
-      - name: Prepare cache for next build
-        run: |
-          rm -rf /tmp/.buildx-cache-debug
-          mv /tmp/.buildx-cache-debug-new /tmp/.buildx-cache-debug
-
-  docker-alpine-release:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v2
-        with:
-          fetch-depth: 0
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v1
-      - name: Set up QEMU for multiple platforms
-        uses: docker/setup-qemu-action@master
-        with:
-          platforms: arm64,amd64
-      - name: Cache Docker layers
-        uses: actions/cache@v2
-        with:
-          path: /tmp/.buildx-cache-alpine
-          key: ${{ runner.os }}-buildx-alpine-${{ github.sha }}
-          restore-keys: |
-            ${{ runner.os }}-buildx-alpine-
-      - name: Docker meta
-        id: meta-alpine
-        uses: docker/metadata-action@v3
-        with:
-          # list of Docker images to use as base name for tags
-          images: |
-            ${{ secrets.DOCKERHUB_USERNAME }}/headscale
-            ghcr.io/${{ github.repository_owner }}/headscale
-          flavor: |
-            latest=false
-          tags: |
-            type=semver,pattern={{version}}-alpine
-            type=semver,pattern={{major}}.{{minor}}-alpine
-            type=semver,pattern={{major}}-alpine
-            type=raw,value=latest-alpine
-            type=sha,suffix=-alpine
-      - name: Login to DockerHub
-        uses: docker/login-action@v1
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-      - name: Login to GHCR
-        uses: docker/login-action@v1
-        with:
-          registry: ghcr.io
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-      - name: Build and push
-        id: docker_build
-        uses: docker/build-push-action@v2
-        with:
-          push: true
-          context: .
-          file: Dockerfile.alpine
-          tags: ${{ steps.meta-alpine.outputs.tags }}
-          labels: ${{ steps.meta-alpine.outputs.labels }}
-          platforms: linux/amd64,linux/arm64
-          cache-from: type=local,src=/tmp/.buildx-cache-alpine
-          cache-to: type=local,dest=/tmp/.buildx-cache-alpine-new
-      - name: Prepare cache for next build
-        run: |
-          rm -rf /tmp/.buildx-cache-alpine
-          mv /tmp/.buildx-cache-alpine-new /tmp/.buildx-cache-alpine

.github/workflows/stale.yml

@@ -0,0 +1,27 @@
+name: Close inactive issues
+
+on:
+  schedule:
+    - cron: "30 1 * * *"
+
+jobs:
+  close-issues:
+    if: github.repository == 'juanfont/headscale'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/stale@997185467fa4f803885201cee163a9f38240193d # v10.1.1
+        with:
+          days-before-issue-stale: 90
+          days-before-issue-close: 7
+          stale-issue-label: "stale"
+          stale-issue-message: "This issue is stale because it has been open for 90 days with no
+            activity."
+          close-issue-message: "This issue was closed because it has been inactive for 14 days
+            since being marked as stale."
+          days-before-pr-stale: -1
+          days-before-pr-close: -1
+          exempt-issue-labels: "no-stale-bot,needs-more-info"
+          repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/support-request.yml

@@ -0,0 +1,30 @@
+name: Support Request - Close Issue
+
+on:
+  issues:
+    types: [labeled]
+
+jobs:
+  close-support-request:
+    if: >-
+      github.event.label.name == 'support-request' &&
+      github.repository == 'juanfont/headscale'
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          sparse-checkout: .github/label-response/support-request.md
+          sparse-checkout-cone-mode: false
+
+      - name: Post comment and close issue
+        run: |
+          gh issue comment "$NUMBER" --body-file .github/label-response/support-request.md
+          gh issue close "$NUMBER" --reason "not planned"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          NUMBER: ${{ github.event.issue.number }}

.github/workflows/test-integration.yaml

@@ -0,0 +1,322 @@
+name: integration
+# To debug locally on a branch, and when needing secrets
+# change this to include `push` so the build is ran on
+# the main repository.
+on: [pull_request]
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+jobs:
+  # build: Builds binaries and Docker images once, uploads as artifacts for reuse.
+  # build-postgres: Pulls postgres image separately to avoid Docker Hub rate limits.
+  # sqlite: Runs all integration tests with SQLite backend.
+  # postgres: Runs a subset of tests with PostgreSQL to verify database compatibility.
+  build:
+    runs-on: ubuntu-24.04-arm
+    outputs:
+      files-changed: ${{ steps.changed-files.outputs.files }}
+    steps:
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+        with:
+          fetch-depth: 2
+      - name: Get changed files
+        id: changed-files
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
+        with:
+          filters: |
+            files:
+              - '*.nix'
+              - 'go.*'
+              - '**/*.go'
+              - 'integration/**'
+              - 'config-example.yaml'
+              - '.github/workflows/test-integration.yaml'
+              - '.github/workflows/integration-test-template.yml'
+              - 'Dockerfile.*'
+      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+        if: steps.changed-files.outputs.files == 'true'
+      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+        if: steps.changed-files.outputs.files == 'true'
+        with:
+          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix', '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
+      - name: Build binaries and warm Go cache
+        if: steps.changed-files.outputs.files == 'true'
+        run: |
+          # Build all Go binaries in one nix shell to maximize cache reuse
+          nix develop --command -- bash -c '
+            go build -o hi ./cmd/hi
+            CGO_ENABLED=0 GOOS=linux go build -o headscale ./cmd/headscale
+            # Build integration test binary to warm the cache with all dependencies
+            go test -c ./integration -o /dev/null 2>/dev/null || true
+          '
+      - name: Upload hi binary
+        if: steps.changed-files.outputs.files == 'true'
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: hi-binary
+          path: hi
+          retention-days: 10
+      - name: Package Go cache
+        if: steps.changed-files.outputs.files == 'true'
+        run: |
+          # Package Go module cache and build cache
+          tar -czf go-cache.tar.gz -C ~ go .cache/go-build
+      - name: Upload Go cache
+        if: steps.changed-files.outputs.files == 'true'
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: go-cache
+          path: go-cache.tar.gz
+          retention-days: 10
+      - name: Pin Docker to v28 (avoid v29 breaking changes)
+        if: steps.changed-files.outputs.files == 'true'
+        run: |
+          # Docker 29 breaks docker build via Go client libraries and
+          # docker load/save with certain tarball formats.
+          # Pin to Docker 28.x until our tooling is updated.
+          # https://github.com/actions/runner-images/issues/13474
+          sudo install -m 0755 -d /etc/apt/keyrings
+          curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
+            | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+          echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
+            https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
+            | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+          sudo apt-get update -qq
+          VERSION=$(apt-cache madison docker-ce | grep '28\.5' | head -1 | awk '{print $3}')
+          sudo apt-get install -y --allow-downgrades \
+            "docker-ce=${VERSION}" "docker-ce-cli=${VERSION}"
+          sudo systemctl restart docker
+          docker version
+      - name: Build headscale image
+        if: steps.changed-files.outputs.files == 'true'
+        run: |
+          docker build \
+            --file Dockerfile.integration-ci \
+            --tag headscale:${{ github.sha }} \
+            .
+          docker save headscale:${{ github.sha }} | gzip > headscale-image.tar.gz
+      - name: Build tailscale HEAD image
+        if: steps.changed-files.outputs.files == 'true'
+        run: |
+          docker build \
+            --file Dockerfile.tailscale-HEAD \
+            --tag tailscale-head:${{ github.sha }} \
+            .
+          docker save tailscale-head:${{ github.sha }} | gzip > tailscale-head-image.tar.gz
+      - name: Upload headscale image
+        if: steps.changed-files.outputs.files == 'true'
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: headscale-image
+          path: headscale-image.tar.gz
+          retention-days: 10
+      - name: Upload tailscale HEAD image
+        if: steps.changed-files.outputs.files == 'true'
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: tailscale-head-image
+          path: tailscale-head-image.tar.gz
+          retention-days: 10
+  build-postgres:
+    runs-on: ubuntu-24.04-arm
+    needs: build
+    if: needs.build.outputs.files-changed == 'true'
+    steps:
+      - name: Pin Docker to v28 (avoid v29 breaking changes)
+        run: |
+          # Docker 29 breaks docker build via Go client libraries and
+          # docker load/save with certain tarball formats.
+          # Pin to Docker 28.x until our tooling is updated.
+          # https://github.com/actions/runner-images/issues/13474
+          sudo install -m 0755 -d /etc/apt/keyrings
+          curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
+            | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+          echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
+            https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
+            | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+          sudo apt-get update -qq
+          VERSION=$(apt-cache madison docker-ce | grep '28\.5' | head -1 | awk '{print $3}')
+          sudo apt-get install -y --allow-downgrades \
+            "docker-ce=${VERSION}" "docker-ce-cli=${VERSION}"
+          sudo systemctl restart docker
+          docker version
+      - name: Pull and save postgres image
+        run: |
+          docker pull postgres:latest
+          docker tag postgres:latest postgres:${{ github.sha }}
+          docker save postgres:${{ github.sha }} | gzip > postgres-image.tar.gz
+      - name: Upload postgres image
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: postgres-image
+          path: postgres-image.tar.gz
+          retention-days: 10
+  sqlite:
+    needs: build
+    if: needs.build.outputs.files-changed == 'true'
+    strategy:
+      fail-fast: false
+      matrix:
+        test:
+          - TestACLHostsInNetMapTable
+          - TestACLAllowUser80Dst
+          - TestACLDenyAllPort80
+          - TestACLAllowUserDst
+          - TestACLAllowStarDst
+          - TestACLNamedHostsCanReachBySubnet
+          - TestACLNamedHostsCanReach
+          - TestACLDevice1CanAccessDevice2
+          - TestPolicyUpdateWhileRunningWithCLIInDatabase
+          - TestACLAutogroupMember
+          - TestACLAutogroupTagged
+          - TestACLAutogroupSelf
+          - TestACLPolicyPropagationOverTime
+          - TestACLTagPropagation
+          - TestACLTagPropagationPortSpecific
+          - TestACLGroupWithUnknownUser
+          - TestACLGroupAfterUserDeletion
+          - TestACLGroupDeletionExactReproduction
+          - TestACLDynamicUnknownUserAddition
+          - TestACLDynamicUnknownUserRemoval
+          - TestAPIAuthenticationBypass
+          - TestAPIAuthenticationBypassCurl
+          - TestGRPCAuthenticationBypass
+          - TestCLIWithConfigAuthenticationBypass
+          - TestAuthKeyLogoutAndReloginSameUser
+          - TestAuthKeyLogoutAndReloginNewUser
+          - TestAuthKeyLogoutAndReloginSameUserExpiredKey
+          - TestAuthKeyDeleteKey
+          - TestAuthKeyLogoutAndReloginRoutesPreserved
+          - TestOIDCAuthenticationPingAll
+          - TestOIDCExpireNodesBasedOnTokenExpiry
+          - TestOIDC024UserCreation
+          - TestOIDCAuthenticationWithPKCE
+          - TestOIDCReloginSameNodeNewUser
+          - TestOIDCFollowUpUrl
+          - TestOIDCMultipleOpenedLoginUrls
+          - TestOIDCReloginSameNodeSameUser
+          - TestOIDCExpiryAfterRestart
+          - TestOIDCACLPolicyOnJoin
+          - TestOIDCReloginSameUserRoutesPreserved
+          - TestAuthWebFlowAuthenticationPingAll
+          - TestAuthWebFlowLogoutAndReloginSameUser
+          - TestAuthWebFlowLogoutAndReloginNewUser
+          - TestUserCommand
+          - TestPreAuthKeyCommand
+          - TestPreAuthKeyCommandWithoutExpiry
+          - TestPreAuthKeyCommandReusableEphemeral
+          - TestPreAuthKeyCorrectUserLoggedInCommand
+          - TestTaggedNodesCLIOutput
+          - TestApiKeyCommand
+          - TestNodeCommand
+          - TestNodeExpireCommand
+          - TestNodeRenameCommand
+          - TestPolicyCommand
+          - TestPolicyBrokenConfigCommand
+          - TestDERPVerifyEndpoint
+          - TestResolveMagicDNS
+          - TestResolveMagicDNSExtraRecordsPath
+          - TestDERPServerScenario
+          - TestDERPServerWebsocketScenario
+          - TestPingAllByIP
+          - TestPingAllByIPPublicDERP
+          - TestEphemeral
+          - TestEphemeralInAlternateTimezone
+          - TestEphemeral2006DeletedTooQuickly
+          - TestPingAllByHostname
+          - TestTaildrop
+          - TestUpdateHostnameFromClient
+          - TestExpireNode
+          - TestSetNodeExpiryInFuture
+          - TestDisableNodeExpiry
+          - TestNodeOnlineStatus
+          - TestPingAllByIPManyUpDown
+          - Test2118DeletingOnlineNodePanics
+          - TestGrantCapRelay
+          - TestGrantCapDrive
+          - TestEnablingRoutes
+          - TestHASubnetRouterFailover
+          - TestSubnetRouteACL
+          - TestEnablingExitRoutes
+          - TestSubnetRouterMultiNetwork
+          - TestSubnetRouterMultiNetworkExitNode
+          - TestAutoApproveMultiNetwork/authkey-tag.*
+          - TestAutoApproveMultiNetwork/authkey-user.*
+          - TestAutoApproveMultiNetwork/authkey-group.*
+          - TestAutoApproveMultiNetwork/webauth-tag.*
+          - TestAutoApproveMultiNetwork/webauth-user.*
+          - TestAutoApproveMultiNetwork/webauth-group.*
+          - TestSubnetRouteACLFiltering
+          - TestGrantViaSubnetSteering
+          - TestHeadscale
+          - TestTailscaleNodesJoiningHeadcale
+          - TestSSHOneUserToAll
+          - TestSSHMultipleUsersAllToAll
+          - TestSSHNoSSHConfigured
+          - TestSSHIsBlockedInACL
+          - TestSSHUserOnlyIsolation
+          - TestSSHAutogroupSelf
+          - TestSSHOneUserToOneCheckModeCLI
+          - TestSSHOneUserToOneCheckModeOIDC
+          - TestSSHCheckModeUnapprovedTimeout
+          - TestSSHCheckModeCheckPeriodCLI
+          - TestSSHCheckModeAutoApprove
+          - TestSSHCheckModeNegativeCLI
+          - TestSSHLocalpart
+          - TestTagsAuthKeyWithTagRequestDifferentTag
+          - TestTagsAuthKeyWithTagNoAdvertiseFlag
+          - TestTagsAuthKeyWithTagCannotAddViaCLI
+          - TestTagsAuthKeyWithTagCannotChangeViaCLI
+          - TestTagsAuthKeyWithTagAdminOverrideReauthPreserves
+          - TestTagsAuthKeyWithTagCLICannotModifyAdminTags
+          - TestTagsAuthKeyWithoutTagCannotRequestTags
+          - TestTagsAuthKeyWithoutTagRegisterNoTags
+          - TestTagsAuthKeyWithoutTagCannotAddViaCLI
+          - TestTagsAuthKeyWithoutTagCLINoOpAfterAdminWithReset
+          - TestTagsAuthKeyWithoutTagCLINoOpAfterAdminWithEmptyAdvertise
+          - TestTagsAuthKeyWithoutTagCLICannotReduceAdminMultiTag
+          - TestTagsUserLoginOwnedTagAtRegistration
+          - TestTagsUserLoginNonExistentTagAtRegistration
+          - TestTagsUserLoginUnownedTagAtRegistration
+          - TestTagsUserLoginAddTagViaCLIReauth
+          - TestTagsUserLoginRemoveTagViaCLIReauth
+          - TestTagsUserLoginCLINoOpAfterAdminAssignment
+          - TestTagsUserLoginCLICannotRemoveAdminTags
+          - TestTagsAuthKeyWithTagRequestNonExistentTag
+          - TestTagsAuthKeyWithTagRequestUnownedTag
+          - TestTagsAuthKeyWithoutTagRequestNonExistentTag
+          - TestTagsAuthKeyWithoutTagRequestUnownedTag
+          - TestTagsAdminAPICannotSetNonExistentTag
+          - TestTagsAdminAPICanSetUnownedTag
+          - TestTagsAdminAPICannotRemoveAllTags
+          - TestTagsIssue2978ReproTagReplacement
+          - TestTagsAdminAPICannotSetInvalidFormat
+          - TestTagsUserLoginReauthWithEmptyTagsRemovesAllTags
+          - TestTagsAuthKeyWithoutUserInheritsTags
+          - TestTagsAuthKeyWithoutUserRejectsAdvertisedTags
+          - TestTagsAuthKeyConvertToUserViaCLIRegister
+    uses: ./.github/workflows/integration-test-template.yml
+    secrets: inherit
+    with:
+      test: ${{ matrix.test }}
+      postgres_flag: "--postgres=0"
+      database_name: "sqlite"
+  postgres:
+    needs: [build, build-postgres]
+    if: needs.build.outputs.files-changed == 'true'
+    strategy:
+      fail-fast: false
+      matrix:
+        test:
+          - TestACLAllowUserDst
+          - TestPingAllByIP
+          - TestEphemeral2006DeletedTooQuickly
+          - TestPingAllByIPManyUpDown
+          - TestSubnetRouterMultiNetwork
+    uses: ./.github/workflows/integration-test-template.yml
+    secrets: inherit
+    with:
+      test: ${{ matrix.test }}
+      postgres_flag: "--postgres=1"
+      database_name: "postgres"

.github/workflows/test-integration.yml

@@ -1,32 +0,0 @@
-name: CI
-
-on: [pull_request]
-
-jobs:
-  integration-test:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v2
-        with:
-          fetch-depth: 2
-
-      - name: Get changed files
-        id: changed-files
-        uses: tj-actions/changed-files@v14.1
-        with:
-          files: |
-            go.*
-            **/*.go
-            integration_test/
-            config-example.yaml
-
-      - name: Setup Go
-        if: steps.changed-files.outputs.any_changed == 'true'
-        uses: actions/setup-go@v2
-        with:
-          go-version: "1.17.7"
-
-      - name: Run Integration tests
-        if: steps.changed-files.outputs.any_changed == 'true'
-        run: go test -tags integration -timeout 30m

.github/workflows/test.yml

@@ -1,43 +1,47 @@
-name: CI
+name: Tests
 
 on: [push, pull_request]
 
+concurrency:
+  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
   test:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
         with:
           fetch-depth: 2
 
       - name: Get changed files
         id: changed-files
-        uses: tj-actions/changed-files@v14.1
+        uses: dorny/paths-filter@de90cc6fb38fc0963ad72b210f1f284cd68cea36 # v3.0.2
         with:
-          files: |
-            go.*
-            **/*.go
-            integration_test/
-            config-example.yaml
+          filters: |
+            files:
+              - '*.nix'
+              - 'go.*'
+              - '**/*.go'
+              - 'integration_test/'
+              - 'config-example.yaml'
 
-      - name: Setup Go
-        if: steps.changed-files.outputs.any_changed == 'true'
-        uses: actions/setup-go@v2
+      - uses: nixbuild/nix-quick-install-action@2c9db80fb984ceb1bcaa77cdda3fdf8cfba92035 # v34
+        if: steps.changed-files.outputs.files == 'true'
+      - uses: nix-community/cache-nix-action@135667ec418502fa5a3598af6fb9eb733888ce6a # v6.1.3
+        if: steps.changed-files.outputs.files == 'true'
         with:
-          go-version: "1.17.7"
-
-      - name: Install dependencies
-        if: steps.changed-files.outputs.any_changed == 'true'
-        run: |
-          go version
-          sudo apt update
-          sudo apt install -y make
+          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('**/*.nix',
+            '**/flake.lock') }}
+          restore-prefixes-first-match: nix-${{ runner.os }}-${{ runner.arch }}
 
       - name: Run tests
-        if: steps.changed-files.outputs.any_changed == 'true'
-        run: make test
-
-      - name: Run build
-        if: steps.changed-files.outputs.any_changed == 'true'
-        run: make
+        if: steps.changed-files.outputs.files == 'true'
+        env:
+          # As of 2025-01-06, these env vars was not automatically
+          # set anymore which breaks the initdb for postgres on
+          # some of the database migration tests.
+          LC_ALL: "en_US.UTF-8"
+          LC_CTYPE: "en_US.UTF-8"
+        run: nix develop --command -- gotestsum

.github/workflows/update-flake.yml

@@ -0,0 +1,19 @@
+name: update-flake-lock
+on:
+  workflow_dispatch: # allows manual triggering
+  schedule:
+    - cron: "0 0 * * 0" # runs weekly on Sunday at 00:00
+
+jobs:
+  lockfile:
+    if: github.repository == 'juanfont/headscale'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@21a544727d0c62386e78b4befe52d19ad12692e3 # v17
+      - name: Update flake.lock
+        uses: DeterminateSystems/update-flake-lock@428c2b58a4b7414dabd372acb6a03dba1084d3ab # v25
+        with:
+          pr-title: "Update flake.lock"

.gitignore

@@ -1,3 +1,11 @@
+ignored/
+tailscale/
+.vscode/
+.claude/
+logs/
+
+*.prof
+
 # Binaries for programs and plugins
 *.exe
 *.exe~
@@ -12,13 +20,16 @@
 *.out
 
 # Dependency directories (remove the comment below to include it)
-# vendor/
+vendor/
 
+dist/
 /headscale
-config.json
 config.yaml
+config*.yaml
+!config-example.yaml
 derp.yaml
 *.hujson
+!hscontrol/policy/v2/testdata/*/*.hujson
 *.key
 /db.sqlite
 *.sqlite3
@@ -26,4 +37,21 @@ derp.yaml
 # Exclude Jetbrains Editors
 .idea
 
-test_output/ 
+test_output/
+control_logs/
+
+# Nix build output
+result
+.direnv/
+
+integration_test/etc/config.dump.yaml
+
+# MkDocs
+.cache
+/site
+
+__debug_bin
+
+node_modules/
+package-lock.json
+package.json

.golangci.yaml

@@ -1,56 +1,108 @@
 ---
-run:
-  timeout: 10m
-
-issues:
-  skip-dirs:
-    - gen
+version: "2"
 linters:
-  enable-all: true
+  default: all
   disable:
-    - exhaustivestruct
-    - revive
-    - lll
-    - interfacer
-    - scopelint
-    - maligned
-    - golint
-    - gofmt
+    - cyclop
+    - depguard
+    - dupl
+    - exhaustruct
+    - funcorder
+    - funlen
     - gochecknoglobals
     - gochecknoinits
     - gocognit
-    - funlen
-    - exhaustivestruct
-    - tagliatelle
     - godox
+    - interfacebloat
     - ireturn
-
-    # We should strive to enable these:
-    - wrapcheck
-    - dupl
+    - lll
+    - maintidx
     - makezero
-
-    # We might want to enable this, but it might be a lot of work
-    - cyclop
+    - mnd
+    - musttag
     - nestif
-    - wsl # might be incompatible with gofumpt
-    - testpackage
+    - nolintlint
     - paralleltest
+    - revive
+    - tagliatelle
+    - testpackage
+    - varnamelen
+    - wrapcheck
+    - wsl
+  settings:
+    forbidigo:
+      forbid:
+        # Forbid time.Sleep everywhere with context-appropriate alternatives
+        - pattern: 'time\.Sleep'
+          msg: >-
+            time.Sleep is forbidden.
+            In tests: use assert.EventuallyWithT for polling/waiting patterns.
+            In production code: use a backoff strategy (e.g., cenkalti/backoff) or proper synchronization primitives.
+        # Forbid inline string literals in zerolog field methods - use zf.* constants
+        - pattern: '\.(Str|Int|Int8|Int16|Int32|Int64|Uint|Uint8|Uint16|Uint32|Uint64|Float32|Float64|Bool|Dur|Time|TimeDiff|Strs|Ints|Uints|Floats|Bools|Any|Interface)\("[^"]+"'
+          msg: >-
+            Use zf.* constants for zerolog field names instead of string literals.
+            Import "github.com/juanfont/headscale/hscontrol/util/zlog/zf" and use
+            constants like zf.NodeID, zf.UserName, etc. Add new constants to
+            hscontrol/util/zlog/zf/fields.go if needed.
+        # Forbid ptr.To - use Go 1.26 new(expr) instead
+        - pattern: 'ptr\.To\('
+          msg: >-
+            ptr.To is forbidden. Use Go 1.26's new(expr) syntax instead.
+            Example: ptr.To(value) → new(value)
+        # Forbid tsaddr.SortPrefixes - use slices.SortFunc with netip.Prefix.Compare
+        - pattern: 'tsaddr\.SortPrefixes'
+          msg: >-
+            tsaddr.SortPrefixes is forbidden. Use Go 1.26's netip.Prefix.Compare instead.
+            Example: slices.SortFunc(prefixes, netip.Prefix.Compare)
+      analyze-types: true
+    gocritic:
+      disabled-checks:
+        - appendAssign
+        - ifElseChain
+    nlreturn:
+      block-size: 4
+    varnamelen:
+      ignore-names:
+        - err
+        - db
+        - id
+        - ip
+        - ok
+        - c
+        - tt
+        - tx
+        - rx
+        - sb
+        - wg
+        - pr
+        - p
+        - p2
+      ignore-type-assert-ok: true
+      ignore-map-index-ok: true
+  exclusions:
+    generated: lax
+    presets:
+      - comments
+      - common-false-positives
+      - legacy
+      - std-error-handling
+    paths:
+      - third_party$
+      - builtin$
+      - examples$
+      - gen
 
-linters-settings:
-  varnamelen:
-    ignore-type-assert-ok: true
-    ignore-map-index-ok: true
-    ignore-names:
-      - err
-      - db
-      - id
-      - ip
-      - ok
-      - c
-
-  gocritic:
-    disabled-checks:
-      - appendAssign
-      # TODO(kradalby): Remove this
-      - ifElseChain
+formatters:
+  enable:
+    - gci
+    - gofmt
+    - gofumpt
+    - goimports
+  exclusions:
+    generated: lax
+    paths:
+      - third_party$
+      - builtin$
+      - examples$
+      - gen

.goreleaser.yml

@@ -1,89 +1,159 @@
 ---
+version: 2
 before:
   hooks:
-    - go mod tidy -compat=1.17
+    - go mod tidy -compat=1.26
+    - go mod vendor
 
 release:
   prerelease: auto
+  draft: true
+  header: |
+    ## Upgrade
+
+    Please follow the steps outlined in the [upgrade guide](https://headscale.net/stable/setup/upgrade/) to update your existing Headscale installation.
 
 builds:
-  - id: darwin-amd64
-    main: ./cmd/headscale/headscale.go
+  - id: headscale
+    main: ./cmd/headscale
     mod_timestamp: "{{ .CommitTimestamp }}"
-    goos:
-      - darwin
-    goarch:
-      - amd64
     env:
-      - PKG_CONFIG_SYSROOT_DIR=/sysroot/macos/amd64
-      - PKG_CONFIG_PATH=/sysroot/macos/amd64/usr/local/lib/pkgconfig
-      - CC=o64-clang
-      - CXX=o64-clang++
+      - CGO_ENABLED=0
+    targets:
+      - darwin_amd64
+      - darwin_arm64
+      - freebsd_amd64
+      - linux_amd64
+      - linux_arm64
     flags:
       - -mod=readonly
-    ldflags:
-      - -s -w -X github.com/juanfont/headscale/cmd/headscale/cli.Version=v{{.Version}}
-
-  - id: linux-armhf
-    main: ./cmd/headscale/headscale.go
-    mod_timestamp: "{{ .CommitTimestamp }}"
-    goos:
-      - linux
-    goarch:
-      - arm
-    goarm:
-      - "7"
-    env:
-      - CC=arm-linux-gnueabihf-gcc
-      - CXX=arm-linux-gnueabihf-g++
-      - CGO_FLAGS=--sysroot=/sysroot/linux/armhf
-      - CGO_LDFLAGS=--sysroot=/sysroot/linux/armhf
-      - PKG_CONFIG_SYSROOT_DIR=/sysroot/linux/armhf
-      - PKG_CONFIG_PATH=/sysroot/linux/armhf/opt/vc/lib/pkgconfig:/sysroot/linux/armhf/usr/lib/arm-linux-gnueabihf/pkgconfig:/sysroot/linux/armhf/usr/lib/pkgconfig:/sysroot/linux/armhf/usr/local/lib/pkgconfig
-    flags:
-      - -mod=readonly
-    ldflags:
-      - -s -w -X github.com/juanfont/headscale/cmd/headscale/cli.Version=v{{.Version}}
-
-  - id: linux-amd64
-    env:
-      - CGO_ENABLED=1
-    goos:
-      - linux
-    goarch:
-      - amd64
-    main: ./cmd/headscale/headscale.go
-    mod_timestamp: "{{ .CommitTimestamp }}"
-    ldflags:
-      - -s -w -X github.com/juanfont/headscale/cmd/headscale/cli.Version=v{{.Version}}
-
-  - id: linux-arm64
-    goos:
-      - linux
-    goarch:
-      - arm64
-    env:
-      - CGO_ENABLED=1
-      - CC=aarch64-linux-gnu-gcc
-    main: ./cmd/headscale/headscale.go
-    mod_timestamp: "{{ .CommitTimestamp }}"
-    ldflags:
-      - -s -w -X github.com/juanfont/headscale/cmd/headscale/cli.Version=v{{.Version}}
 
 archives:
   - id: golang-cross
-    builds:
-      - darwin-amd64
-      - linux-armhf
-      - linux-amd64
-      - linux-arm64
-    name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
-    format: binary
+    name_template: '{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ with .Arm }}v{{ . }}{{ end }}{{ with .Mips }}_{{ . }}{{ end }}{{ if not (eq .Amd64 "v1") }}{{ .Amd64 }}{{ end }}'
+    formats:
+      - binary
+
+source:
+  enabled: true
+  name_template: "{{ .ProjectName }}_{{ .Version }}"
+  format: tar.gz
+  files:
+    - "vendor/"
+
+nfpms:
+  # Configure nFPM for .deb and .rpm releases
+  #
+  # See https://nfpm.goreleaser.com/configuration/
+  # and https://goreleaser.com/customization/nfpm/
+  #
+  # Useful tools for debugging .debs:
+  # List file contents: dpkg -c dist/headscale...deb
+  # Package metadata: dpkg --info dist/headscale....deb
+  #
+  - ids:
+      - headscale
+    package_name: headscale
+    priority: optional
+    vendor: headscale
+    maintainer: Kristoffer Dalby <kristoffer@dalby.cc>
+    homepage: https://github.com/juanfont/headscale
+    description: |-
+      Open source implementation of the Tailscale control server.
+      Headscale aims to implement a self-hosted, open source alternative to the
+      Tailscale control server. Headscale's goal is to provide self-hosters and
+      hobbyists with an open-source server they can use for their projects and
+      labs. It implements a narrow scope, a single Tailscale network (tailnet),
+      suitable for a personal use, or a small open-source organisation.
+    bindir: /usr/bin
+    section: net
+    formats:
+      - deb
+    contents:
+      - src: ./config-example.yaml
+        dst: /etc/headscale/config.yaml
+        type: config|noreplace
+        file_info:
+          mode: 0644
+      - src: ./packaging/systemd/headscale.service
+        dst: /usr/lib/systemd/system/headscale.service
+      - dst: /var/lib/headscale
+        type: dir
+      - src: LICENSE
+        dst: /usr/share/doc/headscale/copyright
+    scripts:
+      postinstall: ./packaging/deb/postinst
+      postremove: ./packaging/deb/postrm
+      preremove: ./packaging/deb/prerm
+    deb:
+      lintian_overrides:
+        - no-changelog # Our CHANGELOG.md uses a different formatting
+        - no-manual-page
+        - statically-linked-binary
+
+kos:
+  - id: ghcr
+    repositories:
+      - ghcr.io/juanfont/headscale
+      - headscale/headscale
+
+    # bare tells KO to only use the repository
+    # for tagging and naming the container.
+    bare: true
+    base_image: gcr.io/distroless/base-debian13
+    build: headscale
+    main: ./cmd/headscale
+    env:
+      - CGO_ENABLED=0
+    platforms:
+      - linux/amd64
+      - linux/arm64
+    tags:
+      - "{{ if not .Prerelease }}latest{{ end }}"
+      - "{{ if not .Prerelease }}{{ .Major }}.{{ .Minor }}.{{ .Patch }}{{ end }}"
+      - "{{ if not .Prerelease }}{{ .Major }}.{{ .Minor }}{{ end }}"
+      - "{{ if not .Prerelease }}{{ .Major }}{{ end }}"
+      - "{{ if not .Prerelease }}v{{ .Major }}.{{ .Minor }}.{{ .Patch }}{{ end }}"
+      - "{{ if not .Prerelease }}v{{ .Major }}.{{ .Minor }}{{ end }}"
+      - "{{ if not .Prerelease }}v{{ .Major }}{{ end }}"
+      - "{{ if not .Prerelease }}stable{{ else }}unstable{{ end }}"
+      - "{{ .Tag }}"
+      - '{{ trimprefix .Tag "v" }}'
+      - "sha-{{ .ShortCommit }}"
+    creation_time: "{{.CommitTimestamp}}"
+    ko_data_creation_time: "{{.CommitTimestamp}}"
+
+  - id: ghcr-debug
+    repositories:
+      - ghcr.io/juanfont/headscale
+      - headscale/headscale
+
+    bare: true
+    base_image: gcr.io/distroless/base-debian13:debug
+    build: headscale
+    main: ./cmd/headscale
+    env:
+      - CGO_ENABLED=0
+    platforms:
+      - linux/amd64
+      - linux/arm64
+    tags:
+      - "{{ if not .Prerelease }}latest-debug{{ end }}"
+      - "{{ if not .Prerelease }}{{ .Major }}.{{ .Minor }}.{{ .Patch }}-debug{{ end }}"
+      - "{{ if not .Prerelease }}{{ .Major }}.{{ .Minor }}-debug{{ end }}"
+      - "{{ if not .Prerelease }}{{ .Major }}-debug{{ end }}"
+      - "{{ if not .Prerelease }}v{{ .Major }}.{{ .Minor }}.{{ .Patch }}-debug{{ end }}"
+      - "{{ if not .Prerelease }}v{{ .Major }}.{{ .Minor }}-debug{{ end }}"
+      - "{{ if not .Prerelease }}v{{ .Major }}-debug{{ end }}"
+      - "{{ if not .Prerelease }}stable-debug{{ else }}unstable-debug{{ end }}"
+      - "{{ .Tag }}-debug"
+      - '{{ trimprefix .Tag "v" }}-debug'
+      - "sha-{{ .ShortCommit }}-debug"
 
 checksum:
   name_template: "checksums.txt"
 snapshot:
-  name_template: "{{ .Tag }}-next"
+  version_template: "{{ .Tag }}-next"
 changelog:
   sort: asc
   filters:

.mcp.json

@@ -0,0 +1,34 @@
+{
+  "mcpServers": {
+    "claude-code-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@steipete/claude-code-mcp@latest"],
+      "env": {}
+    },
+    "sequential-thinking": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
+      "env": {}
+    },
+    "nixos": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["mcp-nixos"],
+      "env": {}
+    },
+    "context7": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"],
+      "env": {}
+    },
+    "git": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@cyanheads/git-mcp-server"],
+      "env": {}
+    }
+  }
+}

.mdformat.toml

@@ -0,0 +1,2 @@
+[plugin.mkdocs]
+align_semantic_breaks_in_lists = true

.pre-commit-config.yaml

@@ -0,0 +1,62 @@
+# prek/pre-commit configuration for headscale
+# See: https://prek.j178.dev/quickstart/
+# See: https://prek.j178.dev/builtin/
+
+# Global exclusions - ignore generated code
+exclude: ^gen/
+
+repos:
+  # Built-in hooks from pre-commit/pre-commit-hooks
+  # prek will use fast-path optimized versions automatically
+  # See: https://prek.j178.dev/builtin/
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-executables-have-shebangs
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-toml
+      - id: check-xml
+      - id: check-yaml
+      - id: detect-private-key
+      - id: end-of-file-fixer
+      - id: fix-byte-order-marker
+      - id: mixed-line-ending
+      - id: trailing-whitespace
+
+  # Local hooks for project-specific tooling
+  - repo: local
+    hooks:
+      # nixpkgs-fmt for Nix files
+      - id: nixpkgs-fmt
+        name: nixpkgs-fmt
+        entry: nixpkgs-fmt
+        language: system
+        files: \.nix$
+
+      # Prettier for formatting
+      - id: prettier
+        name: prettier
+        entry: prettier --write --list-different
+        language: system
+        exclude: ^docs/
+        types_or: [javascript, jsx, ts, tsx, yaml, json, toml, html, css, scss, sass, markdown]
+
+      # mdformat for docs
+      - id: mdformat
+        name: mdformat
+        entry: mdformat
+        language: system
+        types_or: [markdown]
+        files: ^docs/
+
+      # golangci-lint for Go code quality
+      - id: golangci-lint
+        name: golangci-lint
+        entry: nix develop --command -- golangci-lint run --new-from-rev=HEAD~1 --timeout=5m --fix
+        language: system
+        types: [go]
+        pass_filenames: false

.prettierignore

@@ -0,0 +1,2 @@
+.github/workflows/test-integration-v2*
+docs/

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

CODE_OF_CONDUCT.md

@@ -0,0 +1,134 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation
+in our community a harassment-free experience for everyone, regardless
+of age, body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open,
+welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for
+our community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our
+  mistakes, and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or
+  political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in
+  a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our
+standards of acceptable behavior and will take appropriate and fair
+corrective action in response to any behavior that they deem
+inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit,
+or reject comments, commits, code, wiki edits, issues, and other
+contributions that are not aligned to this Code of Conduct, and will
+communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also
+applies when an individual is officially representing the community in
+public spaces. Examples of representing our community include using an
+official e-mail address, posting via an official social media account,
+or acting as an appointed representative at an online or offline
+event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior
+may be reported to the community leaders responsible for enforcement
+on our [Discord server](https://discord.gg/c84AZQhmpx). All complaints
+will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and
+security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in
+determining the consequences for any action they deem in violation of
+this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior
+deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders,
+providing clarity around the nature of the violation and an
+explanation of why the behavior was inappropriate. A public apology
+may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued
+behavior. No interaction with the people involved, including
+unsolicited interaction with those enforcing the Code of Conduct, for
+a specified period of time. This includes avoiding interactions in
+community spaces as well as external channels like social
+media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards,
+including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or
+public communication with the community for a specified period of
+time. No public or private interaction with the people involved,
+including unsolicited interaction with those enforcing the Code of
+Conduct, is allowed during this period. Violating these terms may lead
+to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of
+community standards, including sustained inappropriate behavior,
+harassment of an individual, or aggression toward or disparagement of
+classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction
+within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor
+Covenant][homepage], version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of
+conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the
+FAQ at https://www.contributor-covenant.org/faq. Translations are
+available at https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Headscale is "Open Source, acknowledged contribution", this means that any contribution will have to be discussed with the maintainers before being added to the project.
+This model has been chosen to reduce the risk of burnout by limiting the maintenance overhead of reviewing and validating third-party code.
+
+## Why do we have this model?
+
+Headscale has a small maintainer team that tries to balance working on the project, fixing bugs and reviewing contributions.
+
+When we work on issues ourselves, we develop first hand knowledge of the code and it makes it possible for us to maintain and own the code as the project develops.
+
+Code contributions are seen as a positive thing. People enjoy and engage with our project, but it also comes with some challenges; we have to understand the code, we have to understand the feature, we might have to become familiar with external libraries or services and we think about security implications. All those steps are required during the reviewing process. After the code has been merged, the feature has to be maintained. Any changes reliant on external services must be updated and expanded accordingly.
+
+The review and day-1 maintenance adds a significant burden on the maintainers. Often we hope that the contributor will help out, but we found that most of the time, they disappear after their new feature was added.
+
+This means that when someone contributes, we are mostly happy about it, but we do have to run it through a series of checks to establish if we actually can maintain this feature.
+
+## What do we require?
+
+A general description is provided here and an explicit list is provided in our pull request template.
+
+All new features have to start out with a design document, which should be discussed on the issue tracker (not discord). It should include a use case for the feature, how it can be implemented, who will implement it and a plan for maintaining it.
+
+All features have to be end-to-end tested (integration tests) and have good unit test coverage to ensure that they work as expected. This will also ensure that the feature continues to work as expected over time. If a change cannot be tested, a strong case for why this is not possible needs to be presented.
+
+The contributor should help to maintain the feature over time. In case the feature is not maintained probably, the maintainers reserve themselves the right to remove features they redeem as unmaintainable. This should help to improve the quality of the software and keep it in a maintainable state.
+
+## Bug fixes
+
+Headscale is open to code contributions for bug fixes without discussion.
+
+## Documentation
+
+If you find mistakes in the documentation, please submit a fix to the documentation.

Dockerfile

@@ -1,22 +0,0 @@
-# Builder image
-FROM docker.io/golang:1.17.7-bullseye AS build
-ENV GOPATH /go
-WORKDIR /go/src/headscale
-
-COPY go.mod go.sum /go/src/headscale/
-RUN go mod download
-
-COPY . .
-
-RUN go install -a -ldflags="-extldflags=-static" -tags netgo,sqlite_omit_load_extension ./cmd/headscale
-RUN strip /go/bin/headscale
-RUN test -e /go/bin/headscale
-
-# Production image
-FROM gcr.io/distroless/base-debian11
-
-COPY --from=build /go/bin/headscale /bin/headscale
-ENV TZ UTC
-
-EXPOSE 8080/tcp
-CMD ["headscale"]

Dockerfile.alpine

@@ -1,23 +0,0 @@
-# Builder image
-FROM docker.io/golang:1.17.7-alpine AS build
-ENV GOPATH /go
-WORKDIR /go/src/headscale
-
-COPY go.mod go.sum /go/src/headscale/
-RUN apk add gcc musl-dev
-RUN go mod download
-
-COPY . .
-
-RUN go install -a -ldflags="-extldflags=-static" -tags netgo,sqlite_omit_load_extension ./cmd/headscale
-RUN strip /go/bin/headscale
-RUN test -e /go/bin/headscale
-
-# Production image
-FROM docker.io/alpine:latest
-
-COPY --from=build /go/bin/headscale /bin/headscale
-ENV TZ UTC
-
-EXPOSE 8080/tcp
-CMD ["headscale"]

Dockerfile.debug

@@ -1,23 +0,0 @@
-# Builder image
-FROM docker.io/golang:1.17.7-bullseye AS build
-ENV GOPATH /go
-WORKDIR /go/src/headscale
-
-COPY go.mod go.sum /go/src/headscale/
-RUN go mod download
-
-COPY . .
-
-RUN go install -a -ldflags="-extldflags=-static" -tags netgo,sqlite_omit_load_extension ./cmd/headscale
-RUN test -e /go/bin/headscale
-
-# Debug image
-FROM gcr.io/distroless/base-debian11:debug
-
-COPY --from=build /go/bin/headscale /bin/headscale
-ENV TZ UTC
-
-# Need to reset the entrypoint or everything will run as a busybox script
-ENTRYPOINT []
-EXPOSE 8080/tcp
-CMD ["headscale"]

Dockerfile.derper

@@ -0,0 +1,19 @@
+# For testing purposes only
+
+FROM golang:1.26.1-alpine AS build-env
+
+WORKDIR /go/src
+
+RUN apk add --no-cache git
+ARG VERSION_BRANCH=main
+RUN git clone https://github.com/tailscale/tailscale.git --branch=$VERSION_BRANCH --depth=1
+WORKDIR /go/src/tailscale
+
+ARG TARGETARCH
+RUN GOARCH=$TARGETARCH go install -v ./cmd/derper
+
+FROM alpine:3.22
+RUN apk add --no-cache ca-certificates iptables iproute2 ip6tables curl
+
+COPY --from=build-env /go/bin/* /usr/local/bin/
+ENTRYPOINT [ "/usr/local/bin/derper" ]

Dockerfile.integration

@@ -0,0 +1,44 @@
+# This Dockerfile and the images produced are for testing headscale,
+# and are in no way endorsed by Headscale's maintainers as an
+# official nor supported release or distribution.
+
+FROM docker.io/golang:1.26.1-trixie AS builder
+ARG VERSION=dev
+ENV GOPATH /go
+WORKDIR /go/src/headscale
+
+# Install delve debugger first - rarely changes, good cache candidate
+RUN go install github.com/go-delve/delve/cmd/dlv@latest
+
+# Download dependencies - only invalidated when go.mod/go.sum change
+COPY go.mod go.sum /go/src/headscale/
+RUN go mod download
+
+# Copy source and build - invalidated on any source change
+COPY . .
+
+# Build debug binary with debug symbols for delve
+RUN CGO_ENABLED=0 GOOS=linux go build -gcflags="all=-N -l" -o /go/bin/headscale ./cmd/headscale
+
+# Runtime stage
+FROM debian:trixie-slim
+
+RUN apt-get --update install --no-install-recommends --yes \
+    bash ca-certificates curl dnsutils findutils iproute2 jq less procps python3 sqlite3 \
+  && apt-get dist-clean
+
+RUN mkdir -p /var/run/headscale
+
+# Copy binaries from builder
+COPY --from=builder /go/bin/headscale /usr/local/bin/headscale
+COPY --from=builder /go/bin/dlv /usr/local/bin/dlv
+
+# Copy source code for delve source-level debugging
+COPY --from=builder /go/src/headscale /go/src/headscale
+
+WORKDIR /go/src/headscale
+
+# Need to reset the entrypoint or everything will run as a busybox script
+ENTRYPOINT []
+EXPOSE 8080/tcp 40000/tcp
+CMD ["dlv", "--listen=0.0.0.0:40000", "--headless=true", "--api-version=2", "--accept-multiclient", "exec", "/usr/local/bin/headscale", "--"]

Dockerfile.integration-ci

@@ -0,0 +1,17 @@
+# Minimal CI image - expects pre-built headscale binary in build context
+# For local development with delve debugging, use Dockerfile.integration instead
+
+FROM debian:trixie-slim
+
+RUN apt-get --update install --no-install-recommends --yes \
+    bash ca-certificates curl dnsutils findutils iproute2 jq less procps python3 sqlite3 \
+  && apt-get dist-clean
+
+RUN mkdir -p /var/run/headscale
+
+# Copy pre-built headscale binary from build context
+COPY headscale /usr/local/bin/headscale
+
+ENTRYPOINT []
+EXPOSE 8080/tcp
+CMD ["/usr/local/bin/headscale"]

Dockerfile.tailscale

@@ -1,11 +0,0 @@
-FROM ubuntu:latest
-
-ARG TAILSCALE_VERSION
-
-RUN apt-get update \
-    && apt-get install -y gnupg curl \
-    && curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/focal.gpg | apt-key add - \
-    && curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/focal.list | tee /etc/apt/sources.list.d/tailscale.list \
-    && apt-get update \
-    && apt-get install -y tailscale=${TAILSCALE_VERSION} dnsutils \
-    && rm -rf /var/lib/apt/lists/*

Dockerfile.tailscale-HEAD

@@ -0,0 +1,47 @@
+# Copyright (c) Tailscale Inc & AUTHORS
+# SPDX-License-Identifier: BSD-3-Clause
+
+# This Dockerfile is more or less lifted from tailscale/tailscale
+# to ensure a similar build process when testing the HEAD of tailscale.
+
+FROM golang:1.26.1-alpine AS build-env
+
+WORKDIR /go/src
+
+RUN apk add --no-cache git
+
+# Replace `RUN git...` with `COPY` and a local checked out version of Tailscale in `./tailscale`
+# to test specific commits of the Tailscale client. This is useful when trying to find out why
+# something specific broke between two versions of Tailscale with for example `git bisect`.
+# COPY ./tailscale .
+RUN git clone https://github.com/tailscale/tailscale.git
+
+WORKDIR /go/src/tailscale
+
+
+# see build_docker.sh
+ARG VERSION_LONG=""
+ENV VERSION_LONG=$VERSION_LONG
+ARG VERSION_SHORT=""
+ENV VERSION_SHORT=$VERSION_SHORT
+ARG VERSION_GIT_HASH=""
+ENV VERSION_GIT_HASH=$VERSION_GIT_HASH
+ARG TARGETARCH
+
+ARG BUILD_TAGS=""
+
+RUN GOARCH=$TARGETARCH go install -tags="${BUILD_TAGS}" -ldflags="\
+      -X tailscale.com/version.longStamp=$VERSION_LONG \
+      -X tailscale.com/version.shortStamp=$VERSION_SHORT \
+      -X tailscale.com/version.gitCommitStamp=$VERSION_GIT_HASH" \
+      -v ./cmd/tailscale ./cmd/tailscaled ./cmd/containerboot
+
+FROM alpine:3.22
+# Upstream: ca-certificates ip6tables iptables iproute2
+# Tests: curl python3 (traceroute via BusyBox)
+RUN apk add --no-cache ca-certificates curl ip6tables iptables iproute2 python3
+
+COPY --from=build-env /go/bin/* /usr/local/bin/
+# For compat with the previous run.sh, although ideally you should be
+# using build_docker.sh which sets an entrypoint for the image.
+RUN mkdir /tailscale && ln -s /usr/local/bin/containerboot /tailscale/run.sh

Makefile

@@ -1,55 +1,135 @@
-# Calculate version
-version = $(shell ./scripts/version-at-commit.sh)
+# Headscale Makefile
+# Modern Makefile following best practices
 
-rwildcard=$(foreach d,$(wildcard $1*),$(call rwildcard,$d/,$2) $(filter $(subst *,%,$2),$d))
+# Version calculation
+VERSION ?= $(shell git describe --always --tags --dirty)
 
-# GO_SOURCES = $(wildcard *.go)
-# PROTO_SOURCES = $(wildcard **/*.proto)
-GO_SOURCES = $(call rwildcard,,*.go)
-PROTO_SOURCES = $(call rwildcard,,*.proto)
+# Build configuration
+GOOS ?= $(shell uname | tr '[:upper:]' '[:lower:]')
+ifeq ($(filter $(GOOS), openbsd netbsd solaris plan9), )
+	PIE_FLAGS = -buildmode=pie
+endif
+
+# Tool availability check with nix warning
+define check_tool
+	@command -v $(1) >/dev/null 2>&1 || { \
+		echo "Warning: $(1) not found. Run 'nix develop' to ensure all dependencies are available."; \
+		exit 1; \
+	}
+endef
+
+# Source file collections using shell find for better performance
+GO_SOURCES := $(shell find . -name '*.go' -not -path './gen/*' -not -path './vendor/*')
+PROTO_SOURCES := $(shell find . -name '*.proto' -not -path './gen/*' -not -path './vendor/*')
+PRETTIER_SOURCES := $(shell find . \( -name '*.md' -o -name '*.yaml' -o -name '*.yml' -o -name '*.ts' -o -name '*.js' -o -name '*.html' -o -name '*.css' -o -name '*.scss' -o -name '*.sass' \) -not -path './gen/*' -not -path './vendor/*' -not -path './node_modules/*')
+
+# Default target
+.PHONY: all
+all: lint test build
+
+# Dependency checking
+.PHONY: check-deps
+check-deps:
+	$(call check_tool,go)
+	$(call check_tool,golangci-lint)
+	$(call check_tool,gofumpt)
+	$(call check_tool,mdformat)
+	$(call check_tool,prettier)
+	$(call check_tool,clang-format)
+	$(call check_tool,buf)
+
+# Build targets
+.PHONY: build
+build: check-deps $(GO_SOURCES) go.mod go.sum
+	@echo "Building headscale..."
+	go build $(PIE_FLAGS) -ldflags "-X main.version=$(VERSION)" -o headscale ./cmd/headscale
+
+# Test targets
+.PHONY: test
+test: check-deps $(GO_SOURCES) go.mod go.sum
+	@echo "Running Go tests..."
+	go test -race ./...
 
 
-build:
-	go build -ldflags "-s -w -X github.com/juanfont/headscale/cmd/headscale/cli.Version=$(version)" cmd/headscale/headscale.go
+# Formatting targets
+.PHONY: fmt
+fmt: fmt-go fmt-mdformat fmt-prettier fmt-proto
 
-dev: lint test build
+.PHONY: fmt-go
+fmt-go: check-deps $(GO_SOURCES)
+	@echo "Formatting Go code..."
+	gofumpt -l -w .
+	golangci-lint run --fix
 
-test:
-	@go test -coverprofile=coverage.out ./...
+.PHONY: fmt-mdformat
+fmt-mdformat: check-deps
+	@echo "Formatting documentation..."
+	mdformat docs/
 
-test_integration:
-	go test -tags integration -timeout 30m -count=1 ./...
+.PHONY: fmt-prettier
+fmt-prettier: check-deps $(PRETTIER_SOURCES)
+	@echo "Formatting markup and config files..."
+	prettier --write '**/*.{ts,js,md,yaml,yml,sass,css,scss,html}'
 
-test_integration_cli:
-	go test -tags integration -v integration_cli_test.go integration_common_test.go
+.PHONY: fmt-proto
+fmt-proto: check-deps $(PROTO_SOURCES)
+	@echo "Formatting Protocol Buffer files..."
+	clang-format -i $(PROTO_SOURCES)
 
-coverprofile_func:
-	go tool cover -func=coverage.out
+# Linting targets
+.PHONY: lint
+lint: lint-go lint-proto
 
-coverprofile_html:
-	go tool cover -html=coverage.out
+.PHONY: lint-go
+lint-go: check-deps $(GO_SOURCES) go.mod go.sum
+	@echo "Linting Go code..."
+	golangci-lint run --timeout 10m
 
-lint:
-	golangci-lint run --fix --timeout 10m
-
-fmt:
-	prettier --write '**/**.{ts,js,md,yaml,yml,sass,css,scss,html}'
-	golines --max-len=88 --base-formatter=gofumpt -w $(GO_SOURCES)
-	clang-format -style="{BasedOnStyle: Google, IndentWidth: 4, AlignConsecutiveDeclarations: true, AlignConsecutiveAssignments: true, ColumnLimit: 0}" -i $(PROTO_SOURCES)
-
-proto-lint:
+.PHONY: lint-proto
+lint-proto: check-deps $(PROTO_SOURCES)
+	@echo "Linting Protocol Buffer files..."
 	cd proto/ && buf lint
 
-compress: build
-	upx --brute headscale
+# Code generation
+.PHONY: generate
+generate: check-deps
+	@echo "Generating code..."
+	go generate ./...
 
-generate:
-	rm -rf gen
-	buf generate proto
+# Clean targets
+.PHONY: clean
+clean:
+	rm -rf headscale gen
 
-install-protobuf-plugins:
-	go install \
-		github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway \
-		github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2 \
-		google.golang.org/protobuf/cmd/protoc-gen-go \
-		google.golang.org/grpc/cmd/protoc-gen-go-grpc
+# Development workflow
+.PHONY: dev
+dev: fmt lint test build
+
+# Help target
+.PHONY: help
+help:
+	@echo "Headscale Development Makefile"
+	@echo ""
+	@echo "Main targets:"
+	@echo "  all          - Run lint, test, and build (default)"
+	@echo "  build        - Build headscale binary"
+	@echo "  test         - Run Go tests"
+	@echo "  fmt          - Format all code (Go, docs, proto)"
+	@echo "  lint         - Lint all code (Go, proto)"
+	@echo "  generate     - Generate code from Protocol Buffers"
+	@echo "  dev          - Full development workflow (fmt + lint + test + build)"
+	@echo "  clean        - Clean build artifacts"
+	@echo ""
+	@echo "Specific targets:"
+	@echo "  fmt-go       - Format Go code only"
+	@echo "  fmt-mdformat - Format documentation only"
+	@echo "  fmt-prettier - Format markup and config files only"
+	@echo "  fmt-proto    - Format Protocol Buffer files only"
+	@echo "  lint-go      - Lint Go code only"
+	@echo "  lint-proto   - Lint Protocol Buffer files only"
+	@echo ""
+	@echo "Dependencies:"
+	@echo "  check-deps   - Verify required tools are available"
+	@echo ""
+	@echo "Note: If not running in a nix shell, ensure dependencies are available:"
+	@echo "  nix develop"

README.md

@@ -1,77 +1,108 @@
-# headscale
+![headscale logo](./docs/assets/logo/headscale3_header_stacked_left.png)
 
 ![ci](https://github.com/juanfont/headscale/actions/workflows/test.yml/badge.svg)
 
-An open source, self-hosted implementation of the Tailscale coordination server.
+An open source, self-hosted implementation of the Tailscale control server.
 
-Join our [Discord](https://discord.gg/XcQxk2VHjx) server for a chat.
+Join our [Discord server](https://discord.gg/c84AZQhmpx) for a chat.
 
-**Note:** Always select the same GitHub tag as the released version you use to ensure you have the correct example configuration and documentation. The `main` branch might contain unreleased changes.
+**Note:** Always select the same GitHub tag as the released version you use
+to ensure you have the correct example configuration. The `main` branch might
+contain unreleased changes. The documentation is available for stable and
+development versions:
 
-## Overview
+- [Documentation for the stable version](https://headscale.net/stable/)
+- [Documentation for the development version](https://headscale.net/development/)
 
-Tailscale is [a modern VPN](https://tailscale.com/) built on top of [Wireguard](https://www.wireguard.com/). It [works like an overlay network](https://tailscale.com/blog/how-tailscale-works/) between the computers of your networks - using all kinds of [NAT traversal sorcery](https://tailscale.com/blog/how-nat-traversal-works/).
+## What is Tailscale
 
-Everything in Tailscale is Open Source, except the GUI clients for proprietary OS (Windows and macOS/iOS), and the 'coordination/control server'.
+Tailscale is [a modern VPN](https://tailscale.com/) built on top of
+[Wireguard](https://www.wireguard.com/).
+It [works like an overlay network](https://tailscale.com/blog/how-tailscale-works/)
+between the computers of your networks - using
+[NAT traversal](https://tailscale.com/blog/how-nat-traversal-works/).
 
-The control server works as an exchange point of Wireguard public keys for the nodes in the Tailscale network. It also assigns the IP addresses of the clients, creates the boundaries between each user, enables sharing machines between users, and exposes the advertised routes of your nodes.
+Everything in Tailscale is Open Source, except the GUI clients for proprietary OS
+(Windows and macOS/iOS), and the control server.
 
-headscale implements this coordination server.
+The control server works as an exchange point of Wireguard public keys for the
+nodes in the Tailscale network. It assigns the IP addresses of the clients,
+creates the boundaries between each user, enables sharing machines between users,
+and exposes the advertised routes of your nodes.
 
-## Support
+A [Tailscale network (tailnet)](https://tailscale.com/kb/1136/tailnet/) is private
+network which Tailscale assigns to a user in terms of private users or an
+organisation.
 
-If you like `headscale` and find it useful, there is sponsorship and donation buttons available in the repo.
+## Design goal
 
-If you would like to sponsor features, bugs or prioritisation, reach out to one of the maintainers.
+Headscale aims to implement a self-hosted, open source alternative to the
+[Tailscale](https://tailscale.com/) control server. Headscale's goal is to
+provide self-hosters and hobbyists with an open-source server they can use for
+their projects and labs. It implements a narrow scope, a _single_ Tailscale
+network (tailnet), suitable for a personal use, or a small open-source
+organisation.
 
-## Status
+## Supporting Headscale
 
-- [x] Base functionality (nodes can communicate with each other)
-- [x] Node registration through the web flow
-- [x] Network changes are relayed to the nodes
-- [x] Namespaces support (~tailnets in Tailscale.com naming)
-- [x] Routing (advertise & accept, including exit nodes)
-- [x] Node registration via pre-auth keys (including reusable keys, and ephemeral node support)
-- [x] JSON-formatted output
-- [x] ACLs
-- [x] Taildrop (File Sharing)
-- [x] Support for alternative IP ranges in the tailnets (default Tailscale's 100.64.0.0/10)
-- [x] DNS (passing DNS servers to nodes)
-- [x] Single-Sign-On (via Open ID Connect)
-- [x] Share nodes between namespaces
-- [x] MagicDNS (see `docs/`)
+If you like `headscale` and find it useful, there is a sponsorship and donation
+buttons available in the repo.
+
+## Features
+
+Please see ["Features" in the documentation](https://headscale.net/stable/about/features/).
 
 ## Client OS support
 
-| OS      | Supports headscale                                                                                                |
-| ------- | ----------------------------------------------------------------------------------------------------------------- |
-| Linux   | Yes                                                                                                               |
-| OpenBSD | Yes                                                                                                               |
-| macOS   | Yes (see `/apple` on your headscale for more information)                                                         |
-| Windows | Yes [docs](./docs/windows-client.md)                                                                              |
-| Android | [You need to compile the client yourself](https://github.com/juanfont/headscale/issues/58#issuecomment-885255270) |
-| iOS     | Not yet                                                                                                           |
-
-## Roadmap 🤷
-
-Suggestions/PRs welcomed!
+Please see ["Client and operating system support" in the documentation](https://headscale.net/stable/about/clients/).
 
 ## Running headscale
 
-Please have a look at the documentation under [`docs/`](docs/).
+**Please note that we do not support nor encourage the use of reverse proxies
+and container to run Headscale.**
+
+Please have a look at the [`documentation`](https://headscale.net/stable/).
+
+For NixOS users, a module is available in [`nix/`](./nix/).
+
+## Builds from `main`
+
+Development builds from the `main` branch are available as container images and
+binaries. See the [development builds](https://headscale.net/stable/setup/install/main/)
+documentation for details.
+
+## Talks
+
+- Fosdem 2026 (video): [Headscale & Tailscale: The complementary open source clone](https://fosdem.org/2026/schedule/event/KYQ3LL-headscale-the-complementary-open-source-clone/)
+  - presented by Kristoffer Dalby
+- Fosdem 2023 (video): [Headscale: How we are using integration testing to reimplement Tailscale](https://fosdem.org/2023/schedule/event/goheadscale/)
+  - presented by Juan Font Alonso and Kristoffer Dalby
 
 ## Disclaimer
 
-1. We have nothing to do with Tailscale, or Tailscale Inc.
-2. The purpose of Headscale is maintaining a working, self-hosted Tailscale control panel.
+This project is not associated with Tailscale Inc.
+
+However, one of the active maintainers for Headscale [is employed by Tailscale](https://tailscale.com/blog/opensource) and he is allowed to spend work hours contributing to the project. Contributions from this maintainer are reviewed by other maintainers.
+
+The maintainers work together on setting the direction for the project. The underlying principle is to serve the community of self-hosters, enthusiasts and hobbyists - while having a sustainable project.
 
 ## Contributing
 
-To contribute to Headscale you would need the lastest version of [Go](https://golang.org) and [Buf](https://buf.build)(Protobuf generator).
+Please read the [CONTRIBUTING.md](./CONTRIBUTING.md) file.
+
+### Requirements
+
+To contribute to headscale you would need the latest version of [Go](https://golang.org)
+and [Buf](https://buf.build) (Protobuf generator).
+
+We recommend using [Nix](https://nixos.org/) to setup a development environment. This can
+be done with `nix develop`, which will install the tools and give you a shell.
+This guarantees that you will have the same dev env as `headscale` maintainers.
 
 ### Code style
 
-To ensure we have some consistency with a growing number of contributions, this project has adopted linting and style/formatting rules:
+To ensure we have some consistency with a growing number of contributions,
+this project has adopted linting and style/formatting rules:
 
 The **Go** code is linted with [`golangci-lint`](https://golangci-lint.run) and
 formatted with [`golines`](https://github.com/segmentio/golines) (width 88) and
@@ -82,6 +113,8 @@ run `make lint` and `make fmt` before committing any code.
 The **Proto** code is linted with [`buf`](https://docs.buf.build/lint/overview) and
 formatted with [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html).
 
+The **docs** are formatted with [`mdformat`](https://mdformat.readthedocs.io).
+
 The **rest** (Markdown, YAML, etc) is formatted with [`prettier`](https://prettier.io).
 
 Check out the `.golangci.yaml` and `Makefile` to see the specific configuration.
@@ -90,15 +123,18 @@ Check out the `.golangci.yaml` and `Makefile` to see the specific configuration.
 
 - Go
 - Buf
-- Protobuf tools:
+- Protobuf tools
+
+Install and activate:
 
 ```shell
-make install-protobuf-plugins
+nix develop
 ```
 
 ### Testing and building
 
-Some parts of the project require the generation of Go code from Protobuf (if changes are made in `proto/`) and it must be (re-)generated with:
+Some parts of the project require the generation of Go code from Protobuf
+(if changes are made in `proto/`) and it must be (re-)generated with:
 
 ```shell
 make generate
@@ -118,169 +154,31 @@ To build the program:
 make build
 ```
 
+### Development workflow
+
+We recommend using Nix for dependency management to ensure you have all required tools. If you prefer to manage dependencies yourself, you can use Make directly:
+
+**With Nix (recommended):**
+
+```shell
+nix develop
+make test
+make build
+```
+
+**With your own dependencies:**
+
+```shell
+make test
+make build
+```
+
+The Makefile will warn you if any required tools are missing and suggest running `nix develop`. Run `make help` to see all available targets.
+
 ## Contributors
 
-<table>
-<tr>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/juanfont>
-            <img src=https://avatars.githubusercontent.com/u/181059?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Juan Font/>
-            <br />
-            <sub style="font-size:14px"><b>Juan Font</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/kradalby>
-            <img src=https://avatars.githubusercontent.com/u/98431?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Kristoffer Dalby/>
-            <br />
-            <sub style="font-size:14px"><b>Kristoffer Dalby</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/cure>
-            <img src=https://avatars.githubusercontent.com/u/149135?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Ward Vandewege/>
-            <br />
-            <sub style="font-size:14px"><b>Ward Vandewege</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/ohdearaugustin>
-            <img src=https://avatars.githubusercontent.com/u/14001491?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=ohdearaugustin/>
-            <br />
-            <sub style="font-size:14px"><b>ohdearaugustin</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/unreality>
-            <img src=https://avatars.githubusercontent.com/u/352522?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=unreality/>
-            <br />
-            <sub style="font-size:14px"><b>unreality</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/qbit>
-            <img src=https://avatars.githubusercontent.com/u/68368?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Aaron Bieber/>
-            <br />
-            <sub style="font-size:14px"><b>Aaron Bieber</b></sub>
-        </a>
-    </td>
-</tr>
-<tr>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/ptman>
-            <img src=https://avatars.githubusercontent.com/u/24669?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Paul Tötterman/>
-            <br />
-            <sub style="font-size:14px"><b>Paul Tötterman</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/cmars>
-            <img src=https://avatars.githubusercontent.com/u/23741?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Casey Marshall/>
-            <br />
-            <sub style="font-size:14px"><b>Casey Marshall</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/SilverBut>
-            <img src=https://avatars.githubusercontent.com/u/6560655?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Silver Bullet/>
-            <br />
-            <sub style="font-size:14px"><b>Silver Bullet</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/t56k>
-            <img src=https://avatars.githubusercontent.com/u/12165422?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=thomas/>
-            <br />
-            <sub style="font-size:14px"><b>thomas</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/awoimbee>
-            <img src=https://avatars.githubusercontent.com/u/22431493?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Arthur Woimbée/>
-            <br />
-            <sub style="font-size:14px"><b>Arthur Woimbée</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/fkr>
-            <img src=https://avatars.githubusercontent.com/u/51063?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Felix Kronlage-Dammers/>
-            <br />
-            <sub style="font-size:14px"><b>Felix Kronlage-Dammers</b></sub>
-        </a>
-    </td>
-</tr>
-<tr>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/felixonmars>
-            <img src=https://avatars.githubusercontent.com/u/1006477?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Felix Yan/>
-            <br />
-            <sub style="font-size:14px"><b>Felix Yan</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/shaananc>
-            <img src=https://avatars.githubusercontent.com/u/2287839?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Shaanan Cohney/>
-            <br />
-            <sub style="font-size:14px"><b>Shaanan Cohney</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/Teteros>
-            <img src=https://avatars.githubusercontent.com/u/5067989?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Teteros/>
-            <br />
-            <sub style="font-size:14px"><b>Teteros</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/gitter-badger>
-            <img src=https://avatars.githubusercontent.com/u/8518239?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=The Gitter Badger/>
-            <br />
-            <sub style="font-size:14px"><b>The Gitter Badger</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/tianon>
-            <img src=https://avatars.githubusercontent.com/u/161631?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Tianon Gravi/>
-            <br />
-            <sub style="font-size:14px"><b>Tianon Gravi</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/woudsma>
-            <img src=https://avatars.githubusercontent.com/u/6162978?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Tjerk Woudsma/>
-            <br />
-            <sub style="font-size:14px"><b>Tjerk Woudsma</b></sub>
-        </a>
-    </td>
-</tr>
-<tr>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/zekker6>
-            <img src=https://avatars.githubusercontent.com/u/1367798?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Zakhar Bessarab/>
-            <br />
-            <sub style="font-size:14px"><b>Zakhar Bessarab</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/derelm>
-            <img src=https://avatars.githubusercontent.com/u/465155?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=derelm/>
-            <br />
-            <sub style="font-size:14px"><b>derelm</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/ignoramous>
-            <img src=https://avatars.githubusercontent.com/u/852289?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=ignoramous/>
-            <br />
-            <sub style="font-size:14px"><b>ignoramous</b></sub>
-        </a>
-    </td>
-    <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0">
-        <a href=https://github.com/xpzouying>
-            <img src=https://avatars.githubusercontent.com/u/3946563?v=4 width="100;"  style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=zy/>
-            <br />
-            <sub style="font-size:14px"><b>zy</b></sub>
-        </a>
-    </td>
-</tr>
-</table>
+<a href="https://github.com/juanfont/headscale/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=juanfont/headscale" />
+</a>
+
+Made with [contrib.rocks](https://contrib.rocks).

acls.go

@@ -1,308 +0,0 @@
-package headscale
-
-import (
-	"encoding/json"
-	"fmt"
-	"io"
-	"os"
-	"strconv"
-	"strings"
-
-	"github.com/rs/zerolog/log"
-	"github.com/tailscale/hujson"
-	"inet.af/netaddr"
-	"tailscale.com/tailcfg"
-)
-
-const (
-	errEmptyPolicy        = Error("empty policy")
-	errInvalidAction      = Error("invalid action")
-	errInvalidUserSection = Error("invalid user section")
-	errInvalidGroup       = Error("invalid group")
-	errInvalidTag         = Error("invalid tag")
-	errInvalidNamespace   = Error("invalid namespace")
-	errInvalidPortFormat  = Error("invalid port format")
-)
-
-const (
-	Base8              = 8
-	Base10             = 10
-	BitSize16          = 16
-	BitSize32          = 32
-	BitSize64          = 64
-	portRangeBegin     = 0
-	portRangeEnd       = 65535
-	expectedTokenItems = 2
-)
-
-// LoadACLPolicy loads the ACL policy from the specify path, and generates the ACL rules.
-func (h *Headscale) LoadACLPolicy(path string) error {
-	log.Debug().
-		Str("func", "LoadACLPolicy").
-		Str("path", path).
-		Msg("Loading ACL policy from path")
-
-	policyFile, err := os.Open(path)
-	if err != nil {
-		return err
-	}
-	defer policyFile.Close()
-
-	var policy ACLPolicy
-	policyBytes, err := io.ReadAll(policyFile)
-	if err != nil {
-		return err
-	}
-
-	ast, err := hujson.Parse(policyBytes)
-	if err != nil {
-		return err
-	}
-	ast.Standardize()
-	policyBytes = ast.Pack()
-	err = json.Unmarshal(policyBytes, &policy)
-	if err != nil {
-		return err
-	}
-	if policy.IsZero() {
-		return errEmptyPolicy
-	}
-
-	h.aclPolicy = &policy
-	rules, err := h.generateACLRules()
-	if err != nil {
-		return err
-	}
-	h.aclRules = rules
-
-	log.Trace().Interface("ACL", rules).Msg("ACL rules generated")
-
-	return nil
-}
-
-func (h *Headscale) generateACLRules() ([]tailcfg.FilterRule, error) {
-	rules := []tailcfg.FilterRule{}
-
-	for index, acl := range h.aclPolicy.ACLs {
-		if acl.Action != "accept" {
-			return nil, errInvalidAction
-		}
-
-		filterRule := tailcfg.FilterRule{}
-
-		srcIPs := []string{}
-		for innerIndex, user := range acl.Users {
-			srcs, err := h.generateACLPolicySrcIP(user)
-			if err != nil {
-				log.Error().
-					Msgf("Error parsing ACL %d, User %d", index, innerIndex)
-
-				return nil, err
-			}
-			srcIPs = append(srcIPs, srcs...)
-		}
-		filterRule.SrcIPs = srcIPs
-
-		destPorts := []tailcfg.NetPortRange{}
-		for innerIndex, ports := range acl.Ports {
-			dests, err := h.generateACLPolicyDestPorts(ports)
-			if err != nil {
-				log.Error().
-					Msgf("Error parsing ACL %d, Port %d", index, innerIndex)
-
-				return nil, err
-			}
-			destPorts = append(destPorts, dests...)
-		}
-
-		rules = append(rules, tailcfg.FilterRule{
-			SrcIPs:   srcIPs,
-			DstPorts: destPorts,
-		})
-	}
-
-	return rules, nil
-}
-
-func (h *Headscale) generateACLPolicySrcIP(u string) ([]string, error) {
-	return h.expandAlias(u)
-}
-
-func (h *Headscale) generateACLPolicyDestPorts(
-	d string,
-) ([]tailcfg.NetPortRange, error) {
-	tokens := strings.Split(d, ":")
-	if len(tokens) < expectedTokenItems || len(tokens) > 3 {
-		return nil, errInvalidPortFormat
-	}
-
-	var alias string
-	// We can have here stuff like:
-	// git-server:*
-	// 192.168.1.0/24:22
-	// tag:montreal-webserver:80,443
-	// tag:api-server:443
-	// example-host-1:*
-	if len(tokens) == expectedTokenItems {
-		alias = tokens[0]
-	} else {
-		alias = fmt.Sprintf("%s:%s", tokens[0], tokens[1])
-	}
-
-	expanded, err := h.expandAlias(alias)
-	if err != nil {
-		return nil, err
-	}
-	ports, err := h.expandPorts(tokens[len(tokens)-1])
-	if err != nil {
-		return nil, err
-	}
-
-	dests := []tailcfg.NetPortRange{}
-	for _, d := range expanded {
-		for _, p := range *ports {
-			pr := tailcfg.NetPortRange{
-				IP:    d,
-				Ports: p,
-			}
-			dests = append(dests, pr)
-		}
-	}
-
-	return dests, nil
-}
-
-func (h *Headscale) expandAlias(alias string) ([]string, error) {
-	if alias == "*" {
-		return []string{"*"}, nil
-	}
-
-	if strings.HasPrefix(alias, "group:") {
-		if _, ok := h.aclPolicy.Groups[alias]; !ok {
-			return nil, errInvalidGroup
-		}
-		ips := []string{}
-		for _, n := range h.aclPolicy.Groups[alias] {
-			nodes, err := h.ListMachinesInNamespace(n)
-			if err != nil {
-				return nil, errInvalidNamespace
-			}
-			for _, node := range nodes {
-				ips = append(ips, node.IPAddresses.ToStringSlice()...)
-			}
-		}
-
-		return ips, nil
-	}
-
-	if strings.HasPrefix(alias, "tag:") {
-		if _, ok := h.aclPolicy.TagOwners[alias]; !ok {
-			return nil, errInvalidTag
-		}
-
-		// This will have HORRIBLE performance.
-		// We need to change the data model to better store tags
-		machines := []Machine{}
-		if err := h.db.Where("registered").Find(&machines).Error; err != nil {
-			return nil, err
-		}
-		ips := []string{}
-		for _, machine := range machines {
-			hostinfo := tailcfg.Hostinfo{}
-			if len(machine.HostInfo) != 0 {
-				hi, err := machine.HostInfo.MarshalJSON()
-				if err != nil {
-					return nil, err
-				}
-				err = json.Unmarshal(hi, &hostinfo)
-				if err != nil {
-					return nil, err
-				}
-
-				// FIXME: Check TagOwners allows this
-				for _, t := range hostinfo.RequestTags {
-					if alias[4:] == t {
-						ips = append(ips, machine.IPAddresses.ToStringSlice()...)
-
-						break
-					}
-				}
-			}
-		}
-
-		return ips, nil
-	}
-
-	n, err := h.GetNamespace(alias)
-	if err == nil {
-		nodes, err := h.ListMachinesInNamespace(n.Name)
-		if err != nil {
-			return nil, err
-		}
-		ips := []string{}
-		for _, n := range nodes {
-			ips = append(ips, n.IPAddresses.ToStringSlice()...)
-		}
-
-		return ips, nil
-	}
-
-	if h, ok := h.aclPolicy.Hosts[alias]; ok {
-		return []string{h.String()}, nil
-	}
-
-	ip, err := netaddr.ParseIP(alias)
-	if err == nil {
-		return []string{ip.String()}, nil
-	}
-
-	cidr, err := netaddr.ParseIPPrefix(alias)
-	if err == nil {
-		return []string{cidr.String()}, nil
-	}
-
-	return nil, errInvalidUserSection
-}
-
-func (h *Headscale) expandPorts(portsStr string) (*[]tailcfg.PortRange, error) {
-	if portsStr == "*" {
-		return &[]tailcfg.PortRange{
-			{First: portRangeBegin, Last: portRangeEnd},
-		}, nil
-	}
-
-	ports := []tailcfg.PortRange{}
-	for _, portStr := range strings.Split(portsStr, ",") {
-		rang := strings.Split(portStr, "-")
-		switch len(rang) {
-		case 1:
-			port, err := strconv.ParseUint(rang[0], Base10, BitSize16)
-			if err != nil {
-				return nil, err
-			}
-			ports = append(ports, tailcfg.PortRange{
-				First: uint16(port),
-				Last:  uint16(port),
-			})
-
-		case expectedTokenItems:
-			start, err := strconv.ParseUint(rang[0], Base10, BitSize16)
-			if err != nil {
-				return nil, err
-			}
-			last, err := strconv.ParseUint(rang[1], Base10, BitSize16)
-			if err != nil {
-				return nil, err
-			}
-			ports = append(ports, tailcfg.PortRange{
-				First: uint16(start),
-				Last:  uint16(last),
-			})
-
-		default:
-			return nil, errInvalidPortFormat
-		}
-	}
-
-	return &ports, nil
-}

acls_test.go

@@ -1,167 +0,0 @@
-package headscale
-
-import (
-	"gopkg.in/check.v1"
-)
-
-func (s *Suite) TestWrongPath(c *check.C) {
-	err := app.LoadACLPolicy("asdfg")
-	c.Assert(err, check.NotNil)
-}
-
-func (s *Suite) TestBrokenHuJson(c *check.C) {
-	err := app.LoadACLPolicy("./tests/acls/broken.hujson")
-	c.Assert(err, check.NotNil)
-}
-
-func (s *Suite) TestInvalidPolicyHuson(c *check.C) {
-	err := app.LoadACLPolicy("./tests/acls/invalid.hujson")
-	c.Assert(err, check.NotNil)
-	c.Assert(err, check.Equals, errEmptyPolicy)
-}
-
-func (s *Suite) TestParseHosts(c *check.C) {
-	var hosts Hosts
-	err := hosts.UnmarshalJSON(
-		[]byte(
-			`{"example-host-1": "100.100.100.100","example-host-2": "100.100.101.100/24"}`,
-		),
-	)
-	c.Assert(hosts, check.NotNil)
-	c.Assert(err, check.IsNil)
-}
-
-func (s *Suite) TestParseInvalidCIDR(c *check.C) {
-	var hosts Hosts
-	err := hosts.UnmarshalJSON([]byte(`{"example-host-1": "100.100.100.100/42"}`))
-	c.Assert(hosts, check.IsNil)
-	c.Assert(err, check.NotNil)
-}
-
-func (s *Suite) TestRuleInvalidGeneration(c *check.C) {
-	err := app.LoadACLPolicy("./tests/acls/acl_policy_invalid.hujson")
-	c.Assert(err, check.NotNil)
-}
-
-func (s *Suite) TestBasicRule(c *check.C) {
-	err := app.LoadACLPolicy("./tests/acls/acl_policy_basic_1.hujson")
-	c.Assert(err, check.IsNil)
-
-	rules, err := app.generateACLRules()
-	c.Assert(err, check.IsNil)
-	c.Assert(rules, check.NotNil)
-}
-
-func (s *Suite) TestPortRange(c *check.C) {
-	err := app.LoadACLPolicy("./tests/acls/acl_policy_basic_range.hujson")
-	c.Assert(err, check.IsNil)
-
-	rules, err := app.generateACLRules()
-	c.Assert(err, check.IsNil)
-	c.Assert(rules, check.NotNil)
-
-	c.Assert(rules, check.HasLen, 1)
-	c.Assert(rules[0].DstPorts, check.HasLen, 1)
-	c.Assert(rules[0].DstPorts[0].Ports.First, check.Equals, uint16(5400))
-	c.Assert(rules[0].DstPorts[0].Ports.Last, check.Equals, uint16(5500))
-}
-
-func (s *Suite) TestPortWildcard(c *check.C) {
-	err := app.LoadACLPolicy("./tests/acls/acl_policy_basic_wildcards.hujson")
-	c.Assert(err, check.IsNil)
-
-	rules, err := app.generateACLRules()
-	c.Assert(err, check.IsNil)
-	c.Assert(rules, check.NotNil)
-
-	c.Assert(rules, check.HasLen, 1)
-	c.Assert(rules[0].DstPorts, check.HasLen, 1)
-	c.Assert(rules[0].DstPorts[0].Ports.First, check.Equals, uint16(0))
-	c.Assert(rules[0].DstPorts[0].Ports.Last, check.Equals, uint16(65535))
-	c.Assert(rules[0].SrcIPs, check.HasLen, 1)
-	c.Assert(rules[0].SrcIPs[0], check.Equals, "*")
-}
-
-func (s *Suite) TestPortNamespace(c *check.C) {
-	namespace, err := app.CreateNamespace("testnamespace")
-	c.Assert(err, check.IsNil)
-
-	pak, err := app.CreatePreAuthKey(namespace.Name, false, false, nil)
-	c.Assert(err, check.IsNil)
-
-	_, err = app.GetMachine("testnamespace", "testmachine")
-	c.Assert(err, check.NotNil)
-	ips, _ := app.getAvailableIPs()
-	machine := Machine{
-		ID:             0,
-		MachineKey:     "foo",
-		NodeKey:        "bar",
-		DiscoKey:       "faa",
-		Name:           "testmachine",
-		NamespaceID:    namespace.ID,
-		Registered:     true,
-		RegisterMethod: RegisterMethodAuthKey,
-		IPAddresses:    ips,
-		AuthKeyID:      uint(pak.ID),
-	}
-	app.db.Save(&machine)
-
-	err = app.LoadACLPolicy(
-		"./tests/acls/acl_policy_basic_namespace_as_user.hujson",
-	)
-	c.Assert(err, check.IsNil)
-
-	rules, err := app.generateACLRules()
-	c.Assert(err, check.IsNil)
-	c.Assert(rules, check.NotNil)
-
-	c.Assert(rules, check.HasLen, 1)
-	c.Assert(rules[0].DstPorts, check.HasLen, 1)
-	c.Assert(rules[0].DstPorts[0].Ports.First, check.Equals, uint16(0))
-	c.Assert(rules[0].DstPorts[0].Ports.Last, check.Equals, uint16(65535))
-	c.Assert(rules[0].SrcIPs, check.HasLen, 1)
-	c.Assert(rules[0].SrcIPs[0], check.Not(check.Equals), "not an ip")
-	c.Assert(len(ips), check.Equals, 1)
-	c.Assert(rules[0].SrcIPs[0], check.Equals, ips[0].String())
-}
-
-func (s *Suite) TestPortGroup(c *check.C) {
-	namespace, err := app.CreateNamespace("testnamespace")
-	c.Assert(err, check.IsNil)
-
-	pak, err := app.CreatePreAuthKey(namespace.Name, false, false, nil)
-	c.Assert(err, check.IsNil)
-
-	_, err = app.GetMachine("testnamespace", "testmachine")
-	c.Assert(err, check.NotNil)
-	ips, _ := app.getAvailableIPs()
-	machine := Machine{
-		ID:             0,
-		MachineKey:     "foo",
-		NodeKey:        "bar",
-		DiscoKey:       "faa",
-		Name:           "testmachine",
-		NamespaceID:    namespace.ID,
-		Registered:     true,
-		RegisterMethod: RegisterMethodAuthKey,
-		IPAddresses:    ips,
-		AuthKeyID:      uint(pak.ID),
-	}
-	app.db.Save(&machine)
-
-	err = app.LoadACLPolicy("./tests/acls/acl_policy_basic_groups.hujson")
-	c.Assert(err, check.IsNil)
-
-	rules, err := app.generateACLRules()
-	c.Assert(err, check.IsNil)
-	c.Assert(rules, check.NotNil)
-
-	c.Assert(rules, check.HasLen, 1)
-	c.Assert(rules[0].DstPorts, check.HasLen, 1)
-	c.Assert(rules[0].DstPorts[0].Ports.First, check.Equals, uint16(0))
-	c.Assert(rules[0].DstPorts[0].Ports.Last, check.Equals, uint16(65535))
-	c.Assert(rules[0].SrcIPs, check.HasLen, 1)
-	c.Assert(rules[0].SrcIPs[0], check.Not(check.Equals), "not an ip")
-	c.Assert(len(ips), check.Equals, 1)
-	c.Assert(rules[0].SrcIPs[0], check.Equals, ips[0].String())
-}

acls_types.go

@@ -1,79 +0,0 @@
-package headscale
-
-import (
-	"encoding/json"
-	"strings"
-
-	"github.com/tailscale/hujson"
-	"inet.af/netaddr"
-)
-
-// ACLPolicy represents a Tailscale ACL Policy.
-type ACLPolicy struct {
-	Groups    Groups    `json:"Groups"`
-	Hosts     Hosts     `json:"Hosts"`
-	TagOwners TagOwners `json:"TagOwners"`
-	ACLs      []ACL     `json:"ACLs"`
-	Tests     []ACLTest `json:"Tests"`
-}
-
-// ACL is a basic rule for the ACL Policy.
-type ACL struct {
-	Action string   `json:"Action"`
-	Users  []string `json:"Users"`
-	Ports  []string `json:"Ports"`
-}
-
-// Groups references a series of alias in the ACL rules.
-type Groups map[string][]string
-
-// Hosts are alias for IP addresses or subnets.
-type Hosts map[string]netaddr.IPPrefix
-
-// TagOwners specify what users (namespaces?) are allow to use certain tags.
-type TagOwners map[string][]string
-
-// ACLTest is not implemented, but should be use to check if a certain rule is allowed.
-type ACLTest struct {
-	User  string   `json:"User"`
-	Allow []string `json:"Allow"`
-	Deny  []string `json:"Deny,omitempty"`
-}
-
-// UnmarshalJSON allows to parse the Hosts directly into netaddr objects.
-func (hosts *Hosts) UnmarshalJSON(data []byte) error {
-	newHosts := Hosts{}
-	hostIPPrefixMap := make(map[string]string)
-	ast, err := hujson.Parse(data)
-	if err != nil {
-		return err
-	}
-	ast.Standardize()
-	data = ast.Pack()
-	err = json.Unmarshal(data, &hostIPPrefixMap)
-	if err != nil {
-		return err
-	}
-	for host, prefixStr := range hostIPPrefixMap {
-		if !strings.Contains(prefixStr, "/") {
-			prefixStr += "/32"
-		}
-		prefix, err := netaddr.ParseIPPrefix(prefixStr)
-		if err != nil {
-			return err
-		}
-		newHosts[host] = prefix
-	}
-	*hosts = newHosts
-
-	return nil
-}
-
-// IsZero is perhaps a bit naive here.
-func (policy ACLPolicy) IsZero() bool {
-	if len(policy.Groups) == 0 && len(policy.Hosts) == 0 && len(policy.ACLs) == 0 {
-		return true
-	}
-
-	return false
-}

api.go

@@ -1,616 +0,0 @@
-package headscale
-
-import (
-	"bytes"
-	"encoding/binary"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"html/template"
-	"io"
-	"net/http"
-	"strings"
-	"time"
-
-	"github.com/gin-gonic/gin"
-	"github.com/klauspost/compress/zstd"
-	"github.com/rs/zerolog/log"
-	"gorm.io/gorm"
-	"tailscale.com/tailcfg"
-	"tailscale.com/types/key"
-)
-
-const (
-	reservedResponseHeaderSize               = 4
-	RegisterMethodAuthKey                    = "authKey"
-	RegisterMethodOIDC                       = "oidc"
-	RegisterMethodCLI                        = "cli"
-	ErrRegisterMethodCLIDoesNotSupportExpire = Error(
-		"machines registered with CLI does not support expire",
-	)
-)
-
-// KeyHandler provides the Headscale pub key
-// Listens in /key.
-func (h *Headscale) KeyHandler(ctx *gin.Context) {
-	ctx.Data(
-		http.StatusOK,
-		"text/plain; charset=utf-8",
-		[]byte(MachinePublicKeyStripPrefix(h.privateKey.Public())),
-	)
-}
-
-type registerWebAPITemplateConfig struct {
-	Key string
-}
-
-var registerWebAPITemplate = template.Must(
-	template.New("registerweb").Parse(`<html>
-	<body>
-	<h1>headscale</h1>
-	<p>
-		Run the command below in the headscale server to add this machine to your network:
-	</p>
-
-	<p>
-		<code>
-			<b>headscale -n NAMESPACE nodes register --key {{.Key}}</b>
-		</code>
-	</p>
-
-	</body>
-	</html>`),
-)
-
-// RegisterWebAPI shows a simple message in the browser to point to the CLI
-// Listens in /register.
-func (h *Headscale) RegisterWebAPI(ctx *gin.Context) {
-	machineKeyStr := ctx.Query("key")
-	if machineKeyStr == "" {
-		ctx.String(http.StatusBadRequest, "Wrong params")
-
-		return
-	}
-
-	var content bytes.Buffer
-	if err := registerWebAPITemplate.Execute(&content, registerWebAPITemplateConfig{
-		Key: machineKeyStr,
-	}); err != nil {
-		log.Error().
-			Str("func", "RegisterWebAPI").
-			Err(err).
-			Msg("Could not render register web API template")
-		ctx.Data(
-			http.StatusInternalServerError,
-			"text/html; charset=utf-8",
-			[]byte("Could not render register web API template"),
-		)
-	}
-
-	ctx.Data(http.StatusOK, "text/html; charset=utf-8", content.Bytes())
-}
-
-// RegistrationHandler handles the actual registration process of a machine
-// Endpoint /machine/:id.
-func (h *Headscale) RegistrationHandler(ctx *gin.Context) {
-	body, _ := io.ReadAll(ctx.Request.Body)
-	machineKeyStr := ctx.Param("id")
-
-	var machineKey key.MachinePublic
-	err := machineKey.UnmarshalText([]byte(MachinePublicKeyEnsurePrefix(machineKeyStr)))
-	if err != nil {
-		log.Error().
-			Caller().
-			Err(err).
-			Msg("Cannot parse machine key")
-		machineRegistrations.WithLabelValues("unknown", "web", "error", "unknown").Inc()
-		ctx.String(http.StatusInternalServerError, "Sad!")
-
-		return
-	}
-	req := tailcfg.RegisterRequest{}
-	err = decode(body, &req, &machineKey, h.privateKey)
-	if err != nil {
-		log.Error().
-			Caller().
-			Err(err).
-			Msg("Cannot decode message")
-		machineRegistrations.WithLabelValues("unknown", "web", "error", "unknown").Inc()
-		ctx.String(http.StatusInternalServerError, "Very sad!")
-
-		return
-	}
-
-	now := time.Now().UTC()
-	machine, err := h.GetMachineByMachineKey(machineKey)
-	if errors.Is(err, gorm.ErrRecordNotFound) {
-		log.Info().Str("machine", req.Hostinfo.Hostname).Msg("New machine")
-		newMachine := Machine{
-			Expiry:     &time.Time{},
-			MachineKey: MachinePublicKeyStripPrefix(machineKey),
-			Name:       req.Hostinfo.Hostname,
-		}
-		if err := h.db.Create(&newMachine).Error; err != nil {
-			log.Error().
-				Caller().
-				Err(err).
-				Msg("Could not create row")
-			machineRegistrations.WithLabelValues("unknown", "web", "error", machine.Namespace.Name).
-				Inc()
-
-			return
-		}
-		machine = &newMachine
-	}
-
-	if machine.Registered {
-		// If the NodeKey stored in headscale is the same as the key presented in a registration
-		// request, then we have a node that is either:
-		// - Trying to log out (sending a expiry in the past)
-		// - A valid, registered machine, looking for the node map
-		// - Expired machine wanting to reauthenticate
-		if machine.NodeKey == NodePublicKeyStripPrefix(req.NodeKey) {
-			// The client sends an Expiry in the past if the client is requesting to expire the key (aka logout)
-			//   https://github.com/tailscale/tailscale/blob/main/tailcfg/tailcfg.go#L648
-			if !req.Expiry.IsZero() && req.Expiry.UTC().Before(now) {
-				h.handleMachineLogOut(ctx, machineKey, *machine)
-
-				return
-			}
-
-			// If machine is not expired, and is register, we have a already accepted this machine,
-			// let it proceed with a valid registration
-			if !machine.isExpired() {
-				h.handleMachineValidRegistration(ctx, machineKey, *machine)
-
-				return
-			}
-		}
-
-		// The NodeKey we have matches OldNodeKey, which means this is a refresh after a key expiration
-		if machine.NodeKey == NodePublicKeyStripPrefix(req.OldNodeKey) &&
-			!machine.isExpired() {
-			h.handleMachineRefreshKey(ctx, machineKey, req, *machine)
-
-			return
-		}
-
-		// The machine has expired
-		h.handleMachineExpired(ctx, machineKey, req, *machine)
-
-		return
-	}
-
-	// If the machine has AuthKey set, handle registration via PreAuthKeys
-	if req.Auth.AuthKey != "" {
-		h.handleAuthKey(ctx, machineKey, req, *machine)
-
-		return
-	}
-
-	h.handleMachineRegistrationNew(ctx, machineKey, req, *machine)
-}
-
-func (h *Headscale) getMapResponse(
-	machineKey key.MachinePublic,
-	req tailcfg.MapRequest,
-	machine *Machine,
-) ([]byte, error) {
-	log.Trace().
-		Str("func", "getMapResponse").
-		Str("machine", req.Hostinfo.Hostname).
-		Msg("Creating Map response")
-	node, err := machine.toNode(h.cfg.BaseDomain, h.cfg.DNSConfig, true)
-	if err != nil {
-		log.Error().
-			Caller().
-			Str("func", "getMapResponse").
-			Err(err).
-			Msg("Cannot convert to node")
-
-		return nil, err
-	}
-
-	peers, err := h.getValidPeers(machine)
-	if err != nil {
-		log.Error().
-			Caller().
-			Str("func", "getMapResponse").
-			Err(err).
-			Msg("Cannot fetch peers")
-
-		return nil, err
-	}
-
-	profiles := getMapResponseUserProfiles(*machine, peers)
-
-	nodePeers, err := peers.toNodes(h.cfg.BaseDomain, h.cfg.DNSConfig, true)
-	if err != nil {
-		log.Error().
-			Caller().
-			Str("func", "getMapResponse").
-			Err(err).
-			Msg("Failed to convert peers to Tailscale nodes")
-
-		return nil, err
-	}
-
-	dnsConfig := getMapResponseDNSConfig(
-		h.cfg.DNSConfig,
-		h.cfg.BaseDomain,
-		*machine,
-		peers,
-	)
-
-	resp := tailcfg.MapResponse{
-		KeepAlive:    false,
-		Node:         node,
-		Peers:        nodePeers,
-		DNSConfig:    dnsConfig,
-		Domain:       h.cfg.BaseDomain,
-		PacketFilter: h.aclRules,
-		DERPMap:      h.DERPMap,
-		UserProfiles: profiles,
-	}
-
-	log.Trace().
-		Str("func", "getMapResponse").
-		Str("machine", req.Hostinfo.Hostname).
-		// Interface("payload", resp).
-		Msgf("Generated map response: %s", tailMapResponseToString(resp))
-
-	var respBody []byte
-	if req.Compress == "zstd" {
-		src, _ := json.Marshal(resp)
-
-		encoder, _ := zstd.NewWriter(nil)
-		srcCompressed := encoder.EncodeAll(src, nil)
-		respBody = h.privateKey.SealTo(machineKey, srcCompressed)
-	} else {
-		respBody, err = encode(resp, &machineKey, h.privateKey)
-		if err != nil {
-			return nil, err
-		}
-	}
-	// declare the incoming size on the first 4 bytes
-	data := make([]byte, reservedResponseHeaderSize)
-	binary.LittleEndian.PutUint32(data, uint32(len(respBody)))
-	data = append(data, respBody...)
-
-	return data, nil
-}
-
-func (h *Headscale) getMapKeepAliveResponse(
-	machineKey key.MachinePublic,
-	mapRequest tailcfg.MapRequest,
-) ([]byte, error) {
-	mapResponse := tailcfg.MapResponse{
-		KeepAlive: true,
-	}
-	var respBody []byte
-	var err error
-	if mapRequest.Compress == "zstd" {
-		src, _ := json.Marshal(mapResponse)
-		encoder, _ := zstd.NewWriter(nil)
-		srcCompressed := encoder.EncodeAll(src, nil)
-		respBody = h.privateKey.SealTo(machineKey, srcCompressed)
-	} else {
-		respBody, err = encode(mapResponse, &machineKey, h.privateKey)
-		if err != nil {
-			return nil, err
-		}
-	}
-	data := make([]byte, reservedResponseHeaderSize)
-	binary.LittleEndian.PutUint32(data, uint32(len(respBody)))
-	data = append(data, respBody...)
-
-	return data, nil
-}
-
-func (h *Headscale) handleMachineLogOut(
-	ctx *gin.Context,
-	machineKey key.MachinePublic,
-	machine Machine,
-) {
-	resp := tailcfg.RegisterResponse{}
-
-	log.Info().
-		Str("machine", machine.Name).
-		Msg("Client requested logout")
-
-	h.ExpireMachine(&machine)
-
-	resp.AuthURL = ""
-	resp.MachineAuthorized = false
-	resp.User = *machine.Namespace.toUser()
-	respBody, err := encode(resp, &machineKey, h.privateKey)
-	if err != nil {
-		log.Error().
-			Caller().
-			Err(err).
-			Msg("Cannot encode message")
-		ctx.String(http.StatusInternalServerError, "")
-
-		return
-	}
-	ctx.Data(http.StatusOK, "application/json; charset=utf-8", respBody)
-}
-
-func (h *Headscale) handleMachineValidRegistration(
-	ctx *gin.Context,
-	machineKey key.MachinePublic,
-	machine Machine,
-) {
-	resp := tailcfg.RegisterResponse{}
-
-	// The machine registration is valid, respond with redirect to /map
-	log.Debug().
-		Str("machine", machine.Name).
-		Msg("Client is registered and we have the current NodeKey. All clear to /map")
-
-	resp.AuthURL = ""
-	resp.MachineAuthorized = true
-	resp.User = *machine.Namespace.toUser()
-	resp.Login = *machine.Namespace.toLogin()
-
-	respBody, err := encode(resp, &machineKey, h.privateKey)
-	if err != nil {
-		log.Error().
-			Caller().
-			Err(err).
-			Msg("Cannot encode message")
-		machineRegistrations.WithLabelValues("update", "web", "error", machine.Namespace.Name).
-			Inc()
-		ctx.String(http.StatusInternalServerError, "")
-
-		return
-	}
-	machineRegistrations.WithLabelValues("update", "web", "success", machine.Namespace.Name).
-		Inc()
-	ctx.Data(http.StatusOK, "application/json; charset=utf-8", respBody)
-}
-
-func (h *Headscale) handleMachineExpired(
-	ctx *gin.Context,
-	machineKey key.MachinePublic,
-	registerRequest tailcfg.RegisterRequest,
-	machine Machine,
-) {
-	resp := tailcfg.RegisterResponse{}
-
-	// The client has registered before, but has expired
-	log.Debug().
-		Str("machine", machine.Name).
-		Msg("Machine registration has expired. Sending a authurl to register")
-
-	if registerRequest.Auth.AuthKey != "" {
-		h.handleAuthKey(ctx, machineKey, registerRequest, machine)
-
-		return
-	}
-
-	if h.cfg.OIDC.Issuer != "" {
-		resp.AuthURL = fmt.Sprintf("%s/oidc/register/%s",
-			strings.TrimSuffix(h.cfg.ServerURL, "/"), machineKey.String())
-	} else {
-		resp.AuthURL = fmt.Sprintf("%s/register?key=%s",
-			strings.TrimSuffix(h.cfg.ServerURL, "/"), machineKey.String())
-	}
-
-	respBody, err := encode(resp, &machineKey, h.privateKey)
-	if err != nil {
-		log.Error().
-			Caller().
-			Err(err).
-			Msg("Cannot encode message")
-		machineRegistrations.WithLabelValues("reauth", "web", "error", machine.Namespace.Name).
-			Inc()
-		ctx.String(http.StatusInternalServerError, "")
-
-		return
-	}
-	machineRegistrations.WithLabelValues("reauth", "web", "success", machine.Namespace.Name).
-		Inc()
-	ctx.Data(http.StatusOK, "application/json; charset=utf-8", respBody)
-}
-
-func (h *Headscale) handleMachineRefreshKey(
-	ctx *gin.Context,
-	machineKey key.MachinePublic,
-	registerRequest tailcfg.RegisterRequest,
-	machine Machine,
-) {
-	resp := tailcfg.RegisterResponse{}
-
-	log.Debug().
-		Str("machine", machine.Name).
-		Msg("We have the OldNodeKey in the database. This is a key refresh")
-	machine.NodeKey = NodePublicKeyStripPrefix(registerRequest.NodeKey)
-	h.db.Save(&machine)
-
-	resp.AuthURL = ""
-	resp.User = *machine.Namespace.toUser()
-	respBody, err := encode(resp, &machineKey, h.privateKey)
-	if err != nil {
-		log.Error().
-			Caller().
-			Err(err).
-			Msg("Cannot encode message")
-		ctx.String(http.StatusInternalServerError, "Extremely sad!")
-
-		return
-	}
-	ctx.Data(http.StatusOK, "application/json; charset=utf-8", respBody)
-}
-
-func (h *Headscale) handleMachineRegistrationNew(
-	ctx *gin.Context,
-	machineKey key.MachinePublic,
-	registerRequest tailcfg.RegisterRequest,
-	machine Machine,
-) {
-	resp := tailcfg.RegisterResponse{}
-
-	// The machine registration is new, redirect the client to the registration URL
-	log.Debug().
-		Str("machine", machine.Name).
-		Msg("The node is sending us a new NodeKey, sending auth url")
-	if h.cfg.OIDC.Issuer != "" {
-		resp.AuthURL = fmt.Sprintf(
-			"%s/oidc/register/%s",
-			strings.TrimSuffix(h.cfg.ServerURL, "/"),
-			machineKey.String(),
-		)
-	} else {
-		resp.AuthURL = fmt.Sprintf("%s/register?key=%s",
-			strings.TrimSuffix(h.cfg.ServerURL, "/"), MachinePublicKeyStripPrefix(machineKey))
-	}
-
-	if !registerRequest.Expiry.IsZero() {
-		log.Trace().
-			Caller().
-			Str("machine", machine.Name).
-			Time("expiry", registerRequest.Expiry).
-			Msg("Non-zero expiry time requested, adding to cache")
-		h.requestedExpiryCache.Set(
-			machineKey.String(),
-			registerRequest.Expiry,
-			requestedExpiryCacheExpiration,
-		)
-	}
-
-	machine.NodeKey = NodePublicKeyStripPrefix(registerRequest.NodeKey)
-
-	// save the NodeKey
-	h.db.Save(&machine)
-
-	respBody, err := encode(resp, &machineKey, h.privateKey)
-	if err != nil {
-		log.Error().
-			Caller().
-			Err(err).
-			Msg("Cannot encode message")
-		ctx.String(http.StatusInternalServerError, "")
-
-		return
-	}
-	ctx.Data(http.StatusOK, "application/json; charset=utf-8", respBody)
-}
-
-// TODO: check if any locks are needed around IP allocation.
-func (h *Headscale) handleAuthKey(
-	ctx *gin.Context,
-	machineKey key.MachinePublic,
-	registerRequest tailcfg.RegisterRequest,
-	machine Machine,
-) {
-	log.Debug().
-		Str("func", "handleAuthKey").
-		Str("machine", registerRequest.Hostinfo.Hostname).
-		Msgf("Processing auth key for %s", registerRequest.Hostinfo.Hostname)
-	resp := tailcfg.RegisterResponse{}
-	pak, err := h.checkKeyValidity(registerRequest.Auth.AuthKey)
-	if err != nil {
-		log.Error().
-			Caller().
-			Str("func", "handleAuthKey").
-			Str("machine", machine.Name).
-			Err(err).
-			Msg("Failed authentication via AuthKey")
-		resp.MachineAuthorized = false
-		respBody, err := encode(resp, &machineKey, h.privateKey)
-		if err != nil {
-			log.Error().
-				Caller().
-				Str("func", "handleAuthKey").
-				Str("machine", machine.Name).
-				Err(err).
-				Msg("Cannot encode message")
-			ctx.String(http.StatusInternalServerError, "")
-			machineRegistrations.WithLabelValues("new", "authkey", "error", machine.Namespace.Name).
-				Inc()
-
-			return
-		}
-		ctx.Data(http.StatusUnauthorized, "application/json; charset=utf-8", respBody)
-		log.Error().
-			Caller().
-			Str("func", "handleAuthKey").
-			Str("machine", machine.Name).
-			Msg("Failed authentication via AuthKey")
-		machineRegistrations.WithLabelValues("new", "authkey", "error", machine.Namespace.Name).
-			Inc()
-
-		return
-	}
-
-	if machine.isRegistered() {
-		log.Trace().
-			Caller().
-			Str("machine", machine.Name).
-			Msg("machine already registered, reauthenticating")
-
-		h.RefreshMachine(&machine, registerRequest.Expiry)
-	} else {
-		log.Debug().
-			Str("func", "handleAuthKey").
-			Str("machine", machine.Name).
-			Msg("Authentication key was valid, proceeding to acquire IP addresses")
-		ips, err := h.getAvailableIPs()
-		if err != nil {
-			log.Error().
-				Caller().
-				Str("func", "handleAuthKey").
-				Str("machine", machine.Name).
-				Msg("Failed to find an available IP address")
-			machineRegistrations.WithLabelValues("new", "authkey", "error", machine.Namespace.Name).
-				Inc()
-
-			return
-		}
-		log.Info().
-			Str("func", "handleAuthKey").
-			Str("machine", machine.Name).
-			Str("ips", strings.Join(ips.ToStringSlice(), ",")).
-			Msgf("Assigning %s to %s", strings.Join(ips.ToStringSlice(), ","), machine.Name)
-
-		machine.Expiry = &registerRequest.Expiry
-		machine.AuthKeyID = uint(pak.ID)
-		machine.IPAddresses = ips
-		machine.NamespaceID = pak.NamespaceID
-
-		machine.NodeKey = NodePublicKeyStripPrefix(registerRequest.NodeKey)
-		// we update it just in case
-		machine.Registered = true
-		machine.RegisterMethod = RegisterMethodAuthKey
-		h.db.Save(&machine)
-	}
-
-	pak.Used = true
-	h.db.Save(&pak)
-
-	resp.MachineAuthorized = true
-	resp.User = *pak.Namespace.toUser()
-	respBody, err := encode(resp, &machineKey, h.privateKey)
-	if err != nil {
-		log.Error().
-			Caller().
-			Str("func", "handleAuthKey").
-			Str("machine", machine.Name).
-			Err(err).
-			Msg("Cannot encode message")
-		machineRegistrations.WithLabelValues("new", "authkey", "error", machine.Namespace.Name).
-			Inc()
-		ctx.String(http.StatusInternalServerError, "Extremely sad!")
-
-		return
-	}
-	machineRegistrations.WithLabelValues("new", "authkey", "success", machine.Namespace.Name).
-		Inc()
-	ctx.Data(http.StatusOK, "application/json; charset=utf-8", respBody)
-	log.Info().
-		Str("func", "handleAuthKey").
-		Str("machine", machine.Name).
-		Str("ips", strings.Join(machine.IPAddresses.ToStringSlice(), ", ")).
-		Msg("Successfully authenticated via AuthKey")
-}

api_key.go

@@ -1,164 +0,0 @@
-package headscale
-
-import (
-	"fmt"
-	"strings"
-	"time"
-
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
-	"golang.org/x/crypto/bcrypt"
-	"google.golang.org/protobuf/types/known/timestamppb"
-)
-
-const (
-	apiPrefixLength = 7
-	apiKeyLength    = 32
-	apiKeyParts     = 2
-
-	errAPIKeyFailedToParse = Error("Failed to parse ApiKey")
-)
-
-// APIKey describes the datamodel for API keys used to remotely authenticate with
-// headscale.
-type APIKey struct {
-	ID     uint64 `gorm:"primary_key"`
-	Prefix string `gorm:"uniqueIndex"`
-	Hash   []byte
-
-	CreatedAt  *time.Time
-	Expiration *time.Time
-	LastSeen   *time.Time
-}
-
-// CreateAPIKey creates a new ApiKey in a namespace, and returns it.
-func (h *Headscale) CreateAPIKey(
-	expiration *time.Time,
-) (string, *APIKey, error) {
-	prefix, err := GenerateRandomStringURLSafe(apiPrefixLength)
-	if err != nil {
-		return "", nil, err
-	}
-
-	toBeHashed, err := GenerateRandomStringURLSafe(apiKeyLength)
-	if err != nil {
-		return "", nil, err
-	}
-
-	// Key to return to user, this will only be visible _once_
-	keyStr := prefix + "." + toBeHashed
-
-	hash, err := bcrypt.GenerateFromPassword([]byte(toBeHashed), bcrypt.DefaultCost)
-	if err != nil {
-		return "", nil, err
-	}
-
-	key := APIKey{
-		Prefix:     prefix,
-		Hash:       hash,
-		Expiration: expiration,
-	}
-	h.db.Save(&key)
-
-	return keyStr, &key, nil
-}
-
-// ListAPIKeys returns the list of ApiKeys for a namespace.
-func (h *Headscale) ListAPIKeys() ([]APIKey, error) {
-	keys := []APIKey{}
-	if err := h.db.Find(&keys).Error; err != nil {
-		return nil, err
-	}
-
-	return keys, nil
-}
-
-// GetAPIKey returns a ApiKey for a given key.
-func (h *Headscale) GetAPIKey(prefix string) (*APIKey, error) {
-	key := APIKey{}
-	if result := h.db.First(&key, "prefix = ?", prefix); result.Error != nil {
-		return nil, result.Error
-	}
-
-	return &key, nil
-}
-
-// GetAPIKeyByID returns a ApiKey for a given id.
-func (h *Headscale) GetAPIKeyByID(id uint64) (*APIKey, error) {
-	key := APIKey{}
-	if result := h.db.Find(&APIKey{ID: id}).First(&key); result.Error != nil {
-		return nil, result.Error
-	}
-
-	return &key, nil
-}
-
-// DestroyAPIKey destroys a ApiKey. Returns error if the ApiKey
-// does not exist.
-func (h *Headscale) DestroyAPIKey(key APIKey) error {
-	if result := h.db.Unscoped().Delete(key); result.Error != nil {
-		return result.Error
-	}
-
-	return nil
-}
-
-// ExpireAPIKey marks a ApiKey as expired.
-func (h *Headscale) ExpireAPIKey(key *APIKey) error {
-	if err := h.db.Model(&key).Update("Expiration", time.Now()).Error; err != nil {
-		return err
-	}
-
-	return nil
-}
-
-func (h *Headscale) ValidateAPIKey(keyStr string) (bool, error) {
-	prefix, hash, err := splitAPIKey(keyStr)
-	if err != nil {
-		return false, fmt.Errorf("failed to validate api key: %w", err)
-	}
-
-	key, err := h.GetAPIKey(prefix)
-	if err != nil {
-		return false, fmt.Errorf("failed to validate api key: %w", err)
-	}
-
-	if key.Expiration.Before(time.Now()) {
-		return false, nil
-	}
-
-	if err := bcrypt.CompareHashAndPassword(key.Hash, []byte(hash)); err != nil {
-		return false, err
-	}
-
-	return true, nil
-}
-
-func splitAPIKey(key string) (string, string, error) {
-	parts := strings.Split(key, ".")
-	if len(parts) != apiKeyParts {
-		return "", "", errAPIKeyFailedToParse
-	}
-
-	return parts[0], parts[1], nil
-}
-
-func (key *APIKey) toProto() *v1.ApiKey {
-	protoKey := v1.ApiKey{
-		Id:     key.ID,
-		Prefix: key.Prefix,
-	}
-
-	if key.Expiration != nil {
-		protoKey.Expiration = timestamppb.New(*key.Expiration)
-	}
-
-	if key.CreatedAt != nil {
-		protoKey.CreatedAt = timestamppb.New(*key.CreatedAt)
-	}
-
-	if key.LastSeen != nil {
-		protoKey.LastSeen = timestamppb.New(*key.LastSeen)
-	}
-
-	return &protoKey
-}

api_key_test.go

@@ -1,89 +0,0 @@
-package headscale
-
-import (
-	"time"
-
-	"gopkg.in/check.v1"
-)
-
-func (*Suite) TestCreateAPIKey(c *check.C) {
-	apiKeyStr, apiKey, err := app.CreateAPIKey(nil)
-	c.Assert(err, check.IsNil)
-	c.Assert(apiKey, check.NotNil)
-
-	// Did we get a valid key?
-	c.Assert(apiKey.Prefix, check.NotNil)
-	c.Assert(apiKey.Hash, check.NotNil)
-	c.Assert(apiKeyStr, check.Not(check.Equals), "")
-
-	_, err = app.ListAPIKeys()
-	c.Assert(err, check.IsNil)
-
-	keys, err := app.ListAPIKeys()
-	c.Assert(err, check.IsNil)
-	c.Assert(len(keys), check.Equals, 1)
-}
-
-func (*Suite) TestAPIKeyDoesNotExist(c *check.C) {
-	key, err := app.GetAPIKey("does-not-exist")
-	c.Assert(err, check.NotNil)
-	c.Assert(key, check.IsNil)
-}
-
-func (*Suite) TestValidateAPIKeyOk(c *check.C) {
-	nowPlus2 := time.Now().Add(2 * time.Hour)
-	apiKeyStr, apiKey, err := app.CreateAPIKey(&nowPlus2)
-	c.Assert(err, check.IsNil)
-	c.Assert(apiKey, check.NotNil)
-
-	valid, err := app.ValidateAPIKey(apiKeyStr)
-	c.Assert(err, check.IsNil)
-	c.Assert(valid, check.Equals, true)
-}
-
-func (*Suite) TestValidateAPIKeyNotOk(c *check.C) {
-	nowMinus2 := time.Now().Add(time.Duration(-2) * time.Hour)
-	apiKeyStr, apiKey, err := app.CreateAPIKey(&nowMinus2)
-	c.Assert(err, check.IsNil)
-	c.Assert(apiKey, check.NotNil)
-
-	valid, err := app.ValidateAPIKey(apiKeyStr)
-	c.Assert(err, check.IsNil)
-	c.Assert(valid, check.Equals, false)
-
-	now := time.Now()
-	apiKeyStrNow, apiKey, err := app.CreateAPIKey(&now)
-	c.Assert(err, check.IsNil)
-	c.Assert(apiKey, check.NotNil)
-
-	validNow, err := app.ValidateAPIKey(apiKeyStrNow)
-	c.Assert(err, check.IsNil)
-	c.Assert(validNow, check.Equals, false)
-
-	validSilly, err := app.ValidateAPIKey("nota.validkey")
-	c.Assert(err, check.NotNil)
-	c.Assert(validSilly, check.Equals, false)
-
-	validWithErr, err := app.ValidateAPIKey("produceerrorkey")
-	c.Assert(err, check.NotNil)
-	c.Assert(validWithErr, check.Equals, false)
-}
-
-func (*Suite) TestExpireAPIKey(c *check.C) {
-	nowPlus2 := time.Now().Add(2 * time.Hour)
-	apiKeyStr, apiKey, err := app.CreateAPIKey(&nowPlus2)
-	c.Assert(err, check.IsNil)
-	c.Assert(apiKey, check.NotNil)
-
-	valid, err := app.ValidateAPIKey(apiKeyStr)
-	c.Assert(err, check.IsNil)
-	c.Assert(valid, check.Equals, true)
-
-	err = app.ExpireAPIKey(apiKey)
-	c.Assert(err, check.IsNil)
-	c.Assert(apiKey.Expiration, check.NotNil)
-
-	notValid, err := app.ValidateAPIKey(apiKeyStr)
-	c.Assert(err, check.IsNil)
-	c.Assert(notValid, check.Equals, false)
-}

app.go

@@ -1,774 +0,0 @@
-package headscale
-
-import (
-	"context"
-	"crypto/tls"
-	"errors"
-	"fmt"
-	"io"
-	"io/fs"
-	"net"
-	"net/http"
-	"net/url"
-	"os"
-	"os/signal"
-	"sort"
-	"strings"
-	"sync"
-	"syscall"
-	"time"
-
-	"github.com/coreos/go-oidc/v3/oidc"
-	"github.com/gin-gonic/gin"
-	grpc_middleware "github.com/grpc-ecosystem/go-grpc-middleware"
-	"github.com/grpc-ecosystem/grpc-gateway/v2/runtime"
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
-	"github.com/patrickmn/go-cache"
-	zerolog "github.com/philip-bui/grpc-zerolog"
-	zl "github.com/rs/zerolog"
-	"github.com/rs/zerolog/log"
-	ginprometheus "github.com/zsais/go-gin-prometheus"
-	"golang.org/x/crypto/acme"
-	"golang.org/x/crypto/acme/autocert"
-	"golang.org/x/oauth2"
-	"golang.org/x/sync/errgroup"
-	"google.golang.org/grpc"
-	"google.golang.org/grpc/codes"
-	"google.golang.org/grpc/credentials"
-	"google.golang.org/grpc/credentials/insecure"
-	"google.golang.org/grpc/metadata"
-	"google.golang.org/grpc/peer"
-	"google.golang.org/grpc/reflection"
-	"google.golang.org/grpc/status"
-	"gorm.io/gorm"
-	"inet.af/netaddr"
-	"tailscale.com/tailcfg"
-	"tailscale.com/types/dnstype"
-	"tailscale.com/types/key"
-)
-
-const (
-	AuthPrefix         = "Bearer "
-	Postgres           = "postgres"
-	Sqlite             = "sqlite3"
-	updateInterval     = 5000
-	HTTPReadTimeout    = 30 * time.Second
-	privateKeyFileMode = 0o600
-
-	requestedExpiryCacheExpiration      = time.Minute * 5
-	requestedExpiryCacheCleanupInterval = time.Minute * 10
-
-	errUnsupportedDatabase                 = Error("unsupported DB")
-	errUnsupportedLetsEncryptChallengeType = Error(
-		"unknown value for Lets Encrypt challenge type",
-	)
-)
-
-// Config contains the initial Headscale configuration.
-type Config struct {
-	ServerURL                      string
-	Addr                           string
-	GRPCAddr                       string
-	GRPCAllowInsecure              bool
-	EphemeralNodeInactivityTimeout time.Duration
-	IPPrefixes                     []netaddr.IPPrefix
-	PrivateKeyPath                 string
-	BaseDomain                     string
-
-	DERP DERPConfig
-
-	DBtype string
-	DBpath string
-	DBhost string
-	DBport int
-	DBname string
-	DBuser string
-	DBpass string
-
-	TLSLetsEncryptListen        string
-	TLSLetsEncryptHostname      string
-	TLSLetsEncryptCacheDir      string
-	TLSLetsEncryptChallengeType string
-
-	TLSCertPath string
-	TLSKeyPath  string
-
-	ACMEURL   string
-	ACMEEmail string
-
-	DNSConfig *tailcfg.DNSConfig
-
-	UnixSocket           string
-	UnixSocketPermission fs.FileMode
-
-	OIDC OIDCConfig
-
-	CLI CLIConfig
-}
-
-type OIDCConfig struct {
-	Issuer       string
-	ClientID     string
-	ClientSecret string
-	MatchMap     map[string]string
-}
-
-type DERPConfig struct {
-	URLs            []url.URL
-	Paths           []string
-	AutoUpdate      bool
-	UpdateFrequency time.Duration
-}
-
-type CLIConfig struct {
-	Address  string
-	APIKey   string
-	Timeout  time.Duration
-	Insecure bool
-}
-
-// Headscale represents the base app of the service.
-type Headscale struct {
-	cfg        Config
-	db         *gorm.DB
-	dbString   string
-	dbType     string
-	dbDebug    bool
-	privateKey *key.MachinePrivate
-
-	DERPMap *tailcfg.DERPMap
-
-	aclPolicy *ACLPolicy
-	aclRules  []tailcfg.FilterRule
-
-	lastStateChange sync.Map
-
-	oidcProvider   *oidc.Provider
-	oauth2Config   *oauth2.Config
-	oidcStateCache *cache.Cache
-
-	requestedExpiryCache *cache.Cache
-}
-
-// NewHeadscale returns the Headscale app.
-func NewHeadscale(cfg Config) (*Headscale, error) {
-	privKey, err := readOrCreatePrivateKey(cfg.PrivateKeyPath)
-	if err != nil {
-		return nil, fmt.Errorf("failed to read or create private key: %w", err)
-	}
-
-	var dbString string
-	switch cfg.DBtype {
-	case Postgres:
-		dbString = fmt.Sprintf(
-			"host=%s port=%d dbname=%s user=%s password=%s sslmode=disable",
-			cfg.DBhost,
-			cfg.DBport,
-			cfg.DBname,
-			cfg.DBuser,
-			cfg.DBpass,
-		)
-	case Sqlite:
-		dbString = cfg.DBpath
-	default:
-		return nil, errUnsupportedDatabase
-	}
-
-	requestedExpiryCache := cache.New(
-		requestedExpiryCacheExpiration,
-		requestedExpiryCacheCleanupInterval,
-	)
-
-	app := Headscale{
-		cfg:                  cfg,
-		dbType:               cfg.DBtype,
-		dbString:             dbString,
-		privateKey:           privKey,
-		aclRules:             tailcfg.FilterAllowAll, // default allowall
-		requestedExpiryCache: requestedExpiryCache,
-	}
-
-	err = app.initDB()
-	if err != nil {
-		return nil, err
-	}
-
-	if cfg.OIDC.Issuer != "" {
-		err = app.initOIDC()
-		if err != nil {
-			return nil, err
-		}
-	}
-
-	if app.cfg.DNSConfig != nil && app.cfg.DNSConfig.Proxied { // if MagicDNS
-		magicDNSDomains := generateMagicDNSRootDomains(app.cfg.IPPrefixes)
-		// we might have routes already from Split DNS
-		if app.cfg.DNSConfig.Routes == nil {
-			app.cfg.DNSConfig.Routes = make(map[string][]dnstype.Resolver)
-		}
-		for _, d := range magicDNSDomains {
-			app.cfg.DNSConfig.Routes[d.WithoutTrailingDot()] = nil
-		}
-	}
-
-	return &app, nil
-}
-
-// Redirect to our TLS url.
-func (h *Headscale) redirect(w http.ResponseWriter, req *http.Request) {
-	target := h.cfg.ServerURL + req.URL.RequestURI()
-	http.Redirect(w, req, target, http.StatusFound)
-}
-
-// expireEphemeralNodes deletes ephemeral machine records that have not been
-// seen for longer than h.cfg.EphemeralNodeInactivityTimeout.
-func (h *Headscale) expireEphemeralNodes(milliSeconds int64) {
-	ticker := time.NewTicker(time.Duration(milliSeconds) * time.Millisecond)
-	for range ticker.C {
-		h.expireEphemeralNodesWorker()
-	}
-}
-
-func (h *Headscale) expireEphemeralNodesWorker() {
-	namespaces, err := h.ListNamespaces()
-	if err != nil {
-		log.Error().Err(err).Msg("Error listing namespaces")
-
-		return
-	}
-
-	for _, namespace := range namespaces {
-		machines, err := h.ListMachinesInNamespace(namespace.Name)
-		if err != nil {
-			log.Error().
-				Err(err).
-				Str("namespace", namespace.Name).
-				Msg("Error listing machines in namespace")
-
-			return
-		}
-
-		for _, machine := range machines {
-			if machine.AuthKey != nil && machine.LastSeen != nil &&
-				machine.AuthKey.Ephemeral &&
-				time.Now().
-					After(machine.LastSeen.Add(h.cfg.EphemeralNodeInactivityTimeout)) {
-				log.Info().
-					Str("machine", machine.Name).
-					Msg("Ephemeral client removed from database")
-
-				err = h.db.Unscoped().Delete(machine).Error
-				if err != nil {
-					log.Error().
-						Err(err).
-						Str("machine", machine.Name).
-						Msg("🤮 Cannot delete ephemeral machine from the database")
-				}
-			}
-		}
-
-		h.setLastStateChangeToNow(namespace.Name)
-	}
-}
-
-func (h *Headscale) grpcAuthenticationInterceptor(ctx context.Context,
-	req interface{},
-	info *grpc.UnaryServerInfo,
-	handler grpc.UnaryHandler) (interface{}, error) {
-	// Check if the request is coming from the on-server client.
-	// This is not secure, but it is to maintain maintainability
-	// with the "legacy" database-based client
-	// It is also neede for grpc-gateway to be able to connect to
-	// the server
-	client, _ := peer.FromContext(ctx)
-
-	log.Trace().
-		Caller().
-		Str("client_address", client.Addr.String()).
-		Msg("Client is trying to authenticate")
-
-	meta, ok := metadata.FromIncomingContext(ctx)
-	if !ok {
-		log.Error().
-			Caller().
-			Str("client_address", client.Addr.String()).
-			Msg("Retrieving metadata is failed")
-
-		return ctx, status.Errorf(
-			codes.InvalidArgument,
-			"Retrieving metadata is failed",
-		)
-	}
-
-	authHeader, ok := meta["authorization"]
-	if !ok {
-		log.Error().
-			Caller().
-			Str("client_address", client.Addr.String()).
-			Msg("Authorization token is not supplied")
-
-		return ctx, status.Errorf(
-			codes.Unauthenticated,
-			"Authorization token is not supplied",
-		)
-	}
-
-	token := authHeader[0]
-
-	if !strings.HasPrefix(token, AuthPrefix) {
-		log.Error().
-			Caller().
-			Str("client_address", client.Addr.String()).
-			Msg(`missing "Bearer " prefix in "Authorization" header`)
-
-		return ctx, status.Error(
-			codes.Unauthenticated,
-			`missing "Bearer " prefix in "Authorization" header`,
-		)
-	}
-
-	valid, err := h.ValidateAPIKey(strings.TrimPrefix(token, AuthPrefix))
-	if err != nil {
-		log.Error().
-			Caller().
-			Err(err).
-			Str("client_address", client.Addr.String()).
-			Msg("failed to validate token")
-
-		return ctx, status.Error(codes.Internal, "failed to validate token")
-	}
-
-	if !valid {
-		log.Info().
-			Str("client_address", client.Addr.String()).
-			Msg("invalid token")
-
-		return ctx, status.Error(codes.Unauthenticated, "invalid token")
-	}
-
-	return handler(ctx, req)
-}
-
-func (h *Headscale) httpAuthenticationMiddleware(ctx *gin.Context) {
-	log.Trace().
-		Caller().
-		Str("client_address", ctx.ClientIP()).
-		Msg("HTTP authentication invoked")
-
-	authHeader := ctx.GetHeader("authorization")
-
-	if !strings.HasPrefix(authHeader, AuthPrefix) {
-		log.Error().
-			Caller().
-			Str("client_address", ctx.ClientIP()).
-			Msg(`missing "Bearer " prefix in "Authorization" header`)
-		ctx.AbortWithStatus(http.StatusUnauthorized)
-
-		return
-	}
-
-	ctx.AbortWithStatus(http.StatusUnauthorized)
-
-	valid, err := h.ValidateAPIKey(strings.TrimPrefix(authHeader, AuthPrefix))
-	if err != nil {
-		log.Error().
-			Caller().
-			Err(err).
-			Str("client_address", ctx.ClientIP()).
-			Msg("failed to validate token")
-
-		ctx.AbortWithStatus(http.StatusInternalServerError)
-
-		return
-	}
-
-	if !valid {
-		log.Info().
-			Str("client_address", ctx.ClientIP()).
-			Msg("invalid token")
-
-		ctx.AbortWithStatus(http.StatusUnauthorized)
-
-		return
-	}
-
-	ctx.Next()
-}
-
-// ensureUnixSocketIsAbsent will check if the given path for headscales unix socket is clear
-// and will remove it if it is not.
-func (h *Headscale) ensureUnixSocketIsAbsent() error {
-	// File does not exist, all fine
-	if _, err := os.Stat(h.cfg.UnixSocket); errors.Is(err, os.ErrNotExist) {
-		return nil
-	}
-
-	return os.Remove(h.cfg.UnixSocket)
-}
-
-func (h *Headscale) createRouter(grpcMux *runtime.ServeMux) *gin.Engine {
-	router := gin.Default()
-
-	prometheus := ginprometheus.NewPrometheus("gin")
-	prometheus.Use(router)
-
-	router.GET(
-		"/health",
-		func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{"healthy": "ok"}) },
-	)
-	router.GET("/key", h.KeyHandler)
-	router.GET("/register", h.RegisterWebAPI)
-	router.POST("/machine/:id/map", h.PollNetMapHandler)
-	router.POST("/machine/:id", h.RegistrationHandler)
-	router.GET("/oidc/register/:mkey", h.RegisterOIDC)
-	router.GET("/oidc/callback", h.OIDCCallback)
-	router.GET("/apple", h.AppleMobileConfig)
-	router.GET("/apple/:platform", h.ApplePlatformConfig)
-	router.GET("/swagger", SwaggerUI)
-	router.GET("/swagger/v1/openapiv2.json", SwaggerAPIv1)
-
-	api := router.Group("/api")
-	api.Use(h.httpAuthenticationMiddleware)
-	{
-		api.Any("/v1/*any", gin.WrapF(grpcMux.ServeHTTP))
-	}
-
-	router.NoRoute(stdoutHandler)
-
-	return router
-}
-
-// Serve launches a GIN server with the Headscale API.
-func (h *Headscale) Serve() error {
-	var err error
-
-	// Fetch an initial DERP Map before we start serving
-	h.DERPMap = GetDERPMap(h.cfg.DERP)
-
-	if h.cfg.DERP.AutoUpdate {
-		derpMapCancelChannel := make(chan struct{})
-		defer func() { derpMapCancelChannel <- struct{}{} }()
-		go h.scheduledDERPMapUpdateWorker(derpMapCancelChannel)
-	}
-
-	go h.expireEphemeralNodes(updateInterval)
-
-	if zl.GlobalLevel() == zl.TraceLevel {
-		zerolog.RespLog = true
-	} else {
-		zerolog.RespLog = false
-	}
-
-	// Prepare group for running listeners
-	errorGroup := new(errgroup.Group)
-
-	ctx := context.Background()
-	ctx, cancel := context.WithCancel(ctx)
-	defer cancel()
-
-	//
-	//
-	// Set up LOCAL listeners
-	//
-
-	err = h.ensureUnixSocketIsAbsent()
-	if err != nil {
-		return fmt.Errorf("unable to remove old socket file: %w", err)
-	}
-
-	socketListener, err := net.Listen("unix", h.cfg.UnixSocket)
-	if err != nil {
-		return fmt.Errorf("failed to set up gRPC socket: %w", err)
-	}
-
-	// Change socket permissions
-	if err := os.Chmod(h.cfg.UnixSocket, h.cfg.UnixSocketPermission); err != nil {
-		return fmt.Errorf("failed change permission of gRPC socket: %w", err)
-	}
-
-	// Handle common process-killing signals so we can gracefully shut down:
-	sigc := make(chan os.Signal, 1)
-	signal.Notify(sigc, os.Interrupt, syscall.SIGTERM)
-	go func(c chan os.Signal) {
-		// Wait for a SIGINT or SIGKILL:
-		sig := <-c
-		log.Printf("Caught signal %s: shutting down.", sig)
-		// Stop listening (and unlink the socket if unix type):
-		socketListener.Close()
-		// And we're done:
-		os.Exit(0)
-	}(sigc)
-
-	grpcGatewayMux := runtime.NewServeMux()
-
-	// Make the grpc-gateway connect to grpc over socket
-	grpcGatewayConn, err := grpc.Dial(
-		h.cfg.UnixSocket,
-		[]grpc.DialOption{
-			grpc.WithTransportCredentials(insecure.NewCredentials()),
-			grpc.WithContextDialer(GrpcSocketDialer),
-		}...,
-	)
-	if err != nil {
-		return err
-	}
-
-	// Connect to the gRPC server over localhost to skip
-	// the authentication.
-	err = v1.RegisterHeadscaleServiceHandler(ctx, grpcGatewayMux, grpcGatewayConn)
-	if err != nil {
-		return err
-	}
-
-	// Start the local gRPC server without TLS and without authentication
-	grpcSocket := grpc.NewServer(zerolog.UnaryInterceptor())
-
-	v1.RegisterHeadscaleServiceServer(grpcSocket, newHeadscaleV1APIServer(h))
-	reflection.Register(grpcSocket)
-
-	errorGroup.Go(func() error { return grpcSocket.Serve(socketListener) })
-
-	//
-	//
-	// Set up REMOTE listeners
-	//
-
-	tlsConfig, err := h.getTLSSettings()
-	if err != nil {
-		log.Error().Err(err).Msg("Failed to set up TLS configuration")
-
-		return err
-	}
-
-	//
-	//
-	// gRPC setup
-	//
-
-	// We are sadly not able to run gRPC and HTTPS (2.0) on the same
-	// port because the connection mux does not support matching them
-	// since they are so similar. There is multiple issues open and we
-	// can revisit this if changes:
-	// https://github.com/soheilhy/cmux/issues/68
-	// https://github.com/soheilhy/cmux/issues/91
-
-	if tlsConfig != nil || h.cfg.GRPCAllowInsecure {
-		log.Info().Msgf("Enabling remote gRPC at %s", h.cfg.GRPCAddr)
-
-		grpcOptions := []grpc.ServerOption{
-			grpc.UnaryInterceptor(
-				grpc_middleware.ChainUnaryServer(
-					h.grpcAuthenticationInterceptor,
-					zerolog.NewUnaryServerInterceptor(),
-				),
-			),
-		}
-
-		if tlsConfig != nil {
-			grpcOptions = append(grpcOptions,
-				grpc.Creds(credentials.NewTLS(tlsConfig)),
-			)
-		} else {
-			log.Warn().Msg("gRPC is running without security")
-		}
-
-		grpcServer := grpc.NewServer(grpcOptions...)
-
-		v1.RegisterHeadscaleServiceServer(grpcServer, newHeadscaleV1APIServer(h))
-		reflection.Register(grpcServer)
-
-		grpcListener, err := net.Listen("tcp", h.cfg.GRPCAddr)
-		if err != nil {
-			return fmt.Errorf("failed to bind to TCP address: %w", err)
-		}
-
-		errorGroup.Go(func() error { return grpcServer.Serve(grpcListener) })
-
-		log.Info().
-			Msgf("listening and serving gRPC on: %s", h.cfg.GRPCAddr)
-	}
-
-	//
-	//
-	// HTTP setup
-	//
-
-	router := h.createRouter(grpcGatewayMux)
-
-	httpServer := &http.Server{
-		Addr:        h.cfg.Addr,
-		Handler:     router,
-		ReadTimeout: HTTPReadTimeout,
-		// Go does not handle timeouts in HTTP very well, and there is
-		// no good way to handle streaming timeouts, therefore we need to
-		// keep this at unlimited and be careful to clean up connections
-		// https://blog.cloudflare.com/the-complete-guide-to-golang-net-http-timeouts/#aboutstreaming
-		WriteTimeout: 0,
-	}
-
-	var httpListener net.Listener
-	if tlsConfig != nil {
-		httpServer.TLSConfig = tlsConfig
-		httpListener, err = tls.Listen("tcp", h.cfg.Addr, tlsConfig)
-	} else {
-		httpListener, err = net.Listen("tcp", h.cfg.Addr)
-	}
-	if err != nil {
-		return fmt.Errorf("failed to bind to TCP address: %w", err)
-	}
-
-	errorGroup.Go(func() error { return httpServer.Serve(httpListener) })
-
-	log.Info().
-		Msgf("listening and serving HTTP on: %s", h.cfg.Addr)
-
-	return errorGroup.Wait()
-}
-
-func (h *Headscale) getTLSSettings() (*tls.Config, error) {
-	var err error
-	if h.cfg.TLSLetsEncryptHostname != "" {
-		if !strings.HasPrefix(h.cfg.ServerURL, "https://") {
-			log.Warn().
-				Msg("Listening with TLS but ServerURL does not start with https://")
-		}
-
-		certManager := autocert.Manager{
-			Prompt:     autocert.AcceptTOS,
-			HostPolicy: autocert.HostWhitelist(h.cfg.TLSLetsEncryptHostname),
-			Cache:      autocert.DirCache(h.cfg.TLSLetsEncryptCacheDir),
-			Client: &acme.Client{
-				DirectoryURL: h.cfg.ACMEURL,
-			},
-			Email: h.cfg.ACMEEmail,
-		}
-
-		switch h.cfg.TLSLetsEncryptChallengeType {
-		case "TLS-ALPN-01":
-			// Configuration via autocert with TLS-ALPN-01 (https://tools.ietf.org/html/rfc8737)
-			// The RFC requires that the validation is done on port 443; in other words, headscale
-			// must be reachable on port 443.
-			return certManager.TLSConfig(), nil
-
-		case "HTTP-01":
-			// Configuration via autocert with HTTP-01. This requires listening on
-			// port 80 for the certificate validation in addition to the headscale
-			// service, which can be configured to run on any other port.
-			go func() {
-				log.Fatal().
-					Caller().
-					Err(http.ListenAndServe(h.cfg.TLSLetsEncryptListen, certManager.HTTPHandler(http.HandlerFunc(h.redirect)))).
-					Msg("failed to set up a HTTP server")
-			}()
-
-			return certManager.TLSConfig(), nil
-
-		default:
-			return nil, errUnsupportedLetsEncryptChallengeType
-		}
-	} else if h.cfg.TLSCertPath == "" {
-		if !strings.HasPrefix(h.cfg.ServerURL, "http://") {
-			log.Warn().Msg("Listening without TLS but ServerURL does not start with http://")
-		}
-
-		return nil, err
-	} else {
-		if !strings.HasPrefix(h.cfg.ServerURL, "https://") {
-			log.Warn().Msg("Listening with TLS but ServerURL does not start with https://")
-		}
-		tlsConfig := &tls.Config{
-			ClientAuth:   tls.RequireAnyClientCert,
-			NextProtos:   []string{"http/1.1"},
-			Certificates: make([]tls.Certificate, 1),
-			MinVersion:   tls.VersionTLS12,
-		}
-		tlsConfig.Certificates[0], err = tls.LoadX509KeyPair(h.cfg.TLSCertPath, h.cfg.TLSKeyPath)
-
-		return tlsConfig, err
-	}
-}
-
-func (h *Headscale) setLastStateChangeToNow(namespace string) {
-	now := time.Now().UTC()
-	lastStateUpdate.WithLabelValues("", "headscale").Set(float64(now.Unix()))
-	h.lastStateChange.Store(namespace, now)
-}
-
-func (h *Headscale) getLastStateChange(namespaces ...string) time.Time {
-	times := []time.Time{}
-
-	for _, namespace := range namespaces {
-		if wrapped, ok := h.lastStateChange.Load(namespace); ok {
-			lastChange, _ := wrapped.(time.Time)
-
-			times = append(times, lastChange)
-		}
-	}
-
-	sort.Slice(times, func(i, j int) bool {
-		return times[i].After(times[j])
-	})
-
-	log.Trace().Msgf("Latest times %#v", times)
-
-	if len(times) == 0 {
-		return time.Now().UTC()
-	} else {
-		return times[0]
-	}
-}
-
-func stdoutHandler(ctx *gin.Context) {
-	body, _ := io.ReadAll(ctx.Request.Body)
-
-	log.Trace().
-		Interface("header", ctx.Request.Header).
-		Interface("proto", ctx.Request.Proto).
-		Interface("url", ctx.Request.URL).
-		Bytes("body", body).
-		Msg("Request did not match")
-}
-
-func readOrCreatePrivateKey(path string) (*key.MachinePrivate, error) {
-	privateKey, err := os.ReadFile(path)
-	if errors.Is(err, os.ErrNotExist) {
-		log.Info().Str("path", path).Msg("No private key file at path, creating...")
-
-		machineKey := key.NewMachine()
-
-		machineKeyStr, err := machineKey.MarshalText()
-		if err != nil {
-			return nil, fmt.Errorf(
-				"failed to convert private key to string for saving: %w",
-				err,
-			)
-		}
-		err = os.WriteFile(path, machineKeyStr, privateKeyFileMode)
-		if err != nil {
-			return nil, fmt.Errorf(
-				"failed to save private key to disk: %w",
-				err,
-			)
-		}
-
-		return &machineKey, nil
-	} else if err != nil {
-		return nil, fmt.Errorf("failed to read private key file: %w", err)
-	}
-
-	trimmedPrivateKey := strings.TrimSpace(string(privateKey))
-	privateKeyEnsurePrefix := PrivateKeyEnsurePrefix(trimmedPrivateKey)
-
-	var machineKey key.MachinePrivate
-	if err = machineKey.UnmarshalText([]byte(privateKeyEnsurePrefix)); err != nil {
-		log.Info().
-			Str("path", path).
-			Msg("This might be due to a legacy (headscale pre-0.12) private key. " +
-				"If the key is in WireGuard format, delete the key and restart headscale. " +
-				"A new key will automatically be generated. All Tailscale clients will have to be restarted")
-
-		return nil, fmt.Errorf("failed to parse private key: %w", err)
-	}
-
-	return &machineKey, nil
-}

app_test.go

@@ -1,67 +0,0 @@
-package headscale
-
-import (
-	"io/ioutil"
-	"os"
-	"testing"
-
-	"github.com/patrickmn/go-cache"
-	"gopkg.in/check.v1"
-	"inet.af/netaddr"
-)
-
-func Test(t *testing.T) {
-	check.TestingT(t)
-}
-
-var _ = check.Suite(&Suite{})
-
-type Suite struct{}
-
-var (
-	tmpDir string
-	app    Headscale
-)
-
-func (s *Suite) SetUpTest(c *check.C) {
-	s.ResetDB(c)
-}
-
-func (s *Suite) TearDownTest(c *check.C) {
-	os.RemoveAll(tmpDir)
-}
-
-func (s *Suite) ResetDB(c *check.C) {
-	if len(tmpDir) != 0 {
-		os.RemoveAll(tmpDir)
-	}
-	var err error
-	tmpDir, err = ioutil.TempDir("", "autoygg-client-test")
-	if err != nil {
-		c.Fatal(err)
-	}
-	cfg := Config{
-		IPPrefixes: []netaddr.IPPrefix{
-			netaddr.MustParseIPPrefix("10.27.0.0/23"),
-		},
-	}
-
-	app = Headscale{
-		cfg:      cfg,
-		dbType:   "sqlite3",
-		dbString: tmpDir + "/headscale_test.db",
-		requestedExpiryCache: cache.New(
-			requestedExpiryCacheExpiration,
-			requestedExpiryCacheCleanupInterval,
-		),
-	}
-	err = app.initDB()
-	if err != nil {
-		c.Fatal(err)
-	}
-	db, err := app.openDB()
-	if err != nil {
-		c.Fatal(err)
-	}
-	app.db = db
-}

apple_mobileconfig.go

@@ -1,266 +0,0 @@
-package headscale
-
-import (
-	"bytes"
-	"html/template"
-	"net/http"
-
-	"github.com/gin-gonic/gin"
-	"github.com/gofrs/uuid"
-	"github.com/rs/zerolog/log"
-)
-
-// AppleMobileConfig shows a simple message in the browser to point to the CLI
-// Listens in /register.
-func (h *Headscale) AppleMobileConfig(ctx *gin.Context) {
-	appleTemplate := template.Must(template.New("apple").Parse(`
-<html>
-	<body>
-		<h1>Apple configuration profiles</h1>
-		<p>
-		    This page provides <a href="https://support.apple.com/guide/mdm/mdm-overview-mdmbf9e668/web">configuration profiles</a> for the official Tailscale clients for <a href="https://apps.apple.com/us/app/tailscale/id1470499037?ls=1">iOS</a> and <a href="https://apps.apple.com/ca/app/tailscale/id1475387142?mt=12">macOS</a>.
-		</p>
-		<p>
-		    The profiles will configure Tailscale.app to use {{.Url}} as its control server.
-		</p>
-
-		<h3>Caution</h3>
-		<p>You should always inspect the profile before installing it:</p>
-		<!--
-		<p><code>curl {{.Url}}/apple/ios</code></p>
-		-->
-		<p><code>curl {{.Url}}/apple/macos</code></p>
-		
-		<h2>Profiles</h2>
-
-		<!--
-		<h3>iOS</h3>
-		<p>
-		    <a href="/apple/ios" download="headscale_ios.mobileconfig">iOS profile</a>
-		</p>
-		-->
-		
-		<h3>macOS</h3>
-		<p>Headscale can be set to the default server by installing a Headscale configuration profile:</p>
-		<p>
-		    <a href="/apple/macos" download="headscale_macos.mobileconfig">macOS profile</a>
-		</p>
-
-		<ol>
-		<li>Download the profile, then open it. When it has been opened, there should be a notification that a profile can be installed</li>
-		<li>Open System Preferences and go to "Profiles"</li>
-		<li>Find and install the Headscale profile</li>
-		<li>Restart Tailscale.app and log in</li>
-		</ol>
-
-		<p>Or</p>
-		<p>Use your terminal to configure the default setting for Tailscale by issuing:</p>
-		<code>defaults write io.tailscale.ipn.macos ControlURL {{.URL}}</code>
-
-		<p>Restart Tailscale.app and log in.</p>
-	
-	</body>
-</html>`))
-
-	config := map[string]interface{}{
-		"URL": h.cfg.ServerURL,
-	}
-
-	var payload bytes.Buffer
-	if err := appleTemplate.Execute(&payload, config); err != nil {
-		log.Error().
-			Str("handler", "AppleMobileConfig").
-			Err(err).
-			Msg("Could not render Apple index template")
-		ctx.Data(
-			http.StatusInternalServerError,
-			"text/html; charset=utf-8",
-			[]byte("Could not render Apple index template"),
-		)
-
-		return
-	}
-
-	ctx.Data(http.StatusOK, "text/html; charset=utf-8", payload.Bytes())
-}
-
-func (h *Headscale) ApplePlatformConfig(ctx *gin.Context) {
-	platform := ctx.Param("platform")
-
-	id, err := uuid.NewV4()
-	if err != nil {
-		log.Error().
-			Str("handler", "ApplePlatformConfig").
-			Err(err).
-			Msg("Failed not create UUID")
-		ctx.Data(
-			http.StatusInternalServerError,
-			"text/html; charset=utf-8",
-			[]byte("Failed to create UUID"),
-		)
-
-		return
-	}
-
-	contentID, err := uuid.NewV4()
-	if err != nil {
-		log.Error().
-			Str("handler", "ApplePlatformConfig").
-			Err(err).
-			Msg("Failed not create UUID")
-		ctx.Data(
-			http.StatusInternalServerError,
-			"text/html; charset=utf-8",
-			[]byte("Failed to create UUID"),
-		)
-
-		return
-	}
-
-	platformConfig := AppleMobilePlatformConfig{
-		UUID: contentID,
-		URL:  h.cfg.ServerURL,
-	}
-
-	var payload bytes.Buffer
-
-	switch platform {
-	case "macos":
-		if err := macosTemplate.Execute(&payload, platformConfig); err != nil {
-			log.Error().
-				Str("handler", "ApplePlatformConfig").
-				Err(err).
-				Msg("Could not render Apple macOS template")
-			ctx.Data(
-				http.StatusInternalServerError,
-				"text/html; charset=utf-8",
-				[]byte("Could not render Apple macOS template"),
-			)
-
-			return
-		}
-	case "ios":
-		if err := iosTemplate.Execute(&payload, platformConfig); err != nil {
-			log.Error().
-				Str("handler", "ApplePlatformConfig").
-				Err(err).
-				Msg("Could not render Apple iOS template")
-			ctx.Data(
-				http.StatusInternalServerError,
-				"text/html; charset=utf-8",
-				[]byte("Could not render Apple iOS template"),
-			)
-
-			return
-		}
-	default:
-		ctx.Data(
-			http.StatusOK,
-			"text/html; charset=utf-8",
-			[]byte("Invalid platform, only ios and macos is supported"),
-		)
-
-		return
-	}
-
-	config := AppleMobileConfig{
-		UUID:    id,
-		URL:     h.cfg.ServerURL,
-		Payload: payload.String(),
-	}
-
-	var content bytes.Buffer
-	if err := commonTemplate.Execute(&content, config); err != nil {
-		log.Error().
-			Str("handler", "ApplePlatformConfig").
-			Err(err).
-			Msg("Could not render Apple platform template")
-		ctx.Data(
-			http.StatusInternalServerError,
-			"text/html; charset=utf-8",
-			[]byte("Could not render Apple platform template"),
-		)
-
-		return
-	}
-
-	ctx.Data(
-		http.StatusOK,
-		"application/x-apple-aspen-config; charset=utf-8",
-		content.Bytes(),
-	)
-}
-
-type AppleMobileConfig struct {
-	UUID    uuid.UUID
-	URL     string
-	Payload string
-}
-
-type AppleMobilePlatformConfig struct {
-	UUID uuid.UUID
-	URL  string
-}
-
-var commonTemplate = template.Must(
-	template.New("mobileconfig").Parse(`<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-  <dict>
-    <key>PayloadUUID</key>
-    <string>{{.UUID}}</string>
-    <key>PayloadDisplayName</key>
-    <string>Headscale</string>
-    <key>PayloadDescription</key>
-    <string>Configure Tailscale login server to: {{.URL}}</string>
-    <key>PayloadIdentifier</key>
-    <string>com.github.juanfont.headscale</string>
-    <key>PayloadRemovalDisallowed</key>
-    <false/>
-    <key>PayloadType</key>
-    <string>Configuration</string>
-    <key>PayloadVersion</key>
-    <integer>1</integer>
-    <key>PayloadContent</key>
-    <array>
-    {{.Payload}}
-    </array>
-  </dict>
-</plist>`),
-)
-
-var iosTemplate = template.Must(template.New("iosTemplate").Parse(`
-    <dict>
-        <key>PayloadType</key>
-        <string>io.tailscale.ipn.ios</string>
-        <key>PayloadUUID</key>
-        <string>{{.UUID}}</string>
-        <key>PayloadIdentifier</key>
-        <string>com.github.juanfont.headscale</string>
-        <key>PayloadVersion</key>
-        <integer>1</integer>
-        <key>PayloadEnabled</key>
-        <true/>
-
-        <key>ControlURL</key>
-        <string>{{.URL}}</string>
-    </dict>
-`))
-
-var macosTemplate = template.Must(template.New("macosTemplate").Parse(`
-    <dict>
-        <key>PayloadType</key>
-        <string>io.tailscale.ipn.macos</string>
-        <key>PayloadUUID</key>
-        <string>{{.UUID}}</string>
-        <key>PayloadIdentifier</key>
-        <string>com.github.juanfont.headscale</string>
-        <key>PayloadVersion</key>
-        <integer>1</integer>
-        <key>PayloadEnabled</key>
-        <true/>
-
-        <key>ControlURL</key>
-        <string>{{.URL}}</string>
-    </dict>
-`))

cli_test.go

@@ -1,41 +0,0 @@
-package headscale
-
-import (
-	"time"
-
-	"gopkg.in/check.v1"
-	"inet.af/netaddr"
-)
-
-func (s *Suite) TestRegisterMachine(c *check.C) {
-	namespace, err := app.CreateNamespace("test")
-	c.Assert(err, check.IsNil)
-
-	now := time.Now().UTC()
-
-	machine := Machine{
-		ID:          0,
-		MachineKey:  "8ce002a935f8c394e55e78fbbb410576575ff8ec5cfa2e627e4b807f1be15b0e",
-		NodeKey:     "bar",
-		DiscoKey:    "faa",
-		Name:        "testmachine",
-		NamespaceID: namespace.ID,
-		IPAddresses: []netaddr.IP{netaddr.MustParseIP("10.0.0.1")},
-		Expiry:      &now,
-	}
-	err = app.db.Save(&machine).Error
-	c.Assert(err, check.IsNil)
-
-	_, err = app.GetMachine(namespace.Name, machine.Name)
-	c.Assert(err, check.IsNil)
-
-	machineAfterRegistering, err := app.RegisterMachine(
-		machine.MachineKey,
-		namespace.Name,
-	)
-	c.Assert(err, check.IsNil)
-	c.Assert(machineAfterRegistering.Registered, check.Equals, true)
-
-	_, err = machineAfterRegistering.GetHostInfo()
-	c.Assert(err, check.IsNil)
-}

cmd/headscale/cli/api_key.go

@@ -1,21 +1,19 @@
 package cli
 
 import (
+	"context"
 	"fmt"
 	"strconv"
-	"time"
 
-	"github.com/juanfont/headscale"
 	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/juanfont/headscale/hscontrol/util"
 	"github.com/pterm/pterm"
-	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
-	"google.golang.org/protobuf/types/known/timestamppb"
 )
 
 const (
-	// 90 days.
-	DefaultAPIKeyExpiry = 90 * 24 * time.Hour
+	// DefaultAPIKeyExpiry is 90 days.
+	DefaultAPIKeyExpiry = "90d"
 )
 
 func init() {
@@ -23,81 +21,58 @@ func init() {
 	apiKeysCmd.AddCommand(listAPIKeys)
 
 	createAPIKeyCmd.Flags().
-		DurationP("expiration", "e", DefaultAPIKeyExpiry, "Human-readable expiration of the key (30m, 24h, 365d...)")
+		StringP("expiration", "e", DefaultAPIKeyExpiry, "Human-readable expiration of the key (e.g. 30m, 24h)")
 
 	apiKeysCmd.AddCommand(createAPIKeyCmd)
 
 	expireAPIKeyCmd.Flags().StringP("prefix", "p", "", "ApiKey prefix")
-	err := expireAPIKeyCmd.MarkFlagRequired("prefix")
-	if err != nil {
-		log.Fatal().Err(err).Msg("")
-	}
+	expireAPIKeyCmd.Flags().Uint64P("id", "i", 0, "ApiKey ID")
 	apiKeysCmd.AddCommand(expireAPIKeyCmd)
+
+	deleteAPIKeyCmd.Flags().StringP("prefix", "p", "", "ApiKey prefix")
+	deleteAPIKeyCmd.Flags().Uint64P("id", "i", 0, "ApiKey ID")
+	apiKeysCmd.AddCommand(deleteAPIKeyCmd)
 }
 
 var apiKeysCmd = &cobra.Command{
-	Use:   "apikeys",
-	Short: "Handle the Api keys in Headscale",
+	Use:     "apikeys",
+	Short:   "Handle the Api keys in Headscale",
+	Aliases: []string{"apikey", "api"},
 }
 
 var listAPIKeys = &cobra.Command{
-	Use:   "list",
-	Short: "List the Api keys for headscale",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.ListApiKeysRequest{}
-
-		response, err := client.ListApiKeys(ctx, request)
+	Use:     "list",
+	Short:   "List the Api keys for headscale",
+	Aliases: []string{"ls", "show"},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		response, err := client.ListApiKeys(ctx, &v1.ListApiKeysRequest{})
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting the list of keys: %s", err),
-				output,
-			)
-
-			return
+			return fmt.Errorf("listing api keys: %w", err)
 		}
 
-		if output != "" {
-			SuccessOutput(response.ApiKeys, "", output)
-
-			return
-		}
-
-		tableData := pterm.TableData{
-			{"ID", "Prefix", "Expiration", "Created"},
-		}
-		for _, key := range response.ApiKeys {
-			expiration := "-"
-
-			if key.GetExpiration() != nil {
-				expiration = ColourTime(key.Expiration.AsTime())
+		return printListOutput(cmd, response.GetApiKeys(), func() error {
+			tableData := pterm.TableData{
+				{"ID", "Prefix", "Expiration", "Created"},
 			}
 
-			tableData = append(tableData, []string{
-				strconv.FormatUint(key.GetId(), headscale.Base10),
-				key.GetPrefix(),
-				expiration,
-				key.GetCreatedAt().AsTime().Format(HeadscaleDateTimeFormat),
-			})
+			for _, key := range response.GetApiKeys() {
+				expiration := "-"
 
-		}
-		err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Failed to render pterm table: %s", err),
-				output,
-			)
+				if key.GetExpiration() != nil {
+					expiration = ColourTime(key.GetExpiration().AsTime())
+				}
 
-			return
-		}
-	},
+				tableData = append(tableData, []string{
+					strconv.FormatUint(key.GetId(), util.Base10),
+					key.GetPrefix(),
+					expiration,
+					key.GetCreatedAt().AsTime().Format(HeadscaleDateTimeFormat),
+				})
+			}
+
+			return pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
+		})
+	}),
 }
 
 var createAPIKeyCmd = &cobra.Command{
@@ -107,77 +82,80 @@ var createAPIKeyCmd = &cobra.Command{
 Creates a new Api key, the Api key is only visible on creation
 and cannot be retrieved again.
 If you loose a key, create a new one and revoke (expire) the old one.`,
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		log.Trace().
-			Msg("Preparing to create ApiKey")
-
-		request := &v1.CreateApiKeyRequest{}
-
-		duration, _ := cmd.Flags().GetDuration("expiration")
-		expiration := time.Now().UTC().Add(duration)
-
-		log.Trace().Dur("expiration", duration).Msg("expiration has been set")
-
-		request.Expiration = timestamppb.New(expiration)
-
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
-
-		response, err := client.CreateApiKey(ctx, request)
+	Aliases: []string{"c", "new"},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		expiration, err := expirationFromFlag(cmd)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot create Api Key: %s\n", err),
-				output,
-			)
-
-			return
+			return err
 		}
 
-		SuccessOutput(response.ApiKey, response.ApiKey, output)
-	},
+		response, err := client.CreateApiKey(ctx, &v1.CreateApiKeyRequest{
+			Expiration: expiration,
+		})
+		if err != nil {
+			return fmt.Errorf("creating api key: %w", err)
+		}
+
+		return printOutput(cmd, response.GetApiKey(), response.GetApiKey())
+	}),
+}
+
+// apiKeyIDOrPrefix reads --id and --prefix from cmd and validates that
+// exactly one is provided.
+func apiKeyIDOrPrefix(cmd *cobra.Command) (uint64, string, error) {
+	id, _ := cmd.Flags().GetUint64("id")
+	prefix, _ := cmd.Flags().GetString("prefix")
+
+	switch {
+	case id == 0 && prefix == "":
+		return 0, "", fmt.Errorf("either --id or --prefix must be provided: %w", errMissingParameter)
+	case id != 0 && prefix != "":
+		return 0, "", fmt.Errorf("only one of --id or --prefix can be provided: %w", errMissingParameter)
+	}
+
+	return id, prefix, nil
 }
 
 var expireAPIKeyCmd = &cobra.Command{
 	Use:     "expire",
 	Short:   "Expire an ApiKey",
-	Aliases: []string{"revoke"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		prefix, err := cmd.Flags().GetString("prefix")
+	Aliases: []string{"revoke", "exp", "e"},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		id, prefix, err := apiKeyIDOrPrefix(cmd)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting prefix from CLI flag: %s", err),
-				output,
-			)
-
-			return
+			return err
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.ExpireApiKeyRequest{
+		response, err := client.ExpireApiKey(ctx, &v1.ExpireApiKeyRequest{
+			Id:     id,
 			Prefix: prefix,
-		}
-
-		response, err := client.ExpireApiKey(ctx, request)
+		})
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot expire Api Key: %s\n", err),
-				output,
-			)
-
-			return
+			return fmt.Errorf("expiring api key: %w", err)
 		}
 
-		SuccessOutput(response, "Key expired", output)
-	},
+		return printOutput(cmd, response, "Key expired")
+	}),
+}
+
+var deleteAPIKeyCmd = &cobra.Command{
+	Use:     "delete",
+	Short:   "Delete an ApiKey",
+	Aliases: []string{"remove", "del"},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		id, prefix, err := apiKeyIDOrPrefix(cmd)
+		if err != nil {
+			return err
+		}
+
+		response, err := client.DeleteApiKey(ctx, &v1.DeleteApiKeyRequest{
+			Id:     id,
+			Prefix: prefix,
+		})
+		if err != nil {
+			return fmt.Errorf("deleting api key: %w", err)
+		}
+
+		return printOutput(cmd, response, "Key deleted")
+	}),
 }

cmd/headscale/cli/auth.go

@@ -0,0 +1,93 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+
+	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/spf13/cobra"
+)
+
+func init() {
+	rootCmd.AddCommand(authCmd)
+
+	authRegisterCmd.Flags().StringP("user", "u", "", "User")
+	authRegisterCmd.Flags().String("auth-id", "", "Auth ID")
+	mustMarkRequired(authRegisterCmd, "user", "auth-id")
+	authCmd.AddCommand(authRegisterCmd)
+
+	authApproveCmd.Flags().String("auth-id", "", "Auth ID")
+	mustMarkRequired(authApproveCmd, "auth-id")
+	authCmd.AddCommand(authApproveCmd)
+
+	authRejectCmd.Flags().String("auth-id", "", "Auth ID")
+	mustMarkRequired(authRejectCmd, "auth-id")
+	authCmd.AddCommand(authRejectCmd)
+}
+
+var authCmd = &cobra.Command{
+	Use:   "auth",
+	Short: "Manage node authentication and approval",
+}
+
+var authRegisterCmd = &cobra.Command{
+	Use:   "register",
+	Short: "Register a node to your network",
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		user, _ := cmd.Flags().GetString("user")
+		authID, _ := cmd.Flags().GetString("auth-id")
+
+		request := &v1.AuthRegisterRequest{
+			AuthId: authID,
+			User:   user,
+		}
+
+		response, err := client.AuthRegister(ctx, request)
+		if err != nil {
+			return fmt.Errorf("registering node: %w", err)
+		}
+
+		return printOutput(
+			cmd,
+			response.GetNode(),
+			fmt.Sprintf("Node %s registered", response.GetNode().GetGivenName()))
+	}),
+}
+
+var authApproveCmd = &cobra.Command{
+	Use:   "approve",
+	Short: "Approve a pending authentication request",
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		authID, _ := cmd.Flags().GetString("auth-id")
+
+		request := &v1.AuthApproveRequest{
+			AuthId: authID,
+		}
+
+		response, err := client.AuthApprove(ctx, request)
+		if err != nil {
+			return fmt.Errorf("approving auth request: %w", err)
+		}
+
+		return printOutput(cmd, response, "Auth request approved")
+	}),
+}
+
+var authRejectCmd = &cobra.Command{
+	Use:   "reject",
+	Short: "Reject a pending authentication request",
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		authID, _ := cmd.Flags().GetString("auth-id")
+
+		request := &v1.AuthRejectRequest{
+			AuthId: authID,
+		}
+
+		response, err := client.AuthReject(ctx, request)
+		if err != nil {
+			return fmt.Errorf("rejecting auth request: %w", err)
+		}
+
+		return printOutput(cmd, response, "Auth request rejected")
+	}),
+}

cmd/headscale/cli/configtest.go

@@ -0,0 +1,25 @@
+package cli
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+)
+
+func init() {
+	rootCmd.AddCommand(configTestCmd)
+}
+
+var configTestCmd = &cobra.Command{
+	Use:   "configtest",
+	Short: "Test the configuration.",
+	Long:  "Run a test of the configuration and exit.",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		_, err := newHeadscaleServerWithConfig()
+		if err != nil {
+			return fmt.Errorf("configuration error: %w", err)
+		}
+
+		return nil
+	},
+}

cmd/headscale/cli/debug.go

@@ -1,42 +1,22 @@
 package cli
 
 import (
+	"context"
 	"fmt"
 
 	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
-	"github.com/rs/zerolog/log"
+	"github.com/juanfont/headscale/hscontrol/types"
 	"github.com/spf13/cobra"
-	"google.golang.org/grpc/status"
 )
 
-const (
-	keyLength             = 64
-	errPreAuthKeyTooShort = Error("key too short, must be 64 hexadecimal characters")
-)
-
-// Error is used to compare errors as per https://dave.cheney.net/2016/04/07/constant-errors
-type Error string
-
-func (e Error) Error() string { return string(e) }
-
 func init() {
 	rootCmd.AddCommand(debugCmd)
 
 	createNodeCmd.Flags().StringP("name", "", "", "Name")
-	err := createNodeCmd.MarkFlagRequired("name")
-	if err != nil {
-		log.Fatal().Err(err).Msg("")
-	}
-	createNodeCmd.Flags().StringP("namespace", "n", "", "Namespace")
-	err = createNodeCmd.MarkFlagRequired("namespace")
-	if err != nil {
-		log.Fatal().Err(err).Msg("")
-	}
+	createNodeCmd.Flags().StringP("user", "u", "", "User")
 	createNodeCmd.Flags().StringP("key", "k", "", "Key")
-	err = createNodeCmd.MarkFlagRequired("key")
-	if err != nil {
-		log.Fatal().Err(err).Msg("")
-	}
+	mustMarkRequired(createNodeCmd, "name", "user", "key")
+
 	createNodeCmd.Flags().
 		StringSliceP("route", "r", []string{}, "List (or repeated flags) of routes to advertise")
 
@@ -51,82 +31,31 @@ var debugCmd = &cobra.Command{
 
 var createNodeCmd = &cobra.Command{
 	Use:   "create-node",
-	Short: "Create a node (machine) that can be registered with `nodes register <>` command",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
+	Short: "Create a node that can be registered with `auth register <>` command",
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		user, _ := cmd.Flags().GetString("user")
+		name, _ := cmd.Flags().GetString("name")
+		registrationID, _ := cmd.Flags().GetString("key")
 
-		namespace, err := cmd.Flags().GetString("namespace")
+		_, err := types.AuthIDFromString(registrationID)
 		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error getting namespace: %s", err), output)
-
-			return
+			return fmt.Errorf("parsing machine key: %w", err)
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
+		routes, _ := cmd.Flags().GetStringSlice("route")
 
-		name, err := cmd.Flags().GetString("name")
+		request := &v1.DebugCreateNodeRequest{
+			Key:    registrationID,
+			Name:   name,
+			User:   user,
+			Routes: routes,
+		}
+
+		response, err := client.DebugCreateNode(ctx, request)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting node from flag: %s", err),
-				output,
-			)
-
-			return
+			return fmt.Errorf("creating node: %w", err)
 		}
 
-		machineKey, err := cmd.Flags().GetString("key")
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting key from flag: %s", err),
-				output,
-			)
-
-			return
-		}
-		if len(machineKey) != keyLength {
-			err = errPreAuthKeyTooShort
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error: %s", err),
-				output,
-			)
-
-			return
-		}
-
-		routes, err := cmd.Flags().GetStringSlice("route")
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting routes from flag: %s", err),
-				output,
-			)
-
-			return
-		}
-
-		request := &v1.DebugCreateMachineRequest{
-			Key:       machineKey,
-			Name:      name,
-			Namespace: namespace,
-			Routes:    routes,
-		}
-
-		response, err := client.DebugCreateMachine(ctx, request)
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot create machine: %s", status.Convert(err).Message()),
-				output,
-			)
-
-			return
-		}
-
-		SuccessOutput(response.Machine, "Machine created", output)
-	},
+		return printOutput(cmd, response.GetNode(), "Node created")
+	}),
 }

cmd/headscale/cli/dump_config.go

@@ -0,0 +1,26 @@
+package cli
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
+)
+
+func init() {
+	rootCmd.AddCommand(dumpConfigCmd)
+}
+
+var dumpConfigCmd = &cobra.Command{
+	Use:    "dumpConfig",
+	Short:  "dump current config to /etc/headscale/config.dump.yaml, integration test only",
+	Hidden: true,
+	RunE: func(cmd *cobra.Command, args []string) error {
+		err := viper.WriteConfigAs("/etc/headscale/config.dump.yaml")
+		if err != nil {
+			return fmt.Errorf("dumping config: %w", err)
+		}
+
+		return nil
+	},
+}

cmd/headscale/cli/generate.go

@@ -13,29 +13,25 @@ func init() {
 }
 
 var generateCmd = &cobra.Command{
-	Use:   "generate",
-	Short: "Generate commands",
+	Use:     "generate",
+	Short:   "Generate commands",
+	Aliases: []string{"gen"},
 }
 
 var generatePrivateKeyCmd = &cobra.Command{
 	Use:   "private-key",
 	Short: "Generate a private key for the headscale server",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
+	RunE: func(cmd *cobra.Command, args []string) error {
 		machineKey := key.NewMachine()
 
 		machineKeyStr, err := machineKey.MarshalText()
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting machine key from flag: %s", err),
-				output,
-			)
+			return fmt.Errorf("marshalling machine key: %w", err)
 		}
 
-		SuccessOutput(map[string]string{
+		return printOutput(cmd, map[string]string{
 			"private_key": string(machineKeyStr),
 		},
-			string(machineKeyStr), output)
+			string(machineKeyStr))
 	},
 }

cmd/headscale/cli/health.go

@@ -0,0 +1,27 @@
+package cli
+
+import (
+	"context"
+	"fmt"
+
+	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/spf13/cobra"
+)
+
+func init() {
+	rootCmd.AddCommand(healthCmd)
+}
+
+var healthCmd = &cobra.Command{
+	Use:   "health",
+	Short: "Check the health of the Headscale server",
+	Long:  "Check the health of the Headscale server. This command will return an exit code of 0 if the server is healthy, or 1 if it is not.",
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		response, err := client.Health(ctx, &v1.HealthRequest{})
+		if err != nil {
+			return fmt.Errorf("checking health: %w", err)
+		}
+
+		return printOutput(cmd, response, "")
+	}),
+}

cmd/headscale/cli/mockoidc.go

@@ -0,0 +1,164 @@
+package cli
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net"
+	"net/http"
+	"os"
+	"strconv"
+	"time"
+
+	"github.com/juanfont/headscale/hscontrol/util/zlog/zf"
+	"github.com/oauth2-proxy/mockoidc"
+	"github.com/rs/zerolog/log"
+	"github.com/spf13/cobra"
+)
+
+// Error is used to compare errors as per https://dave.cheney.net/2016/04/07/constant-errors
+type Error string
+
+func (e Error) Error() string { return string(e) }
+
+const (
+	errMockOidcClientIDNotDefined     = Error("MOCKOIDC_CLIENT_ID not defined")
+	errMockOidcClientSecretNotDefined = Error("MOCKOIDC_CLIENT_SECRET not defined")
+	errMockOidcPortNotDefined         = Error("MOCKOIDC_PORT not defined")
+	errMockOidcUsersNotDefined        = Error("MOCKOIDC_USERS not defined")
+	refreshTTL                        = 60 * time.Minute
+)
+
+var accessTTL = 2 * time.Minute
+
+func init() {
+	rootCmd.AddCommand(mockOidcCmd)
+}
+
+var mockOidcCmd = &cobra.Command{
+	Use:   "mockoidc",
+	Short: "Runs a mock OIDC server for testing",
+	Long:  "This internal command runs a OpenID Connect for testing purposes",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		err := mockOIDC()
+		if err != nil {
+			return fmt.Errorf("running mock OIDC server: %w", err)
+		}
+
+		return nil
+	},
+}
+
+func mockOIDC() error {
+	clientID := os.Getenv("MOCKOIDC_CLIENT_ID")
+	if clientID == "" {
+		return errMockOidcClientIDNotDefined
+	}
+
+	clientSecret := os.Getenv("MOCKOIDC_CLIENT_SECRET")
+	if clientSecret == "" {
+		return errMockOidcClientSecretNotDefined
+	}
+
+	addrStr := os.Getenv("MOCKOIDC_ADDR")
+	if addrStr == "" {
+		return errMockOidcPortNotDefined
+	}
+
+	portStr := os.Getenv("MOCKOIDC_PORT")
+	if portStr == "" {
+		return errMockOidcPortNotDefined
+	}
+
+	accessTTLOverride := os.Getenv("MOCKOIDC_ACCESS_TTL")
+	if accessTTLOverride != "" {
+		newTTL, err := time.ParseDuration(accessTTLOverride)
+		if err != nil {
+			return err
+		}
+
+		accessTTL = newTTL
+	}
+
+	userStr := os.Getenv("MOCKOIDC_USERS")
+	if userStr == "" {
+		return errMockOidcUsersNotDefined
+	}
+
+	var users []mockoidc.MockUser
+
+	err := json.Unmarshal([]byte(userStr), &users)
+	if err != nil {
+		return fmt.Errorf("unmarshalling users: %w", err)
+	}
+
+	log.Info().Interface(zf.Users, users).Msg("loading users from JSON")
+
+	log.Info().Msgf("access token TTL: %s", accessTTL)
+
+	port, err := strconv.Atoi(portStr)
+	if err != nil {
+		return err
+	}
+
+	mock, err := getMockOIDC(clientID, clientSecret, users)
+	if err != nil {
+		return err
+	}
+
+	listener, err := new(net.ListenConfig).Listen(context.Background(), "tcp", fmt.Sprintf("%s:%d", addrStr, port))
+	if err != nil {
+		return err
+	}
+
+	err = mock.Start(listener, nil)
+	if err != nil {
+		return err
+	}
+
+	log.Info().Msgf("mock OIDC server listening on %s", listener.Addr().String())
+	log.Info().Msgf("issuer: %s", mock.Issuer())
+
+	c := make(chan struct{})
+	<-c
+
+	return nil
+}
+
+func getMockOIDC(clientID string, clientSecret string, users []mockoidc.MockUser) (*mockoidc.MockOIDC, error) {
+	keypair, err := mockoidc.NewKeypair(nil)
+	if err != nil {
+		return nil, err
+	}
+
+	userQueue := mockoidc.UserQueue{}
+
+	for _, user := range users {
+		userQueue.Push(&user)
+	}
+
+	mock := mockoidc.MockOIDC{
+		ClientID:                      clientID,
+		ClientSecret:                  clientSecret,
+		AccessTTL:                     accessTTL,
+		RefreshTTL:                    refreshTTL,
+		CodeChallengeMethodsSupported: []string{"plain", "S256"},
+		Keypair:                       keypair,
+		SessionStore:                  mockoidc.NewSessionStore(),
+		UserQueue:                     &userQueue,
+		ErrorQueue:                    &mockoidc.ErrorQueue{},
+	}
+
+	_ = mock.AddMiddleware(func(h http.Handler) http.Handler {
+		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			log.Info().Msgf("request: %+v", r)
+			h.ServeHTTP(w, r)
+
+			if r.Response != nil {
+				log.Info().Msgf("response: %+v", r.Response)
+			}
+		})
+	})
+
+	return &mock, nil
+}

cmd/headscale/cli/namespaces.go

@@ -1,238 +0,0 @@
-package cli
-
-import (
-	"fmt"
-
-	survey "github.com/AlecAivazis/survey/v2"
-	"github.com/juanfont/headscale"
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
-	"github.com/pterm/pterm"
-	"github.com/rs/zerolog/log"
-	"github.com/spf13/cobra"
-	"google.golang.org/grpc/status"
-)
-
-func init() {
-	rootCmd.AddCommand(namespaceCmd)
-	namespaceCmd.AddCommand(createNamespaceCmd)
-	namespaceCmd.AddCommand(listNamespacesCmd)
-	namespaceCmd.AddCommand(destroyNamespaceCmd)
-	namespaceCmd.AddCommand(renameNamespaceCmd)
-}
-
-const (
-	errMissingParameter = headscale.Error("missing parameters")
-)
-
-var namespaceCmd = &cobra.Command{
-	Use:   "namespaces",
-	Short: "Manage the namespaces of Headscale",
-}
-
-var createNamespaceCmd = &cobra.Command{
-	Use:   "create NAME",
-	Short: "Creates a new namespace",
-	Args: func(cmd *cobra.Command, args []string) error {
-		if len(args) < 1 {
-			return errMissingParameter
-		}
-
-		return nil
-	},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		namespaceName := args[0]
-
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
-
-		log.Trace().Interface("client", client).Msg("Obtained gRPC client")
-
-		request := &v1.CreateNamespaceRequest{Name: namespaceName}
-
-		log.Trace().Interface("request", request).Msg("Sending CreateNamespace request")
-		response, err := client.CreateNamespace(ctx, request)
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf(
-					"Cannot create namespace: %s",
-					status.Convert(err).Message(),
-				),
-				output,
-			)
-
-			return
-		}
-
-		SuccessOutput(response.Namespace, "Namespace created", output)
-	},
-}
-
-var destroyNamespaceCmd = &cobra.Command{
-	Use:   "destroy NAME",
-	Short: "Destroys a namespace",
-	Args: func(cmd *cobra.Command, args []string) error {
-		if len(args) < 1 {
-			return errMissingParameter
-		}
-
-		return nil
-	},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		namespaceName := args[0]
-
-		request := &v1.GetNamespaceRequest{
-			Name: namespaceName,
-		}
-
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
-
-		_, err := client.GetNamespace(ctx, request)
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error: %s", status.Convert(err).Message()),
-				output,
-			)
-
-			return
-		}
-
-		confirm := false
-		force, _ := cmd.Flags().GetBool("force")
-		if !force {
-			prompt := &survey.Confirm{
-				Message: fmt.Sprintf(
-					"Do you want to remove the namespace '%s' and any associated preauthkeys?",
-					namespaceName,
-				),
-			}
-			err := survey.AskOne(prompt, &confirm)
-			if err != nil {
-				return
-			}
-		}
-
-		if confirm || force {
-			request := &v1.DeleteNamespaceRequest{Name: namespaceName}
-
-			response, err := client.DeleteNamespace(ctx, request)
-			if err != nil {
-				ErrorOutput(
-					err,
-					fmt.Sprintf(
-						"Cannot destroy namespace: %s",
-						status.Convert(err).Message(),
-					),
-					output,
-				)
-
-				return
-			}
-			SuccessOutput(response, "Namespace destroyed", output)
-		} else {
-			SuccessOutput(map[string]string{"Result": "Namespace not destroyed"}, "Namespace not destroyed", output)
-		}
-	},
-}
-
-var listNamespacesCmd = &cobra.Command{
-	Use:   "list",
-	Short: "List all the namespaces",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.ListNamespacesRequest{}
-
-		response, err := client.ListNamespaces(ctx, request)
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot get namespaces: %s", status.Convert(err).Message()),
-				output,
-			)
-
-			return
-		}
-
-		if output != "" {
-			SuccessOutput(response.Namespaces, "", output)
-
-			return
-		}
-
-		tableData := pterm.TableData{{"ID", "Name", "Created"}}
-		for _, namespace := range response.GetNamespaces() {
-			tableData = append(
-				tableData,
-				[]string{
-					namespace.GetId(),
-					namespace.GetName(),
-					namespace.GetCreatedAt().AsTime().Format("2006-01-02 15:04:05"),
-				},
-			)
-		}
-		err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Failed to render pterm table: %s", err),
-				output,
-			)
-
-			return
-		}
-	},
-}
-
-var renameNamespaceCmd = &cobra.Command{
-	Use:   "rename OLD_NAME NEW_NAME",
-	Short: "Renames a namespace",
-	Args: func(cmd *cobra.Command, args []string) error {
-		expectedArguments := 2
-		if len(args) < expectedArguments {
-			return errMissingParameter
-		}
-
-		return nil
-	},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.RenameNamespaceRequest{
-			OldName: args[0],
-			NewName: args[1],
-		}
-
-		response, err := client.RenameNamespace(ctx, request)
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf(
-					"Cannot rename namespace: %s",
-					status.Convert(err).Message(),
-				),
-				output,
-			)
-
-			return
-		}
-
-		SuccessOutput(response.Namespace, "Namespace renamed", output)
-	},
-}

cmd/headscale/cli/nodes.go

@@ -1,537 +1,509 @@
 package cli
 
 import (
+	"context"
 	"fmt"
-	"log"
+	"net/netip"
 	"strconv"
 	"strings"
 	"time"
 
-	survey "github.com/AlecAivazis/survey/v2"
-	"github.com/juanfont/headscale"
 	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/juanfont/headscale/hscontrol/util"
 	"github.com/pterm/pterm"
+	"github.com/samber/lo"
 	"github.com/spf13/cobra"
-	"google.golang.org/grpc/status"
+	"google.golang.org/protobuf/types/known/timestamppb"
 	"tailscale.com/types/key"
 )
 
 func init() {
 	rootCmd.AddCommand(nodeCmd)
-	listNodesCmd.Flags().StringP("namespace", "n", "", "Filter by namespace")
+	listNodesCmd.Flags().StringP("user", "u", "", "Filter by user")
 	nodeCmd.AddCommand(listNodesCmd)
 
-	registerNodeCmd.Flags().StringP("namespace", "n", "", "Namespace")
-	err := registerNodeCmd.MarkFlagRequired("namespace")
-	if err != nil {
-		log.Fatalf(err.Error())
-	}
+	listNodeRoutesCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
+	nodeCmd.AddCommand(listNodeRoutesCmd)
+
+	registerNodeCmd.Flags().StringP("user", "u", "", "User")
 	registerNodeCmd.Flags().StringP("key", "k", "", "Key")
-	err = registerNodeCmd.MarkFlagRequired("key")
-	if err != nil {
-		log.Fatalf(err.Error())
-	}
+	mustMarkRequired(registerNodeCmd, "user", "key")
 	nodeCmd.AddCommand(registerNodeCmd)
 
 	expireNodeCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
-	err = expireNodeCmd.MarkFlagRequired("identifier")
-	if err != nil {
-		log.Fatalf(err.Error())
-	}
+	expireNodeCmd.Flags().StringP("expiry", "e", "", "Set expire to (RFC3339 format, e.g. 2025-08-27T10:00:00Z), or leave empty to expire immediately.")
+	expireNodeCmd.Flags().BoolP("disable", "d", false, "Disable key expiry (node will never expire)")
+	mustMarkRequired(expireNodeCmd, "identifier")
 	nodeCmd.AddCommand(expireNodeCmd)
 
+	renameNodeCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
+	mustMarkRequired(renameNodeCmd, "identifier")
+	nodeCmd.AddCommand(renameNodeCmd)
+
 	deleteNodeCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
-	err = deleteNodeCmd.MarkFlagRequired("identifier")
-	if err != nil {
-		log.Fatalf(err.Error())
-	}
+	mustMarkRequired(deleteNodeCmd, "identifier")
 	nodeCmd.AddCommand(deleteNodeCmd)
 
-	shareMachineCmd.Flags().StringP("namespace", "n", "", "Namespace")
-	err = shareMachineCmd.MarkFlagRequired("namespace")
-	if err != nil {
-		log.Fatalf(err.Error())
-	}
-	shareMachineCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
-	err = shareMachineCmd.MarkFlagRequired("identifier")
-	if err != nil {
-		log.Fatalf(err.Error())
-	}
-	nodeCmd.AddCommand(shareMachineCmd)
+	tagCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
+	mustMarkRequired(tagCmd, "identifier")
+	tagCmd.Flags().StringSliceP("tags", "t", []string{}, "List of tags to add to the node")
+	nodeCmd.AddCommand(tagCmd)
 
-	unshareMachineCmd.Flags().StringP("namespace", "n", "", "Namespace")
-	err = unshareMachineCmd.MarkFlagRequired("namespace")
-	if err != nil {
-		log.Fatalf(err.Error())
-	}
-	unshareMachineCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
-	err = unshareMachineCmd.MarkFlagRequired("identifier")
-	if err != nil {
-		log.Fatalf(err.Error())
-	}
-	nodeCmd.AddCommand(unshareMachineCmd)
+	approveRoutesCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
+	mustMarkRequired(approveRoutesCmd, "identifier")
+	approveRoutesCmd.Flags().StringSliceP("routes", "r", []string{}, `List of routes that will be approved (comma-separated, e.g. "10.0.0.0/8,192.168.0.0/24" or empty string to remove all approved routes)`)
+	nodeCmd.AddCommand(approveRoutesCmd)
+
+	nodeCmd.AddCommand(backfillNodeIPsCmd)
 }
 
 var nodeCmd = &cobra.Command{
-	Use:   "nodes",
-	Short: "Manage the nodes of Headscale",
+	Use:     "nodes",
+	Short:   "Manage the nodes of Headscale",
+	Aliases: []string{"node"},
 }
 
 var registerNodeCmd = &cobra.Command{
-	Use:   "register",
-	Short: "Registers a machine to your network",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-		namespace, err := cmd.Flags().GetString("namespace")
+	Use:        "register",
+	Short:      "Registers a node to your network",
+	Deprecated: "use 'headscale auth register --auth-id <id> --user <user>' instead",
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		user, _ := cmd.Flags().GetString("user")
+		registrationID, _ := cmd.Flags().GetString("key")
+
+		request := &v1.RegisterNodeRequest{
+			Key:  registrationID,
+			User: user,
+		}
+
+		response, err := client.RegisterNode(ctx, request)
 		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error getting namespace: %s", err), output)
-
-			return
+			return fmt.Errorf("registering node: %w", err)
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
-
-		machineKey, err := cmd.Flags().GetString("key")
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting machine key from flag: %s", err),
-				output,
-			)
-
-			return
-		}
-
-		request := &v1.RegisterMachineRequest{
-			Key:       machineKey,
-			Namespace: namespace,
-		}
-
-		response, err := client.RegisterMachine(ctx, request)
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf(
-					"Cannot register machine: %s\n",
-					status.Convert(err).Message(),
-				),
-				output,
-			)
-
-			return
-		}
-
-		SuccessOutput(response.Machine, "Machine register", output)
-	},
+		return printOutput(
+			cmd,
+			response.GetNode(),
+			fmt.Sprintf("Node %s registered", response.GetNode().GetGivenName()))
+	}),
 }
 
 var listNodesCmd = &cobra.Command{
-	Use:   "list",
-	Short: "List nodes",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-		namespace, err := cmd.Flags().GetString("namespace")
+	Use:     "list",
+	Short:   "List nodes",
+	Aliases: []string{"ls", "show"},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		user, _ := cmd.Flags().GetString("user")
+
+		response, err := client.ListNodes(ctx, &v1.ListNodesRequest{User: user})
 		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error getting namespace: %s", err), output)
-
-			return
+			return fmt.Errorf("listing nodes: %w", err)
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
+		return printListOutput(cmd, response.GetNodes(), func() error {
+			tableData, err := nodesToPtables(user, response.GetNodes())
+			if err != nil {
+				return fmt.Errorf("converting to table: %w", err)
+			}
 
-		request := &v1.ListMachinesRequest{
-			Namespace: namespace,
-		}
+			return pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
+		})
+	}),
+}
 
-		response, err := client.ListMachines(ctx, request)
+var listNodeRoutesCmd = &cobra.Command{
+	Use:     "list-routes",
+	Short:   "List routes available on nodes",
+	Aliases: []string{"lsr", "routes"},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		identifier, _ := cmd.Flags().GetUint64("identifier")
+
+		response, err := client.ListNodes(ctx, &v1.ListNodesRequest{})
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot get nodes: %s", status.Convert(err).Message()),
-				output,
-			)
-
-			return
+			return fmt.Errorf("listing nodes: %w", err)
 		}
 
-		if output != "" {
-			SuccessOutput(response.Machines, "", output)
+		nodes := response.GetNodes()
+		if identifier != 0 {
+			for _, node := range response.GetNodes() {
+				if node.GetId() == identifier {
+					nodes = []*v1.Node{node}
 
-			return
+					break
+				}
+			}
 		}
 
-		tableData, err := nodesToPtables(namespace, response.Machines)
-		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error converting to table: %s", err), output)
+		nodes = lo.Filter(nodes, func(n *v1.Node, _ int) bool {
+			return (n.GetSubnetRoutes() != nil && len(n.GetSubnetRoutes()) > 0) || (n.GetApprovedRoutes() != nil && len(n.GetApprovedRoutes()) > 0) || (n.GetAvailableRoutes() != nil && len(n.GetAvailableRoutes()) > 0)
+		})
 
-			return
-		}
-
-		err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Failed to render pterm table: %s", err),
-				output,
-			)
-
-			return
-		}
-	},
+		return printListOutput(cmd, nodes, func() error {
+			return pterm.DefaultTable.WithHasHeader().WithData(nodeRoutesToPtables(nodes)).Render()
+		})
+	}),
 }
 
 var expireNodeCmd = &cobra.Command{
-	Use:     "expire",
-	Short:   "Expire (log out) a machine in your network",
-	Long:    "Expiring a node will keep the node in the database and force it to reauthenticate.",
-	Aliases: []string{"logout"},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
+	Use:   "expire",
+	Short: "Expire (log out) a node in your network",
+	Long: `Expiring a node will keep the node in the database and force it to reauthenticate.
 
-		identifier, err := cmd.Flags().GetUint64("identifier")
+Use --disable to disable key expiry (node will never expire).`,
+	Aliases: []string{"logout", "exp", "e"},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		identifier, _ := cmd.Flags().GetUint64("identifier")
+		disableExpiry, _ := cmd.Flags().GetBool("disable")
+
+		// Handle disable expiry - node will never expire.
+		if disableExpiry {
+			request := &v1.ExpireNodeRequest{
+				NodeId:        identifier,
+				DisableExpiry: true,
+			}
+
+			response, err := client.ExpireNode(ctx, request)
+			if err != nil {
+				return fmt.Errorf("disabling node expiry: %w", err)
+			}
+
+			return printOutput(cmd, response.GetNode(), "Node expiry disabled")
+		}
+
+		expiry, _ := cmd.Flags().GetString("expiry")
+
+		now := time.Now()
+
+		expiryTime := now
+		if expiry != "" {
+			var err error
+			expiryTime, err = time.Parse(time.RFC3339, expiry)
+			if err != nil {
+				return fmt.Errorf("parsing expiry time: %w", err)
+			}
+		}
+
+		request := &v1.ExpireNodeRequest{
+			NodeId: identifier,
+			Expiry: timestamppb.New(expiryTime),
+		}
+
+		response, err := client.ExpireNode(ctx, request)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error converting ID to integer: %s", err),
-				output,
-			)
-
-			return
+			return fmt.Errorf("expiring node: %w", err)
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.ExpireMachineRequest{
-			MachineId: identifier,
+		if now.Equal(expiryTime) || now.After(expiryTime) {
+			return printOutput(cmd, response.GetNode(), "Node expired")
 		}
 
-		response, err := client.ExpireMachine(ctx, request)
+		return printOutput(cmd, response.GetNode(), "Node expiration updated")
+	}),
+}
+
+var renameNodeCmd = &cobra.Command{
+	Use:   "rename NEW_NAME",
+	Short: "Renames a node in your network",
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		identifier, _ := cmd.Flags().GetUint64("identifier")
+
+		newName := ""
+		if len(args) > 0 {
+			newName = args[0]
+		}
+
+		request := &v1.RenameNodeRequest{
+			NodeId:  identifier,
+			NewName: newName,
+		}
+
+		response, err := client.RenameNode(ctx, request)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf(
-					"Cannot expire machine: %s\n",
-					status.Convert(err).Message(),
-				),
-				output,
-			)
-
-			return
+			return fmt.Errorf("renaming node: %w", err)
 		}
 
-		SuccessOutput(response.Machine, "Machine expired", output)
-	},
+		return printOutput(cmd, response.GetNode(), "Node renamed")
+	}),
 }
 
 var deleteNodeCmd = &cobra.Command{
-	Use:   "delete",
-	Short: "Delete a node",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
+	Use:     "delete",
+	Short:   "Delete a node",
+	Aliases: []string{"del"},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		identifier, _ := cmd.Flags().GetUint64("identifier")
 
-		identifier, err := cmd.Flags().GetUint64("identifier")
+		getRequest := &v1.GetNodeRequest{
+			NodeId: identifier,
+		}
+
+		getResponse, err := client.GetNode(ctx, getRequest)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error converting ID to integer: %s", err),
-				output,
-			)
-
-			return
+			return fmt.Errorf("getting node: %w", err)
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
-
-		getRequest := &v1.GetMachineRequest{
-			MachineId: identifier,
+		deleteRequest := &v1.DeleteNodeRequest{
+			NodeId: identifier,
 		}
 
-		getResponse, err := client.GetMachine(ctx, getRequest)
+		if !confirmAction(cmd, fmt.Sprintf(
+			"Do you want to remove the node %s?",
+			getResponse.GetNode().GetName(),
+		)) {
+			return printOutput(cmd, map[string]string{"Result": "Node not deleted"}, "Node not deleted")
+		}
+
+		_, err = client.DeleteNode(ctx, deleteRequest)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf(
-					"Error getting node node: %s",
-					status.Convert(err).Message(),
-				),
-				output,
-			)
-
-			return
+			return fmt.Errorf("deleting node: %w", err)
 		}
 
-		deleteRequest := &v1.DeleteMachineRequest{
-			MachineId: identifier,
-		}
-
-		confirm := false
-		force, _ := cmd.Flags().GetBool("force")
-		if !force {
-			prompt := &survey.Confirm{
-				Message: fmt.Sprintf(
-					"Do you want to remove the node %s?",
-					getResponse.GetMachine().Name,
-				),
-			}
-			err = survey.AskOne(prompt, &confirm)
-			if err != nil {
-				return
-			}
-		}
-
-		if confirm || force {
-			response, err := client.DeleteMachine(ctx, deleteRequest)
-			if output != "" {
-				SuccessOutput(response, "", output)
-
-				return
-			}
-			if err != nil {
-				ErrorOutput(
-					err,
-					fmt.Sprintf(
-						"Error deleting node: %s",
-						status.Convert(err).Message(),
-					),
-					output,
-				)
-
-				return
-			}
-			SuccessOutput(
-				map[string]string{"Result": "Node deleted"},
-				"Node deleted",
-				output,
-			)
-		} else {
-			SuccessOutput(map[string]string{"Result": "Node not deleted"}, "Node not deleted", output)
-		}
-	},
-}
-
-func sharingWorker(
-	cmd *cobra.Command,
-) (string, *v1.Machine, *v1.Namespace, error) {
-	output, _ := cmd.Flags().GetString("output")
-	namespaceStr, err := cmd.Flags().GetString("namespace")
-	if err != nil {
-		ErrorOutput(err, fmt.Sprintf("Error getting namespace: %s", err), output)
-
-		return "", nil, nil, err
-	}
-
-	ctx, client, conn, cancel := getHeadscaleCLIClient()
-	defer cancel()
-	defer conn.Close()
-
-	identifier, err := cmd.Flags().GetUint64("identifier")
-	if err != nil {
-		ErrorOutput(err, fmt.Sprintf("Error converting ID to integer: %s", err), output)
-
-		return "", nil, nil, err
-	}
-
-	machineRequest := &v1.GetMachineRequest{
-		MachineId: identifier,
-	}
-
-	machineResponse, err := client.GetMachine(ctx, machineRequest)
-	if err != nil {
-		ErrorOutput(
-			err,
-			fmt.Sprintf("Error getting node node: %s", status.Convert(err).Message()),
-			output,
+		return printOutput(
+			cmd,
+			map[string]string{"Result": "Node deleted"},
+			"Node deleted",
 		)
-
-		return "", nil, nil, err
-	}
-
-	namespaceRequest := &v1.GetNamespaceRequest{
-		Name: namespaceStr,
-	}
-
-	namespaceResponse, err := client.GetNamespace(ctx, namespaceRequest)
-	if err != nil {
-		ErrorOutput(
-			err,
-			fmt.Sprintf("Error getting node node: %s", status.Convert(err).Message()),
-			output,
-		)
-
-		return "", nil, nil, err
-	}
-
-	return output, machineResponse.GetMachine(), namespaceResponse.GetNamespace(), nil
+	}),
 }
 
-var shareMachineCmd = &cobra.Command{
-	Use:   "share",
-	Short: "Shares a node from the current namespace to the specified one",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, machine, namespace, err := sharingWorker(cmd)
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Failed to fetch namespace or machine: %s", err),
-				output,
-			)
+var backfillNodeIPsCmd = &cobra.Command{
+	Use:   "backfillips",
+	Short: "Backfill IPs missing from nodes",
+	Long: `
+Backfill IPs can be used to add/remove IPs from nodes
+based on the current configuration of Headscale.
 
-			return
+If there are nodes that does not have IPv4 or IPv6
+even if prefixes for both are configured in the config,
+this command can be used to assign IPs of the sort to
+all nodes that are missing.
+
+If you remove IPv4 or IPv6 prefixes from the config,
+it can be run to remove the IPs that should no longer
+be assigned to nodes.`,
+	RunE: func(cmd *cobra.Command, args []string) error {
+		if !confirmAction(cmd, "Are you sure that you want to assign/remove IPs to/from nodes?") {
+			return nil
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel, err := newHeadscaleCLIWithConfig()
+		if err != nil {
+			return fmt.Errorf("connecting to headscale: %w", err)
+		}
 		defer cancel()
 		defer conn.Close()
 
-		request := &v1.ShareMachineRequest{
-			MachineId: machine.Id,
-			Namespace: namespace.Name,
-		}
-
-		response, err := client.ShareMachine(ctx, request)
+		changes, err := client.BackfillNodeIPs(ctx, &v1.BackfillNodeIPsRequest{Confirmed: true})
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error sharing node: %s", status.Convert(err).Message()),
-				output,
-			)
-
-			return
+			return fmt.Errorf("backfilling IPs: %w", err)
 		}
 
-		SuccessOutput(response.Machine, "Node shared", output)
-	},
-}
-
-var unshareMachineCmd = &cobra.Command{
-	Use:   "unshare",
-	Short: "Unshares a node from the specified namespace",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, machine, namespace, err := sharingWorker(cmd)
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Failed to fetch namespace or machine: %s", err),
-				output,
-			)
-
-			return
-		}
-
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.UnshareMachineRequest{
-			MachineId: machine.Id,
-			Namespace: namespace.Name,
-		}
-
-		response, err := client.UnshareMachine(ctx, request)
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error unsharing node: %s", status.Convert(err).Message()),
-				output,
-			)
-
-			return
-		}
-
-		SuccessOutput(response.Machine, "Node unshared", output)
+		return printOutput(cmd, changes, "Node IPs backfilled successfully")
 	},
 }
 
 func nodesToPtables(
-	currentNamespace string,
-	machines []*v1.Machine,
+	currentUser string,
+	nodes []*v1.Node,
 ) (pterm.TableData, error) {
-	tableData := pterm.TableData{
-		{
-			"ID",
-			"Name",
-			"NodeKey",
-			"Namespace",
-			"IP addresses",
-			"Ephemeral",
-			"Last seen",
-			"Online",
-			"Expired",
-		},
+	tableHeader := []string{
+		"ID",
+		"Hostname",
+		"Name",
+		"MachineKey",
+		"NodeKey",
+		"User",
+		"Tags",
+		"IP addresses",
+		"Ephemeral",
+		"Last seen",
+		"Expiration",
+		"Connected",
+		"Expired",
 	}
+	tableData := pterm.TableData{tableHeader}
 
-	for _, machine := range machines {
+	for _, node := range nodes {
 		var ephemeral bool
-		if machine.PreAuthKey != nil && machine.PreAuthKey.Ephemeral {
+		if node.GetPreAuthKey() != nil && node.GetPreAuthKey().GetEphemeral() {
 			ephemeral = true
 		}
 
-		var lastSeen time.Time
-		var lastSeenTime string
-		if machine.LastSeen != nil {
-			lastSeen = machine.LastSeen.AsTime()
-			lastSeenTime = lastSeen.Format("2006-01-02 15:04:05")
+		var (
+			lastSeen     time.Time
+			lastSeenTime string
+		)
+
+		if node.GetLastSeen() != nil {
+			lastSeen = node.GetLastSeen().AsTime()
+			lastSeenTime = lastSeen.Format(HeadscaleDateTimeFormat)
 		}
 
-		var expiry time.Time
-		if machine.Expiry != nil {
-			expiry = machine.Expiry.AsTime()
+		var (
+			expiry     time.Time
+			expiryTime string
+		)
+
+		if node.GetExpiry() != nil {
+			expiry = node.GetExpiry().AsTime()
+			expiryTime = expiry.Format(HeadscaleDateTimeFormat)
+		} else {
+			expiryTime = "N/A"
+		}
+
+		var machineKey key.MachinePublic
+
+		err := machineKey.UnmarshalText(
+			[]byte(node.GetMachineKey()),
+		)
+		if err != nil {
+			machineKey = key.MachinePublic{}
 		}
 
 		var nodeKey key.NodePublic
-		err := nodeKey.UnmarshalText(
-			[]byte(headscale.NodePublicKeyEnsurePrefix(machine.NodeKey)),
+
+		err = nodeKey.UnmarshalText(
+			[]byte(node.GetNodeKey()),
 		)
 		if err != nil {
 			return nil, err
 		}
 
 		var online string
-		if lastSeen.After(
-			time.Now().Add(-5 * time.Minute),
-		) { // TODO: Find a better way to reliably show if online
+		if node.GetOnline() {
 			online = pterm.LightGreen("online")
 		} else {
 			online = pterm.LightRed("offline")
 		}
 
 		var expired string
-		if expiry.IsZero() || expiry.After(time.Now()) {
-			expired = pterm.LightGreen("no")
-		} else {
+		if node.GetExpiry() != nil && node.GetExpiry().AsTime().Before(time.Now()) {
 			expired = pterm.LightRed("yes")
+		} else {
+			expired = pterm.LightGreen("no")
 		}
 
-		var namespace string
-		if currentNamespace == "" || (currentNamespace == machine.Namespace.Name) {
-			namespace = pterm.LightMagenta(machine.Namespace.Name)
-		} else {
-			// Shared into this namespace
-			namespace = pterm.LightYellow(machine.Namespace.Name)
+		var tagsBuilder strings.Builder
+
+		for _, tag := range node.GetTags() {
+			tagsBuilder.WriteString("\n" + tag)
+		}
+
+		tags := strings.TrimLeft(tagsBuilder.String(), "\n")
+
+		var user string
+		if node.GetUser() != nil {
+			user = node.GetUser().GetName()
+		}
+
+		var ipBuilder strings.Builder
+		for _, addr := range node.GetIpAddresses() {
+			ip, err := netip.ParseAddr(addr)
+			if err == nil {
+				if ipBuilder.Len() > 0 {
+					ipBuilder.WriteString("\n")
+				}
+
+				ipBuilder.WriteString(ip.String())
+			}
+		}
+
+		ipAddresses := ipBuilder.String()
+
+		nodeData := []string{
+			strconv.FormatUint(node.GetId(), util.Base10),
+			node.GetName(),
+			node.GetGivenName(),
+			machineKey.ShortString(),
+			nodeKey.ShortString(),
+			user,
+			tags,
+			ipAddresses,
+			strconv.FormatBool(ephemeral),
+			lastSeenTime,
+			expiryTime,
+			online,
+			expired,
 		}
 		tableData = append(
 			tableData,
-			[]string{
-				strconv.FormatUint(machine.Id, headscale.Base10),
-				machine.Name,
-				nodeKey.ShortString(),
-				namespace,
-				strings.Join(machine.IpAddresses, ", "),
-				strconv.FormatBool(ephemeral),
-				lastSeenTime,
-				online,
-				expired,
-			},
+			nodeData,
 		)
 	}
 
 	return tableData, nil
 }
+
+func nodeRoutesToPtables(
+	nodes []*v1.Node,
+) pterm.TableData {
+	tableHeader := []string{
+		"ID",
+		"Hostname",
+		"Approved",
+		"Available",
+		"Serving (Primary)",
+	}
+	tableData := pterm.TableData{tableHeader}
+
+	for _, node := range nodes {
+		nodeData := []string{
+			strconv.FormatUint(node.GetId(), util.Base10),
+			node.GetGivenName(),
+			strings.Join(node.GetApprovedRoutes(), "\n"),
+			strings.Join(node.GetAvailableRoutes(), "\n"),
+			strings.Join(node.GetSubnetRoutes(), "\n"),
+		}
+		tableData = append(
+			tableData,
+			nodeData,
+		)
+	}
+
+	return tableData
+}
+
+var tagCmd = &cobra.Command{
+	Use:     "tag",
+	Short:   "Manage the tags of a node",
+	Aliases: []string{"tags", "t"},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		identifier, _ := cmd.Flags().GetUint64("identifier")
+		tagsToSet, _ := cmd.Flags().GetStringSlice("tags")
+
+		// Sending tags to node
+		request := &v1.SetTagsRequest{
+			NodeId: identifier,
+			Tags:   tagsToSet,
+		}
+
+		resp, err := client.SetTags(ctx, request)
+		if err != nil {
+			return fmt.Errorf("setting tags: %w", err)
+		}
+
+		return printOutput(cmd, resp.GetNode(), "Node updated")
+	}),
+}
+
+var approveRoutesCmd = &cobra.Command{
+	Use:   "approve-routes",
+	Short: "Manage the approved routes of a node",
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		identifier, _ := cmd.Flags().GetUint64("identifier")
+		routes, _ := cmd.Flags().GetStringSlice("routes")
+
+		// Sending routes to node
+		request := &v1.SetApprovedRoutesRequest{
+			NodeId: identifier,
+			Routes: routes,
+		}
+
+		resp, err := client.SetApprovedRoutes(ctx, request)
+		if err != nil {
+			return fmt.Errorf("setting approved routes: %w", err)
+		}
+
+		return printOutput(cmd, resp.GetNode(), "Node updated")
+	}),
+}

cmd/headscale/cli/policy.go

@@ -0,0 +1,189 @@
+package cli
+
+import (
+	"errors"
+	"fmt"
+	"os"
+
+	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/juanfont/headscale/hscontrol/db"
+	"github.com/juanfont/headscale/hscontrol/policy"
+	"github.com/juanfont/headscale/hscontrol/types"
+	"github.com/spf13/cobra"
+	"tailscale.com/types/views"
+)
+
+const (
+	bypassFlag = "bypass-grpc-and-access-database-directly" //nolint:gosec // not a credential
+)
+
+var errAborted = errors.New("command aborted by user")
+
+// bypassDatabase loads the server config and opens the database directly,
+// bypassing the gRPC server. The caller is responsible for closing the
+// returned database handle.
+func bypassDatabase() (*db.HSDatabase, error) {
+	cfg, err := types.LoadServerConfig()
+	if err != nil {
+		return nil, fmt.Errorf("loading config: %w", err)
+	}
+
+	d, err := db.NewHeadscaleDatabase(cfg, nil)
+	if err != nil {
+		return nil, fmt.Errorf("opening database: %w", err)
+	}
+
+	return d, nil
+}
+
+func init() {
+	rootCmd.AddCommand(policyCmd)
+
+	getPolicy.Flags().BoolP(bypassFlag, "", false, "Uses the headscale config to directly access the database, bypassing gRPC and does not require the server to be running")
+	policyCmd.AddCommand(getPolicy)
+
+	setPolicy.Flags().StringP("file", "f", "", "Path to a policy file in HuJSON format")
+	setPolicy.Flags().BoolP(bypassFlag, "", false, "Uses the headscale config to directly access the database, bypassing gRPC and does not require the server to be running")
+	mustMarkRequired(setPolicy, "file")
+	policyCmd.AddCommand(setPolicy)
+
+	checkPolicy.Flags().StringP("file", "f", "", "Path to a policy file in HuJSON format")
+	mustMarkRequired(checkPolicy, "file")
+	policyCmd.AddCommand(checkPolicy)
+}
+
+var policyCmd = &cobra.Command{
+	Use:   "policy",
+	Short: "Manage the Headscale ACL Policy",
+}
+
+var getPolicy = &cobra.Command{
+	Use:     "get",
+	Short:   "Print the current ACL Policy",
+	Aliases: []string{"show", "view", "fetch"},
+	RunE: func(cmd *cobra.Command, args []string) error {
+		var policyData string
+		if bypass, _ := cmd.Flags().GetBool(bypassFlag); bypass {
+			if !confirmAction(cmd, "DO NOT run this command if an instance of headscale is running, are you sure headscale is not running?") {
+				return errAborted
+			}
+
+			d, err := bypassDatabase()
+			if err != nil {
+				return err
+			}
+			defer d.Close()
+
+			pol, err := d.GetPolicy()
+			if err != nil {
+				return fmt.Errorf("loading policy from database: %w", err)
+			}
+
+			policyData = pol.Data
+		} else {
+			ctx, client, conn, cancel, err := newHeadscaleCLIWithConfig()
+			if err != nil {
+				return fmt.Errorf("connecting to headscale: %w", err)
+			}
+			defer cancel()
+			defer conn.Close()
+
+			response, err := client.GetPolicy(ctx, &v1.GetPolicyRequest{})
+			if err != nil {
+				return fmt.Errorf("loading ACL policy: %w", err)
+			}
+
+			policyData = response.GetPolicy()
+		}
+
+		// This does not pass output format as we don't support yaml, json or
+		// json-line output for this command. It is HuJSON already.
+		fmt.Println(policyData)
+
+		return nil
+	},
+}
+
+var setPolicy = &cobra.Command{
+	Use:   "set",
+	Short: "Updates the ACL Policy",
+	Long: `
+	Updates the existing ACL Policy with the provided policy. The policy must be a valid HuJSON object.
+	This command only works when the acl.policy_mode is set to "db", and the policy will be stored in the database.`,
+	Aliases: []string{"put", "update"},
+	RunE: func(cmd *cobra.Command, args []string) error {
+		policyPath, _ := cmd.Flags().GetString("file")
+
+		policyBytes, err := os.ReadFile(policyPath)
+		if err != nil {
+			return fmt.Errorf("reading policy file: %w", err)
+		}
+
+		if bypass, _ := cmd.Flags().GetBool(bypassFlag); bypass {
+			if !confirmAction(cmd, "DO NOT run this command if an instance of headscale is running, are you sure headscale is not running?") {
+				return errAborted
+			}
+
+			d, err := bypassDatabase()
+			if err != nil {
+				return err
+			}
+			defer d.Close()
+
+			users, err := d.ListUsers()
+			if err != nil {
+				return fmt.Errorf("loading users for policy validation: %w", err)
+			}
+
+			_, err = policy.NewPolicyManager(policyBytes, users, views.Slice[types.NodeView]{})
+			if err != nil {
+				return fmt.Errorf("parsing policy file: %w", err)
+			}
+
+			_, err = d.SetPolicy(string(policyBytes))
+			if err != nil {
+				return fmt.Errorf("setting ACL policy: %w", err)
+			}
+		} else {
+			request := &v1.SetPolicyRequest{Policy: string(policyBytes)}
+
+			ctx, client, conn, cancel, err := newHeadscaleCLIWithConfig()
+			if err != nil {
+				return fmt.Errorf("connecting to headscale: %w", err)
+			}
+			defer cancel()
+			defer conn.Close()
+
+			_, err = client.SetPolicy(ctx, request)
+			if err != nil {
+				return fmt.Errorf("setting ACL policy: %w", err)
+			}
+		}
+
+		fmt.Println("Policy updated.")
+
+		return nil
+	},
+}
+
+var checkPolicy = &cobra.Command{
+	Use:   "check",
+	Short: "Check the Policy file for errors",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		policyPath, _ := cmd.Flags().GetString("file")
+
+		policyBytes, err := os.ReadFile(policyPath)
+		if err != nil {
+			return fmt.Errorf("reading policy file: %w", err)
+		}
+
+		_, err = policy.NewPolicyManager(policyBytes, nil, views.Slice[types.NodeView]{})
+		if err != nil {
+			return fmt.Errorf("parsing policy file: %w", err)
+		}
+
+		fmt.Println("Policy is valid")
+
+		return nil
+	},
+}

cmd/headscale/cli/preauthkeys.go

@@ -1,215 +1,178 @@
 package cli
 
 import (
+	"context"
 	"fmt"
 	"strconv"
-	"time"
+	"strings"
 
 	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/juanfont/headscale/hscontrol/util"
 	"github.com/pterm/pterm"
-	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
-	"google.golang.org/protobuf/types/known/timestamppb"
 )
 
 const (
-	DefaultPreAuthKeyExpiry = 1 * time.Hour
+	DefaultPreAuthKeyExpiry = "1h"
 )
 
 func init() {
 	rootCmd.AddCommand(preauthkeysCmd)
-	preauthkeysCmd.PersistentFlags().StringP("namespace", "n", "", "Namespace")
-	err := preauthkeysCmd.MarkPersistentFlagRequired("namespace")
-	if err != nil {
-		log.Fatal().Err(err).Msg("")
-	}
 	preauthkeysCmd.AddCommand(listPreAuthKeys)
 	preauthkeysCmd.AddCommand(createPreAuthKeyCmd)
 	preauthkeysCmd.AddCommand(expirePreAuthKeyCmd)
+	preauthkeysCmd.AddCommand(deletePreAuthKeyCmd)
 	createPreAuthKeyCmd.PersistentFlags().
 		Bool("reusable", false, "Make the preauthkey reusable")
 	createPreAuthKeyCmd.PersistentFlags().
 		Bool("ephemeral", false, "Preauthkey for ephemeral nodes")
 	createPreAuthKeyCmd.Flags().
-		DurationP("expiration", "e", DefaultPreAuthKeyExpiry, "Human-readable expiration of the key (30m, 24h, 365d...)")
+		StringP("expiration", "e", DefaultPreAuthKeyExpiry, "Human-readable expiration of the key (e.g. 30m, 24h)")
+	createPreAuthKeyCmd.Flags().
+		StringSlice("tags", []string{}, "Tags to automatically assign to node")
+	createPreAuthKeyCmd.PersistentFlags().Uint64P("user", "u", 0, "User identifier (ID)")
+	expirePreAuthKeyCmd.PersistentFlags().Uint64P("id", "i", 0, "Authkey ID")
+	deletePreAuthKeyCmd.PersistentFlags().Uint64P("id", "i", 0, "Authkey ID")
 }
 
 var preauthkeysCmd = &cobra.Command{
-	Use:   "preauthkeys",
-	Short: "Handle the preauthkeys in Headscale",
+	Use:     "preauthkeys",
+	Short:   "Handle the preauthkeys in Headscale",
+	Aliases: []string{"preauthkey", "authkey", "pre"},
 }
 
 var listPreAuthKeys = &cobra.Command{
-	Use:   "list",
-	Short: "List the preauthkeys for this namespace",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		namespace, err := cmd.Flags().GetString("namespace")
+	Use:     "list",
+	Short:   "List all preauthkeys",
+	Aliases: []string{"ls", "show"},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		response, err := client.ListPreAuthKeys(ctx, &v1.ListPreAuthKeysRequest{})
 		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error getting namespace: %s", err), output)
-
-			return
+			return fmt.Errorf("listing preauthkeys: %w", err)
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.ListPreAuthKeysRequest{
-			Namespace: namespace,
-		}
-
-		response, err := client.ListPreAuthKeys(ctx, request)
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting the list of keys: %s", err),
-				output,
-			)
-
-			return
-		}
-
-		if output != "" {
-			SuccessOutput(response.PreAuthKeys, "", output)
-
-			return
-		}
-
-		tableData := pterm.TableData{
-			{"ID", "Key", "Reusable", "Ephemeral", "Used", "Expiration", "Created"},
-		}
-		for _, key := range response.PreAuthKeys {
-			expiration := "-"
-			if key.GetExpiration() != nil {
-				expiration = ColourTime(key.Expiration.AsTime())
+		return printListOutput(cmd, response.GetPreAuthKeys(), func() error {
+			tableData := pterm.TableData{
+				{
+					"ID",
+					"Key/Prefix",
+					"Reusable",
+					"Ephemeral",
+					"Used",
+					"Expiration",
+					"Created",
+					"Owner",
+				},
 			}
 
-			var reusable string
-			if key.GetEphemeral() {
-				reusable = "N/A"
-			} else {
-				reusable = fmt.Sprintf("%v", key.GetReusable())
+			for _, key := range response.GetPreAuthKeys() {
+				expiration := "-"
+				if key.GetExpiration() != nil {
+					expiration = ColourTime(key.GetExpiration().AsTime())
+				}
+
+				var owner string
+				if len(key.GetAclTags()) > 0 {
+					owner = strings.Join(key.GetAclTags(), "\n")
+				} else if key.GetUser() != nil {
+					owner = key.GetUser().GetName()
+				} else {
+					owner = "-"
+				}
+
+				tableData = append(tableData, []string{
+					strconv.FormatUint(key.GetId(), util.Base10),
+					key.GetKey(),
+					strconv.FormatBool(key.GetReusable()),
+					strconv.FormatBool(key.GetEphemeral()),
+					strconv.FormatBool(key.GetUsed()),
+					expiration,
+					key.GetCreatedAt().AsTime().Format(HeadscaleDateTimeFormat),
+					owner,
+				})
 			}
 
-			tableData = append(tableData, []string{
-				key.GetId(),
-				key.GetKey(),
-				reusable,
-				strconv.FormatBool(key.GetEphemeral()),
-				strconv.FormatBool(key.GetUsed()),
-				expiration,
-				key.GetCreatedAt().AsTime().Format("2006-01-02 15:04:05"),
-			})
-
-		}
-		err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Failed to render pterm table: %s", err),
-				output,
-			)
-
-			return
-		}
-	},
+			return pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
+		})
+	}),
 }
 
 var createPreAuthKeyCmd = &cobra.Command{
-	Use:   "create",
-	Short: "Creates a new preauthkey in the specified namespace",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		namespace, err := cmd.Flags().GetString("namespace")
-		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error getting namespace: %s", err), output)
-
-			return
-		}
-
+	Use:     "create",
+	Short:   "Creates a new preauthkey",
+	Aliases: []string{"c", "new"},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		user, _ := cmd.Flags().GetUint64("user")
 		reusable, _ := cmd.Flags().GetBool("reusable")
 		ephemeral, _ := cmd.Flags().GetBool("ephemeral")
+		tags, _ := cmd.Flags().GetStringSlice("tags")
 
-		log.Trace().
-			Bool("reusable", reusable).
-			Bool("ephemeral", ephemeral).
-			Str("namespace", namespace).
-			Msg("Preparing to create preauthkey")
-
-		request := &v1.CreatePreAuthKeyRequest{
-			Namespace: namespace,
-			Reusable:  reusable,
-			Ephemeral: ephemeral,
+		expiration, err := expirationFromFlag(cmd)
+		if err != nil {
+			return err
 		}
 
-		duration, _ := cmd.Flags().GetDuration("expiration")
-		expiration := time.Now().UTC().Add(duration)
-
-		log.Trace().Dur("expiration", duration).Msg("expiration has been set")
-
-		request.Expiration = timestamppb.New(expiration)
-
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
+		request := &v1.CreatePreAuthKeyRequest{
+			User:       user,
+			Reusable:   reusable,
+			Ephemeral:  ephemeral,
+			AclTags:    tags,
+			Expiration: expiration,
+		}
 
 		response, err := client.CreatePreAuthKey(ctx, request)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot create Pre Auth Key: %s\n", err),
-				output,
-			)
-
-			return
+			return fmt.Errorf("creating preauthkey: %w", err)
 		}
 
-		SuccessOutput(response.PreAuthKey, response.PreAuthKey.Key, output)
-	},
+		return printOutput(cmd, response.GetPreAuthKey(), response.GetPreAuthKey().GetKey())
+	}),
 }
 
 var expirePreAuthKeyCmd = &cobra.Command{
-	Use:   "expire KEY",
-	Short: "Expire a preauthkey",
-	Args: func(cmd *cobra.Command, args []string) error {
-		if len(args) < 1 {
-			return errMissingParameter
+	Use:     "expire",
+	Short:   "Expire a preauthkey",
+	Aliases: []string{"revoke", "exp", "e"},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		id, _ := cmd.Flags().GetUint64("id")
+
+		if id == 0 {
+			return fmt.Errorf("missing --id parameter: %w", errMissingParameter)
 		}
 
-		return nil
-	},
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-		namespace, err := cmd.Flags().GetString("namespace")
-		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error getting namespace: %s", err), output)
-
-			return
-		}
-
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
-
 		request := &v1.ExpirePreAuthKeyRequest{
-			Namespace: namespace,
-			Key:       args[0],
+			Id: id,
 		}
 
 		response, err := client.ExpirePreAuthKey(ctx, request)
 		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot expire Pre Auth Key: %s\n", err),
-				output,
-			)
-
-			return
+			return fmt.Errorf("expiring preauthkey: %w", err)
 		}
 
-		SuccessOutput(response, "Key expired", output)
-	},
+		return printOutput(cmd, response, "Key expired")
+	}),
+}
+
+var deletePreAuthKeyCmd = &cobra.Command{
+	Use:     "delete",
+	Short:   "Delete a preauthkey",
+	Aliases: []string{"del", "rm", "d"},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		id, _ := cmd.Flags().GetUint64("id")
+
+		if id == 0 {
+			return fmt.Errorf("missing --id parameter: %w", errMissingParameter)
+		}
+
+		request := &v1.DeletePreAuthKeyRequest{
+			Id: id,
+		}
+
+		response, err := client.DeletePreAuthKey(ctx, request)
+		if err != nil {
+			return fmt.Errorf("deleting preauthkey: %w", err)
+		}
+
+		return printOutput(cmd, response, "Key deleted")
+	}),
 }

cmd/headscale/cli/pterm_style.go

@@ -7,7 +7,7 @@ import (
 )
 
 func ColourTime(date time.Time) string {
-	dateStr := date.Format("2006-01-02 15:04:05")
+	dateStr := date.Format(HeadscaleDateTimeFormat)
 
 	if date.After(time.Now()) {
 		dateStr = pterm.LightGreen(dateStr)

cmd/headscale/cli/root.go

@@ -1,17 +1,139 @@
 package cli
 
 import (
-	"fmt"
 	"os"
+	"runtime"
+	"slices"
+	"strings"
 
+	"github.com/juanfont/headscale/hscontrol/types"
+	"github.com/rs/zerolog"
+	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
+	"github.com/tcnksm/go-latest"
 )
 
+var cfgFile string = ""
+
 func init() {
+	if len(os.Args) > 1 &&
+		(os.Args[1] == "version" || os.Args[1] == "mockoidc" || os.Args[1] == "completion") {
+		return
+	}
+
+	if slices.Contains(os.Args, "policy") && slices.Contains(os.Args, "check") {
+		zerolog.SetGlobalLevel(zerolog.Disabled)
+		return
+	}
+
+	cobra.OnInitialize(initConfig)
+	rootCmd.PersistentFlags().
+		StringVarP(&cfgFile, "config", "c", "", "config file (default is /etc/headscale/config.yaml)")
 	rootCmd.PersistentFlags().
 		StringP("output", "o", "", "Output format. Empty for human-readable, 'json', 'json-line' or 'yaml'")
 	rootCmd.PersistentFlags().
 		Bool("force", false, "Disable prompts and forces the execution")
+
+	// Re-enable usage output only for flag-parsing errors; runtime errors
+	// from RunE should never dump usage text.
+	rootCmd.SetFlagErrorFunc(func(cmd *cobra.Command, err error) error {
+		cmd.SilenceUsage = false
+
+		return err
+	})
+}
+
+func initConfig() {
+	if cfgFile == "" {
+		cfgFile = os.Getenv("HEADSCALE_CONFIG")
+	}
+
+	if cfgFile != "" {
+		err := types.LoadConfig(cfgFile, true)
+		if err != nil {
+			log.Fatal().Caller().Err(err).Msgf("error loading config file %s", cfgFile)
+		}
+	} else {
+		err := types.LoadConfig("", false)
+		if err != nil {
+			log.Fatal().Caller().Err(err).Msgf("error loading config")
+		}
+	}
+
+	machineOutput := hasMachineOutputFlag()
+
+	// If the user has requested a "node" readable format,
+	// then disable login so the output remains valid.
+	if machineOutput {
+		zerolog.SetGlobalLevel(zerolog.Disabled)
+	}
+
+	logFormat := viper.GetString("log.format")
+	if logFormat == types.JSONLogFormat {
+		log.Logger = log.Output(os.Stdout)
+	}
+
+	disableUpdateCheck := viper.GetBool("disable_check_updates")
+	if !disableUpdateCheck && !machineOutput {
+		versionInfo := types.GetVersionInfo()
+		if (runtime.GOOS == "linux" || runtime.GOOS == "darwin") &&
+			!versionInfo.Dirty {
+			githubTag := &latest.GithubTag{
+				Owner:         "juanfont",
+				Repository:    "headscale",
+				TagFilterFunc: filterPreReleasesIfStable(func() string { return versionInfo.Version }),
+			}
+
+			res, err := latest.Check(githubTag, versionInfo.Version)
+			if err == nil && res.Outdated {
+				//nolint
+				log.Warn().Msgf(
+					"An updated version of Headscale has been found (%s vs. your current %s). Check it out https://github.com/juanfont/headscale/releases\n",
+					res.Current,
+					versionInfo.Version,
+				)
+			}
+		}
+	}
+}
+
+var prereleases = []string{"alpha", "beta", "rc", "dev"}
+
+func isPreReleaseVersion(version string) bool {
+	for _, unstable := range prereleases {
+		if strings.Contains(version, unstable) {
+			return true
+		}
+	}
+
+	return false
+}
+
+// filterPreReleasesIfStable returns a function that filters out
+// pre-release tags if the current version is stable.
+// If the current version is a pre-release, it does not filter anything.
+// versionFunc is a function that returns the current version string, it is
+// a func for testability.
+func filterPreReleasesIfStable(versionFunc func() string) func(string) bool {
+	return func(tag string) bool {
+		version := versionFunc()
+
+		// If we are on a pre-release version, then we do not filter anything
+		// as we want to recommend the user the latest pre-release.
+		if isPreReleaseVersion(version) {
+			return false
+		}
+
+		// If we are on a stable release, filter out pre-releases.
+		for _, ignore := range prereleases {
+			if strings.Contains(tag, ignore) {
+				return true
+			}
+		}
+
+		return false
+	}
 }
 
 var rootCmd = &cobra.Command{
@@ -21,11 +143,15 @@ var rootCmd = &cobra.Command{
 headscale is an open source implementation of the Tailscale control server
 
 https://github.com/juanfont/headscale`,
+	SilenceErrors: true,
+	SilenceUsage:  true,
 }
 
 func Execute() {
-	if err := rootCmd.Execute(); err != nil {
-		fmt.Fprintln(os.Stderr, err)
+	cmd, err := rootCmd.ExecuteC()
+	if err != nil {
+		outputFormat, _ := cmd.Flags().GetString("output")
+		printError(err, outputFormat)
 		os.Exit(1)
 	}
 }

cmd/headscale/cli/root_test.go

@@ -0,0 +1,293 @@
+package cli
+
+import (
+	"testing"
+)
+
+func TestFilterPreReleasesIfStable(t *testing.T) {
+	tests := []struct {
+		name           string
+		currentVersion string
+		tag            string
+		expectedFilter bool
+		description    string
+	}{
+		{
+			name:           "stable version filters alpha tag",
+			currentVersion: "0.23.0",
+			tag:            "v0.24.0-alpha.1",
+			expectedFilter: true,
+			description:    "When on stable release, alpha tags should be filtered",
+		},
+		{
+			name:           "stable version filters beta tag",
+			currentVersion: "0.23.0",
+			tag:            "v0.24.0-beta.2",
+			expectedFilter: true,
+			description:    "When on stable release, beta tags should be filtered",
+		},
+		{
+			name:           "stable version filters rc tag",
+			currentVersion: "0.23.0",
+			tag:            "v0.24.0-rc.1",
+			expectedFilter: true,
+			description:    "When on stable release, rc tags should be filtered",
+		},
+		{
+			name:           "stable version allows stable tag",
+			currentVersion: "0.23.0",
+			tag:            "v0.24.0",
+			expectedFilter: false,
+			description:    "When on stable release, stable tags should not be filtered",
+		},
+		{
+			name:           "alpha version allows alpha tag",
+			currentVersion: "0.23.0-alpha.1",
+			tag:            "v0.24.0-alpha.2",
+			expectedFilter: false,
+			description:    "When on alpha release, alpha tags should not be filtered",
+		},
+		{
+			name:           "alpha version allows beta tag",
+			currentVersion: "0.23.0-alpha.1",
+			tag:            "v0.24.0-beta.1",
+			expectedFilter: false,
+			description:    "When on alpha release, beta tags should not be filtered",
+		},
+		{
+			name:           "alpha version allows rc tag",
+			currentVersion: "0.23.0-alpha.1",
+			tag:            "v0.24.0-rc.1",
+			expectedFilter: false,
+			description:    "When on alpha release, rc tags should not be filtered",
+		},
+		{
+			name:           "alpha version allows stable tag",
+			currentVersion: "0.23.0-alpha.1",
+			tag:            "v0.24.0",
+			expectedFilter: false,
+			description:    "When on alpha release, stable tags should not be filtered",
+		},
+		{
+			name:           "beta version allows alpha tag",
+			currentVersion: "0.23.0-beta.1",
+			tag:            "v0.24.0-alpha.1",
+			expectedFilter: false,
+			description:    "When on beta release, alpha tags should not be filtered",
+		},
+		{
+			name:           "beta version allows beta tag",
+			currentVersion: "0.23.0-beta.2",
+			tag:            "v0.24.0-beta.3",
+			expectedFilter: false,
+			description:    "When on beta release, beta tags should not be filtered",
+		},
+		{
+			name:           "beta version allows rc tag",
+			currentVersion: "0.23.0-beta.1",
+			tag:            "v0.24.0-rc.1",
+			expectedFilter: false,
+			description:    "When on beta release, rc tags should not be filtered",
+		},
+		{
+			name:           "beta version allows stable tag",
+			currentVersion: "0.23.0-beta.1",
+			tag:            "v0.24.0",
+			expectedFilter: false,
+			description:    "When on beta release, stable tags should not be filtered",
+		},
+		{
+			name:           "rc version allows alpha tag",
+			currentVersion: "0.23.0-rc.1",
+			tag:            "v0.24.0-alpha.1",
+			expectedFilter: false,
+			description:    "When on rc release, alpha tags should not be filtered",
+		},
+		{
+			name:           "rc version allows beta tag",
+			currentVersion: "0.23.0-rc.1",
+			tag:            "v0.24.0-beta.1",
+			expectedFilter: false,
+			description:    "When on rc release, beta tags should not be filtered",
+		},
+		{
+			name:           "rc version allows rc tag",
+			currentVersion: "0.23.0-rc.2",
+			tag:            "v0.24.0-rc.3",
+			expectedFilter: false,
+			description:    "When on rc release, rc tags should not be filtered",
+		},
+		{
+			name:           "rc version allows stable tag",
+			currentVersion: "0.23.0-rc.1",
+			tag:            "v0.24.0",
+			expectedFilter: false,
+			description:    "When on rc release, stable tags should not be filtered",
+		},
+		{
+			name:           "stable version with patch filters alpha",
+			currentVersion: "0.23.1",
+			tag:            "v0.24.0-alpha.1",
+			expectedFilter: true,
+			description:    "Stable version with patch number should filter alpha tags",
+		},
+		{
+			name:           "stable version with patch allows stable",
+			currentVersion: "0.23.1",
+			tag:            "v0.24.0",
+			expectedFilter: false,
+			description:    "Stable version with patch number should allow stable tags",
+		},
+		{
+			name:           "tag with alpha substring in version number",
+			currentVersion: "0.23.0",
+			tag:            "v1.0.0-alpha.1",
+			expectedFilter: true,
+			description:    "Tags with alpha in version string should be filtered on stable",
+		},
+		{
+			name:           "tag with beta substring in version number",
+			currentVersion: "0.23.0",
+			tag:            "v1.0.0-beta.1",
+			expectedFilter: true,
+			description:    "Tags with beta in version string should be filtered on stable",
+		},
+		{
+			name:           "tag with rc substring in version number",
+			currentVersion: "0.23.0",
+			tag:            "v1.0.0-rc.1",
+			expectedFilter: true,
+			description:    "Tags with rc in version string should be filtered on stable",
+		},
+		{
+			name:           "empty tag on stable version",
+			currentVersion: "0.23.0",
+			tag:            "",
+			expectedFilter: false,
+			description:    "Empty tags should not be filtered",
+		},
+		{
+			name:           "dev version allows all tags",
+			currentVersion: "0.23.0-dev",
+			tag:            "v0.24.0-alpha.1",
+			expectedFilter: false,
+			description:    "Dev versions should not filter any tags (pre-release allows all)",
+		},
+		{
+			name:           "stable version filters dev tag",
+			currentVersion: "0.23.0",
+			tag:            "v0.24.0-dev",
+			expectedFilter: true,
+			description:    "When on stable release, dev tags should be filtered",
+		},
+		{
+			name:           "dev version allows dev tag",
+			currentVersion: "0.23.0-dev",
+			tag:            "v0.24.0-dev.1",
+			expectedFilter: false,
+			description:    "When on dev release, dev tags should not be filtered",
+		},
+		{
+			name:           "dev version allows stable tag",
+			currentVersion: "0.23.0-dev",
+			tag:            "v0.24.0",
+			expectedFilter: false,
+			description:    "When on dev release, stable tags should not be filtered",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := filterPreReleasesIfStable(func() string { return tt.currentVersion })(tt.tag)
+			if result != tt.expectedFilter {
+				t.Errorf("%s: got %v, want %v\nDescription: %s\nCurrent version: %s, Tag: %s",
+					tt.name,
+					result,
+					tt.expectedFilter,
+					tt.description,
+					tt.currentVersion,
+					tt.tag,
+				)
+			}
+		})
+	}
+}
+
+func TestIsPreReleaseVersion(t *testing.T) {
+	tests := []struct {
+		name        string
+		version     string
+		expected    bool
+		description string
+	}{
+		{
+			name:        "stable version",
+			version:     "0.23.0",
+			expected:    false,
+			description: "Stable version should not be pre-release",
+		},
+		{
+			name:        "alpha version",
+			version:     "0.23.0-alpha.1",
+			expected:    true,
+			description: "Alpha version should be pre-release",
+		},
+		{
+			name:        "beta version",
+			version:     "0.23.0-beta.1",
+			expected:    true,
+			description: "Beta version should be pre-release",
+		},
+		{
+			name:        "rc version",
+			version:     "0.23.0-rc.1",
+			expected:    true,
+			description: "RC version should be pre-release",
+		},
+		{
+			name:        "version with alpha substring",
+			version:     "0.23.0-alphabetical",
+			expected:    true,
+			description: "Version containing 'alpha' should be pre-release",
+		},
+		{
+			name:        "version with beta substring",
+			version:     "0.23.0-betamax",
+			expected:    true,
+			description: "Version containing 'beta' should be pre-release",
+		},
+		{
+			name:        "dev version",
+			version:     "0.23.0-dev",
+			expected:    true,
+			description: "Dev version should be pre-release",
+		},
+		{
+			name:        "empty version",
+			version:     "",
+			expected:    false,
+			description: "Empty version should not be pre-release",
+		},
+		{
+			name:        "version with patch number",
+			version:     "0.23.1",
+			expected:    false,
+			description: "Stable version with patch should not be pre-release",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := isPreReleaseVersion(tt.version)
+			if result != tt.expected {
+				t.Errorf("%s: got %v, want %v\nDescription: %s\nVersion: %s",
+					tt.name,
+					result,
+					tt.expected,
+					tt.description,
+					tt.version,
+				)
+			}
+		})
+	}
+}

cmd/headscale/cli/routes.go

@@ -1,207 +0,0 @@
-package cli
-
-import (
-	"fmt"
-	"log"
-	"strconv"
-
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
-	"github.com/pterm/pterm"
-	"github.com/spf13/cobra"
-	"google.golang.org/grpc/status"
-)
-
-func init() {
-	rootCmd.AddCommand(routesCmd)
-
-	listRoutesCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
-	err := listRoutesCmd.MarkFlagRequired("identifier")
-	if err != nil {
-		log.Fatalf(err.Error())
-	}
-	routesCmd.AddCommand(listRoutesCmd)
-
-	enableRouteCmd.Flags().
-		StringSliceP("route", "r", []string{}, "List (or repeated flags) of routes to enable")
-	enableRouteCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
-	err = enableRouteCmd.MarkFlagRequired("identifier")
-	if err != nil {
-		log.Fatalf(err.Error())
-	}
-
-	routesCmd.AddCommand(enableRouteCmd)
-
-	nodeCmd.AddCommand(routesCmd)
-}
-
-var routesCmd = &cobra.Command{
-	Use:   "routes",
-	Short: "Manage the routes of Headscale",
-}
-
-var listRoutesCmd = &cobra.Command{
-	Use:   "list",
-	Short: "List routes advertised and enabled by a given node",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		machineID, err := cmd.Flags().GetUint64("identifier")
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting machine id from flag: %s", err),
-				output,
-			)
-
-			return
-		}
-
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.GetMachineRouteRequest{
-			MachineId: machineID,
-		}
-
-		response, err := client.GetMachineRoute(ctx, request)
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot get nodes: %s", status.Convert(err).Message()),
-				output,
-			)
-
-			return
-		}
-
-		if output != "" {
-			SuccessOutput(response.Routes, "", output)
-
-			return
-		}
-
-		tableData := routesToPtables(response.Routes)
-		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error converting to table: %s", err), output)
-
-			return
-		}
-
-		err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Failed to render pterm table: %s", err),
-				output,
-			)
-
-			return
-		}
-	},
-}
-
-var enableRouteCmd = &cobra.Command{
-	Use:   "enable",
-	Short: "Set the enabled routes for a given node",
-	Long: `This command will take a list of routes that will _replace_ 
-the current set of routes on a given node.
-If you would like to disable a route, simply run the command again, but 
-omit the route you do not want to enable.
-	`,
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		machineID, err := cmd.Flags().GetUint64("identifier")
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting machine id from flag: %s", err),
-				output,
-			)
-
-			return
-		}
-
-		routes, err := cmd.Flags().GetStringSlice("route")
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Error getting routes from flag: %s", err),
-				output,
-			)
-
-			return
-		}
-
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
-		defer cancel()
-		defer conn.Close()
-
-		request := &v1.EnableMachineRoutesRequest{
-			MachineId: machineID,
-			Routes:    routes,
-		}
-
-		response, err := client.EnableMachineRoutes(ctx, request)
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf(
-					"Cannot register machine: %s\n",
-					status.Convert(err).Message(),
-				),
-				output,
-			)
-
-			return
-		}
-
-		if output != "" {
-			SuccessOutput(response.Routes, "", output)
-
-			return
-		}
-
-		tableData := routesToPtables(response.Routes)
-		if err != nil {
-			ErrorOutput(err, fmt.Sprintf("Error converting to table: %s", err), output)
-
-			return
-		}
-
-		err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Failed to render pterm table: %s", err),
-				output,
-			)
-
-			return
-		}
-	},
-}
-
-// routesToPtables converts the list of routes to a nice table.
-func routesToPtables(routes *v1.Routes) pterm.TableData {
-	tableData := pterm.TableData{{"Route", "Enabled"}}
-
-	for _, route := range routes.GetAdvertisedRoutes() {
-		enabled := isStringInSlice(routes.EnabledRoutes, route)
-
-		tableData = append(tableData, []string{route, strconv.FormatBool(enabled)})
-	}
-
-	return tableData
-}
-
-func isStringInSlice(strs []string, s string) bool {
-	for _, s2 := range strs {
-		if s == s2 {
-			return true
-		}
-	}
-
-	return false
-}

cmd/headscale/cli/serve.go

@@ -0,0 +1,37 @@
+package cli
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+
+	"github.com/spf13/cobra"
+	"github.com/tailscale/squibble"
+)
+
+func init() {
+	rootCmd.AddCommand(serveCmd)
+}
+
+var serveCmd = &cobra.Command{
+	Use:   "serve",
+	Short: "Launches the headscale server",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		app, err := newHeadscaleServerWithConfig()
+		if err != nil {
+			if squibbleErr, ok := errors.AsType[squibble.ValidationError](err); ok {
+				fmt.Printf("SQLite schema failed to validate:\n")
+				fmt.Println(squibbleErr.Diff)
+			}
+
+			return fmt.Errorf("initializing: %w", err)
+		}
+
+		err = app.Serve()
+		if err != nil && !errors.Is(err, http.ErrServerClosed) {
+			return fmt.Errorf("headscale ran into an error and had to shut down: %w", err)
+		}
+
+		return nil
+	},
+}

cmd/headscale/cli/server.go

@@ -1,30 +0,0 @@
-package cli
-
-import (
-	"log"
-
-	"github.com/spf13/cobra"
-)
-
-func init() {
-	rootCmd.AddCommand(serveCmd)
-}
-
-var serveCmd = &cobra.Command{
-	Use:   "serve",
-	Short: "Launches the headscale server",
-	Args: func(cmd *cobra.Command, args []string) error {
-		return nil
-	},
-	Run: func(cmd *cobra.Command, args []string) {
-		h, err := getHeadscaleApp()
-		if err != nil {
-			log.Fatalf("Error initializing: %s", err)
-		}
-
-		err = h.Serve()
-		if err != nil {
-			log.Fatalf("Error initializing: %s", err)
-		}
-	},
-}

cmd/headscale/cli/users.go

@@ -0,0 +1,243 @@
+package cli
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/url"
+	"strconv"
+
+	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/juanfont/headscale/hscontrol/util"
+	"github.com/juanfont/headscale/hscontrol/util/zlog/zf"
+	"github.com/pterm/pterm"
+	"github.com/rs/zerolog/log"
+	"github.com/spf13/cobra"
+)
+
+// CLI user errors.
+var (
+	errFlagRequired       = errors.New("--name or --identifier flag is required")
+	errMultipleUsersMatch = errors.New("multiple users match query, specify an ID")
+)
+
+func usernameAndIDFlag(cmd *cobra.Command) {
+	cmd.Flags().Int64P("identifier", "i", -1, "User identifier (ID)")
+	cmd.Flags().StringP("name", "n", "", "Username")
+}
+
+// usernameAndIDFromFlag returns the username and ID from the flags of the command.
+func usernameAndIDFromFlag(cmd *cobra.Command) (uint64, string, error) {
+	username, _ := cmd.Flags().GetString("name")
+
+	identifier, _ := cmd.Flags().GetInt64("identifier")
+	if username == "" && identifier < 0 {
+		return 0, "", errFlagRequired
+	}
+
+	// Normalise unset/negative identifiers to 0 so the uint64
+	// conversion does not produce a bogus large value.
+	if identifier < 0 {
+		identifier = 0
+	}
+
+	return uint64(identifier), username, nil //nolint:gosec // identifier is clamped to >= 0 above
+}
+
+func init() {
+	rootCmd.AddCommand(userCmd)
+	userCmd.AddCommand(createUserCmd)
+	createUserCmd.Flags().StringP("display-name", "d", "", "Display name")
+	createUserCmd.Flags().StringP("email", "e", "", "Email")
+	createUserCmd.Flags().StringP("picture-url", "p", "", "Profile picture URL")
+	userCmd.AddCommand(listUsersCmd)
+	usernameAndIDFlag(listUsersCmd)
+	listUsersCmd.Flags().StringP("email", "e", "", "Email")
+	userCmd.AddCommand(destroyUserCmd)
+	usernameAndIDFlag(destroyUserCmd)
+	userCmd.AddCommand(renameUserCmd)
+	usernameAndIDFlag(renameUserCmd)
+	renameUserCmd.Flags().StringP("new-name", "r", "", "New username")
+	mustMarkRequired(renameUserCmd, "new-name")
+}
+
+var userCmd = &cobra.Command{
+	Use:     "users",
+	Short:   "Manage the users of Headscale",
+	Aliases: []string{"user"},
+}
+
+var createUserCmd = &cobra.Command{
+	Use:     "create NAME",
+	Short:   "Creates a new user",
+	Aliases: []string{"c", "new"},
+	Args: func(cmd *cobra.Command, args []string) error {
+		if len(args) < 1 {
+			return errMissingParameter
+		}
+
+		return nil
+	},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		userName := args[0]
+
+		log.Trace().Interface(zf.Client, client).Msg("obtained gRPC client")
+
+		request := &v1.CreateUserRequest{Name: userName}
+
+		if displayName, _ := cmd.Flags().GetString("display-name"); displayName != "" {
+			request.DisplayName = displayName
+		}
+
+		if email, _ := cmd.Flags().GetString("email"); email != "" {
+			request.Email = email
+		}
+
+		if pictureURL, _ := cmd.Flags().GetString("picture-url"); pictureURL != "" {
+			if _, err := url.Parse(pictureURL); err != nil { //nolint:noinlineerr
+				return fmt.Errorf("invalid picture URL: %w", err)
+			}
+
+			request.PictureUrl = pictureURL
+		}
+
+		log.Trace().Interface(zf.Request, request).Msg("sending CreateUser request")
+
+		response, err := client.CreateUser(ctx, request)
+		if err != nil {
+			return fmt.Errorf("creating user: %w", err)
+		}
+
+		return printOutput(cmd, response.GetUser(), "User created")
+	}),
+}
+
+var destroyUserCmd = &cobra.Command{
+	Use:     "destroy --identifier ID or --name NAME",
+	Short:   "Destroys a user",
+	Aliases: []string{"delete"},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		id, username, err := usernameAndIDFromFlag(cmd)
+		if err != nil {
+			return err
+		}
+
+		request := &v1.ListUsersRequest{
+			Name: username,
+			Id:   id,
+		}
+
+		users, err := client.ListUsers(ctx, request)
+		if err != nil {
+			return fmt.Errorf("listing users: %w", err)
+		}
+
+		if len(users.GetUsers()) != 1 {
+			return errMultipleUsersMatch
+		}
+
+		user := users.GetUsers()[0]
+
+		if !confirmAction(cmd, fmt.Sprintf(
+			"Do you want to remove the user %q (%d) and any associated preauthkeys?",
+			user.GetName(), user.GetId(),
+		)) {
+			return printOutput(cmd, map[string]string{"Result": "User not destroyed"}, "User not destroyed")
+		}
+
+		deleteRequest := &v1.DeleteUserRequest{Id: user.GetId()}
+
+		response, err := client.DeleteUser(ctx, deleteRequest)
+		if err != nil {
+			return fmt.Errorf("destroying user: %w", err)
+		}
+
+		return printOutput(cmd, response, "User destroyed")
+	}),
+}
+
+var listUsersCmd = &cobra.Command{
+	Use:     "list",
+	Short:   "List all the users",
+	Aliases: []string{"ls", "show"},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		request := &v1.ListUsersRequest{}
+
+		id, _ := cmd.Flags().GetInt64("identifier")
+		username, _ := cmd.Flags().GetString("name")
+		email, _ := cmd.Flags().GetString("email")
+
+		// filter by one param at most
+		switch {
+		case id > 0:
+			request.Id = uint64(id)
+		case username != "":
+			request.Name = username
+		case email != "":
+			request.Email = email
+		}
+
+		response, err := client.ListUsers(ctx, request)
+		if err != nil {
+			return fmt.Errorf("listing users: %w", err)
+		}
+
+		return printListOutput(cmd, response.GetUsers(), func() error {
+			tableData := pterm.TableData{{"ID", "Name", "Username", "Email", "Created"}}
+			for _, user := range response.GetUsers() {
+				tableData = append(
+					tableData,
+					[]string{
+						strconv.FormatUint(user.GetId(), util.Base10),
+						user.GetDisplayName(),
+						user.GetName(),
+						user.GetEmail(),
+						user.GetCreatedAt().AsTime().Format(HeadscaleDateTimeFormat),
+					},
+				)
+			}
+
+			return pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
+		})
+	}),
+}
+
+var renameUserCmd = &cobra.Command{
+	Use:     "rename",
+	Short:   "Renames a user",
+	Aliases: []string{"mv"},
+	RunE: grpcRunE(func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error {
+		id, username, err := usernameAndIDFromFlag(cmd)
+		if err != nil {
+			return err
+		}
+
+		listReq := &v1.ListUsersRequest{
+			Name: username,
+			Id:   id,
+		}
+
+		users, err := client.ListUsers(ctx, listReq)
+		if err != nil {
+			return fmt.Errorf("listing users: %w", err)
+		}
+
+		if len(users.GetUsers()) != 1 {
+			return errMultipleUsersMatch
+		}
+
+		newName, _ := cmd.Flags().GetString("new-name")
+
+		renameReq := &v1.RenameUserRequest{
+			OldId:   id,
+			NewName: newName,
+		}
+
+		response, err := client.RenameUser(ctx, renameReq)
+		if err != nil {
+			return fmt.Errorf("renaming user: %w", err)
+		}
+
+		return printOutput(cmd, response.GetUser(), "User renamed")
+	}),
+}

cmd/headscale/cli/utils.go

@@ -6,381 +6,90 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
-	"io/fs"
-	"net/url"
 	"os"
-	"path/filepath"
-	"regexp"
-	"strconv"
-	"strings"
 	"time"
 
-	"github.com/juanfont/headscale"
 	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/juanfont/headscale/hscontrol"
+	"github.com/juanfont/headscale/hscontrol/types"
+	"github.com/juanfont/headscale/hscontrol/util"
+	"github.com/juanfont/headscale/hscontrol/util/zlog/zf"
+	"github.com/prometheus/common/model"
 	"github.com/rs/zerolog/log"
-	"github.com/spf13/viper"
+	"github.com/spf13/cobra"
 	"google.golang.org/grpc"
 	"google.golang.org/grpc/credentials"
 	"google.golang.org/grpc/credentials/insecure"
-	"gopkg.in/yaml.v2"
-	"inet.af/netaddr"
-	"tailscale.com/tailcfg"
-	"tailscale.com/types/dnstype"
+	"google.golang.org/protobuf/types/known/timestamppb"
+	"gopkg.in/yaml.v3"
 )
 
 const (
-	PermissionFallback      = 0o700
 	HeadscaleDateTimeFormat = "2006-01-02 15:04:05"
+	SocketWritePermissions  = 0o666
+
+	outputFormatJSON     = "json"
+	outputFormatJSONLine = "json-line"
+	outputFormatYAML     = "yaml"
 )
 
-func LoadConfig(path string) error {
-	viper.SetConfigName("config")
-	if path == "" {
-		viper.AddConfigPath("/etc/headscale/")
-		viper.AddConfigPath("$HOME/.headscale")
-		viper.AddConfigPath(".")
-	} else {
-		// For testing
-		viper.AddConfigPath(path)
-	}
+var (
+	errAPIKeyNotSet     = errors.New("HEADSCALE_CLI_API_KEY environment variable needs to be set")
+	errMissingParameter = errors.New("missing parameters")
+)
 
-	viper.SetEnvPrefix("headscale")
-	viper.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
-	viper.AutomaticEnv()
-
-	viper.SetDefault("tls_letsencrypt_cache_dir", "/var/www/.cache")
-	viper.SetDefault("tls_letsencrypt_challenge_type", "HTTP-01")
-
-	viper.SetDefault("log_level", "info")
-
-	viper.SetDefault("dns_config", nil)
-
-	viper.SetDefault("unix_socket", "/var/run/headscale.sock")
-	viper.SetDefault("unix_socket_permission", "0o770")
-
-	viper.SetDefault("grpc_listen_addr", ":50443")
-	viper.SetDefault("grpc_allow_insecure", false)
-
-	viper.SetDefault("cli.timeout", "5s")
-	viper.SetDefault("cli.insecure", false)
-
-	if err := viper.ReadInConfig(); err != nil {
-		return fmt.Errorf("fatal error reading config file: %w", err)
-	}
-
-	// Collect any validation errors and return them all at once
-	var errorText string
-	if (viper.GetString("tls_letsencrypt_hostname") != "") &&
-		((viper.GetString("tls_cert_path") != "") || (viper.GetString("tls_key_path") != "")) {
-		errorText += "Fatal config error: set either tls_letsencrypt_hostname or tls_cert_path/tls_key_path, not both\n"
-	}
-
-	if (viper.GetString("tls_letsencrypt_hostname") != "") &&
-		(viper.GetString("tls_letsencrypt_challenge_type") == "TLS-ALPN-01") &&
-		(!strings.HasSuffix(viper.GetString("listen_addr"), ":443")) {
-		// this is only a warning because there could be something sitting in front of headscale that redirects the traffic (e.g. an iptables rule)
-		log.Warn().
-			Msg("Warning: when using tls_letsencrypt_hostname with TLS-ALPN-01 as challenge type, headscale must be reachable on port 443, i.e. listen_addr should probably end in :443")
-	}
-
-	if (viper.GetString("tls_letsencrypt_challenge_type") != "HTTP-01") &&
-		(viper.GetString("tls_letsencrypt_challenge_type") != "TLS-ALPN-01") {
-		errorText += "Fatal config error: the only supported values for tls_letsencrypt_challenge_type are HTTP-01 and TLS-ALPN-01\n"
-	}
-
-	if !strings.HasPrefix(viper.GetString("server_url"), "http://") &&
-		!strings.HasPrefix(viper.GetString("server_url"), "https://") {
-		errorText += "Fatal config error: server_url must start with https:// or http://\n"
-	}
-	if errorText != "" {
-		//nolint
-		return errors.New(strings.TrimSuffix(errorText, "\n"))
-	} else {
-		return nil
-	}
-}
-
-func GetDERPConfig() headscale.DERPConfig {
-	urlStrs := viper.GetStringSlice("derp.urls")
-
-	urls := make([]url.URL, len(urlStrs))
-	for index, urlStr := range urlStrs {
-		urlAddr, err := url.Parse(urlStr)
+// mustMarkRequired marks the named flags as required on cmd, panicking
+// if any name does not match a registered flag.  This is only called
+// from init() where a failure indicates a programming error.
+func mustMarkRequired(cmd *cobra.Command, names ...string) {
+	for _, n := range names {
+		err := cmd.MarkFlagRequired(n)
 		if err != nil {
-			log.Error().
-				Str("url", urlStr).
-				Err(err).
-				Msg("Failed to parse url, ignoring...")
+			panic(fmt.Sprintf("marking flag %q required on %q: %v", n, cmd.Name(), err))
 		}
-
-		urls[index] = *urlAddr
-	}
-
-	paths := viper.GetStringSlice("derp.paths")
-
-	autoUpdate := viper.GetBool("derp.auto_update_enabled")
-	updateFrequency := viper.GetDuration("derp.update_frequency")
-
-	return headscale.DERPConfig{
-		URLs:            urls,
-		Paths:           paths,
-		AutoUpdate:      autoUpdate,
-		UpdateFrequency: updateFrequency,
 	}
 }
 
-func GetDNSConfig() (*tailcfg.DNSConfig, string) {
-	if viper.IsSet("dns_config") {
-		dnsConfig := &tailcfg.DNSConfig{}
-
-		if viper.IsSet("dns_config.nameservers") {
-			nameserversStr := viper.GetStringSlice("dns_config.nameservers")
-
-			nameservers := make([]netaddr.IP, len(nameserversStr))
-			resolvers := make([]dnstype.Resolver, len(nameserversStr))
-
-			for index, nameserverStr := range nameserversStr {
-				nameserver, err := netaddr.ParseIP(nameserverStr)
-				if err != nil {
-					log.Error().
-						Str("func", "getDNSConfig").
-						Err(err).
-						Msgf("Could not parse nameserver IP: %s", nameserverStr)
-				}
-
-				nameservers[index] = nameserver
-				resolvers[index] = dnstype.Resolver{
-					Addr: nameserver.String(),
-				}
-			}
-
-			dnsConfig.Nameservers = nameservers
-			dnsConfig.Resolvers = resolvers
-		}
-
-		if viper.IsSet("dns_config.restricted_nameservers") {
-			if len(dnsConfig.Nameservers) > 0 {
-				dnsConfig.Routes = make(map[string][]dnstype.Resolver)
-				restrictedDNS := viper.GetStringMapStringSlice(
-					"dns_config.restricted_nameservers",
-				)
-				for domain, restrictedNameservers := range restrictedDNS {
-					restrictedResolvers := make(
-						[]dnstype.Resolver,
-						len(restrictedNameservers),
-					)
-					for index, nameserverStr := range restrictedNameservers {
-						nameserver, err := netaddr.ParseIP(nameserverStr)
-						if err != nil {
-							log.Error().
-								Str("func", "getDNSConfig").
-								Err(err).
-								Msgf("Could not parse restricted nameserver IP: %s", nameserverStr)
-						}
-						restrictedResolvers[index] = dnstype.Resolver{
-							Addr: nameserver.String(),
-						}
-					}
-					dnsConfig.Routes[domain] = restrictedResolvers
-				}
-			} else {
-				log.Warn().
-					Msg("Warning: dns_config.restricted_nameservers is set, but no nameservers are configured. Ignoring restricted_nameservers.")
-			}
-		}
-
-		if viper.IsSet("dns_config.domains") {
-			dnsConfig.Domains = viper.GetStringSlice("dns_config.domains")
-		}
-
-		if viper.IsSet("dns_config.magic_dns") {
-			magicDNS := viper.GetBool("dns_config.magic_dns")
-			if len(dnsConfig.Nameservers) > 0 {
-				dnsConfig.Proxied = magicDNS
-			} else if magicDNS {
-				log.Warn().
-					Msg("Warning: dns_config.magic_dns is set, but no nameservers are configured. Ignoring magic_dns.")
-			}
-		}
-
-		var baseDomain string
-		if viper.IsSet("dns_config.base_domain") {
-			baseDomain = viper.GetString("dns_config.base_domain")
-		} else {
-			baseDomain = "headscale.net" // does not really matter when MagicDNS is not enabled
-		}
-
-		return dnsConfig, baseDomain
-	}
-
-	return nil, ""
-}
-
-func absPath(path string) string {
-	// If a relative path is provided, prefix it with the the directory where
-	// the config file was found.
-	if (path != "") && !strings.HasPrefix(path, string(os.PathSeparator)) {
-		dir, _ := filepath.Split(viper.ConfigFileUsed())
-		if dir != "" {
-			path = filepath.Join(dir, path)
-		}
-	}
-
-	return path
-}
-
-func getHeadscaleConfig() headscale.Config {
-	dnsConfig, baseDomain := GetDNSConfig()
-	derpConfig := GetDERPConfig()
-
-	configuredPrefixes := viper.GetStringSlice("ip_prefixes")
-	parsedPrefixes := make([]netaddr.IPPrefix, 0, len(configuredPrefixes)+1)
-
-	legacyPrefixField := viper.GetString("ip_prefix")
-	if len(legacyPrefixField) > 0 {
-		log.
-			Warn().
-			Msgf(
-				"%s, %s",
-				"use of 'ip_prefix' for configuration is deprecated",
-				"please see 'ip_prefixes' in the shipped example.",
-			)
-		legacyPrefix, err := netaddr.ParseIPPrefix(legacyPrefixField)
-		if err != nil {
-			panic(fmt.Errorf("failed to parse ip_prefix: %w", err))
-		}
-		parsedPrefixes = append(parsedPrefixes, legacyPrefix)
-	}
-
-	for i, prefixInConfig := range configuredPrefixes {
-		prefix, err := netaddr.ParseIPPrefix(prefixInConfig)
-		if err != nil {
-			panic(fmt.Errorf("failed to parse ip_prefixes[%d]: %w", i, err))
-		}
-		parsedPrefixes = append(parsedPrefixes, prefix)
-	}
-
-	prefixes := make([]netaddr.IPPrefix, 0, len(parsedPrefixes))
-	{
-		// dedup
-		normalizedPrefixes := make(map[string]int, len(parsedPrefixes))
-		for i, p := range parsedPrefixes {
-			normalized, _ := p.Range().Prefix()
-			normalizedPrefixes[normalized.String()] = i
-		}
-
-		// convert back to list
-		for _, i := range normalizedPrefixes {
-			prefixes = append(prefixes, parsedPrefixes[i])
-		}
-	}
-
-	if len(prefixes) < 1 {
-		prefixes = append(prefixes, netaddr.MustParseIPPrefix("100.64.0.0/10"))
-		log.Warn().
-			Msgf("'ip_prefixes' not configured, falling back to default: %v", prefixes)
-	}
-
-	return headscale.Config{
-		ServerURL:         viper.GetString("server_url"),
-		Addr:              viper.GetString("listen_addr"),
-		GRPCAddr:          viper.GetString("grpc_listen_addr"),
-		GRPCAllowInsecure: viper.GetBool("grpc_allow_insecure"),
-
-		IPPrefixes:     prefixes,
-		PrivateKeyPath: absPath(viper.GetString("private_key_path")),
-		BaseDomain:     baseDomain,
-
-		DERP: derpConfig,
-
-		EphemeralNodeInactivityTimeout: viper.GetDuration(
-			"ephemeral_node_inactivity_timeout",
-		),
-
-		DBtype: viper.GetString("db_type"),
-		DBpath: absPath(viper.GetString("db_path")),
-		DBhost: viper.GetString("db_host"),
-		DBport: viper.GetInt("db_port"),
-		DBname: viper.GetString("db_name"),
-		DBuser: viper.GetString("db_user"),
-		DBpass: viper.GetString("db_pass"),
-
-		TLSLetsEncryptHostname: viper.GetString("tls_letsencrypt_hostname"),
-		TLSLetsEncryptListen:   viper.GetString("tls_letsencrypt_listen"),
-		TLSLetsEncryptCacheDir: absPath(
-			viper.GetString("tls_letsencrypt_cache_dir"),
-		),
-		TLSLetsEncryptChallengeType: viper.GetString("tls_letsencrypt_challenge_type"),
-
-		TLSCertPath: absPath(viper.GetString("tls_cert_path")),
-		TLSKeyPath:  absPath(viper.GetString("tls_key_path")),
-
-		DNSConfig: dnsConfig,
-
-		ACMEEmail: viper.GetString("acme_email"),
-		ACMEURL:   viper.GetString("acme_url"),
-
-		UnixSocket:           viper.GetString("unix_socket"),
-		UnixSocketPermission: GetFileMode("unix_socket_permission"),
-
-		OIDC: headscale.OIDCConfig{
-			Issuer:       viper.GetString("oidc.issuer"),
-			ClientID:     viper.GetString("oidc.client_id"),
-			ClientSecret: viper.GetString("oidc.client_secret"),
-		},
-
-		CLI: headscale.CLIConfig{
-			Address:  viper.GetString("cli.address"),
-			APIKey:   viper.GetString("cli.api_key"),
-			Timeout:  viper.GetDuration("cli.timeout"),
-			Insecure: viper.GetBool("cli.insecure"),
-		},
-	}
-}
-
-func getHeadscaleApp() (*headscale.Headscale, error) {
-	// Minimum inactivity time out is keepalive timeout (60s) plus a few seconds
-	// to avoid races
-	minInactivityTimeout, _ := time.ParseDuration("65s")
-	if viper.GetDuration("ephemeral_node_inactivity_timeout") <= minInactivityTimeout {
-		// TODO: Find a better way to return this text
-		//nolint
-		err := fmt.Errorf(
-			"ephemeral_node_inactivity_timeout (%s) is set too low, must be more than %s",
-			viper.GetString("ephemeral_node_inactivity_timeout"),
-			minInactivityTimeout,
-		)
-
-		return nil, err
-	}
-
-	cfg := getHeadscaleConfig()
-
-	cfg.OIDC.MatchMap = loadOIDCMatchMap()
-
-	app, err := headscale.NewHeadscale(cfg)
+func newHeadscaleServerWithConfig() (*hscontrol.Headscale, error) {
+	cfg, err := types.LoadServerConfig()
 	if err != nil {
-		return nil, err
+		return nil, fmt.Errorf(
+			"loading configuration: %w",
+			err,
+		)
 	}
 
-	// We are doing this here, as in the future could be cool to have it also hot-reload
-
-	if viper.GetString("acl_policy_path") != "" {
-		aclPath := absPath(viper.GetString("acl_policy_path"))
-		err = app.LoadACLPolicy(aclPath)
-		if err != nil {
-			log.Error().
-				Str("path", aclPath).
-				Err(err).
-				Msg("Could not load the ACL policy")
-		}
+	app, err := hscontrol.NewHeadscale(cfg)
+	if err != nil {
+		return nil, fmt.Errorf("creating new headscale: %w", err)
 	}
 
 	return app, nil
 }
 
-func getHeadscaleCLIClient() (context.Context, v1.HeadscaleServiceClient, *grpc.ClientConn, context.CancelFunc) {
-	cfg := getHeadscaleConfig()
+// grpcRunE wraps a cobra RunE func, injecting a ready gRPC client and
+// context. Connection lifecycle is managed by the wrapper — callers
+// never see the underlying conn or cancel func.
+func grpcRunE(
+	fn func(ctx context.Context, client v1.HeadscaleServiceClient, cmd *cobra.Command, args []string) error,
+) func(*cobra.Command, []string) error {
+	return func(cmd *cobra.Command, args []string) error {
+		ctx, client, conn, cancel, err := newHeadscaleCLIWithConfig()
+		if err != nil {
+			return fmt.Errorf("connecting to headscale: %w", err)
+		}
+		defer cancel()
+		defer conn.Close()
+
+		return fn(ctx, client, cmd, args)
+	}
+}
+
+func newHeadscaleCLIWithConfig() (context.Context, v1.HeadscaleServiceClient, *grpc.ClientConn, context.CancelFunc, error) {
+	cfg, err := types.LoadCLIConfig()
+	if err != nil {
+		return nil, nil, nil, nil, fmt.Errorf("loading configuration: %w", err)
+	}
 
 	log.Debug().
 		Dur("timeout", cfg.CLI.Timeout).
@@ -389,12 +98,12 @@ func getHeadscaleCLIClient() (context.Context, v1.HeadscaleServiceClient, *grpc.
 	ctx, cancel := context.WithTimeout(context.Background(), cfg.CLI.Timeout)
 
 	grpcOptions := []grpc.DialOption{
-		grpc.WithBlock(),
+		grpc.WithBlock(), //nolint:staticcheck // SA1019: deprecated but supported in 1.x
 	}
 
 	address := cfg.CLI.Address
 
-	// If the address is not set, we assume that we are on the server hosting headscale.
+	// If the address is not set, we assume that we are on the server hosting hscontrol.
 	if address == "" {
 		log.Debug().
 			Str("socket", cfg.UnixSocket).
@@ -402,17 +111,39 @@ func getHeadscaleCLIClient() (context.Context, v1.HeadscaleServiceClient, *grpc.
 
 		address = cfg.UnixSocket
 
+		// Try to give the user better feedback if we cannot write to the headscale
+		// socket.  Note: os.OpenFile on a Unix domain socket returns ENXIO on
+		// Linux which is expected — only permission errors are actionable here.
+		// The actual gRPC connection uses net.Dial which handles sockets properly.
+		socket, err := os.OpenFile(cfg.UnixSocket, os.O_WRONLY, SocketWritePermissions) //nolint
+		if err != nil {
+			if os.IsPermission(err) {
+				cancel()
+
+				return nil, nil, nil, nil, fmt.Errorf(
+					"unable to read/write to headscale socket %q, do you have the correct permissions? %w",
+					cfg.UnixSocket,
+					err,
+				)
+			}
+		} else {
+			socket.Close()
+		}
+
 		grpcOptions = append(
 			grpcOptions,
 			grpc.WithTransportCredentials(insecure.NewCredentials()),
-			grpc.WithContextDialer(headscale.GrpcSocketDialer),
+			grpc.WithContextDialer(util.GrpcSocketDialer),
 		)
 	} else {
 		// If we are not connecting to a local server, require an API key for authentication
 		apiKey := cfg.CLI.APIKey
 		if apiKey == "" {
-			log.Fatal().Caller().Msgf("HEADSCALE_CLI_API_KEY environment variable needs to be set.")
+			cancel()
+
+			return nil, nil, nil, nil, errAPIKeyNotSet
 		}
+
 		grpcOptions = append(grpcOptions,
 			grpc.WithPerRPCCredentials(tokenAuth{
 				token: apiKey,
@@ -437,58 +168,136 @@ func getHeadscaleCLIClient() (context.Context, v1.HeadscaleServiceClient, *grpc.
 		}
 	}
 
-	log.Trace().Caller().Str("address", address).Msg("Connecting via gRPC")
-	conn, err := grpc.DialContext(ctx, address, grpcOptions...)
+	log.Trace().Caller().Str(zf.Address, address).Msg("connecting via gRPC")
+
+	conn, err := grpc.DialContext(ctx, address, grpcOptions...) //nolint:staticcheck // SA1019: deprecated but supported in 1.x
 	if err != nil {
-		log.Fatal().Caller().Err(err).Msgf("Could not connect: %v", err)
+		cancel()
+
+		return nil, nil, nil, nil, fmt.Errorf("connecting to %s: %w", address, err)
 	}
 
 	client := v1.NewHeadscaleServiceClient(conn)
 
-	return ctx, client, conn, cancel
+	return ctx, client, conn, cancel, nil
 }
 
-func SuccessOutput(result interface{}, override string, outputFormat string) {
-	var jsonBytes []byte
-	var err error
+// formatOutput serialises result into the requested format. For the
+// default (empty) format the human-readable override string is returned.
+func formatOutput(result any, override string, outputFormat string) (string, error) {
 	switch outputFormat {
-	case "json":
-		jsonBytes, err = json.MarshalIndent(result, "", "\t")
+	case outputFormatJSON:
+		b, err := json.MarshalIndent(result, "", "\t")
 		if err != nil {
-			log.Fatal().Err(err)
+			return "", fmt.Errorf("marshalling JSON output: %w", err)
 		}
-	case "json-line":
-		jsonBytes, err = json.Marshal(result)
-		if err != nil {
-			log.Fatal().Err(err)
-		}
-	case "yaml":
-		jsonBytes, err = yaml.Marshal(result)
-		if err != nil {
-			log.Fatal().Err(err)
-		}
-	default:
-		//nolint
-		fmt.Println(override)
 
-		return
+		return string(b), nil
+	case outputFormatJSONLine:
+		b, err := json.Marshal(result)
+		if err != nil {
+			return "", fmt.Errorf("marshalling JSON-line output: %w", err)
+		}
+
+		return string(b), nil
+	case outputFormatYAML:
+		b, err := yaml.Marshal(result)
+		if err != nil {
+			return "", fmt.Errorf("marshalling YAML output: %w", err)
+		}
+
+		return string(b), nil
+	default:
+		return override, nil
+	}
+}
+
+// printOutput formats result and writes it to stdout. It reads the --output
+// flag from cmd to decide the serialisation format.
+func printOutput(cmd *cobra.Command, result any, override string) error {
+	format, _ := cmd.Flags().GetString("output")
+
+	out, err := formatOutput(result, override, format)
+	if err != nil {
+		return err
 	}
 
-	//nolint
-	fmt.Println(string(jsonBytes))
+	fmt.Println(out)
+
+	return nil
 }
 
-func ErrorOutput(errResult error, override string, outputFormat string) {
+// expirationFromFlag parses the --expiration flag as a Prometheus-style
+// duration (e.g. "90d", "1h") and returns an absolute timestamp.
+func expirationFromFlag(cmd *cobra.Command) (*timestamppb.Timestamp, error) {
+	durationStr, _ := cmd.Flags().GetString("expiration")
+
+	duration, err := model.ParseDuration(durationStr)
+	if err != nil {
+		return nil, fmt.Errorf("parsing duration: %w", err)
+	}
+
+	return timestamppb.New(time.Now().UTC().Add(time.Duration(duration))), nil
+}
+
+// confirmAction returns true when the user confirms a prompt, or when
+// --force is set.  Callers decide what to do when it returns false.
+func confirmAction(cmd *cobra.Command, prompt string) bool {
+	force, _ := cmd.Flags().GetBool("force")
+	if force {
+		return true
+	}
+
+	return util.YesNo(prompt)
+}
+
+// printListOutput checks the --output flag: when a machine-readable format is
+// requested it serialises data as JSON/YAML; otherwise it calls renderTable
+// to produce the human-readable pterm table.
+func printListOutput(
+	cmd *cobra.Command,
+	data any,
+	renderTable func() error,
+) error {
+	format, _ := cmd.Flags().GetString("output")
+	if format != "" {
+		return printOutput(cmd, data, "")
+	}
+
+	return renderTable()
+}
+
+// printError writes err to stderr, formatting it as JSON/YAML when the
+// --output flag requests machine-readable output.  Used exclusively by
+// Execute() so that every error surfaces in the format the caller asked for.
+func printError(err error, outputFormat string) {
 	type errOutput struct {
 		Error string `json:"error"`
 	}
 
-	SuccessOutput(errOutput{errResult.Error()}, override, outputFormat)
+	e := errOutput{Error: err.Error()}
+
+	var formatted []byte
+
+	switch outputFormat {
+	case outputFormatJSON:
+		formatted, _ = json.MarshalIndent(e, "", "\t") //nolint:errchkjson // errOutput contains only a string field
+	case outputFormatJSONLine:
+		formatted, _ = json.Marshal(e) //nolint:errchkjson // errOutput contains only a string field
+	case outputFormatYAML:
+		formatted, _ = yaml.Marshal(e)
+	default:
+		fmt.Fprintf(os.Stderr, "Error: %s\n", err)
+
+		return
+	}
+
+	fmt.Fprintf(os.Stderr, "%s\n", formatted)
 }
 
-func HasMachineOutputFlag() bool {
+func hasMachineOutputFlag() bool {
 	for _, arg := range os.Args {
-		if arg == "json" || arg == "json-line" || arg == "yaml" {
+		if arg == outputFormatJSON || arg == outputFormatJSONLine || arg == outputFormatYAML {
 			return true
 		}
 	}
@@ -513,26 +322,3 @@ func (t tokenAuth) GetRequestMetadata(
 func (tokenAuth) RequireTransportSecurity() bool {
 	return true
 }
-
-// loadOIDCMatchMap is a wrapper around viper to verifies that the keys in
-// the match map is valid regex strings.
-func loadOIDCMatchMap() map[string]string {
-	strMap := viper.GetStringMapString("oidc.domain_map")
-
-	for oidcMatcher := range strMap {
-		_ = regexp.MustCompile(oidcMatcher)
-	}
-
-	return strMap
-}
-
-func GetFileMode(key string) fs.FileMode {
-	modeStr := viper.GetString(key)
-
-	mode, err := strconv.ParseUint(modeStr, headscale.Base8, headscale.BitSize64)
-	if err != nil {
-		return PermissionFallback
-	}
-
-	return fs.FileMode(mode)
-}

cmd/headscale/cli/version.go

@@ -1,21 +1,22 @@
 package cli
 
 import (
+	"github.com/juanfont/headscale/hscontrol/types"
 	"github.com/spf13/cobra"
 )
 
-var Version = "dev"
-
 func init() {
 	rootCmd.AddCommand(versionCmd)
+	versionCmd.Flags().StringP("output", "o", "", "Output format. Empty for human-readable, 'json', 'json-line' or 'yaml'")
 }
 
 var versionCmd = &cobra.Command{
 	Use:   "version",
 	Short: "Print the version.",
 	Long:  "The version of headscale.",
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-		SuccessOutput(map[string]string{"version": Version}, Version, output)
+	RunE: func(cmd *cobra.Command, args []string) error {
+		info := types.GetVersionInfo()
+
+		return printOutput(cmd, info, info.String())
 	},
 }

cmd/headscale/headscale.go

@@ -1,21 +1,18 @@
 package main
 
 import (
-	"fmt"
 	"os"
-	"runtime"
 	"time"
 
-	"github.com/efekarakus/termcolor"
+	"github.com/jagottsicher/termcolor"
 	"github.com/juanfont/headscale/cmd/headscale/cli"
 	"github.com/rs/zerolog"
 	"github.com/rs/zerolog/log"
-	"github.com/spf13/viper"
-	"github.com/tcnksm/go-latest"
 )
 
 func main() {
 	var colors bool
+
 	switch l := termcolor.SupportLevel(os.Stderr); l {
 	case termcolor.Level16M:
 		colors = true
@@ -38,49 +35,10 @@ func main() {
 
 	zerolog.TimeFieldFormat = zerolog.TimeFormatUnix
 	log.Logger = log.Output(zerolog.ConsoleWriter{
-		Out:        os.Stdout,
+		Out:        os.Stderr,
 		TimeFormat: time.RFC3339,
 		NoColor:    !colors,
 	})
 
-	if err := cli.LoadConfig(""); err != nil {
-		log.Fatal().Caller().Err(err)
-	}
-
-	machineOutput := cli.HasMachineOutputFlag()
-
-	logLevel := viper.GetString("log_level")
-	level, err := zerolog.ParseLevel(logLevel)
-	if err != nil {
-		zerolog.SetGlobalLevel(zerolog.DebugLevel)
-	} else {
-		zerolog.SetGlobalLevel(level)
-	}
-
-	// If the user has requested a "machine" readable format,
-	// then disable login so the output remains valid.
-	if machineOutput {
-		zerolog.SetGlobalLevel(zerolog.Disabled)
-	}
-
-	if !viper.GetBool("disable_check_updates") && !machineOutput {
-		if (runtime.GOOS == "linux" || runtime.GOOS == "darwin") &&
-			cli.Version != "dev" {
-			githubTag := &latest.GithubTag{
-				Owner:      "juanfont",
-				Repository: "headscale",
-			}
-			res, err := latest.Check(githubTag, cli.Version)
-			if err == nil && res.Outdated {
-				//nolint
-				fmt.Printf(
-					"An updated version of Headscale has been found (%s vs. your current %s). Check it out https://github.com/juanfont/headscale/releases\n",
-					res.Current,
-					cli.Version,
-				)
-			}
-		}
-	}
-
 	cli.Execute()
 }

cmd/headscale/headscale_test.go

@@ -2,152 +2,76 @@ package main
 
 import (
 	"io/fs"
-	"io/ioutil"
 	"os"
 	"path/filepath"
-	"strings"
 	"testing"
 
-	"github.com/juanfont/headscale/cmd/headscale/cli"
+	"github.com/juanfont/headscale/hscontrol/types"
+	"github.com/juanfont/headscale/hscontrol/util"
 	"github.com/spf13/viper"
-	"gopkg.in/check.v1"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
-func Test(t *testing.T) {
-	check.TestingT(t)
-}
-
-var _ = check.Suite(&Suite{})
-
-type Suite struct{}
-
-func (s *Suite) SetUpSuite(c *check.C) {
-}
-
-func (s *Suite) TearDownSuite(c *check.C) {
-}
-
-func (*Suite) TestConfigLoading(c *check.C) {
-	tmpDir, err := ioutil.TempDir("", "headscale")
-	if err != nil {
-		c.Fatal(err)
-	}
-	defer os.RemoveAll(tmpDir)
+func TestConfigFileLoading(t *testing.T) {
+	tmpDir := t.TempDir()
 
 	path, err := os.Getwd()
-	if err != nil {
-		c.Fatal(err)
-	}
+	require.NoError(t, err)
+
+	cfgFile := filepath.Join(tmpDir, "config.yaml")
 
 	// Symlink the example config file
 	err = os.Symlink(
 		filepath.Clean(path+"/../../config-example.yaml"),
-		filepath.Join(tmpDir, "config.yaml"),
+		cfgFile,
 	)
-	if err != nil {
-		c.Fatal(err)
-	}
+	require.NoError(t, err)
 
 	// Load example config, it should load without validation errors
-	err = cli.LoadConfig(tmpDir)
-	c.Assert(err, check.IsNil)
+	err = types.LoadConfig(cfgFile, true)
+	require.NoError(t, err)
 
 	// Test that config file was interpreted correctly
-	c.Assert(viper.GetString("server_url"), check.Equals, "http://127.0.0.1:8080")
-	c.Assert(viper.GetString("listen_addr"), check.Equals, "0.0.0.0:8080")
-	c.Assert(viper.GetString("db_type"), check.Equals, "sqlite3")
-	c.Assert(viper.GetString("db_path"), check.Equals, "/var/lib/headscale/db.sqlite")
-	c.Assert(viper.GetString("tls_letsencrypt_hostname"), check.Equals, "")
-	c.Assert(viper.GetString("tls_letsencrypt_listen"), check.Equals, ":http")
-	c.Assert(viper.GetString("tls_letsencrypt_challenge_type"), check.Equals, "HTTP-01")
-	c.Assert(viper.GetStringSlice("dns_config.nameservers")[0], check.Equals, "1.1.1.1")
-	c.Assert(
-		cli.GetFileMode("unix_socket_permission"),
-		check.Equals,
-		fs.FileMode(0o770),
-	)
+	assert.Equal(t, "http://127.0.0.1:8080", viper.GetString("server_url"))
+	assert.Equal(t, "127.0.0.1:8080", viper.GetString("listen_addr"))
+	assert.Equal(t, "127.0.0.1:9090", viper.GetString("metrics_listen_addr"))
+	assert.Equal(t, "sqlite", viper.GetString("database.type"))
+	assert.Equal(t, "/var/lib/headscale/db.sqlite", viper.GetString("database.sqlite.path"))
+	assert.Empty(t, viper.GetString("tls_letsencrypt_hostname"))
+	assert.Equal(t, ":http", viper.GetString("tls_letsencrypt_listen"))
+	assert.Equal(t, "HTTP-01", viper.GetString("tls_letsencrypt_challenge_type"))
+	assert.Equal(t, fs.FileMode(0o770), util.GetFileMode("unix_socket_permission"))
+	assert.False(t, viper.GetBool("logtail.enabled"))
 }
 
-func (*Suite) TestDNSConfigLoading(c *check.C) {
-	tmpDir, err := ioutil.TempDir("", "headscale")
-	if err != nil {
-		c.Fatal(err)
-	}
-	defer os.RemoveAll(tmpDir)
+func TestConfigLoading(t *testing.T) {
+	tmpDir := t.TempDir()
 
 	path, err := os.Getwd()
-	if err != nil {
-		c.Fatal(err)
-	}
+	require.NoError(t, err)
 
 	// Symlink the example config file
 	err = os.Symlink(
 		filepath.Clean(path+"/../../config-example.yaml"),
 		filepath.Join(tmpDir, "config.yaml"),
 	)
-	if err != nil {
-		c.Fatal(err)
-	}
+	require.NoError(t, err)
 
 	// Load example config, it should load without validation errors
-	err = cli.LoadConfig(tmpDir)
-	c.Assert(err, check.IsNil)
+	err = types.LoadConfig(tmpDir, false)
+	require.NoError(t, err)
 
-	dnsConfig, baseDomain := cli.GetDNSConfig()
-
-	c.Assert(dnsConfig.Nameservers[0].String(), check.Equals, "1.1.1.1")
-	c.Assert(dnsConfig.Resolvers[0].Addr, check.Equals, "1.1.1.1")
-	c.Assert(dnsConfig.Proxied, check.Equals, true)
-	c.Assert(baseDomain, check.Equals, "example.com")
-}
-
-func writeConfig(c *check.C, tmpDir string, configYaml []byte) {
-	// Populate a custom config file
-	configFile := filepath.Join(tmpDir, "config.yaml")
-	err := ioutil.WriteFile(configFile, configYaml, 0o600)
-	if err != nil {
-		c.Fatalf("Couldn't write file %s", configFile)
-	}
-}
-
-func (*Suite) TestTLSConfigValidation(c *check.C) {
-	tmpDir, err := ioutil.TempDir("", "headscale")
-	if err != nil {
-		c.Fatal(err)
-	}
-	// defer os.RemoveAll(tmpDir)
-
-	configYaml := []byte(
-		"---\ntls_letsencrypt_hostname: \"example.com\"\ntls_letsencrypt_challenge_type: \"\"\ntls_cert_path: \"abc.pem\"",
-	)
-	writeConfig(c, tmpDir, configYaml)
-
-	// Check configuration validation errors (1)
-	err = cli.LoadConfig(tmpDir)
-	c.Assert(err, check.NotNil)
-	// check.Matches can not handle multiline strings
-	tmp := strings.ReplaceAll(err.Error(), "\n", "***")
-	c.Assert(
-		tmp,
-		check.Matches,
-		".*Fatal config error: set either tls_letsencrypt_hostname or tls_cert_path/tls_key_path, not both.*",
-	)
-	c.Assert(
-		tmp,
-		check.Matches,
-		".*Fatal config error: the only supported values for tls_letsencrypt_challenge_type are.*",
-	)
-	c.Assert(
-		tmp,
-		check.Matches,
-		".*Fatal config error: server_url must start with https:// or http://.*",
-	)
-
-	// Check configuration validation errors (2)
-	configYaml = []byte(
-		"---\nserver_url: \"http://127.0.0.1:8080\"\ntls_letsencrypt_hostname: \"example.com\"\ntls_letsencrypt_challenge_type: \"TLS-ALPN-01\"",
-	)
-	writeConfig(c, tmpDir, configYaml)
-	err = cli.LoadConfig(tmpDir)
-	c.Assert(err, check.IsNil)
+	// Test that config file was interpreted correctly
+	assert.Equal(t, "http://127.0.0.1:8080", viper.GetString("server_url"))
+	assert.Equal(t, "127.0.0.1:8080", viper.GetString("listen_addr"))
+	assert.Equal(t, "127.0.0.1:9090", viper.GetString("metrics_listen_addr"))
+	assert.Equal(t, "sqlite", viper.GetString("database.type"))
+	assert.Equal(t, "/var/lib/headscale/db.sqlite", viper.GetString("database.sqlite.path"))
+	assert.Empty(t, viper.GetString("tls_letsencrypt_hostname"))
+	assert.Equal(t, ":http", viper.GetString("tls_letsencrypt_listen"))
+	assert.Equal(t, "HTTP-01", viper.GetString("tls_letsencrypt_challenge_type"))
+	assert.Equal(t, fs.FileMode(0o770), util.GetFileMode("unix_socket_permission"))
+	assert.False(t, viper.GetBool("logtail.enabled"))
+	assert.False(t, viper.GetBool("randomize_client_port"))
 }

cmd/hi/README.md

@@ -0,0 +1,6 @@
+# hi
+
+hi (headscale integration runner) is an entirely "vibe coded" wrapper around our
+[integration test suite](../integration). It essentially runs the docker
+commands for you with some added benefits of extracting resources like logs and
+databases.

cmd/hi/cleanup.go

@@ -0,0 +1,431 @@
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/cenkalti/backoff/v5"
+	"github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/filters"
+	"github.com/docker/docker/api/types/image"
+	"github.com/docker/docker/client"
+	"github.com/docker/docker/errdefs"
+)
+
+// cleanupBeforeTest performs cleanup operations before running tests.
+// Only removes stale (stopped/exited) test containers to avoid interfering with concurrent test runs.
+func cleanupBeforeTest(ctx context.Context) error {
+	err := cleanupStaleTestContainers(ctx)
+	if err != nil {
+		return fmt.Errorf("cleaning stale test containers: %w", err)
+	}
+
+	if err := pruneDockerNetworks(ctx); err != nil { //nolint:noinlineerr
+		return fmt.Errorf("pruning networks: %w", err)
+	}
+
+	return nil
+}
+
+// cleanupAfterTest removes the test container and all associated integration test containers for the run.
+func cleanupAfterTest(ctx context.Context, cli *client.Client, containerID, runID string) error {
+	// Remove the main test container
+	err := cli.ContainerRemove(ctx, containerID, container.RemoveOptions{
+		Force: true,
+	})
+	if err != nil {
+		return fmt.Errorf("removing test container: %w", err)
+	}
+
+	// Clean up integration test containers for this run only
+	if runID != "" {
+		err := killTestContainersByRunID(ctx, runID)
+		if err != nil {
+			return fmt.Errorf("cleaning up containers for run %s: %w", runID, err)
+		}
+	}
+
+	return nil
+}
+
+// killTestContainers terminates and removes all test containers.
+func killTestContainers(ctx context.Context) error {
+	cli, err := createDockerClient(ctx)
+	if err != nil {
+		return fmt.Errorf("creating Docker client: %w", err)
+	}
+	defer cli.Close()
+
+	containers, err := cli.ContainerList(ctx, container.ListOptions{
+		All: true,
+	})
+	if err != nil {
+		return fmt.Errorf("listing containers: %w", err)
+	}
+
+	removed := 0
+
+	for _, cont := range containers {
+		shouldRemove := false
+
+		for _, name := range cont.Names {
+			if strings.Contains(name, "headscale-test-suite") ||
+				strings.Contains(name, "hs-") ||
+				strings.Contains(name, "ts-") ||
+				strings.Contains(name, "derp-") {
+				shouldRemove = true
+				break
+			}
+		}
+
+		if shouldRemove {
+			// First kill the container if it's running
+			if cont.State == "running" {
+				_ = cli.ContainerKill(ctx, cont.ID, "KILL")
+			}
+
+			// Then remove the container with retry logic
+			if removeContainerWithRetry(ctx, cli, cont.ID) {
+				removed++
+			}
+		}
+	}
+
+	if removed > 0 {
+		fmt.Printf("Removed %d test containers\n", removed)
+	} else {
+		fmt.Println("No test containers found to remove")
+	}
+
+	return nil
+}
+
+// killTestContainersByRunID terminates and removes all test containers for a specific run ID.
+// This function filters containers by the hi.run-id label to only affect containers
+// belonging to the specified test run, leaving other concurrent test runs untouched.
+func killTestContainersByRunID(ctx context.Context, runID string) error {
+	cli, err := createDockerClient(ctx)
+	if err != nil {
+		return fmt.Errorf("creating Docker client: %w", err)
+	}
+	defer cli.Close()
+
+	// Filter containers by hi.run-id label
+	containers, err := cli.ContainerList(ctx, container.ListOptions{
+		All: true,
+		Filters: filters.NewArgs(
+			filters.Arg("label", "hi.run-id="+runID),
+		),
+	})
+	if err != nil {
+		return fmt.Errorf("listing containers for run %s: %w", runID, err)
+	}
+
+	removed := 0
+
+	for _, cont := range containers {
+		// Kill the container if it's running
+		if cont.State == "running" {
+			_ = cli.ContainerKill(ctx, cont.ID, "KILL")
+		}
+
+		// Remove the container with retry logic
+		if removeContainerWithRetry(ctx, cli, cont.ID) {
+			removed++
+		}
+	}
+
+	if removed > 0 {
+		fmt.Printf("Removed %d containers for run ID %s\n", removed, runID)
+	}
+
+	return nil
+}
+
+// cleanupStaleTestContainers removes stopped/exited test containers without affecting running tests.
+// This is useful for cleaning up leftover containers from previous crashed or interrupted test runs
+// without interfering with currently running concurrent tests.
+func cleanupStaleTestContainers(ctx context.Context) error {
+	cli, err := createDockerClient(ctx)
+	if err != nil {
+		return fmt.Errorf("creating Docker client: %w", err)
+	}
+	defer cli.Close()
+
+	// Only get stopped/exited containers
+	containers, err := cli.ContainerList(ctx, container.ListOptions{
+		All: true,
+		Filters: filters.NewArgs(
+			filters.Arg("status", "exited"),
+			filters.Arg("status", "dead"),
+		),
+	})
+	if err != nil {
+		return fmt.Errorf("listing stopped containers: %w", err)
+	}
+
+	removed := 0
+
+	for _, cont := range containers {
+		// Only remove containers that look like test containers
+		shouldRemove := false
+
+		for _, name := range cont.Names {
+			if strings.Contains(name, "headscale-test-suite") ||
+				strings.Contains(name, "hs-") ||
+				strings.Contains(name, "ts-") ||
+				strings.Contains(name, "derp-") {
+				shouldRemove = true
+				break
+			}
+		}
+
+		if shouldRemove {
+			if removeContainerWithRetry(ctx, cli, cont.ID) {
+				removed++
+			}
+		}
+	}
+
+	if removed > 0 {
+		fmt.Printf("Removed %d stale test containers\n", removed)
+	}
+
+	return nil
+}
+
+const (
+	containerRemoveInitialInterval = 100 * time.Millisecond
+	containerRemoveMaxElapsedTime  = 2 * time.Second
+)
+
+// removeContainerWithRetry attempts to remove a container with exponential backoff retry logic.
+func removeContainerWithRetry(ctx context.Context, cli *client.Client, containerID string) bool {
+	expBackoff := backoff.NewExponentialBackOff()
+	expBackoff.InitialInterval = containerRemoveInitialInterval
+
+	_, err := backoff.Retry(ctx, func() (struct{}, error) {
+		err := cli.ContainerRemove(ctx, containerID, container.RemoveOptions{
+			Force: true,
+		})
+		if err != nil {
+			return struct{}{}, err
+		}
+
+		return struct{}{}, nil
+	}, backoff.WithBackOff(expBackoff), backoff.WithMaxElapsedTime(containerRemoveMaxElapsedTime))
+
+	return err == nil
+}
+
+// pruneDockerNetworks removes unused Docker networks.
+func pruneDockerNetworks(ctx context.Context) error {
+	cli, err := createDockerClient(ctx)
+	if err != nil {
+		return fmt.Errorf("creating Docker client: %w", err)
+	}
+	defer cli.Close()
+
+	report, err := cli.NetworksPrune(ctx, filters.Args{})
+	if err != nil {
+		return fmt.Errorf("pruning networks: %w", err)
+	}
+
+	if len(report.NetworksDeleted) > 0 {
+		fmt.Printf("Removed %d unused networks\n", len(report.NetworksDeleted))
+	} else {
+		fmt.Println("No unused networks found to remove")
+	}
+
+	return nil
+}
+
+// cleanOldImages removes test-related and old dangling Docker images.
+func cleanOldImages(ctx context.Context) error {
+	cli, err := createDockerClient(ctx)
+	if err != nil {
+		return fmt.Errorf("creating Docker client: %w", err)
+	}
+	defer cli.Close()
+
+	images, err := cli.ImageList(ctx, image.ListOptions{
+		All: true,
+	})
+	if err != nil {
+		return fmt.Errorf("listing images: %w", err)
+	}
+
+	removed := 0
+
+	for _, img := range images {
+		shouldRemove := false
+
+		for _, tag := range img.RepoTags {
+			if strings.Contains(tag, "hs-") ||
+				strings.Contains(tag, "headscale-integration") ||
+				strings.Contains(tag, "tailscale") {
+				shouldRemove = true
+				break
+			}
+		}
+
+		if len(img.RepoTags) == 0 && time.Unix(img.Created, 0).Before(time.Now().Add(-7*24*time.Hour)) {
+			shouldRemove = true
+		}
+
+		if shouldRemove {
+			_, err := cli.ImageRemove(ctx, img.ID, image.RemoveOptions{
+				Force: true,
+			})
+			if err == nil {
+				removed++
+			}
+		}
+	}
+
+	if removed > 0 {
+		fmt.Printf("Removed %d test images\n", removed)
+	} else {
+		fmt.Println("No test images found to remove")
+	}
+
+	return nil
+}
+
+// cleanCacheVolume removes the Docker volume used for Go module cache.
+func cleanCacheVolume(ctx context.Context) error {
+	cli, err := createDockerClient(ctx)
+	if err != nil {
+		return fmt.Errorf("creating Docker client: %w", err)
+	}
+	defer cli.Close()
+
+	volumeName := "hs-integration-go-cache"
+
+	err = cli.VolumeRemove(ctx, volumeName, true)
+	if err != nil {
+		if errdefs.IsNotFound(err) { //nolint:staticcheck // SA1019: deprecated but functional
+			fmt.Printf("Go module cache volume not found: %s\n", volumeName)
+		} else if errdefs.IsConflict(err) { //nolint:staticcheck // SA1019: deprecated but functional
+			fmt.Printf("Go module cache volume is in use and cannot be removed: %s\n", volumeName)
+		} else {
+			fmt.Printf("Failed to remove Go module cache volume %s: %v\n", volumeName, err)
+		}
+	} else {
+		fmt.Printf("Removed Go module cache volume: %s\n", volumeName)
+	}
+
+	return nil
+}
+
+// cleanupSuccessfulTestArtifacts removes artifacts from successful test runs to save disk space.
+// This function removes large artifacts that are mainly useful for debugging failures:
+// - Database dumps (.db files)
+// - Profile data (pprof directories)
+// - MapResponse data (mapresponses directories)
+// - Prometheus metrics files
+//
+// It preserves:
+// - Log files (.log) which are small and useful for verification.
+func cleanupSuccessfulTestArtifacts(logsDir string, verbose bool) error {
+	entries, err := os.ReadDir(logsDir)
+	if err != nil {
+		return fmt.Errorf("reading logs directory: %w", err)
+	}
+
+	var (
+		removedFiles, removedDirs int
+		totalSize                 int64
+	)
+
+	for _, entry := range entries {
+		name := entry.Name()
+		fullPath := filepath.Join(logsDir, name)
+
+		if entry.IsDir() {
+			// Remove pprof and mapresponses directories (typically large)
+			// These directories contain artifacts from all containers in the test run
+			if name == "pprof" || name == "mapresponses" {
+				size, sizeErr := getDirSize(fullPath)
+				if sizeErr == nil {
+					totalSize += size
+				}
+
+				err := os.RemoveAll(fullPath)
+				if err != nil {
+					if verbose {
+						log.Printf("Warning: failed to remove directory %s: %v", name, err)
+					}
+				} else {
+					removedDirs++
+
+					if verbose {
+						log.Printf("Removed directory: %s/", name)
+					}
+				}
+			}
+		} else {
+			// Only process test-related files (headscale and tailscale)
+			if !strings.HasPrefix(name, "hs-") && !strings.HasPrefix(name, "ts-") {
+				continue
+			}
+
+			// Remove database, metrics, and status files, but keep logs
+			shouldRemove := strings.HasSuffix(name, ".db") ||
+				strings.HasSuffix(name, "_metrics.txt") ||
+				strings.HasSuffix(name, "_status.json")
+
+			if shouldRemove {
+				info, infoErr := entry.Info()
+				if infoErr == nil {
+					totalSize += info.Size()
+				}
+
+				err := os.Remove(fullPath)
+				if err != nil {
+					if verbose {
+						log.Printf("Warning: failed to remove file %s: %v", name, err)
+					}
+				} else {
+					removedFiles++
+
+					if verbose {
+						log.Printf("Removed file: %s", name)
+					}
+				}
+			}
+		}
+	}
+
+	if removedFiles > 0 || removedDirs > 0 {
+		const bytesPerMB = 1024 * 1024
+		log.Printf("Cleaned up %d files and %d directories (freed ~%.2f MB)",
+			removedFiles, removedDirs, float64(totalSize)/bytesPerMB)
+	}
+
+	return nil
+}
+
+// getDirSize calculates the total size of a directory.
+func getDirSize(path string) (int64, error) {
+	var size int64
+
+	err := filepath.Walk(path, func(_ string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+
+		if !info.IsDir() {
+			size += info.Size()
+		}
+
+		return nil
+	})
+
+	return size, err
+}

cmd/hi/docker.go

@@ -0,0 +1,807 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/image"
+	"github.com/docker/docker/api/types/mount"
+	"github.com/docker/docker/client"
+	"github.com/docker/docker/pkg/stdcopy"
+	"github.com/juanfont/headscale/integration/dockertestutil"
+)
+
+const defaultDirPerm = 0o755
+
+var (
+	ErrTestFailed              = errors.New("test failed")
+	ErrUnexpectedContainerWait = errors.New("unexpected end of container wait")
+	ErrNoDockerContext         = errors.New("no docker context found")
+	ErrMemoryLimitViolations   = errors.New("container(s) exceeded memory limits")
+)
+
+// runTestContainer executes integration tests in a Docker container.
+//
+//nolint:gocyclo // complex test orchestration function
+func runTestContainer(ctx context.Context, config *RunConfig) error {
+	cli, err := createDockerClient(ctx)
+	if err != nil {
+		return fmt.Errorf("creating Docker client: %w", err)
+	}
+	defer cli.Close()
+
+	runID := dockertestutil.GenerateRunID()
+	containerName := "headscale-test-suite-" + runID
+	logsDir := filepath.Join(config.LogsDir, runID)
+
+	if config.Verbose {
+		log.Printf("Run ID: %s", runID)
+		log.Printf("Container name: %s", containerName)
+		log.Printf("Logs directory: %s", logsDir)
+	}
+
+	absLogsDir, err := filepath.Abs(logsDir)
+	if err != nil {
+		return fmt.Errorf("getting absolute path for logs directory: %w", err)
+	}
+
+	const dirPerm = 0o755
+	if err := os.MkdirAll(absLogsDir, dirPerm); err != nil { //nolint:noinlineerr
+		return fmt.Errorf("creating logs directory: %w", err)
+	}
+
+	if config.CleanBefore {
+		if config.Verbose {
+			log.Printf("Running pre-test cleanup...")
+		}
+
+		err := cleanupBeforeTest(ctx)
+		if err != nil && config.Verbose {
+			log.Printf("Warning: pre-test cleanup failed: %v", err)
+		}
+	}
+
+	goTestCmd := buildGoTestCommand(config)
+	if config.Verbose {
+		log.Printf("Command: %s", strings.Join(goTestCmd, " "))
+	}
+
+	imageName := "golang:" + config.GoVersion
+	if err := ensureImageAvailable(ctx, cli, imageName, config.Verbose); err != nil { //nolint:noinlineerr
+		return fmt.Errorf("ensuring image availability: %w", err)
+	}
+
+	resp, err := createGoTestContainer(ctx, cli, config, containerName, absLogsDir, goTestCmd)
+	if err != nil {
+		return fmt.Errorf("creating container: %w", err)
+	}
+
+	if config.Verbose {
+		log.Printf("Created container: %s", resp.ID)
+	}
+
+	if err := cli.ContainerStart(ctx, resp.ID, container.StartOptions{}); err != nil { //nolint:noinlineerr
+		return fmt.Errorf("starting container: %w", err)
+	}
+
+	log.Printf("Starting test: %s", config.TestPattern)
+	log.Printf("Run ID: %s", runID)
+	log.Printf("Monitor with: docker logs -f %s", containerName)
+	log.Printf("Logs directory: %s", logsDir)
+
+	// Start stats collection for container resource monitoring (if enabled)
+	var statsCollector *StatsCollector
+
+	if config.Stats {
+		var err error
+
+		statsCollector, err = NewStatsCollector(ctx)
+		if err != nil {
+			if config.Verbose {
+				log.Printf("Warning: failed to create stats collector: %v", err)
+			}
+
+			statsCollector = nil
+		}
+
+		if statsCollector != nil {
+			defer statsCollector.Close()
+
+			// Start stats collection immediately - no need for complex retry logic
+			// The new implementation monitors Docker events and will catch containers as they start
+			err := statsCollector.StartCollection(ctx, runID, config.Verbose)
+			if err != nil {
+				if config.Verbose {
+					log.Printf("Warning: failed to start stats collection: %v", err)
+				}
+			}
+			defer statsCollector.StopCollection()
+		}
+	}
+
+	exitCode, err := streamAndWait(ctx, cli, resp.ID)
+
+	// Ensure all containers have finished and logs are flushed before extracting artifacts
+	waitErr := waitForContainerFinalization(ctx, cli, resp.ID, config.Verbose)
+	if waitErr != nil && config.Verbose {
+		log.Printf("Warning: failed to wait for container finalization: %v", waitErr)
+	}
+
+	// Extract artifacts from test containers before cleanup
+	if err := extractArtifactsFromContainers(ctx, resp.ID, logsDir, config.Verbose); err != nil && config.Verbose { //nolint:noinlineerr
+		log.Printf("Warning: failed to extract artifacts from containers: %v", err)
+	}
+
+	// Always list control files regardless of test outcome
+	listControlFiles(logsDir)
+
+	// Print stats summary and check memory limits if enabled
+	if config.Stats && statsCollector != nil {
+		violations := statsCollector.PrintSummaryAndCheckLimits(config.HSMemoryLimit, config.TSMemoryLimit)
+		if len(violations) > 0 {
+			log.Printf("MEMORY LIMIT VIOLATIONS DETECTED:")
+			log.Printf("=================================")
+
+			for _, violation := range violations {
+				log.Printf("Container %s exceeded memory limit: %.1f MB > %.1f MB",
+					violation.ContainerName, violation.MaxMemoryMB, violation.LimitMB)
+			}
+
+			return fmt.Errorf("test failed: %d %w", len(violations), ErrMemoryLimitViolations)
+		}
+	}
+
+	shouldCleanup := config.CleanAfter && (!config.KeepOnFailure || exitCode == 0)
+	if shouldCleanup {
+		if config.Verbose {
+			log.Printf("Running post-test cleanup for run %s...", runID)
+		}
+
+		cleanErr := cleanupAfterTest(ctx, cli, resp.ID, runID)
+
+		if cleanErr != nil && config.Verbose {
+			log.Printf("Warning: post-test cleanup failed: %v", cleanErr)
+		}
+
+		// Clean up artifacts from successful tests to save disk space in CI
+		if exitCode == 0 {
+			if config.Verbose {
+				log.Printf("Test succeeded, cleaning up artifacts to save disk space...")
+			}
+
+			cleanErr := cleanupSuccessfulTestArtifacts(logsDir, config.Verbose)
+
+			if cleanErr != nil && config.Verbose {
+				log.Printf("Warning: artifact cleanup failed: %v", cleanErr)
+			}
+		}
+	}
+
+	if err != nil {
+		return fmt.Errorf("executing test: %w", err)
+	}
+
+	if exitCode != 0 {
+		return fmt.Errorf("%w: exit code %d", ErrTestFailed, exitCode)
+	}
+
+	log.Printf("Test completed successfully!")
+
+	return nil
+}
+
+// buildGoTestCommand constructs the go test command arguments.
+func buildGoTestCommand(config *RunConfig) []string {
+	cmd := []string{"go", "test", "./..."}
+
+	if config.TestPattern != "" {
+		cmd = append(cmd, "-run", config.TestPattern)
+	}
+
+	if config.FailFast {
+		cmd = append(cmd, "-failfast")
+	}
+
+	cmd = append(cmd, "-timeout", config.Timeout.String())
+	cmd = append(cmd, "-v")
+
+	return cmd
+}
+
+// createGoTestContainer creates a Docker container configured for running integration tests.
+func createGoTestContainer(ctx context.Context, cli *client.Client, config *RunConfig, containerName, logsDir string, goTestCmd []string) (container.CreateResponse, error) {
+	pwd, err := os.Getwd()
+	if err != nil {
+		return container.CreateResponse{}, fmt.Errorf("getting working directory: %w", err)
+	}
+
+	projectRoot := findProjectRoot(pwd)
+
+	runID := dockertestutil.ExtractRunIDFromContainerName(containerName)
+
+	env := []string{
+		fmt.Sprintf("HEADSCALE_INTEGRATION_POSTGRES=%d", boolToInt(config.UsePostgres)),
+		"HEADSCALE_INTEGRATION_RUN_ID=" + runID,
+	}
+
+	// Pass through CI environment variable for CI detection
+	if ci := os.Getenv("CI"); ci != "" {
+		env = append(env, "CI="+ci)
+	}
+
+	// Pass through all HEADSCALE_INTEGRATION_* environment variables
+	for _, e := range os.Environ() {
+		if strings.HasPrefix(e, "HEADSCALE_INTEGRATION_") {
+			// Skip the ones we already set explicitly
+			if strings.HasPrefix(e, "HEADSCALE_INTEGRATION_POSTGRES=") ||
+				strings.HasPrefix(e, "HEADSCALE_INTEGRATION_RUN_ID=") {
+				continue
+			}
+
+			env = append(env, e)
+		}
+	}
+
+	// Set GOCACHE to a known location (used by both bind mount and volume cases)
+	env = append(env, "GOCACHE=/cache/go-build")
+
+	containerConfig := &container.Config{
+		Image:      "golang:" + config.GoVersion,
+		Cmd:        goTestCmd,
+		Env:        env,
+		WorkingDir: projectRoot + "/integration",
+		Tty:        true,
+		Labels: map[string]string{
+			"hi.run-id":    runID,
+			"hi.test-type": "test-runner",
+		},
+	}
+
+	// Get the correct Docker socket path from the current context
+	dockerSocketPath := getDockerSocketPath()
+
+	if config.Verbose {
+		log.Printf("Using Docker socket: %s", dockerSocketPath)
+	}
+
+	binds := []string{
+		fmt.Sprintf("%s:%s", projectRoot, projectRoot),
+		dockerSocketPath + ":/var/run/docker.sock",
+		logsDir + ":/tmp/control",
+	}
+
+	// Use bind mounts for Go cache if provided via environment variables,
+	// otherwise fall back to Docker volumes for local development
+	var mounts []mount.Mount
+
+	goCache := os.Getenv("HEADSCALE_INTEGRATION_GO_CACHE")
+	goBuildCache := os.Getenv("HEADSCALE_INTEGRATION_GO_BUILD_CACHE")
+
+	if goCache != "" {
+		binds = append(binds, goCache+":/go")
+	} else {
+		mounts = append(mounts, mount.Mount{
+			Type:   mount.TypeVolume,
+			Source: "hs-integration-go-cache",
+			Target: "/go",
+		})
+	}
+
+	if goBuildCache != "" {
+		binds = append(binds, goBuildCache+":/cache/go-build")
+	} else {
+		mounts = append(mounts, mount.Mount{
+			Type:   mount.TypeVolume,
+			Source: "hs-integration-go-build-cache",
+			Target: "/cache/go-build",
+		})
+	}
+
+	hostConfig := &container.HostConfig{
+		AutoRemove: false, // We'll remove manually for better control
+		Binds:      binds,
+		Mounts:     mounts,
+	}
+
+	return cli.ContainerCreate(ctx, containerConfig, hostConfig, nil, nil, containerName)
+}
+
+// streamAndWait streams container output and waits for completion.
+func streamAndWait(ctx context.Context, cli *client.Client, containerID string) (int, error) {
+	out, err := cli.ContainerLogs(ctx, containerID, container.LogsOptions{
+		ShowStdout: true,
+		ShowStderr: true,
+		Follow:     true,
+	})
+	if err != nil {
+		return -1, fmt.Errorf("getting container logs: %w", err)
+	}
+	defer out.Close()
+
+	go func() {
+		_, _ = io.Copy(os.Stdout, out)
+	}()
+
+	statusCh, errCh := cli.ContainerWait(ctx, containerID, container.WaitConditionNotRunning)
+	select {
+	case err := <-errCh:
+		if err != nil {
+			return -1, fmt.Errorf("waiting for container: %w", err)
+		}
+	case status := <-statusCh:
+		return int(status.StatusCode), nil
+	}
+
+	return -1, ErrUnexpectedContainerWait
+}
+
+// waitForContainerFinalization ensures all test containers have properly finished and flushed their output.
+func waitForContainerFinalization(ctx context.Context, cli *client.Client, testContainerID string, verbose bool) error {
+	// First, get all related test containers
+	containers, err := cli.ContainerList(ctx, container.ListOptions{All: true})
+	if err != nil {
+		return fmt.Errorf("listing containers: %w", err)
+	}
+
+	testContainers := getCurrentTestContainers(containers, testContainerID, verbose)
+
+	// Wait for all test containers to reach a final state
+	maxWaitTime := 10 * time.Second
+	checkInterval := 500 * time.Millisecond
+	timeout := time.After(maxWaitTime)
+
+	ticker := time.NewTicker(checkInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-timeout:
+			if verbose {
+				log.Printf("Timeout waiting for container finalization, proceeding with artifact extraction")
+			}
+
+			return nil
+		case <-ticker.C:
+			allFinalized := true
+
+			for _, testCont := range testContainers {
+				inspect, err := cli.ContainerInspect(ctx, testCont.ID)
+				if err != nil {
+					if verbose {
+						log.Printf("Warning: failed to inspect container %s: %v", testCont.name, err)
+					}
+
+					continue
+				}
+
+				// Check if container is in a final state
+				if !isContainerFinalized(inspect.State) {
+					allFinalized = false
+
+					if verbose {
+						log.Printf("Container %s still finalizing (state: %s)", testCont.name, inspect.State.Status)
+					}
+
+					break
+				}
+			}
+
+			if allFinalized {
+				if verbose {
+					log.Printf("All test containers finalized, ready for artifact extraction")
+				}
+
+				return nil
+			}
+		}
+	}
+}
+
+// isContainerFinalized checks if a container has reached a final state where logs are flushed.
+func isContainerFinalized(state *container.State) bool {
+	// Container is finalized if it's not running and has a finish time
+	return !state.Running && state.FinishedAt != ""
+}
+
+// findProjectRoot locates the project root by finding the directory containing go.mod.
+func findProjectRoot(startPath string) string {
+	current := startPath
+	for {
+		if _, err := os.Stat(filepath.Join(current, "go.mod")); err == nil { //nolint:noinlineerr
+			return current
+		}
+
+		parent := filepath.Dir(current)
+		if parent == current {
+			return startPath
+		}
+
+		current = parent
+	}
+}
+
+// boolToInt converts a boolean to an integer for environment variables.
+func boolToInt(b bool) int {
+	if b {
+		return 1
+	}
+
+	return 0
+}
+
+// DockerContext represents Docker context information.
+type DockerContext struct {
+	Name      string         `json:"Name"`
+	Metadata  map[string]any `json:"Metadata"`
+	Endpoints map[string]any `json:"Endpoints"`
+	Current   bool           `json:"Current"`
+}
+
+// createDockerClient creates a Docker client with context detection.
+func createDockerClient(ctx context.Context) (*client.Client, error) {
+	contextInfo, err := getCurrentDockerContext(ctx)
+	if err != nil {
+		return client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
+	}
+
+	var clientOpts []client.Opt
+
+	clientOpts = append(clientOpts, client.WithAPIVersionNegotiation())
+
+	if contextInfo != nil {
+		if endpoints, ok := contextInfo.Endpoints["docker"]; ok {
+			if endpointMap, ok := endpoints.(map[string]any); ok {
+				if host, ok := endpointMap["Host"].(string); ok {
+					if runConfig.Verbose {
+						log.Printf("Using Docker host from context '%s': %s", contextInfo.Name, host)
+					}
+
+					clientOpts = append(clientOpts, client.WithHost(host))
+				}
+			}
+		}
+	}
+
+	if len(clientOpts) == 1 {
+		clientOpts = append(clientOpts, client.FromEnv)
+	}
+
+	return client.NewClientWithOpts(clientOpts...)
+}
+
+// getCurrentDockerContext retrieves the current Docker context information.
+func getCurrentDockerContext(ctx context.Context) (*DockerContext, error) {
+	cmd := exec.CommandContext(ctx, "docker", "context", "inspect")
+
+	output, err := cmd.Output()
+	if err != nil {
+		return nil, fmt.Errorf("getting docker context: %w", err)
+	}
+
+	var contexts []DockerContext
+	if err := json.Unmarshal(output, &contexts); err != nil { //nolint:noinlineerr
+		return nil, fmt.Errorf("parsing docker context: %w", err)
+	}
+
+	if len(contexts) > 0 {
+		return &contexts[0], nil
+	}
+
+	return nil, ErrNoDockerContext
+}
+
+// getDockerSocketPath returns the correct Docker socket path for the current context.
+func getDockerSocketPath() string {
+	// Always use the default socket path for mounting since Docker handles
+	// the translation to the actual socket (e.g., colima socket) internally
+	return "/var/run/docker.sock"
+}
+
+// checkImageAvailableLocally checks if the specified Docker image is available locally.
+func checkImageAvailableLocally(ctx context.Context, cli *client.Client, imageName string) (bool, error) {
+	_, _, err := cli.ImageInspectWithRaw(ctx, imageName) //nolint:staticcheck // SA1019: deprecated but functional
+	if err != nil {
+		if client.IsErrNotFound(err) { //nolint:staticcheck // SA1019: deprecated but functional
+			return false, nil
+		}
+
+		return false, fmt.Errorf("inspecting image %s: %w", imageName, err)
+	}
+
+	return true, nil
+}
+
+// ensureImageAvailable checks if the image is available locally first, then pulls if needed.
+func ensureImageAvailable(ctx context.Context, cli *client.Client, imageName string, verbose bool) error {
+	// First check if image is available locally
+	available, err := checkImageAvailableLocally(ctx, cli, imageName)
+	if err != nil {
+		return fmt.Errorf("checking local image availability: %w", err)
+	}
+
+	if available {
+		if verbose {
+			log.Printf("Image %s is available locally", imageName)
+		}
+
+		return nil
+	}
+
+	// Image not available locally, try to pull it
+	if verbose {
+		log.Printf("Image %s not found locally, pulling...", imageName)
+	}
+
+	reader, err := cli.ImagePull(ctx, imageName, image.PullOptions{})
+	if err != nil {
+		return fmt.Errorf("pulling image %s: %w", imageName, err)
+	}
+	defer reader.Close()
+
+	if verbose {
+		_, err = io.Copy(os.Stdout, reader)
+		if err != nil {
+			return fmt.Errorf("reading pull output: %w", err)
+		}
+	} else {
+		_, err = io.Copy(io.Discard, reader)
+		if err != nil {
+			return fmt.Errorf("reading pull output: %w", err)
+		}
+
+		log.Printf("Image %s pulled successfully", imageName)
+	}
+
+	return nil
+}
+
+// listControlFiles displays the headscale test artifacts created in the control logs directory.
+func listControlFiles(logsDir string) {
+	entries, err := os.ReadDir(logsDir)
+	if err != nil {
+		log.Printf("Logs directory: %s", logsDir)
+		return
+	}
+
+	var (
+		logFiles  []string
+		dataFiles []string
+		dataDirs  []string
+	)
+
+	for _, entry := range entries {
+		name := entry.Name()
+		// Only show headscale (hs-*) files and directories
+		if !strings.HasPrefix(name, "hs-") {
+			continue
+		}
+
+		if entry.IsDir() {
+			// Include directories (pprof, mapresponses)
+			if strings.Contains(name, "-pprof") || strings.Contains(name, "-mapresponses") {
+				dataDirs = append(dataDirs, name)
+			}
+		} else {
+			// Include files
+			switch {
+			case strings.HasSuffix(name, ".stderr.log") || strings.HasSuffix(name, ".stdout.log"):
+				logFiles = append(logFiles, name)
+			case strings.HasSuffix(name, ".db"):
+				dataFiles = append(dataFiles, name)
+			}
+		}
+	}
+
+	log.Printf("Test artifacts saved to: %s", logsDir)
+
+	if len(logFiles) > 0 {
+		log.Printf("Headscale logs:")
+
+		for _, file := range logFiles {
+			log.Printf("  %s", file)
+		}
+	}
+
+	if len(dataFiles) > 0 || len(dataDirs) > 0 {
+		log.Printf("Headscale data:")
+
+		for _, file := range dataFiles {
+			log.Printf("  %s", file)
+		}
+
+		for _, dir := range dataDirs {
+			log.Printf("  %s/", dir)
+		}
+	}
+}
+
+// extractArtifactsFromContainers collects container logs and files from the specific test run.
+func extractArtifactsFromContainers(ctx context.Context, testContainerID, logsDir string, verbose bool) error {
+	cli, err := createDockerClient(ctx)
+	if err != nil {
+		return fmt.Errorf("creating Docker client: %w", err)
+	}
+	defer cli.Close()
+
+	// List all containers
+	containers, err := cli.ContainerList(ctx, container.ListOptions{All: true})
+	if err != nil {
+		return fmt.Errorf("listing containers: %w", err)
+	}
+
+	// Get containers from the specific test run
+	currentTestContainers := getCurrentTestContainers(containers, testContainerID, verbose)
+
+	extractedCount := 0
+
+	for _, cont := range currentTestContainers {
+		// Extract container logs and tar files
+		err := extractContainerArtifacts(ctx, cli, cont.ID, cont.name, logsDir, verbose)
+		if err != nil {
+			if verbose {
+				log.Printf("Warning: failed to extract artifacts from container %s (%s): %v", cont.name, cont.ID[:12], err)
+			}
+		} else {
+			if verbose {
+				log.Printf("Extracted artifacts from container %s (%s)", cont.name, cont.ID[:12])
+			}
+
+			extractedCount++
+		}
+	}
+
+	if verbose && extractedCount > 0 {
+		log.Printf("Extracted artifacts from %d containers", extractedCount)
+	}
+
+	return nil
+}
+
+// testContainer represents a container from the current test run.
+type testContainer struct {
+	ID   string
+	name string
+}
+
+// getCurrentTestContainers filters containers to only include those from the current test run.
+func getCurrentTestContainers(containers []container.Summary, testContainerID string, verbose bool) []testContainer {
+	var testRunContainers []testContainer
+
+	// Find the test container to get its run ID label
+	var runID string
+
+	for _, cont := range containers {
+		if cont.ID == testContainerID {
+			if cont.Labels != nil {
+				runID = cont.Labels["hi.run-id"]
+			}
+
+			break
+		}
+	}
+
+	if runID == "" {
+		log.Printf("Error: test container %s missing required hi.run-id label", testContainerID[:12])
+		return testRunContainers
+	}
+
+	if verbose {
+		log.Printf("Looking for containers with run ID: %s", runID)
+	}
+
+	// Find all containers with the same run ID
+	for _, cont := range containers {
+		for _, name := range cont.Names {
+			containerName := strings.TrimPrefix(name, "/")
+			if strings.HasPrefix(containerName, "hs-") || strings.HasPrefix(containerName, "ts-") {
+				// Check if container has matching run ID label
+				if cont.Labels != nil && cont.Labels["hi.run-id"] == runID {
+					testRunContainers = append(testRunContainers, testContainer{
+						ID:   cont.ID,
+						name: containerName,
+					})
+					if verbose {
+						log.Printf("Including container %s (run ID: %s)", containerName, runID)
+					}
+				}
+
+				break
+			}
+		}
+	}
+
+	return testRunContainers
+}
+
+// extractContainerArtifacts saves logs and tar files from a container.
+func extractContainerArtifacts(ctx context.Context, cli *client.Client, containerID, containerName, logsDir string, verbose bool) error {
+	// Ensure the logs directory exists
+	err := os.MkdirAll(logsDir, defaultDirPerm)
+	if err != nil {
+		return fmt.Errorf("creating logs directory: %w", err)
+	}
+
+	// Extract container logs
+	err = extractContainerLogs(ctx, cli, containerID, containerName, logsDir, verbose)
+	if err != nil {
+		return fmt.Errorf("extracting logs: %w", err)
+	}
+
+	// Extract tar files for headscale containers only
+	if strings.HasPrefix(containerName, "hs-") {
+		err := extractContainerFiles(ctx, cli, containerID, containerName, logsDir, verbose)
+		if err != nil {
+			if verbose {
+				log.Printf("Warning: failed to extract files from %s: %v", containerName, err)
+			}
+			// Don't fail the whole extraction if files are missing
+		}
+	}
+
+	return nil
+}
+
+// extractContainerLogs saves the stdout and stderr logs from a container to files.
+func extractContainerLogs(ctx context.Context, cli *client.Client, containerID, containerName, logsDir string, verbose bool) error {
+	// Get container logs
+	logReader, err := cli.ContainerLogs(ctx, containerID, container.LogsOptions{
+		ShowStdout: true,
+		ShowStderr: true,
+		Timestamps: false,
+		Follow:     false,
+		Tail:       "all",
+	})
+	if err != nil {
+		return fmt.Errorf("getting container logs: %w", err)
+	}
+	defer logReader.Close()
+
+	// Create log files following the headscale naming convention
+	stdoutPath := filepath.Join(logsDir, containerName+".stdout.log")
+	stderrPath := filepath.Join(logsDir, containerName+".stderr.log")
+
+	// Create buffers to capture stdout and stderr separately
+	var stdoutBuf, stderrBuf bytes.Buffer
+
+	// Demultiplex the Docker logs stream to separate stdout and stderr
+	_, err = stdcopy.StdCopy(&stdoutBuf, &stderrBuf, logReader)
+	if err != nil {
+		return fmt.Errorf("demultiplexing container logs: %w", err)
+	}
+
+	// Write stdout logs
+	if err := os.WriteFile(stdoutPath, stdoutBuf.Bytes(), 0o644); err != nil { //nolint:gosec,noinlineerr // log files should be readable
+		return fmt.Errorf("writing stdout log: %w", err)
+	}
+
+	// Write stderr logs
+	if err := os.WriteFile(stderrPath, stderrBuf.Bytes(), 0o644); err != nil { //nolint:gosec,noinlineerr // log files should be readable
+		return fmt.Errorf("writing stderr log: %w", err)
+	}
+
+	if verbose {
+		log.Printf("Saved logs for %s: %s, %s", containerName, stdoutPath, stderrPath)
+	}
+
+	return nil
+}
+
+// extractContainerFiles extracts database file and directories from headscale containers.
+// Note: The actual file extraction is now handled by the integration tests themselves
+// via SaveProfile, SaveMapResponses, and SaveDatabase functions in hsic.go.
+func extractContainerFiles(ctx context.Context, cli *client.Client, containerID, containerName, logsDir string, verbose bool) error {
+	// Files are now extracted directly by the integration tests
+	// This function is kept for potential future use or other file types
+	return nil
+}

cmd/hi/doctor.go

@@ -0,0 +1,380 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"log"
+	"os/exec"
+	"strings"
+)
+
+var ErrSystemChecksFailed = errors.New("system checks failed")
+
+// DoctorResult represents the result of a single health check.
+type DoctorResult struct {
+	Name        string
+	Status      string // "PASS", "FAIL", "WARN"
+	Message     string
+	Suggestions []string
+}
+
+// runDoctorCheck performs comprehensive pre-flight checks for integration testing.
+func runDoctorCheck(ctx context.Context) error {
+	results := []DoctorResult{}
+
+	// Check 1: Docker binary availability
+	results = append(results, checkDockerBinary())
+
+	// Check 2: Docker daemon connectivity
+	dockerResult := checkDockerDaemon(ctx)
+	results = append(results, dockerResult)
+
+	// If Docker is available, run additional checks
+	if dockerResult.Status == "PASS" {
+		results = append(results, checkDockerContext(ctx))
+		results = append(results, checkDockerSocket(ctx))
+		results = append(results, checkGolangImage(ctx))
+	}
+
+	// Check 3: Go installation
+	results = append(results, checkGoInstallation(ctx))
+
+	// Check 4: Git repository
+	results = append(results, checkGitRepository(ctx))
+
+	// Check 5: Required files
+	results = append(results, checkRequiredFiles(ctx))
+
+	// Display results
+	displayDoctorResults(results)
+
+	// Return error if any critical checks failed
+	for _, result := range results {
+		if result.Status == "FAIL" {
+			return fmt.Errorf("%w - see details above", ErrSystemChecksFailed)
+		}
+	}
+
+	log.Printf("✅ All system checks passed - ready to run integration tests!")
+
+	return nil
+}
+
+// checkDockerBinary verifies Docker binary is available.
+func checkDockerBinary() DoctorResult {
+	_, err := exec.LookPath("docker")
+	if err != nil {
+		return DoctorResult{
+			Name:    "Docker Binary",
+			Status:  "FAIL",
+			Message: "Docker binary not found in PATH",
+			Suggestions: []string{
+				"Install Docker: https://docs.docker.com/get-docker/",
+				"For macOS: consider using colima or Docker Desktop",
+				"Ensure docker is in your PATH",
+			},
+		}
+	}
+
+	return DoctorResult{
+		Name:    "Docker Binary",
+		Status:  "PASS",
+		Message: "Docker binary found",
+	}
+}
+
+// checkDockerDaemon verifies Docker daemon is running and accessible.
+func checkDockerDaemon(ctx context.Context) DoctorResult {
+	cli, err := createDockerClient(ctx)
+	if err != nil {
+		return DoctorResult{
+			Name:    "Docker Daemon",
+			Status:  "FAIL",
+			Message: fmt.Sprintf("Cannot create Docker client: %v", err),
+			Suggestions: []string{
+				"Start Docker daemon/service",
+				"Check Docker Desktop is running (if using Docker Desktop)",
+				"For colima: run 'colima start'",
+				"Verify DOCKER_HOST environment variable if set",
+			},
+		}
+	}
+	defer cli.Close()
+
+	_, err = cli.Ping(ctx)
+	if err != nil {
+		return DoctorResult{
+			Name:    "Docker Daemon",
+			Status:  "FAIL",
+			Message: fmt.Sprintf("Cannot ping Docker daemon: %v", err),
+			Suggestions: []string{
+				"Ensure Docker daemon is running",
+				"Check Docker socket permissions",
+				"Try: docker info",
+			},
+		}
+	}
+
+	return DoctorResult{
+		Name:    "Docker Daemon",
+		Status:  "PASS",
+		Message: "Docker daemon is running and accessible",
+	}
+}
+
+// checkDockerContext verifies Docker context configuration.
+func checkDockerContext(ctx context.Context) DoctorResult {
+	contextInfo, err := getCurrentDockerContext(ctx)
+	if err != nil {
+		return DoctorResult{
+			Name:    "Docker Context",
+			Status:  "WARN",
+			Message: "Could not detect Docker context, using default settings",
+			Suggestions: []string{
+				"Check: docker context ls",
+				"Consider setting up a specific context if needed",
+			},
+		}
+	}
+
+	if contextInfo == nil {
+		return DoctorResult{
+			Name:    "Docker Context",
+			Status:  "PASS",
+			Message: "Using default Docker context",
+		}
+	}
+
+	return DoctorResult{
+		Name:    "Docker Context",
+		Status:  "PASS",
+		Message: "Using Docker context: " + contextInfo.Name,
+	}
+}
+
+// checkDockerSocket verifies Docker socket accessibility.
+func checkDockerSocket(ctx context.Context) DoctorResult {
+	cli, err := createDockerClient(ctx)
+	if err != nil {
+		return DoctorResult{
+			Name:    "Docker Socket",
+			Status:  "FAIL",
+			Message: fmt.Sprintf("Cannot access Docker socket: %v", err),
+			Suggestions: []string{
+				"Check Docker socket permissions",
+				"Add user to docker group: sudo usermod -aG docker $USER",
+				"For colima: ensure socket is accessible",
+			},
+		}
+	}
+	defer cli.Close()
+
+	info, err := cli.Info(ctx)
+	if err != nil {
+		return DoctorResult{
+			Name:    "Docker Socket",
+			Status:  "FAIL",
+			Message: fmt.Sprintf("Cannot get Docker info: %v", err),
+			Suggestions: []string{
+				"Check Docker daemon status",
+				"Verify socket permissions",
+			},
+		}
+	}
+
+	return DoctorResult{
+		Name:    "Docker Socket",
+		Status:  "PASS",
+		Message: fmt.Sprintf("Docker socket accessible (Server: %s)", info.ServerVersion),
+	}
+}
+
+// checkGolangImage verifies the golang Docker image is available locally or can be pulled.
+func checkGolangImage(ctx context.Context) DoctorResult {
+	cli, err := createDockerClient(ctx)
+	if err != nil {
+		return DoctorResult{
+			Name:    "Golang Image",
+			Status:  "FAIL",
+			Message: "Cannot create Docker client for image check",
+		}
+	}
+	defer cli.Close()
+
+	goVersion := detectGoVersion()
+	imageName := "golang:" + goVersion
+
+	// First check if image is available locally
+	available, err := checkImageAvailableLocally(ctx, cli, imageName)
+	if err != nil {
+		return DoctorResult{
+			Name:    "Golang Image",
+			Status:  "FAIL",
+			Message: fmt.Sprintf("Cannot check golang image %s: %v", imageName, err),
+			Suggestions: []string{
+				"Check Docker daemon status",
+				"Try: docker images | grep golang",
+			},
+		}
+	}
+
+	if available {
+		return DoctorResult{
+			Name:    "Golang Image",
+			Status:  "PASS",
+			Message: fmt.Sprintf("Golang image %s is available locally", imageName),
+		}
+	}
+
+	// Image not available locally, try to pull it
+	err = ensureImageAvailable(ctx, cli, imageName, false)
+	if err != nil {
+		return DoctorResult{
+			Name:    "Golang Image",
+			Status:  "FAIL",
+			Message: fmt.Sprintf("Golang image %s not available locally and cannot pull: %v", imageName, err),
+			Suggestions: []string{
+				"Check internet connectivity",
+				"Verify Docker Hub access",
+				"Try: docker pull " + imageName,
+				"Or run tests offline if image was pulled previously",
+			},
+		}
+	}
+
+	return DoctorResult{
+		Name:    "Golang Image",
+		Status:  "PASS",
+		Message: fmt.Sprintf("Golang image %s is now available", imageName),
+	}
+}
+
+// checkGoInstallation verifies Go is installed and working.
+func checkGoInstallation(ctx context.Context) DoctorResult {
+	_, err := exec.LookPath("go")
+	if err != nil {
+		return DoctorResult{
+			Name:    "Go Installation",
+			Status:  "FAIL",
+			Message: "Go binary not found in PATH",
+			Suggestions: []string{
+				"Install Go: https://golang.org/dl/",
+				"Ensure go is in your PATH",
+			},
+		}
+	}
+
+	cmd := exec.CommandContext(ctx, "go", "version")
+
+	output, err := cmd.Output()
+	if err != nil {
+		return DoctorResult{
+			Name:    "Go Installation",
+			Status:  "FAIL",
+			Message: fmt.Sprintf("Cannot get Go version: %v", err),
+		}
+	}
+
+	version := strings.TrimSpace(string(output))
+
+	return DoctorResult{
+		Name:    "Go Installation",
+		Status:  "PASS",
+		Message: version,
+	}
+}
+
+// checkGitRepository verifies we're in a git repository.
+func checkGitRepository(ctx context.Context) DoctorResult {
+	cmd := exec.CommandContext(ctx, "git", "rev-parse", "--git-dir")
+
+	err := cmd.Run()
+	if err != nil {
+		return DoctorResult{
+			Name:    "Git Repository",
+			Status:  "FAIL",
+			Message: "Not in a Git repository",
+			Suggestions: []string{
+				"Run from within the headscale git repository",
+				"Clone the repository: git clone https://github.com/juanfont/headscale.git",
+			},
+		}
+	}
+
+	return DoctorResult{
+		Name:    "Git Repository",
+		Status:  "PASS",
+		Message: "Running in Git repository",
+	}
+}
+
+// checkRequiredFiles verifies required files exist.
+func checkRequiredFiles(ctx context.Context) DoctorResult {
+	requiredFiles := []string{
+		"go.mod",
+		"integration/",
+		"cmd/hi/",
+	}
+
+	var missingFiles []string
+
+	for _, file := range requiredFiles {
+		cmd := exec.CommandContext(ctx, "test", "-e", file)
+
+		err := cmd.Run()
+		if err != nil {
+			missingFiles = append(missingFiles, file)
+		}
+	}
+
+	if len(missingFiles) > 0 {
+		return DoctorResult{
+			Name:    "Required Files",
+			Status:  "FAIL",
+			Message: "Missing required files: " + strings.Join(missingFiles, ", "),
+			Suggestions: []string{
+				"Ensure you're in the headscale project root directory",
+				"Check that integration/ directory exists",
+				"Verify this is a complete headscale repository",
+			},
+		}
+	}
+
+	return DoctorResult{
+		Name:    "Required Files",
+		Status:  "PASS",
+		Message: "All required files found",
+	}
+}
+
+// displayDoctorResults shows the results in a formatted way.
+func displayDoctorResults(results []DoctorResult) {
+	log.Printf("🔍 System Health Check Results")
+	log.Printf("================================")
+
+	for _, result := range results {
+		var icon string
+
+		switch result.Status {
+		case "PASS":
+			icon = "✅"
+		case "WARN":
+			icon = "⚠️"
+		case "FAIL":
+			icon = "❌"
+		default:
+			icon = "❓"
+		}
+
+		log.Printf("%s %s: %s", icon, result.Name, result.Message)
+
+		if len(result.Suggestions) > 0 {
+			for _, suggestion := range result.Suggestions {
+				log.Printf("   💡 %s", suggestion)
+			}
+		}
+	}
+
+	log.Printf("================================")
+}

cmd/hi/main.go

@@ -0,0 +1,98 @@
+package main
+
+import (
+	"context"
+	"os"
+
+	"github.com/creachadair/command"
+	"github.com/creachadair/flax"
+)
+
+var runConfig RunConfig
+
+func main() {
+	root := command.C{
+		Name: "hi",
+		Help: "Headscale Integration test runner",
+		Commands: []*command.C{
+			{
+				Name:     "run",
+				Help:     "Run integration tests",
+				Usage:    "run [test-pattern] [flags]",
+				SetFlags: command.Flags(flax.MustBind, &runConfig),
+				Run:      runIntegrationTest,
+			},
+			{
+				Name: "doctor",
+				Help: "Check system requirements for running integration tests",
+				Run: func(env *command.Env) error {
+					return runDoctorCheck(env.Context())
+				},
+			},
+			{
+				Name: "clean",
+				Help: "Clean Docker resources",
+				Commands: []*command.C{
+					{
+						Name: "networks",
+						Help: "Prune unused Docker networks",
+						Run: func(env *command.Env) error {
+							return pruneDockerNetworks(env.Context())
+						},
+					},
+					{
+						Name: "images",
+						Help: "Clean old test images",
+						Run: func(env *command.Env) error {
+							return cleanOldImages(env.Context())
+						},
+					},
+					{
+						Name: "containers",
+						Help: "Kill all test containers",
+						Run: func(env *command.Env) error {
+							return killTestContainers(env.Context())
+						},
+					},
+					{
+						Name: "cache",
+						Help: "Clean Go module cache volume",
+						Run: func(env *command.Env) error {
+							return cleanCacheVolume(env.Context())
+						},
+					},
+					{
+						Name: "all",
+						Help: "Run all cleanup operations",
+						Run: func(env *command.Env) error {
+							return cleanAll(env.Context())
+						},
+					},
+				},
+			},
+			command.HelpCommand(nil),
+		},
+	}
+
+	env := root.NewEnv(nil).MergeFlags(true)
+	command.RunOrFail(env, os.Args[1:])
+}
+
+func cleanAll(ctx context.Context) error {
+	err := killTestContainers(ctx)
+	if err != nil {
+		return err
+	}
+
+	err = pruneDockerNetworks(ctx)
+	if err != nil {
+		return err
+	}
+
+	err = cleanOldImages(ctx)
+	if err != nil {
+		return err
+	}
+
+	return cleanCacheVolume(ctx)
+}

cmd/hi/run.go

@@ -0,0 +1,129 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/creachadair/command"
+)
+
+var ErrTestPatternRequired = errors.New("test pattern is required as first argument or use --test flag")
+
+type RunConfig struct {
+	TestPattern   string        `flag:"test,Test pattern to run"`
+	Timeout       time.Duration `flag:"timeout,default=120m,Test timeout"`
+	FailFast      bool          `flag:"failfast,default=true,Stop on first test failure"`
+	UsePostgres   bool          `flag:"postgres,default=false,Use PostgreSQL instead of SQLite"`
+	GoVersion     string        `flag:"go-version,Go version to use (auto-detected from go.mod)"`
+	CleanBefore   bool          `flag:"clean-before,default=true,Clean stale resources before test"`
+	CleanAfter    bool          `flag:"clean-after,default=true,Clean resources after test"`
+	KeepOnFailure bool          `flag:"keep-on-failure,default=false,Keep containers on test failure"`
+	LogsDir       string        `flag:"logs-dir,default=control_logs,Control logs directory"`
+	Verbose       bool          `flag:"verbose,default=false,Verbose output"`
+	Stats         bool          `flag:"stats,default=false,Collect and display container resource usage statistics"`
+	HSMemoryLimit float64       `flag:"hs-memory-limit,default=0,Fail test if any Headscale container exceeds this memory limit in MB (0 = disabled)"`
+	TSMemoryLimit float64       `flag:"ts-memory-limit,default=0,Fail test if any Tailscale container exceeds this memory limit in MB (0 = disabled)"`
+}
+
+// runIntegrationTest executes the integration test workflow.
+func runIntegrationTest(env *command.Env) error {
+	args := env.Args
+	if len(args) > 0 && runConfig.TestPattern == "" {
+		runConfig.TestPattern = args[0]
+	}
+
+	if runConfig.TestPattern == "" {
+		return ErrTestPatternRequired
+	}
+
+	if runConfig.GoVersion == "" {
+		runConfig.GoVersion = detectGoVersion()
+	}
+
+	// Run pre-flight checks
+	if runConfig.Verbose {
+		log.Printf("Running pre-flight system checks...")
+	}
+
+	err := runDoctorCheck(env.Context())
+	if err != nil {
+		return fmt.Errorf("pre-flight checks failed: %w", err)
+	}
+
+	if runConfig.Verbose {
+		log.Printf("Running test: %s", runConfig.TestPattern)
+		log.Printf("Go version: %s", runConfig.GoVersion)
+		log.Printf("Timeout: %s", runConfig.Timeout)
+		log.Printf("Use PostgreSQL: %t", runConfig.UsePostgres)
+	}
+
+	return runTestContainer(env.Context(), &runConfig)
+}
+
+// detectGoVersion reads the Go version from go.mod file.
+func detectGoVersion() string {
+	goModPath := filepath.Join("..", "..", "go.mod")
+
+	if _, err := os.Stat("go.mod"); err == nil { //nolint:noinlineerr
+		goModPath = "go.mod"
+	} else if _, err := os.Stat("../../go.mod"); err == nil { //nolint:noinlineerr
+		goModPath = "../../go.mod"
+	}
+
+	content, err := os.ReadFile(goModPath)
+	if err != nil {
+		return "1.26.1"
+	}
+
+	lines := splitLines(string(content))
+	for _, line := range lines {
+		if len(line) > 3 && line[:3] == "go " {
+			version := line[3:]
+			if idx := indexOf(version, " "); idx != -1 {
+				version = version[:idx]
+			}
+
+			return version
+		}
+	}
+
+	return "1.26.1"
+}
+
+// splitLines splits a string into lines without using strings.Split.
+func splitLines(s string) []string {
+	var (
+		lines   []string
+		current string
+	)
+
+	for _, char := range s {
+		if char == '\n' {
+			lines = append(lines, current)
+			current = ""
+		} else {
+			current += string(char)
+		}
+	}
+
+	if current != "" {
+		lines = append(lines, current)
+	}
+
+	return lines
+}
+
+// indexOf finds the first occurrence of substr in s.
+func indexOf(s, substr string) int {
+	for i := 0; i <= len(s)-len(substr); i++ {
+		if s[i:i+len(substr)] == substr {
+			return i
+		}
+	}
+
+	return -1
+}

cmd/hi/stats.go

@@ -0,0 +1,493 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/docker/docker/api/types"
+	"github.com/docker/docker/api/types/container"
+	"github.com/docker/docker/api/types/events"
+	"github.com/docker/docker/api/types/filters"
+	"github.com/docker/docker/client"
+)
+
+// ErrStatsCollectionAlreadyStarted is returned when trying to start stats collection that is already running.
+var ErrStatsCollectionAlreadyStarted = errors.New("stats collection already started")
+
+// ContainerStats represents statistics for a single container.
+type ContainerStats struct {
+	ContainerID   string
+	ContainerName string
+	Stats         []StatsSample
+	mutex         sync.RWMutex
+}
+
+// StatsSample represents a single stats measurement.
+type StatsSample struct {
+	Timestamp time.Time
+	CPUUsage  float64 // CPU usage percentage
+	MemoryMB  float64 // Memory usage in MB
+}
+
+// StatsCollector manages collection of container statistics.
+type StatsCollector struct {
+	client            *client.Client
+	containers        map[string]*ContainerStats
+	stopChan          chan struct{}
+	wg                sync.WaitGroup
+	mutex             sync.RWMutex
+	collectionStarted bool
+}
+
+// NewStatsCollector creates a new stats collector instance.
+func NewStatsCollector(ctx context.Context) (*StatsCollector, error) {
+	cli, err := createDockerClient(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("creating Docker client: %w", err)
+	}
+
+	return &StatsCollector{
+		client:     cli,
+		containers: make(map[string]*ContainerStats),
+		stopChan:   make(chan struct{}),
+	}, nil
+}
+
+// StartCollection begins monitoring all containers and collecting stats for hs- and ts- containers with matching run ID.
+func (sc *StatsCollector) StartCollection(ctx context.Context, runID string, verbose bool) error {
+	sc.mutex.Lock()
+	defer sc.mutex.Unlock()
+
+	if sc.collectionStarted {
+		return ErrStatsCollectionAlreadyStarted
+	}
+
+	sc.collectionStarted = true
+
+	// Start monitoring existing containers
+	sc.wg.Add(1)
+
+	go sc.monitorExistingContainers(ctx, runID, verbose)
+
+	// Start Docker events monitoring for new containers
+	sc.wg.Add(1)
+
+	go sc.monitorDockerEvents(ctx, runID, verbose)
+
+	if verbose {
+		log.Printf("Started container monitoring for run ID %s", runID)
+	}
+
+	return nil
+}
+
+// StopCollection stops all stats collection.
+func (sc *StatsCollector) StopCollection() {
+	// Check if already stopped without holding lock
+	sc.mutex.RLock()
+
+	if !sc.collectionStarted {
+		sc.mutex.RUnlock()
+		return
+	}
+
+	sc.mutex.RUnlock()
+
+	// Signal stop to all goroutines
+	close(sc.stopChan)
+
+	// Wait for all goroutines to finish
+	sc.wg.Wait()
+
+	// Mark as stopped
+	sc.mutex.Lock()
+	sc.collectionStarted = false
+	sc.mutex.Unlock()
+}
+
+// monitorExistingContainers checks for existing containers that match our criteria.
+func (sc *StatsCollector) monitorExistingContainers(ctx context.Context, runID string, verbose bool) {
+	defer sc.wg.Done()
+
+	containers, err := sc.client.ContainerList(ctx, container.ListOptions{})
+	if err != nil {
+		if verbose {
+			log.Printf("Failed to list existing containers: %v", err)
+		}
+
+		return
+	}
+
+	for _, cont := range containers {
+		if sc.shouldMonitorContainer(cont, runID) {
+			sc.startStatsForContainer(ctx, cont.ID, cont.Names[0], verbose)
+		}
+	}
+}
+
+// monitorDockerEvents listens for container start events and begins monitoring relevant containers.
+func (sc *StatsCollector) monitorDockerEvents(ctx context.Context, runID string, verbose bool) {
+	defer sc.wg.Done()
+
+	filter := filters.NewArgs()
+	filter.Add("type", "container")
+	filter.Add("event", "start")
+
+	eventOptions := events.ListOptions{
+		Filters: filter,
+	}
+
+	events, errs := sc.client.Events(ctx, eventOptions)
+
+	for {
+		select {
+		case <-sc.stopChan:
+			return
+		case <-ctx.Done():
+			return
+		case event := <-events:
+			if event.Type == "container" && event.Action == "start" {
+				// Get container details
+				containerInfo, err := sc.client.ContainerInspect(ctx, event.ID) //nolint:staticcheck // SA1019: use Actor.ID
+				if err != nil {
+					continue
+				}
+
+				// Convert to types.Container format for consistency
+				cont := types.Container{ //nolint:staticcheck // SA1019: use container.Summary
+					ID:     containerInfo.ID,
+					Names:  []string{containerInfo.Name},
+					Labels: containerInfo.Config.Labels,
+				}
+
+				if sc.shouldMonitorContainer(cont, runID) {
+					sc.startStatsForContainer(ctx, cont.ID, cont.Names[0], verbose)
+				}
+			}
+		case err := <-errs:
+			if verbose {
+				log.Printf("Error in Docker events stream: %v", err)
+			}
+
+			return
+		}
+	}
+}
+
+// shouldMonitorContainer determines if a container should be monitored.
+func (sc *StatsCollector) shouldMonitorContainer(cont types.Container, runID string) bool { //nolint:staticcheck // SA1019: use container.Summary
+	// Check if it has the correct run ID label
+	if cont.Labels == nil || cont.Labels["hi.run-id"] != runID {
+		return false
+	}
+
+	// Check if it's an hs- or ts- container
+	for _, name := range cont.Names {
+		containerName := strings.TrimPrefix(name, "/")
+		if strings.HasPrefix(containerName, "hs-") || strings.HasPrefix(containerName, "ts-") {
+			return true
+		}
+	}
+
+	return false
+}
+
+// startStatsForContainer begins stats collection for a specific container.
+func (sc *StatsCollector) startStatsForContainer(ctx context.Context, containerID, containerName string, verbose bool) {
+	containerName = strings.TrimPrefix(containerName, "/")
+
+	sc.mutex.Lock()
+	// Check if we're already monitoring this container
+	if _, exists := sc.containers[containerID]; exists {
+		sc.mutex.Unlock()
+		return
+	}
+
+	sc.containers[containerID] = &ContainerStats{
+		ContainerID:   containerID,
+		ContainerName: containerName,
+		Stats:         make([]StatsSample, 0),
+	}
+	sc.mutex.Unlock()
+
+	if verbose {
+		log.Printf("Starting stats collection for container %s (%s)", containerName, containerID[:12])
+	}
+
+	sc.wg.Add(1)
+
+	go sc.collectStatsForContainer(ctx, containerID, verbose)
+}
+
+// collectStatsForContainer collects stats for a specific container using Docker API streaming.
+func (sc *StatsCollector) collectStatsForContainer(ctx context.Context, containerID string, verbose bool) {
+	defer sc.wg.Done()
+
+	// Use Docker API streaming stats - much more efficient than CLI
+	statsResponse, err := sc.client.ContainerStats(ctx, containerID, true)
+	if err != nil {
+		if verbose {
+			log.Printf("Failed to get stats stream for container %s: %v", containerID[:12], err)
+		}
+
+		return
+	}
+	defer statsResponse.Body.Close()
+
+	decoder := json.NewDecoder(statsResponse.Body)
+
+	var prevStats *container.Stats //nolint:staticcheck // SA1019: use StatsResponse
+
+	for {
+		select {
+		case <-sc.stopChan:
+			return
+		case <-ctx.Done():
+			return
+		default:
+			var stats container.Stats //nolint:staticcheck // SA1019: use StatsResponse
+
+			err := decoder.Decode(&stats)
+			if err != nil {
+				// EOF is expected when container stops or stream ends
+				if err.Error() != "EOF" && verbose {
+					log.Printf("Failed to decode stats for container %s: %v", containerID[:12], err)
+				}
+
+				return
+			}
+
+			// Calculate CPU percentage (only if we have previous stats)
+			var cpuPercent float64
+			if prevStats != nil {
+				cpuPercent = calculateCPUPercent(prevStats, &stats)
+			}
+
+			// Calculate memory usage in MB
+			memoryMB := float64(stats.MemoryStats.Usage) / (1024 * 1024)
+
+			// Store the sample (skip first sample since CPU calculation needs previous stats)
+			if prevStats != nil {
+				// Get container stats reference without holding the main mutex
+				var (
+					containerStats *ContainerStats
+					exists         bool
+				)
+
+				sc.mutex.RLock()
+				containerStats, exists = sc.containers[containerID]
+				sc.mutex.RUnlock()
+
+				if exists && containerStats != nil {
+					containerStats.mutex.Lock()
+					containerStats.Stats = append(containerStats.Stats, StatsSample{
+						Timestamp: time.Now(),
+						CPUUsage:  cpuPercent,
+						MemoryMB:  memoryMB,
+					})
+					containerStats.mutex.Unlock()
+				}
+			}
+
+			// Save current stats for next iteration
+			prevStats = &stats
+		}
+	}
+}
+
+// calculateCPUPercent calculates CPU usage percentage from Docker stats.
+func calculateCPUPercent(prevStats, stats *container.Stats) float64 { //nolint:staticcheck // SA1019: use StatsResponse
+	// CPU calculation based on Docker's implementation
+	cpuDelta := float64(stats.CPUStats.CPUUsage.TotalUsage) - float64(prevStats.CPUStats.CPUUsage.TotalUsage)
+	systemDelta := float64(stats.CPUStats.SystemUsage) - float64(prevStats.CPUStats.SystemUsage)
+
+	if systemDelta > 0 && cpuDelta >= 0 {
+		// Calculate CPU percentage: (container CPU delta / system CPU delta) * number of CPUs * 100
+		numCPUs := float64(len(stats.CPUStats.CPUUsage.PercpuUsage))
+		if numCPUs == 0 {
+			// Fallback: if PercpuUsage is not available, assume 1 CPU
+			numCPUs = 1.0
+		}
+
+		return (cpuDelta / systemDelta) * numCPUs * 100.0
+	}
+
+	return 0.0
+}
+
+// ContainerStatsSummary represents summary statistics for a container.
+type ContainerStatsSummary struct {
+	ContainerName string
+	SampleCount   int
+	CPU           StatsSummary
+	Memory        StatsSummary
+}
+
+// MemoryViolation represents a container that exceeded the memory limit.
+type MemoryViolation struct {
+	ContainerName string
+	MaxMemoryMB   float64
+	LimitMB       float64
+}
+
+// StatsSummary represents min, max, and average for a metric.
+type StatsSummary struct {
+	Min     float64
+	Max     float64
+	Average float64
+}
+
+// GetSummary returns a summary of collected statistics.
+func (sc *StatsCollector) GetSummary() []ContainerStatsSummary {
+	// Take snapshot of container references without holding main lock long
+	sc.mutex.RLock()
+
+	containerRefs := make([]*ContainerStats, 0, len(sc.containers))
+	for _, containerStats := range sc.containers {
+		containerRefs = append(containerRefs, containerStats)
+	}
+
+	sc.mutex.RUnlock()
+
+	summaries := make([]ContainerStatsSummary, 0, len(containerRefs))
+
+	for _, containerStats := range containerRefs {
+		containerStats.mutex.RLock()
+		stats := make([]StatsSample, len(containerStats.Stats))
+		copy(stats, containerStats.Stats)
+		containerName := containerStats.ContainerName
+		containerStats.mutex.RUnlock()
+
+		if len(stats) == 0 {
+			continue
+		}
+
+		summary := ContainerStatsSummary{
+			ContainerName: containerName,
+			SampleCount:   len(stats),
+		}
+
+		// Calculate CPU stats
+		cpuValues := make([]float64, len(stats))
+		memoryValues := make([]float64, len(stats))
+
+		for i, sample := range stats {
+			cpuValues[i] = sample.CPUUsage
+			memoryValues[i] = sample.MemoryMB
+		}
+
+		summary.CPU = calculateStatsSummary(cpuValues)
+		summary.Memory = calculateStatsSummary(memoryValues)
+
+		summaries = append(summaries, summary)
+	}
+
+	// Sort by container name for consistent output
+	sort.Slice(summaries, func(i, j int) bool {
+		return summaries[i].ContainerName < summaries[j].ContainerName
+	})
+
+	return summaries
+}
+
+// calculateStatsSummary calculates min, max, and average for a slice of values.
+func calculateStatsSummary(values []float64) StatsSummary {
+	if len(values) == 0 {
+		return StatsSummary{}
+	}
+
+	minVal := values[0]
+	maxVal := values[0]
+	sum := 0.0
+
+	for _, value := range values {
+		if value < minVal {
+			minVal = value
+		}
+
+		if value > maxVal {
+			maxVal = value
+		}
+
+		sum += value
+	}
+
+	return StatsSummary{
+		Min:     minVal,
+		Max:     maxVal,
+		Average: sum / float64(len(values)),
+	}
+}
+
+// PrintSummary prints the statistics summary to the console.
+func (sc *StatsCollector) PrintSummary() {
+	summaries := sc.GetSummary()
+
+	if len(summaries) == 0 {
+		log.Printf("No container statistics collected")
+		return
+	}
+
+	log.Printf("Container Resource Usage Summary:")
+	log.Printf("================================")
+
+	for _, summary := range summaries {
+		log.Printf("Container: %s (%d samples)", summary.ContainerName, summary.SampleCount)
+		log.Printf("  CPU Usage:    Min: %6.2f%%  Max: %6.2f%%  Avg: %6.2f%%",
+			summary.CPU.Min, summary.CPU.Max, summary.CPU.Average)
+		log.Printf("  Memory Usage: Min: %6.1f MB Max: %6.1f MB Avg: %6.1f MB",
+			summary.Memory.Min, summary.Memory.Max, summary.Memory.Average)
+		log.Printf("")
+	}
+}
+
+// CheckMemoryLimits checks if any containers exceeded their memory limits.
+func (sc *StatsCollector) CheckMemoryLimits(hsLimitMB, tsLimitMB float64) []MemoryViolation {
+	if hsLimitMB <= 0 && tsLimitMB <= 0 {
+		return nil
+	}
+
+	summaries := sc.GetSummary()
+
+	var violations []MemoryViolation
+
+	for _, summary := range summaries {
+		var limitMB float64
+		if strings.HasPrefix(summary.ContainerName, "hs-") {
+			limitMB = hsLimitMB
+		} else if strings.HasPrefix(summary.ContainerName, "ts-") {
+			limitMB = tsLimitMB
+		} else {
+			continue // Skip containers that don't match our patterns
+		}
+
+		if limitMB > 0 && summary.Memory.Max > limitMB {
+			violations = append(violations, MemoryViolation{
+				ContainerName: summary.ContainerName,
+				MaxMemoryMB:   summary.Memory.Max,
+				LimitMB:       limitMB,
+			})
+		}
+	}
+
+	return violations
+}
+
+// PrintSummaryAndCheckLimits prints the statistics summary and returns memory violations if any.
+func (sc *StatsCollector) PrintSummaryAndCheckLimits(hsLimitMB, tsLimitMB float64) []MemoryViolation {
+	sc.PrintSummary()
+	return sc.CheckMemoryLimits(hsLimitMB, tsLimitMB)
+}
+
+// Close closes the stats collector and cleans up resources.
+func (sc *StatsCollector) Close() error {
+	sc.StopCollection()
+	return sc.client.Close()
+}

cmd/mapresponses/main.go

@@ -0,0 +1,66 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+
+	"github.com/creachadair/command"
+	"github.com/creachadair/flax"
+	"github.com/juanfont/headscale/hscontrol/mapper"
+	"github.com/juanfont/headscale/integration/integrationutil"
+)
+
+type MapConfig struct {
+	Directory string `flag:"directory,Directory to read map responses from"`
+}
+
+var (
+	mapConfig            MapConfig
+	errDirectoryRequired = errors.New("directory is required")
+)
+
+func main() {
+	root := command.C{
+		Name: "mapresponses",
+		Help: "MapResponses is a tool to map and compare map responses from a directory",
+		Commands: []*command.C{
+			{
+				Name:     "online",
+				Help:     "",
+				Usage:    "run [test-pattern] [flags]",
+				SetFlags: command.Flags(flax.MustBind, &mapConfig),
+				Run:      runOnline,
+			},
+			command.HelpCommand(nil),
+		},
+	}
+
+	env := root.NewEnv(nil).MergeFlags(true)
+	command.RunOrFail(env, os.Args[1:])
+}
+
+// runIntegrationTest executes the integration test workflow.
+func runOnline(env *command.Env) error {
+	if mapConfig.Directory == "" {
+		return errDirectoryRequired
+	}
+
+	resps, err := mapper.ReadMapResponsesFromDirectory(mapConfig.Directory)
+	if err != nil {
+		return fmt.Errorf("reading map responses from directory: %w", err)
+	}
+
+	expected := integrationutil.BuildExpectedOnlineMap(resps)
+
+	out, err := json.MarshalIndent(expected, "", "  ")
+	if err != nil {
+		return fmt.Errorf("marshaling expected online map: %w", err)
+	}
+
+	os.Stderr.Write(out)
+	os.Stderr.Write([]byte("\n"))
+
+	return nil
+}