bring back last_seen in database (#2579)

* db: add back last_seen to the database

Fixes #2574

Signed-off-by: Kristoffer Dalby <kristoffer@tailscale.com>

* integration: ensure last_seen is set

Signed-off-by: Kristoffer Dalby <kristoffer@tailscale.com>

---------

Signed-off-by: Kristoffer Dalby <kristoffer@tailscale.com>

.github/CODEOWNERS

@@ -1,10 +1,10 @@
 * @juanfont @kradalby
 
-*.md @ohdearaugustin
-*.yml @ohdearaugustin
-*.yaml @ohdearaugustin
-Dockerfile* @ohdearaugustin
-.goreleaser.yaml @ohdearaugustin
-/docs/ @ohdearaugustin
-/.github/workflows/ @ohdearaugustin
-/.github/renovate.json @ohdearaugustin
+*.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/ISSUE_TEMPLATE/bug_report.md

@@ -1,65 +0,0 @@
----
-name: "Bug report"
-about: "Create a bug report to help us improve"
-title: ""
-labels: ["bug"]
-assignees: ""
----
-
-<!--
-Before posting a bug report, discuss the behaviour you are expecting with the Discord community
-to make sure that it is truly a bug.
-The issue tracker is not the place to ask for support or how to set up Headscale.
-
-Bug reports without the sufficient information will be closed.
-
-Headscale is a multinational community across the globe. Our language is English.
-All bug reports needs to be in English.
--->
-
-## 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. -->
-
-## Environment
-
-<!-- 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
--->
-
-- OS:
-- Headscale version:
-- Tailscale version:
-
-<!--
-We do not support running Headscale in a container nor behind a (reverse) proxy.
-If either of these are true for your environment, ask the community in Discord
-instead of filing a bug report.
--->
-
-- [ ] Headscale is behind a (reverse) proxy
-- [ ] Headscale runs in a container
-
-## To Reproduce
-
-<!-- Steps to reproduce the behavior. -->
-
-## Logs and attachments
-
-<!-- Please attach files with:
-- Client netmap dump (see below)
-- ACL configuration
-- Headscale configuration
-
-Dump the netmap of tailscale clients:
-`tailscale debug netmap > DESCRIPTIVE_NAME.json`
-
-Please provide information describing the netmap, which client, which headscale version etc.
--->

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -0,0 +1,97 @@
+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".
+
+        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
+      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: |
+        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 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/feature_request.md

@@ -1,26 +0,0 @@
----
-name: "Feature request"
-about: "Suggest an idea for headscale"
-title: ""
-labels: ["enhancement"]
-assignees: ""
----
-
-<!--
-We typically have a clear roadmap for what we want to improve and reserve the right
-to close feature requests that does not fit in the roadmap, or fit with the scope
-of the project, or we actually want to implement ourselves.
-
-Headscale is a multinational community across the globe. Our language is English.
-All bug reports needs to be in English.
--->
-
-## Why
-
-<!-- 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? -->
-
-## Description
-
-<!-- A clear and precise description of what new or changed feature you want. -->

.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/pull_request_template.md

@@ -12,7 +12,7 @@ If you find mistakes in the documentation, please submit a fix to the documentat
 
 <!-- Please tick if the following things apply. You… -->
 
-- [ ] read the [CONTRIBUTING guidelines](README.md#contributing)
+- [ ] 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

.github/workflows/build.yml

@@ -13,7 +13,7 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  build:
+  build-nix:
     runs-on: ubuntu-latest
     permissions: write-all
     steps:
@@ -36,7 +36,7 @@ jobs:
       - uses: DeterminateSystems/magic-nix-cache-action@main
         if: steps.changed-files.outputs.files == 'true'
 
-      - name: Run build
+      - name: Run nix build
         id: build
         if: steps.changed-files.outputs.files == 'true'
         run: |
@@ -69,3 +69,27 @@ jobs:
         with:
           name: headscale-linux
           path: result/bin/headscale
+  build-cross:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        env:
+          - "GOARCH=arm   GOOS=linux GOARM=5"
+          - "GOARCH=arm   GOOS=linux GOARM=6"
+          - "GOARCH=arm   GOOS=linux GOARM=7"
+          - "GOARCH=arm64 GOOS=linux"
+          - "GOARCH=386   GOOS=linux"
+          - "GOARCH=amd64 GOOS=linux"
+          - "GOARCH=arm64 GOOS=darwin"
+          - "GOARCH=amd64 GOOS=darwin"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+
+      - name: Run go cross compile
+        run: env ${{ matrix.env }} nix develop --command -- go build -o "headscale" ./cmd/headscale
+      - uses: actions/upload-artifact@v4
+        with:
+          name: "headscale-${{ matrix.env }}"
+          path: "headscale"

.github/workflows/check-tests.yaml

@@ -32,7 +32,7 @@ jobs:
       - name: Generate and check integration tests
         if: steps.changed-files.outputs.files == 'true'
         run: |
-          nix develop --command bash -c "cd cmd/gh-action-integration-generator/ && go generate"
+          nix develop --command bash -c "cd .github/workflows && go generate"
           git diff --exit-code .github/workflows/test-integration.yaml
 
       - name: Show missing tests

.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@v4
+        with:
+          fetch-depth: 0
+      - name: Install python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - name: Setup cache
+        uses: actions/cache@v4
+        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

@@ -13,11 +13,11 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
       - name: Install python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: 3.x
       - name: Setup cache
-        uses: actions/cache@v2
+        uses: actions/cache@v4
         with:
           key: ${{ github.ref }}
           path: .cache

.github/workflows/docs.yml

@@ -1,52 +0,0 @@
-name: Build documentation
-
-on:
-  push:
-    branches:
-      - main
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-      - name: Install python
-        uses: actions/setup-python@v4
-        with:
-          python-version: 3.x
-      - name: Setup cache
-        uses: actions/cache@v2
-        with:
-          key: ${{ github.ref }}
-          path: .cache
-      - name: Setup dependencies
-        run: pip install -r docs/requirements.txt
-      - name: Build docs
-        run: mkdocs build --strict
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: ./site
-
-  deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    permissions:
-      pages: write
-      id-token: write
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - name: Configure Pages
-        uses: actions/configure-pages@v4
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4

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

@@ -1,6 +1,6 @@
 package main
 
-//go:generate go run ./main.go
+//go:generate go run ./gh-action-integration-generator.go
 
 import (
 	"bytes"
@@ -38,23 +38,28 @@ func findTests() []string {
 	return tests
 }
 
-func updateYAML(tests []string) {
+func updateYAML(tests []string, testPath string) {
 	testsForYq := fmt.Sprintf("[%s]", strings.Join(tests, ", "))
 
 	yqCommand := fmt.Sprintf(
-		"yq eval '.jobs.integration-test.strategy.matrix.test = %s' ../../.github/workflows/test-integration.yaml -i",
+		"yq eval '.jobs.integration-test.strategy.matrix.test = %s' %s -i",
 		testsForYq,
+		testPath,
 	)
 	cmd := exec.Command("bash", "-c", yqCommand)
 
-	var out bytes.Buffer
-	cmd.Stdout = &out
+	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.Println("YAML file updated successfully")
+	fmt.Printf("YAML file (%s) updated successfully\n", testPath)
 }
 
 func main() {
@@ -65,5 +70,5 @@ func main() {
 		quotedTests[i] = fmt.Sprintf("\"%s\"", test)
 	}
 
-	updateYAML(quotedTests)
+	updateYAML(quotedTests, "./test-integration.yaml")
 }

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

@@ -7,6 +7,7 @@ on:
 
 jobs:
   build:
+    if: github.repository == 'juanfont/headscale'
     runs-on: ubuntu-latest
 
     steps:

.github/workflows/lint.yml

@@ -31,7 +31,7 @@ jobs:
 
       - name: golangci-lint
         if: steps.changed-files.outputs.files == 'true'
-        run: nix develop --command -- golangci-lint run --new-from-rev=${{github.event.pull_request.base.sha}} --out-format=github-actions .
+        run: nix develop --command -- golangci-lint run --new-from-rev=${{github.event.pull_request.base.sha}} --out-format=colored-line-number
 
   prettier-lint:
     runs-on: ubuntu-latest

.github/workflows/release.yml

@@ -9,6 +9,7 @@ on:
 
 jobs:
   goreleaser:
+    if: github.repository == 'juanfont/headscale'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout

.github/workflows/stale.yml

@@ -6,6 +6,7 @@ on:
 
 jobs:
   close-issues:
+    if: github.repository == 'juanfont/headscale'
     runs-on: ubuntu-latest
     permissions:
       issues: write
@@ -20,4 +21,5 @@ jobs:
           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"
           repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test-integration.yaml

@@ -1,4 +1,7 @@
 name: Integration Tests
+# 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 }}
@@ -18,39 +21,57 @@ jobs:
           - TestACLNamedHostsCanReachBySubnet
           - TestACLNamedHostsCanReach
           - TestACLDevice1CanAccessDevice2
+          - TestPolicyUpdateWhileRunningWithCLIInDatabase
+          - TestAuthKeyLogoutAndReloginSameUser
+          - TestAuthKeyLogoutAndReloginNewUser
+          - TestAuthKeyLogoutAndReloginSameUserExpiredKey
           - TestOIDCAuthenticationPingAll
           - TestOIDCExpireNodesBasedOnTokenExpiry
+          - TestOIDC024UserCreation
+          - TestOIDCAuthenticationWithPKCE
+          - TestOIDCReloginSameNodeNewUser
           - TestAuthWebFlowAuthenticationPingAll
           - TestAuthWebFlowLogoutAndRelogin
           - TestUserCommand
           - TestPreAuthKeyCommand
           - TestPreAuthKeyCommandWithoutExpiry
           - TestPreAuthKeyCommandReusableEphemeral
+          - TestPreAuthKeyCorrectUserLoggedInCommand
           - TestApiKeyCommand
           - TestNodeTagCommand
-          - TestNodeAdvertiseTagNoACLCommand
-          - TestNodeAdvertiseTagWithACLCommand
+          - TestNodeAdvertiseTagCommand
           - TestNodeCommand
           - TestNodeExpireCommand
           - TestNodeRenameCommand
           - TestNodeMoveCommand
+          - TestPolicyCommand
+          - TestPolicyBrokenConfigCommand
+          - TestDERPVerifyEndpoint
+          - TestResolveMagicDNS
+          - TestResolveMagicDNSExtraRecordsPath
           - TestDERPServerScenario
+          - TestDERPServerWebsocketScenario
           - TestPingAllByIP
           - TestPingAllByIPPublicDERP
-          - TestAuthKeyLogoutAndRelogin
           - TestEphemeral
+          - TestEphemeralInAlternateTimezone
+          - TestEphemeral2006DeletedTooQuickly
           - TestPingAllByHostname
           - TestTaildrop
-          - TestResolveMagicDNS
+          - TestUpdateHostnameFromClient
           - TestExpireNode
           - TestNodeOnlineStatus
           - TestPingAllByIPManyUpDown
+          - Test2118DeletingOnlineNodePanics
           - TestEnablingRoutes
           - TestHASubnetRouterFailover
-          - TestEnableDisableAutoApprovedRoute
           - TestSubnetRouteACL
+          - TestEnablingExitRoutes
+          - TestSubnetRouterMultiNetwork
+          - TestSubnetRouterMultiNetworkExitNode
+          - TestAutoApproveMultiNetwork
+          - TestSubnetRouteACLFiltering
           - TestHeadscale
-          - TestCreateTailscale
           - TestTailscaleNodesJoiningHeadcale
           - TestSSHOneUserToAll
           - TestSSHMultipleUsersAllToAll
@@ -58,6 +79,16 @@ jobs:
           - TestSSHIsBlockedInACL
           - TestSSHUserOnlyIsolation
         database: [postgres, sqlite]
+    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@v4
         with:
@@ -73,6 +104,16 @@ jobs:
               - '**/*.go'
               - 'integration_test/'
               - 'config-example.yaml'
+      - name: Tailscale
+        if: ${{ env.HAS_TAILSCALE_SECRET }}
+        uses: tailscale/github-action@v2
+        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
       - uses: DeterminateSystems/nix-installer-action@main
         if: steps.changed-files.outputs.files == 'true'
       - uses: DeterminateSystems/magic-nix-cache-action@main
@@ -86,7 +127,17 @@ jobs:
         env:
           USE_POSTGRES: ${{ matrix.database == 'postgres' && '1' || '0' }}
         with:
-          attempt_limit: 5
+          # Our integration tests are started like a thundering herd, often
+          # hitting limits of the various external repositories we depend on
+          # like docker hub. This will retry jobs every 5 min, 10 times,
+          # hopefully letting us avoid manual intervention and restarting jobs.
+          # One could of course argue that we should invest in trying to avoid
+          # this, but currently it seems like a larger investment to be cleverer
+          # about this.
+          # Some of the jobs might still require manual restart as they are really
+          # slow and this will cause them to eventually be killed by Github actions.
+          attempt_delay: 300000 # 5 min
+          attempt_limit: 10
           command: |
             nix develop --command -- docker run \
               --tty --rm \
@@ -112,3 +163,6 @@ jobs:
         with:
           name: ${{ matrix.test }}-${{matrix.database}}-pprof
           path: "control_logs/*.pprof.tar"
+      - name: Setup a blocking tmux session
+        if: ${{ env.HAS_TAILSCALE_SECRET }}
+        uses: alexellis/block-with-tmux-action@master

.github/workflows/test.yml

@@ -34,4 +34,10 @@ jobs:
 
       - name: Run tests
         if: steps.changed-files.outputs.files == 'true'
-        run: nix develop --check
+        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

@@ -6,6 +6,7 @@ on:
 
 jobs:
   lockfile:
+    if: github.repository == 'juanfont/headscale'
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository

.gitignore

@@ -22,6 +22,7 @@ dist/
 /headscale
 config.json
 config.yaml
+config*.yaml
 derp.yaml
 *.hujson
 *.key

.golangci.yaml

@@ -1,77 +1,79 @@
 ---
-run:
-  timeout: 10m
-  build-tags:
-    - ts2019
-
-issues:
-  skip-dirs:
-    - gen
+version: "2"
 linters:
-  enable-all: true
+  default: all
   disable:
+    - cyclop
     - depguard
-
-    - exhaustivestruct
-    - revive
-    - lll
-    - interfacer
-    - scopelint
-    - maligned
-    - golint
-    - gofmt
+    - dupl
+    - exhaustruct
+    - funlen
     - gochecknoglobals
     - gochecknoinits
     - gocognit
-    - funlen
-    - exhaustivestruct
-    - tagliatelle
     - godox
-    - ireturn
-    - execinquery
-    - exhaustruct
-    - nolintlint
-    - musttag # causes issues with imported libs
-    - depguard
-
-    # deprecated
-    - structcheck # replaced by unused
-    - ifshort # deprecated by the owner
-    - varcheck # replaced by unused
-    - nosnakecase # replaced by revive
-    - deadcode # replaced by unused
-
-    # We should strive to enable these:
-    - wrapcheck
-    - dupl
-    - makezero
-    - maintidx
-
-    # Limits the methods of an interface to 10. We have more in integration tests
     - interfacebloat
-
-    # We might want to enable this, but it might be a lot of work
-    - cyclop
+    - ireturn
+    - lll
+    - maintidx
+    - makezero
+    - musttag
     - nestif
-    - wsl # might be incompatible with gofumpt
-    - testpackage
+    - nolintlint
     - paralleltest
+    - revive
+    - tagliatelle
+    - testpackage
+    - wrapcheck
+    - wsl
+  settings:
+    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
-      - tt
-
-  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,7 +1,8 @@
 ---
+version: 2
 before:
   hooks:
-    - go mod tidy -compat=1.22
+    - go mod tidy -compat=1.24
     - go mod vendor
 
 release:
@@ -26,14 +27,17 @@ builds:
     flags:
       - -mod=readonly
     ldflags:
-      - -s -w -X github.com/juanfont/headscale/cmd/headscale/cli.Version=v{{.Version}}
+      - -s -w
+      - -X github.com/juanfont/headscale/hscontrol/types.Version={{ .Version }}
+      - -X github.com/juanfont/headscale/hscontrol/types.GitCommitHash={{ .Commit }}
     tags:
       - ts2019
 
 archives:
   - id: golang-cross
     name_template: '{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ with .Arm }}v{{ . }}{{ end }}{{ with .Mips }}_{{ . }}{{ end }}{{ if not (eq .Amd64 "v1") }}{{ .Amd64 }}{{ end }}'
-    format: binary
+    formats:
+      - binary
 
 source:
   enabled: true
@@ -52,7 +56,7 @@ nfpms:
   # List file contents: dpkg -c dist/headscale...deb
   # Package metadata: dpkg --info dist/headscale....deb
   #
-  - builds:
+  - ids:
       - headscale
     package_name: headscale
     priority: optional
@@ -81,7 +85,9 @@ nfpms:
 
 kos:
   - id: ghcr
-    repository: ghcr.io/juanfont/headscale
+    repositories:
+      - ghcr.io/juanfont/headscale
+      - headscale/headscale
 
     # bare tells KO to only use the repository
     # for tagging and naming the container.
@@ -109,33 +115,13 @@ kos:
       - '{{ trimprefix .Tag "v" }}'
       - "sha-{{ .ShortCommit }}"
 
-  - id: dockerhub
-    build: headscale
-    base_image: gcr.io/distroless/base-debian12
-    repository: headscale/headscale
-    bare: true
-    platforms:
-      - linux/amd64
-      - linux/386
-      - linux/arm64
-      - linux/arm/v7
-    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 }}"
-
   - id: ghcr-debug
-    repository: ghcr.io/juanfont/headscale
+    repositories:
+      - ghcr.io/juanfont/headscale
+      - headscale/headscale
+
     bare: true
-    base_image: "debian:12"
+    base_image: gcr.io/distroless/base-debian12:debug
     build: headscale
     main: ./cmd/headscale
     env:
@@ -153,30 +139,7 @@ kos:
       - "{{ 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{{ else }}unstable-debug{{ end }}"
-      - "{{ .Tag }}-debug"
-      - '{{ trimprefix .Tag "v" }}-debug'
-      - "sha-{{ .ShortCommit }}-debug"
-
-  - id: dockerhub-debug
-    build: headscale
-    base_image: "debian:12"
-    repository: headscale/headscale
-    bare: true
-    platforms:
-      - linux/amd64
-      - linux/386
-      - linux/arm64
-      - linux/arm/v7
-    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{{ else }}unstable-debug{{ end }}"
+      - "{{ if not .Prerelease }}stable-debug{{ else }}unstable-debug{{ end }}"
       - "{{ .Tag }}-debug"
       - '{{ trimprefix .Tag "v" }}-debug'
       - "sha-{{ .ShortCommit }}-debug"
@@ -184,7 +147,7 @@ kos:
 checksum:
   name_template: "checksums.txt"
 snapshot:
-  name_template: "{{ .Tag }}-next"
+  version_template: "{{ .Tag }}-next"
 changelog:
   sort: asc
   filters:

.prettierignore

@@ -1,6 +1,4 @@
 .github/workflows/test-integration-v2*
-docs/dns-records.md
-docs/running-headscale-container.md
-docs/running-headscale-linux-manual.md
-docs/running-headscale-linux.md
-docs/running-headscale-openbsd.md
+docs/about/features.md
+docs/ref/configuration.md
+docs/ref/remote-cli.md

CODE_OF_CONDUCT.md

@@ -62,7 +62,7 @@ event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior
 may be reported to the community leaders responsible for enforcement
-at our Discord channel. All complaints
+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

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.derper

@@ -0,0 +1,19 @@
+# For testing purposes only
+
+FROM golang: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.18
+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

@@ -2,30 +2,23 @@
 # and are in no way endorsed by Headscale's maintainers as an
 # official nor supported release or distribution.
 
-FROM docker.io/golang:1.22-bookworm AS build
+FROM docker.io/golang:1.24-bookworm
 ARG VERSION=dev
 ENV GOPATH /go
 WORKDIR /go/src/headscale
 
+RUN apt-get update \
+  && apt-get install --no-install-recommends --yes less jq sqlite3 dnsutils \
+  && rm -rf /var/lib/apt/lists/* \
+  && apt-get clean
+RUN mkdir -p /var/run/headscale
+
 COPY go.mod go.sum /go/src/headscale/
 RUN go mod download
 
 COPY . .
 
-RUN CGO_ENABLED=0 GOOS=linux go install -ldflags="-s -w -X github.com/juanfont/headscale/cmd/headscale/cli.Version=$VERSION" -a ./cmd/headscale
-RUN test -e /go/bin/headscale
-
-# Debug image
-FROM docker.io/golang:1.22-bookworm
-
-COPY --from=build /go/bin/headscale /bin/headscale
-ENV TZ UTC
-
-RUN apt-get update \
-  && apt-get install --no-install-recommends --yes less jq \
-  && rm -rf /var/lib/apt/lists/* \
-  && apt-get clean
-RUN mkdir -p /var/run/headscale
+RUN CGO_ENABLED=0 GOOS=linux go install -a ./cmd/headscale && test -e /go/bin/headscale
 
 # Need to reset the entrypoint or everything will run as a busybox script
 ENTRYPOINT []

Dockerfile.tailscale-HEAD

@@ -1,21 +1,45 @@
-# 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.
+# Copyright (c) Tailscale Inc & AUTHORS
+# SPDX-License-Identifier: BSD-3-Clause
 
-FROM golang:latest
+# This Dockerfile is more or less lifted from tailscale/tailscale
+# to ensure a similar build process when testing the HEAD of tailscale.
 
-RUN apt-get update \
-    && apt-get install -y dnsutils git iptables ssh ca-certificates \
-    && rm -rf /var/lib/apt/lists/*
+FROM golang:1.24-alpine AS build-env
 
-RUN useradd --shell=/bin/bash --create-home ssh-it-user
+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/tailscale
+WORKDIR /go/src/tailscale
 
-RUN git checkout main \
-    && sh build_dist.sh tailscale.com/cmd/tailscale \
-    && sh build_dist.sh tailscale.com/cmd/tailscaled \
-    && cp tailscale /usr/local/bin/ \
-    && cp tailscaled /usr/local/bin/
+
+# 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.18
+RUN apk add --no-cache ca-certificates iptables iproute2 ip6tables curl
+
+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

@@ -22,7 +22,7 @@ build:
 dev: lint test build
 
 test:
-	gotestsum -- -short -coverprofile=coverage.out ./...
+	gotestsum -- -short -race -coverprofile=coverage.out ./...
 
 test_integration:
 	docker run \
@@ -31,16 +31,27 @@ test_integration:
 		--name headscale-test-suite \
 		-v $$PWD:$$PWD -w $$PWD/integration \
 		-v /var/run/docker.sock:/var/run/docker.sock \
+		-v $$PWD/control_logs:/tmp/control \
 		golang:1 \
-		go run gotest.tools/gotestsum@latest -- -failfast ./... -timeout 120m -parallel 8
+		go run gotest.tools/gotestsum@latest -- -race -failfast ./... -timeout 120m -parallel 8
 
 lint:
 	golangci-lint run --fix --timeout 10m
 
-fmt:
+fmt: fmt-go fmt-prettier fmt-proto
+
+fmt-prettier:
 	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)
+	prettier --write --print-width 80 --prose-wrap always CHANGELOG.md
+
+fmt-go:
+	# TODO(kradalby): Reeval if we want to use 88 in the future.
+	# golines --max-len=88 --base-formatter=gofumpt -w $(GO_SOURCES)
+	gofumpt -l -w .
+	golangci-lint run --fix
+
+fmt-proto:
+	clang-format -i $(PROTO_SOURCES)
 
 proto-lint:
 	cd proto/ && go run github.com/bufbuild/buf/cmd/buf lint

README.md

@@ -4,11 +4,15 @@
 
 An open source, self-hosted implementation of the Tailscale control server.
 
-Join our [Discord](https://discord.gg/c84AZQhmpx) 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.
+to ensure you have the correct example configuration. The `main` branch might
+contain unreleased changes. The documentation is available for stable and
+development versions:
+
+* [Documentation for the stable version](https://headscale.net/stable/)
+* [Documentation for the development version](https://headscale.net/development/)
 
 ## What is Tailscale
 
@@ -32,12 +36,12 @@ organisation.
 
 ## Design goal
 
-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 Tailnet, suitable for a personal use, or a small
-open-source organisation.
+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.
 
 ## Supporting Headscale
 
@@ -46,39 +50,18 @@ buttons available in the repo.
 
 ## Features
 
-- Full "base" support of Tailscale's features
-- Configurable DNS
-  - [Split DNS](https://tailscale.com/kb/1054/dns/#using-dns-settings-in-the-admin-console)
-- Node registration
-  - Single-Sign-On (via Open ID Connect)
-  - Pre authenticated key
-- Taildrop (File Sharing)
-- [Access control lists](https://tailscale.com/kb/1018/acls/)
-- [MagicDNS](https://tailscale.com/kb/1081/magicdns)
-- Support for multiple IP ranges in the tailnet
-- Dual stack (IPv4 and IPv6)
-- Routing advertising (including exit nodes)
-- Ephemeral nodes
-- Embedded [DERP server](https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp)
+Please see ["Features" in the documentation](https://headscale.net/stable/about/features/).
 
 ## Client OS support
 
-| OS      | Supports headscale                                        |
-| ------- | --------------------------------------------------------- |
-| Linux   | Yes                                                       |
-| OpenBSD | Yes                                                       |
-| FreeBSD | Yes                                                       |
-| macOS   | Yes (see `/apple` on your headscale for more information) |
-| Windows | Yes [docs](./docs/windows-client.md)                      |
-| Android | Yes [docs](./docs/android-client.md)                      |
-| iOS     | Yes [docs](./docs/iOS-client.md)                          |
+Please see ["Client and operating system support" in the documentation](https://headscale.net/stable/about/clients/).
 
 ## Running headscale
 
 **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/).
+Please have a look at the [`documentation`](https://headscale.net/stable/).
 
 ## Talks
 
@@ -87,25 +70,20 @@ Please have a look at the [`documentation`](https://headscale.net/).
 
 ## Disclaimer
 
-1. This project is not associated with 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
 
-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 read the [CONTRIBUTING.md](./CONTRIBUTING.md) file.
 
 ### Requirements
 
-To contribute to headscale you would need the lastest version of [Go](https://golang.org)
-and [Buf](https://buf.build)(Protobuf generator).
+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.

cmd/headscale/cli/api_key.go

@@ -54,7 +54,7 @@ var listAPIKeys = &cobra.Command{
 	Run: func(cmd *cobra.Command, args []string) {
 		output, _ := cmd.Flags().GetString("output")
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
@@ -67,14 +67,10 @@ var listAPIKeys = &cobra.Command{
 				fmt.Sprintf("Error getting the list of keys: %s", err),
 				output,
 			)
-
-			return
 		}
 
 		if output != "" {
 			SuccessOutput(response.GetApiKeys(), "", output)
-
-			return
 		}
 
 		tableData := pterm.TableData{
@@ -102,8 +98,6 @@ var listAPIKeys = &cobra.Command{
 				fmt.Sprintf("Failed to render pterm table: %s", err),
 				output,
 			)
-
-			return
 		}
 	},
 }
@@ -119,9 +113,6 @@ 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{}
 
 		durationStr, _ := cmd.Flags().GetString("expiration")
@@ -133,19 +124,13 @@ If you loose a key, create a new one and revoke (expire) the old one.`,
 				fmt.Sprintf("Could not parse duration: %s\n", err),
 				output,
 			)
-
-			return
 		}
 
 		expiration := time.Now().UTC().Add(time.Duration(duration))
 
-		log.Trace().
-			Dur("expiration", time.Duration(duration)).
-			Msg("expiration has been set")
-
 		request.Expiration = timestamppb.New(expiration)
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
@@ -156,8 +141,6 @@ If you loose a key, create a new one and revoke (expire) the old one.`,
 				fmt.Sprintf("Cannot create Api Key: %s\n", err),
 				output,
 			)
-
-			return
 		}
 
 		SuccessOutput(response.GetApiKey(), response.GetApiKey(), output)
@@ -178,11 +161,9 @@ var expireAPIKeyCmd = &cobra.Command{
 				fmt.Sprintf("Error getting prefix from CLI flag: %s", err),
 				output,
 			)
-
-			return
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
@@ -197,8 +178,6 @@ var expireAPIKeyCmd = &cobra.Command{
 				fmt.Sprintf("Cannot expire Api Key: %s\n", err),
 				output,
 			)
-
-			return
 		}
 
 		SuccessOutput(response, "Key expired", output)
@@ -219,11 +198,9 @@ var deleteAPIKeyCmd = &cobra.Command{
 				fmt.Sprintf("Error getting prefix from CLI flag: %s", err),
 				output,
 			)
-
-			return
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
@@ -238,8 +215,6 @@ var deleteAPIKeyCmd = &cobra.Command{
 				fmt.Sprintf("Cannot delete Api Key: %s\n", err),
 				output,
 			)
-
-			return
 		}
 
 		SuccessOutput(response, "Key deleted", output)

cmd/headscale/cli/configtest.go

@@ -14,7 +14,7 @@ var configTestCmd = &cobra.Command{
 	Short: "Test the configuration.",
 	Long:  "Run a test of the configuration and exit.",
 	Run: func(cmd *cobra.Command, args []string) {
-		_, err := getHeadscaleApp()
+		_, err := newHeadscaleServerWithConfig()
 		if err != nil {
 			log.Fatal().Caller().Err(err).Msg("Error initializing")
 		}

cmd/headscale/cli/debug.go

@@ -4,10 +4,10 @@ import (
 	"fmt"
 
 	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/juanfont/headscale/hscontrol/types"
 	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
 	"google.golang.org/grpc/status"
-	"tailscale.com/types/key"
 )
 
 const (
@@ -64,11 +64,9 @@ var createNodeCmd = &cobra.Command{
 		user, err := cmd.Flags().GetString("user")
 		if err != nil {
 			ErrorOutput(err, fmt.Sprintf("Error getting user: %s", err), output)
-
-			return
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
@@ -79,31 +77,24 @@ var createNodeCmd = &cobra.Command{
 				fmt.Sprintf("Error getting node from flag: %s", err),
 				output,
 			)
-
-			return
 		}
 
-		machineKey, err := cmd.Flags().GetString("key")
+		registrationID, err := cmd.Flags().GetString("key")
 		if err != nil {
 			ErrorOutput(
 				err,
 				fmt.Sprintf("Error getting key from flag: %s", err),
 				output,
 			)
-
-			return
 		}
 
-		var mkey key.MachinePublic
-		err = mkey.UnmarshalText([]byte(machineKey))
+		_, err = types.RegistrationIDFromString(registrationID)
 		if err != nil {
 			ErrorOutput(
 				err,
 				fmt.Sprintf("Failed to parse machine key from flag: %s", err),
 				output,
 			)
-
-			return
 		}
 
 		routes, err := cmd.Flags().GetStringSlice("route")
@@ -113,12 +104,10 @@ var createNodeCmd = &cobra.Command{
 				fmt.Sprintf("Error getting routes from flag: %s", err),
 				output,
 			)
-
-			return
 		}
 
 		request := &v1.DebugCreateNodeRequest{
-			Key:    machineKey,
+			Key:    registrationID,
 			Name:   name,
 			User:   user,
 			Routes: routes,
@@ -131,8 +120,6 @@ var createNodeCmd = &cobra.Command{
 				fmt.Sprintf("Cannot create node: %s", status.Convert(err).Message()),
 				output,
 			)
-
-			return
 		}
 
 		SuccessOutput(response.GetNode(), "Node created", output)

cmd/headscale/cli/mockoidc.go

@@ -1,8 +1,10 @@
 package cli
 
 import (
+	"encoding/json"
 	"fmt"
 	"net"
+	"net/http"
 	"os"
 	"strconv"
 	"time"
@@ -64,6 +66,19 @@ func mockOIDC() error {
 		accessTTL = newTTL
 	}
 
+	userStr := os.Getenv("MOCKOIDC_USERS")
+	if userStr == "" {
+		return fmt.Errorf("MOCKOIDC_USERS not defined")
+	}
+
+	var users []mockoidc.MockUser
+	err := json.Unmarshal([]byte(userStr), &users)
+	if err != nil {
+		return fmt.Errorf("unmarshalling users: %w", err)
+	}
+
+	log.Info().Interface("users", users).Msg("loading users from JSON")
+
 	log.Info().Msgf("Access token TTL: %s", accessTTL)
 
 	port, err := strconv.Atoi(portStr)
@@ -71,7 +86,7 @@ func mockOIDC() error {
 		return err
 	}
 
-	mock, err := getMockOIDC(clientID, clientSecret)
+	mock, err := getMockOIDC(clientID, clientSecret, users)
 	if err != nil {
 		return err
 	}
@@ -93,12 +108,18 @@ func mockOIDC() error {
 	return nil
 }
 
-func getMockOIDC(clientID string, clientSecret string) (*mockoidc.MockOIDC, error) {
+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,
@@ -107,9 +128,19 @@ func getMockOIDC(clientID string, clientSecret string) (*mockoidc.MockOIDC, erro
 		CodeChallengeMethodsSupported: []string{"plain", "S256"},
 		Keypair:                       keypair,
 		SessionStore:                  mockoidc.NewSessionStore(),
-		UserQueue:                     &mockoidc.UserQueue{},
+		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/nodes.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"log"
 	"net/netip"
+	"slices"
 	"strconv"
 	"strings"
 	"time"
@@ -12,6 +13,7 @@ import (
 	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"
 	"tailscale.com/types/key"
@@ -26,9 +28,11 @@ func init() {
 	listNodesNamespaceFlag := listNodesCmd.Flags().Lookup("namespace")
 	listNodesNamespaceFlag.Deprecated = deprecateNamespaceMessage
 	listNodesNamespaceFlag.Hidden = true
-
 	nodeCmd.AddCommand(listNodesCmd)
 
+	listNodeRoutesCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
+	nodeCmd.AddCommand(listNodeRoutesCmd)
+
 	registerNodeCmd.Flags().StringP("user", "u", "", "User")
 
 	registerNodeCmd.Flags().StringP("namespace", "n", "", "User")
@@ -38,33 +42,33 @@ func init() {
 
 	err := registerNodeCmd.MarkFlagRequired("user")
 	if err != nil {
-		log.Fatalf(err.Error())
+		log.Fatal(err.Error())
 	}
 	registerNodeCmd.Flags().StringP("key", "k", "", "Key")
 	err = registerNodeCmd.MarkFlagRequired("key")
 	if err != nil {
-		log.Fatalf(err.Error())
+		log.Fatal(err.Error())
 	}
 	nodeCmd.AddCommand(registerNodeCmd)
 
 	expireNodeCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
 	err = expireNodeCmd.MarkFlagRequired("identifier")
 	if err != nil {
-		log.Fatalf(err.Error())
+		log.Fatal(err.Error())
 	}
 	nodeCmd.AddCommand(expireNodeCmd)
 
 	renameNodeCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
 	err = renameNodeCmd.MarkFlagRequired("identifier")
 	if err != nil {
-		log.Fatalf(err.Error())
+		log.Fatal(err.Error())
 	}
 	nodeCmd.AddCommand(renameNodeCmd)
 
 	deleteNodeCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
 	err = deleteNodeCmd.MarkFlagRequired("identifier")
 	if err != nil {
-		log.Fatalf(err.Error())
+		log.Fatal(err.Error())
 	}
 	nodeCmd.AddCommand(deleteNodeCmd)
 
@@ -72,10 +76,10 @@ func init() {
 
 	err = moveNodeCmd.MarkFlagRequired("identifier")
 	if err != nil {
-		log.Fatalf(err.Error())
+		log.Fatal(err.Error())
 	}
 
-	moveNodeCmd.Flags().StringP("user", "u", "", "New user")
+	moveNodeCmd.Flags().Uint64P("user", "u", 0, "New user")
 
 	moveNodeCmd.Flags().StringP("namespace", "n", "", "User")
 	moveNodeNamespaceFlag := moveNodeCmd.Flags().Lookup("namespace")
@@ -84,20 +88,20 @@ func init() {
 
 	err = moveNodeCmd.MarkFlagRequired("user")
 	if err != nil {
-		log.Fatalf(err.Error())
+		log.Fatal(err.Error())
 	}
 	nodeCmd.AddCommand(moveNodeCmd)
 
 	tagCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
-
-	err = tagCmd.MarkFlagRequired("identifier")
-	if err != nil {
-		log.Fatalf(err.Error())
-	}
-	tagCmd.Flags().
-		StringSliceP("tags", "t", []string{}, "List of tags to add to the node")
+	tagCmd.MarkFlagRequired("identifier")
+	tagCmd.Flags().StringSliceP("tags", "t", []string{}, "List of tags to add to the node")
 	nodeCmd.AddCommand(tagCmd)
 
+	approveRoutesCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
+	approveRoutesCmd.MarkFlagRequired("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)
 }
 
@@ -115,27 +119,23 @@ var registerNodeCmd = &cobra.Command{
 		user, err := cmd.Flags().GetString("user")
 		if err != nil {
 			ErrorOutput(err, fmt.Sprintf("Error getting user: %s", err), output)
-
-			return
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
-		machineKey, err := cmd.Flags().GetString("key")
+		registrationID, err := cmd.Flags().GetString("key")
 		if err != nil {
 			ErrorOutput(
 				err,
 				fmt.Sprintf("Error getting node key from flag: %s", err),
 				output,
 			)
-
-			return
 		}
 
 		request := &v1.RegisterNodeRequest{
-			Key:  machineKey,
+			Key:  registrationID,
 			User: user,
 		}
 
@@ -149,8 +149,6 @@ var registerNodeCmd = &cobra.Command{
 				),
 				output,
 			)
-
-			return
 		}
 
 		SuccessOutput(
@@ -168,17 +166,13 @@ var listNodesCmd = &cobra.Command{
 		user, err := cmd.Flags().GetString("user")
 		if err != nil {
 			ErrorOutput(err, fmt.Sprintf("Error getting user: %s", err), output)
-
-			return
 		}
 		showTags, err := cmd.Flags().GetBool("tags")
 		if err != nil {
 			ErrorOutput(err, fmt.Sprintf("Error getting tags flag: %s", err), output)
-
-			return
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
@@ -193,21 +187,15 @@ var listNodesCmd = &cobra.Command{
 				fmt.Sprintf("Cannot get nodes: %s", status.Convert(err).Message()),
 				output,
 			)
-
-			return
 		}
 
 		if output != "" {
 			SuccessOutput(response.GetNodes(), "", output)
-
-			return
 		}
 
 		tableData, err := nodesToPtables(user, showTags, response.GetNodes())
 		if err != nil {
 			ErrorOutput(err, fmt.Sprintf("Error converting to table: %s", err), output)
-
-			return
 		}
 
 		err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
@@ -217,9 +205,73 @@ var listNodesCmd = &cobra.Command{
 				fmt.Sprintf("Failed to render pterm table: %s", err),
 				output,
 			)
+		}
+	},
+}
+
+var listNodeRoutesCmd = &cobra.Command{
+	Use:     "list-routes",
+	Short:   "List routes available on nodes",
+	Aliases: []string{"lsr", "routes"},
+	Run: func(cmd *cobra.Command, args []string) {
+		output, _ := cmd.Flags().GetString("output")
+		identifier, err := cmd.Flags().GetUint64("identifier")
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error converting ID to integer: %s", err),
+				output,
+			)
 
 			return
 		}
+
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
+		defer cancel()
+		defer conn.Close()
+
+		request := &v1.ListNodesRequest{}
+
+		response, err := client.ListNodes(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				"Cannot get nodes: "+status.Convert(err).Message(),
+				output,
+			)
+		}
+
+		if output != "" {
+			SuccessOutput(response.GetNodes(), "", output)
+		}
+
+		nodes := response.GetNodes()
+		if identifier != 0 {
+			for _, node := range response.GetNodes() {
+				if node.GetId() == identifier {
+					nodes = []*v1.Node{node}
+					break
+				}
+			}
+		}
+
+		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)
+		})
+
+		tableData, err := nodeRoutesToPtables(nodes)
+		if err != nil {
+			ErrorOutput(err, fmt.Sprintf("Error converting to table: %s", err), output)
+		}
+
+		err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Failed to render pterm table: %s", err),
+				output,
+			)
+		}
 	},
 }
 
@@ -242,7 +294,7 @@ var expireNodeCmd = &cobra.Command{
 			return
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
@@ -285,7 +337,7 @@ var renameNodeCmd = &cobra.Command{
 			return
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
@@ -334,7 +386,7 @@ var deleteNodeCmd = &cobra.Command{
 			return
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
@@ -423,7 +475,7 @@ var moveNodeCmd = &cobra.Command{
 			return
 		}
 
-		user, err := cmd.Flags().GetString("user")
+		user, err := cmd.Flags().GetUint64("user")
 		if err != nil {
 			ErrorOutput(
 				err,
@@ -434,7 +486,7 @@ var moveNodeCmd = &cobra.Command{
 			return
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
@@ -507,7 +559,7 @@ be assigned to nodes.`,
 			return
 		}
 		if confirm {
-			ctx, client, conn, cancel := getHeadscaleCLIClient()
+			ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 			defer cancel()
 			defer conn.Close()
 
@@ -617,14 +669,14 @@ func nodesToPtables(
 		forcedTags = strings.TrimLeft(forcedTags, ",")
 		var invalidTags string
 		for _, tag := range node.GetInvalidTags() {
-			if !contains(node.GetForcedTags(), tag) {
+			if !slices.Contains(node.GetForcedTags(), tag) {
 				invalidTags += "," + pterm.LightRed(tag)
 			}
 		}
 		invalidTags = strings.TrimLeft(invalidTags, ",")
 		var validTags string
 		for _, tag := range node.GetValidTags() {
-			if !contains(node.GetForcedTags(), tag) {
+			if !slices.Contains(node.GetForcedTags(), tag) {
 				validTags += "," + pterm.LightGreen(tag)
 			}
 		}
@@ -674,13 +726,42 @@ func nodesToPtables(
 	return tableData, nil
 }
 
+func nodeRoutesToPtables(
+	nodes []*v1.Node,
+) (pterm.TableData, error) {
+	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(), ", "),
+			strings.Join(node.GetAvailableRoutes(), ", "),
+			strings.Join(node.GetSubnetRoutes(), ", "),
+		}
+		tableData = append(
+			tableData,
+			nodeData,
+		)
+	}
+
+	return tableData, nil
+}
+
 var tagCmd = &cobra.Command{
 	Use:     "tag",
 	Short:   "Manage the tags of a node",
 	Aliases: []string{"tags", "t"},
 	Run: func(cmd *cobra.Command, args []string) {
 		output, _ := cmd.Flags().GetString("output")
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
@@ -731,3 +812,60 @@ var tagCmd = &cobra.Command{
 		}
 	},
 }
+
+var approveRoutesCmd = &cobra.Command{
+	Use:   "approve-routes",
+	Short: "Manage the approved routes of a node",
+	Run: func(cmd *cobra.Command, args []string) {
+		output, _ := cmd.Flags().GetString("output")
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
+		defer cancel()
+		defer conn.Close()
+
+		// retrieve flags from CLI
+		identifier, err := cmd.Flags().GetUint64("identifier")
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error converting ID to integer: %s", err),
+				output,
+			)
+
+			return
+		}
+		routes, err := cmd.Flags().GetStringSlice("routes")
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error retrieving list of routes to add to node, %v", err),
+				output,
+			)
+
+			return
+		}
+
+		// Sending routes to node
+		request := &v1.SetApprovedRoutesRequest{
+			NodeId: identifier,
+			Routes: routes,
+		}
+		resp, err := client.SetApprovedRoutes(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error while sending routes to headscale: %s", err),
+				output,
+			)
+
+			return
+		}
+
+		if resp != nil {
+			SuccessOutput(
+				resp.GetNode(),
+				"Node updated",
+				output,
+			)
+		}
+	},
+}

cmd/headscale/cli/policy.go

@@ -0,0 +1,121 @@
+package cli
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/juanfont/headscale/hscontrol/policy"
+	"github.com/rs/zerolog/log"
+	"github.com/spf13/cobra"
+)
+
+func init() {
+	rootCmd.AddCommand(policyCmd)
+	policyCmd.AddCommand(getPolicy)
+
+	setPolicy.Flags().StringP("file", "f", "", "Path to a policy file in HuJSON format")
+	if err := setPolicy.MarkFlagRequired("file"); err != nil {
+		log.Fatal().Err(err).Msg("")
+	}
+	policyCmd.AddCommand(setPolicy)
+
+	checkPolicy.Flags().StringP("file", "f", "", "Path to a policy file in HuJSON format")
+	if err := checkPolicy.MarkFlagRequired("file"); err != nil {
+		log.Fatal().Err(err).Msg("")
+	}
+	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"},
+	Run: func(cmd *cobra.Command, args []string) {
+		output, _ := cmd.Flags().GetString("output")
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
+		defer cancel()
+		defer conn.Close()
+
+		request := &v1.GetPolicyRequest{}
+
+		response, err := client.GetPolicy(ctx, request)
+		if err != nil {
+			ErrorOutput(err, fmt.Sprintf("Failed loading ACL Policy: %s", err), output)
+		}
+
+		// TODO(pallabpain): Maybe print this better?
+		// This does not pass output as we dont support yaml, json or json-line
+		// output for this command. It is HuJSON already.
+		SuccessOutput("", response.GetPolicy(), "")
+	},
+}
+
+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"},
+	Run: func(cmd *cobra.Command, args []string) {
+		output, _ := cmd.Flags().GetString("output")
+		policyPath, _ := cmd.Flags().GetString("file")
+
+		f, err := os.Open(policyPath)
+		if err != nil {
+			ErrorOutput(err, fmt.Sprintf("Error opening the policy file: %s", err), output)
+		}
+		defer f.Close()
+
+		policyBytes, err := io.ReadAll(f)
+		if err != nil {
+			ErrorOutput(err, fmt.Sprintf("Error reading the policy file: %s", err), output)
+		}
+
+		request := &v1.SetPolicyRequest{Policy: string(policyBytes)}
+
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
+		defer cancel()
+		defer conn.Close()
+
+		if _, err := client.SetPolicy(ctx, request); err != nil {
+			ErrorOutput(err, fmt.Sprintf("Failed to set ACL Policy: %s", err), output)
+		}
+
+		SuccessOutput(nil, "Policy updated.", "")
+	},
+}
+
+var checkPolicy = &cobra.Command{
+	Use:   "check",
+	Short: "Check the Policy file for errors",
+	Run: func(cmd *cobra.Command, args []string) {
+		output, _ := cmd.Flags().GetString("output")
+		policyPath, _ := cmd.Flags().GetString("file")
+
+		f, err := os.Open(policyPath)
+		if err != nil {
+			ErrorOutput(err, fmt.Sprintf("Error opening the policy file: %s", err), output)
+		}
+		defer f.Close()
+
+		policyBytes, err := io.ReadAll(f)
+		if err != nil {
+			ErrorOutput(err, fmt.Sprintf("Error reading the policy file: %s", err), output)
+		}
+
+		_, err = policy.NewPolicyManager(policyBytes, nil, nil)
+		if err != nil {
+			ErrorOutput(err, fmt.Sprintf("Error parsing the policy file: %s", err), output)
+		}
+
+		SuccessOutput(nil, "Policy is valid", "")
+	},
+}

cmd/headscale/cli/preauthkeys.go

@@ -20,7 +20,7 @@ const (
 
 func init() {
 	rootCmd.AddCommand(preauthkeysCmd)
-	preauthkeysCmd.PersistentFlags().StringP("user", "u", "", "User")
+	preauthkeysCmd.PersistentFlags().Uint64P("user", "u", 0, "User identifier (ID)")
 
 	preauthkeysCmd.PersistentFlags().StringP("namespace", "n", "", "User")
 	pakNamespaceFlag := preauthkeysCmd.PersistentFlags().Lookup("namespace")
@@ -57,14 +57,12 @@ var listPreAuthKeys = &cobra.Command{
 	Run: func(cmd *cobra.Command, args []string) {
 		output, _ := cmd.Flags().GetString("output")
 
-		user, err := cmd.Flags().GetString("user")
+		user, err := cmd.Flags().GetUint64("user")
 		if err != nil {
 			ErrorOutput(err, fmt.Sprintf("Error getting user: %s", err), output)
-
-			return
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
@@ -85,8 +83,6 @@ var listPreAuthKeys = &cobra.Command{
 
 		if output != "" {
 			SuccessOutput(response.GetPreAuthKeys(), "", output)
-
-			return
 		}
 
 		tableData := pterm.TableData{
@@ -116,7 +112,7 @@ var listPreAuthKeys = &cobra.Command{
 			aclTags = strings.TrimLeft(aclTags, ",")
 
 			tableData = append(tableData, []string{
-				key.GetId(),
+				strconv.FormatUint(key.GetId(), 64),
 				key.GetKey(),
 				strconv.FormatBool(key.GetReusable()),
 				strconv.FormatBool(key.GetEphemeral()),
@@ -134,8 +130,6 @@ var listPreAuthKeys = &cobra.Command{
 				fmt.Sprintf("Failed to render pterm table: %s", err),
 				output,
 			)
-
-			return
 		}
 	},
 }
@@ -147,23 +141,15 @@ var createPreAuthKeyCmd = &cobra.Command{
 	Run: func(cmd *cobra.Command, args []string) {
 		output, _ := cmd.Flags().GetString("output")
 
-		user, err := cmd.Flags().GetString("user")
+		user, err := cmd.Flags().GetUint64("user")
 		if err != nil {
 			ErrorOutput(err, fmt.Sprintf("Error getting user: %s", err), output)
-
-			return
 		}
 
 		reusable, _ := cmd.Flags().GetBool("reusable")
 		ephemeral, _ := cmd.Flags().GetBool("ephemeral")
 		tags, _ := cmd.Flags().GetStringSlice("tags")
 
-		log.Trace().
-			Bool("reusable", reusable).
-			Bool("ephemeral", ephemeral).
-			Str("user", user).
-			Msg("Preparing to create preauthkey")
-
 		request := &v1.CreatePreAuthKeyRequest{
 			User:      user,
 			Reusable:  reusable,
@@ -180,8 +166,6 @@ var createPreAuthKeyCmd = &cobra.Command{
 				fmt.Sprintf("Could not parse duration: %s\n", err),
 				output,
 			)
-
-			return
 		}
 
 		expiration := time.Now().UTC().Add(time.Duration(duration))
@@ -192,7 +176,7 @@ var createPreAuthKeyCmd = &cobra.Command{
 
 		request.Expiration = timestamppb.New(expiration)
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
@@ -203,8 +187,6 @@ var createPreAuthKeyCmd = &cobra.Command{
 				fmt.Sprintf("Cannot create Pre Auth Key: %s\n", err),
 				output,
 			)
-
-			return
 		}
 
 		SuccessOutput(response.GetPreAuthKey(), response.GetPreAuthKey().GetKey(), output)
@@ -224,14 +206,12 @@ var expirePreAuthKeyCmd = &cobra.Command{
 	},
 	Run: func(cmd *cobra.Command, args []string) {
 		output, _ := cmd.Flags().GetString("output")
-		user, err := cmd.Flags().GetString("user")
+		user, err := cmd.Flags().GetUint64("user")
 		if err != nil {
 			ErrorOutput(err, fmt.Sprintf("Error getting user: %s", err), output)
-
-			return
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
@@ -247,8 +227,6 @@ var expirePreAuthKeyCmd = &cobra.Command{
 				fmt.Sprintf("Cannot expire Pre Auth Key: %s\n", err),
 				output,
 			)
-
-			return
 		}
 
 		SuccessOutput(response, "Key expired", output)

cmd/headscale/cli/root.go

@@ -4,11 +4,13 @@ import (
 	"fmt"
 	"os"
 	"runtime"
+	"slices"
 
 	"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"
 )
 
@@ -24,6 +26,11 @@ func init() {
 		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)")
@@ -49,39 +56,34 @@ func initConfig() {
 		}
 	}
 
-	cfg, err := types.GetHeadscaleConfig()
-	if err != nil {
-		log.Fatal().Caller().Err(err).Msg("Failed to get headscale configuration")
-	}
-
 	machineOutput := HasMachineOutputFlag()
 
-	zerolog.SetGlobalLevel(cfg.Log.Level)
-
 	// If the user has requested a "node" readable format,
 	// then disable login so the output remains valid.
 	if machineOutput {
 		zerolog.SetGlobalLevel(zerolog.Disabled)
 	}
 
-	if cfg.Log.Format == types.JSONLogFormat {
+	logFormat := viper.GetString("log.format")
+	if logFormat == types.JSONLogFormat {
 		log.Logger = log.Output(os.Stdout)
 	}
 
-	if !cfg.DisableUpdateCheck && !machineOutput {
+	disableUpdateCheck := viper.GetBool("disable_check_updates")
+	if !disableUpdateCheck && !machineOutput {
 		if (runtime.GOOS == "linux" || runtime.GOOS == "darwin") &&
-			Version != "dev" {
+			types.Version != "dev" {
 			githubTag := &latest.GithubTag{
 				Owner:      "juanfont",
 				Repository: "headscale",
 			}
-			res, err := latest.Check(githubTag, Version)
+			res, err := latest.Check(githubTag, types.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,
-					Version,
+					types.Version,
 				)
 			}
 		}

cmd/headscale/cli/routes.go

@@ -1,298 +0,0 @@
-package cli
-
-import (
-	"fmt"
-	"log"
-	"net/netip"
-	"strconv"
-
-	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
-	"github.com/juanfont/headscale/hscontrol/types"
-	"github.com/pterm/pterm"
-	"github.com/spf13/cobra"
-	"google.golang.org/grpc/status"
-)
-
-const (
-	Base10 = 10
-)
-
-func init() {
-	rootCmd.AddCommand(routesCmd)
-	listRoutesCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
-	routesCmd.AddCommand(listRoutesCmd)
-
-	enableRouteCmd.Flags().Uint64P("route", "r", 0, "Route identifier (ID)")
-	err := enableRouteCmd.MarkFlagRequired("route")
-	if err != nil {
-		log.Fatalf(err.Error())
-	}
-	routesCmd.AddCommand(enableRouteCmd)
-
-	disableRouteCmd.Flags().Uint64P("route", "r", 0, "Route identifier (ID)")
-	err = disableRouteCmd.MarkFlagRequired("route")
-	if err != nil {
-		log.Fatalf(err.Error())
-	}
-	routesCmd.AddCommand(disableRouteCmd)
-
-	deleteRouteCmd.Flags().Uint64P("route", "r", 0, "Route identifier (ID)")
-	err = deleteRouteCmd.MarkFlagRequired("route")
-	if err != nil {
-		log.Fatalf(err.Error())
-	}
-	routesCmd.AddCommand(deleteRouteCmd)
-}
-
-var routesCmd = &cobra.Command{
-	Use:     "routes",
-	Short:   "Manage the routes of Headscale",
-	Aliases: []string{"r", "route"},
-}
-
-var listRoutesCmd = &cobra.Command{
-	Use:     "list",
-	Short:   "List all routes",
-	Aliases: []string{"ls", "show"},
-	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()
-
-		var routes []*v1.Route
-
-		if machineID == 0 {
-			response, err := client.GetRoutes(ctx, &v1.GetRoutesRequest{})
-			if err != nil {
-				ErrorOutput(
-					err,
-					fmt.Sprintf("Cannot get nodes: %s", status.Convert(err).Message()),
-					output,
-				)
-
-				return
-			}
-
-			if output != "" {
-				SuccessOutput(response.GetRoutes(), "", output)
-
-				return
-			}
-
-			routes = response.GetRoutes()
-		} else {
-			response, err := client.GetNodeRoutes(ctx, &v1.GetNodeRoutesRequest{
-				NodeId: machineID,
-			})
-			if err != nil {
-				ErrorOutput(
-					err,
-					fmt.Sprintf("Cannot get routes for node %d: %s", machineID, status.Convert(err).Message()),
-					output,
-				)
-
-				return
-			}
-
-			if output != "" {
-				SuccessOutput(response.GetRoutes(), "", output)
-
-				return
-			}
-
-			routes = response.GetRoutes()
-		}
-
-		tableData := routesToPtables(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 a route as enabled",
-	Long:  `This command will make as enabled a given route.`,
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		routeID, err := cmd.Flags().GetUint64("route")
-		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()
-
-		response, err := client.EnableRoute(ctx, &v1.EnableRouteRequest{
-			RouteId: routeID,
-		})
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot enable route %d: %s", routeID, status.Convert(err).Message()),
-				output,
-			)
-
-			return
-		}
-
-		if output != "" {
-			SuccessOutput(response, "", output)
-
-			return
-		}
-	},
-}
-
-var disableRouteCmd = &cobra.Command{
-	Use:   "disable",
-	Short: "Set as disabled a given route",
-	Long:  `This command will make as disabled a given route.`,
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		routeID, err := cmd.Flags().GetUint64("route")
-		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()
-
-		response, err := client.DisableRoute(ctx, &v1.DisableRouteRequest{
-			RouteId: routeID,
-		})
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot disable route %d: %s", routeID, status.Convert(err).Message()),
-				output,
-			)
-
-			return
-		}
-
-		if output != "" {
-			SuccessOutput(response, "", output)
-
-			return
-		}
-	},
-}
-
-var deleteRouteCmd = &cobra.Command{
-	Use:   "delete",
-	Short: "Delete a given route",
-	Long:  `This command will delete a given route.`,
-	Run: func(cmd *cobra.Command, args []string) {
-		output, _ := cmd.Flags().GetString("output")
-
-		routeID, err := cmd.Flags().GetUint64("route")
-		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()
-
-		response, err := client.DeleteRoute(ctx, &v1.DeleteRouteRequest{
-			RouteId: routeID,
-		})
-		if err != nil {
-			ErrorOutput(
-				err,
-				fmt.Sprintf("Cannot delete route %d: %s", routeID, status.Convert(err).Message()),
-				output,
-			)
-
-			return
-		}
-
-		if output != "" {
-			SuccessOutput(response, "", output)
-
-			return
-		}
-	},
-}
-
-// routesToPtables converts the list of routes to a nice table.
-func routesToPtables(routes []*v1.Route) pterm.TableData {
-	tableData := pterm.TableData{{"ID", "Node", "Prefix", "Advertised", "Enabled", "Primary"}}
-
-	for _, route := range routes {
-		var isPrimaryStr string
-		prefix, err := netip.ParsePrefix(route.GetPrefix())
-		if err != nil {
-			log.Printf("Error parsing prefix %s: %s", route.GetPrefix(), err)
-
-			continue
-		}
-		if prefix == types.ExitRouteV4 || prefix == types.ExitRouteV6 {
-			isPrimaryStr = "-"
-		} else {
-			isPrimaryStr = strconv.FormatBool(route.GetIsPrimary())
-		}
-
-		tableData = append(tableData,
-			[]string{
-				strconv.FormatUint(route.GetId(), Base10),
-				route.GetNode().GetGivenName(),
-				route.GetPrefix(),
-				strconv.FormatBool(route.GetAdvertised()),
-				strconv.FormatBool(route.GetEnabled()),
-				isPrimaryStr,
-			})
-	}
-
-	return tableData
-}

cmd/headscale/cli/serve.go

@@ -1,6 +1,9 @@
 package cli
 
 import (
+	"errors"
+	"net/http"
+
 	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
 )
@@ -16,14 +19,14 @@ var serveCmd = &cobra.Command{
 		return nil
 	},
 	Run: func(cmd *cobra.Command, args []string) {
-		app, err := getHeadscaleApp()
+		app, err := newHeadscaleServerWithConfig()
 		if err != nil {
 			log.Fatal().Caller().Err(err).Msg("Error initializing")
 		}
 
 		err = app.Serve()
-		if err != nil {
-			log.Fatal().Caller().Err(err).Msg("Error starting server")
+		if err != nil && !errors.Is(err, http.ErrServerClosed) {
+			log.Fatal().Caller().Err(err).Msg("Headscale ran into an error and had to shut down.")
 		}
 	},
 }

cmd/headscale/cli/users.go

@@ -3,6 +3,7 @@ package cli
 import (
 	"errors"
 	"fmt"
+	"net/url"
 
 	survey "github.com/AlecAivazis/survey/v2"
 	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
@@ -12,12 +13,46 @@ import (
 	"google.golang.org/grpc/status"
 )
 
+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.
+// If both are empty, it will exit the program with an error.
+func usernameAndIDFromFlag(cmd *cobra.Command) (uint64, string) {
+	username, _ := cmd.Flags().GetString("name")
+	identifier, _ := cmd.Flags().GetInt64("identifier")
+	if username == "" && identifier < 0 {
+		err := errors.New("--name or --identifier flag is required")
+		ErrorOutput(
+			err,
+			fmt.Sprintf(
+				"Cannot rename user: %s",
+				status.Convert(err).Message(),
+			),
+			"",
+		)
+	}
+
+	return uint64(identifier), username
+}
+
 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")
+	renameNodeCmd.MarkFlagRequired("new-name")
 }
 
 var errMissingParameter = errors.New("missing parameters")
@@ -44,7 +79,7 @@ var createUserCmd = &cobra.Command{
 
 		userName := args[0]
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
@@ -52,6 +87,28 @@ var createUserCmd = &cobra.Command{
 
 		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 {
+				ErrorOutput(
+					err,
+					fmt.Sprintf(
+						"Invalid Picture URL: %s",
+						err,
+					),
+					output,
+				)
+			}
+			request.PictureUrl = pictureURL
+		}
+
 		log.Trace().Interface("request", request).Msg("Sending CreateUser request")
 		response, err := client.CreateUser(ctx, request)
 		if err != nil {
@@ -63,8 +120,6 @@ var createUserCmd = &cobra.Command{
 				),
 				output,
 			)
-
-			return
 		}
 
 		SuccessOutput(response.GetUser(), "User created", output)
@@ -72,47 +127,49 @@ var createUserCmd = &cobra.Command{
 }
 
 var destroyUserCmd = &cobra.Command{
-	Use:     "destroy NAME",
+	Use:     "destroy --identifier ID or --name NAME",
 	Short:   "Destroys a user",
 	Aliases: []string{"delete"},
-	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")
 
-		userName := args[0]
-
-		request := &v1.GetUserRequest{
-			Name: userName,
+		id, username := usernameAndIDFromFlag(cmd)
+		request := &v1.ListUsersRequest{
+			Name: username,
+			Id:   id,
 		}
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
-		_, err := client.GetUser(ctx, request)
+		users, err := client.ListUsers(ctx, request)
 		if err != nil {
 			ErrorOutput(
 				err,
 				fmt.Sprintf("Error: %s", status.Convert(err).Message()),
 				output,
 			)
-
-			return
 		}
 
+		if len(users.GetUsers()) != 1 {
+			err := fmt.Errorf("Unable to determine user to delete, query returned multiple users, use ID")
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error: %s", status.Convert(err).Message()),
+				output,
+			)
+		}
+
+		user := users.GetUsers()[0]
+
 		confirm := false
 		force, _ := cmd.Flags().GetBool("force")
 		if !force {
 			prompt := &survey.Confirm{
 				Message: fmt.Sprintf(
-					"Do you want to remove the user '%s' and any associated preauthkeys?",
-					userName,
+					"Do you want to remove the user %q (%d) and any associated preauthkeys?",
+					user.GetName(), user.GetId(),
 				),
 			}
 			err := survey.AskOne(prompt, &confirm)
@@ -122,7 +179,7 @@ var destroyUserCmd = &cobra.Command{
 		}
 
 		if confirm || force {
-			request := &v1.DeleteUserRequest{Name: userName}
+			request := &v1.DeleteUserRequest{Id: user.GetId()}
 
 			response, err := client.DeleteUser(ctx, request)
 			if err != nil {
@@ -134,8 +191,6 @@ var destroyUserCmd = &cobra.Command{
 					),
 					output,
 				)
-
-				return
 			}
 			SuccessOutput(response, "User destroyed", output)
 		} else {
@@ -151,12 +206,29 @@ var listUsersCmd = &cobra.Command{
 	Run: func(cmd *cobra.Command, args []string) {
 		output, _ := cmd.Flags().GetString("output")
 
-		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
 		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)
+			break
+		case username != "":
+			request.Name = username
+			break
+		case email != "":
+			request.Email = email
+			break
+		}
+
 		response, err := client.ListUsers(ctx, request)
 		if err != nil {
 			ErrorOutput(
@@ -164,23 +236,21 @@ var listUsersCmd = &cobra.Command{
 				fmt.Sprintf("Cannot get users: %s", status.Convert(err).Message()),
 				output,
 			)
-
-			return
 		}
 
 		if output != "" {
 			SuccessOutput(response.GetUsers(), "", output)
-
-			return
 		}
 
-		tableData := pterm.TableData{{"ID", "Name", "Created"}}
+		tableData := pterm.TableData{{"ID", "Name", "Username", "Email", "Created"}}
 		for _, user := range response.GetUsers() {
 			tableData = append(
 				tableData,
 				[]string{
-					user.GetId(),
+					fmt.Sprintf("%d", user.GetId()),
+					user.GetDisplayName(),
 					user.GetName(),
+					user.GetEmail(),
 					user.GetCreatedAt().AsTime().Format("2006-01-02 15:04:05"),
 				},
 			)
@@ -192,37 +262,53 @@ var listUsersCmd = &cobra.Command{
 				fmt.Sprintf("Failed to render pterm table: %s", err),
 				output,
 			)
-
-			return
 		}
 	},
 }
 
 var renameUserCmd = &cobra.Command{
-	Use:     "rename OLD_NAME NEW_NAME",
+	Use:     "rename",
 	Short:   "Renames a user",
 	Aliases: []string{"mv"},
-	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()
+		ctx, client, conn, cancel := newHeadscaleCLIWithConfig()
 		defer cancel()
 		defer conn.Close()
 
-		request := &v1.RenameUserRequest{
-			OldName: args[0],
-			NewName: args[1],
+		id, username := usernameAndIDFromFlag(cmd)
+		listReq := &v1.ListUsersRequest{
+			Name: username,
+			Id:   id,
 		}
 
-		response, err := client.RenameUser(ctx, request)
+		users, err := client.ListUsers(ctx, listReq)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error: %s", status.Convert(err).Message()),
+				output,
+			)
+		}
+
+		if len(users.GetUsers()) != 1 {
+			err := fmt.Errorf("Unable to determine user to delete, query returned multiple users, use ID")
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error: %s", status.Convert(err).Message()),
+				output,
+			)
+		}
+
+		newName, _ := cmd.Flags().GetString("new-name")
+
+		renameReq := &v1.RenameUserRequest{
+			OldId:   id,
+			NewName: newName,
+		}
+
+		response, err := client.RenameUser(ctx, renameReq)
 		if err != nil {
 			ErrorOutput(
 				err,
@@ -232,8 +318,6 @@ var renameUserCmd = &cobra.Command{
 				),
 				output,
 			)
-
-			return
 		}
 
 		SuccessOutput(response.GetUser(), "User renamed", output)

cmd/headscale/cli/utils.go

@@ -6,11 +6,9 @@ import (
 	"encoding/json"
 	"fmt"
 	"os"
-	"reflect"
 
 	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
 	"github.com/juanfont/headscale/hscontrol"
-	"github.com/juanfont/headscale/hscontrol/policy"
 	"github.com/juanfont/headscale/hscontrol/types"
 	"github.com/juanfont/headscale/hscontrol/util"
 	"github.com/rs/zerolog/log"
@@ -25,40 +23,25 @@ const (
 	SocketWritePermissions  = 0o666
 )
 
-func getHeadscaleApp() (*hscontrol.Headscale, error) {
-	cfg, err := types.GetHeadscaleConfig()
+func newHeadscaleServerWithConfig() (*hscontrol.Headscale, error) {
+	cfg, err := types.LoadServerConfig()
 	if err != nil {
 		return nil, fmt.Errorf(
-			"failed to load configuration while creating headscale instance: %w",
+			"loading configuration: %w",
 			err,
 		)
 	}
 
 	app, err := hscontrol.NewHeadscale(cfg)
 	if err != nil {
-		return nil, err
-	}
-
-	// We are doing this here, as in the future could be cool to have it also hot-reload
-
-	if cfg.ACL.PolicyPath != "" {
-		aclPath := util.AbsolutePathFromConfigPath(cfg.ACL.PolicyPath)
-		pol, err := policy.LoadACLPolicyFromPath(aclPath)
-		if err != nil {
-			log.Fatal().
-				Str("path", aclPath).
-				Err(err).
-				Msg("Could not load the ACL policy")
-		}
-
-		app.ACLPolicy = pol
+		return nil, fmt.Errorf("creating new headscale: %w", err)
 	}
 
 	return app, nil
 }
 
-func getHeadscaleCLIClient() (context.Context, v1.HeadscaleServiceClient, *grpc.ClientConn, context.CancelFunc) {
-	cfg, err := types.GetHeadscaleConfig()
+func newHeadscaleCLIWithConfig() (context.Context, v1.HeadscaleServiceClient, *grpc.ClientConn, context.CancelFunc) {
+	cfg, err := types.LoadCLIConfig()
 	if err != nil {
 		log.Fatal().
 			Err(err).
@@ -89,7 +72,7 @@ func getHeadscaleCLIClient() (context.Context, v1.HeadscaleServiceClient, *grpc.
 
 		// Try to give the user better feedback if we cannot write to the headscale
 		// socket.
-		socket, err := os.OpenFile(cfg.UnixSocket, os.O_WRONLY, SocketWritePermissions) //nolint
+		socket, err := os.OpenFile(cfg.UnixSocket, os.O_WRONLY, SocketWritePermissions) // nolint
 		if err != nil {
 			if os.IsPermission(err) {
 				log.Fatal().
@@ -147,7 +130,7 @@ func getHeadscaleCLIClient() (context.Context, v1.HeadscaleServiceClient, *grpc.
 	return ctx, client, conn, cancel
 }
 
-func SuccessOutput(result interface{}, override string, outputFormat string) {
+func output(result interface{}, override string, outputFormat string) string {
 	var jsonBytes []byte
 	var err error
 	switch outputFormat {
@@ -167,22 +150,27 @@ func SuccessOutput(result interface{}, override string, outputFormat string) {
 			log.Fatal().Err(err).Msg("failed to unmarshal output")
 		}
 	default:
-		//nolint
-		fmt.Println(override)
-
-		return
+		// nolint
+		return override
 	}
 
-	//nolint
-	fmt.Println(string(jsonBytes))
+	return string(jsonBytes)
 }
 
+// SuccessOutput prints the result to stdout and exits with status code 0.
+func SuccessOutput(result interface{}, override string, outputFormat string) {
+	fmt.Println(output(result, override, outputFormat))
+	os.Exit(0)
+}
+
+// ErrorOutput prints an error message to stderr and exits with status code 1.
 func ErrorOutput(errResult error, override string, outputFormat string) {
 	type errOutput struct {
 		Error string `json:"error"`
 	}
 
-	SuccessOutput(errOutput{errResult.Error()}, override, outputFormat)
+	fmt.Fprintf(os.Stderr, "%s\n", output(errOutput{errResult.Error()}, override, outputFormat))
+	os.Exit(1)
 }
 
 func HasMachineOutputFlag() bool {
@@ -212,13 +200,3 @@ func (t tokenAuth) GetRequestMetadata(
 func (tokenAuth) RequireTransportSecurity() bool {
 	return true
 }
-
-func contains[T string](ts []T, t T) bool {
-	for _, v := range ts {
-		if reflect.DeepEqual(v, t) {
-			return true
-		}
-	}
-
-	return false
-}

cmd/headscale/cli/version.go

@@ -1,11 +1,10 @@
 package cli
 
 import (
+	"github.com/juanfont/headscale/hscontrol/types"
 	"github.com/spf13/cobra"
 )
 
-var Version = "dev"
-
 func init() {
 	rootCmd.AddCommand(versionCmd)
 }
@@ -16,6 +15,9 @@ var versionCmd = &cobra.Command{
 	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)
+		SuccessOutput(map[string]string{
+			"version": types.Version,
+			"commit":  types.GitCommitHash,
+		}, types.Version, output)
 	},
 }

cmd/headscale/headscale_test.go

@@ -4,7 +4,6 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
-	"strings"
 	"testing"
 
 	"github.com/juanfont/headscale/hscontrol/types"
@@ -63,7 +62,6 @@ func (*Suite) TestConfigFileLoading(c *check.C) {
 	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(
 		util.GetFileMode("unix_socket_permission"),
 		check.Equals,
@@ -106,7 +104,6 @@ func (*Suite) TestConfigLoading(c *check.C) {
 	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(
 		util.GetFileMode("unix_socket_permission"),
 		check.Equals,
@@ -115,93 +112,3 @@ func (*Suite) TestConfigLoading(c *check.C) {
 	c.Assert(viper.GetBool("logtail.enabled"), check.Equals, false)
 	c.Assert(viper.GetBool("randomize_client_port"), check.Equals, false)
 }
-
-func (*Suite) TestDNSConfigLoading(c *check.C) {
-	tmpDir, err := os.MkdirTemp("", "headscale")
-	if err != nil {
-		c.Fatal(err)
-	}
-	defer os.RemoveAll(tmpDir)
-
-	path, err := os.Getwd()
-	if err != nil {
-		c.Fatal(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)
-	}
-
-	// Load example config, it should load without validation errors
-	err = types.LoadConfig(tmpDir, false)
-	c.Assert(err, check.IsNil)
-
-	dnsConfig, baseDomain := types.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 := os.WriteFile(configFile, configYaml, 0o600)
-	if err != nil {
-		c.Fatalf("Couldn't write file %s", configFile)
-	}
-}
-
-func (*Suite) TestTLSConfigValidation(c *check.C) {
-	tmpDir, err := os.MkdirTemp("", "headscale")
-	if err != nil {
-		c.Fatal(err)
-	}
-	// defer os.RemoveAll(tmpDir)
-	configYaml := []byte(`---
-tls_letsencrypt_hostname: example.com
-tls_letsencrypt_challenge_type: ""
-tls_cert_path: abc.pem
-noise:
-  private_key_path: noise_private.key`)
-	writeConfig(c, tmpDir, configYaml)
-
-	// Check configuration validation errors (1)
-	err = types.LoadConfig(tmpDir, false)
-	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(`---
-noise:
-  private_key_path: noise_private.key
-server_url: http://127.0.0.1:8080
-tls_letsencrypt_hostname: example.com
-tls_letsencrypt_challenge_type: TLS-ALPN-01
-`)
-	writeConfig(c, tmpDir, configYaml)
-	err = types.LoadConfig(tmpDir, false)
-	c.Assert(err, check.IsNil)
-}

config-example.yaml

@@ -18,10 +18,8 @@ server_url: http://127.0.0.1:8080
 # listen_addr: 0.0.0.0:8080
 listen_addr: 127.0.0.1:8080
 
-# Address to listen to /metrics, you may want
-# to keep this endpoint private to your internal
-# network
-#
+# Address to listen to /metrics and /debug, you may want
+# to keep this endpoint private to your internal network
 metrics_listen_addr: 127.0.0.1:9090
 
 # Address to listen for gRPC.
@@ -43,9 +41,9 @@ grpc_allow_insecure: false
 # The Noise section includes specific configuration for the
 # TS2021 Noise protocol
 noise:
-  # The Noise private key is used to encrypt the
-  # traffic between headscale and Tailscale clients when
-  # using the new Noise-based protocol.
+  # The Noise private key is used to encrypt the traffic between headscale and
+  # Tailscale clients when using the new Noise-based protocol. A missing key
+  # will be automatically generated.
   private_key_path: /var/lib/headscale/noise_private.key
 
 # List of IP prefixes to allocate tailaddresses from.
@@ -58,8 +56,8 @@ noise:
 # IPv4: https://github.com/tailscale/tailscale/blob/22ebb25e833264f58d7c3f534a8b166894a89536/net/tsaddr/tsaddr.go#L33
 # Any other range is NOT supported, and it will cause unexpected issues.
 prefixes:
-  v6: fd7a:115c:a1e0::/48
   v4: 100.64.0.0/10
+  v6: fd7a:115c:a1e0::/48
 
   # Strategy used for allocation of IPs to nodes, available options:
   # - sequential (default): assigns the next free IP from the previous given IP.
@@ -93,10 +91,8 @@ derp:
     # For more details on how this works, check this great article: https://tailscale.com/blog/how-tailscale-works/
     stun_listen_addr: "0.0.0.0:3478"
 
-    # Private key used to encrypt the traffic between headscale DERP
-    # and Tailscale clients.
-    # The private key file will be autogenerated if it's missing.
-    #
+    # Private key used to encrypt the traffic between headscale DERP and
+    # Tailscale clients. A missing key will be automatically generated.
     private_key_path: /var/lib/headscale/derp_server_private.key
 
     # This flag can be used, so the DERP map entry for the embedded DERP server is not written automatically,
@@ -105,7 +101,7 @@ derp:
     automatically_add_embedded_derp_region: true
 
     # For better connection stability (especially when using an Exit-Node and DNS is not working),
-    # it is possible to optionall add the public IPv4 and IPv6 address to the Derp-Map using:
+    # it is possible to optionally add the public IPv4 and IPv6 address to the Derp-Map using:
     ipv4: 1.2.3.4
     ipv6: 2001:db8::1
 
@@ -138,13 +134,44 @@ disable_check_updates: false
 ephemeral_node_inactivity_timeout: 30m
 
 database:
+  # Database type. Available options: sqlite, postgres
+  # Please note that using Postgres is highly discouraged as it is only supported for legacy reasons.
+  # All new development, testing and optimisations are done with SQLite in mind.
   type: sqlite
 
+  # Enable debug mode. This setting requires the log.level to be set to "debug" or "trace".
+  debug: false
+
+  # GORM configuration settings.
+  gorm:
+    # Enable prepared statements.
+    prepare_stmt: true
+
+    # Enable parameterized queries.
+    parameterized_queries: true
+
+    # Skip logging "record not found" errors.
+    skip_err_record_not_found: true
+
+    # Threshold for slow queries in milliseconds.
+    slow_threshold: 1000
+
   # SQLite config
   sqlite:
     path: /var/lib/headscale/db.sqlite
 
+    # Enable WAL mode for SQLite. This is recommended for production environments.
+    # https://www.sqlite.org/wal.html
+    write_ahead_log: true
+
+    # Maximum number of WAL file frames before the WAL file is automatically checkpointed.
+    # https://www.sqlite.org/c3ref/wal_autocheckpoint.html
+    # Set to 0 to disable automatic checkpointing.
+    wal_autocheckpoint: 1000
+
   # # Postgres config
+  # Please note that using Postgres is highly discouraged as it is only supported for legacy reasons.
+  # See database.type for more information.
   # postgres:
   #   # If using a Unix socket to connect to Postgres, set the socket path in the 'host' field and leave 'port' blank.
   #   host: localhost
@@ -183,7 +210,7 @@ tls_letsencrypt_cache_dir: /var/lib/headscale/cache
 
 # Type of ACME challenge to use, currently supported types:
 # HTTP-01 or TLS-ALPN-01
-# See [docs/tls.md](docs/tls.md) for more information
+# See: docs/ref/tls.md for more information
 tls_letsencrypt_challenge_type: HTTP-01
 # When HTTP-01 challenge is chosen, letsencrypt must set up a
 # verification endpoint, and it will be listening on:
@@ -199,10 +226,17 @@ log:
   format: text
   level: info
 
-# Path to a file containg ACL policies.
-# ACLs can be defined as YAML or HUJSON.
-# https://tailscale.com/kb/1018/acls/
-acl_policy_path: ""
+## Policy
+# headscale supports Tailscale's ACL policies.
+# Please have a look to their KB to better
+# understand the concepts: https://tailscale.com/kb/1018/acls/
+policy:
+  # The mode can be "file" or "database" that defines
+  # where the ACL policies are stored and read from.
+  mode: file
+  # If the mode is set to "file", the path to a
+  # HuJSON file containing ACL policies.
+  path: ""
 
 ## DNS
 #
@@ -213,59 +247,73 @@ acl_policy_path: ""
 # - https://tailscale.com/kb/1081/magicdns/
 # - https://tailscale.com/blog/2021-09-private-dns-with-magicdns/
 #
-dns_config:
-  # Whether to prefer using Headscale provided DNS or use local.
-  override_local_dns: true
+# Please note that for the DNS configuration to have any effect,
+# clients must have the `--accept-dns=true` option enabled. This is the
+# default for the Tailscale client. This option is enabled by default
+# in the Tailscale client.
+#
+# Setting _any_ of the configuration and `--accept-dns=true` on the
+# clients will integrate with the DNS manager on the client or
+# overwrite /etc/resolv.conf.
+# https://tailscale.com/kb/1235/resolv-conf
+#
+# If you want stop Headscale from managing the DNS configuration
+# all the fields under `dns` should be set to empty values.
+dns:
+  # Whether to use [MagicDNS](https://tailscale.com/kb/1081/magicdns/).
+  magic_dns: true
+
+  # Defines the base domain to create the hostnames for MagicDNS.
+  # This domain _must_ be different from the server_url domain.
+  # `base_domain` must be a FQDN, without the trailing dot.
+  # The FQDN of the hosts will be
+  # `hostname.base_domain` (e.g., _myhost.example.com_).
+  base_domain: example.com
+
+  # Whether to use the local DNS settings of a node (default) or override the
+  # local DNS settings and force the use of Headscale's DNS configuration.
+  override_local_dns: false
 
   # List of DNS servers to expose to clients.
   nameservers:
-    - 1.1.1.1
+    global:
+      - 1.1.1.1
+      - 1.0.0.1
+      - 2606:4700:4700::1111
+      - 2606:4700:4700::1001
 
-  # NextDNS (see https://tailscale.com/kb/1218/nextdns/).
-  # "abc123" is example NextDNS ID, replace with yours.
-  #
-  # With metadata sharing:
-  # nameservers:
-  #   - https://dns.nextdns.io/abc123
-  #
-  # Without metadata sharing:
-  # nameservers:
-  #   - 2a07:a8c0::ab:c123
-  #   - 2a07:a8c1::ab:c123
+      # NextDNS (see https://tailscale.com/kb/1218/nextdns/).
+      # "abc123" is example NextDNS ID, replace with yours.
+      # - https://dns.nextdns.io/abc123
 
-  # Split DNS (see https://tailscale.com/kb/1054/dns/),
-  # list of search domains and the DNS to query for each one.
-  #
-  # restricted_nameservers:
-  #   foo.bar.com:
-  #     - 1.1.1.1
-  #   darp.headscale.net:
-  #     - 1.1.1.1
-  #     - 8.8.8.8
+    # Split DNS (see https://tailscale.com/kb/1054/dns/),
+    # a map of domains and which DNS server to use for each.
+    split:
+      {}
+      # foo.bar.com:
+      #   - 1.1.1.1
+      # darp.headscale.net:
+      #   - 1.1.1.1
+      #   - 8.8.8.8
 
-  # Search domains to inject.
-  domains: []
+  # Set custom DNS search domains. With MagicDNS enabled,
+  # your tailnet base_domain is always the first search domain.
+  search_domains: []
 
   # Extra DNS records
-  # so far only A-records are supported (on the tailscale side)
-  # See https://github.com/juanfont/headscale/blob/main/docs/dns-records.md#Limitations
-  # extra_records:
+  # so far only A and AAAA records are supported (on the tailscale side)
+  # See: docs/ref/dns.md
+  extra_records: []
   #   - name: "grafana.myvpn.example.com"
   #     type: "A"
   #     value: "100.64.0.3"
   #
   #   # you can also put it in one line
   #   - { name: "prometheus.myvpn.example.com", type: "A", value: "100.64.0.3" }
-
-  # Whether to use [MagicDNS](https://tailscale.com/kb/1081/magicdns/).
-  # Only works if there is at least a nameserver defined.
-  magic_dns: true
-
-  # Defines the base domain to create the hostnames for MagicDNS.
-  # `base_domain` must be a FQDNs, without the trailing dot.
-  # The FQDN of the hosts will be
-  # `hostname.user.base_domain` (e.g., _myhost.myuser.example.com_).
-  base_domain: example.com
+  #
+  # Alternatively, extra DNS records can be loaded from a JSON file.
+  # Headscale processes this file on each change.
+  # extra_records_path: /var/lib/headscale/extra-records.json
 
 # Unix socket used for the CLI to connect without authentication
 # Note: for production you will want to set this to something like:
@@ -316,12 +364,30 @@ unix_socket_permission: "0770"
 #   allowed_users:
 #     - alice@example.com
 #
-#   # If `strip_email_domain` is set to `true`, the domain part of the username email address will be removed.
-#   # This will transform `first-name.last-name@example.com` to the user `first-name.last-name`
-#   # If `strip_email_domain` is set to `false` the domain part will NOT be removed resulting to the following
-#   user: `first-name.last-name.example.com`
+#   # Optional: PKCE (Proof Key for Code Exchange) configuration
+#   # PKCE adds an additional layer of security to the OAuth 2.0 authorization code flow
+#   # by preventing authorization code interception attacks
+#   # See https://datatracker.ietf.org/doc/html/rfc7636
+#   pkce:
+#     # Enable or disable PKCE support (default: false)
+#     enabled: false
+#     # PKCE method to use:
+#     # - plain: Use plain code verifier
+#     # - S256: Use SHA256 hashed code verifier (default, recommended)
+#     method: S256
 #
-#   strip_email_domain: true
+#   # Map legacy users from pre-0.24.0 versions of headscale to the new OIDC users
+#   # by taking the username from the legacy user and matching it with the username
+#   # provided by the OIDC. This is useful when migrating from legacy users to OIDC
+#   # to force them using the unique identifier from the OIDC and to give them a
+#   # proper display name and picture if available.
+#   # Note that this will only work if the username from the legacy user is the same
+#   # and there is a possibility for account takeover should a username have changed
+#   # with the provider.
+#   # When this feature is disabled, it will cause all new logins to be created as new users.
+#   # Note this option will be removed in the future and should be set to false
+#   # on all new installations, or when all users have logged in with OIDC once.
+#   map_legacy_users: false
 
 # Logtail configuration
 # Logtail is Tailscales logging and auditing infrastructure, it allows the control panel

docs/about/clients.md

@@ -0,0 +1,16 @@
+# Client and operating system support
+
+We aim to support the [**last 10 releases** of the Tailscale client](https://tailscale.com/changelog#client) on all
+provided operating systems and platforms. Some platforms might require additional configuration to connect with
+headscale.
+
+| OS      | Supports headscale                                                                                    |
+| ------- | ----------------------------------------------------------------------------------------------------- |
+| Linux   | Yes                                                                                                   |
+| OpenBSD | Yes                                                                                                   |
+| FreeBSD | Yes                                                                                                   |
+| Windows | Yes (see [docs](../usage/connect/windows.md) and `/windows` on your headscale for more information)   |
+| Android | Yes (see [docs](../usage/connect/android.md) for more information)                                    |
+| macOS   | Yes (see [docs](../usage/connect/apple.md#macos) and `/apple` on your headscale for more information) |
+| iOS     | Yes (see [docs](../usage/connect/apple.md#ios) and `/apple` on your headscale for more information)   |
+| tvOS    | Yes (see [docs](../usage/connect/apple.md#tvos) and `/apple` on your headscale for more information)  |

docs/about/contributing.md

@@ -0,0 +1,3 @@
+{%
+    include-markdown "../../CONTRIBUTING.md"
+%}

docs/about/faq.md

@@ -0,0 +1,137 @@
+# Frequently Asked Questions
+
+## What is the design goal of headscale?
+
+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.
+
+## How can I contribute?
+
+Headscale is "Open Source, acknowledged contribution", this means that any
+contribution will have to be discussed with the Maintainers before being submitted.
+
+Please see [Contributing](contributing.md) for more information.
+
+## Why is 'acknowledged contribution' the chosen model?
+
+Both maintainers have full-time jobs and families, and we want to avoid burnout. We also want to avoid frustration from contributors when their PRs are not accepted.
+
+We are more than happy to exchange emails, or to have dedicated calls before a PR is submitted.
+
+## When/Why is Feature X going to be implemented?
+
+We don't know. We might be working on it. If you're interested in contributing, please post a feature request about it.
+
+Please be aware that there are a number of reasons why we might not accept specific contributions:
+
+- It is not possible to implement the feature in a way that makes sense in a self-hosted environment.
+- Given that we are reverse-engineering Tailscale to satisfy our own curiosity, we might be interested in implementing the feature ourselves.
+- You are not sending unit and integration tests with it.
+
+## Do you support Y method of deploying headscale?
+
+We currently support deploying headscale using our binaries and the DEB packages. Visit our [installation guide using
+official releases](../setup/install/official.md) for more information.
+
+In addition to that, you may use packages provided by the community or from distributions. Learn more in the
+[installation guide using community packages](../setup/install/community.md).
+
+For convenience, we also [build container images with headscale](../setup/install/container.md). But **please be aware that
+we don't officially support deploying headscale using Docker**. On our [Discord server](https://discord.gg/c84AZQhmpx)
+we have a "docker-issues" channel where you can ask for Docker-specific help to the community.
+
+## Scaling / How many clients does Headscale support?
+
+It depends. As often stated, Headscale is not enterprise software and our focus
+is homelabbers and self-hosters. Of course, we do not prevent people from using
+it in a commercial/professional setting and often get questions about scaling.
+
+Please note that when Headscale is developed, performance is not part of the
+consideration as the main audience is considered to be users with a moddest
+amount of devices. We focus on correctness and feature parity with Tailscale
+SaaS over time.
+
+To understand if you might be able to use Headscale for your usecase, I will
+describe two scenarios in an effort to explain what is the central bottleneck
+of Headscale:
+
+1. An environment with 1000 servers
+
+    - they rarely  "move" (change their endpoints)
+    - new nodes are added rarely
+
+2. An environment with 80 laptops/phones (end user devices)
+
+    - nodes move often, e.g. switching from home to office
+
+Headscale calculates a map of all nodes that need to talk to each other,
+creating this "world map" requires a lot of CPU time. When an event that
+requires changes to this map happens, the whole "world" is recalculated, and a
+new "world map" is created for every node in the network.
+
+This means that under certain conditions, Headscale can likely handle 100s
+of devices (maybe more), if there is _little to no change_ happening in the
+network. For example, in Scenario 1, the process of computing the world map is
+extremly demanding due to the size of the network, but when the map has been
+created and the nodes are not changing, the Headscale instance will likely
+return to a very low resource usage until the next time there is an event
+requiring the new map.
+
+In the case of Scenario 2, the process of computing the world map is less
+demanding due to the smaller size of the network, however, the type of nodes
+will likely change frequently, which would lead to a constant resource usage.
+
+Headscale will start to struggle when the two scenarios overlap, e.g. many nodes
+with frequent changes will cause the resource usage to remain constantly high.
+In the worst case scenario, the queue of nodes waiting for their map will grow
+to a point where Headscale never will be able to catch up, and nodes will never
+learn about the current state of the world.
+
+We expect that the performance will improve over time as we improve the code
+base, but it is not a focus. In general, we will never make the tradeoff to make
+things faster on the cost of less maintainable or readable code. We are a small
+team and have to optimise for maintainabillity.
+
+## Which database should I use?
+
+We recommend the use of SQLite as database for headscale:
+
+- SQLite is simple to setup and easy to use
+- It scales well for all of headscale's usecases
+- Development and testing happens primarily on SQLite
+- PostgreSQL is still supported, but is considered to be in "maintenance mode"
+
+The headscale project itself does not provide a tool to migrate from PostgreSQL to SQLite. Please have a look at [the
+related tools documentation](../ref/integration/tools.md) for migration tooling provided by the community.
+
+The choice of database has little to no impact on the performance of the server,
+see [Scaling / How many clients does Headscale support?](#scaling-how-many-clients-does-headscale-support) for understanding how Headscale spends its resources.
+
+## Why is my reverse proxy not working with headscale?
+
+We don't know. We don't use reverse proxies with headscale ourselves, so we don't have any experience with them. We have
+[community documentation](../ref/integration/reverse-proxy.md) on how to configure various reverse proxies, and a
+dedicated "reverse-proxy-issues" channel on our [Discord server](https://discord.gg/c84AZQhmpx) where you can ask for
+help to the community.
+
+## Can I use headscale and tailscale on the same machine?
+
+Running headscale on a machine that is also in the tailnet can cause problems with subnet routers, traffic relay nodes, and MagicDNS. It might work, but it is not supported.
+
+
+## Why do two nodes see each other in their status, even if an ACL allows traffic only in one direction?
+
+A frequent use case is to allow traffic only from one node to another, but not the other way around. For example, the
+workstation of an administrator should be able to connect to all nodes but the nodes themselves shouldn't be able to
+connect back to the administrator's node. Why do all nodes see the administrator's workstation in the output of
+`tailscale status`?
+
+This is essentially how Tailscale works. If traffic is allowed to flow in one direction, then both nodes see each other
+in their output of `tailscale status`. Traffic is still filtered according to the ACL, with the exception of `tailscale
+ping` which is always allowed in either direction.
+
+See also <https://tailscale.com/kb/1087/device-visibility>.

docs/about/features.md

@@ -0,0 +1,38 @@
+# Features
+
+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. This page
+provides on overview of Headscale's feature and compatibility with the Tailscale control server:
+
+- [x] Full "base" support of Tailscale's features
+- [x] Node registration
+    - [x] Interactive
+    - [x] Pre authenticated key
+- [x] [DNS](../ref/dns.md)
+    - [x] [MagicDNS](https://tailscale.com/kb/1081/magicdns)
+    - [x] [Global and restricted nameservers (split DNS)](https://tailscale.com/kb/1054/dns#nameservers)
+    - [x] [search domains](https://tailscale.com/kb/1054/dns#search-domains)
+    - [x] [Extra DNS records (Headscale only)](../ref/dns.md#setting-extra-dns-records)
+- [x] [Taildrop (File Sharing)](https://tailscale.com/kb/1106/taildrop)
+- [x] [Routes](../ref/routes.md)
+    - [x] [Subnet routers](../ref/routes.md#subnet-router)
+    - [x] [Exit nodes](../ref/routes.md#exit-node)
+- [x] Dual stack (IPv4 and IPv6)
+- [x] Ephemeral nodes
+- [x] Embedded [DERP server](https://tailscale.com/kb/1232/derp-servers)
+- [x] Access control lists ([GitHub label "policy"](https://github.com/juanfont/headscale/labels/policy%20%F0%9F%93%9D))
+    - [x] ACL management via API
+    - [x] Some [Autogroups](https://tailscale.com/kb/1396/targets#autogroups), currently: `autogroup:internet`,
+      `autogroup:nonroot`
+    - [x] [Auto approvers](https://tailscale.com/kb/1337/acl-syntax#auto-approvers) for [subnet
+      routers](../ref/routes.md#automatically-approve-routes-of-a-subnet-router) and [exit
+      nodes](../ref/routes.md#automatically-approve-an-exit-node-with-auto-approvers)
+    - [x] [Tailscale SSH](https://tailscale.com/kb/1193/tailscale-ssh)
+* [ ] Node registration using Single-Sign-On (OpenID Connect) ([GitHub label "OIDC"](https://github.com/juanfont/headscale/labels/OIDC))
+    - [x] Basic registration
+    - [x] Update user profile from identity provider
+    - [ ] Dynamic ACL support
+    - [ ] OIDC groups cannot be used in ACLs
+- [ ] [Funnel](https://tailscale.com/kb/1223/funnel) ([#1040](https://github.com/juanfont/headscale/issues/1040))
+- [ ] [Serve](https://tailscale.com/kb/1312/serve) ([#1234](https://github.com/juanfont/headscale/issues/1921))
+- [ ] [Network flow logs](https://tailscale.com/kb/1219/network-flow-logs) ([#1687](https://github.com/juanfont/headscale/issues/1687))

docs/about/help.md

@@ -0,0 +1,5 @@
+# Getting help
+
+Join our [Discord server](https://discord.gg/c84AZQhmpx) for announcements and community support.
+
+Please report bugs via [GitHub issues](https://github.com/juanfont/headscale/issues)

docs/about/releases.md

@@ -0,0 +1,10 @@
+# Releases
+
+All headscale releases are available on the [GitHub release page](https://github.com/juanfont/headscale/releases). Those
+releases are available as binaries for various platforms and architectures, packages for Debian based systems and source
+code archives. Container images are available on [Docker Hub](https://hub.docker.com/r/headscale/headscale) and
+[GitHub Container Registry](https://github.com/juanfont/headscale/pkgs/container/headscale).
+
+An Atom/RSS feed of headscale releases is available [here](https://github.com/juanfont/headscale/releases.atom).
+
+See the "announcements" channel on our [Discord server](https://discord.gg/c84AZQhmpx) for news about headscale.

docs/about/sponsor.md

@@ -0,0 +1,4 @@
+# Sponsor
+
+If you like to support the development of headscale, please consider a donation via
+[ko-fi.com/headscale](https://ko-fi.com/headscale). Thank you!

docs/android-client.md

@@ -1,19 +0,0 @@
-# Connecting an Android client
-
-## Goal
-
-This documentation has the goal of showing how a user can use the official Android [Tailscale](https://tailscale.com) client with `headscale`.
-
-## Installation
-
-Install the official Tailscale Android client from the [Google Play Store](https://play.google.com/store/apps/details?id=com.tailscale.ipn) or [F-Droid](https://f-droid.org/packages/com.tailscale.ipn/).
-
-Ensure that the installed version is at least 1.30.0, as that is the first release to support custom URLs.
-
-## Configuring the headscale URL
-
-After opening the app, the kebab menu icon (three dots) on the top bar on the right must be repeatedly opened and closed until the _Change server_ option appears in the menu. This is where you can enter your headscale URL.
-
-A screen recording of this process can be seen in the `tailscale-android` PR which implemented this functionality: <https://github.com/tailscale/tailscale-android/pull/55>
-
-After saving and restarting the app, selecting the regular _Sign in_ option (non-SSO) should open up the headscale authentication page.

docs/dns-records.md

@@ -1,92 +0,0 @@
-# Setting custom DNS records
-
-!!! warning "Community documentation"
-
-    This page is not actively maintained by the headscale authors and is
-    written by community members. It is _not_ verified by `headscale` developers.
-
-    **It might be outdated and it might miss necessary steps**.
-
-## Goal
-
-This documentation has the goal of showing how a user can set custom DNS records with `headscale`s magic dns.
-An example use case is to serve apps on the same host via a reverse proxy like NGINX, in this case a Prometheus monitoring stack. This allows to nicely access the service with "http://grafana.myvpn.example.com" instead of the hostname and portnum combination "http://hostname-in-magic-dns.myvpn.example.com:3000".
-
-## Setup
-
-### 1. Change the configuration
-
-1. Change the `config.yaml` to contain the desired records like so:
-
-    ```yaml
-    dns_config:
-      ...
-      extra_records:
-        - name: "prometheus.myvpn.example.com"
-          type: "A"
-          value: "100.64.0.3"
-
-        - name: "grafana.myvpn.example.com"
-          type: "A"
-          value: "100.64.0.3"
-      ...
-    ```
-
-1. Restart your headscale instance.
-
-    !!! warning
-
-        Beware of the limitations listed later on!
-
-### 2. Verify that the records are set
-
-You can use a DNS querying tool of your choice on one of your hosts to verify that your newly set records are actually available in MagicDNS, here we used [`dig`](https://man.archlinux.org/man/dig.1.en):
-
-```
-$ dig grafana.myvpn.example.com
-
-; <<>> DiG 9.18.10 <<>> grafana.myvpn.example.com
-;; global options: +cmd
-;; Got answer:
-;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 44054
-;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
-
-;; OPT PSEUDOSECTION:
-; EDNS: version: 0, flags:; udp: 65494
-;; QUESTION SECTION:
-;grafana.myvpn.example.com.         IN      A
-
-;; ANSWER SECTION:
-grafana.myvpn.example.com.  593     IN      A       100.64.0.3
-
-;; Query time: 0 msec
-;; SERVER: 127.0.0.53#53(127.0.0.53) (UDP)
-;; WHEN: Sat Dec 31 11:46:55 CET 2022
-;; MSG SIZE  rcvd: 66
-```
-
-### 3. Optional: Setup the reverse proxy
-
-The motivating example here was to be able to access internal monitoring services on the same host without specifying a port:
-
-```
-server {
-    listen 80;
-    listen [::]:80;
-
-    server_name grafana.myvpn.example.com;
-
-    location / {
-        proxy_pass http://localhost:3000;
-        proxy_set_header Host $http_host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-
-}
-```
-
-## Limitations
-
-[Not all types of records are supported](https://github.com/tailscale/tailscale/blob/6edf357b96b28ee1be659a70232c0135b2ffedfd/ipn/ipnlocal/local.go#L2989-L3007), especially no CNAME records.

docs/exit-node.md

@@ -1,49 +0,0 @@
-# Exit Nodes
-
-## On the node
-
-Register the node and make it advertise itself as an exit node:
-
-```console
-$ sudo tailscale up --login-server https://my-server.com --advertise-exit-node
-```
-
-If the node is already registered, it can advertise exit capabilities like this:
-
-```console
-$ sudo tailscale set --advertise-exit-node
-```
-
-To use a node as an exit node, IP forwarding must be enabled on the node. Check the official [Tailscale documentation](https://tailscale.com/kb/1019/subnets/?tab=linux#enable-ip-forwarding) for how to enable IP fowarding.
-
-## On the control server
-
-```console
-$ # list nodes
-$ headscale routes list
-ID | Machine | Prefix    | Advertised | Enabled | Primary
-1  |         | 0.0.0.0/0 | false      | false   | -
-2  |         | ::/0      | false      | false   | -
-3  | phobos  | 0.0.0.0/0 | true       | false   | -
-4  | phobos  | ::/0      | true       | false   | -
-$ # enable routes for phobos
-$ headscale routes enable -r 3
-$ headscale routes enable -r 4
-$ # Check node list again. The routes are now enabled.
-$ headscale routes list
-ID | Machine | Prefix    | Advertised | Enabled | Primary
-1  |         | 0.0.0.0/0 | false      | false   | -
-2  |         | ::/0      | false      | false   | -
-3  | phobos  | 0.0.0.0/0 | true       | true    | -
-4  | phobos  | ::/0      | true       | true    | -
-```
-
-## On the client
-
-The exit node can now be used with:
-
-```console
-$ sudo tailscale set --exit-node phobos
-```
-
-Check the official [Tailscale documentation](https://tailscale.com/kb/1103/exit-nodes/?q=exit#step-3-use-the-exit-node) for how to do it on your device.

docs/faq.md

@@ -1,57 +0,0 @@
----
-hide:
-  - navigation
----
-
-# Frequently Asked Questions
-
-## What is the design goal of headscale?
-
-`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_ Tailnet, suitable for a personal use, or a small
-open-source organisation.
-
-## How can I contribute?
-
-Headscale is "Open Source, acknowledged contribution", this means that any
-contribution will have to be discussed with the Maintainers before being submitted.
-
-Headscale is open to code contributions for bug fixes without discussion.
-
-If you find mistakes in the documentation, please also submit a fix to the documentation.
-
-## Why is 'acknowledged contribution' the chosen model?
-
-Both maintainers have full-time jobs and families, and we want to avoid burnout. We also want to avoid frustration from contributors when their PRs are not accepted.
-
-We are more than happy to exchange emails, or to have dedicated calls before a PR is submitted.
-
-## When/Why is Feature X going to be implemented?
-
-We don't know. We might be working on it. If you want to help, please send us a PR.
-
-Please be aware that there are a number of reasons why we might not accept specific contributions:
-
-- It is not possible to implement the feature in a way that makes sense in a self-hosted environment.
-- Given that we are reverse-engineering Tailscale to satify our own curiosity, we might be interested in implementing the feature ourselves.
-- You are not sending unit and integration tests with it.
-
-## Do you support Y method of deploying Headscale?
-
-We currently support deploying `headscale` using our binaries and the DEB packages. Both can be found in the
-[GitHub releases page](https://github.com/juanfont/headscale/releases).
-
-In addition to that, there are semi-official RPM packages by the Fedora infra team https://copr.fedorainfracloud.org/coprs/jonathanspw/headscale/
-
-For convenience, we also build Docker images with `headscale`. But **please be aware that we don't officially support deploying `headscale` using Docker**. We have a [Discord channel](https://discord.com/channels/896711691637780480/1070619770942148618) where you can ask for Docker-specific help to the community.
-
-## Why is my reverse proxy not working with Headscale?
-
-We don't know. We don't use reverse proxies with `headscale` ourselves, so we don't have any experience with them. We have [community documentation](https://headscale.net/reverse-proxy/) on how to configure various reverse proxies, and a dedicated [Discord channel](https://discord.com/channels/896711691637780480/1070619818346164324) where you can ask for help to the community.
-
-## Can I use headscale and tailscale on the same machine?
-
-Running headscale on a machine that is also in the tailnet can cause problems with subnet routers, traffic relay nodes, and MagicDNS. It might work, but it is not supported.

docs/glossary.md

@@ -1,6 +0,0 @@
-# Glossary
-
-| Term      | Description                                                                                                                                 |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| Machine   | A machine is a single entity connected to `headscale`, typically an installation of Tailscale. Also known as **Node**                       |
-| Namespace | A namespace was a logical grouping of machines "owned" by the same entity, in Tailscale, this is typically a User (This is now called user) |

docs/iOS-client.md

@@ -1,30 +0,0 @@
-# Connecting an iOS client
-
-## Goal
-
-This documentation has the goal of showing how a user can use the official iOS [Tailscale](https://tailscale.com) client with `headscale`.
-
-## Installation
-
-Install the official Tailscale iOS client from the [App Store](https://apps.apple.com/app/tailscale/id1470499037).
-
-Ensure that the installed version is at least 1.38.1, as that is the first release to support alternate control servers.
-
-## Configuring the headscale URL
-
-!!! info "Apple devices"
-
-    An endpoint with information on how to connect your Apple devices
-    (currently macOS only) is available at `/apple` on your running instance.
-
-Ensure that the tailscale app is logged out before proceeding.
-
-Go to iOS settings, scroll down past game center and tv provider to the tailscale app and select it. The headscale URL can be entered into the _"ALTERNATE COORDINATION SERVER URL"_ box.
-
-> **Note**
->
-> If the app was previously logged into tailscale, toggle on the _Reset Keychain_ switch.
-
-Restart the app by closing it from the iOS app switcher, open the app and select the regular _Sign in_ option (non-SSO), and it should open up to the headscale authentication page.
-
-Enter your credentials and log in. Headscale should now be working on your iOS device.

docs/index.md

@@ -4,40 +4,34 @@ hide:
   - toc
 ---
 
-# headscale
+# Welcome to headscale
 
-`headscale` is an open source, self-hosted implementation of the Tailscale control server.
+Headscale is an open source, self-hosted implementation of the Tailscale control server.
 
-This page contains the documentation for the latest version of headscale. Please also check our [FAQ](/faq/).
+This page contains the documentation for the latest version of headscale. Please also check our [FAQ](./about/faq.md).
 
-Join our [Discord](https://discord.gg/c84AZQhmpx) server for a chat and community support.
+Join our [Discord server](https://discord.gg/c84AZQhmpx) for a chat and community support.
 
 ## Design goal
 
-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 narrower scope, a single Tailnet, suitable for a personal use, or a small
-open-source organisation.
+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.
 
 ## Supporting headscale
 
-If you like `headscale` and find it useful, there is a sponsorship and donation
-buttons available in the repo.
+Please see [Sponsor](about/sponsor.md) for more information.
 
 ## Contributing
 
 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 see [Contributing](about/contributing.md) for more information.
 
 ## About
 
-`headscale` is maintained by [Kristoffer Dalby](https://kradalby.no/) and [Juan Font](https://font.eu).
+Headscale is maintained by [Kristoffer Dalby](https://kradalby.no/) and [Juan Font](https://font.eu).

docs/packaging/headscale.systemd.service

@@ -9,6 +9,7 @@ Type=simple
 User=headscale
 Group=headscale
 ExecStart=/usr/bin/headscale serve
+ExecReload=/usr/bin/kill -HUP $MAINPID
 Restart=always
 RestartSec=5
 

docs/packaging/postinstall.sh

@@ -6,8 +6,10 @@
 HEADSCALE_EXE="/usr/bin/headscale"
 BSD_HIER=""
 HEADSCALE_RUN_DIR="/var/run/headscale"
+HEADSCALE_HOME_DIR="/var/lib/headscale"
 HEADSCALE_USER="headscale"
 HEADSCALE_GROUP="headscale"
+HEADSCALE_SHELL="/usr/sbin/nologin"
 
 ensure_sudo() {
 	if [ "$(id -u)" = "0" ]; then
@@ -29,13 +31,13 @@ ensure_headscale_path() {
 
 create_headscale_user() {
 	printf "PostInstall: Adding headscale user %s\n" "$HEADSCALE_USER"
-	useradd -s /bin/sh -c "headscale default user" headscale
+	useradd -r -s "$HEADSCALE_SHELL" -d "$HEADSCALE_HOME_DIR" -c "headscale default user" "$HEADSCALE_USER"
 }
 
 create_headscale_group() {
 	if command -V systemctl >/dev/null 2>&1; then
 		printf "PostInstall: Adding headscale group %s\n" "$HEADSCALE_GROUP"
-		groupadd "$HEADSCALE_GROUP"
+		groupadd -r "$HEADSCALE_GROUP"
 
 		printf "PostInstall: Adding headscale user %s to group %s\n" "$HEADSCALE_USER" "$HEADSCALE_GROUP"
 		usermod -a -G "$HEADSCALE_GROUP" "$HEADSCALE_USER"
@@ -43,7 +45,7 @@ create_headscale_group() {
 
 	if [ "$ID" = "alpine" ]; then
 		printf "PostInstall: Adding headscale group %s\n" "$HEADSCALE_GROUP"
-		addgroup "$HEADSCALE_GROUP"
+		addgroup -S "$HEADSCALE_GROUP"
 
 		printf "PostInstall: Adding headscale user %s to group %s\n" "$HEADSCALE_USER" "$HEADSCALE_GROUP"
 		addgroup "$HEADSCALE_USER" "$HEADSCALE_GROUP"

docs/proposals/001-acls.md

@@ -1,362 +0,0 @@
-# ACLs
-
-A key component of tailscale is the notion of Tailnet. This notion is hidden
-but the implications that it have on how to use tailscale are not.
-
-For tailscale an [tailnet](https://tailscale.com/kb/1136/tailnet/) is the
-following:
-
-> For personal users, you are a tailnet of many devices and one person. Each
-> device gets a private Tailscale IP address in the CGNAT range and every
-> device can talk directly to every other device, wherever they are on the
-> internet.
->
-> For businesses and organizations, a tailnet is many devices and many users.
-> It can be based on your Microsoft Active Directory, your Google Workspace, a
-> GitHub organization, Okta tenancy, or other identity provider namespace. All
-> of the devices and users in your tailnet can be seen by the tailnet
-> administrators in the Tailscale admin console. There you can apply
-> tailnet-wide configuration, such as ACLs that affect visibility of devices
-> inside your tailnet, DNS settings, and more.
-
-## Current implementation and issues
-
-Currently in headscale, the namespaces are used both as tailnet and users. The
-issue is that if we want to use the ACL's we can't use both at the same time.
-
-Tailnet's cannot communicate with each others. So we can't have an ACL that
-authorize tailnet (namespace) A to talk to tailnet (namespace) B.
-
-We also can't write ACLs based on the users (namespaces in headscale) since all
-devices belong to the same user.
-
-With the current implementation the only ACL that we can user is to associate
-each headscale IP to a host manually then write the ACLs according to this
-manual mapping.
-
-```json
-{
-  "hosts": {
-    "host1": "100.64.0.1",
-    "server": "100.64.0.2"
-  },
-  "acls": [
-    { "action": "accept", "users": ["host1"], "ports": ["host2:80,443"] }
-  ]
-}
-```
-
-While this works, it requires a lot of manual editing on the configuration and
-to keep track of all devices IP address.
-
-## Proposition for a next implementation
-
-In order to ease the use of ACL's we need to split the tailnet and users
-notion.
-
-A solution could be to consider a headscale server (in it's entirety) as a
-tailnet.
-
-For personal users the default behavior could either allow all communications
-between all namespaces (like tailscale) or dissallow all communications between
-namespaces (current behavior).
-
-For businesses and organisations, viewing a headscale instance a single tailnet
-would allow users (namespace) to talk to each other with the ACLs. As described
-in tailscale's documentation [[1]], a server should be tagged and personnal
-devices should be tied to a user. Translated in headscale's terms each user can
-have multiple devices and all those devices should be in the same namespace.
-The servers should be tagged and used as such.
-
-This implementation would render useless the sharing feature that is currently
-implemented since an ACL could do the same. Simplifying to only one user
-interface to do one thing is easier and less confusing for the users.
-
-To better suit the ACLs in this proposition, it's advised to consider that each
-namespaces belong to one person. This person can have multiple devices, they
-will all be considered as the same user in the ACLs. OIDC feature wouldn't need
-to map people to namespace, just create a namespace if the person isn't
-registered yet.
-
-As a sidenote, users would like to write ACLs as YAML. We should offer users
-the ability to rules in either format (HuJSON or YAML).
-
-[1]: https://tailscale.com/kb/1068/acl-tags/
-
-## Example
-
-Let's build an example use case for a small business (It may be the place where
-ACL's are the most useful).
-
-We have a small company with a boss, an admin, two developper and an intern.
-
-The boss should have access to all servers but not to the users hosts. Admin
-should also have access to all hosts except that their permissions should be
-limited to maintaining the hosts (for example purposes). The developers can do
-anything they want on dev hosts, but only watch on productions hosts. Intern
-can only interact with the development servers.
-
-Each user have at least a device connected to the network and we have some
-servers.
-
-- database.prod
-- database.dev
-- app-server1.prod
-- app-server1.dev
-- billing.internal
-
-### Current headscale implementation
-
-Let's create some namespaces
-
-```bash
-headscale namespaces create prod
-headscale namespaces create dev
-headscale namespaces create internal
-headscale namespaces create users
-
-headscale nodes register -n users boss-computer
-headscale nodes register -n users admin1-computer
-headscale nodes register -n users dev1-computer
-headscale nodes register -n users dev1-phone
-headscale nodes register -n users dev2-computer
-headscale nodes register -n users intern1-computer
-
-headscale nodes register -n prod database
-headscale nodes register -n prod app-server1
-
-headscale nodes register -n dev database
-headscale nodes register -n dev app-server1
-
-headscale nodes register -n internal billing
-
-headscale nodes list
-ID  | Name              | Namespace | IP address
-1   | boss-computer     | users     | 100.64.0.1
-2   | admin1-computer   | users     | 100.64.0.2
-3   | dev1-computer     | users     | 100.64.0.3
-4   | dev1-phone        | users     | 100.64.0.4
-5   | dev2-computer     | users     | 100.64.0.5
-6   | intern1-computer  | users     | 100.64.0.6
-7   | database          | prod      | 100.64.0.7
-8   | app-server1       | prod      | 100.64.0.8
-9   | database          | dev       | 100.64.0.9
-10  | app-server1       | dev       | 100.64.0.10
-11  | internal          | internal  | 100.64.0.11
-```
-
-In order to only allow the communications related to our description above we
-need to add the following ACLs
-
-```json
-{
-  "hosts": {
-    "boss-computer": "100.64.0.1",
-    "admin1-computer": "100.64.0.2",
-    "dev1-computer": "100.64.0.3",
-    "dev1-phone": "100.64.0.4",
-    "dev2-computer": "100.64.0.5",
-    "intern1-computer": "100.64.0.6",
-    "prod-app-server1": "100.64.0.8"
-  },
-  "groups": {
-    "group:dev": ["dev1-computer", "dev1-phone", "dev2-computer"],
-    "group:admin": ["admin1-computer"],
-    "group:boss": ["boss-computer"],
-    "group:intern": ["intern1-computer"]
-  },
-  "acls": [
-    // boss have access to all servers but no users hosts
-    {
-      "action": "accept",
-      "users": ["group:boss"],
-      "ports": ["prod:*", "dev:*", "internal:*"]
-    },
-
-    // admin have access to adminstration port (lets only consider port 22 here)
-    {
-      "action": "accept",
-      "users": ["group:admin"],
-      "ports": ["prod:22", "dev:22", "internal:22"]
-    },
-
-    // dev can do anything on dev servers and check access on prod servers
-    {
-      "action": "accept",
-      "users": ["group:dev"],
-      "ports": ["dev:*", "prod-app-server1:80,443"]
-    },
-
-    // interns only have access to port 80 and 443 on dev servers (lame internship)
-    { "action": "accept", "users": ["group:intern"], "ports": ["dev:80,443"] },
-
-    // users can access their own devices
-    {
-      "action": "accept",
-      "users": ["dev1-computer"],
-      "ports": ["dev1-phone:*"]
-    },
-    {
-      "action": "accept",
-      "users": ["dev1-phone"],
-      "ports": ["dev1-computer:*"]
-    },
-
-    // internal namespace communications should still be allowed within the namespace
-    { "action": "accept", "users": ["dev"], "ports": ["dev:*"] },
-    { "action": "accept", "users": ["prod"], "ports": ["prod:*"] },
-    { "action": "accept", "users": ["internal"], "ports": ["internal:*"] }
-  ]
-}
-```
-
-Since communications between namespace isn't possible we also have to share the
-devices between the namespaces.
-
-```bash
-
-// add boss host to prod, dev and internal network
-headscale nodes share -i 1 -n prod
-headscale nodes share -i 1 -n dev
-headscale nodes share -i 1 -n internal
-
-// add admin computer to prod, dev and internal network
-headscale nodes share -i 2 -n prod
-headscale nodes share -i 2 -n dev
-headscale nodes share -i 2 -n internal
-
-// add all dev to prod and dev network
-headscale nodes share -i 3 -n dev
-headscale nodes share -i 4 -n dev
-headscale nodes share -i 3 -n prod
-headscale nodes share -i 4 -n prod
-headscale nodes share -i 5 -n dev
-headscale nodes share -i 5 -n prod
-
-headscale nodes share -i 6 -n dev
-```
-
-This fake network have not been tested but it should work. Operating it could
-be quite tedious if the company grows. Each time a new user join we have to add
-it to a group, and share it to the correct namespaces. If the user want
-multiple devices we have to allow communication to each of them one by one. If
-business conduct a change in the organisations we may have to rewrite all acls
-and reorganise all namespaces.
-
-If we add servers in production we should also update the ACLs to allow dev
-access to certain category of them (only app servers for example).
-
-### example based on the proposition in this document
-
-Let's create the namespaces
-
-```bash
-headscale namespaces create boss
-headscale namespaces create admin1
-headscale namespaces create dev1
-headscale namespaces create dev2
-headscale namespaces create intern1
-```
-
-We don't need to create namespaces for the servers because the servers will be
-tagged. When registering the servers we will need to add the flag
-`--advertised-tags=tag:<tag1>,tag:<tag2>`, and the user (namespace) that is
-registering the server should be allowed to do it. Since anyone can add tags to
-a server they can register, the check of the tags is done on headscale server
-and only valid tags are applied. A tag is valid if the namespace that is
-registering it is allowed to do it.
-
-Here are the ACL's to implement the same permissions as above:
-
-```json
-{
-  // groups are simpler and only list the namespaces name
-  "groups": {
-    "group:boss": ["boss"],
-    "group:dev": ["dev1", "dev2"],
-    "group:admin": ["admin1"],
-    "group:intern": ["intern1"]
-  },
-  "tagOwners": {
-    // the administrators can add servers in production
-    "tag:prod-databases": ["group:admin"],
-    "tag:prod-app-servers": ["group:admin"],
-
-    // the boss can tag any server as internal
-    "tag:internal": ["group:boss"],
-
-    // dev can add servers for dev purposes as well as admins
-    "tag:dev-databases": ["group:admin", "group:dev"],
-    "tag:dev-app-servers": ["group:admin", "group:dev"]
-
-    // interns cannot add servers
-  },
-  "acls": [
-    // boss have access to all servers
-    {
-      "action": "accept",
-      "users": ["group:boss"],
-      "ports": [
-        "tag:prod-databases:*",
-        "tag:prod-app-servers:*",
-        "tag:internal:*",
-        "tag:dev-databases:*",
-        "tag:dev-app-servers:*"
-      ]
-    },
-
-    // admin have only access to administrative ports of the servers
-    {
-      "action": "accept",
-      "users": ["group:admin"],
-      "ports": [
-        "tag:prod-databases:22",
-        "tag:prod-app-servers:22",
-        "tag:internal:22",
-        "tag:dev-databases:22",
-        "tag:dev-app-servers:22"
-      ]
-    },
-
-    {
-      "action": "accept",
-      "users": ["group:dev"],
-      "ports": [
-        "tag:dev-databases:*",
-        "tag:dev-app-servers:*",
-        "tag:prod-app-servers:80,443"
-      ]
-    },
-
-    // servers should be able to talk to database. Database should not be able to initiate connections to server
-    {
-      "action": "accept",
-      "users": ["tag:dev-app-servers"],
-      "ports": ["tag:dev-databases:5432"]
-    },
-    {
-      "action": "accept",
-      "users": ["tag:prod-app-servers"],
-      "ports": ["tag:prod-databases:5432"]
-    },
-
-    // interns have access to dev-app-servers only in reading mode
-    {
-      "action": "accept",
-      "users": ["group:intern"],
-      "ports": ["tag:dev-app-servers:80,443"]
-    },
-
-    // we still have to allow internal namespaces communications since nothing guarantees that each user have their own namespaces. This could be talked over.
-    { "action": "accept", "users": ["boss"], "ports": ["boss:*"] },
-    { "action": "accept", "users": ["dev1"], "ports": ["dev1:*"] },
-    { "action": "accept", "users": ["dev2"], "ports": ["dev2:*"] },
-    { "action": "accept", "users": ["admin1"], "ports": ["admin1:*"] },
-    { "action": "accept", "users": ["intern1"], "ports": ["intern1:*"] }
-  ]
-}
-```
-
-With this implementation, the sharing step is not necessary. Maintenance cost
-of the ACL file is lower and less tedious (no need to map hostname and IP's
-into it).

docs/proposals/002-better-routing.md

@@ -1,48 +0,0 @@
-# Better route management
-
-As of today, route management in Headscale is very basic and does not allow for much flexibility, including implementing subnet HA, 4via6 or more advanced features. We also have a number of bugs (e.g., routes exposed by ephemeral nodes)
-
-This proposal aims to improve the route management.
-
-## Current situation
-
-Routes advertised by the nodes are read from the Hostinfo struct. If approved from the the CLI or via autoApprovers, the route is added to the EnabledRoutes field in `Machine`.
-
-This means that the advertised routes are not persisted in the database, as Hostinfo is always replaced. In the same way, EnabledRoutes can get out of sync with the actual routes in the node.
-
-In case of colliding routes (i.e., subnets that are exposed from multiple nodes), we are currently just sending all of them in `PrimaryRoutes`... and hope for the best. (`PrimaryRoutes` is the field in `Node` used for subnet failover).
-
-## Proposal
-
-The core part is to create a new `Route` struct (and DB table), with the following fields:
-
-```go
-type Route struct {
-	ID          uint64 `gorm:"primary_key"`
-
-    Machine     *Machine
-    Prefix      IPPrefix
-
-    Advertised  bool
-    Enabled     bool
-    IsPrimary   bool
-
-
-    CreatedAt   *time.Time
-    UpdatedAt   *time.Time
-    DeletedAt   *time.Time
-}
-```
-
-- The `Advertised` field is set to true if the route is being advertised by the node. It is set to false if the route is removed. This way we can indicate if a later enabled route has stopped being advertised. A similar behaviour happens in the Tailscale.com control panel.
-
-- The `Enabled` field is set to true if the route is enabled - via CLI or autoApprovers.
-
-- `IsPrimary` indicates if Headscale has selected this route as the primary route for that particular subnet. This allows us to implement subnet failover. This would be fully automatic if there is more than subnet routers advertising the same network - which is the behaviour of Tailscale.com.
-
-## Stuff to bear in mind
-
-- We need to make sure to migrate the current `EnabledRoutes` of `Machine` into the new table.
-- When a node stops sharing a subnet, I reckon we should mark it both as not `Advertised` and not `Enabled`. Users should re-enable it if the node advertises it again.
-- If only one subnet router is advertising a subnet, we should mark it as primary.
-- Regarding subnet failover, the current behaviour of Tailscale.com is to perform the failover after 15 seconds from the node disconnecting from their control panel. I reckon we cannot do the same currently. Our maximum granularity is the keep alive period.

docs/ref/acls.md

@@ -3,7 +3,7 @@ Headscale implements the same policy ACLs as Tailscale.com, adapted to the self-
 For instance, instead of referring to users when defining groups you must
 use users (which are the equivalent to user/logins in Tailscale.com).
 
-Please check https://tailscale.com/kb/1018/acls/, and `./tests/acls/` in this repo for working examples.
+Please check https://tailscale.com/kb/1018/acls/ for further information.
 
 When using ACL's the User borders are no longer applied. All machines
 whichever the User have the ability to communicate with other hosts as
@@ -36,36 +36,38 @@ servers.
 - billing.internal
 - router.internal
 
-![ACL implementation example](images/headscale-acl-network.png)
+![ACL implementation example](../images/headscale-acl-network.png)
 
 ## ACL setup
 
-Note: Users will be created automatically when users authenticate with the
-Headscale server.
+ACLs have to be written in [huJSON](https://github.com/tailscale/hujson).
 
-ACLs could be written either on [huJSON](https://github.com/tailscale/hujson)
-or YAML. Check the [test ACLs](../tests/acls) for further information.
-
-When registering the servers we will need to add the flag
-`--advertise-tags=tag:<tag1>,tag:<tag2>`, and the user that is
-registering the server should be allowed to do it. Since anyone can add tags to
-a server they can register, the check of the tags is done on headscale server
-and only valid tags are applied. A tag is valid if the user that is
+When [registering the servers](../usage/getting-started.md#register-a-node) we
+will need to add the flag `--advertise-tags=tag:<tag1>,tag:<tag2>`, and the user
+that is registering the server should be allowed to do it. Since anyone can add
+tags to a server they can register, the check of the tags is done on headscale
+server and only valid tags are applied. A tag is valid if the user that is
 registering it is allowed to do it.
 
-To use ACLs in headscale, you must edit your config.yaml file. In there you will find a `acl_policy_path: ""` parameter. This will need to point to your ACL file. More info on how these policies are written can be found [here](https://tailscale.com/kb/1018/acls/).
+To use ACLs in headscale, you must edit your `config.yaml` file. In there you will find a `policy.path` parameter. This
+will need to point to your ACL file. More info on how these policies are written can be found
+[here](https://tailscale.com/kb/1018/acls/).
+
+Please reload or restart Headscale after updating the ACL file. Headscale may be reloaded either via its systemd service
+(`sudo systemctl reload headscale`) or by sending a SIGHUP signal (`sudo kill -HUP $(pidof headscale)`) to the main
+process. Headscale logs the result of ACL policy processing after each reload.
 
 Here are the ACL's to implement the same permissions as above:
 
-```json
+```json title="acl.json"
 {
   // groups are collections of users having a common scope. A user can be in multiple groups
   // groups cannot be composed of groups
   "groups": {
-    "group:boss": ["boss"],
-    "group:dev": ["dev1", "dev2"],
-    "group:admin": ["admin1"],
-    "group:intern": ["intern1"]
+    "group:boss": ["boss@"],
+    "group:dev": ["dev1@", "dev2@"],
+    "group:admin": ["admin1@"],
+    "group:intern": ["intern1@"]
   },
   // tagOwners in tailscale is an association between a TAG and the people allowed to set this TAG on a server.
   // This is documented [here](https://tailscale.com/kb/1068/acl-tags#defining-a-tag)
@@ -88,7 +90,7 @@ Here are the ACL's to implement the same permissions as above:
   // to define a single host, use a /32 mask. You cannot use DNS entries here,
   // as they're prone to be hijacked by replacing their IP addresses.
   // see https://github.com/tailscale/tailscale/issues/3800 for more information.
-  "Hosts": {
+  "hosts": {
     "postgresql.internal": "10.20.0.2/32",
     "webservers.internal": "10.20.10.1/29"
   },
@@ -147,13 +149,11 @@ Here are the ACL's to implement the same permissions as above:
     },
     // developers have access to the internal network through the router.
     // the internal network is composed of HTTPS endpoints and Postgresql
-    // database servers. There's an additional rule to allow traffic to be
-    // forwarded to the internal subnet, 10.20.0.0/16. See this issue
-    // https://github.com/juanfont/headscale/issues/502
+    // database servers.
     {
       "action": "accept",
       "src": ["group:dev"],
-      "dst": ["10.20.0.0/16:443,5432", "router.internal:0"]
+      "dst": ["10.20.0.0/16:443,5432"]
     },
 
     // servers should be able to talk to database in tcp/5432. Database should not be able to initiate connections to
@@ -179,11 +179,11 @@ Here are the ACL's to implement the same permissions as above:
 
     // We still have to allow internal users communications since nothing guarantees that each user have
     // their own users.
-    { "action": "accept", "src": ["boss"], "dst": ["boss:*"] },
-    { "action": "accept", "src": ["dev1"], "dst": ["dev1:*"] },
-    { "action": "accept", "src": ["dev2"], "dst": ["dev2:*"] },
-    { "action": "accept", "src": ["admin1"], "dst": ["admin1:*"] },
-    { "action": "accept", "src": ["intern1"], "dst": ["intern1:*"] }
+    { "action": "accept", "src": ["boss@"], "dst": ["boss@:*"] },
+    { "action": "accept", "src": ["dev1@"], "dst": ["dev1@:*"] },
+    { "action": "accept", "src": ["dev2@"], "dst": ["dev2@:*"] },
+    { "action": "accept", "src": ["admin1@"], "dst": ["admin1@:*"] },
+    { "action": "accept", "src": ["intern1@"], "dst": ["intern1@:*"] }
   ]
 }
 ```

docs/ref/configuration.md

@@ -0,0 +1,39 @@
+# Configuration
+
+- Headscale loads its configuration from a YAML file
+- It searches for `config.yaml` in the following paths:
+    - `/etc/headscale`
+    - `$HOME/.headscale`
+    - the current working directory
+- Use the command line flag `-c`, `--config` to load the configuration from a different path
+- Validate the configuration file with: `headscale configtest`
+
+!!! example "Get the [example configuration from the GitHub repository](https://github.com/juanfont/headscale/blob/main/config-example.yaml)"
+
+    Always select the [same GitHub tag](https://github.com/juanfont/headscale/tags) as the released version you use to
+    ensure you have the correct example configuration. The `main` branch might contain unreleased changes.
+
+    === "View on GitHub"
+
+        * Development version: <https://github.com/juanfont/headscale/blob/main/config-example.yaml>
+        * Version {{ headscale.version }}: <https://github.com/juanfont/headscale/blob/v{{ headscale.version }}/config-example.yaml>
+
+    === "Download with `wget`"
+
+        ```shell
+        # Development version
+        wget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml
+
+        # Version {{ headscale.version }}
+        wget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/v{{ headscale.version }}/config-example.yaml
+        ```
+
+    === "Download with `curl`"
+
+        ```shell
+        # Development version
+        curl -o config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml
+
+        # Version {{ headscale.version }}
+        curl -o config.yaml https://raw.githubusercontent.com/juanfont/headscale/v{{ headscale.version }}/config-example.yaml
+        ```

docs/ref/dns.md

@@ -0,0 +1,112 @@
+# DNS
+
+Headscale supports [most DNS features](../about/features.md) from Tailscale. DNS related settings can be configured
+within `dns` section of the [configuration file](./configuration.md).
+
+## Setting extra DNS records
+
+Headscale allows to set extra DNS records which are made available via
+[MagicDNS](https://tailscale.com/kb/1081/magicdns). Extra DNS records can be configured either via static entries in the
+[configuration file](./configuration.md) or from a JSON file that Headscale continuously watches for changes:
+
+* Use the `dns.extra_records` option in the [configuration file](./configuration.md) for entries that are static and
+  don't change while Headscale is running. Those entries are processed when Headscale is starting up and changes to the
+  configuration require a restart of Headscale.
+* For dynamic DNS records that may be added, updated or removed while Headscale is running or DNS records that are
+  generated by scripts the option `dns.extra_records_path` in the [configuration file](./configuration.md) is useful.
+  Set it to the absolute path of the JSON file containing DNS records and Headscale processes this file as it detects
+  changes.
+
+An example use case is to serve multiple apps on the same host via a reverse proxy like NGINX, in this case a Prometheus
+monitoring stack. This allows to nicely access the service with "http://grafana.myvpn.example.com" instead of the
+hostname and port combination "http://hostname-in-magic-dns.myvpn.example.com:3000".
+
+!!! warning "Limitations"
+
+    Currently, [only A and AAAA records are processed by Tailscale](https://github.com/tailscale/tailscale/blob/v1.78.3/ipn/ipnlocal/local.go#L4461-L4479).
+
+
+1.  Configure extra DNS records using one of the available configuration options:
+
+    === "Static entries, via `dns.extra_records`"
+
+        ```yaml title="config.yaml"
+        dns:
+          ...
+          extra_records:
+            - name: "grafana.myvpn.example.com"
+              type: "A"
+              value: "100.64.0.3"
+
+            - name: "prometheus.myvpn.example.com"
+              type: "A"
+              value: "100.64.0.3"
+          ...
+        ```
+
+        Restart your headscale instance.
+
+    === "Dynamic entries, via `dns.extra_records_path`"
+
+        ```json title="extra-records.json"
+        [
+          {
+            "name": "grafana.myvpn.example.com",
+            "type": "A",
+            "value": "100.64.0.3"
+          },
+          {
+            "name": "prometheus.myvpn.example.com",
+            "type": "A",
+            "value": "100.64.0.3"
+          }
+        ]
+        ```
+
+        Headscale picks up changes to the above JSON file automatically.
+
+        !!! tip "Good to know"
+
+            * The `dns.extra_records_path` option in the [configuration file](./configuration.md) needs to reference the
+              JSON file containing extra DNS records.
+            * Be sure to "sort keys" and produce a stable output in case you generate the JSON file with a script.
+              Headscale uses a checksum to detect changes to the file and a stable output avoids unnecessary processing.
+
+1.  Verify that DNS records are properly set using the DNS querying tool of your choice:
+
+    === "Query with dig"
+
+        ```console
+        dig +short grafana.myvpn.example.com
+        100.64.0.3
+        ```
+
+    === "Query with drill"
+
+        ```console
+        drill -Q grafana.myvpn.example.com
+        100.64.0.3
+        ```
+
+1.  Optional: Setup the reverse proxy
+
+    The motivating example here was to be able to access internal monitoring services on the same host without
+    specifying a port, depicted as NGINX configuration snippet:
+
+    ```nginx title="nginx.conf"
+    server {
+        listen 80;
+        listen [::]:80;
+
+        server_name grafana.myvpn.example.com;
+
+        location / {
+            proxy_pass http://localhost:3000;
+            proxy_set_header Host $http_host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }
+
+    }
+    ```

docs/ref/integration/reverse-proxy.md

@@ -3,7 +3,7 @@
 !!! warning "Community documentation"
 
     This page is not actively maintained by the headscale authors and is
-    written by community members. It is _not_ verified by `headscale` developers.
+    written by community members. It is _not_ verified by headscale developers.
 
     **It might be outdated and it might miss necessary steps**.
 
@@ -11,15 +11,19 @@ Running headscale behind a reverse proxy is useful when running multiple applica
 
 ### WebSockets
 
-The reverse proxy MUST be configured to support WebSockets, as it is needed for clients running Tailscale v1.30+.
+The reverse proxy MUST be configured to support WebSockets to communicate with Tailscale clients.
 
-WebSockets support is required when using the headscale embedded DERP server. In this case, you will also need to expose the UDP port used for STUN (by default, udp/3478). Please check our [config-example.yaml](https://github.com/juanfont/headscale/blob/main/config-example.yaml).
+WebSockets support is also required when using the headscale embedded DERP server. In this case, you will also need to expose the UDP port used for STUN (by default, udp/3478). Please check our [config-example.yaml](https://github.com/juanfont/headscale/blob/main/config-example.yaml).
+
+### Cloudflare
+
+Running headscale behind a cloudflare proxy or cloudflare tunnel is not supported and will not work as Cloudflare does not support WebSocket POSTs as required by the Tailscale protocol. See [this issue](https://github.com/juanfont/headscale/issues/1468)
 
 ### TLS
 
 Headscale can be configured not to use TLS, leaving it to the reverse proxy to handle. Add the following configuration values to your headscale config file.
 
-```yaml
+```yaml title="config.yaml"
 server_url: https://<YOUR_SERVER_NAME> # This should be the FQDN at which headscale will be served
 listen_addr: 0.0.0.0:8080
 metrics_listen_addr: 0.0.0.0:9090
@@ -31,7 +35,7 @@ tls_key_path: ""
 
 The following example configuration can be used in your nginx setup, substituting values as necessary. `<IP:PORT>` should be the IP address and port where headscale is running. In most cases, this will be `http://localhost:8080`.
 
-```Nginx
+```nginx title="nginx.conf"
 map $http_upgrade $connection_upgrade {
     default      upgrade;
     ''           close;
@@ -76,7 +80,7 @@ Sending local reply with details upgrade_failed
 
 ### Envoy
 
-You need add a new upgrade_type named `tailscale-control-protocol`. [see detail](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-upgradeconfig)
+You need to add a new upgrade_type named `tailscale-control-protocol`. [see details](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto#extensions-filters-network-http-connection-manager-v3-httpconnectionmanager-upgradeconfig)
 
 ### Istio
 
@@ -109,21 +113,21 @@ spec:
 
 The following Caddyfile is all that is necessary to use Caddy as a reverse proxy for headscale, in combination with the `config.yaml` specifications above to disable headscale's built in TLS. Replace values as necessary - `<YOUR_SERVER_NAME>` should be the FQDN at which headscale will be served, and `<IP:PORT>` should be the IP address and port where headscale is running. In most cases, this will be `localhost:8080`.
 
-```
+```none title="Caddyfile"
 <YOUR_SERVER_NAME> {
     reverse_proxy <IP:PORT>
 }
 ```
 
-Caddy v2 will [automatically](https://caddyserver.com/docs/automatic-https) provision a certficate for your domain/subdomain, force HTTPS, and proxy websockets - no further configuration is necessary.
+Caddy v2 will [automatically](https://caddyserver.com/docs/automatic-https) provision a certificate for your domain/subdomain, force HTTPS, and proxy websockets - no further configuration is necessary.
 
-For a slightly more complex configuration which utilizes Docker containers to manage Caddy, Headscale, and Headscale-UI, [Guru Computing's guide](https://blog.gurucomputing.com.au/smart-vpns-with-headscale/) is an excellent reference.
+For a slightly more complex configuration which utilizes Docker containers to manage Caddy, headscale, and Headscale-UI, [Guru Computing's guide](https://blog.gurucomputing.com.au/smart-vpns-with-headscale/) is an excellent reference.
 
 ## Apache
 
-The following minimal Apache config will proxy traffic to the Headscale instance on `<IP:PORT>`. Note that `upgrade=any` is required as a parameter for `ProxyPass` so that WebSockets traffic whose `Upgrade` header value is not equal to `WebSocket` (i. e. Tailscale Control Protocol) is forwarded correctly. See the [Apache docs](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html) for more information on this.
+The following minimal Apache config will proxy traffic to the headscale instance on `<IP:PORT>`. Note that `upgrade=any` is required as a parameter for `ProxyPass` so that WebSockets traffic whose `Upgrade` header value is not equal to `WebSocket` (i. e. Tailscale Control Protocol) is forwarded correctly. See the [Apache docs](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html) for more information on this.
 
-```
+```apache title="apache.conf"
 <VirtualHost *:443>
 	ServerName <YOUR_SERVER_NAME>
 

docs/ref/integration/tools.md

@@ -0,0 +1,14 @@
+# Tools related to headscale
+
+!!! warning "Community contributions"
+
+    This page contains community contributions. The projects listed here are not
+    maintained by the headscale authors and are written by community members.
+
+This page collects third-party tools and scripts related to headscale.
+
+| Name                  | Repository Link                                                 | Description                                                          |
+| --------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------- |
+| tailscale-manager     | [Github](https://github.com/singlestore-labs/tailscale-manager) | Dynamically manage Tailscale route advertisements                    |
+| headscalebacktosqlite | [Github](https://github.com/bigbozza/headscalebacktosqlite)     | Migrate headscale from PostgreSQL back to SQLite                     |
+| headscale-pf          | [Github](https://github.com/YouSysAdmin/headscale-pf)           | Populates user groups based on user groups in Jumpcloud or Authentik |

docs/ref/integration/web-ui.md

@@ -0,0 +1,19 @@
+# Web interfaces for headscale
+
+!!! warning "Community contributions"
+
+    This page contains community contributions. The projects listed here are not
+    maintained by the headscale authors and are written by community members.
+
+Headscale doesn't provide a built-in web interface but users may pick one from the available options.
+
+| Name                   | Repository Link                                            | Description                                                                          |
+| ---------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| headscale-ui           | [Github](https://github.com/gurucomputing/headscale-ui)    | A web frontend for the headscale Tailscale-compatible coordination server            |
+| HeadscaleUi            | [GitHub](https://github.com/simcu/headscale-ui)            | A static headscale admin ui, no backend environment required                         |
+| Headplane              | [GitHub](https://github.com/tale/headplane)                | An advanced Tailscale inspired frontend for headscale                                |
+| headscale-admin        | [Github](https://github.com/GoodiesHQ/headscale-admin)     | Headscale-Admin is meant to be a simple, modern web interface for headscale          |
+| ouroboros              | [Github](https://github.com/yellowsink/ouroboros)          | Ouroboros is designed for users to manage their own devices, rather than for admins  |
+| unraid-headscale-admin | [Github](https://github.com/ich777/unraid-headscale-admin) | A simple headscale admin UI for Unraid, it offers Local (`docker exec`) and API Mode |
+
+You can ask for support on our [Discord server](https://discord.gg/c84AZQhmpx) in the "web-interfaces" channel.

docs/ref/oidc.md

@@ -1,4 +1,4 @@
-# Configuring Headscale to use OIDC authentication
+# Configuring headscale to use OIDC authentication
 
 In order to authenticate users through a centralized solution one must enable the OIDC integration.
 
@@ -11,7 +11,7 @@ Known limitations:
 
 In your `config.yaml`, customize this to your liking:
 
-```yaml
+```yaml title="config.yaml"
 oidc:
   # Block further startup until the OIDC provider is healthy and available
   only_start_if_oidc_is_available: true
@@ -45,18 +45,24 @@ oidc:
   allowed_users:
     - alice@example.com
 
-  # If `strip_email_domain` is set to `true`, the domain part of the username email address will be removed.
-  # This will transform `first-name.last-name@example.com` to the user `first-name.last-name`
-  # If `strip_email_domain` is set to `false` the domain part will NOT be removed resulting to the following
-  # user: `first-name.last-name.example.com`
-  strip_email_domain: true
+  # Optional: PKCE (Proof Key for Code Exchange) configuration
+  # PKCE adds an additional layer of security to the OAuth 2.0 authorization code flow
+  # by preventing authorization code interception attacks
+  # See https://datatracker.ietf.org/doc/html/rfc7636
+  pkce:
+    # Enable or disable PKCE support (default: false)
+    enabled: false
+    # PKCE method to use:
+    # - plain: Use plain code verifier
+    # - S256: Use SHA256 hashed code verifier (default, recommended)
+    method: S256
 ```
 
 ## Azure AD example
 
-In order to integrate Headscale with Azure Active Directory, we'll need to provision an App Registration with the correct scopes and redirect URI. Here with Terraform:
+In order to integrate headscale with Azure Active Directory, we'll need to provision an App Registration with the correct scopes and redirect URI. Here with Terraform:
 
-```hcl
+```hcl title="terraform.hcl"
 resource "azuread_application" "headscale" {
   display_name = "Headscale"
 
@@ -84,7 +90,7 @@ resource "azuread_application" "headscale" {
     }
   }
   web {
-    # Points at your running Headscale instance
+    # Points at your running headscale instance
     redirect_uris = ["https://headscale.example.com/oidc/callback"]
 
     implicit_grant {
@@ -125,9 +131,9 @@ output "headscale_client_secret" {
 }
 ```
 
-And in your Headscale `config.yaml`:
+And in your headscale `config.yaml`:
 
-```yaml
+```yaml title="config.yaml"
 oidc:
   issuer: "https://login.microsoftonline.com/<tenant-UUID>/v2.0"
   client_id: "<client-id-from-terraform>"
@@ -144,7 +150,7 @@ oidc:
 
 ## Google OAuth Example
 
-In order to integrate Headscale with Google, you'll need to have a [Google Cloud Console](https://console.cloud.google.com) account.
+In order to integrate headscale with Google, you'll need to have a [Google Cloud Console](https://console.cloud.google.com) account.
 
 Google OAuth has a [verification process](https://support.google.com/cloud/answer/9110914?hl=en) if you need to have users authenticate who are outside of your domain. If you only need to authenticate users from your domain name (ie `@example.com`), you don't need to go through the verification process.
 
@@ -158,17 +164,50 @@ However if you don't have a domain, or need to add users outside of your domain,
 4. Click `Create Credentials` -> `OAuth client ID`
 5. Under `Application Type`, choose `Web Application`
 6. For `Name`, enter whatever you like
-7. Under `Authorised redirect URIs`, use `https://example.com/oidc/callback`, replacing example.com with your Headscale URL.
+7. Under `Authorised redirect URIs`, use `https://example.com/oidc/callback`, replacing example.com with your headscale URL.
 8. Click `Save` at the bottom of the form
 9. Take note of the `Client ID` and `Client secret`, you can also download it for reference if you need it.
 10. Edit your headscale config, under `oidc`, filling in your `client_id` and `client_secret`:
-
-```yaml
-oidc:
-  issuer: "https://accounts.google.com"
-  client_id: ""
-  client_secret: ""
-  scope: ["openid", "profile", "email"]
-```
+    ```yaml title="config.yaml"
+    oidc:
+      issuer: "https://accounts.google.com"
+      client_id: ""
+      client_secret: ""
+      scope: ["openid", "profile", "email"]
+    ```
 
 You can also use `allowed_domains` and `allowed_users` to restrict the users who can authenticate.
+
+## Authelia
+Authelia since v4.39.0, has removed most claims from the `ID Token`, they are still available when application queries [UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo). 
+
+Following config restores sending 'default' claims in the `ID Token`
+
+For more information please read: [Authelia restore functionality prior to claims parameter](https://www.authelia.com/integration/openid-connect/openid-connect-1.0-claims/#restore-functionality-prior-to-claims-parameter)
+
+
+```yaml
+identity_providers:
+  oidc:
+    claims_policies:
+      default:
+        id_token: ['groups', 'email', 'email_verified', 'alt_emails', 'preferred_username', 'name']
+    clients:
+      - client_id: 'headscale'
+        client_name: 'headscale'
+        client_secret: ''
+        public: false
+        claims_policy: 'default'
+        authorization_policy: 'two_factor'
+        require_pkce: true
+        pkce_challenge_method: 'S256'
+        redirect_uris:
+          - 'https://headscale.example.com/oidc/callback'
+        scopes:
+          - 'openid'
+          - 'profile'
+          - 'groups'
+          - 'email'
+        userinfo_signed_response_alg: 'none'
+        token_endpoint_auth_method: 'client_secret_basic'
+```

docs/ref/remote-cli.md

@@ -0,0 +1,105 @@
+# Controlling headscale with remote CLI
+
+This documentation has the goal of showing a user how-to control a headscale instance
+from a remote machine with the `headscale` command line binary.
+
+## Prerequisite
+
+- A workstation to run `headscale` (any supported platform, e.g. Linux).
+- A headscale server with gRPC enabled.
+- Connections to the gRPC port (default: `50443`) are allowed.
+- Remote access requires an encrypted connection via TLS.
+- An API key to authenticate with the headscale server.
+
+## Create an API key
+
+We need to create an API key to authenticate with the remote headscale server when using it from our workstation.
+
+To create an API key, log into your headscale server and generate a key:
+
+```shell
+headscale apikeys create --expiration 90d
+```
+
+Copy the output of the command and save it for later. Please note that you can not retrieve a key again,
+if the key is lost, expire the old one, and create a new key.
+
+To list the keys currently associated with the server:
+
+```shell
+headscale apikeys list
+```
+
+and to expire a key:
+
+```shell
+headscale apikeys expire --prefix "<PREFIX>"
+```
+
+## Download and configure headscale
+
+1.  Download the [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases). Make
+    sure to use the same version as on the server.
+
+1.  Put the binary somewhere in your `PATH`, e.g. `/usr/local/bin/headscale`
+
+1.  Make `headscale` executable:
+
+    ```shell
+    chmod +x /usr/local/bin/headscale
+    ```
+
+1.  Provide the connection parameters for the remote headscale server either via a minimal YAML configuration file or via
+    environment variables:
+
+    === "Minimal YAML configuration file"
+
+        ```yaml title="config.yaml"
+        cli:
+            address: <HEADSCALE_ADDRESS>:<PORT>
+            api_key: <API_KEY_FROM_PREVIOUS_STEP>
+        ```
+
+    === "Environment variables"
+
+        ```shell
+        export HEADSCALE_CLI_ADDRESS="<HEADSCALE_ADDRESS>:<PORT>"
+        export HEADSCALE_CLI_API_KEY="<API_KEY_FROM_PREVIOUS_STEP>"
+        ```
+
+        !!! bug
+
+            Headscale currently requires at least an empty configuration file when environment variables are used to
+            specify connection details. See [issue 2193](https://github.com/juanfont/headscale/issues/2193) for more
+            information.
+
+    This instructs the `headscale` binary to connect to a remote instance at `<HEADSCALE_ADDRESS>:<PORT>`, instead of
+    connecting to the local instance.
+
+1.  Test the connection
+
+    Let us run the headscale command to verify that we can connect by listing our nodes:
+
+    ```shell
+    headscale nodes list
+    ```
+
+    You should now be able to see a list of your nodes from your workstation, and you can
+    now control the headscale server from your workstation.
+
+## Behind a proxy
+
+It is possible to run the gRPC remote endpoint behind a reverse proxy, like Nginx, and have it run on the _same_ port as headscale.
+
+While this is _not a supported_ feature, an example on how this can be set up on
+[NixOS is shown here](https://github.com/kradalby/dotfiles/blob/4489cdbb19cddfbfae82cd70448a38fde5a76711/machines/headscale.oracldn/headscale.nix#L61-L91).
+
+## Troubleshooting
+
+- Make sure you have the _same_ headscale version on your server and workstation.
+- Ensure that connections to the gRPC port are allowed.
+- Verify that your TLS certificate is valid and trusted.
+- If you don't have access to a trusted certificate (e.g. from Let's Encrypt), either:
+    - Add your self-signed certificate to the trust store of your OS _or_
+    - Disable certificate verification by either setting `cli.insecure: true` in the configuration file or by setting
+      `HEADSCALE_CLI_INSECURE=1` via an environment variable. We do **not** recommend to disable certificate validation.

docs/ref/routes.md

@@ -0,0 +1,279 @@
+# Routes
+Headscale supports route advertising and can be used to manage [subnet routers](https://tailscale.com/kb/1019/subnets)
+and [exit nodes](https://tailscale.com/kb/1103/exit-nodes) for a tailnet.
+
+- [Subnet routers](#subnet-router) may be used to connect an existing network such as a virtual
+  private cloud or an on-premise network with your tailnet. Use a subnet router to access devices where Tailscale can't
+  be installed or to gradually rollout Tailscale.
+- [Exit nodes](#exit-node) can be used to route all Internet traffic for another Tailscale
+  node. Use it to securely access the Internet on an untrusted Wi-Fi or to access online services that expect traffic
+  from a specific IP address.
+
+## Subnet router
+The setup of a subnet router requires double opt-in, once from a subnet router and once on the control server to allow
+its use within the tailnet. Optionally, use [`autoApprovers` to automatically approve routes from a subnet
+router](#automatically-approve-routes-of-a-subnet-router).
+
+### Setup a subnet router
+#### Configure a node as subnet router
+
+Register a node and advertise the routes it should handle as comma separated list:
+
+```console
+$ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-routes=10.0.0.0/8,192.168.0.0/24
+```
+
+If the node is already registered, it can advertise new routes or update previously announced routes with:
+
+```console
+$ sudo tailscale set --advertise-routes=10.0.0.0/8,192.168.0.0/24
+```
+
+Finally, [enable IP forwarding](#enable-ip-forwarding) to route traffic.
+
+
+#### Enable the subnet router on the control server
+
+The routes of a tailnet can be displayed with the `headscale nodes list-routes` command. A subnet router with the
+hostname `myrouter` announced the IPv4 networks `10.0.0.0/8` and `192.168.0.0/24`. Those need to be approved before they
+can be used.
+
+```console
+$ headscale nodes list-routes
+ID | Hostname | Approved | Available                  | Serving (Primary)
+1  | myrouter |          | 10.0.0.0/8, 192.168.0.0/24 |
+```
+
+Approve all desired routes of a subnet router by specifying them as comma separated list:
+
+```console
+$ headscale nodes approve-routes --identifier 1 --routes 10.0.0.0/8,192.168.0.0/24
+Node updated
+```
+
+The node `myrouter` can now route the IPv4 networks `10.0.0.0/8` and `192.168.0.0/24` for the tailnet.
+
+```console
+$ headscale nodes list-routes
+ID | Hostname | Approved                   | Available                  | Serving (Primary)
+1  | myrouter | 10.0.0.0/8, 192.168.0.0/24 | 10.0.0.0/8, 192.168.0.0/24 | 10.0.0.0/8, 192.168.0.0/24
+```
+
+#### Use the subnet router
+
+To accept routes advertised by a subnet router on a node:
+
+```console
+$ sudo tailscale set --accept-routes
+```
+
+Please refer to the official [Tailscale
+documentation](https://tailscale.com/kb/1019/subnets#use-your-subnet-routes-from-other-devices) for how to use a subnet
+router on different operating systems.
+
+### Restrict the use of a subnet router with ACL
+The routes announced by subnet routers are available to the nodes in a tailnet. By default, without an ACL enabled, all
+nodes can accept and use such routes. Configure an ACL to explicitly manage who can use routes.
+
+The ACL snippet below defines three hosts, a subnet router `router`, a regular node `node` and `service.example.net` as
+internal service that can be reached via a route on the subnet router `router`. It allows the node `node` to access
+`service.example.net` on port 80 and 443 which is reachable via the subnet router. Access to the subnet router itself is
+denied.
+
+```json title="Access the routes of a subnet router without the subnet router itself"
+{
+  "hosts": {
+    // the router is not referenced but announces 192.168.0.0/24"
+    "router": "100.64.0.1/32",
+    "node": "100.64.0.2/32",
+    "service.example.net": "192.168.0.1/32"
+  },
+  "acls": [
+    {
+      "action": "accept",
+      "src": [
+        "node"
+      ],
+      "dst": [
+        "service.example.net:80,443"
+      ]
+    }
+  ]
+}
+```
+
+### Automatically approve routes of a subnet router
+The initial setup of a subnet router usually requires manual approval of their announced routes on the control server
+before they can be used by a node in a tailnet. Headscale supports the `autoApprovers` section of an ACL to automate the
+approval of routes served with a subnet router.
+
+The ACL snippet below defines the tag `tag:router` owned by the user `alice`. This tag is used for `routes` in the
+`autoApprovers` section. The IPv4 route `192.168.0.0/24` is automatically approved once announced by a subnet router
+owned by the user `alice` and that also advertises the tag `tag:router`.
+
+```json title="Subnet routers owned by alice and tagged with tag:router are automatically approved"
+{
+  "tagOwners": {
+    "tag:router": [
+      "alice@"
+    ]
+  },
+  "autoApprovers": {
+    "routes": {
+      "192.168.0.0/24": [
+        "tag:router"
+      ]
+    }
+  },
+  "acls": [
+    // more rules
+  ]
+}
+```
+
+Advertise the route `192.168.0.0/24` from a subnet router that also advertises the tag `tag:router` when joining the tailnet:
+
+```console
+$ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags tag:router --advertise-routes 192.168.0.0/24
+```
+
+Please see the [official Tailscale documentation](https://tailscale.com/kb/1337/acl-syntax#autoapprovers) for more
+information on auto approvers.
+
+## Exit node
+The setup of an exit node requires double opt-in, once from an exit node and once on the control server to allow its use
+within the tailnet. Optionally, use [`autoApprovers` to automatically approve an exit
+node](#automatically-approve-an-exit-node-with-auto-approvers).
+
+### Setup an exit node
+#### Configure a node as exit node
+
+Register a node and make it advertise itself as an exit node:
+
+```console
+$ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-exit-node
+```
+
+If the node is already registered, it can advertise exit capabilities like this:
+
+```console
+$ sudo tailscale set --advertise-exit-node
+```
+
+Finally, [enable IP forwarding](#enable-ip-forwarding) to route traffic.
+
+
+#### Enable the exit node on the control server
+
+The routes of a tailnet can be displayed with the `headscale nodes list-routes` command. An exit node can be recognized
+by its announced routes: `0.0.0.0/0` for IPv4 and `::/0` for IPv6. The exit node with the hostname `myexit` is already
+available, but needs to be approved:
+
+```console
+$ headscale nodes list-routes
+ID | Hostname | Approved | Available       | Serving (Primary)
+1  | myexit   |          | 0.0.0.0/0, ::/0 |
+```
+
+For exit nodes, it is sufficient to approve either the IPv4 or IPv6 route. The other will be approved automatically.
+
+```console
+$ headscale nodes approve-routes --identifier 1 --routes 0.0.0.0/0
+Node updated
+```
+
+The node `myexit` is now approved as exit node for the tailnet:
+
+```console
+$ headscale nodes list-routes
+ID | Hostname | Approved        | Available       | Serving (Primary)
+1  | myexit   | 0.0.0.0/0, ::/0 | 0.0.0.0/0, ::/0 | 0.0.0.0/0, ::/0
+```
+
+#### Use the exit node
+
+The exit node can now be used on a node with:
+
+```console
+$ sudo tailscale set --exit-node myexit
+```
+
+Please refer to the official [Tailscale documentation](https://tailscale.com/kb/1103/exit-nodes#use-the-exit-node) for
+how to use an exit node on different operating systems.
+
+### Restrict the use of an exit node with ACL
+An exit node is offered to all nodes in a tailnet. By default, without an ACL enabled, all nodes in a tailnet can select
+and use an exit node. Configure `autogroup:internet` in an ACL rule to restrict who can use *any* of the available exit
+nodes.
+
+```json title="Example use of autogroup:internet"
+{
+  "acls": [
+    {
+      "action": "accept",
+      "src": [
+        "..."
+      ],
+      "dst": [
+        "autogroup:internet:*"
+      ]
+    }
+  ]
+}
+```
+
+### Automatically approve an exit node with auto approvers
+The initial setup of an exit node usually requires manual approval on the control server before it can be used by a node
+in a tailnet. Headscale supports the `autoApprovers` section of an ACL to automate the approval of a new exit node as
+soon as it joins the tailnet.
+
+The ACL snippet below defines the tag `tag:exit` owned by the user `alice`. This tag is used for `exitNode` in the
+`autoApprovers` section. A new exit node which is owned by the user `alice` and that also advertises the tag `tag:exit`
+is automatically approved:
+
+```json title="Exit nodes owned by alice and tagged with tag:exit are automatically approved"
+{
+  "tagOwners": {
+    "tag:exit": [
+      "alice@"
+    ]
+  },
+  "autoApprovers": {
+    "exitNode": [
+      "tag:exit"
+    ]
+  },
+  "acls": [
+    // more rules
+  ]
+}
+```
+
+Advertise a node as exit node and also advertise the tag `tag:exit` when joining the tailnet:
+
+```console
+$ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags tag:exit --advertise-exit-node
+```
+
+Please see the [official Tailscale documentation](https://tailscale.com/kb/1337/acl-syntax#autoapprovers) for more
+information on auto approvers.
+
+## High availability
+
+Headscale has limited support for high availability routing. Multiple subnet routers with overlapping routes or multiple
+exit nodes can be used to provide high availability for users. If one router node goes offline, another one can serve
+the same routes to clients. Please see the official [Tailscale documentation on high
+availability](https://tailscale.com/kb/1115/high-availability#subnet-router-high-availability) for details.
+
+!!! bug
+
+    In certain situations it might take up to 16 minutes for Headscale to detect a node as offline. A failover node
+    might not be selected fast enough, if such a node is used as subnet router or exit node causing service
+    interruptions for clients. See [issue 2129](https://github.com/juanfont/headscale/issues/2129) for more information.
+
+## Troubleshooting
+### Enable IP forwarding
+
+A subnet router or exit node is routing traffic on behalf of other nodes and thus requires IP forwarding. Check the
+official [Tailscale documentation](https://tailscale.com/kb/1019/subnets/?tab=linux#enable-ip-forwarding) for how to
+enable IP forwarding.

docs/ref/tls.md

@@ -4,16 +4,18 @@
 
 Headscale can be configured to expose its web service via TLS. To configure the certificate and key file manually, set the `tls_cert_path` and `tls_cert_path` configuration parameters. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.
 
-```yaml
+```yaml title="config.yaml"
 tls_cert_path: ""
 tls_key_path: ""
 ```
 
+The certificate should contain the full chain, else some clients, like the Tailscale Android client, will reject it.
+
 ## Let's Encrypt / ACME
 
 To get a certificate automatically via [Let's Encrypt](https://letsencrypt.org/), set `tls_letsencrypt_hostname` to the desired certificate hostname. This name must resolve to the IP address(es) headscale is reachable on (i.e., it must correspond to the `server_url` configuration parameter). The certificate and Let's Encrypt account credentials will be stored in the directory configured in `tls_letsencrypt_cache_dir`. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.
 
-```yaml
+```yaml title="config.yaml"
 tls_letsencrypt_hostname: ""
 tls_letsencrypt_listen: ":http"
 tls_letsencrypt_cache_dir: ".cache"
@@ -47,10 +49,10 @@ Headscale uses [autocert](https://pkg.go.dev/golang.org/x/crypto/acme/autocert),
 
 If you want to validate that certificate renewal completed successfully, this can be done either manually, or through external monitoring software. Two examples of doing this manually:
 
-1. Open the URL for your Headscale server in your browser of choice, and manually inspecting the expiry date of the certificate you receive.
+1. Open the URL for your headscale server in your browser of choice, and manually inspecting the expiry date of the certificate you receive.
 2. Or, check remotely from CLI using `openssl`:
 
-```bash
+```console
 $ openssl s_client -servername [hostname] -connect [hostname]:443 | openssl x509 -noout -dates
 (...)
 notBefore=Feb  8 09:48:26 2024 GMT

docs/remote-cli.md

@@ -1,100 +0,0 @@
-# Controlling `headscale` with remote CLI
-
-## Prerequisit
-
-- A workstation to run `headscale` (could be Linux, macOS, other supported platforms)
-- A `headscale` server (version `0.13.0` or newer)
-- Access to create API keys (local access to the `headscale` server)
-- `headscale` _must_ be served over TLS/HTTPS
-  - Remote access does _not_ support unencrypted traffic.
-- Port `50443` must be open in the firewall (or port overriden by `grpc_listen_addr` option)
-
-## Goal
-
-This documentation has the goal of showing a user how-to set control a `headscale` instance
-from a remote machine with the `headscale` command line binary.
-
-## Create an API key
-
-We need to create an API key to authenticate our remote `headscale` when using it from our workstation.
-
-To create a API key, log into your `headscale` server and generate a key:
-
-```shell
-headscale apikeys create --expiration 90d
-```
-
-Copy the output of the command and save it for later. Please note that you can not retrieve a key again,
-if the key is lost, expire the old one, and create a new key.
-
-To list the keys currently assosicated with the server:
-
-```shell
-headscale apikeys list
-```
-
-and to expire a key:
-
-```shell
-headscale apikeys expire --prefix "<PREFIX>"
-```
-
-## Download and configure `headscale`
-
-1. Download the latest [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases):
-
-2. Put the binary somewhere in your `PATH`, e.g. `/usr/local/bin/headscale`
-
-3. Make `headscale` executable:
-
-```shell
-chmod +x /usr/local/bin/headscale
-```
-
-4. Configure the CLI through Environment Variables
-
-```shell
-export HEADSCALE_CLI_ADDRESS="<HEADSCALE ADDRESS>:<PORT>"
-export HEADSCALE_CLI_API_KEY="<API KEY FROM PREVIOUS STAGE>"
-```
-
-for example:
-
-```shell
-export HEADSCALE_CLI_ADDRESS="headscale.example.com:50443"
-export HEADSCALE_CLI_API_KEY="abcde12345"
-```
-
-This will tell the `headscale` binary to connect to a remote instance, instead of looking
-for a local instance (which is what it does on the server).
-
-The API key is needed to make sure that your are allowed to access the server. The key is _not_
-needed when running directly on the server, as the connection is local.
-
-5. Test the connection
-
-Let us run the headscale command to verify that we can connect by listing our nodes:
-
-```shell
-headscale nodes list
-```
-
-You should now be able to see a list of your nodes from your workstation, and you can
-now control the `headscale` server from your workstation.
-
-## Behind a proxy
-
-It is possible to run the gRPC remote endpoint behind a reverse proxy, like Nginx, and have it run on the _same_ port as `headscale`.
-
-While this is _not a supported_ feature, an example on how this can be set up on
-[NixOS is shown here](https://github.com/kradalby/dotfiles/blob/4489cdbb19cddfbfae82cd70448a38fde5a76711/machines/headscale.oracldn/headscale.nix#L61-L91).
-
-## Troubleshooting
-
-Checklist:
-
-- Make sure you have the _same_ `headscale` version on your server and workstation
-- Make sure you use version `0.13.0` or newer.
-- Verify that your TLS certificate is valid and trusted
-  - If you do not have access to a trusted certificate (e.g. from Let's Encrypt), add your self signed certificate to the trust store of your OS or
-  - Set `HEADSCALE_CLI_INSECURE` to 0 in your environement

docs/requirements.txt

@@ -1,4 +1,6 @@
-cairosvg~=2.7.1
-mkdocs-material~=9.5.18
-mkdocs-minify-plugin~=0.7.1
-pillow~=10.1.0
+mike~=2.1
+mkdocs-include-markdown-plugin~=7.1
+mkdocs-macros-plugin~=1.3
+mkdocs-material[imaging]~=9.5
+mkdocs-minify-plugin~=0.7
+mkdocs-redirects~=1.2

docs/running-headscale-container.md

@@ -1,195 +0,0 @@
-# Running headscale in a container
-
-!!! warning "Community documentation"
-
-    This page is not actively maintained by the headscale authors and is
-    written by community members. It is _not_ verified by `headscale` developers.
-
-    **It might be outdated and it might miss necessary steps**.
-
-## Goal
-
-This documentation has the goal of showing a user how-to set up and run `headscale` in a container.
-[Docker](https://www.docker.com) is used as the reference container implementation, but there is no reason that it should
-not work with alternatives like [Podman](https://podman.io). The Docker image can be found on Docker Hub [here](https://hub.docker.com/r/headscale/headscale).
-
-## Configure and run `headscale`
-
-1. Prepare a directory on the host Docker node in your directory of choice, used to hold `headscale` configuration and the [SQLite](https://www.sqlite.org/) database:
-
-    ```shell
-    mkdir -p ./headscale/config
-    cd ./headscale
-    ```
-
-1. Create an empty SQlite datebase in the headscale directory:
-
-    ```shell
-    touch ./config/db.sqlite
-    ```
-
-1. **(Strongly Recommended)** Download a copy of the [example configuration](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository.
-
-    - Using `wget`:
-
-        ```shell
-        wget -O ./config/config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml
-        ```
-
-    - Using `curl`:
-
-        ```shell
-        curl https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml -o ./config/config.yaml
-        ```
-
-    - **(Advanced)** If you would like to hand craft a config file **instead** of downloading the example config file, create a blank `headscale` configuration in the headscale directory to edit:
-
-        ```shell
-        touch ./config/config.yaml
-        ```
-
-        Modify the config file to your preferences before launching Docker container.
-        Here are some settings that you likely want:
-
-        ```yaml
-        # Change to your hostname or host IP
-        server_url: http://your-host-name:8080
-        # Listen to 0.0.0.0 so it's accessible outside the container
-        metrics_listen_addr: 0.0.0.0:9090
-        # The default /var/lib/headscale path is not writable in the container
-        noise:
-          private_key_path: /etc/headscale/noise_private.key
-        # The default /var/lib/headscale path is not writable in the container
-        derp:
-          private_key_path: /etc/headscale/private.key
-        # The default /var/run/headscale path is not writable  in the container
-        unix_socket: /etc/headscale/headscale.sock
-        # The default /var/lib/headscale path is not writable  in the container
-        database.type: sqlite3
-        database.sqlite.path: /etc/headscale/db.sqlite
-        ```
-
-        Alternatively, you can mount `/var/lib` and `/var/run` from your host system by adding
-        `--volume $(pwd)/lib:/var/lib/headscale` and `--volume $(pwd)/run:/var/run/headscale`
-        in the next step.
-
-1. Start the headscale server while working in the host headscale directory:
-
-    ```shell
-    docker run \
-      --name headscale \
-      --detach \
-      --volume $(pwd)/config:/etc/headscale/ \
-      --publish 127.0.0.1:8080:8080 \
-      --publish 127.0.0.1:9090:9090 \
-      headscale/headscale:<VERSION> \
-      headscale serve
-    ```
-
-    Note: use `0.0.0.0:8080:8080` instead of `127.0.0.1:8080:8080` if you want to expose the container externally.
-
-    This command will mount `config/` under `/etc/headscale`, forward port 8080 out of the container so the
-    `headscale` instance becomes available and then detach so headscale runs in the background.
-
-    Example `docker-compose.yaml`
-
-      ```yaml
-      version: "3.7"
-      
-      services:
-        headscale:
-          image: headscale/headscale:0.22.3
-          restart: unless-stopped
-          container_name: headscale
-          ports:
-            - "127.0.0.1:8080:8080"
-            - "127.0.0.1:9090:9090"
-          volumes:
-            # pls change [config_path] to the fullpath of the config folder just created
-            - [config_path]:/etc/headscale
-          command: headscale serve
-      ```
-
-1. Verify `headscale` is running:
-   Follow the container logs:
-
-    ```shell
-    docker logs --follow headscale
-    ```
-
-    Verify running containers:
-
-    ```shell
-    docker ps
-    ```
-
-    Verify `headscale` is available:
-
-    ```shell
-    curl http://127.0.0.1:9090/metrics
-    ```
-
-1. Create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)):
-
-    ```shell
-    docker exec headscale \
-    headscale users create myfirstuser
-    ```
-
-### Register a machine (normal login)
-
-On a client machine, execute the `tailscale` login command:
-
-```shell
-tailscale up --login-server YOUR_HEADSCALE_URL
-```
-
-To register a machine when running `headscale` in a container, take the headscale command and pass it to the container:
-
-```shell
-docker exec headscale \
-  headscale --user myfirstuser nodes register --key <YOU_+MACHINE_KEY>
-```
-
-### Register machine using a pre authenticated key
-
-Generate a key using the command line:
-
-```shell
-docker exec headscale \
-  headscale --user myfirstuser preauthkeys create --reusable --expiration 24h
-```
-
-This will return a pre-authenticated key that can be used to connect a node to `headscale` during the `tailscale` command:
-
-```shell
-tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
-```
-
-## Debugging headscale running in Docker
-
-The `headscale/headscale` Docker container is based on a "distroless" image that does not contain a shell or any other debug tools. If you need to debug your application running in the Docker container, you can use the `-debug` variant, for example `headscale/headscale:x.x.x-debug`.
-
-### Running the debug Docker container
-
-To run the debug Docker container, use the exact same commands as above, but replace `headscale/headscale:x.x.x` with `headscale/headscale:x.x.x-debug` (`x.x.x` is the version of headscale). The two containers are compatible with each other, so you can alternate between them.
-
-### Executing commands in the debug container
-
-The default command in the debug container is to run `headscale`, which is located at `/bin/headscale` inside the container.
-
-Additionally, the debug container includes a minimalist Busybox shell.
-
-To launch a shell in the container, use:
-
-```
-docker run -it headscale/headscale:x.x.x-debug sh
-```
-
-You can also execute commands directly, such as `ls /bin` in this example:
-
-```
-docker run headscale/headscale:x.x.x-debug ls /bin
-```
-
-Using `docker exec` allows you to run commands in an existing container.

docs/running-headscale-linux-manual.md

@@ -1,197 +0,0 @@
-# Running headscale on Linux
-
-## Note: Outdated and "advanced"
-
-This documentation is considered the "legacy"/advanced/manual version of the documentation, you most likely do not
-want to use this documentation and rather look at the distro specific documentation (TODO LINK)[].
-
-## Goal
-
-This documentation has the goal of showing a user how-to set up and run `headscale` on Linux.
-In additional to the "get up and running section", there is an optional [SystemD section](#running-headscale-in-the-background-with-systemd)
-describing how to make `headscale` run properly in a server environment.
-
-## Configure and run `headscale`
-
-1. Download the latest [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases):
-
-    ```shell
-    wget --output-document=/usr/local/bin/headscale \
-    https://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>
-    ```
-
-1. Make `headscale` executable:
-
-    ```shell
-    chmod +x /usr/local/bin/headscale
-    ```
-
-1. Prepare a directory to hold `headscale` configuration and the [SQLite](https://www.sqlite.org/) database:
-
-    ```shell
-    # Directory for configuration
-
-    mkdir -p /etc/headscale
-
-    # Directory for Database, and other variable data (like certificates)
-    mkdir -p /var/lib/headscale
-    # or if you create a headscale user:
-    useradd \
-      --create-home \
-      --home-dir /var/lib/headscale/ \
-      --system \
-      --user-group \
-      --shell /usr/sbin/nologin \
-      headscale
-    ```
-
-1. Create an empty SQLite database:
-
-    ```shell
-    touch /var/lib/headscale/db.sqlite
-    ```
-
-1. Create a `headscale` configuration:
-
-    ```shell
-    touch /etc/headscale/config.yaml
-    ```
-
-    **(Strongly Recommended)** Download a copy of the [example configuration][config-example.yaml](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository.
-
-1. Start the headscale server:
-
-    ```shell
-    headscale serve
-    ```
-
-    This command will start `headscale` in the current terminal session.
-
-    ---
-
-    To continue the tutorial, open a new terminal and let it run in the background.
-    Alternatively use terminal emulators like [tmux](https://github.com/tmux/tmux) or [screen](https://www.gnu.org/software/screen/).
-
-    To run `headscale` in the background, please follow the steps in the [SystemD section](#running-headscale-in-the-background-with-systemd) before continuing.
-
-1. Verify `headscale` is running:
-  Verify `headscale` is available:
-
-    ```shell
-    curl http://127.0.0.1:9090/metrics
-    ```
-
-1. Create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)):
-
-    ```shell
-    headscale users create myfirstuser
-    ```
-
-### Register a machine (normal login)
-
-On a client machine, execute the `tailscale` login command:
-
-```shell
-tailscale up --login-server YOUR_HEADSCALE_URL
-```
-
-Register the machine:
-
-```shell
-headscale --user myfirstuser nodes register --key <YOUR_MACHINE_KEY>
-```
-
-### Register machine using a pre authenticated key
-
-Generate a key using the command line:
-
-```shell
-headscale --user myfirstuser preauthkeys create --reusable --expiration 24h
-```
-
-This will return a pre-authenticated key that can be used to connect a node to `headscale` during the `tailscale` command:
-
-```shell
-tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
-```
-
-## Running `headscale` in the background with SystemD
-
-:warning: **Deprecated**: This part is very outdated and you should use the [pre-packaged Headscale for this](./running-headscale-linux.md)
-
-This section demonstrates how to run `headscale` as a service in the background with [SystemD](https://www.freedesktop.org/wiki/Software/systemd/).
-This should work on most modern Linux distributions.
-
-1. Create a SystemD service configuration at `/etc/systemd/system/headscale.service` containing:
-
-    ```systemd
-    [Unit]
-    Description=headscale controller
-    After=syslog.target
-    After=network.target
-
-    [Service]
-    Type=simple
-    User=headscale
-    Group=headscale
-    ExecStart=/usr/local/bin/headscale serve
-    Restart=always
-    RestartSec=5
-
-    # Optional security enhancements
-    NoNewPrivileges=yes
-    PrivateTmp=yes
-    ProtectSystem=strict
-    ProtectHome=yes
-    WorkingDirectory=/var/lib/headscale
-    ReadWritePaths=/var/lib/headscale /var/run/headscale
-    AmbientCapabilities=CAP_NET_BIND_SERVICE
-    RuntimeDirectory=headscale
-
-    [Install]
-    WantedBy=multi-user.target
-    ```
-
-    Note that when running as the headscale user ensure that, either you add your current user to the headscale group:
-
-    ```shell
-    usermod -a -G headscale current_user
-    ```
-
-    or run all headscale commands as the headscale user:
-
-    ```shell
-    su - headscale
-    ```
-
-1. In `/etc/headscale/config.yaml`, override the default `headscale` unix socket with path that is writable by the `headscale` user or group:
-
-    ```yaml
-    unix_socket: /var/run/headscale/headscale.sock
-    ```
-
-1. Reload SystemD to load the new configuration file:
-
-    ```shell
-    systemctl daemon-reload
-    ```
-
-1. Enable and start the new `headscale` service:
-
-    ```shell
-    systemctl enable --now headscale
-    ```
-
-1. Verify the headscale service:
-
-    ```shell
-    systemctl status headscale
-    ```
-
-    Verify `headscale` is available:
-
-    ```shell
-    curl http://127.0.0.1:9090/metrics
-    ```
-
-`headscale` will now run in the background and start at boot.

docs/running-headscale-linux.md

@@ -1,95 +0,0 @@
-# Running headscale on Linux
-
-## Requirements
-
-- Ubuntu 20.04 or newer, Debian 11 or newer.
-
-## Goal
-
-Get Headscale up and running.
-
-This includes running Headscale with SystemD.
-
-## Migrating from manual install
-
-If you are migrating from the old manual install, the best thing would be to remove
-the files installed by following [the guide in reverse](./running-headscale-linux-manual.md).
-
-You should _not_ delete the database (`/var/lib/headscale/db.sqlite`) and the
-configuration (`/etc/headscale/config.yaml`).
-
-## Installation
-
-1. Download the latest Headscale package for your platform (`.deb` for Ubuntu and Debian) from [Headscale's releases page](https://github.com/juanfont/headscale/releases):
-
-    ```shell
-    wget --output-document=headscale.deb \
-      https://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>.deb
-    ```
-
-1. Install Headscale:
-
-    ```shell
-    sudo apt install headscale.deb
-    ```
-
-1. Enable Headscale service, this will start Headscale at boot:
-
-    ```shell
-    sudo systemctl enable headscale
-    ```
-
-1. Configure Headscale by editing the configuration file:
-
-    ```shell
-    nano /etc/headscale/config.yaml
-    ```
-
-1. Start Headscale:
-
-    ```shell
-    sudo systemctl start headscale
-    ```
-
-1. Check that Headscale is running as intended:
-
-    ```shell
-    systemctl status headscale
-    ```
-
-## Using Headscale
-
-### Create a user
-
-```shell
-headscale users create myfirstuser
-```
-
-### Register a machine (normal login)
-
-On a client machine, run the `tailscale` login command:
-
-```shell
-tailscale up --login-server <YOUR_HEADSCALE_URL>
-```
-
-Register the machine:
-
-```shell
-headscale --user myfirstuser nodes register --key <YOUR_MACHINE_KEY>
-```
-
-### Register machine using a pre authenticated key
-
-Generate a key using the command line:
-
-```shell
-headscale --user myfirstuser preauthkeys create --reusable --expiration 24h
-```
-
-This will return a pre-authenticated key that is used to
-connect a node to `headscale` during the `tailscale` command:
-
-```shell
-tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
-```

docs/running-headscale-openbsd.md

@@ -1,210 +0,0 @@
-# Running headscale on OpenBSD
-
-!!! warning "Community documentation"
-
-    This page is not actively maintained by the headscale authors and is
-    written by community members. It is _not_ verified by `headscale` developers.
-
-    **It might be outdated and it might miss necessary steps**.
-
-## Goal
-
-This documentation has the goal of showing a user how-to install and run `headscale` on OpenBSD 7.1.
-In additional to the "get up and running section", there is an optional [rc.d section](#running-headscale-in-the-background-with-rcd)
-describing how to make `headscale` run properly in a server environment.
-
-## Install `headscale`
-
-1. Install from ports (not recommended)
-
-    !!! info
-
-        As of OpenBSD 7.2, there's a headscale in ports collection, however, it's severely outdated(v0.12.4). You can install it via `pkg_add headscale`.
-
-1. Install from source on OpenBSD 7.2
-
-    ```shell
-    # Install prerequistes
-    pkg_add go
-
-    git clone https://github.com/juanfont/headscale.git
-
-    cd headscale
-
-    # optionally checkout a release
-    # option a. you can find offical relase at https://github.com/juanfont/headscale/releases/latest
-    # option b. get latest tag, this may be a beta release
-    latestTag=$(git describe --tags `git rev-list --tags --max-count=1`)
-
-    git checkout $latestTag
-
-    go build -ldflags="-s -w -X github.com/juanfont/headscale/cmd/headscale/cli.Version=$latestTag" github.com/juanfont/headscale
-
-    # make it executable
-    chmod a+x headscale
-
-    # copy it to /usr/local/sbin
-    cp headscale /usr/local/sbin
-    ```
-
-1. Install from source via cross compile
-
-    ```shell
-    # Install prerequistes
-    # 1. go v1.20+: headscale newer than 0.21 needs go 1.20+ to compile
-    # 2. gmake: Makefile in the headscale repo is written in GNU make syntax
-
-    git clone https://github.com/juanfont/headscale.git
-
-    cd headscale
-
-    # optionally checkout a release
-    # option a. you can find offical relase at https://github.com/juanfont/headscale/releases/latest
-    # option b. get latest tag, this may be a beta release
-    latestTag=$(git describe --tags `git rev-list --tags --max-count=1`)
-
-    git checkout $latestTag
-
-    make build GOOS=openbsd
-
-    # copy headscale to openbsd machine and put it in /usr/local/sbin
-    ```
-
-## Configure and run `headscale`
-
-1. Prepare a directory to hold `headscale` configuration and the [SQLite](https://www.sqlite.org/) database:
-
-    ```shell
-    # Directory for configuration
-
-    mkdir -p /etc/headscale
-
-    # Directory for Database, and other variable data (like certificates)
-    mkdir -p /var/lib/headscale
-    ```
-
-1. Create an empty SQLite database:
-
-    ```shell
-    touch /var/lib/headscale/db.sqlite
-    ```
-
-1. Create a `headscale` configuration:
-
-    ```shell
-    touch /etc/headscale/config.yaml
-    ```
-
-**(Strongly Recommended)** Download a copy of the [example configuration][config-example.yaml](https://github.com/juanfont/headscale/blob/main/config-example.yaml) from the headscale repository.
-
-1. Start the headscale server:
-
-    ```shell
-    headscale serve
-    ```
-
-    This command will start `headscale` in the current terminal session.
-
-    ***
-
-    To continue the tutorial, open a new terminal and let it run in the background.
-    Alternatively use terminal emulators like [tmux](https://github.com/tmux/tmux).
-
-    To run `headscale` in the background, please follow the steps in the [rc.d section](#running-headscale-in-the-background-with-rcd) before continuing.
-
-1. Verify `headscale` is running:
-
-    Verify `headscale` is available:
-
-    ```shell
-    curl http://127.0.0.1:9090/metrics
-    ```
-
-1. Create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)):
-
-    ```shell
-    headscale users create myfirstuser
-    ```
-
-### Register a machine (normal login)
-
-On a client machine, execute the `tailscale` login command:
-
-```shell
-tailscale up --login-server YOUR_HEADSCALE_URL
-```
-
-Register the machine:
-
-```shell
-headscale --user myfirstuser nodes register --key <YOU_+MACHINE_KEY>
-```
-
-### Register machine using a pre authenticated key
-
-Generate a key using the command line:
-
-```shell
-headscale --user myfirstuser preauthkeys create --reusable --expiration 24h
-```
-
-This will return a pre-authenticated key that can be used to connect a node to `headscale` during the `tailscale` command:
-
-```shell
-tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
-```
-
-## Running `headscale` in the background with rc.d
-
-This section demonstrates how to run `headscale` as a service in the background with [rc.d](https://man.openbsd.org/rc.d).
-
-1. Create a rc.d service at `/etc/rc.d/headscale` containing:
-
-    ```shell
-    #!/bin/ksh
-
-    daemon="/usr/local/sbin/headscale"
-    daemon_logger="daemon.info"
-    daemon_user="root"
-    daemon_flags="serve"
-    daemon_timeout=60
-
-    . /etc/rc.d/rc.subr
-
-    rc_bg=YES
-    rc_reload=NO
-
-    rc_cmd $1
-    ```
-
-1. `/etc/rc.d/headscale` needs execute permission:
-
-    ```shell
-    chmod a+x /etc/rc.d/headscale
-    ```
-
-1. Start `headscale` service:
-
-    ```shell
-    rcctl start headscale
-    ```
-
-1. Make `headscale` service start at boot:
-
-    ```shell
-    rcctl enable headscale
-    ```
-
-1. Verify the headscale service:
-
-    ```shell
-    rcctl check headscale
-    ```
-
-    Verify `headscale` is available:
-
-    ```shell
-    curl http://127.0.0.1:9090/metrics
-    ```
-
-    `headscale` will now run in the background and start at boot.

docs/running-headscale-sealos.md

@@ -1,136 +0,0 @@
-# Running headscale on Sealos
-
-!!! warning "Community documentation"
-
-    This page is not actively maintained by the headscale authors and is
-    written by community members. It is _not_ verified by `headscale` developers.
-
-    **It might be outdated and it might miss necessary steps**.
-
-## Goal
-
-This documentation has the goal of showing a user how-to run `headscale` on Sealos.
-
-## Running headscale server
-
-1. Click the following prebuilt template(version [0.23.0-alpha2](https://github.com/juanfont/headscale/releases/tag/v0.23.0-alpha2)):
-
-   [![](https://cdn.jsdelivr.net/gh/labring-actions/templates@main/Deploy-on-Sealos.svg)](https://cloud.sealos.io/?openapp=system-template%3FtemplateName%3Dheadscale)
-
-2. Click "Deploy Application" on the template page to start deployment. Upon completion, two applications appear: Headscale, and its [visual interface](https://github.com/GoodiesHQ/headscale-admin).
-3. Once deployment concludes, click 'Details' on the Headscale application page to navigate to the application's details.
-4. Wait for the application's status to switch to running. For accessing the headscale server, the Public Address associated with port 8080 is the address of the headscale server. To access the Headscale console, simply append `/admin/` to the Headscale public URL.
-
-   ![](./images/headscale-sealos-url.png)
-
-5. Click on 'Terminal' button on the right side of the details to access the Terminal of the headscale application. then create a user ([tailnet](https://tailscale.com/kb/1136/tailnet/)):
-
-   ```bash
-   headscale users create myfirstuser
-   ```
-
-### Register a machine (normal login)
-
-On a client machine, execute the `tailscale` login command:
-
-```bash
-# replace <YOUR_HEADSCALE_URL> with the public domain provided by Sealos
-tailscale up --login-server YOUR_HEADSCALE_URL
-```
-
-To register a machine when running headscale in [Sealos](https://sealos.io), click on 'Terminal' button on the right side of the headscale application's detail page to access the Terminal of the headscale application, then take the headscale command:
-
-```bash
-headscale --user myfirstuser nodes register --key <YOU_+MACHINE_KEY>
-```
-
-### Register machine using a pre authenticated key
-
-click on 'Terminal' button on the right side of the headscale application's detail page to access the Terminal of the headscale application, then generate a key using the command line:
-
-```bash
-headscale --user myfirstuser preauthkeys create --reusable --expiration 24h
-```
-
-This will return a pre-authenticated key that can be used to connect a node to `headscale` during the `tailscale` command:
-
-```bash
-tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
-```
-
-## Controlling headscale with remote CLI
-
-This documentation has the goal of showing a user how-to set control a headscale instance from a remote machine with the headscale command line binary.
-
-### Create an API key
-
-We need to create an API key to authenticate our remote headscale when using it from our workstation.
-
-To create a API key, click on 'Terminal' button on the right side of the headscale application's detail page to access the Terminal of the headscale application, then generate a key:
-
-```bash
-headscale apikeys create --expiration 90d
-```
-
-Copy the output of the command and save it for later. Please note that you can not retrieve a key again, if the key is lost, expire the old one, and create a new key.
-
-To list the keys currently assosicated with the server:
-
-```bash
-headscale apikeys list
-```
-
-and to expire a key:
-
-```bash
-headscale apikeys expire --prefix "<PREFIX>"
-```
-
-### Download and configure `headscale` client
-
-1. Download the latest [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases):
-
-2. Put the binary somewhere in your `PATH`, e.g. `/usr/local/bin/headscale`
-
-3. Make `headscale` executable:
-
-```shell
-chmod +x /usr/local/bin/headscale
-```
-
-4. Configure the CLI through Environment Variables
-
-```shell
-export HEADSCALE_CLI_ADDRESS="<HEADSCALE ADDRESS>:443"
-export HEADSCALE_CLI_API_KEY="<API KEY FROM PREVIOUS STAGE>"
-```
-
-In the headscale application's detail page, The Public Address corresponding to port 50443 corresponds to the value of <HEADSCALE ADDRESS>.
-
-![](./images/headscale-sealos-grpc-url.png)
-
-for example:
-
-```shell
-export HEADSCALE_CLI_ADDRESS="pwnjnnly.cloud.sealos.io:443"
-export HEADSCALE_CLI_API_KEY="abcde12345"
-```
-
-This will tell the `headscale` binary to connect to a remote instance, instead of looking
-for a local instance.
-
-The API key is needed to make sure that your are allowed to access the server. The key is _not_
-needed when running directly on the server, as the connection is local.
-
-1. Test the connection
-
-Let us run the headscale command to verify that we can connect by listing our nodes:
-
-```shell
-headscale nodes list
-```
-
-You should now be able to see a list of your nodes from your workstation, and you can
-now control the `headscale` server from your workstation.
-
-> Reference: [Headscale Deployment and Usage Guide: Mastering Tailscale's Self-Hosting Basics](https://icloudnative.io/en/posts/how-to-set-up-or-migrate-headscale/)

docs/setup/install/community.md

@@ -0,0 +1,55 @@
+# Community packages
+
+Several Linux distributions and community members provide packages for headscale. Those packages may be used instead of
+the [official releases](./official.md) provided by the headscale maintainers. Such packages offer improved integration
+for their targeted operating system and usually:
+
+- setup a dedicated local user account to run headscale
+- provide a default configuration
+- install headscale as system service
+
+!!! warning "Community packages might be outdated"
+
+    The packages mentioned on this page might be outdated or unmaintained. Use the [official releases](./official.md) to
+    get the current stable version or to test pre-releases.
+
+    [![Packaging status](https://repology.org/badge/vertical-allrepos/headscale.svg)](https://repology.org/project/headscale/versions)
+
+## Arch Linux
+
+Arch Linux offers a package for headscale, install via:
+
+```shell
+pacman -S headscale
+```
+
+The [AUR package `headscale-git`](https://aur.archlinux.org/packages/headscale-git) can be used to build the current
+development version.
+
+## Fedora, RHEL, CentOS
+
+A third-party repository for various RPM based distributions is available at:
+<https://copr.fedorainfracloud.org/coprs/jonathanspw/headscale/>. The site provides detailed setup and installation
+instructions.
+
+## Nix, NixOS
+
+A Nix package is available as: `headscale`. See the [NixOS package site for installation
+details](https://search.nixos.org/packages?show=headscale).
+
+## Gentoo
+
+```shell
+emerge --ask net-vpn/headscale
+```
+
+Gentoo specific documentation is available [here](https://wiki.gentoo.org/wiki/User:Maffblaster/Drafts/Headscale).
+
+## OpenBSD
+
+Headscale is available in ports. The port installs headscale as system service with `rc.d` and provides usage
+instructions upon installation.
+
+```shell
+pkg_add headscale
+```

docs/setup/install/container.md

@@ -0,0 +1,154 @@
+# Running headscale in a container
+
+!!! warning "Community documentation"
+
+    This page is not actively maintained by the headscale authors and is
+    written by community members. It is _not_ verified by headscale developers.
+
+    **It might be outdated and it might miss necessary steps**.
+
+This documentation has the goal of showing a user how-to set up and run headscale in a container. A container runtime
+such as [Docker](https://www.docker.com) or [Podman](https://podman.io) is required. The container image can be found on
+[Docker Hub](https://hub.docker.com/r/headscale/headscale) and [GitHub Container
+Registry](https://github.com/juanfont/headscale/pkgs/container/headscale). The container image URLs are:
+
+- [Docker Hub](https://hub.docker.com/r/headscale/headscale): `docker.io/headscale/headscale:<VERSION>`
+- [GitHub Container Registry](https://github.com/juanfont/headscale/pkgs/container/headscale):
+  `ghcr.io/juanfont/headscale:<VERSION>`
+
+## Configure and run headscale
+
+1.  Create a directory on the Docker host to store headscale's [configuration](../../ref/configuration.md) and the [SQLite](https://www.sqlite.org/) database:
+
+    ```shell
+    mkdir -p ./headscale/{config,lib,run}
+    cd ./headscale
+    ```
+
+1.  Download the example configuration for your chosen version and save it as: `$(pwd)/config/config.yaml`. Adjust the
+    configuration to suit your local environment. See [Configuration](../../ref/configuration.md) for details.
+
+1.  Start headscale from within the previously created `./headscale` directory:
+
+    ```shell
+    docker run \
+      --name headscale \
+      --detach \
+      --volume "$(pwd)/config:/etc/headscale" \
+      --volume "$(pwd)/lib:/var/lib/headscale" \
+      --volume "$(pwd)/run:/var/run/headscale" \
+      --publish 127.0.0.1:8080:8080 \
+      --publish 127.0.0.1:9090:9090 \
+      docker.io/headscale/headscale:<VERSION> \
+      serve
+    ```
+
+    Note: use `0.0.0.0:8080:8080` instead of `127.0.0.1:8080:8080` if you want to expose the container externally.
+
+    This command mounts the local directories inside the container, forwards port 8080 and 9090 out of the container so
+    the headscale instance becomes available and then detaches so headscale runs in the background.
+
+    A similar configuration for `docker-compose`:
+
+    ```yaml title="docker-compose.yaml"
+    services:
+      headscale:
+        image: docker.io/headscale/headscale:<VERSION>
+        restart: unless-stopped
+        container_name: headscale
+        ports:
+          - "127.0.0.1:8080:8080"
+          - "127.0.0.1:9090:9090"
+        volumes:
+          # Please set <HEADSCALE_PATH> to the absolute path
+          # of the previously created headscale directory.
+          - <HEADSCALE_PATH>/config:/etc/headscale
+          - <HEADSCALE_PATH>/lib:/var/lib/headscale
+          - <HEADSCALE_PATH>/run:/var/run/headscale
+        command: serve
+    ```
+
+1.  Verify headscale is running:
+
+    Follow the container logs:
+
+    ```shell
+    docker logs --follow headscale
+    ```
+
+    Verify running containers:
+
+    ```shell
+    docker ps
+    ```
+
+    Verify headscale is available:
+
+    ```shell
+    curl http://127.0.0.1:9090/metrics
+    ```
+
+1.  Create a headscale user:
+
+    ```shell
+    docker exec -it headscale \
+      headscale users create myfirstuser
+    ```
+
+### Register a machine (normal login)
+
+On a client machine, execute the `tailscale up` command to login:
+
+```shell
+tailscale up --login-server YOUR_HEADSCALE_URL
+```
+
+To register a machine when running headscale in a container, take the headscale command and pass it to the container:
+
+```shell
+docker exec -it headscale \
+  headscale nodes register --user myfirstuser --key <YOUR_MACHINE_KEY>
+```
+
+### Register a machine using a pre authenticated key
+
+Generate a key using the command line:
+
+```shell
+docker exec -it headscale \
+  headscale preauthkeys create --user myfirstuser --reusable --expiration 24h
+```
+
+This will return a pre-authenticated key that can be used to connect a node to headscale with the `tailscale up` command:
+
+```shell
+tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
+```
+
+## Debugging headscale running in Docker
+
+The Headscale container image is based on a "distroless" image that does not contain a shell or any other debug tools. If you need to debug headscale running in the Docker container, you can use the `-debug` variant, for example `docker.io/headscale/headscale:x.x.x-debug`.
+
+### Running the debug Docker container
+
+To run the debug Docker container, use the exact same commands as above, but replace `docker.io/headscale/headscale:x.x.x` with `docker.io/headscale/headscale:x.x.x-debug` (`x.x.x` is the version of headscale). The two containers are compatible with each other, so you can alternate between them.
+
+### Executing commands in the debug container
+
+The default command in the debug container is to run `headscale`, which is located at `/ko-app/headscale` inside the container.
+
+Additionally, the debug container includes a minimalist Busybox shell.
+
+To launch a shell in the container, use:
+
+```shell
+docker run -it docker.io/headscale/headscale:x.x.x-debug sh
+```
+
+You can also execute commands directly, such as `ls /ko-app` in this example:
+
+```shell
+docker run docker.io/headscale/headscale:x.x.x-debug ls /ko-app
+```
+
+Using `docker exec -it` allows you to run commands in an existing container.

docs/setup/install/official.md

@@ -0,0 +1,117 @@
+# Official releases
+
+Official releases for headscale are available as binaries for various platforms and DEB packages for Debian and Ubuntu.
+Both are available on the [GitHub releases page](https://github.com/juanfont/headscale/releases).
+
+## Using packages for Debian/Ubuntu (recommended)
+
+It is recommended to use our DEB packages to install headscale on a Debian based system as those packages configure a
+local user to run headscale, provide a default configuration and ship with a systemd service file. Supported
+distributions are Ubuntu 20.04 or newer, Debian 11 or newer.
+
+1.  Download the [latest headscale package](https://github.com/juanfont/headscale/releases/latest) for your platform (`.deb` for Ubuntu and Debian).
+
+    ```shell
+    HEADSCALE_VERSION="" # See above URL for latest version, e.g. "X.Y.Z" (NOTE: do not add the "v" prefix!)
+    HEADSCALE_ARCH="" # Your system architecture, e.g. "amd64"
+    wget --output-document=headscale.deb \
+     "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"
+    ```
+
+1.  Install headscale:
+
+    ```shell
+    sudo apt install ./headscale.deb
+    ```
+
+1.  [Configure headscale by editing the configuration file](../../ref/configuration.md):
+
+    ```shell
+    sudo nano /etc/headscale/config.yaml
+    ```
+
+1.  Enable and start the headscale service:
+
+    ```shell
+    sudo systemctl enable --now headscale
+    ```
+
+1.  Verify that headscale is running as intended:
+
+    ```shell
+    sudo systemctl status headscale
+    ```
+
+## Using standalone binaries (advanced)
+
+!!! warning "Advanced"
+
+    This installation method is considered advanced as one needs to take care of the local user and the systemd
+    service themselves. If possible, use the [DEB packages](#using-packages-for-debianubuntu-recommended) or a
+    [community package](./community.md) instead.
+
+This section describes the installation of headscale according to the [Requirements and
+assumptions](../requirements.md#assumptions). Headscale is run by a dedicated local user and the service itself is
+managed by systemd.
+
+1.  Download the latest [`headscale` binary from GitHub's release page](https://github.com/juanfont/headscale/releases):
+
+    ```shell
+    sudo wget --output-document=/usr/local/bin/headscale \
+    https://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>
+    ```
+
+1.  Make `headscale` executable:
+
+    ```shell
+    sudo chmod +x /usr/local/bin/headscale
+    ```
+
+1.  Add a dedicated local user to run headscale:
+
+    ```shell
+    sudo useradd \
+     --create-home \
+     --home-dir /var/lib/headscale/ \
+     --system \
+     --user-group \
+     --shell /usr/sbin/nologin \
+     headscale
+    ```
+
+1.  Download the example configuration for your chosen version and save it as: `/etc/headscale/config.yaml`. Adjust the
+    configuration to suit your local environment. See [Configuration](../../ref/configuration.md) for details.
+
+    ```shell
+    sudo mkdir -p /etc/headscale
+    sudo nano /etc/headscale/config.yaml
+    ```
+
+1.  Copy [headscale's systemd service file](../../packaging/headscale.systemd.service) to
+    `/etc/systemd/system/headscale.service` and adjust it to suit your local setup. The following parameters likely need
+    to be modified: `ExecStart`, `WorkingDirectory`, `ReadWritePaths`.
+
+1.  In `/etc/headscale/config.yaml`, override the default `headscale` unix socket with a path that is writable by the
+    `headscale` user or group:
+
+    ```yaml title="config.yaml"
+    unix_socket: /var/run/headscale/headscale.sock
+    ```
+
+1.  Reload systemd to load the new configuration file:
+
+    ```shell
+    systemctl daemon-reload
+    ```
+
+1.  Enable and start the new headscale service:
+
+    ```shell
+    systemctl enable --now headscale
+    ```
+
+1.  Verify that headscale is running as intended:
+
+    ```shell
+    systemctl status headscale
+    ```

docs/setup/install/source.md

@@ -0,0 +1,63 @@
+# Build from source
+
+!!! warning "Community documentation"
+
+    This page is not actively maintained by the headscale authors and is
+    written by community members. It is _not_ verified by headscale developers.
+
+    **It might be outdated and it might miss necessary steps**.
+
+Headscale can be built from source using the latest version of [Go](https://golang.org) and [Buf](https://buf.build)
+(Protobuf generator). See the [Contributing section in the GitHub
+README](https://github.com/juanfont/headscale#contributing) for more information.
+
+## OpenBSD
+
+### Install from source
+
+```shell
+# Install prerequisites
+pkg_add go git
+
+git clone https://github.com/juanfont/headscale.git
+
+cd headscale
+
+# optionally checkout a release
+# option a. you can find official release at https://github.com/juanfont/headscale/releases/latest
+# option b. get latest tag, this may be a beta release
+latestTag=$(git describe --tags `git rev-list --tags --max-count=1`)
+
+git checkout $latestTag
+
+go build -ldflags="-s -w -X github.com/juanfont/headscale/hscontrol/types.Version=$latestTag" -X github.com/juanfont/headscale/hscontrol/types.GitCommitHash=HASH" github.com/juanfont/headscale
+
+# make it executable
+chmod a+x headscale
+
+# copy it to /usr/local/sbin
+cp headscale /usr/local/sbin
+```
+
+### Install from source via cross compile
+
+```shell
+# Install prerequisites
+# 1. go v1.20+: headscale newer than 0.21 needs go 1.20+ to compile
+# 2. gmake: Makefile in the headscale repo is written in GNU make syntax
+
+git clone https://github.com/juanfont/headscale.git
+
+cd headscale
+
+# optionally checkout a release
+# option a. you can find official release at https://github.com/juanfont/headscale/releases/latest
+# option b. get latest tag, this may be a beta release
+latestTag=$(git describe --tags `git rev-list --tags --max-count=1`)
+
+git checkout $latestTag
+
+make build GOOS=openbsd
+
+# copy headscale to openbsd machine and put it in /usr/local/sbin
+```

docs/setup/requirements.md

@@ -0,0 +1,28 @@
+# Requirements
+
+Headscale should just work as long as the following requirements are met:
+
+- A server with a public IP address for headscale. A dual-stack setup with a public IPv4 and a public IPv6 address is
+  recommended.
+- Headscale is served via HTTPS on port 443[^1].
+- A reasonably modern Linux or BSD based operating system.
+- A dedicated local user account to run headscale.
+- A little bit of command line knowledge to configure and operate headscale.
+
+## Assumptions
+
+The headscale documentation and the provided examples are written with a few assumptions in mind:
+
+- Headscale is running as system service via a dedicated local user `headscale`.
+- The [configuration](../ref/configuration.md) is loaded from `/etc/headscale/config.yaml`.
+- SQLite is used as database.
+- The data directory for headscale (used for private keys, ACLs, SQLite database, …) is located in `/var/lib/headscale`.
+- URLs and values that need to be replaced by the user are either denoted as `<VALUE_TO_CHANGE>` or use placeholder
+  values such as `headscale.example.com`.
+
+Please adjust to your local environment accordingly.
+
+[^1]:
+    The Tailscale client assumes HTTPS on port 443 in certain situations. Serving headscale either via HTTP or via HTTPS
+    on a port other than 443 is possible but sticking with HTTPS on port 443 is strongly recommended for production
+    setups. See [issue 2164](https://github.com/juanfont/headscale/issues/2164) for more information.

docs/setup/upgrade.md

@@ -0,0 +1,10 @@
+# Upgrade an existing installation
+
+Update an existing headscale installation to a new version:
+
+- Read the announcement on the [GitHub releases](https://github.com/juanfont/headscale/releases) page for the new
+  version. It lists the changes of the release along with possible breaking changes.
+- **Create a backup of your database.**
+- Update headscale to the new version, preferably by following the same installation method.
+- Compare and update the [configuration](../ref/configuration.md) file.
+- Restart headscale.

docs/usage/connect/android.md

@@ -0,0 +1,14 @@
+# Connecting an Android client
+
+This documentation has the goal of showing how a user can use the official Android [Tailscale](https://tailscale.com) client with headscale.
+
+## Installation
+
+Install the official Tailscale Android client from the [Google Play Store](https://play.google.com/store/apps/details?id=com.tailscale.ipn) or [F-Droid](https://f-droid.org/packages/com.tailscale.ipn/).
+
+## Configuring the headscale URL
+
+- Open the app and select the settings menu in the upper-right corner
+- Tap on `Accounts`
+- In the kebab menu icon (three dots) in the upper-right corner select `Use an alternate server`
+- Enter your server URL (e.g `https://headscale.example.com`) and follow the instructions

docs/usage/connect/apple.md

@@ -0,0 +1,65 @@
+# Connecting an Apple client
+
+This documentation has the goal of showing how a user can use the official iOS and macOS [Tailscale](https://tailscale.com) clients with headscale.
+
+!!! info "Instructions on your headscale instance"
+
+    An endpoint with information on how to connect your Apple device
+    is also available at `/apple` on your running instance.
+
+## iOS
+
+### Installation
+
+Install the official Tailscale iOS client from the [App Store](https://apps.apple.com/app/tailscale/id1470499037).
+
+### Configuring the headscale URL
+
+- Open the Tailscale app
+- Click the account icon in the top-right corner and select `Log in…`.
+- Tap the top-right options menu button and select `Use custom coordination server`.
+- Enter your instance url (e.g `https://headscale.example.com`)
+- Enter your credentials and log in. Headscale should now be working on your iOS device.
+
+## macOS
+
+### Installation
+
+Choose one of the available [Tailscale clients for macOS](https://tailscale.com/kb/1065/macos-variants) and install it.
+
+### Configuring the headscale URL
+
+#### Command line
+
+Use Tailscale's login command to connect with your headscale instance (e.g `https://headscale.example.com`):
+
+```
+tailscale login --login-server <YOUR_HEADSCALE_URL>
+```
+
+#### GUI
+
+- Option + Click the Tailscale icon in the menu and hover over the Debug menu
+- Under `Custom Login Server`, select `Add Account...`
+- Enter the URL of your headscale instance (e.g `https://headscale.example.com`) and press `Add Account`
+- Follow the login procedure in the browser
+
+## tvOS
+
+### Installation
+
+Install the official Tailscale tvOS client from the [App Store](https://apps.apple.com/app/tailscale/id1470499037).
+
+!!! danger
+
+    **Don't** open the Tailscale App after installation!
+
+### Configuring the headscale URL
+
+- Open Settings (the Apple tvOS settings) > Apps > Tailscale
+- Under `ALTERNATE COORDINATION SERVER URL`, select `URL`
+- Enter the URL of your headscale instance (e.g `https://headscale.example.com`) and press `OK`
+- Return to the tvOS Home screen
+- Open Tailscale
+- Click the button `Install VPN configuration` and confirm the appearing popup by clicking the `Allow` button
+- Scan the QR code and follow the login procedure

docs/usage/connect/windows.md

@@ -0,0 +1,59 @@
+# Connecting a Windows client
+
+This documentation has the goal of showing how a user can use the official Windows [Tailscale](https://tailscale.com) client with headscale.
+
+!!! info "Instructions on your headscale instance"
+
+    An endpoint with information on how to connect your Windows device
+    is also available at `/windows` on your running instance.
+
+## Installation
+
+Download the [Official Windows Client](https://tailscale.com/download/windows) and install it.
+
+## Configuring the headscale URL
+
+Open a Command Prompt or Powershell and use Tailscale's login command to connect with your headscale instance (e.g
+`https://headscale.example.com`):
+
+```
+tailscale login --login-server <YOUR_HEADSCALE_URL>
+```
+
+Follow the instructions in the opened browser window to finish the configuration.
+
+## Troubleshooting
+
+### Unattended mode
+
+By default, Tailscale's Windows client is only running when the user is logged in. If you want to keep Tailscale running
+all the time, please enable "Unattended mode":
+
+- Click on the Tailscale tray icon and select `Preferences`
+- Enable `Run unattended`
+- Confirm the "Unattended mode" message
+
+See also [Keep Tailscale running when I'm not logged in to my computer](https://tailscale.com/kb/1088/run-unattended)
+
+### Failing node registration
+
+If you are seeing repeated messages like:
+
+```
+[GIN] 2022/02/10 - 16:39:34 | 200 |    1.105306ms |       127.0.0.1 | POST     "/machine/redacted"
+```
+
+in your headscale output, turn on `DEBUG` logging and look for:
+
+```
+2022-02-11T00:59:29Z DBG Machine registration has expired. Sending a authurl to register machine=redacted
+```
+
+This typically means that the registry keys above was not set appropriately.
+
+To reset and try again, it is important to do the following:
+
+1. Shut down the Tailscale service (or the client running in the tray)
+2. Delete Tailscale Application data folder, located at `C:\Users\<USERNAME>\AppData\Local\Tailscale` and try to connect again.
+3. Ensure the Windows node is deleted from headscale (to ensure fresh setup)
+4. Start Tailscale on the Windows machine and retry the login.

docs/usage/getting-started.md

@@ -0,0 +1,135 @@
+# Getting started
+
+This page helps you get started with headscale and provides a few usage examples for the headscale command line tool
+`headscale`.
+
+!!! note "Prerequisites"
+
+    * Headscale is installed and running as system service. Read the [setup section](../setup/requirements.md) for
+      installation instructions.
+    * The configuration file exists and is adjusted to suit your environment, see
+      [Configuration](../ref/configuration.md) for details.
+    * Headscale is reachable from the Internet. Verify this by opening client specific setup instructions in your
+      browser, e.g. https://headscale.example.com/windows
+    * The Tailscale client is installed, see [Client and operating system support](../about/clients.md) for more
+      information.
+
+## Getting help
+
+The `headscale` command line tool provides built-in help. To show available commands along with their arguments and
+options, run:
+
+=== "Native"
+
+    ```shell
+    # Show help
+    headscale help
+
+    # Show help for a specific command
+    headscale <COMMAND> --help
+    ```
+
+=== "Container"
+
+    ```shell
+    # Show help
+    docker exec -it headscale \
+      headscale help
+
+    # Show help for a specific command
+    docker exec -it headscale \
+      headscale <COMMAND> --help
+    ```
+
+## Manage headscale users
+
+In headscale, a node (also known as machine or device) is always assigned to a
+headscale user. Such a headscale user may have many nodes assigned to them and
+can be managed with the `headscale users` command. Invoke the built-in help for
+more information: `headscale users --help`.
+
+### Create a headscale user
+
+=== "Native"
+
+    ```shell
+    headscale users create <USER>
+    ```
+
+=== "Container"
+
+    ```shell
+    docker exec -it headscale \
+      headscale users create <USER>
+    ```
+
+### List existing headscale users
+
+=== "Native"
+
+    ```shell
+    headscale users list
+    ```
+
+=== "Container"
+
+    ```shell
+    docker exec -it headscale \
+      headscale users list
+    ```
+
+## Register a node
+
+One has to register a node first to use headscale as coordination with Tailscale. The following examples work for the
+Tailscale client on Linux/BSD operating systems. Alternatively, follow the instructions to connect
+[Android](connect/android.md), [Apple](connect/apple.md) or [Windows](connect/windows.md) devices.
+
+### Normal, interactive login
+
+On a client machine, run the `tailscale up` command and provide the FQDN of your headscale instance as argument:
+
+```shell
+tailscale up --login-server <YOUR_HEADSCALE_URL>
+```
+
+Usually, a browser window with further instructions is opened and contains the value for `<YOUR_MACHINE_KEY>`. Approve
+and register the node on your headscale server:
+
+=== "Native"
+
+    ```shell
+    headscale nodes register --user <USER> --key <YOUR_MACHINE_KEY>
+    ```
+
+=== "Container"
+
+    ```shell
+    docker exec -it headscale \
+      headscale nodes register --user <USER> --key <YOUR_MACHINE_KEY>
+    ```
+
+### Using a preauthkey
+
+It is also possible to generate a preauthkey and register a node non-interactively. First, generate a preauthkey on the
+headscale instance. By default, the key is valid for one hour and can only be used once (see `headscale preauthkeys
+--help` for other options):
+
+=== "Native"
+
+    ```shell
+    headscale preauthkeys create --user <USER>
+    ```
+
+=== "Container"
+
+    ```shell
+    docker exec -it headscale \
+      headscale preauthkeys create --user <USER>
+    ```
+
+The command returns the preauthkey on success which is used to connect a node to the headscale instance via the
+`tailscale up` command:
+
+```shell
+tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>
+```

docs/web-ui.md

@@ -1,15 +0,0 @@
-# Headscale web interface
-
-!!! warning "Community contributions"
-
-    This page contains community contributions. The projects listed here are not
-    maintained by the Headscale authors and are written by community members.
-
-| Name            | Repository Link                                         | Description                                                                 | Status |
-| --------------- | ------------------------------------------------------- | --------------------------------------------------------------------------- | ------ |
-| headscale-webui | [Github](https://github.com/ifargle/headscale-webui)    | A simple Headscale web UI for small-scale deployments.                      | Alpha  |
-| headscale-ui    | [Github](https://github.com/gurucomputing/headscale-ui) | A web frontend for the headscale Tailscale-compatible coordination server   | Alpha  |
-| HeadscaleUi     | [GitHub](https://github.com/simcu/headscale-ui)         | A static headscale admin ui, no backend enviroment required                 | Alpha  |
-| headscale-admin | [Github](https://github.com/GoodiesHQ/headscale-admin)  | Headscale-Admin is meant to be a simple, modern web interface for Headscale | Beta   |
-
-You can ask for support on our dedicated [Discord channel](https://discord.com/channels/896711691637780480/1105842846386356294).

docs/windows-client.md

@@ -1,60 +0,0 @@
-# Connecting a Windows client
-
-## Goal
-
-This documentation has the goal of showing how a user can use the official Windows [Tailscale](https://tailscale.com) client with `headscale`.
-
-## Add registry keys
-
-To make the Windows client behave as expected and to run well with `headscale`, two registry keys **must** be set:
-
-- `HKLM:\SOFTWARE\Tailscale IPN\UnattendedMode` must be set to `always` as a `string` type, to allow Tailscale to run properly in the background
-- `HKLM:\SOFTWARE\Tailscale IPN\LoginURL` must be set to `<YOUR HEADSCALE URL>` as a `string` type, to ensure Tailscale contacts the correct control server.
-
-You can set these using the Windows Registry Editor:
-
-![windows-registry](./images/windows-registry.png)
-
-Or via the following Powershell commands (right click Powershell icon and select "Run as administrator"):
-
-```
-New-Item -Path "HKLM:\SOFTWARE\Tailscale IPN"
-New-ItemProperty -Path 'HKLM:\Software\Tailscale IPN' -Name UnattendedMode -PropertyType String -Value always
-New-ItemProperty -Path 'HKLM:\Software\Tailscale IPN' -Name LoginURL -PropertyType String -Value https://YOUR-HEADSCALE-URL
-```
-
-The Tailscale Windows client has been observed to reset its configuration on logout/reboot and these two keys [resolves that issue](https://github.com/tailscale/tailscale/issues/2798).
-
-For a guide on how to edit registry keys, [check out Computer Hope](https://www.computerhope.com/issues/ch001348.htm).
-
-## Installation
-
-Download the [Official Windows Client](https://tailscale.com/download/windows) and install it.
-
-When the installation has finished, start Tailscale and log in (you might have to click the icon in the system tray).
-
-The log in should open a browser Window and direct you to your `headscale` instance.
-
-## Troubleshooting
-
-If you are seeing repeated messages like:
-
-```
-[GIN] 2022/02/10 - 16:39:34 | 200 |    1.105306ms |       127.0.0.1 | POST     "/machine/redacted"
-```
-
-in your `headscale` output, turn on `DEBUG` logging and look for:
-
-```
-2022-02-11T00:59:29Z DBG Machine registration has expired. Sending a authurl to register machine=redacted
-```
-
-This typically means that the registry keys above was not set appropriately.
-
-To reset and try again, it is important to do the following:
-
-1. Ensure the registry keys from the previous guide is correctly set.
-2. Shut down the Tailscale service (or the client running in the tray)
-3. Delete Tailscale Application data folder, located at `C:\Users\<USERNAME>\AppData\Local\Tailscale` and try to connect again.
-4. Ensure the Windows node is deleted from headscale (to ensure fresh setup)
-5. Start Tailscale on the windows machine and retry the login.

examples/README.md

@@ -1,5 +0,0 @@
-# Examples
-
-This directory contains examples on how to run `headscale` on different platforms.
-
-All examples are provided by the community and they are not verified by the `headscale` authors.

examples/kustomize/.gitignore

@@ -1,2 +0,0 @@
-/**/site
-/**/secrets

examples/kustomize/README.md

@@ -1,100 +0,0 @@
-# Deploying headscale on Kubernetes
-
-**Note:** This is contributed by the community and not verified by the headscale authors.
-
-This directory contains [Kustomize](https://kustomize.io) templates that deploy
-headscale in various configurations.
-
-These templates currently support Rancher k3s. Other clusters may require
-adaptation, especially around volume claims and ingress.
-
-Commands below assume this directory is your current working directory.
-
-# Generate secrets and site configuration
-
-Run `./init.bash` to generate keys, passwords, and site configuration files.
-
-Edit `base/site/public.env`, changing `public-hostname` to the public DNS name
-that will be used for your headscale deployment.
-
-Set `public-proto` to "https" if you're planning to use TLS & Let's Encrypt.
-
-Configure DERP servers by editing `base/site/derp.yaml` if needed.
-
-# Add the image to the registry
-
-You'll somehow need to get `headscale:latest` into your cluster image registry.
-
-An easy way to do this with k3s:
-
-- Reconfigure k3s to use docker instead of containerd (`k3s server --docker`)
-- `docker build -t headscale:latest ..` from here
-
-# Create the namespace
-
-If it doesn't already exist, `kubectl create ns headscale`.
-
-# Deploy headscale
-
-## sqlite
-
-`kubectl -n headscale apply -k ./sqlite`
-
-## postgres
-
-`kubectl -n headscale apply -k ./postgres`
-
-# TLS & Let's Encrypt
-
-Test a staging certificate with your configured DNS name and Let's Encrypt.
-
-`kubectl -n headscale apply -k ./staging-tls`
-
-Replace with a production certificate.
-
-`kubectl -n headscale apply -k ./production-tls`
-
-## Static / custom TLS certificates
-
-Only Let's Encrypt is supported. If you need other TLS settings, modify or patch the ingress.
-
-# Administration
-
-Use the wrapper script to remotely operate headscale to perform administrative
-tasks like creating namespaces, authkeys, etc.
-
-```
-[c@nix-slate:~/Projects/headscale/k8s]$ ./headscale.bash
-
-headscale is an open source implementation of the Tailscale control server
-
-https://github.com/juanfont/headscale
-
-Usage:
-  headscale [command]
-
-Available Commands:
-  help        Help about any command
-  namespace   Manage the namespaces of headscale
-  node        Manage the nodes of headscale
-  preauthkey  Handle the preauthkeys in headscale
-  routes      Manage the routes of headscale
-  serve       Launches the headscale server
-  version     Print the version.
-
-Flags:
-  -h, --help            help for headscale
-  -o, --output string   Output format. Empty for human-readable, 'json' or 'json-line'
-
-Use "headscale [command] --help" for more information about a command.
-
-```
-
-# TODO / Ideas
-
-- Interpolate `email:` option to the ClusterIssuer from site configuration.
-  This probably needs to be done with a transformer, kustomize vars don't seem to work.
-- Add kustomize examples for cloud-native ingress, load balancer
-- CockroachDB for the backend
-- DERP server deployment
-- Tor hidden service

examples/kustomize/base/configmap.yaml

@@ -1,9 +0,0 @@
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: headscale-config
-data:
-  server_url: $(PUBLIC_PROTO)://$(PUBLIC_HOSTNAME)
-  listen_addr: "0.0.0.0:8080"
-  metrics_listen_addr: "127.0.0.1:9090"
-  ephemeral_node_inactivity_timeout: "30m"