Clarify relation with Tailscale

Signed-off-by: ChengenH <hce19970702@gmail.com>

.dockerignore

@@ -0,0 +1,19 @@
+// integration tests are not needed in docker
+// ignoring it let us speed up the integration test
+// development
+integration_test.go
+integration_test/
+!integration_test/etc_embedded_derp/tls/server.crt
+
+Dockerfile*
+docker-compose*
+.dockerignore
+.goreleaser.yml
+.git
+.github
+.gitignore
+README.md
+LICENSE
+.vscode
+
+*.sock

.envrc

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

.github/CODEOWNERS

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

.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+ko_fi: headscale

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,65 @@
+---
+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/config.yml

@@ -0,0 +1,11 @@
+# Issues must have some content
+blank_issues_enabled: false
+
+# Contact links
+contact_links:
+  - name: "headscale usage documentation"
+    url: "https://github.com/juanfont/headscale/blob/main/docs"
+    about: "Find documentation about how to configure and run headscale."
+  - name: "headscale Discord community"
+    url: "https://discord.gg/xGj2TuqyxY"
+    about: "Please ask and answer questions about usage of headscale here."

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,26 @@
+---
+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/pull_request_template.md

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

.github/renovate.json

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

.github/workflows/build.yml

@@ -0,0 +1,71 @@
+name: Build
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions: write-all
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - name: Get changed files
+        id: changed-files
+        uses: dorny/paths-filter@v3
+        with:
+          filters: |
+            files:
+              - '*.nix'
+              - 'go.*'
+              - '**/*.go'
+              - 'integration_test/'
+              - 'config-example.yaml'
+      - uses: DeterminateSystems/nix-installer-action@main
+        if: steps.changed-files.outputs.files == 'true'
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+        if: steps.changed-files.outputs.files == 'true'
+
+      - name: Run build
+        id: build
+        if: steps.changed-files.outputs.files == 'true'
+        run: |
+          nix build |& tee build-result
+          BUILD_STATUS="${PIPESTATUS[0]}"
+
+          OLD_HASH=$(cat build-result | grep specified: | awk -F ':' '{print $2}' | sed 's/ //g')
+          NEW_HASH=$(cat build-result | grep got: | awk -F ':' '{print $2}' | sed 's/ //g')
+
+          echo "OLD_HASH=$OLD_HASH" >> $GITHUB_OUTPUT
+          echo "NEW_HASH=$NEW_HASH" >> $GITHUB_OUTPUT
+
+          exit $BUILD_STATUS
+
+      - name: Nix gosum diverging
+        uses: actions/github-script@v6
+        if: failure() && steps.build.outcome == 'failure'
+        with:
+          github-token: ${{secrets.GITHUB_TOKEN}}
+          script: |
+            github.rest.pulls.createReviewComment({
+              pull_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: 'Nix build failed with wrong gosum, please update "vendorSha256" (${{ steps.build.outputs.OLD_HASH }}) for the "headscale" package in flake.nix with the new SHA: ${{ steps.build.outputs.NEW_HASH }}'
+            })
+
+      - uses: actions/upload-artifact@v4
+        if: steps.changed-files.outputs.files == 'true'
+        with:
+          name: headscale-linux
+          path: result/bin/headscale

.github/workflows/check-tests.yaml

@@ -0,0 +1,41 @@
+name: Check integration tests workflow
+
+on: [pull_request]
+
+concurrency:
+  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  check-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - name: Get changed files
+        id: changed-files
+        uses: dorny/paths-filter@v3
+        with:
+          filters: |
+            files:
+              - '*.nix'
+              - 'go.*'
+              - '**/*.go'
+              - 'integration_test/'
+              - 'config-example.yaml'
+      - uses: DeterminateSystems/nix-installer-action@main
+        if: steps.changed-files.outputs.files == 'true'
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+        if: steps.changed-files.outputs.files == 'true'
+
+      - 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"
+          git diff --exit-code .github/workflows/test-integration.yaml
+
+      - name: Show missing tests
+        if: failure()
+        run: |
+          git diff .github/workflows/test-integration.yaml

.github/workflows/docs-test.yml

@@ -0,0 +1,27 @@
+name: Test documentation build
+
+on: [pull_request]
+
+concurrency:
+  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@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

.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+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-actions-updater.yaml

@@ -0,0 +1,22 @@
+name: GitHub Actions Version Updater
+
+on:
+  schedule:
+    # Automatically run on every Sunday
+    - cron: "0 0 * * 0"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # [Required] Access token with `workflow` scope.
+          token: ${{ secrets.WORKFLOW_SECRET }}
+
+      - name: Run GitHub Actions Version Updater
+        uses: saadmk11/github-actions-version-updater@v0.8.1
+        with:
+          # [Required] Access token with `workflow` scope.
+          token: ${{ secrets.WORKFLOW_SECRET }}

.github/workflows/lint.yml

@@ -0,0 +1,75 @@
+name: Lint
+
+on: [pull_request]
+
+concurrency:
+  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  golangci-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - name: Get changed files
+        id: changed-files
+        uses: dorny/paths-filter@v3
+        with:
+          filters: |
+            files:
+              - '*.nix'
+              - 'go.*'
+              - '**/*.go'
+              - 'integration_test/'
+              - 'config-example.yaml'
+      - uses: DeterminateSystems/nix-installer-action@main
+        if: steps.changed-files.outputs.files == 'true'
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+        if: steps.changed-files.outputs.files == 'true'
+
+      - 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 .
+
+  prettier-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - name: Get changed files
+        id: changed-files
+        uses: dorny/paths-filter@v3
+        with:
+          filters: |
+            files:
+              - '*.nix'
+              - '**/*.md'
+              - '**/*.yml'
+              - '**/*.yaml'
+              - '**/*.ts'
+              - '**/*.js'
+              - '**/*.sass'
+              - '**/*.css'
+              - '**/*.scss'
+              - '**/*.html'
+      - uses: DeterminateSystems/nix-installer-action@main
+        if: steps.changed-files.outputs.files == 'true'
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+        if: steps.changed-files.outputs.files == 'true'
+
+      - name: Prettify code
+        if: steps.changed-files.outputs.files == 'true'
+        run: nix develop --command -- prettier --no-error-on-unmatched-pattern --ignore-unknown --check **/*.{ts,js,md,yaml,yml,sass,css,scss,html}
+
+  proto-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+
+      - name: Buf lint
+        run: nix develop --command -- buf lint proto

.github/workflows/release.yml

@@ -1,30 +1,38 @@
-name: goreleaser
+---
+name: Release
 
 on:
   push:
     tags:
       - "*" # triggers only if push new tag version
+  workflow_dispatch:
 
 jobs:
   goreleaser:
-    runs-on: ubuntu-18.04  # due to CGO we need to user an older version
+    runs-on: ubuntu-latest
     steps:
-      -
-        name: Checkout
-        uses: actions/checkout@v2
+      - name: Checkout
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      -
-        name: Set up Go
-        uses: actions/setup-go@v2
+
+      - name: Login to DockerHub
+        uses: docker/login-action@v3
         with:
-          go-version: 1.16
-      -
-        name: Run GoReleaser
-        uses: goreleaser/goreleaser-action@v2
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
         with:
-          distribution: goreleaser
-          version: latest
-          args: release --rm-dist
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: DeterminateSystems/nix-installer-action@main
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+
+      - name: Run goreleaser
+        run: nix develop --command -- goreleaser release --clean
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/stale.yml

@@ -0,0 +1,23 @@
+name: Close inactive issues
+
+on:
+  schedule:
+    - cron: "30 1 * * *"
+
+jobs:
+  close-issues:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/stale@v9
+        with:
+          days-before-issue-stale: 90
+          days-before-issue-close: 7
+          stale-issue-label: "stale"
+          stale-issue-message: "This issue is stale because it has been open for 90 days with no activity."
+          close-issue-message: "This issue was closed because it has been inactive for 14 days since being marked as stale."
+          days-before-pr-stale: -1
+          days-before-pr-close: -1
+          repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test-integration.yaml

@@ -0,0 +1,114 @@
+name: Integration Tests
+on: [pull_request]
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+jobs:
+  integration-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        test:
+          - TestACLHostsInNetMapTable
+          - TestACLAllowUser80Dst
+          - TestACLDenyAllPort80
+          - TestACLAllowUserDst
+          - TestACLAllowStarDst
+          - TestACLNamedHostsCanReachBySubnet
+          - TestACLNamedHostsCanReach
+          - TestACLDevice1CanAccessDevice2
+          - TestOIDCAuthenticationPingAll
+          - TestOIDCExpireNodesBasedOnTokenExpiry
+          - TestAuthWebFlowAuthenticationPingAll
+          - TestAuthWebFlowLogoutAndRelogin
+          - TestUserCommand
+          - TestPreAuthKeyCommand
+          - TestPreAuthKeyCommandWithoutExpiry
+          - TestPreAuthKeyCommandReusableEphemeral
+          - TestApiKeyCommand
+          - TestNodeTagCommand
+          - TestNodeAdvertiseTagNoACLCommand
+          - TestNodeAdvertiseTagWithACLCommand
+          - TestNodeCommand
+          - TestNodeExpireCommand
+          - TestNodeRenameCommand
+          - TestNodeMoveCommand
+          - TestDERPServerScenario
+          - TestPingAllByIP
+          - TestPingAllByIPPublicDERP
+          - TestAuthKeyLogoutAndRelogin
+          - TestEphemeral
+          - TestPingAllByHostname
+          - TestTaildrop
+          - TestResolveMagicDNS
+          - TestExpireNode
+          - TestNodeOnlineStatus
+          - TestPingAllByIPManyUpDown
+          - TestEnablingRoutes
+          - TestHASubnetRouterFailover
+          - TestEnableDisableAutoApprovedRoute
+          - TestSubnetRouteACL
+          - TestHeadscale
+          - TestCreateTailscale
+          - TestTailscaleNodesJoiningHeadcale
+          - TestSSHOneUserToAll
+          - TestSSHMultipleUsersAllToAll
+          - TestSSHNoSSHConfigured
+          - TestSSHIsBlockedInACL
+          - TestSSHUserOnlyIsolation
+        database: [postgres, sqlite]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+      - name: Get changed files
+        id: changed-files
+        uses: dorny/paths-filter@v3
+        with:
+          filters: |
+            files:
+              - '*.nix'
+              - 'go.*'
+              - '**/*.go'
+              - 'integration_test/'
+              - 'config-example.yaml'
+      - uses: DeterminateSystems/nix-installer-action@main
+        if: steps.changed-files.outputs.files == 'true'
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+        if: steps.changed-files.outputs.files == 'true'
+      - uses: satackey/action-docker-layer-caching@main
+        if: steps.changed-files.outputs.files == 'true'
+        continue-on-error: true
+      - name: Run Integration Test
+        uses: Wandalen/wretry.action@master
+        if: steps.changed-files.outputs.files == 'true'
+        env:
+          USE_POSTGRES: ${{ matrix.database == 'postgres' && '1' || '0' }}
+        with:
+          attempt_limit: 5
+          command: |
+            nix develop --command -- docker run \
+              --tty --rm \
+              --volume ~/.cache/hs-integration-go:/go \
+              --name headscale-test-suite \
+              --volume $PWD:$PWD -w $PWD/integration \
+              --volume /var/run/docker.sock:/var/run/docker.sock \
+              --volume $PWD/control_logs:/tmp/control \
+              --env HEADSCALE_INTEGRATION_POSTGRES=${{env.USE_POSTGRES}} \
+              golang:1 \
+                go run gotest.tools/gotestsum@latest -- ./... \
+                  -failfast \
+                  -timeout 120m \
+                  -parallel 1 \
+                  -run "^${{ matrix.test }}$"
+      - uses: actions/upload-artifact@v4
+        if: always() && steps.changed-files.outputs.files == 'true'
+        with:
+          name: ${{ matrix.test }}-${{matrix.database}}-logs
+          path: "control_logs/*.log"
+      - uses: actions/upload-artifact@v4
+        if: always() && steps.changed-files.outputs.files == 'true'
+        with:
+          name: ${{ matrix.test }}-${{matrix.database}}-pprof
+          path: "control_logs/*.pprof.tar"

.github/workflows/test.yml

@@ -1,45 +1,37 @@
-name: CI
+name: Tests
 
 on: [push, pull_request]
 
+concurrency:
+  group: ${{ github.workflow }}-$${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
 jobs:
-  # The "build" workflow
   test:
-    # The type of runner that the job will run on
     runs-on: ubuntu-latest
 
-    # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-    # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-    - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
 
-    # Install and run golangci-lint as a separate step, it's much faster this
-    # way because this action has caching. It'll get run again in `make lint`
-    # below, but it's still much faster in the end than installing
-    # golangci-lint manually in the `Run lint` step.
-    - uses: golangci/golangci-lint-action@v2
-      with:
-        args: --timeout 2m
-    
-    # Setup Go
-    - name: Setup Go
-      uses: actions/setup-go@v2
-      with:
-        go-version: '1.16.3' # The Go version to download (if necessary) and use.
+      - name: Get changed files
+        id: changed-files
+        uses: dorny/paths-filter@v3
+        with:
+          filters: |
+            files:
+              - '*.nix'
+              - 'go.*'
+              - '**/*.go'
+              - 'integration_test/'
+              - 'config-example.yaml'
 
-    # Install all the dependencies
-    - name: Install dependencies
-      run: |
-        go version
-        go install golang.org/x/lint/golint@latest
-        sudo apt update
-        sudo apt install -y make
-        
-    - name: Run tests
-      run: make test
+      - uses: DeterminateSystems/nix-installer-action@main
+        if: steps.changed-files.outputs.files == 'true'
+      - uses: DeterminateSystems/magic-nix-cache-action@main
+        if: steps.changed-files.outputs.files == 'true'
 
-    - name: Run lint
-      run: make lint
-
-    - name: Run build
-      run: make
+      - name: Run tests
+        if: steps.changed-files.outputs.files == 'true'
+        run: nix develop --check

.github/workflows/update-flake.yml

@@ -0,0 +1,18 @@
+name: update-flake-lock
+on:
+  workflow_dispatch: # allows manual triggering
+  schedule:
+    - cron: "0 0 * * 0" # runs weekly on Sunday at 00:00
+
+jobs:
+  lockfile:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Install Nix
+        uses: DeterminateSystems/nix-installer-action@main
+      - name: Update flake.lock
+        uses: DeterminateSystems/update-flake-lock@main
+        with:
+          pr-title: "Update flake.lock"

.gitignore

@@ -1,3 +1,7 @@
+ignored/
+tailscale/
+.vscode/
+
 # Binaries for programs and plugins
 *.exe
 *.exe~
@@ -12,9 +16,32 @@
 *.out
 
 # Dependency directories (remove the comment below to include it)
-# vendor/
+vendor/
 
+dist/
 /headscale
 config.json
+config.yaml
+derp.yaml
+*.hujson
 *.key
 /db.sqlite
+*.sqlite3
+
+# Exclude Jetbrains Editors
+.idea
+
+test_output/
+control_logs/
+
+# Nix build output
+result
+.direnv/
+
+integration_test/etc/config.dump.yaml
+
+# MkDocs
+.cache
+/site
+
+__debug_bin

.golangci.yaml

@@ -0,0 +1,77 @@
+---
+run:
+  timeout: 10m
+  build-tags:
+    - ts2019
+
+issues:
+  skip-dirs:
+    - gen
+linters:
+  enable-all: true
+  disable:
+    - depguard
+
+    - exhaustivestruct
+    - revive
+    - lll
+    - interfacer
+    - scopelint
+    - maligned
+    - golint
+    - gofmt
+    - 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
+    - nestif
+    - wsl # might be incompatible with gofumpt
+    - testpackage
+    - paralleltest
+
+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

.goreleaser.yml

@@ -1,76 +1,193 @@
-# This is an example .goreleaser.yml file with some sane defaults.
-# Make sure to check the documentation at http://goreleaser.com
+---
 before:
   hooks:
-    - go mod tidy
+    - go mod tidy -compat=1.22
+    - go mod vendor
+
+release:
+  prerelease: auto
+
 builds:
-  - id: darwin-amd64
-    main: ./cmd/headscale/headscale.go
-    mod_timestamp: '{{ .CommitTimestamp }}'
-    goos:
-      - darwin
-    goarch:
-      - amd64
+  - id: headscale
+    main: ./cmd/headscale
+    mod_timestamp: "{{ .CommitTimestamp }}"
     env:
-      - PKG_CONFIG_SYSROOT_DIR=/sysroot/macos/amd64
-      - PKG_CONFIG_PATH=/sysroot/macos/amd64/usr/local/lib/pkgconfig
-      - CC=o64-clang
-      - CXX=o64-clang++
+      - CGO_ENABLED=0
+    targets:
+      - darwin_amd64
+      - darwin_arm64
+      - freebsd_amd64
+      - linux_386
+      - linux_amd64
+      - linux_arm64
+      - linux_arm_5
+      - linux_arm_6
+      - linux_arm_7
     flags:
       - -mod=readonly
     ldflags:
-      - -s -w -X main.version={{.Version}}
-  - id: linux-armhf
-    main: ./cmd/headscale/headscale.go
-    mod_timestamp: '{{ .CommitTimestamp }}'
-    goos:
-      - linux
-    goarch:
-      - arm
-    goarm:
-      - 7
-    env:
-      - CC=arm-linux-gnueabihf-gcc
-      - CXX=arm-linux-gnueabihf-g++
-      - CGO_FLAGS=--sysroot=/sysroot/linux/armhf
-      - CGO_LDFLAGS=--sysroot=/sysroot/linux/armhf
-      - PKG_CONFIG_SYSROOT_DIR=/sysroot/linux/armhf
-      - PKG_CONFIG_PATH=/sysroot/linux/armhf/opt/vc/lib/pkgconfig:/sysroot/linux/armhf/usr/lib/arm-linux-gnueabihf/pkgconfig:/sysroot/linux/armhf/usr/lib/pkgconfig:/sysroot/linux/armhf/usr/local/lib/pkgconfig
-    flags:
-      - -mod=readonly
-    ldflags:
-      - -s -w -X main.version={{.Version}}
-
-
-  - id: linux-amd64
-    env:
-      - CGO_ENABLED=1
-    goos:
-      - linux
-    goarch:
-      - amd64
-    goarm:
-      - 6
-      - 7
-    main: ./cmd/headscale/headscale.go
-    mod_timestamp: '{{ .CommitTimestamp }}'
+      - -s -w -X github.com/juanfont/headscale/cmd/headscale/cli.Version=v{{.Version}}
+    tags:
+      - ts2019
 
 archives:
   - id: golang-cross
-    builds:
-      - darwin-amd64
-      - linux-armhf
-      - linux-amd64
-    name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
+    name_template: '{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ with .Arm }}v{{ . }}{{ end }}{{ with .Mips }}_{{ . }}{{ end }}{{ if not (eq .Amd64 "v1") }}{{ .Amd64 }}{{ end }}'
     format: binary
 
+source:
+  enabled: true
+  name_template: "{{ .ProjectName }}_{{ .Version }}"
+  format: tar.gz
+  files:
+    - "vendor/"
+
+nfpms:
+  # Configure nFPM for .deb and .rpm releases
+  #
+  # See https://nfpm.goreleaser.com/configuration/
+  # and https://goreleaser.com/customization/nfpm/
+  #
+  # Useful tools for debugging .debs:
+  # List file contents: dpkg -c dist/headscale...deb
+  # Package metadata: dpkg --info dist/headscale....deb
+  #
+  - builds:
+      - headscale
+    package_name: headscale
+    priority: optional
+    vendor: headscale
+    maintainer: Kristoffer Dalby <kristoffer@dalby.cc>
+    homepage: https://github.com/juanfont/headscale
+    license: BSD
+    bindir: /usr/bin
+    formats:
+      - deb
+    contents:
+      - src: ./config-example.yaml
+        dst: /etc/headscale/config.yaml
+        type: config|noreplace
+        file_info:
+          mode: 0644
+      - src: ./docs/packaging/headscale.systemd.service
+        dst: /usr/lib/systemd/system/headscale.service
+      - dst: /var/lib/headscale
+        type: dir
+      - dst: /var/run/headscale
+        type: dir
+    scripts:
+      postinstall: ./docs/packaging/postinstall.sh
+      postremove: ./docs/packaging/postremove.sh
+
+kos:
+  - id: ghcr
+    repository: ghcr.io/juanfont/headscale
+
+    # bare tells KO to only use the repository
+    # for tagging and naming the container.
+    bare: true
+    base_image: gcr.io/distroless/base-debian12
+    build: headscale
+    main: ./cmd/headscale
+    env:
+      - CGO_ENABLED=0
+    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: 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
+    bare: true
+    base_image: "debian:12"
+    build: headscale
+    main: ./cmd/headscale
+    env:
+      - CGO_ENABLED=0
+    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 }}"
+      - "{{ .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 }}"
+      - "{{ .Tag }}-debug"
+      - '{{ trimprefix .Tag "v" }}-debug'
+      - "sha-{{ .ShortCommit }}-debug"
+
 checksum:
-  name_template: 'checksums.txt'
+  name_template: "checksums.txt"
 snapshot:
   name_template: "{{ .Tag }}-next"
 changelog:
   sort: asc
   filters:
     exclude:
-      - '^docs:'
-      - '^test:'
+      - "^docs:"
+      - "^test:"

.prettierignore

@@ -0,0 +1,6 @@
+.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

CHANGELOG.md

@@ -0,0 +1,386 @@
+# CHANGELOG
+
+## 0.23.0 (2023-XX-XX)
+
+This release is mainly a code reorganisation and refactoring, significantly improving the maintainability of the codebase. This should allow us to improve further and make it easier for the maintainers to keep on top of the project.
+
+**Please remember to always back up your database between versions**
+
+#### Here is a short summary of the broad topics of changes:
+
+Code has been organised into modules, reducing use of global variables/objects, isolating concerns and “putting the right things in the logical place”.
+
+The new [policy](https://github.com/juanfont/headscale/tree/main/hscontrol/policy) and [mapper](https://github.com/juanfont/headscale/tree/main/hscontrol/mapper) package, containing the ACL/Policy logic and the logic for creating the data served to clients (the network “map”) has been rewritten and improved. This change has allowed us to finish SSH support and add additional tests throughout the code to ensure correctness.
+
+The [“poller”, or streaming logic](https://github.com/juanfont/headscale/blob/main/hscontrol/poll.go) has been rewritten and instead of keeping track of the latest updates, checking at a fixed interval, it now uses go channels, implemented in our new [notifier](https://github.com/juanfont/headscale/tree/main/hscontrol/notifier) package and it allows us to send updates to connected clients immediately. This should both improve performance and potential latency before a client picks up an update.
+
+Headscale now supports sending “delta” updates, thanks to the new mapper and poller logic, allowing us to only inform nodes about new nodes, changed nodes and removed nodes. Previously we sent the entire state of the network every time an update was due.
+
+While we have a pretty good [test harness](https://github.com/search?q=repo%3Ajuanfont%2Fheadscale+path%3A_test.go&type=code) for validating our changes, we have rewritten over [10000 lines of code](https://github.com/juanfont/headscale/compare/b01f1f1867136d9b2d7b1392776eb363b482c525...main) and bugs are expected. We need help testing this release. In addition, while we think the performance should in general be better, there might be regressions in parts of the platform, particularly where we prioritised correctness over speed.
+
+There are also several bugfixes that has been encountered and fixed as part of implementing these changes, particularly
+after improving the test harness as part of adopting [#1460](https://github.com/juanfont/headscale/pull/1460).
+
+### BREAKING
+
+- Code reorganisation, a lot of code has moved, please review the following PRs accordingly [#1473](https://github.com/juanfont/headscale/pull/1473)
+- Change the structure of database configuration, see [config-example.yaml](./config-example.yaml) for the new structure. [#1700](https://github.com/juanfont/headscale/pull/1700)
+  - Old structure has been remove and the configuration _must_ be converted.
+  - Adds additional configuration for PostgreSQL for setting max open, idle conection and idle connection lifetime.
+- API: Machine is now Node [#1553](https://github.com/juanfont/headscale/pull/1553)
+- Remove support for older Tailscale clients [#1611](https://github.com/juanfont/headscale/pull/1611)
+  - The latest supported client is 1.38
+- Headscale checks that _at least_ one DERP is defined at start [#1564](https://github.com/juanfont/headscale/pull/1564)
+  - If no DERP is configured, the server will fail to start, this can be because it cannot load the DERPMap from file or url.
+- Embedded DERP server requires a private key [#1611](https://github.com/juanfont/headscale/pull/1611)
+  - Add a filepath entry to [`derp.server.private_key_path`](https://github.com/juanfont/headscale/blob/b35993981297e18393706b2c963d6db882bba6aa/config-example.yaml#L95)
+- Docker images are now built with goreleaser (ko) [#1716](https://github.com/juanfont/headscale/pull/1716) [#1763](https://github.com/juanfont/headscale/pull/1763)
+  - Entrypoint of container image has changed from shell to headscale, require change from `headscale serve` to `serve`
+  - `/var/lib/headscale` and `/var/run/headscale` is no longer created automatically, see [container docs](./docs/running-headscale-container.md)
+- Prefixes are now defined per v4 and v6 range. [#1756](https://github.com/juanfont/headscale/pull/1756)
+  - `ip_prefixes` option is now `prefixes.v4` and `prefixes.v6`
+  - `prefixes.allocation` can be set to assign IPs at `sequential` or `random`. [#1869](https://github.com/juanfont/headscale/pull/1869)
+
+### Changes
+
+- Use versioned migrations [#1644](https://github.com/juanfont/headscale/pull/1644)
+- Make the OIDC callback page better [#1484](https://github.com/juanfont/headscale/pull/1484)
+- SSH support [#1487](https://github.com/juanfont/headscale/pull/1487)
+- State management has been improved [#1492](https://github.com/juanfont/headscale/pull/1492)
+- Use error group handling to ensure tests actually pass [#1535](https://github.com/juanfont/headscale/pull/1535) based on [#1460](https://github.com/juanfont/headscale/pull/1460)
+- Fix hang on SIGTERM [#1492](https://github.com/juanfont/headscale/pull/1492) taken from [#1480](https://github.com/juanfont/headscale/pull/1480)
+- Send logs to stderr by default [#1524](https://github.com/juanfont/headscale/pull/1524)
+- Fix [TS-2023-006](https://tailscale.com/security-bulletins/#ts-2023-006) security UPnP issue [#1563](https://github.com/juanfont/headscale/pull/1563)
+- Turn off gRPC logging [#1640](https://github.com/juanfont/headscale/pull/1640) fixes [#1259](https://github.com/juanfont/headscale/issues/1259)
+- Added the possibility to manually create a DERP-map entry which can be customized, instead of automatically creating it. [#1565](https://github.com/juanfont/headscale/pull/1565)
+- Add support for deleting api keys [#1702](https://github.com/juanfont/headscale/pull/1702)
+- Add command to backfill IP addresses for nodes missing IPs from configured prefixes. [#1869](https://github.com/juanfont/headscale/pull/1869)
+- Log available update as warning [#1877](https://github.com/juanfont/headscale/pull/1877)
+
+## 0.22.3 (2023-05-12)
+
+### Changes
+
+- Added missing ca-certificates in Docker image [#1463](https://github.com/juanfont/headscale/pull/1463)
+
+## 0.22.2 (2023-05-10)
+
+### Changes
+
+- Add environment flags to enable pprof (profiling) [#1382](https://github.com/juanfont/headscale/pull/1382)
+  - Profiles are continously generated in our integration tests.
+- Fix systemd service file location in `.deb` packages [#1391](https://github.com/juanfont/headscale/pull/1391)
+- Improvements on Noise implementation [#1379](https://github.com/juanfont/headscale/pull/1379)
+- Replace node filter logic, ensuring nodes with access can see eachother [#1381](https://github.com/juanfont/headscale/pull/1381)
+- Disable (or delete) both exit routes at the same time [#1428](https://github.com/juanfont/headscale/pull/1428)
+- Ditch distroless for Docker image, create default socket dir in `/var/run/headscale` [#1450](https://github.com/juanfont/headscale/pull/1450)
+
+## 0.22.1 (2023-04-20)
+
+### Changes
+
+- Fix issue where systemd could not bind to port 80 [#1365](https://github.com/juanfont/headscale/pull/1365)
+
+## 0.22.0 (2023-04-20)
+
+### Changes
+
+- Add `.deb` packages to release process [#1297](https://github.com/juanfont/headscale/pull/1297)
+- Update and simplify the documentation to use new `.deb` packages [#1349](https://github.com/juanfont/headscale/pull/1349)
+- Add 32-bit Arm platforms to release process [#1297](https://github.com/juanfont/headscale/pull/1297)
+- Fix longstanding bug that would prevent "\*" from working properly in ACLs (issue [#699](https://github.com/juanfont/headscale/issues/699)) [#1279](https://github.com/juanfont/headscale/pull/1279)
+- Fix issue where IPv6 could not be used in, or while using ACLs (part of [#809](https://github.com/juanfont/headscale/issues/809)) [#1339](https://github.com/juanfont/headscale/pull/1339)
+- Target Go 1.20 and Tailscale 1.38 for Headscale [#1323](https://github.com/juanfont/headscale/pull/1323)
+
+## 0.21.0 (2023-03-20)
+
+### Changes
+
+- Adding "configtest" CLI command. [#1230](https://github.com/juanfont/headscale/pull/1230)
+- Add documentation on connecting with iOS to `/apple` [#1261](https://github.com/juanfont/headscale/pull/1261)
+- Update iOS compatibility and added documentation for iOS [#1264](https://github.com/juanfont/headscale/pull/1264)
+- Allow to delete routes [#1244](https://github.com/juanfont/headscale/pull/1244)
+
+## 0.20.0 (2023-02-03)
+
+### Changes
+
+- Fix wrong behaviour in exit nodes [#1159](https://github.com/juanfont/headscale/pull/1159)
+- Align behaviour of `dns_config.restricted_nameservers` to tailscale [#1162](https://github.com/juanfont/headscale/pull/1162)
+- Make OpenID Connect authenticated client expiry time configurable [#1191](https://github.com/juanfont/headscale/pull/1191)
+  - defaults to 180 days like Tailscale SaaS
+  - adds option to use the expiry time from the OpenID token for the node (see config-example.yaml)
+- Set ControlTime in Map info sent to nodes [#1195](https://github.com/juanfont/headscale/pull/1195)
+- Populate Tags field on Node updates sent [#1195](https://github.com/juanfont/headscale/pull/1195)
+
+## 0.19.0 (2023-01-29)
+
+### BREAKING
+
+- Rename Namespace to User [#1144](https://github.com/juanfont/headscale/pull/1144)
+  - **BACKUP your database before upgrading**
+- Command line flags previously taking `--namespace` or `-n` will now require `--user` or `-u`
+
+## 0.18.0 (2023-01-14)
+
+### Changes
+
+- Reworked routing and added support for subnet router failover [#1024](https://github.com/juanfont/headscale/pull/1024)
+- Added an OIDC AllowGroups Configuration options and authorization check [#1041](https://github.com/juanfont/headscale/pull/1041)
+- Set `db_ssl` to false by default [#1052](https://github.com/juanfont/headscale/pull/1052)
+- Fix duplicate nodes due to incorrect implementation of the protocol [#1058](https://github.com/juanfont/headscale/pull/1058)
+- Report if a machine is online in CLI more accurately [#1062](https://github.com/juanfont/headscale/pull/1062)
+- Added config option for custom DNS records [#1035](https://github.com/juanfont/headscale/pull/1035)
+- Expire nodes based on OIDC token expiry [#1067](https://github.com/juanfont/headscale/pull/1067)
+- Remove ephemeral nodes on logout [#1098](https://github.com/juanfont/headscale/pull/1098)
+- Performance improvements in ACLs [#1129](https://github.com/juanfont/headscale/pull/1129)
+- OIDC client secret can be passed via a file [#1127](https://github.com/juanfont/headscale/pull/1127)
+
+## 0.17.1 (2022-12-05)
+
+### Changes
+
+- Correct typo on macOS standalone profile link [#1028](https://github.com/juanfont/headscale/pull/1028)
+- Update platform docs with Fast User Switching [#1016](https://github.com/juanfont/headscale/pull/1016)
+
+## 0.17.0 (2022-11-26)
+
+### BREAKING
+
+- `noise.private_key_path` has been added and is required for the new noise protocol.
+- Log level option `log_level` was moved to a distinct `log` config section and renamed to `level` [#768](https://github.com/juanfont/headscale/pull/768)
+- Removed Alpine Linux container image [#962](https://github.com/juanfont/headscale/pull/962)
+
+### Important Changes
+
+- Added support for Tailscale TS2021 protocol [#738](https://github.com/juanfont/headscale/pull/738)
+- Add experimental support for [SSH ACL](https://tailscale.com/kb/1018/acls/#tailscale-ssh) (see docs for limitations) [#847](https://github.com/juanfont/headscale/pull/847)
+  - Please note that this support should be considered _partially_ implemented
+  - SSH ACLs status:
+    - Support `accept` and `check` (SSH can be enabled and used for connecting and authentication)
+    - Rejecting connections **are not supported**, meaning that if you enable SSH, then assume that _all_ `ssh` connections **will be allowed**.
+    - If you decied to try this feature, please carefully managed permissions by blocking port `22` with regular ACLs or do _not_ set `--ssh` on your clients.
+    - We are currently improving our testing of the SSH ACLs, help us get an overview by testing and giving feedback.
+  - This feature should be considered dangerous and it is disabled by default. Enable by setting `HEADSCALE_EXPERIMENTAL_FEATURE_SSH=1`.
+
+### Changes
+
+- Add ability to specify config location via env var `HEADSCALE_CONFIG` [#674](https://github.com/juanfont/headscale/issues/674)
+- Target Go 1.19 for Headscale [#778](https://github.com/juanfont/headscale/pull/778)
+- Target Tailscale v1.30.0 to build Headscale [#780](https://github.com/juanfont/headscale/pull/780)
+- Give a warning when running Headscale with reverse proxy improperly configured for WebSockets [#788](https://github.com/juanfont/headscale/pull/788)
+- Fix subnet routers with Primary Routes [#811](https://github.com/juanfont/headscale/pull/811)
+- Added support for JSON logs [#653](https://github.com/juanfont/headscale/issues/653)
+- Sanitise the node key passed to registration url [#823](https://github.com/juanfont/headscale/pull/823)
+- Add support for generating pre-auth keys with tags [#767](https://github.com/juanfont/headscale/pull/767)
+- Add support for evaluating `autoApprovers` ACL entries when a machine is registered [#763](https://github.com/juanfont/headscale/pull/763)
+- Add config flag to allow Headscale to start if OIDC provider is down [#829](https://github.com/juanfont/headscale/pull/829)
+- Fix prefix length comparison bug in AutoApprovers route evaluation [#862](https://github.com/juanfont/headscale/pull/862)
+- Random node DNS suffix only applied if names collide in namespace. [#766](https://github.com/juanfont/headscale/issues/766)
+- Remove `ip_prefix` configuration option and warning [#899](https://github.com/juanfont/headscale/pull/899)
+- Add `dns_config.override_local_dns` option [#905](https://github.com/juanfont/headscale/pull/905)
+- Fix some DNS config issues [#660](https://github.com/juanfont/headscale/issues/660)
+- Make it possible to disable TS2019 with build flag [#928](https://github.com/juanfont/headscale/pull/928)
+- Fix OIDC registration issues [#960](https://github.com/juanfont/headscale/pull/960) and [#971](https://github.com/juanfont/headscale/pull/971)
+- Add support for specifying NextDNS DNS-over-HTTPS resolver [#940](https://github.com/juanfont/headscale/pull/940)
+- Make more sslmode available for postgresql connection [#927](https://github.com/juanfont/headscale/pull/927)
+
+## 0.16.4 (2022-08-21)
+
+### Changes
+
+- Add ability to connect to PostgreSQL over TLS/SSL [#745](https://github.com/juanfont/headscale/pull/745)
+- Fix CLI registration of expired machines [#754](https://github.com/juanfont/headscale/pull/754)
+
+## 0.16.3 (2022-08-17)
+
+### Changes
+
+- Fix issue with OIDC authentication [#747](https://github.com/juanfont/headscale/pull/747)
+
+## 0.16.2 (2022-08-14)
+
+### Changes
+
+- Fixed bugs in the client registration process after migration to NodeKey [#735](https://github.com/juanfont/headscale/pull/735)
+
+## 0.16.1 (2022-08-12)
+
+### Changes
+
+- Updated dependencies (including the library that lacked armhf support) [#722](https://github.com/juanfont/headscale/pull/722)
+- Fix missing group expansion in function `excludeCorretlyTaggedNodes` [#563](https://github.com/juanfont/headscale/issues/563)
+- Improve registration protocol implementation and switch to NodeKey as main identifier [#725](https://github.com/juanfont/headscale/pull/725)
+- Add ability to connect to PostgreSQL via unix socket [#734](https://github.com/juanfont/headscale/pull/734)
+
+## 0.16.0 (2022-07-25)
+
+**Note:** Take a backup of your database before upgrading.
+
+### BREAKING
+
+- Old ACL syntax is no longer supported ("users" & "ports" -> "src" & "dst"). Please check [the new syntax](https://tailscale.com/kb/1018/acls/).
+
+### Changes
+
+- **Drop** armhf (32-bit ARM) support. [#609](https://github.com/juanfont/headscale/pull/609)
+- Headscale fails to serve if the ACL policy file cannot be parsed [#537](https://github.com/juanfont/headscale/pull/537)
+- Fix labels cardinality error when registering unknown pre-auth key [#519](https://github.com/juanfont/headscale/pull/519)
+- Fix send on closed channel crash in polling [#542](https://github.com/juanfont/headscale/pull/542)
+- Fixed spurious calls to setLastStateChangeToNow from ephemeral nodes [#566](https://github.com/juanfont/headscale/pull/566)
+- Add command for moving nodes between namespaces [#362](https://github.com/juanfont/headscale/issues/362)
+- Added more configuration parameters for OpenID Connect (scopes, free-form paramters, domain and user allowlist)
+- Add command to set tags on a node [#525](https://github.com/juanfont/headscale/issues/525)
+- Add command to view tags of nodes [#356](https://github.com/juanfont/headscale/issues/356)
+- Add --all (-a) flag to enable routes command [#360](https://github.com/juanfont/headscale/issues/360)
+- Fix issue where nodes was not updated across namespaces [#560](https://github.com/juanfont/headscale/pull/560)
+- Add the ability to rename a nodes name [#560](https://github.com/juanfont/headscale/pull/560)
+  - Node DNS names are now unique, a random suffix will be added when a node joins
+  - This change contains database changes, remember to **backup** your database before upgrading
+- Add option to enable/disable logtail (Tailscale's logging infrastructure) [#596](https://github.com/juanfont/headscale/pull/596)
+  - This change disables the logs by default
+- Use [Prometheus]'s duration parser, supporting days (`d`), weeks (`w`) and years (`y`) [#598](https://github.com/juanfont/headscale/pull/598)
+- Add support for reloading ACLs with SIGHUP [#601](https://github.com/juanfont/headscale/pull/601)
+- Use new ACL syntax [#618](https://github.com/juanfont/headscale/pull/618)
+- Add -c option to specify config file from command line [#285](https://github.com/juanfont/headscale/issues/285) [#612](https://github.com/juanfont/headscale/pull/601)
+- Add configuration option to allow Tailscale clients to use a random WireGuard port. [kb/1181/firewalls](https://tailscale.com/kb/1181/firewalls) [#624](https://github.com/juanfont/headscale/pull/624)
+- Improve obtuse UX regarding missing configuration (`ephemeral_node_inactivity_timeout` not set) [#639](https://github.com/juanfont/headscale/pull/639)
+- Fix nodes being shown as 'offline' in `tailscale status` [#648](https://github.com/juanfont/headscale/pull/648)
+- Improve shutdown behaviour [#651](https://github.com/juanfont/headscale/pull/651)
+- Drop Gin as web framework in Headscale [648](https://github.com/juanfont/headscale/pull/648) [677](https://github.com/juanfont/headscale/pull/677)
+- Make tailnet node updates check interval configurable [#675](https://github.com/juanfont/headscale/pull/675)
+- Fix regression with HTTP API [#684](https://github.com/juanfont/headscale/pull/684)
+- nodes ls now print both Hostname and Name(Issue [#647](https://github.com/juanfont/headscale/issues/647) PR [#687](https://github.com/juanfont/headscale/pull/687))
+
+## 0.15.0 (2022-03-20)
+
+**Note:** Take a backup of your database before upgrading.
+
+### BREAKING
+
+- Boundaries between Namespaces has been removed and all nodes can communicate by default [#357](https://github.com/juanfont/headscale/pull/357)
+  - To limit access between nodes, use [ACLs](./docs/acls.md).
+- `/metrics` is now a configurable host:port endpoint: [#344](https://github.com/juanfont/headscale/pull/344). You must update your `config.yaml` file to include:
+  ```yaml
+  metrics_listen_addr: 127.0.0.1:9090
+  ```
+
+### Features
+
+- Add support for writing ACL files with YAML [#359](https://github.com/juanfont/headscale/pull/359)
+- Users can now use emails in ACL's groups [#372](https://github.com/juanfont/headscale/issues/372)
+- Add shorthand aliases for commands and subcommands [#376](https://github.com/juanfont/headscale/pull/376)
+- Add `/windows` endpoint for Windows configuration instructions + registry file download [#392](https://github.com/juanfont/headscale/pull/392)
+- Added embedded DERP (and STUN) server into Headscale [#388](https://github.com/juanfont/headscale/pull/388)
+
+### Changes
+
+- Fix a bug were the same IP could be assigned to multiple hosts if joined in quick succession [#346](https://github.com/juanfont/headscale/pull/346)
+- Simplify the code behind registration of machines [#366](https://github.com/juanfont/headscale/pull/366)
+  - Nodes are now only written to database if they are registrated successfully
+- Fix a limitation in the ACLs that prevented users to write rules with `*` as source [#374](https://github.com/juanfont/headscale/issues/374)
+- Reduce the overhead of marshal/unmarshal for Hostinfo, routes and endpoints by using specific types in Machine [#371](https://github.com/juanfont/headscale/pull/371)
+- Apply normalization function to FQDN on hostnames when hosts registers and retrieve informations [#363](https://github.com/juanfont/headscale/issues/363)
+- Fix a bug that prevented the use of `tailscale logout` with OIDC [#508](https://github.com/juanfont/headscale/issues/508)
+- Added Tailscale repo HEAD and unstable releases channel to the integration tests targets [#513](https://github.com/juanfont/headscale/pull/513)
+
+## 0.14.0 (2022-02-24)
+
+**UPCOMING ### BREAKING
+From the **next\*\* version (`0.15.0`), all machines will be able to communicate regardless of
+if they are in the same namespace. This means that the behaviour currently limited to ACLs
+will become default. From version `0.15.0`, all limitation of communications must be done
+with ACLs.
+
+This is a part of aligning `headscale`'s behaviour with Tailscale's upstream behaviour.
+
+### BREAKING
+
+- ACLs have been rewritten to align with the bevaviour Tailscale Control Panel provides. **NOTE:** This is only active if you use ACLs
+  - Namespaces are now treated as Users
+  - All machines can communicate with all machines by default
+  - Tags should now work correctly and adding a host to Headscale should now reload the rules.
+  - The documentation have a [fictional example](docs/acls.md) that should cover some use cases of the ACLs features
+
+### Features
+
+- Add support for configurable mTLS [docs](docs/tls.md#configuring-mutual-tls-authentication-mtls) [#297](https://github.com/juanfont/headscale/pull/297)
+
+### Changes
+
+- Remove dependency on CGO (switch from CGO SQLite to pure Go) [#346](https://github.com/juanfont/headscale/pull/346)
+
+**0.13.0 (2022-02-18):**
+
+### Features
+
+- Add IPv6 support to the prefix assigned to namespaces
+- Add API Key support
+  - Enable remote control of `headscale` via CLI [docs](docs/remote-cli.md)
+  - Enable HTTP API (beta, subject to change)
+- OpenID Connect users will be mapped per namespaces
+  - Each user will get its own namespace, created if it does not exist
+  - `oidc.domain_map` option has been removed
+  - `strip_email_domain` option has been added (see [config-example.yaml](./config-example.yaml))
+
+### Changes
+
+- `ip_prefix` is now superseded by `ip_prefixes` in the configuration [#208](https://github.com/juanfont/headscale/pull/208)
+- Upgrade `tailscale` (1.20.4) and other dependencies to latest [#314](https://github.com/juanfont/headscale/pull/314)
+- fix swapped machine<->namespace labels in `/metrics` [#312](https://github.com/juanfont/headscale/pull/312)
+- remove key-value based update mechanism for namespace changes [#316](https://github.com/juanfont/headscale/pull/316)
+
+**0.12.4 (2022-01-29):**
+
+### Changes
+
+- Make gRPC Unix Socket permissions configurable [#292](https://github.com/juanfont/headscale/pull/292)
+- Trim whitespace before reading Private Key from file [#289](https://github.com/juanfont/headscale/pull/289)
+- Add new command to generate a private key for `headscale` [#290](https://github.com/juanfont/headscale/pull/290)
+- Fixed issue where hosts deleted from control server may be written back to the database, as long as they are connected to the control server [#278](https://github.com/juanfont/headscale/pull/278)
+
+## 0.12.3 (2022-01-13)
+
+### Changes
+
+- Added Alpine container [#270](https://github.com/juanfont/headscale/pull/270)
+- Minor updates in dependencies [#271](https://github.com/juanfont/headscale/pull/271)
+
+## 0.12.2 (2022-01-11)
+
+Happy New Year!
+
+### Changes
+
+- Fix Docker release [#258](https://github.com/juanfont/headscale/pull/258)
+- Rewrite main docs [#262](https://github.com/juanfont/headscale/pull/262)
+- Improve Docker docs [#263](https://github.com/juanfont/headscale/pull/263)
+
+## 0.12.1 (2021-12-24)
+
+(We are skipping 0.12.0 to correct a mishap done weeks ago with the version tagging)
+
+### BREAKING
+
+- Upgrade to Tailscale 1.18 [#229](https://github.com/juanfont/headscale/pull/229)
+  - This change requires a new format for private key, private keys are now generated automatically:
+    1. Delete your current key
+    2. Restart `headscale`, a new key will be generated.
+    3. Restart all Tailscale clients to fetch the new key
+
+### Changes
+
+- Unify configuration example [#197](https://github.com/juanfont/headscale/pull/197)
+- Add stricter linting and formatting [#223](https://github.com/juanfont/headscale/pull/223)
+
+### Features
+
+- Add gRPC and HTTP API (HTTP API is currently disabled) [#204](https://github.com/juanfont/headscale/pull/204)
+- Use gRPC between the CLI and the server [#206](https://github.com/juanfont/headscale/pull/206), [#212](https://github.com/juanfont/headscale/pull/212)
+- Beta OpenID Connect support [#126](https://github.com/juanfont/headscale/pull/126), [#227](https://github.com/juanfont/headscale/pull/227)
+
+## 0.11.0 (2021-10-25)
+
+### BREAKING
+
+- Make headscale fetch DERP map from URL and file [#196](https://github.com/juanfont/headscale/pull/196)

CODE_OF_CONDUCT.md

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

Dockerfile

@@ -1,12 +0,0 @@
-FROM golang:latest AS build
-ENV GOPATH /go
-COPY . /go/src/headscale
-WORKDIR /go/src/headscale
-RUN go install -a -ldflags="-extldflags=-static" -tags netgo,sqlite_omit_load_extension ./cmd/headscale
-RUN test -e /go/bin/headscale
-
-FROM scratch
-COPY --from=build /go/bin/headscale /go/bin/headscale
-ENV TZ UTC
-EXPOSE 8080/tcp
-ENTRYPOINT ["/go/bin/headscale"]

Dockerfile.debug

@@ -0,0 +1,33 @@
+# This Dockerfile and the images produced are for testing headscale,
+# and are in no way endorsed by Headscale's maintainers as an
+# official nor supported release or distribution.
+
+FROM docker.io/golang:1.22-bookworm AS build
+ARG VERSION=dev
+ENV GOPATH /go
+WORKDIR /go/src/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
+
+# Need to reset the entrypoint or everything will run as a busybox script
+ENTRYPOINT []
+EXPOSE 8080/tcp
+CMD ["headscale"]

Dockerfile.tailscale-HEAD

@@ -0,0 +1,21 @@
+# This Dockerfile and the images produced are for testing headscale,
+# and are in no way endorsed by Headscale's maintainers as an
+# official nor supported release or distribution.
+
+FROM golang:latest
+
+RUN apt-get update \
+    && apt-get install -y dnsutils git iptables ssh ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN useradd --shell=/bin/bash --create-home ssh-it-user
+
+RUN git clone https://github.com/tailscale/tailscale.git
+
+WORKDIR /go/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/

Makefile

@@ -1,24 +1,53 @@
 # Calculate version
-version = $(shell ./scripts/version-at-commit.sh)
+version ?= $(shell git describe --always --tags --dirty)
+
+rwildcard=$(foreach d,$(wildcard $1*),$(call rwildcard,$d/,$2) $(filter $(subst *,%,$2),$d))
+
+# Determine if OS supports pie
+GOOS ?= $(shell uname | tr '[:upper:]' '[:lower:]')
+ifeq ($(filter $(GOOS), openbsd netbsd soloaris plan9), )
+	pieflags = -buildmode=pie
+else
+endif
+
+# GO_SOURCES = $(wildcard *.go)
+# PROTO_SOURCES = $(wildcard **/*.proto)
+GO_SOURCES = $(call rwildcard,,*.go)
+PROTO_SOURCES = $(call rwildcard,,*.proto)
+
 
 build:
-	go build -ldflags "-s -w -X main.version=$(version)" cmd/headscale/headscale.go
+	nix build
 
 dev: lint test build
 
 test:
-	@go test -coverprofile=coverage.out ./...
+	gotestsum -- -short -coverprofile=coverage.out ./...
 
-coverprofile_func:
-	go tool cover -func=coverage.out
-
-coverprofile_html:
-	go tool cover -html=coverage.out
+test_integration:
+	docker run \
+		-t --rm \
+		-v ~/.cache/hs-integration-go:/go \
+		--name headscale-test-suite \
+		-v $$PWD:$$PWD -w $$PWD/integration \
+		-v /var/run/docker.sock:/var/run/docker.sock \
+		golang:1 \
+		go run gotest.tools/gotestsum@latest -- -failfast ./... -timeout 120m -parallel 8
 
 lint:
-	golint
-	golangci-lint run
+	golangci-lint run --fix --timeout 10m
+
+fmt:
+	prettier --write '**/**.{ts,js,md,yaml,yml,sass,css,scss,html}'
+	golines --max-len=88 --base-formatter=gofumpt -w $(GO_SOURCES)
+	clang-format -style="{BasedOnStyle: Google, IndentWidth: 4, AlignConsecutiveDeclarations: true, AlignConsecutiveAssignments: true, ColumnLimit: 0}" -i $(PROTO_SOURCES)
+
+proto-lint:
+	cd proto/ && go run github.com/bufbuild/buf/cmd/buf lint
 
 compress: build
 	upx --brute headscale
 
+generate:
+	rm -rf gen
+	buf generate proto

README.md

@@ -1,201 +1,182 @@
-# Headscale
+![headscale logo](./docs/logo/headscale3_header_stacked_left.png)
 
-[![Join the chat at https://gitter.im/headscale-dev/community](https://badges.gitter.im/headscale-dev/community.svg)](https://gitter.im/headscale-dev/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) ![ci](https://github.com/juanfont/headscale/actions/workflows/test.yml/badge.svg)
+![ci](https://github.com/juanfont/headscale/actions/workflows/test.yml/badge.svg)
 
-An open source, self-hosted implementation of the Tailscale coordination server.
+An open source, self-hosted implementation of the Tailscale control server.
 
-## Overview
+Join our [Discord](https://discord.gg/c84AZQhmpx) server for a chat.
 
-Tailscale is [a modern VPN](https://tailscale.com/) built on top of [Wireguard](https://www.wireguard.com/). It [works like an overlay network](https://tailscale.com/blog/how-tailscale-works/) between the computers of your networks - using all kinds of [NAT traversal sorcery](https://tailscale.com/blog/how-nat-traversal-works/).
+**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.
 
-Everything in Tailscale is Open Source, except the GUI clients for proprietary OS (Windows and macOS/iOS), and the 'coordination/control server'.
+## What is Tailscale
 
-The control server works as an exchange point of Wireguard public keys for the nodes in the Tailscale network. It also assigns the IP addresses of the clients, creates the boundaries between each user, enables sharing machines between users, and exposes the advertised routes of your nodes.
+Tailscale is [a modern VPN](https://tailscale.com/) built on top of
+[Wireguard](https://www.wireguard.com/).
+It [works like an overlay network](https://tailscale.com/blog/how-tailscale-works/)
+between the computers of your networks - using
+[NAT traversal](https://tailscale.com/blog/how-nat-traversal-works/).
 
-Headscale implements this coordination server.
+Everything in Tailscale is Open Source, except the GUI clients for proprietary OS
+(Windows and macOS/iOS), and the control server.
 
-## Status
+The control server works as an exchange point of Wireguard public keys for the
+nodes in the Tailscale network. It assigns the IP addresses of the clients,
+creates the boundaries between each user, enables sharing machines between users,
+and exposes the advertised routes of your nodes.
 
-- [x] Base functionality (nodes can communicate with each other)
-- [x] Node registration through the web flow
-- [x] Network changes are relied to the nodes
-- [x] Namespace support (~equivalent to multi-user in Tailscale.com)
-- [x] Routing (advertise & accept, including exit nodes)
-- [x] Node registration via pre-auth keys (including reusable keys, and ephemeral node support)
-- [X] JSON-formatted output
-- [X] ACLs
-- [X] Support for alternative IP ranges in the tailnets (default Tailscale's 100.64.0.0/10)
-- [ ] Share nodes between ~~users~~ namespaces 
-- [ ] DNS
+A [Tailscale network (tailnet)](https://tailscale.com/kb/1136/tailnet/) is private
+network which Tailscale assigns to a user in terms of private users or an
+organisation.
 
+## Design goal
 
-## Roadmap 🤷
+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.
 
-We are now focusing on adding integration tests with the official clients. 
+## Supporting Headscale
 
-Suggestions/PRs welcomed!
+If you like `headscale` and find it useful, there is a sponsorship and donation
+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)
 
-## Running it
+## Client OS support
 
-1. Download the Headscale binary https://github.com/juanfont/headscale/releases, and place it somewhere in your PATH
- 
+| 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)                          |
 
-2. (Optional, you can also use SQLite) Get yourself a PostgreSQL DB running
+## Running headscale
 
-  ```shell
-  docker run --name headscale -e POSTGRES_DB=headscale -e \
-    POSTGRES_USER=foo -e POSTGRES_PASSWORD=bar -p 5432:5432 -d postgres
-  ```
+**Please note that we do not support nor encourage the use of reverse proxies
+and container to run Headscale.**
 
-3. Set some stuff up (headscale Wireguard keys & the config.json file)
-  ```shell
-  wg genkey > private.key
-  wg pubkey < private.key > public.key  # not needed
+Please have a look at the [`documentation`](https://headscale.net/).
 
-  # Postgres
-  cp config.json.postgres.example config.json
-  # or
-  # SQLite
-  cp config.json.sqlite.example config.json
-  ```
-
-4. Create a namespace (a namespace is a 'tailnet', a group of Tailscale nodes that can talk to each other)
-  ```shell
-  headscale namespaces create myfirstnamespace
-  ```
-
-5. Run the server
-  ```shell
-  headscale serve
-  ```
-
-6. If you used tailscale.com before in your nodes, make sure you clear the tailscaled data folder
- ```shell
- systemctl stop tailscaled
- rm -fr /var/lib/tailscale
- systemctl start tailscaled 
- ```
-
-7. Add your first machine
-  ```shell
-  tailscale up -login-server YOUR_HEADSCALE_URL
-  ```
-
-8. Navigate to the URL you will get with `tailscale up`, where you'll find your machine key.
-
-9. In the server, register your machine to a namespace with the CLI
-  ```shell
-  headscale -n myfirstnamespace node register YOURMACHINEKEY
-  ```
-
-Alternatively, you can use Auth Keys to register your machines:
-
-1. Create an authkey
-    ```shell
-    headscale -n myfirstnamespace preauthkeys create --reusable --expiration 24h
-    ```
-
-2. Use the authkey from your machine to register it
-   ```shell
-   tailscale up -login-server YOUR_HEADSCALE_URL --authkey YOURAUTHKEY
-   ```
-
-If you create an authkey with the `--ephemeral` flag, that key will create ephemeral nodes. This implies that `--reusable` is true.
-
-Please bear in mind that all the commands from headscale support adding `-o json` or `-o json-line`  to get a nicely JSON-formatted output.
-
-
-## Configuration reference
-
-Headscale's configuration file is named `config.json` or `config.yaml`. Headscale will look for it in `/etc/headscale`, `~/.headscale` and finally the directory from where the Headscale binary is executed.
-
-```
-    "server_url": "http://192.168.1.12:8080",
-    "listen_addr": "0.0.0.0:8080",
-    "ip_prefix": "100.64.0.0/10"
-```
-
-`server_url` is the external URL via which Headscale is reachable. `listen_addr` is the IP address and port the Headscale program should listen on. `ip_prefix` is the IP prefix (range) in which IP addresses for nodes will be allocated (default 100.64.0.0/10, e.g., 192.168.4.0/24, 10.0.0.0/8)
-
-```
-    "private_key_path": "private.key",
-```
-
-`private_key_path` is the path to the Wireguard private key. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.
-
-```
-    "derp_map_path": "derp.yaml",
-```
-
-`derp_map_path` is the path to the [DERP](https://pkg.go.dev/tailscale.com/derp) map file. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.
-
-```
-    "ephemeral_node_inactivity_timeout": "30m",
-```
-
-`ephemeral_node_inactivity_timeout` is the timeout after which inactive ephemeral node records will be deleted from the database. The default is 30 minutes. This value must be higher than 65 seconds (the keepalive timeout for the HTTP long poll is 60 seconds, plus a few seconds to avoid race conditions).
-
-```
-    "db_host": "localhost",
-    "db_port": 5432,
-    "db_name": "headscale",
-    "db_user": "foo",
-    "db_pass": "bar",
-```
-
-The fields starting with `db_` are used for the PostgreSQL connection information.
-
-
-### Running the service via TLS (optional)
-
-```
-    "tls_cert_path": ""
-    "tls_key_path": ""
-```
-
-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.
-
-```
-    "tls_letsencrypt_hostname": "",
-    "tls_letsencrypt_listen": ":http",
-    "tls_letsencrypt_cache_dir": ".cache",
-    "tls_letsencrypt_challenge_type": "HTTP-01",
-```
-
-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. The certificate will automatically be renewed as needed.
-
-#### Challenge type HTTP-01
-
-The default challenge type `HTTP-01` requires that Headscale is reachable on port 80 for the Let's Encrypt automated validation, in addition to whatever port is configured in `listen_addr`. By default, Headscale listens on port 80 on all local IPs for Let's Encrypt automated validation.
-
-If you need to change the ip and/or port used by Headscale for the Let's Encrypt validation process, set `tls_letsencrypt_listen` to the appropriate value. This can be handy if you are running Headscale as a non-root user (or can't run `setcap`). Keep in mind, however, that Let's Encrypt will _only_ connect to port 80 for the validation callback, so if you change `tls_letsencrypt_listen` you will also need to configure something else (e.g. a firewall rule) to forward the traffic from port 80 to the ip:port combination specified in `tls_letsencrypt_listen`.
-
-#### Challenge type TLS-ALPN-01
-
-Alternatively, `tls_letsencrypt_challenge_type` can be set to `TLS-ALPN-01`. In this configuration, Headscale listens on the ip:port combination defined in `listen_addr`. Let's Encrypt will _only_ connect to port 443 for the validation callback, so if `listen_addr` is not set to port 443, something else (e.g. a firewall rule) will be required to forward the traffic from port 443 to the ip:port combination specified in `listen_addr`.
-
-### Policy ACLs
-
-Headscale implements the same policy ACLs as Tailscale.com, adapted to the self-hosted environment. 
-
-For instance, instead of referring to users when defining groups you must
- use namespaces (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.
+## Talks
 
+- Fosdem 2023 (video): [Headscale: How we are using integration testing to reimplement Tailscale](https://fosdem.org/2023/schedule/event/goheadscale/)
+  - presented by Juan Font Alonso and Kristoffer Dalby
 
 ## Disclaimer
 
-1. We have nothing to do with Tailscale, or Tailscale Inc.
-2. The purpose of writing this was to learn how Tailscale works.
+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.
 
-## More on Tailscale
+## Contributing
 
-- https://tailscale.com/blog/how-tailscale-works/
-- https://tailscale.com/blog/tailscale-key-management/
-- https://tailscale.com/blog/an-unlikely-database-migration/
+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.
+
+### Requirements
+
+To contribute to headscale you would need the lastest version of [Go](https://golang.org)
+and [Buf](https://buf.build)(Protobuf generator).
+
+We recommend using [Nix](https://nixos.org/) to setup a development environment. This can
+be done with `nix develop`, which will install the tools and give you a shell.
+This guarantees that you will have the same dev env as `headscale` maintainers.
+
+### Code style
+
+To ensure we have some consistency with a growing number of contributions,
+this project has adopted linting and style/formatting rules:
+
+The **Go** code is linted with [`golangci-lint`](https://golangci-lint.run) and
+formatted with [`golines`](https://github.com/segmentio/golines) (width 88) and
+[`gofumpt`](https://github.com/mvdan/gofumpt).
+Please configure your editor to run the tools while developing and make sure to
+run `make lint` and `make fmt` before committing any code.
+
+The **Proto** code is linted with [`buf`](https://docs.buf.build/lint/overview) and
+formatted with [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html).
+
+The **rest** (Markdown, YAML, etc) is formatted with [`prettier`](https://prettier.io).
+
+Check out the `.golangci.yaml` and `Makefile` to see the specific configuration.
+
+### Install development tools
+
+- Go
+- Buf
+- Protobuf tools
+
+Install and activate:
+
+```shell
+nix develop
+```
+
+### Testing and building
+
+Some parts of the project require the generation of Go code from Protobuf
+(if changes are made in `proto/`) and it must be (re-)generated with:
+
+```shell
+make generate
+```
+
+**Note**: Please check in changes from `gen/` in a separate commit to make it easier to review.
+
+To run the tests:
+
+```shell
+make test
+```
+
+To build the program:
+
+```shell
+nix build
+```
+
+or
+
+```shell
+make build
+```
+
+## Contributors
+
+<a href="https://github.com/juanfont/headscale/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=juanfont/headscale" />
+</a>
+
+Made with [contrib.rocks](https://contrib.rocks).

acls.go

@@ -1,263 +0,0 @@
-package headscale
-
-import (
-	"encoding/json"
-	"fmt"
-	"io"
-	"log"
-	"os"
-	"strconv"
-	"strings"
-
-	"github.com/tailscale/hujson"
-	"inet.af/netaddr"
-	"tailscale.com/tailcfg"
-)
-
-const errorEmptyPolicy = Error("empty policy")
-const errorInvalidAction = Error("invalid action")
-const errorInvalidUserSection = Error("invalid user section")
-const errorInvalidGroup = Error("invalid group")
-const errorInvalidTag = Error("invalid tag")
-const errorInvalidNamespace = Error("invalid namespace")
-const errorInvalidPortFormat = Error("invalid port format")
-
-// LoadACLPolicy loads the ACL policy from the specify path, and generates the ACL rules
-func (h *Headscale) LoadACLPolicy(path string) error {
-	policyFile, err := os.Open(path)
-	if err != nil {
-		return err
-	}
-	defer policyFile.Close()
-
-	var policy ACLPolicy
-	b, err := io.ReadAll(policyFile)
-	if err != nil {
-		return err
-	}
-	err = hujson.Unmarshal(b, &policy)
-	if err != nil {
-		return err
-	}
-	if policy.IsZero() {
-		return errorEmptyPolicy
-	}
-
-	h.aclPolicy = &policy
-	rules, err := h.generateACLRules()
-	if err != nil {
-		return err
-	}
-	h.aclRules = rules
-	return nil
-}
-
-func (h *Headscale) generateACLRules() (*[]tailcfg.FilterRule, error) {
-	rules := []tailcfg.FilterRule{}
-
-	for i, a := range h.aclPolicy.ACLs {
-		if a.Action != "accept" {
-			return nil, errorInvalidAction
-		}
-
-		r := tailcfg.FilterRule{}
-
-		srcIPs := []string{}
-		for j, u := range a.Users {
-			srcs, err := h.generateACLPolicySrcIP(u)
-			if err != nil {
-				log.Printf("Error parsing ACL %d, User %d", i, j)
-				return nil, err
-			}
-			srcIPs = append(srcIPs, *srcs...)
-		}
-		r.SrcIPs = srcIPs
-
-		destPorts := []tailcfg.NetPortRange{}
-		for j, d := range a.Ports {
-			dests, err := h.generateACLPolicyDestPorts(d)
-			if err != nil {
-				log.Printf("Error parsing ACL %d, Port %d", i, j)
-				return nil, err
-			}
-			destPorts = append(destPorts, *dests...)
-		}
-
-		rules = append(rules, tailcfg.FilterRule{
-			SrcIPs:   srcIPs,
-			DstPorts: destPorts,
-		})
-	}
-
-	return &rules, nil
-}
-
-func (h *Headscale) generateACLPolicySrcIP(u string) (*[]string, error) {
-	return h.expandAlias(u)
-}
-
-func (h *Headscale) generateACLPolicyDestPorts(d string) (*[]tailcfg.NetPortRange, error) {
-	tokens := strings.Split(d, ":")
-	if len(tokens) < 2 || len(tokens) > 3 {
-		return nil, errorInvalidPortFormat
-	}
-
-	var alias string
-	// We can have here stuff like:
-	// git-server:*
-	// 192.168.1.0/24:22
-	// tag:montreal-webserver:80,443
-	// tag:api-server:443
-	// example-host-1:*
-	if len(tokens) == 2 {
-		alias = tokens[0]
-	} else {
-		alias = fmt.Sprintf("%s:%s", tokens[0], tokens[1])
-	}
-
-	expanded, err := h.expandAlias(alias)
-	if err != nil {
-		return nil, err
-	}
-	ports, err := h.expandPorts(tokens[len(tokens)-1])
-	if err != nil {
-		return nil, err
-	}
-
-	dests := []tailcfg.NetPortRange{}
-	for _, d := range *expanded {
-		for _, p := range *ports {
-			pr := tailcfg.NetPortRange{
-				IP:    d,
-				Ports: p,
-			}
-			dests = append(dests, pr)
-		}
-	}
-	return &dests, nil
-}
-
-func (h *Headscale) expandAlias(s string) (*[]string, error) {
-	if s == "*" {
-		return &[]string{"*"}, nil
-	}
-
-	if strings.HasPrefix(s, "group:") {
-		if _, ok := h.aclPolicy.Groups[s]; !ok {
-			return nil, errorInvalidGroup
-		}
-		ips := []string{}
-		for _, n := range h.aclPolicy.Groups[s] {
-			nodes, err := h.ListMachinesInNamespace(n)
-			if err != nil {
-				return nil, errorInvalidNamespace
-			}
-			for _, node := range *nodes {
-				ips = append(ips, node.IPAddress)
-			}
-		}
-		return &ips, nil
-	}
-
-	if strings.HasPrefix(s, "tag:") {
-		if _, ok := h.aclPolicy.TagOwners[s]; !ok {
-			return nil, errorInvalidTag
-		}
-
-		// This will have HORRIBLE performance.
-		// We need to change the data model to better store tags
-		machines := []Machine{}
-		if err := h.db.Where("registered").Find(&machines).Error; err != nil {
-			return nil, err
-		}
-		ips := []string{}
-		for _, m := range machines {
-			hostinfo := tailcfg.Hostinfo{}
-			if len(m.HostInfo) != 0 {
-				hi, err := m.HostInfo.MarshalJSON()
-				if err != nil {
-					return nil, err
-				}
-				err = json.Unmarshal(hi, &hostinfo)
-				if err != nil {
-					return nil, err
-				}
-
-				// FIXME: Check TagOwners allows this
-				for _, t := range hostinfo.RequestTags {
-					if s[4:] == t {
-						ips = append(ips, m.IPAddress)
-						break
-					}
-				}
-			}
-		}
-		return &ips, nil
-	}
-
-	n, err := h.GetNamespace(s)
-	if err == nil {
-		nodes, err := h.ListMachinesInNamespace(n.Name)
-		if err != nil {
-			return nil, err
-		}
-		ips := []string{}
-		for _, n := range *nodes {
-			ips = append(ips, n.IPAddress)
-		}
-		return &ips, nil
-	}
-
-	if h, ok := h.aclPolicy.Hosts[s]; ok {
-		return &[]string{h.String()}, nil
-	}
-
-	ip, err := netaddr.ParseIP(s)
-	if err == nil {
-		return &[]string{ip.String()}, nil
-	}
-
-	cidr, err := netaddr.ParseIPPrefix(s)
-	if err == nil {
-		return &[]string{cidr.String()}, nil
-	}
-
-	return nil, errorInvalidUserSection
-}
-
-func (h *Headscale) expandPorts(s string) (*[]tailcfg.PortRange, error) {
-	if s == "*" {
-		return &[]tailcfg.PortRange{{First: 0, Last: 65535}}, nil
-	}
-
-	ports := []tailcfg.PortRange{}
-	for _, p := range strings.Split(s, ",") {
-		rang := strings.Split(p, "-")
-		if len(rang) == 1 {
-			pi, err := strconv.ParseUint(rang[0], 10, 16)
-			if err != nil {
-				return nil, err
-			}
-			ports = append(ports, tailcfg.PortRange{
-				First: uint16(pi),
-				Last:  uint16(pi),
-			})
-		} else if len(rang) == 2 {
-			start, err := strconv.ParseUint(rang[0], 10, 16)
-			if err != nil {
-				return nil, err
-			}
-			last, err := strconv.ParseUint(rang[1], 10, 16)
-			if err != nil {
-				return nil, err
-			}
-			ports = append(ports, tailcfg.PortRange{
-				First: uint16(start),
-				Last:  uint16(last),
-			})
-		} else {
-			return nil, errorInvalidPortFormat
-		}
-	}
-	return &ports, nil
-}

acls_test.go

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

acls_types.go

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

api.go

@@ -1,468 +0,0 @@
-package headscale
-
-import (
-	"encoding/binary"
-	"encoding/json"
-	"errors"
-	"fmt"
-	"io"
-	"log"
-	"net/http"
-	"time"
-
-	"github.com/gin-gonic/gin"
-	"github.com/klauspost/compress/zstd"
-	"gorm.io/datatypes"
-	"gorm.io/gorm"
-	"inet.af/netaddr"
-	"tailscale.com/tailcfg"
-	"tailscale.com/types/wgkey"
-)
-
-// KeyHandler provides the Headscale pub key
-// Listens in /key
-func (h *Headscale) KeyHandler(c *gin.Context) {
-	c.Data(200, "text/plain; charset=utf-8", []byte(h.publicKey.HexString()))
-}
-
-// RegisterWebAPI shows a simple message in the browser to point to the CLI
-// Listens in /register
-func (h *Headscale) RegisterWebAPI(c *gin.Context) {
-	mKeyStr := c.Query("key")
-	if mKeyStr == "" {
-		c.String(http.StatusBadRequest, "Wrong params")
-		return
-	}
-
-	// spew.Dump(c.Params)
-
-	c.Data(http.StatusOK, "text/html; charset=utf-8", []byte(fmt.Sprintf(`
-	<html>
-	<body>
-	<h1>headscale</h1>
-	<p>
-		Run the command below in the headscale server to add this machine to your network:
-	</p>
-
-	<p>
-		<code>
-			<b>headscale -n NAMESPACE nodes register %s</b>
-		</code>
-	</p>
-
-	</body>
-	</html>
-
-	`, mKeyStr)))
-}
-
-// RegistrationHandler handles the actual registration process of a machine
-// Endpoint /machine/:id
-func (h *Headscale) RegistrationHandler(c *gin.Context) {
-	body, _ := io.ReadAll(c.Request.Body)
-	mKeyStr := c.Param("id")
-	mKey, err := wgkey.ParseHex(mKeyStr)
-	if err != nil {
-		log.Printf("Cannot parse machine key: %s", err)
-		c.String(http.StatusInternalServerError, "Sad!")
-		return
-	}
-	req := tailcfg.RegisterRequest{}
-	err = decode(body, &req, &mKey, h.privateKey)
-	if err != nil {
-		log.Printf("Cannot decode message: %s", err)
-		c.String(http.StatusInternalServerError, "Very sad!")
-		return
-	}
-
-	var m Machine
-	if result := h.db.Preload("Namespace").First(&m, "machine_key = ?", mKey.HexString()); errors.Is(result.Error, gorm.ErrRecordNotFound) {
-		log.Println("New Machine!")
-		m = Machine{
-			Expiry:     &req.Expiry,
-			MachineKey: mKey.HexString(),
-			Name:       req.Hostinfo.Hostname,
-			NodeKey:    wgkey.Key(req.NodeKey).HexString(),
-		}
-		if err := h.db.Create(&m).Error; err != nil {
-			log.Printf("Could not create row: %s", err)
-			return
-		}
-	}
-
-	if !m.Registered && req.Auth.AuthKey != "" {
-		h.handleAuthKey(c, h.db, mKey, req, m)
-		return
-	}
-
-	resp := tailcfg.RegisterResponse{}
-
-	// We have the updated key!
-	if m.NodeKey == wgkey.Key(req.NodeKey).HexString() {
-		if m.Registered {
-			log.Printf("[%s] Client is registered and we have the current NodeKey. All clear to /map", m.Name)
-			resp.AuthURL = ""
-			resp.MachineAuthorized = true
-			resp.User = *m.Namespace.toUser()
-			respBody, err := encode(resp, &mKey, h.privateKey)
-			if err != nil {
-				log.Printf("Cannot encode message: %s", err)
-				c.String(http.StatusInternalServerError, "")
-				return
-			}
-			c.Data(200, "application/json; charset=utf-8", respBody)
-			return
-		}
-
-		log.Printf("[%s] Not registered and not NodeKey rotation. Sending a authurl to register", m.Name)
-		resp.AuthURL = fmt.Sprintf("%s/register?key=%s",
-			h.cfg.ServerURL, mKey.HexString())
-		respBody, err := encode(resp, &mKey, h.privateKey)
-		if err != nil {
-			log.Printf("Cannot encode message: %s", err)
-			c.String(http.StatusInternalServerError, "")
-			return
-		}
-		c.Data(200, "application/json; charset=utf-8", respBody)
-		return
-	}
-
-	// The NodeKey we have matches OldNodeKey, which means this is a refresh after an key expiration
-	if m.NodeKey == wgkey.Key(req.OldNodeKey).HexString() {
-		log.Printf("[%s] We have the OldNodeKey in the database. This is a key refresh", m.Name)
-		m.NodeKey = wgkey.Key(req.NodeKey).HexString()
-		h.db.Save(&m)
-
-		resp.AuthURL = ""
-		resp.User = *m.Namespace.toUser()
-		respBody, err := encode(resp, &mKey, h.privateKey)
-		if err != nil {
-			log.Printf("Cannot encode message: %s", err)
-			c.String(http.StatusInternalServerError, "Extremely sad!")
-			return
-		}
-		c.Data(200, "application/json; charset=utf-8", respBody)
-		return
-	}
-
-	// We arrive here after a client is restarted without finalizing the authentication flow or
-	// when headscale is stopped in the middle of the auth process.
-	if m.Registered {
-		log.Printf("[%s] The node is sending us a new NodeKey, but machine is registered. All clear for /map", m.Name)
-		resp.AuthURL = ""
-		resp.MachineAuthorized = true
-		resp.User = *m.Namespace.toUser()
-		respBody, err := encode(resp, &mKey, h.privateKey)
-		if err != nil {
-			log.Printf("Cannot encode message: %s", err)
-			c.String(http.StatusInternalServerError, "")
-			return
-		}
-		c.Data(200, "application/json; charset=utf-8", respBody)
-		return
-	}
-	log.Printf("[%s] The node is sending us a new NodeKey, sending auth url", m.Name)
-	resp.AuthURL = fmt.Sprintf("%s/register?key=%s",
-		h.cfg.ServerURL, mKey.HexString())
-	respBody, err := encode(resp, &mKey, h.privateKey)
-	if err != nil {
-		log.Printf("Cannot encode message: %s", err)
-		c.String(http.StatusInternalServerError, "")
-		return
-	}
-	c.Data(200, "application/json; charset=utf-8", respBody)
-}
-
-// PollNetMapHandler takes care of /machine/:id/map
-//
-// This is the busiest endpoint, as it keeps the HTTP long poll that updates
-// the clients when something in the network changes.
-//
-// The clients POST stuff like HostInfo and their Endpoints here, but
-// only after their first request (marked with the ReadOnly field).
-//
-// At this moment the updates are sent in a quite horrendous way, but they kinda work.
-func (h *Headscale) PollNetMapHandler(c *gin.Context) {
-	body, _ := io.ReadAll(c.Request.Body)
-	mKeyStr := c.Param("id")
-	mKey, err := wgkey.ParseHex(mKeyStr)
-	if err != nil {
-		log.Printf("Cannot parse client key: %s", err)
-		c.String(http.StatusBadRequest, "")
-		return
-	}
-	req := tailcfg.MapRequest{}
-	err = decode(body, &req, &mKey, h.privateKey)
-	if err != nil {
-		log.Printf("Cannot decode message: %s", err)
-		c.String(http.StatusBadRequest, "")
-		return
-	}
-
-	var m Machine
-	if result := h.db.Preload("Namespace").First(&m, "machine_key = ?", mKey.HexString()); errors.Is(result.Error, gorm.ErrRecordNotFound) {
-		log.Printf("Ignoring request, cannot find machine with key %s", mKey.HexString())
-		c.String(http.StatusUnauthorized, "")
-		return
-	}
-
-	hostinfo, _ := json.Marshal(req.Hostinfo)
-	m.Name = req.Hostinfo.Hostname
-	m.HostInfo = datatypes.JSON(hostinfo)
-	m.DiscoKey = wgkey.Key(req.DiscoKey).HexString()
-	now := time.Now().UTC()
-
-	// From Tailscale client:
-	//
-	// ReadOnly is whether the client just wants to fetch the MapResponse,
-	// without updating their Endpoints. The Endpoints field will be ignored and
-	// LastSeen will not be updated and peers will not be notified of changes.
-	//
-	// The intended use is for clients to discover the DERP map at start-up
-	// before their first real endpoint update.
-	if !req.ReadOnly {
-		endpoints, _ := json.Marshal(req.Endpoints)
-		m.Endpoints = datatypes.JSON(endpoints)
-		m.LastSeen = &now
-	}
-	h.db.Save(&m)
-
-	pollData := make(chan []byte, 1)
-	update := make(chan []byte, 1)
-	cancelKeepAlive := make(chan []byte, 1)
-	defer close(pollData)
-	defer close(cancelKeepAlive)
-	h.pollMu.Lock()
-	h.clientsPolling[m.ID] = update
-	h.pollMu.Unlock()
-
-	data, err := h.getMapResponse(mKey, req, m)
-	if err != nil {
-		c.String(http.StatusInternalServerError, ":(")
-		return
-	}
-
-	// We update our peers if the client is not sending ReadOnly in the MapRequest
-	// so we don't distribute its initial request (it comes with
-	// empty endpoints to peers)
-
-	// Details on the protocol can be found in https://github.com/tailscale/tailscale/blob/main/tailcfg/tailcfg.go#L696
-	log.Printf("[%s] ReadOnly=%t   OmitPeers=%t    Stream=%t", m.Name, req.ReadOnly, req.OmitPeers, req.Stream)
-
-	if req.ReadOnly {
-		log.Printf("[%s] Client is starting up. Asking for DERP map", m.Name)
-		c.Data(200, "application/json; charset=utf-8", *data)
-		return
-	}
-	if req.OmitPeers && !req.Stream {
-		log.Printf("[%s] Client sent endpoint update and is ok with a response without peer list", m.Name)
-		c.Data(200, "application/json; charset=utf-8", *data)
-		return
-	} else if req.OmitPeers && req.Stream {
-		log.Printf("[%s] Warning, ignoring request, don't know how to handle it", m.Name)
-		c.String(http.StatusBadRequest, "")
-		return
-	}
-
-	log.Printf("[%s] Client is ready to access the tailnet", m.Name)
-	log.Printf("[%s] Sending initial map", m.Name)
-	pollData <- *data
-
-	log.Printf("[%s] Notifying peers", m.Name)
-	peers, _ := h.getPeers(m)
-	h.pollMu.Lock()
-	for _, p := range *peers {
-		pUp, ok := h.clientsPolling[uint64(p.ID)]
-		if ok {
-			log.Printf("[%s] Notifying peer %s (%s)", m.Name, p.Name, p.Addresses[0])
-			pUp <- []byte{}
-		} else {
-			log.Printf("[%s] Peer %s does not appear to be polling", m.Name, p.Name)
-		}
-	}
-	h.pollMu.Unlock()
-
-	go h.keepAlive(cancelKeepAlive, pollData, mKey, req, m)
-
-	c.Stream(func(w io.Writer) bool {
-		select {
-		case data := <-pollData:
-			log.Printf("[%s] Sending data (%d bytes)", m.Name, len(data))
-			_, err := w.Write(data)
-			if err != nil {
-				log.Printf("[%s] Cannot write data: %s", m.Name, err)
-			}
-			now := time.Now().UTC()
-			m.LastSeen = &now
-			h.db.Save(&m)
-			return true
-
-		case <-update:
-			log.Printf("[%s] Received a request for update", m.Name)
-			data, err := h.getMapResponse(mKey, req, m)
-			if err != nil {
-				log.Printf("[%s] Could not get the map update: %s", m.Name, err)
-			}
-			_, err = w.Write(*data)
-			if err != nil {
-				log.Printf("[%s] Could not write the map response: %s", m.Name, err)
-			}
-			return true
-
-		case <-c.Request.Context().Done():
-			log.Printf("[%s] The client has closed the connection", m.Name)
-			now := time.Now().UTC()
-			m.LastSeen = &now
-			h.db.Save(&m)
-			h.pollMu.Lock()
-			cancelKeepAlive <- []byte{}
-			delete(h.clientsPolling, m.ID)
-			close(update)
-			h.pollMu.Unlock()
-			return false
-
-		}
-	})
-}
-
-func (h *Headscale) keepAlive(cancel chan []byte, pollData chan []byte, mKey wgkey.Key, req tailcfg.MapRequest, m Machine) {
-	for {
-		select {
-		case <-cancel:
-			return
-
-		default:
-			h.pollMu.Lock()
-			data, err := h.getMapKeepAliveResponse(mKey, req, m)
-			if err != nil {
-				log.Printf("Error generating the keep alive msg: %s", err)
-				return
-			}
-			log.Printf("[%s] Sending keepalive", m.Name)
-			pollData <- *data
-			h.pollMu.Unlock()
-			time.Sleep(60 * time.Second)
-		}
-	}
-}
-
-func (h *Headscale) getMapResponse(mKey wgkey.Key, req tailcfg.MapRequest, m Machine) (*[]byte, error) {
-	node, err := m.toNode()
-	if err != nil {
-		log.Printf("Cannot convert to node: %s", err)
-		return nil, err
-	}
-	peers, err := h.getPeers(m)
-	if err != nil {
-		log.Printf("Cannot fetch peers: %s", err)
-		return nil, err
-	}
-
-	profile := tailcfg.UserProfile{
-		ID:          tailcfg.UserID(m.NamespaceID),
-		LoginName:   m.Namespace.Name,
-		DisplayName: m.Namespace.Name,
-	}
-
-	resp := tailcfg.MapResponse{
-		KeepAlive:    false,
-		Node:         node,
-		Peers:        *peers,
-		DNS:          []netaddr.IP{},
-		SearchPaths:  []string{},
-		Domain:       "headscale.net",
-		PacketFilter: *h.aclRules,
-		DERPMap:      h.cfg.DerpMap,
-		UserProfiles: []tailcfg.UserProfile{profile},
-	}
-
-	var respBody []byte
-	if req.Compress == "zstd" {
-		src, _ := json.Marshal(resp)
-		encoder, _ := zstd.NewWriter(nil)
-		srcCompressed := encoder.EncodeAll(src, nil)
-		respBody, err = encodeMsg(srcCompressed, &mKey, h.privateKey)
-		if err != nil {
-			return nil, err
-		}
-	} else {
-		respBody, err = encode(resp, &mKey, h.privateKey)
-		if err != nil {
-			return nil, err
-		}
-	}
-	// spew.Dump(resp)
-	// declare the incoming size on the first 4 bytes
-	data := make([]byte, 4)
-	binary.LittleEndian.PutUint32(data, uint32(len(respBody)))
-	data = append(data, respBody...)
-	return &data, nil
-}
-
-func (h *Headscale) getMapKeepAliveResponse(mKey wgkey.Key, req tailcfg.MapRequest, m Machine) (*[]byte, error) {
-	resp := tailcfg.MapResponse{
-		KeepAlive: true,
-	}
-	var respBody []byte
-	var err error
-	if req.Compress == "zstd" {
-		src, _ := json.Marshal(resp)
-		encoder, _ := zstd.NewWriter(nil)
-		srcCompressed := encoder.EncodeAll(src, nil)
-		respBody, err = encodeMsg(srcCompressed, &mKey, h.privateKey)
-		if err != nil {
-			return nil, err
-		}
-	} else {
-		respBody, err = encode(resp, &mKey, h.privateKey)
-		if err != nil {
-			return nil, err
-		}
-	}
-	data := make([]byte, 4)
-	binary.LittleEndian.PutUint32(data, uint32(len(respBody)))
-	data = append(data, respBody...)
-	return &data, nil
-}
-
-func (h *Headscale) handleAuthKey(c *gin.Context, db *gorm.DB, idKey wgkey.Key, req tailcfg.RegisterRequest, m Machine) {
-	resp := tailcfg.RegisterResponse{}
-	pak, err := h.checkKeyValidity(req.Auth.AuthKey)
-	if err != nil {
-		resp.MachineAuthorized = false
-		respBody, err := encode(resp, &idKey, h.privateKey)
-		if err != nil {
-			log.Printf("Cannot encode message: %s", err)
-			c.String(http.StatusInternalServerError, "")
-			return
-		}
-		c.Data(200, "application/json; charset=utf-8", respBody)
-		log.Printf("[%s] Failed authentication via AuthKey", m.Name)
-		return
-	}
-	ip, err := h.getAvailableIP()
-	if err != nil {
-		log.Println(err)
-		return
-	}
-	log.Printf("Assigning %s to %s", ip, m.Name)
-
-	m.AuthKeyID = uint(pak.ID)
-	m.IPAddress = ip.String()
-	m.NamespaceID = pak.NamespaceID
-	m.NodeKey = wgkey.Key(req.NodeKey).HexString() // we update it just in case
-	m.Registered = true
-	m.RegisterMethod = "authKey"
-	db.Save(&m)
-
-	resp.MachineAuthorized = true
-	resp.User = *pak.Namespace.toUser()
-	respBody, err := encode(resp, &idKey, h.privateKey)
-	if err != nil {
-		log.Printf("Cannot encode message: %s", err)
-		c.String(http.StatusInternalServerError, "Extremely sad!")
-		return
-	}
-	c.Data(200, "application/json; charset=utf-8", respBody)
-	log.Printf("[%s] Successfully authenticated via AuthKey", m.Name)
-}

app.go

@@ -1,212 +0,0 @@
-package headscale
-
-import (
-	"errors"
-	"fmt"
-	"log"
-	"net/http"
-	"os"
-	"strings"
-	"sync"
-	"time"
-
-	"github.com/gin-gonic/gin"
-	"golang.org/x/crypto/acme/autocert"
-	"gorm.io/gorm"
-	"inet.af/netaddr"
-	"tailscale.com/tailcfg"
-	"tailscale.com/types/wgkey"
-)
-
-// Config contains the initial Headscale configuration
-type Config struct {
-	ServerURL                      string
-	Addr                           string
-	PrivateKeyPath                 string
-	DerpMap                        *tailcfg.DERPMap
-	EphemeralNodeInactivityTimeout time.Duration
-	IPPrefix                       netaddr.IPPrefix
-
-	DBtype string
-	DBpath string
-	DBhost string
-	DBport int
-	DBname string
-	DBuser string
-	DBpass string
-
-	TLSLetsEncryptListen        string
-	TLSLetsEncryptHostname      string
-	TLSLetsEncryptCacheDir      string
-	TLSLetsEncryptChallengeType string
-
-	TLSCertPath string
-	TLSKeyPath  string
-}
-
-// Headscale represents the base app of the service
-type Headscale struct {
-	cfg        Config
-	db         *gorm.DB
-	dbString   string
-	dbType     string
-	dbDebug    bool
-	publicKey  *wgkey.Key
-	privateKey *wgkey.Private
-
-	aclPolicy *ACLPolicy
-	aclRules  *[]tailcfg.FilterRule
-
-	pollMu         sync.Mutex
-	clientsPolling map[uint64]chan []byte // this is by all means a hackity hack
-}
-
-// NewHeadscale returns the Headscale app
-func NewHeadscale(cfg Config) (*Headscale, error) {
-	content, err := os.ReadFile(cfg.PrivateKeyPath)
-	if err != nil {
-		return nil, err
-	}
-	privKey, err := wgkey.ParsePrivate(string(content))
-	if err != nil {
-		return nil, err
-	}
-	pubKey := privKey.Public()
-
-	var dbString string
-	switch cfg.DBtype {
-	case "postgres":
-		dbString = fmt.Sprintf("host=%s port=%d dbname=%s user=%s password=%s sslmode=disable", cfg.DBhost,
-			cfg.DBport, cfg.DBname, cfg.DBuser, cfg.DBpass)
-	case "sqlite3":
-		dbString = cfg.DBpath
-	default:
-		return nil, errors.New("unsupported DB")
-	}
-
-	h := Headscale{
-		cfg:        cfg,
-		dbType:     cfg.DBtype,
-		dbString:   dbString,
-		privateKey: privKey,
-		publicKey:  &pubKey,
-		aclRules:   &tailcfg.FilterAllowAll, // default allowall
-	}
-
-	err = h.initDB()
-	if err != nil {
-		return nil, err
-	}
-
-	h.clientsPolling = make(map[uint64]chan []byte)
-	return &h, nil
-}
-
-// Redirect to our TLS url
-func (h *Headscale) redirect(w http.ResponseWriter, req *http.Request) {
-	target := h.cfg.ServerURL + req.URL.RequestURI()
-	http.Redirect(w, req, target, http.StatusFound)
-}
-
-// ExpireEphemeralNodes deletes ephemeral machine records that have not been
-// seen for longer than h.cfg.EphemeralNodeInactivityTimeout
-func (h *Headscale) ExpireEphemeralNodes(milliSeconds int64) {
-	ticker := time.NewTicker(time.Duration(milliSeconds) * time.Millisecond)
-	for range ticker.C {
-		h.expireEphemeralNodesWorker()
-	}
-}
-
-func (h *Headscale) expireEphemeralNodesWorker() {
-	namespaces, err := h.ListNamespaces()
-	if err != nil {
-		log.Printf("Error listing namespaces: %s", err)
-		return
-	}
-	for _, ns := range *namespaces {
-		machines, err := h.ListMachinesInNamespace(ns.Name)
-		if err != nil {
-			log.Printf("Error listing machines in namespace %s: %s", ns.Name, err)
-			return
-		}
-		for _, m := range *machines {
-			if m.AuthKey != nil && m.LastSeen != nil && m.AuthKey.Ephemeral && time.Now().After(m.LastSeen.Add(h.cfg.EphemeralNodeInactivityTimeout)) {
-				log.Printf("[%s] Ephemeral client removed from database\n", m.Name)
-				err = h.db.Unscoped().Delete(m).Error
-				if err != nil {
-					log.Printf("[%s] 🤮 Cannot delete ephemeral machine from the database: %s", m.Name, err)
-				}
-			}
-		}
-	}
-}
-
-// WatchForKVUpdates checks the KV DB table for requests to perform tailnet upgrades
-// This is a way to communitate the CLI with the headscale server
-func (h *Headscale) watchForKVUpdates(milliSeconds int64) {
-	ticker := time.NewTicker(time.Duration(milliSeconds) * time.Millisecond)
-	for range ticker.C {
-		h.watchForKVUpdatesWorker()
-	}
-}
-
-func (h *Headscale) watchForKVUpdatesWorker() {
-	h.checkForNamespacesPendingUpdates()
-	// more functions will come here in the future
-}
-
-// Serve launches a GIN server with the Headscale API
-func (h *Headscale) Serve() error {
-	r := gin.Default()
-	r.GET("/key", h.KeyHandler)
-	r.GET("/register", h.RegisterWebAPI)
-	r.POST("/machine/:id/map", h.PollNetMapHandler)
-	r.POST("/machine/:id", h.RegistrationHandler)
-	var err error
-
-	go h.watchForKVUpdates(5000)
-
-	if h.cfg.TLSLetsEncryptHostname != "" {
-		if !strings.HasPrefix(h.cfg.ServerURL, "https://") {
-			log.Println("WARNING: listening with TLS but ServerURL does not start with https://")
-		}
-
-		m := autocert.Manager{
-			Prompt:     autocert.AcceptTOS,
-			HostPolicy: autocert.HostWhitelist(h.cfg.TLSLetsEncryptHostname),
-			Cache:      autocert.DirCache(h.cfg.TLSLetsEncryptCacheDir),
-		}
-		s := &http.Server{
-			Addr:      h.cfg.Addr,
-			TLSConfig: m.TLSConfig(),
-			Handler:   r,
-		}
-		if h.cfg.TLSLetsEncryptChallengeType == "TLS-ALPN-01" {
-			// Configuration via autocert with TLS-ALPN-01 (https://tools.ietf.org/html/rfc8737)
-			// The RFC requires that the validation is done on port 443; in other words, headscale
-			// must be reachable on port 443.
-			err = s.ListenAndServeTLS("", "")
-		} else if h.cfg.TLSLetsEncryptChallengeType == "HTTP-01" {
-			// Configuration via autocert with HTTP-01. This requires listening on
-			// port 80 for the certificate validation in addition to the headscale
-			// service, which can be configured to run on any other port.
-			go func() {
-				log.Fatal(http.ListenAndServe(h.cfg.TLSLetsEncryptListen, m.HTTPHandler(http.HandlerFunc(h.redirect))))
-			}()
-			err = s.ListenAndServeTLS("", "")
-		} else {
-			return errors.New("unknown value for TLSLetsEncryptChallengeType")
-		}
-	} else if h.cfg.TLSCertPath == "" {
-		if !strings.HasPrefix(h.cfg.ServerURL, "http://") {
-			log.Println("WARNING: listening without TLS but ServerURL does not start with http://")
-		}
-		err = r.Run(h.cfg.Addr)
-	} else {
-		if !strings.HasPrefix(h.cfg.ServerURL, "https://") {
-			log.Println("WARNING: listening with TLS but ServerURL does not start with https://")
-		}
-		err = r.RunTLS(h.cfg.Addr, h.cfg.TLSCertPath, h.cfg.TLSKeyPath)
-	}
-	return err
-}

app_test.go

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

buf.gen.yaml

@@ -0,0 +1,21 @@
+version: v1
+plugins:
+  - name: go
+    out: gen/go
+    opt:
+      - paths=source_relative
+  - name: go-grpc
+    out: gen/go
+    opt:
+      - paths=source_relative
+  - name: grpc-gateway
+    out: gen/go
+    opt:
+      - paths=source_relative
+      - generate_unbound_methods=true
+  # - name: gorm
+  #   out: gen/go
+  #   opt:
+  #     - paths=source_relative,enums=string,gateway=true
+  - name: openapiv2
+    out: gen/openapiv2

cli.go

@@ -1,40 +0,0 @@
-package headscale
-
-import (
-	"errors"
-
-	"gorm.io/gorm"
-	"tailscale.com/types/wgkey"
-)
-
-// RegisterMachine is executed from the CLI to register a new Machine using its MachineKey
-func (h *Headscale) RegisterMachine(key string, namespace string) (*Machine, error) {
-	ns, err := h.GetNamespace(namespace)
-	if err != nil {
-		return nil, err
-	}
-	mKey, err := wgkey.ParseHex(key)
-	if err != nil {
-		return nil, err
-	}
-
-	m := Machine{}
-	if result := h.db.First(&m, "machine_key = ?", mKey.HexString()); errors.Is(result.Error, gorm.ErrRecordNotFound) {
-		return nil, errors.New("Machine not found")
-	}
-
-	if m.isAlreadyRegistered() {
-		return nil, errors.New("Machine already registered")
-	}
-
-	ip, err := h.getAvailableIP()
-	if err != nil {
-		return nil, err
-	}
-	m.IPAddress = ip.String()
-	m.NamespaceID = ns.ID
-	m.Registered = true
-	m.RegisterMethod = "cli"
-	h.db.Save(&m)
-	return &m, nil
-}

cli_test.go

@@ -1,31 +0,0 @@
-package headscale
-
-import (
-	"gopkg.in/check.v1"
-)
-
-func (s *Suite) TestRegisterMachine(c *check.C) {
-	n, err := h.CreateNamespace("test")
-	c.Assert(err, check.IsNil)
-
-	m := Machine{
-		ID:          0,
-		MachineKey:  "8ce002a935f8c394e55e78fbbb410576575ff8ec5cfa2e627e4b807f1be15b0e",
-		NodeKey:     "bar",
-		DiscoKey:    "faa",
-		Name:        "testmachine",
-		NamespaceID: n.ID,
-		IPAddress:   "10.0.0.1",
-	}
-	h.db.Save(&m)
-
-	_, err = h.GetMachine("test", "testmachine")
-	c.Assert(err, check.IsNil)
-
-	m2, err := h.RegisterMachine("8ce002a935f8c394e55e78fbbb410576575ff8ec5cfa2e627e4b807f1be15b0e", n.Name)
-	c.Assert(err, check.IsNil)
-	c.Assert(m2.Registered, check.Equals, true)
-
-	_, err = m2.GetHostInfo()
-	c.Assert(err, check.IsNil)
-}

cmd/gh-action-integration-generator/main.go

@@ -0,0 +1,69 @@
+package main
+
+//go:generate go run ./main.go
+
+import (
+	"bytes"
+	"fmt"
+	"log"
+	"os/exec"
+	"strings"
+)
+
+func findTests() []string {
+	rgBin, err := exec.LookPath("rg")
+	if err != nil {
+		log.Fatalf("failed to find rg (ripgrep) binary")
+	}
+
+	args := []string{
+		"--regexp", "func (Test.+)\\(.*",
+		"../../integration/",
+		"--replace", "$1",
+		"--sort", "path",
+		"--no-line-number",
+		"--no-filename",
+		"--no-heading",
+	}
+
+	cmd := exec.Command(rgBin, args...)
+	var out bytes.Buffer
+	cmd.Stdout = &out
+	err = cmd.Run()
+	if err != nil {
+		log.Fatalf("failed to run command: %s", err)
+	}
+
+	tests := strings.Split(strings.TrimSpace(out.String()), "\n")
+	return tests
+}
+
+func updateYAML(tests []string) {
+	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",
+		testsForYq,
+	)
+	cmd := exec.Command("bash", "-c", yqCommand)
+
+	var out bytes.Buffer
+	cmd.Stdout = &out
+	err := cmd.Run()
+	if err != nil {
+		log.Fatalf("failed to run yq command: %s", err)
+	}
+
+	fmt.Println("YAML file updated successfully")
+}
+
+func main() {
+	tests := findTests()
+
+	quotedTests := make([]string, len(tests))
+	for i, test := range tests {
+		quotedTests[i] = fmt.Sprintf("\"%s\"", test)
+	}
+
+	updateYAML(quotedTests)
+}

cmd/headscale/cli/api_key.go

@@ -0,0 +1,247 @@
+package cli
+
+import (
+	"fmt"
+	"strconv"
+	"time"
+
+	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/juanfont/headscale/hscontrol/util"
+	"github.com/prometheus/common/model"
+	"github.com/pterm/pterm"
+	"github.com/rs/zerolog/log"
+	"github.com/spf13/cobra"
+	"google.golang.org/protobuf/types/known/timestamppb"
+)
+
+const (
+	// 90 days.
+	DefaultAPIKeyExpiry = "90d"
+)
+
+func init() {
+	rootCmd.AddCommand(apiKeysCmd)
+	apiKeysCmd.AddCommand(listAPIKeys)
+
+	createAPIKeyCmd.Flags().
+		StringP("expiration", "e", DefaultAPIKeyExpiry, "Human-readable expiration of the key (e.g. 30m, 24h)")
+
+	apiKeysCmd.AddCommand(createAPIKeyCmd)
+
+	expireAPIKeyCmd.Flags().StringP("prefix", "p", "", "ApiKey prefix")
+	if err := expireAPIKeyCmd.MarkFlagRequired("prefix"); err != nil {
+		log.Fatal().Err(err).Msg("")
+	}
+	apiKeysCmd.AddCommand(expireAPIKeyCmd)
+
+	deleteAPIKeyCmd.Flags().StringP("prefix", "p", "", "ApiKey prefix")
+	if err := deleteAPIKeyCmd.MarkFlagRequired("prefix"); err != nil {
+		log.Fatal().Err(err).Msg("")
+	}
+	apiKeysCmd.AddCommand(deleteAPIKeyCmd)
+}
+
+var apiKeysCmd = &cobra.Command{
+	Use:     "apikeys",
+	Short:   "Handle the Api keys in Headscale",
+	Aliases: []string{"apikey", "api"},
+}
+
+var listAPIKeys = &cobra.Command{
+	Use:     "list",
+	Short:   "List the Api keys for headscale",
+	Aliases: []string{"ls", "show"},
+	Run: func(cmd *cobra.Command, args []string) {
+		output, _ := cmd.Flags().GetString("output")
+
+		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		defer cancel()
+		defer conn.Close()
+
+		request := &v1.ListApiKeysRequest{}
+
+		response, err := client.ListApiKeys(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error getting the list of keys: %s", err),
+				output,
+			)
+
+			return
+		}
+
+		if output != "" {
+			SuccessOutput(response.GetApiKeys(), "", output)
+
+			return
+		}
+
+		tableData := pterm.TableData{
+			{"ID", "Prefix", "Expiration", "Created"},
+		}
+		for _, key := range response.GetApiKeys() {
+			expiration := "-"
+
+			if key.GetExpiration() != nil {
+				expiration = ColourTime(key.GetExpiration().AsTime())
+			}
+
+			tableData = append(tableData, []string{
+				strconv.FormatUint(key.GetId(), util.Base10),
+				key.GetPrefix(),
+				expiration,
+				key.GetCreatedAt().AsTime().Format(HeadscaleDateTimeFormat),
+			})
+
+		}
+		err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Failed to render pterm table: %s", err),
+				output,
+			)
+
+			return
+		}
+	},
+}
+
+var createAPIKeyCmd = &cobra.Command{
+	Use:   "create",
+	Short: "Creates a new Api key",
+	Long: `
+Creates a new Api key, the Api key is only visible on creation
+and cannot be retrieved again.
+If you loose a key, create a new one and revoke (expire) the old one.`,
+	Aliases: []string{"c", "new"},
+	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")
+
+		duration, err := model.ParseDuration(durationStr)
+		if err != nil {
+			ErrorOutput(
+				err,
+				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()
+		defer cancel()
+		defer conn.Close()
+
+		response, err := client.CreateApiKey(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Cannot create Api Key: %s\n", err),
+				output,
+			)
+
+			return
+		}
+
+		SuccessOutput(response.GetApiKey(), response.GetApiKey(), output)
+	},
+}
+
+var expireAPIKeyCmd = &cobra.Command{
+	Use:     "expire",
+	Short:   "Expire an ApiKey",
+	Aliases: []string{"revoke", "exp", "e"},
+	Run: func(cmd *cobra.Command, args []string) {
+		output, _ := cmd.Flags().GetString("output")
+
+		prefix, err := cmd.Flags().GetString("prefix")
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error getting prefix from CLI flag: %s", err),
+				output,
+			)
+
+			return
+		}
+
+		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		defer cancel()
+		defer conn.Close()
+
+		request := &v1.ExpireApiKeyRequest{
+			Prefix: prefix,
+		}
+
+		response, err := client.ExpireApiKey(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Cannot expire Api Key: %s\n", err),
+				output,
+			)
+
+			return
+		}
+
+		SuccessOutput(response, "Key expired", output)
+	},
+}
+
+var deleteAPIKeyCmd = &cobra.Command{
+	Use:     "delete",
+	Short:   "Delete an ApiKey",
+	Aliases: []string{"remove", "del"},
+	Run: func(cmd *cobra.Command, args []string) {
+		output, _ := cmd.Flags().GetString("output")
+
+		prefix, err := cmd.Flags().GetString("prefix")
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error getting prefix from CLI flag: %s", err),
+				output,
+			)
+
+			return
+		}
+
+		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		defer cancel()
+		defer conn.Close()
+
+		request := &v1.DeleteApiKeyRequest{
+			Prefix: prefix,
+		}
+
+		response, err := client.DeleteApiKey(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Cannot delete Api Key: %s\n", err),
+				output,
+			)
+
+			return
+		}
+
+		SuccessOutput(response, "Key deleted", output)
+	},
+}

cmd/headscale/cli/configtest.go

@@ -0,0 +1,22 @@
+package cli
+
+import (
+	"github.com/rs/zerolog/log"
+	"github.com/spf13/cobra"
+)
+
+func init() {
+	rootCmd.AddCommand(configTestCmd)
+}
+
+var configTestCmd = &cobra.Command{
+	Use:   "configtest",
+	Short: "Test the configuration.",
+	Long:  "Run a test of the configuration and exit.",
+	Run: func(cmd *cobra.Command, args []string) {
+		_, err := getHeadscaleApp()
+		if err != nil {
+			log.Fatal().Caller().Err(err).Msg("Error initializing")
+		}
+	},
+}

cmd/headscale/cli/debug.go

@@ -0,0 +1,140 @@
+package cli
+
+import (
+	"fmt"
+
+	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/rs/zerolog/log"
+	"github.com/spf13/cobra"
+	"google.golang.org/grpc/status"
+	"tailscale.com/types/key"
+)
+
+const (
+	errPreAuthKeyMalformed = Error("key is malformed. expected 64 hex characters with `nodekey` prefix")
+)
+
+// Error is used to compare errors as per https://dave.cheney.net/2016/04/07/constant-errors
+type Error string
+
+func (e Error) Error() string { return string(e) }
+
+func init() {
+	rootCmd.AddCommand(debugCmd)
+
+	createNodeCmd.Flags().StringP("name", "", "", "Name")
+	err := createNodeCmd.MarkFlagRequired("name")
+	if err != nil {
+		log.Fatal().Err(err).Msg("")
+	}
+	createNodeCmd.Flags().StringP("user", "u", "", "User")
+
+	createNodeCmd.Flags().StringP("namespace", "n", "", "User")
+	createNodeNamespaceFlag := createNodeCmd.Flags().Lookup("namespace")
+	createNodeNamespaceFlag.Deprecated = deprecateNamespaceMessage
+	createNodeNamespaceFlag.Hidden = true
+
+	err = createNodeCmd.MarkFlagRequired("user")
+	if err != nil {
+		log.Fatal().Err(err).Msg("")
+	}
+	createNodeCmd.Flags().StringP("key", "k", "", "Key")
+	err = createNodeCmd.MarkFlagRequired("key")
+	if err != nil {
+		log.Fatal().Err(err).Msg("")
+	}
+	createNodeCmd.Flags().
+		StringSliceP("route", "r", []string{}, "List (or repeated flags) of routes to advertise")
+
+	debugCmd.AddCommand(createNodeCmd)
+}
+
+var debugCmd = &cobra.Command{
+	Use:   "debug",
+	Short: "debug and testing commands",
+	Long:  "debug contains extra commands used for debugging and testing headscale",
+}
+
+var createNodeCmd = &cobra.Command{
+	Use:   "create-node",
+	Short: "Create a node that can be registered with `nodes register <>` command",
+	Run: func(cmd *cobra.Command, args []string) {
+		output, _ := cmd.Flags().GetString("output")
+
+		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()
+		defer cancel()
+		defer conn.Close()
+
+		name, err := cmd.Flags().GetString("name")
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error getting node from flag: %s", err),
+				output,
+			)
+
+			return
+		}
+
+		machineKey, 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))
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Failed to parse machine key from flag: %s", err),
+				output,
+			)
+
+			return
+		}
+
+		routes, err := cmd.Flags().GetStringSlice("route")
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error getting routes from flag: %s", err),
+				output,
+			)
+
+			return
+		}
+
+		request := &v1.DebugCreateNodeRequest{
+			Key:    machineKey,
+			Name:   name,
+			User:   user,
+			Routes: routes,
+		}
+
+		response, err := client.DebugCreateNode(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Cannot create node: %s", status.Convert(err).Message()),
+				output,
+			)
+
+			return
+		}
+
+		SuccessOutput(response.GetNode(), "Node created", output)
+	},
+}

cmd/headscale/cli/dump_config.go

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

cmd/headscale/cli/generate.go

@@ -0,0 +1,42 @@
+package cli
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+	"tailscale.com/types/key"
+)
+
+func init() {
+	rootCmd.AddCommand(generateCmd)
+	generateCmd.AddCommand(generatePrivateKeyCmd)
+}
+
+var generateCmd = &cobra.Command{
+	Use:     "generate",
+	Short:   "Generate commands",
+	Aliases: []string{"gen"},
+}
+
+var generatePrivateKeyCmd = &cobra.Command{
+	Use:   "private-key",
+	Short: "Generate a private key for the headscale server",
+	Run: func(cmd *cobra.Command, args []string) {
+		output, _ := cmd.Flags().GetString("output")
+		machineKey := key.NewMachine()
+
+		machineKeyStr, err := machineKey.MarshalText()
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error getting machine key from flag: %s", err),
+				output,
+			)
+		}
+
+		SuccessOutput(map[string]string{
+			"private_key": string(machineKeyStr),
+		},
+			string(machineKeyStr), output)
+	},
+}

cmd/headscale/cli/mockoidc.go

@@ -0,0 +1,115 @@
+package cli
+
+import (
+	"fmt"
+	"net"
+	"os"
+	"strconv"
+	"time"
+
+	"github.com/oauth2-proxy/mockoidc"
+	"github.com/rs/zerolog/log"
+	"github.com/spf13/cobra"
+)
+
+const (
+	errMockOidcClientIDNotDefined     = Error("MOCKOIDC_CLIENT_ID not defined")
+	errMockOidcClientSecretNotDefined = Error("MOCKOIDC_CLIENT_SECRET not defined")
+	errMockOidcPortNotDefined         = Error("MOCKOIDC_PORT not defined")
+	refreshTTL                        = 60 * time.Minute
+)
+
+var accessTTL = 2 * time.Minute
+
+func init() {
+	rootCmd.AddCommand(mockOidcCmd)
+}
+
+var mockOidcCmd = &cobra.Command{
+	Use:   "mockoidc",
+	Short: "Runs a mock OIDC server for testing",
+	Long:  "This internal command runs a OpenID Connect for testing purposes",
+	Run: func(cmd *cobra.Command, args []string) {
+		err := mockOIDC()
+		if err != nil {
+			log.Error().Err(err).Msgf("Error running mock OIDC server")
+			os.Exit(1)
+		}
+	},
+}
+
+func mockOIDC() error {
+	clientID := os.Getenv("MOCKOIDC_CLIENT_ID")
+	if clientID == "" {
+		return errMockOidcClientIDNotDefined
+	}
+	clientSecret := os.Getenv("MOCKOIDC_CLIENT_SECRET")
+	if clientSecret == "" {
+		return errMockOidcClientSecretNotDefined
+	}
+	addrStr := os.Getenv("MOCKOIDC_ADDR")
+	if addrStr == "" {
+		return errMockOidcPortNotDefined
+	}
+	portStr := os.Getenv("MOCKOIDC_PORT")
+	if portStr == "" {
+		return errMockOidcPortNotDefined
+	}
+	accessTTLOverride := os.Getenv("MOCKOIDC_ACCESS_TTL")
+	if accessTTLOverride != "" {
+		newTTL, err := time.ParseDuration(accessTTLOverride)
+		if err != nil {
+			return err
+		}
+		accessTTL = newTTL
+	}
+
+	log.Info().Msgf("Access token TTL: %s", accessTTL)
+
+	port, err := strconv.Atoi(portStr)
+	if err != nil {
+		return err
+	}
+
+	mock, err := getMockOIDC(clientID, clientSecret)
+	if err != nil {
+		return err
+	}
+
+	listener, err := net.Listen("tcp", fmt.Sprintf("%s:%d", addrStr, port))
+	if err != nil {
+		return err
+	}
+
+	err = mock.Start(listener, nil)
+	if err != nil {
+		return err
+	}
+	log.Info().Msgf("Mock OIDC server listening on %s", listener.Addr().String())
+	log.Info().Msgf("Issuer: %s", mock.Issuer())
+	c := make(chan struct{})
+	<-c
+
+	return nil
+}
+
+func getMockOIDC(clientID string, clientSecret string) (*mockoidc.MockOIDC, error) {
+	keypair, err := mockoidc.NewKeypair(nil)
+	if err != nil {
+		return nil, err
+	}
+
+	mock := mockoidc.MockOIDC{
+		ClientID:                      clientID,
+		ClientSecret:                  clientSecret,
+		AccessTTL:                     accessTTL,
+		RefreshTTL:                    refreshTTL,
+		CodeChallengeMethodsSupported: []string{"plain", "S256"},
+		Keypair:                       keypair,
+		SessionStore:                  mockoidc.NewSessionStore(),
+		UserQueue:                     &mockoidc.UserQueue{},
+		ErrorQueue:                    &mockoidc.ErrorQueue{},
+	}
+
+	return &mock, nil
+}

cmd/headscale/cli/namespaces.go

@@ -1,102 +0,0 @@
-package cli
-
-import (
-	"fmt"
-	"log"
-	"strings"
-
-	"github.com/spf13/cobra"
-)
-
-func init() {
-	rootCmd.AddCommand(namespaceCmd)
-	namespaceCmd.AddCommand(createNamespaceCmd)
-	namespaceCmd.AddCommand(listNamespacesCmd)
-	namespaceCmd.AddCommand(destroyNamespaceCmd)
-}
-
-var namespaceCmd = &cobra.Command{
-	Use:   "namespaces",
-	Short: "Manage the namespaces of Headscale",
-}
-
-var createNamespaceCmd = &cobra.Command{
-	Use:   "create NAME",
-	Short: "Creates a new namespace",
-	Args: func(cmd *cobra.Command, args []string) error {
-		if len(args) < 1 {
-			return fmt.Errorf("Missing parameters")
-		}
-		return nil
-	},
-	Run: func(cmd *cobra.Command, args []string) {
-		o, _ := cmd.Flags().GetString("output")
-		h, err := getHeadscaleApp()
-		if err != nil {
-			log.Fatalf("Error initializing: %s", err)
-		}
-		namespace, err := h.CreateNamespace(args[0])
-		if strings.HasPrefix(o, "json") {
-			JsonOutput(namespace, err, o)
-			return
-		}
-		if err != nil {
-			fmt.Printf("Error creating namespace: %s\n", err)
-			return
-		}
-		fmt.Printf("Namespace created\n")
-	},
-}
-
-var destroyNamespaceCmd = &cobra.Command{
-	Use:   "destroy NAME",
-	Short: "Destroys a namespace",
-	Args: func(cmd *cobra.Command, args []string) error {
-		if len(args) < 1 {
-			return fmt.Errorf("Missing parameters")
-		}
-		return nil
-	},
-	Run: func(cmd *cobra.Command, args []string) {
-		o, _ := cmd.Flags().GetString("output")
-		h, err := getHeadscaleApp()
-		if err != nil {
-			log.Fatalf("Error initializing: %s", err)
-		}
-		err = h.DestroyNamespace(args[0])
-		if strings.HasPrefix(o, "json") {
-			JsonOutput(map[string]string{"Result": "Namespace destroyed"}, err, o)
-			return
-		}
-		if err != nil {
-			fmt.Printf("Error destroying namespace: %s\n", err)
-			return
-		}
-		fmt.Printf("Namespace destroyed\n")
-	},
-}
-
-var listNamespacesCmd = &cobra.Command{
-	Use:   "list",
-	Short: "List all the namespaces",
-	Run: func(cmd *cobra.Command, args []string) {
-		o, _ := cmd.Flags().GetString("output")
-		h, err := getHeadscaleApp()
-		if err != nil {
-			log.Fatalf("Error initializing: %s", err)
-		}
-		namespaces, err := h.ListNamespaces()
-		if strings.HasPrefix(o, "json") {
-			JsonOutput(namespaces, err, o)
-			return
-		}
-		if err != nil {
-			fmt.Println(err)
-			return
-		}
-		fmt.Printf("ID\tName\n")
-		for _, n := range *namespaces {
-			fmt.Printf("%d\t%s\n", n.ID, n.Name)
-		}
-	},
-}

cmd/headscale/cli/nodes.go

@@ -3,144 +3,731 @@ package cli
 import (
 	"fmt"
 	"log"
+	"net/netip"
 	"strconv"
 	"strings"
 	"time"
 
 	survey "github.com/AlecAivazis/survey/v2"
+	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/juanfont/headscale/hscontrol/util"
+	"github.com/pterm/pterm"
 	"github.com/spf13/cobra"
+	"google.golang.org/grpc/status"
+	"tailscale.com/types/key"
 )
 
 func init() {
 	rootCmd.AddCommand(nodeCmd)
-	nodeCmd.PersistentFlags().StringP("namespace", "n", "", "Namespace")
-	err := nodeCmd.MarkPersistentFlagRequired("namespace")
+	listNodesCmd.Flags().StringP("user", "u", "", "Filter by user")
+	listNodesCmd.Flags().BoolP("tags", "t", false, "Show tags")
+
+	listNodesCmd.Flags().StringP("namespace", "n", "", "User")
+	listNodesNamespaceFlag := listNodesCmd.Flags().Lookup("namespace")
+	listNodesNamespaceFlag.Deprecated = deprecateNamespaceMessage
+	listNodesNamespaceFlag.Hidden = true
+
+	nodeCmd.AddCommand(listNodesCmd)
+
+	registerNodeCmd.Flags().StringP("user", "u", "", "User")
+
+	registerNodeCmd.Flags().StringP("namespace", "n", "", "User")
+	registerNodeNamespaceFlag := registerNodeCmd.Flags().Lookup("namespace")
+	registerNodeNamespaceFlag.Deprecated = deprecateNamespaceMessage
+	registerNodeNamespaceFlag.Hidden = true
+
+	err := registerNodeCmd.MarkFlagRequired("user")
+	if err != nil {
+		log.Fatalf(err.Error())
+	}
+	registerNodeCmd.Flags().StringP("key", "k", "", "Key")
+	err = registerNodeCmd.MarkFlagRequired("key")
 	if err != nil {
 		log.Fatalf(err.Error())
 	}
-	nodeCmd.AddCommand(listNodesCmd)
 	nodeCmd.AddCommand(registerNodeCmd)
+
+	expireNodeCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
+	err = expireNodeCmd.MarkFlagRequired("identifier")
+	if err != nil {
+		log.Fatalf(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())
+	}
+	nodeCmd.AddCommand(renameNodeCmd)
+
+	deleteNodeCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
+	err = deleteNodeCmd.MarkFlagRequired("identifier")
+	if err != nil {
+		log.Fatalf(err.Error())
+	}
 	nodeCmd.AddCommand(deleteNodeCmd)
+
+	moveNodeCmd.Flags().Uint64P("identifier", "i", 0, "Node identifier (ID)")
+
+	err = moveNodeCmd.MarkFlagRequired("identifier")
+	if err != nil {
+		log.Fatalf(err.Error())
+	}
+
+	moveNodeCmd.Flags().StringP("user", "u", "", "New user")
+
+	moveNodeCmd.Flags().StringP("namespace", "n", "", "User")
+	moveNodeNamespaceFlag := moveNodeCmd.Flags().Lookup("namespace")
+	moveNodeNamespaceFlag.Deprecated = deprecateNamespaceMessage
+	moveNodeNamespaceFlag.Hidden = true
+
+	err = moveNodeCmd.MarkFlagRequired("user")
+	if err != nil {
+		log.Fatalf(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")
+	nodeCmd.AddCommand(tagCmd)
+
+	nodeCmd.AddCommand(backfillNodeIPsCmd)
 }
 
 var nodeCmd = &cobra.Command{
-	Use:   "nodes",
-	Short: "Manage the nodes of Headscale",
+	Use:     "nodes",
+	Short:   "Manage the nodes of Headscale",
+	Aliases: []string{"node", "machine", "machines"},
 }
 
 var registerNodeCmd = &cobra.Command{
-	Use:   "register machineID",
-	Short: "Registers a machine to your network",
-	Args: func(cmd *cobra.Command, args []string) error {
-		if len(args) < 1 {
-			return fmt.Errorf("Missing parameters")
-		}
-		return nil
-	},
+	Use:   "register",
+	Short: "Registers a node to your network",
 	Run: func(cmd *cobra.Command, args []string) {
-		n, err := cmd.Flags().GetString("namespace")
+		output, _ := cmd.Flags().GetString("output")
+		user, err := cmd.Flags().GetString("user")
 		if err != nil {
-			log.Fatalf("Error getting namespace: %s", err)
-		}
-		o, _ := cmd.Flags().GetString("output")
+			ErrorOutput(err, fmt.Sprintf("Error getting user: %s", err), output)
 
-		h, err := getHeadscaleApp()
-		if err != nil {
-			log.Fatalf("Error initializing: %s", err)
-		}
-		m, err := h.RegisterMachine(args[0], n)
-		if strings.HasPrefix(o, "json") {
-			JsonOutput(m, err, o)
 			return
 		}
+
+		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		defer cancel()
+		defer conn.Close()
+
+		machineKey, err := cmd.Flags().GetString("key")
 		if err != nil {
-			fmt.Printf("Cannot register machine: %s\n", err)
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error getting node key from flag: %s", err),
+				output,
+			)
+
 			return
 		}
-		fmt.Printf("Machine registered\n")
+
+		request := &v1.RegisterNodeRequest{
+			Key:  machineKey,
+			User: user,
+		}
+
+		response, err := client.RegisterNode(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf(
+					"Cannot register node: %s\n",
+					status.Convert(err).Message(),
+				),
+				output,
+			)
+
+			return
+		}
+
+		SuccessOutput(
+			response.GetNode(),
+			fmt.Sprintf("Node %s registered", response.GetNode().GetGivenName()), output)
 	},
 }
 
 var listNodesCmd = &cobra.Command{
-	Use:   "list",
-	Short: "List the nodes in a given namespace",
+	Use:     "list",
+	Short:   "List nodes",
+	Aliases: []string{"ls", "show"},
 	Run: func(cmd *cobra.Command, args []string) {
-		n, err := cmd.Flags().GetString("namespace")
+		output, _ := cmd.Flags().GetString("output")
+		user, err := cmd.Flags().GetString("user")
 		if err != nil {
-			log.Fatalf("Error getting namespace: %s", err)
-		}
-		o, _ := cmd.Flags().GetString("output")
+			ErrorOutput(err, fmt.Sprintf("Error getting user: %s", err), output)
 
-		h, err := getHeadscaleApp()
-		if err != nil {
-			log.Fatalf("Error initializing: %s", err)
+			return
 		}
-		machines, err := h.ListMachinesInNamespace(n)
-		if strings.HasPrefix(o, "json") {
-			JsonOutput(machines, err, o)
+		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()
+		defer cancel()
+		defer conn.Close()
+
+		request := &v1.ListNodesRequest{
+			User: user,
+		}
+
+		response, err := client.ListNodes(ctx, request)
 		if err != nil {
-			log.Fatalf("Error getting nodes: %s", err)
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Cannot get nodes: %s", status.Convert(err).Message()),
+				output,
+			)
+
+			return
 		}
 
-		fmt.Printf("ID\tname\t\tlast seen\t\tephemeral\n")
-		for _, m := range *machines {
-			var ephemeral bool
-			if m.AuthKey != nil && m.AuthKey.Ephemeral {
-				ephemeral = true
-			}
-			var lastSeen time.Time
-			if m.LastSeen != nil {
-				lastSeen = *m.LastSeen
-			}
-			fmt.Printf("%d\t%s\t%s\t%t\n", m.ID, m.Name, lastSeen.Format("2006-01-02 15:04:05"), ephemeral)
+		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()
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Failed to render pterm table: %s", err),
+				output,
+			)
+
+			return
+		}
+	},
+}
+
+var expireNodeCmd = &cobra.Command{
+	Use:     "expire",
+	Short:   "Expire (log out) a node in your network",
+	Long:    "Expiring a node will keep the node in the database and force it to reauthenticate.",
+	Aliases: []string{"logout", "exp", "e"},
+	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 := getHeadscaleCLIClient()
+		defer cancel()
+		defer conn.Close()
+
+		request := &v1.ExpireNodeRequest{
+			NodeId: identifier,
+		}
+
+		response, err := client.ExpireNode(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf(
+					"Cannot expire node: %s\n",
+					status.Convert(err).Message(),
+				),
+				output,
+			)
+
+			return
+		}
+
+		SuccessOutput(response.GetNode(), "Node expired", output)
+	},
+}
+
+var renameNodeCmd = &cobra.Command{
+	Use:   "rename NEW_NAME",
+	Short: "Renames a node in your network",
+	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 := getHeadscaleCLIClient()
+		defer cancel()
+		defer conn.Close()
+
+		newName := ""
+		if len(args) > 0 {
+			newName = args[0]
+		}
+		request := &v1.RenameNodeRequest{
+			NodeId:  identifier,
+			NewName: newName,
+		}
+
+		response, err := client.RenameNode(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf(
+					"Cannot rename node: %s\n",
+					status.Convert(err).Message(),
+				),
+				output,
+			)
+
+			return
+		}
+
+		SuccessOutput(response.GetNode(), "Node renamed", output)
 	},
 }
 
 var deleteNodeCmd = &cobra.Command{
-	Use:   "delete ID",
-	Short: "Delete a node",
-	Args: func(cmd *cobra.Command, args []string) error {
-		if len(args) < 1 {
-			return fmt.Errorf("Missing parameters")
-		}
-		return nil
-	},
+	Use:     "delete",
+	Short:   "Delete a node",
+	Aliases: []string{"del"},
 	Run: func(cmd *cobra.Command, args []string) {
-		h, err := getHeadscaleApp()
+		output, _ := cmd.Flags().GetString("output")
+
+		identifier, err := cmd.Flags().GetUint64("identifier")
 		if err != nil {
-			log.Fatalf("Error initializing: %s", err)
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error converting ID to integer: %s", err),
+				output,
+			)
+
+			return
 		}
-		id, err := strconv.Atoi(args[0])
-		if err != nil {
-			log.Fatalf("Error converting ID to integer: %s", err)
+
+		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		defer cancel()
+		defer conn.Close()
+
+		getRequest := &v1.GetNodeRequest{
+			NodeId: identifier,
 		}
-		m, err := h.GetMachineByID(uint64(id))
+
+		getResponse, err := client.GetNode(ctx, getRequest)
 		if err != nil {
-			log.Fatalf("Error getting node: %s", err)
+			ErrorOutput(
+				err,
+				fmt.Sprintf(
+					"Error getting node node: %s",
+					status.Convert(err).Message(),
+				),
+				output,
+			)
+
+			return
+		}
+
+		deleteRequest := &v1.DeleteNodeRequest{
+			NodeId: identifier,
 		}
 
+		confirm := false
+		force, _ := cmd.Flags().GetBool("force")
+		if !force {
+			prompt := &survey.Confirm{
+				Message: fmt.Sprintf(
+					"Do you want to remove the node %s?",
+					getResponse.GetNode().GetName(),
+				),
+			}
+			err = survey.AskOne(prompt, &confirm)
+			if err != nil {
+				return
+			}
+		}
+
+		if confirm || force {
+			response, err := client.DeleteNode(ctx, deleteRequest)
+			if output != "" {
+				SuccessOutput(response, "", output)
+
+				return
+			}
+			if err != nil {
+				ErrorOutput(
+					err,
+					fmt.Sprintf(
+						"Error deleting node: %s",
+						status.Convert(err).Message(),
+					),
+					output,
+				)
+
+				return
+			}
+			SuccessOutput(
+				map[string]string{"Result": "Node deleted"},
+				"Node deleted",
+				output,
+			)
+		} else {
+			SuccessOutput(map[string]string{"Result": "Node not deleted"}, "Node not deleted", output)
+		}
+	},
+}
+
+var moveNodeCmd = &cobra.Command{
+	Use:     "move",
+	Short:   "Move node to another user",
+	Aliases: []string{"mv"},
+	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
+		}
+
+		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()
+		defer cancel()
+		defer conn.Close()
+
+		getRequest := &v1.GetNodeRequest{
+			NodeId: identifier,
+		}
+
+		_, err = client.GetNode(ctx, getRequest)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf(
+					"Error getting node: %s",
+					status.Convert(err).Message(),
+				),
+				output,
+			)
+
+			return
+		}
+
+		moveRequest := &v1.MoveNodeRequest{
+			NodeId: identifier,
+			User:   user,
+		}
+
+		moveResponse, err := client.MoveNode(ctx, moveRequest)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf(
+					"Error moving node: %s",
+					status.Convert(err).Message(),
+				),
+				output,
+			)
+
+			return
+		}
+
+		SuccessOutput(moveResponse.GetNode(), "Node moved to another user", output)
+	},
+}
+
+var backfillNodeIPsCmd = &cobra.Command{
+	Use:   "backfillips",
+	Short: "Backfill IPs missing from nodes",
+	Long: `
+Backfill IPs can be used to add/remove IPs from nodes
+based on the current configuration of Headscale.
+
+If there are nodes that does not have IPv4 or IPv6
+even if prefixes for both are configured in the config,
+this command can be used to assign IPs of the sort to
+all nodes that are missing.
+
+If you remove IPv4 or IPv6 prefixes from the config,
+it can be run to remove the IPs that should no longer
+be assigned to nodes.`,
+	Run: func(cmd *cobra.Command, args []string) {
+		var err error
+		output, _ := cmd.Flags().GetString("output")
+
 		confirm := false
 		prompt := &survey.Confirm{
-			Message: fmt.Sprintf("Do you want to remove the node %s?", m.Name),
+			Message: "Are you sure that you want to assign/remove IPs to/from nodes?",
 		}
 		err = survey.AskOne(prompt, &confirm)
 		if err != nil {
 			return
 		}
-
 		if confirm {
-			err = h.DeleteMachine(m)
+			ctx, client, conn, cancel := getHeadscaleCLIClient()
+			defer cancel()
+			defer conn.Close()
+
+			changes, err := client.BackfillNodeIPs(ctx, &v1.BackfillNodeIPsRequest{Confirmed: confirm})
 			if err != nil {
-				log.Fatalf("Error deleting node: %s", err)
+				ErrorOutput(
+					err,
+					fmt.Sprintf(
+						"Error backfilling IPs: %s",
+						status.Convert(err).Message(),
+					),
+					output,
+				)
+
+				return
 			}
-			fmt.Printf("Node deleted\n")
-		} else {
-			fmt.Printf("Node not deleted\n")
+
+			SuccessOutput(changes, "Node IPs backfilled successfully", output)
+		}
+	},
+}
+
+func nodesToPtables(
+	currentUser string,
+	showTags bool,
+	nodes []*v1.Node,
+) (pterm.TableData, error) {
+	tableHeader := []string{
+		"ID",
+		"Hostname",
+		"Name",
+		"MachineKey",
+		"NodeKey",
+		"User",
+		"IP addresses",
+		"Ephemeral",
+		"Last seen",
+		"Expiration",
+		"Connected",
+		"Expired",
+	}
+	if showTags {
+		tableHeader = append(tableHeader, []string{
+			"ForcedTags",
+			"InvalidTags",
+			"ValidTags",
+		}...)
+	}
+	tableData := pterm.TableData{tableHeader}
+
+	for _, node := range nodes {
+		var ephemeral bool
+		if node.GetPreAuthKey() != nil && node.GetPreAuthKey().GetEphemeral() {
+			ephemeral = true
+		}
+
+		var lastSeen time.Time
+		var lastSeenTime string
+		if node.GetLastSeen() != nil {
+			lastSeen = node.GetLastSeen().AsTime()
+			lastSeenTime = lastSeen.Format("2006-01-02 15:04:05")
+		}
+
+		var expiry time.Time
+		var expiryTime string
+		if node.GetExpiry() != nil {
+			expiry = node.GetExpiry().AsTime()
+			expiryTime = expiry.Format("2006-01-02 15:04:05")
+		} else {
+			expiryTime = "N/A"
+		}
+
+		var machineKey key.MachinePublic
+		err := machineKey.UnmarshalText(
+			[]byte(node.GetMachineKey()),
+		)
+		if err != nil {
+			machineKey = key.MachinePublic{}
+		}
+
+		var nodeKey key.NodePublic
+		err = nodeKey.UnmarshalText(
+			[]byte(node.GetNodeKey()),
+		)
+		if err != nil {
+			return nil, err
+		}
+
+		var online string
+		if node.GetOnline() {
+			online = pterm.LightGreen("online")
+		} else {
+			online = pterm.LightRed("offline")
+		}
+
+		var expired string
+		if expiry.IsZero() || expiry.After(time.Now()) {
+			expired = pterm.LightGreen("no")
+		} else {
+			expired = pterm.LightRed("yes")
+		}
+
+		var forcedTags string
+		for _, tag := range node.GetForcedTags() {
+			forcedTags += "," + tag
+		}
+		forcedTags = strings.TrimLeft(forcedTags, ",")
+		var invalidTags string
+		for _, tag := range node.GetInvalidTags() {
+			if !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) {
+				validTags += "," + pterm.LightGreen(tag)
+			}
+		}
+		validTags = strings.TrimLeft(validTags, ",")
+
+		var user string
+		if currentUser == "" || (currentUser == node.GetUser().GetName()) {
+			user = pterm.LightMagenta(node.GetUser().GetName())
+		} else {
+			// Shared into this user
+			user = pterm.LightYellow(node.GetUser().GetName())
+		}
+
+		var IPV4Address string
+		var IPV6Address string
+		for _, addr := range node.GetIpAddresses() {
+			if netip.MustParseAddr(addr).Is4() {
+				IPV4Address = addr
+			} else {
+				IPV6Address = addr
+			}
+		}
+
+		nodeData := []string{
+			strconv.FormatUint(node.GetId(), util.Base10),
+			node.GetName(),
+			node.GetGivenName(),
+			machineKey.ShortString(),
+			nodeKey.ShortString(),
+			user,
+			strings.Join([]string{IPV4Address, IPV6Address}, ", "),
+			strconv.FormatBool(ephemeral),
+			lastSeenTime,
+			expiryTime,
+			online,
+			expired,
+		}
+		if showTags {
+			nodeData = append(nodeData, []string{forcedTags, invalidTags, validTags}...)
+		}
+		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()
+		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
+		}
+		tagsToSet, err := cmd.Flags().GetStringSlice("tags")
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error retrieving list of tags to add to node, %v", err),
+				output,
+			)
+
+			return
+		}
+
+		// Sending tags to node
+		request := &v1.SetTagsRequest{
+			NodeId: identifier,
+			Tags:   tagsToSet,
+		}
+		resp, err := client.SetTags(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error while sending tags to headscale: %s", err),
+				output,
+			)
+
+			return
+		}
+
+		if resp != nil {
+			SuccessOutput(
+				resp.GetNode(),
+				"Node updated",
+				output,
+			)
 		}
 	},
 }

cmd/headscale/cli/preauthkeys.go

@@ -2,120 +2,255 @@ package cli
 
 import (
 	"fmt"
-	"log"
+	"strconv"
 	"strings"
 	"time"
 
-	"github.com/hako/durafmt"
+	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/prometheus/common/model"
+	"github.com/pterm/pterm"
+	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
+	"google.golang.org/protobuf/types/known/timestamppb"
+)
+
+const (
+	DefaultPreAuthKeyExpiry = "1h"
 )
 
 func init() {
 	rootCmd.AddCommand(preauthkeysCmd)
-	preauthkeysCmd.PersistentFlags().StringP("namespace", "n", "", "Namespace")
-	err := preauthkeysCmd.MarkPersistentFlagRequired("namespace")
+	preauthkeysCmd.PersistentFlags().StringP("user", "u", "", "User")
+
+	preauthkeysCmd.PersistentFlags().StringP("namespace", "n", "", "User")
+	pakNamespaceFlag := preauthkeysCmd.PersistentFlags().Lookup("namespace")
+	pakNamespaceFlag.Deprecated = deprecateNamespaceMessage
+	pakNamespaceFlag.Hidden = true
+
+	err := preauthkeysCmd.MarkPersistentFlagRequired("user")
 	if err != nil {
-		log.Fatalf(err.Error())
+		log.Fatal().Err(err).Msg("")
 	}
 	preauthkeysCmd.AddCommand(listPreAuthKeys)
 	preauthkeysCmd.AddCommand(createPreAuthKeyCmd)
-	createPreAuthKeyCmd.PersistentFlags().Bool("reusable", false, "Make the preauthkey reusable")
-	createPreAuthKeyCmd.PersistentFlags().Bool("ephemeral", false, "Preauthkey for ephemeral nodes")
-	createPreAuthKeyCmd.Flags().StringP("expiration", "e", "", "Human-readable expiration of the key (30m, 24h, 365d...)")
+	preauthkeysCmd.AddCommand(expirePreAuthKeyCmd)
+	createPreAuthKeyCmd.PersistentFlags().
+		Bool("reusable", false, "Make the preauthkey reusable")
+	createPreAuthKeyCmd.PersistentFlags().
+		Bool("ephemeral", false, "Preauthkey for ephemeral nodes")
+	createPreAuthKeyCmd.Flags().
+		StringP("expiration", "e", DefaultPreAuthKeyExpiry, "Human-readable expiration of the key (e.g. 30m, 24h)")
+	createPreAuthKeyCmd.Flags().
+		StringSlice("tags", []string{}, "Tags to automatically assign to node")
 }
 
 var preauthkeysCmd = &cobra.Command{
-	Use:   "preauthkeys",
-	Short: "Handle the preauthkeys in Headscale",
+	Use:     "preauthkeys",
+	Short:   "Handle the preauthkeys in Headscale",
+	Aliases: []string{"preauthkey", "authkey", "pre"},
 }
 
 var listPreAuthKeys = &cobra.Command{
-	Use:   "list",
-	Short: "List the preauthkeys for this namespace",
+	Use:     "list",
+	Short:   "List the preauthkeys for this user",
+	Aliases: []string{"ls", "show"},
 	Run: func(cmd *cobra.Command, args []string) {
-		n, err := cmd.Flags().GetString("namespace")
-		if err != nil {
-			log.Fatalf("Error getting namespace: %s", err)
-		}
-		o, _ := cmd.Flags().GetString("output")
+		output, _ := cmd.Flags().GetString("output")
 
-		h, err := getHeadscaleApp()
+		user, err := cmd.Flags().GetString("user")
 		if err != nil {
-			log.Fatalf("Error initializing: %s", err)
-		}
-		keys, err := h.GetPreAuthKeys(n)
-		if strings.HasPrefix(o, "json") {
-			JsonOutput(keys, err, o)
+			ErrorOutput(err, fmt.Sprintf("Error getting user: %s", err), output)
+
 			return
 		}
 
-		if err != nil {
-			fmt.Printf("Error getting the list of keys: %s\n", err)
-			return
+		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		defer cancel()
+		defer conn.Close()
+
+		request := &v1.ListPreAuthKeysRequest{
+			User: user,
 		}
-		for _, k := range *keys {
-			expiration := "-"
-			if k.Expiration != nil {
-				expiration = k.Expiration.Format("2006-01-02 15:04:05")
-			}
 
-			var reusable string
-			if k.Ephemeral {
-				reusable = "N/A"
-			} else {
-				reusable = fmt.Sprintf("%v", k.Reusable)
-			}
-
-			fmt.Printf(
-				"key: %s, namespace: %s, reusable: %s, ephemeral: %v, expiration: %s, created_at: %s\n",
-				k.Key,
-				k.Namespace.Name,
-				reusable,
-				k.Ephemeral,
-				expiration,
-				k.CreatedAt.Format("2006-01-02 15:04:05"),
+		response, err := client.ListPreAuthKeys(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error getting the list of keys: %s", err),
+				output,
 			)
+
+			return
+		}
+
+		if output != "" {
+			SuccessOutput(response.GetPreAuthKeys(), "", output)
+
+			return
+		}
+
+		tableData := pterm.TableData{
+			{
+				"ID",
+				"Key",
+				"Reusable",
+				"Ephemeral",
+				"Used",
+				"Expiration",
+				"Created",
+				"Tags",
+			},
+		}
+		for _, key := range response.GetPreAuthKeys() {
+			expiration := "-"
+			if key.GetExpiration() != nil {
+				expiration = ColourTime(key.GetExpiration().AsTime())
+			}
+
+			aclTags := ""
+
+			for _, tag := range key.GetAclTags() {
+				aclTags += "," + tag
+			}
+
+			aclTags = strings.TrimLeft(aclTags, ",")
+
+			tableData = append(tableData, []string{
+				key.GetId(),
+				key.GetKey(),
+				strconv.FormatBool(key.GetReusable()),
+				strconv.FormatBool(key.GetEphemeral()),
+				strconv.FormatBool(key.GetUsed()),
+				expiration,
+				key.GetCreatedAt().AsTime().Format("2006-01-02 15:04:05"),
+				aclTags,
+			})
+
+		}
+		err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Failed to render pterm table: %s", err),
+				output,
+			)
+
+			return
 		}
 	},
 }
 
 var createPreAuthKeyCmd = &cobra.Command{
-	Use:   "create",
-	Short: "Creates a new preauthkey in the specified namespace",
+	Use:     "create",
+	Short:   "Creates a new preauthkey in the specified user",
+	Aliases: []string{"c", "new"},
 	Run: func(cmd *cobra.Command, args []string) {
-		n, err := cmd.Flags().GetString("namespace")
-		if err != nil {
-			log.Fatalf("Error getting namespace: %s", err)
-		}
-		o, _ := cmd.Flags().GetString("output")
+		output, _ := cmd.Flags().GetString("output")
 
-		h, err := getHeadscaleApp()
+		user, err := cmd.Flags().GetString("user")
 		if err != nil {
-			log.Fatalf("Error initializing: %s", err)
+			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")
 
-		e, _ := cmd.Flags().GetString("expiration")
-		var expiration *time.Time
-		if e != "" {
-			duration, err := durafmt.ParseStringShort(e)
-			if err != nil {
-				log.Fatalf("Error parsing expiration: %s", err)
-			}
-			exp := time.Now().UTC().Add(duration.Duration())
-			expiration = &exp
+		log.Trace().
+			Bool("reusable", reusable).
+			Bool("ephemeral", ephemeral).
+			Str("user", user).
+			Msg("Preparing to create preauthkey")
+
+		request := &v1.CreatePreAuthKeyRequest{
+			User:      user,
+			Reusable:  reusable,
+			Ephemeral: ephemeral,
+			AclTags:   tags,
 		}
 
-		k, err := h.CreatePreAuthKey(n, reusable, ephemeral, expiration)
-		if strings.HasPrefix(o, "json") {
-			JsonOutput(k, err, o)
-			return
-		}
+		durationStr, _ := cmd.Flags().GetString("expiration")
+
+		duration, err := model.ParseDuration(durationStr)
 		if err != nil {
-			fmt.Println(err)
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Could not parse duration: %s\n", err),
+				output,
+			)
+
 			return
 		}
-		fmt.Printf("Key: %s\n", k.Key)
+
+		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()
+		defer cancel()
+		defer conn.Close()
+
+		response, err := client.CreatePreAuthKey(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Cannot create Pre Auth Key: %s\n", err),
+				output,
+			)
+
+			return
+		}
+
+		SuccessOutput(response.GetPreAuthKey(), response.GetPreAuthKey().GetKey(), output)
+	},
+}
+
+var expirePreAuthKeyCmd = &cobra.Command{
+	Use:     "expire KEY",
+	Short:   "Expire a preauthkey",
+	Aliases: []string{"revoke", "exp", "e"},
+	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")
+		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()
+		defer cancel()
+		defer conn.Close()
+
+		request := &v1.ExpirePreAuthKeyRequest{
+			User: user,
+			Key:  args[0],
+		}
+
+		response, err := client.ExpirePreAuthKey(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Cannot expire Pre Auth Key: %s\n", err),
+				output,
+			)
+
+			return
+		}
+
+		SuccessOutput(response, "Key expired", output)
 	},
 }

cmd/headscale/cli/pterm_style.go

@@ -0,0 +1,19 @@
+package cli
+
+import (
+	"time"
+
+	"github.com/pterm/pterm"
+)
+
+func ColourTime(date time.Time) string {
+	dateStr := date.Format("2006-01-02 15:04:05")
+
+	if date.After(time.Now()) {
+		dateStr = pterm.LightGreen(dateStr)
+	} else {
+		dateStr = pterm.LightRed(dateStr)
+	}
+
+	return dateStr
+}

cmd/headscale/cli/root.go

@@ -2,12 +2,90 @@ package cli
 
 import (
 	"fmt"
-	"github.com/spf13/cobra"
 	"os"
+	"runtime"
+
+	"github.com/juanfont/headscale/hscontrol/types"
+	"github.com/rs/zerolog"
+	"github.com/rs/zerolog/log"
+	"github.com/spf13/cobra"
+	"github.com/tcnksm/go-latest"
 )
 
+const (
+	deprecateNamespaceMessage = "use --user"
+)
+
+var cfgFile string = ""
+
 func init() {
-	rootCmd.PersistentFlags().StringP("output", "o", "", "Output format. Empty for human-readable, 'json' or 'json-line'")
+	if len(os.Args) > 1 &&
+		(os.Args[1] == "version" || os.Args[1] == "mockoidc" || os.Args[1] == "completion") {
+		return
+	}
+
+	cobra.OnInitialize(initConfig)
+	rootCmd.PersistentFlags().
+		StringVarP(&cfgFile, "config", "c", "", "config file (default is /etc/headscale/config.yaml)")
+	rootCmd.PersistentFlags().
+		StringP("output", "o", "", "Output format. Empty for human-readable, 'json', 'json-line' or 'yaml'")
+	rootCmd.PersistentFlags().
+		Bool("force", false, "Disable prompts and forces the execution")
+}
+
+func initConfig() {
+	if cfgFile == "" {
+		cfgFile = os.Getenv("HEADSCALE_CONFIG")
+	}
+	if cfgFile != "" {
+		err := types.LoadConfig(cfgFile, true)
+		if err != nil {
+			log.Fatal().Caller().Err(err).Msgf("Error loading config file %s", cfgFile)
+		}
+	} else {
+		err := types.LoadConfig("", false)
+		if err != nil {
+			log.Fatal().Caller().Err(err).Msgf("Error loading config")
+		}
+	}
+
+	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 {
+		log.Logger = log.Output(os.Stdout)
+	}
+
+	if !cfg.DisableUpdateCheck && !machineOutput {
+		if (runtime.GOOS == "linux" || runtime.GOOS == "darwin") &&
+			Version != "dev" {
+			githubTag := &latest.GithubTag{
+				Owner:      "juanfont",
+				Repository: "headscale",
+			}
+			res, err := latest.Check(githubTag, 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,
+				)
+			}
+		}
+	}
 }
 
 var rootCmd = &cobra.Command{
@@ -16,8 +94,7 @@ var rootCmd = &cobra.Command{
 	Long: `
 headscale is an open source implementation of the Tailscale control server
 
-Juan Font Alonso <juanfontalonso@gmail.com> - 2021
-https://gitlab.com/juanfont/headscale`,
+https://github.com/juanfont/headscale`,
 }
 
 func Execute() {

cmd/headscale/cli/routes.go

@@ -3,93 +3,296 @@ package cli
 import (
 	"fmt"
 	"log"
-	"strings"
+	"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)
-	routesCmd.PersistentFlags().StringP("namespace", "n", "", "Namespace")
-	err := routesCmd.MarkPersistentFlagRequired("namespace")
+	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(listRoutesCmd)
 	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",
+	Use:     "routes",
+	Short:   "Manage the routes of Headscale",
+	Aliases: []string{"r", "route"},
 }
 
 var listRoutesCmd = &cobra.Command{
-	Use:   "list NODE",
-	Short: "List the routes exposed by this node",
-	Args: func(cmd *cobra.Command, args []string) error {
-		if len(args) < 1 {
-			return fmt.Errorf("Missing parameters")
-		}
-		return nil
-	},
+	Use:     "list",
+	Short:   "List all routes",
+	Aliases: []string{"ls", "show"},
 	Run: func(cmd *cobra.Command, args []string) {
-		n, err := cmd.Flags().GetString("namespace")
-		if err != nil {
-			log.Fatalf("Error getting namespace: %s", err)
-		}
-		o, _ := cmd.Flags().GetString("output")
+		output, _ := cmd.Flags().GetString("output")
 
-		h, err := getHeadscaleApp()
+		machineID, err := cmd.Flags().GetUint64("identifier")
 		if err != nil {
-			log.Fatalf("Error initializing: %s", err)
-		}
-		routes, err := h.GetNodeRoutes(n, args[0])
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error getting machine id from flag: %s", err),
+				output,
+			)
 
-		if strings.HasPrefix(o, "json") {
-			JsonOutput(routes, err, o)
 			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 {
-			fmt.Println(err)
+			ErrorOutput(err, fmt.Sprintf("Error converting to table: %s", err), output)
+
 			return
 		}
 
-		fmt.Println(routes)
+		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 node-name route",
-	Short: "Allows exposing a route declared by this node to the rest of the nodes",
-	Args: func(cmd *cobra.Command, args []string) error {
-		if len(args) < 2 {
-			return fmt.Errorf("Missing parameters")
-		}
-		return nil
-	},
+	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) {
-		n, err := cmd.Flags().GetString("namespace")
-		if err != nil {
-			log.Fatalf("Error getting namespace: %s", err)
-		}
-		o, _ := cmd.Flags().GetString("output")
+		output, _ := cmd.Flags().GetString("output")
 
-		h, err := getHeadscaleApp()
+		routeID, err := cmd.Flags().GetUint64("route")
 		if err != nil {
-			log.Fatalf("Error initializing: %s", err)
-		}
-		route, err := h.EnableNodeRoute(n, args[0], args[1])
-		if strings.HasPrefix(o, "json") {
-			JsonOutput(route, err, o)
+			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 {
-			fmt.Println(err)
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Cannot enable route %d: %s", routeID, status.Convert(err).Message()),
+				output,
+			)
+
+			return
+		}
+
+		if output != "" {
+			SuccessOutput(response, "", output)
+
 			return
 		}
-		fmt.Printf("Enabled route %s\n", route)
 	},
 }
+
+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/server.go

@@ -1,8 +1,7 @@
 package cli
 
 import (
-	"log"
-
+	"github.com/rs/zerolog/log"
 	"github.com/spf13/cobra"
 )
 
@@ -17,14 +16,14 @@ var serveCmd = &cobra.Command{
 		return nil
 	},
 	Run: func(cmd *cobra.Command, args []string) {
-		h, err := getHeadscaleApp()
+		app, err := getHeadscaleApp()
 		if err != nil {
-			log.Fatalf("Error initializing: %s", err)
+			log.Fatal().Caller().Err(err).Msg("Error initializing")
 		}
-		go h.ExpireEphemeralNodes(5000)
-		err = h.Serve()
+
+		err = app.Serve()
 		if err != nil {
-			log.Fatalf("Error initializing: %s", err)
+			log.Fatal().Caller().Err(err).Msg("Error starting server")
 		}
 	},
 }

cmd/headscale/cli/users.go

@@ -0,0 +1,241 @@
+package cli
+
+import (
+	"errors"
+	"fmt"
+
+	survey "github.com/AlecAivazis/survey/v2"
+	v1 "github.com/juanfont/headscale/gen/go/headscale/v1"
+	"github.com/pterm/pterm"
+	"github.com/rs/zerolog/log"
+	"github.com/spf13/cobra"
+	"google.golang.org/grpc/status"
+)
+
+func init() {
+	rootCmd.AddCommand(userCmd)
+	userCmd.AddCommand(createUserCmd)
+	userCmd.AddCommand(listUsersCmd)
+	userCmd.AddCommand(destroyUserCmd)
+	userCmd.AddCommand(renameUserCmd)
+}
+
+var errMissingParameter = errors.New("missing parameters")
+
+var userCmd = &cobra.Command{
+	Use:     "users",
+	Short:   "Manage the users of Headscale",
+	Aliases: []string{"user", "namespace", "namespaces", "ns"},
+}
+
+var createUserCmd = &cobra.Command{
+	Use:     "create NAME",
+	Short:   "Creates a new user",
+	Aliases: []string{"c", "new"},
+	Args: func(cmd *cobra.Command, args []string) error {
+		if len(args) < 1 {
+			return errMissingParameter
+		}
+
+		return nil
+	},
+	Run: func(cmd *cobra.Command, args []string) {
+		output, _ := cmd.Flags().GetString("output")
+
+		userName := args[0]
+
+		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		defer cancel()
+		defer conn.Close()
+
+		log.Trace().Interface("client", client).Msg("Obtained gRPC client")
+
+		request := &v1.CreateUserRequest{Name: userName}
+
+		log.Trace().Interface("request", request).Msg("Sending CreateUser request")
+		response, err := client.CreateUser(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf(
+					"Cannot create user: %s",
+					status.Convert(err).Message(),
+				),
+				output,
+			)
+
+			return
+		}
+
+		SuccessOutput(response.GetUser(), "User created", output)
+	},
+}
+
+var destroyUserCmd = &cobra.Command{
+	Use:     "destroy 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,
+		}
+
+		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		defer cancel()
+		defer conn.Close()
+
+		_, err := client.GetUser(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Error: %s", status.Convert(err).Message()),
+				output,
+			)
+
+			return
+		}
+
+		confirm := false
+		force, _ := cmd.Flags().GetBool("force")
+		if !force {
+			prompt := &survey.Confirm{
+				Message: fmt.Sprintf(
+					"Do you want to remove the user '%s' and any associated preauthkeys?",
+					userName,
+				),
+			}
+			err := survey.AskOne(prompt, &confirm)
+			if err != nil {
+				return
+			}
+		}
+
+		if confirm || force {
+			request := &v1.DeleteUserRequest{Name: userName}
+
+			response, err := client.DeleteUser(ctx, request)
+			if err != nil {
+				ErrorOutput(
+					err,
+					fmt.Sprintf(
+						"Cannot destroy user: %s",
+						status.Convert(err).Message(),
+					),
+					output,
+				)
+
+				return
+			}
+			SuccessOutput(response, "User destroyed", output)
+		} else {
+			SuccessOutput(map[string]string{"Result": "User not destroyed"}, "User not destroyed", output)
+		}
+	},
+}
+
+var listUsersCmd = &cobra.Command{
+	Use:     "list",
+	Short:   "List all the users",
+	Aliases: []string{"ls", "show"},
+	Run: func(cmd *cobra.Command, args []string) {
+		output, _ := cmd.Flags().GetString("output")
+
+		ctx, client, conn, cancel := getHeadscaleCLIClient()
+		defer cancel()
+		defer conn.Close()
+
+		request := &v1.ListUsersRequest{}
+
+		response, err := client.ListUsers(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				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"}}
+		for _, user := range response.GetUsers() {
+			tableData = append(
+				tableData,
+				[]string{
+					user.GetId(),
+					user.GetName(),
+					user.GetCreatedAt().AsTime().Format("2006-01-02 15:04:05"),
+				},
+			)
+		}
+		err = pterm.DefaultTable.WithHasHeader().WithData(tableData).Render()
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf("Failed to render pterm table: %s", err),
+				output,
+			)
+
+			return
+		}
+	},
+}
+
+var renameUserCmd = &cobra.Command{
+	Use:     "rename OLD_NAME NEW_NAME",
+	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()
+		defer cancel()
+		defer conn.Close()
+
+		request := &v1.RenameUserRequest{
+			OldName: args[0],
+			NewName: args[1],
+		}
+
+		response, err := client.RenameUser(ctx, request)
+		if err != nil {
+			ErrorOutput(
+				err,
+				fmt.Sprintf(
+					"Cannot rename user: %s",
+					status.Convert(err).Message(),
+				),
+				output,
+			)
+
+			return
+		}
+
+		SuccessOutput(response.GetUser(), "User renamed", output)
+	},
+}

cmd/headscale/cli/utils.go

@@ -1,186 +1,224 @@
 package cli
 
 import (
+	"context"
+	"crypto/tls"
 	"encoding/json"
-	"errors"
 	"fmt"
-	"io"
-	"log"
 	"os"
-	"path/filepath"
-	"strings"
-	"time"
+	"reflect"
 
-	"github.com/juanfont/headscale"
-	"github.com/spf13/viper"
-	"gopkg.in/yaml.v2"
-	"inet.af/netaddr"
-	"tailscale.com/tailcfg"
+	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"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials"
+	"google.golang.org/grpc/credentials/insecure"
+	"gopkg.in/yaml.v3"
 )
 
-type ErrorOutput struct {
-	Error string
-}
+const (
+	HeadscaleDateTimeFormat = "2006-01-02 15:04:05"
+	SocketWritePermissions  = 0o666
+)
 
-func LoadConfig(path string) error {
-	viper.SetConfigName("config")
-	if path == "" {
-		viper.AddConfigPath("/etc/headscale/")
-		viper.AddConfigPath("$HOME/.headscale")
-		viper.AddConfigPath(".")
-	} else {
-		// For testing
-		viper.AddConfigPath(path)
-	}
-	viper.AutomaticEnv()
-
-	viper.SetDefault("tls_letsencrypt_cache_dir", "/var/www/.cache")
-	viper.SetDefault("tls_letsencrypt_challenge_type", "HTTP-01")
-
-	viper.SetDefault("ip_prefix", "100.64.0.0/10")
-
-	err := viper.ReadInConfig()
+func getHeadscaleApp() (*hscontrol.Headscale, error) {
+	cfg, err := types.GetHeadscaleConfig()
 	if err != nil {
-		return fmt.Errorf("Fatal error reading config file: %s \n", err)
+		return nil, fmt.Errorf(
+			"failed to load configuration while creating headscale instance: %w",
+			err,
+		)
 	}
 
-	// Collect any validation errors and return them all at once
-	var errorText string
-	if (viper.GetString("tls_letsencrypt_hostname") != "") && ((viper.GetString("tls_cert_path") != "") || (viper.GetString("tls_key_path") != "")) {
-		errorText += "Fatal config error: set either tls_letsencrypt_hostname or tls_cert_path/tls_key_path, not both\n"
-	}
-
-	if (viper.GetString("tls_letsencrypt_hostname") != "") && (viper.GetString("tls_letsencrypt_challenge_type") == "TLS-ALPN-01") && (!strings.HasSuffix(viper.GetString("listen_addr"), ":443")) {
-		// this is only a warning because there could be something sitting in front of headscale that redirects the traffic (e.g. an iptables rule)
-		log.Println("Warning: when using tls_letsencrypt_hostname with TLS-ALPN-01 as challenge type, headscale must be reachable on port 443, i.e. listen_addr should probably end in :443")
-	}
-
-	if (viper.GetString("tls_letsencrypt_challenge_type") != "HTTP-01") && (viper.GetString("tls_letsencrypt_challenge_type") != "TLS-ALPN-01") {
-		errorText += "Fatal config error: the only supported values for tls_letsencrypt_challenge_type are HTTP-01 and TLS-ALPN-01\n"
-	}
-
-	if !strings.HasPrefix(viper.GetString("server_url"), "http://") && !strings.HasPrefix(viper.GetString("server_url"), "https://") {
-		errorText += "Fatal config error: server_url must start with https:// or http://\n"
-	}
-	if errorText != "" {
-		return errors.New(strings.TrimSuffix(errorText, "\n"))
-	} else {
-		return nil
-	}
-}
-
-func absPath(path string) string {
-	// If a relative path is provided, prefix it with the the directory where
-	// the config file was found.
-	if (path != "") && !strings.HasPrefix(path, string(os.PathSeparator)) {
-		dir, _ := filepath.Split(viper.ConfigFileUsed())
-		if dir != "" {
-			path = filepath.Join(dir, path)
-		}
-	}
-	return path
-}
-
-func getHeadscaleApp() (*headscale.Headscale, error) {
-	derpMap, err := loadDerpMap(absPath(viper.GetString("derp_map_path")))
-	if err != nil {
-		log.Printf("Could not load DERP servers map file: %s", err)
-	}
-
-	// Minimum inactivity time out is keepalive timeout (60s) plus a few seconds
-	// to avoid races
-	minInactivityTimeout, _ := time.ParseDuration("65s")
-	if viper.GetDuration("ephemeral_node_inactivity_timeout") <= minInactivityTimeout {
-		err = fmt.Errorf("ephemeral_node_inactivity_timeout (%s) is set too low, must be more than %s\n", viper.GetString("ephemeral_node_inactivity_timeout"), minInactivityTimeout)
-		return nil, err
-	}
-
-	cfg := headscale.Config{
-		ServerURL:      viper.GetString("server_url"),
-		Addr:           viper.GetString("listen_addr"),
-		PrivateKeyPath: absPath(viper.GetString("private_key_path")),
-		DerpMap:        derpMap,
-		IPPrefix:       netaddr.MustParseIPPrefix(viper.GetString("ip_prefix")),
-
-		EphemeralNodeInactivityTimeout: viper.GetDuration("ephemeral_node_inactivity_timeout"),
-
-		DBtype: viper.GetString("db_type"),
-		DBpath: absPath(viper.GetString("db_path")),
-		DBhost: viper.GetString("db_host"),
-		DBport: viper.GetInt("db_port"),
-		DBname: viper.GetString("db_name"),
-		DBuser: viper.GetString("db_user"),
-		DBpass: viper.GetString("db_pass"),
-
-		TLSLetsEncryptHostname:      viper.GetString("tls_letsencrypt_hostname"),
-		TLSLetsEncryptListen:        viper.GetString("tls_letsencrypt_listen"),
-		TLSLetsEncryptCacheDir:      absPath(viper.GetString("tls_letsencrypt_cache_dir")),
-		TLSLetsEncryptChallengeType: viper.GetString("tls_letsencrypt_challenge_type"),
-
-		TLSCertPath: absPath(viper.GetString("tls_cert_path")),
-		TLSKeyPath:  absPath(viper.GetString("tls_key_path")),
-	}
-
-	h, err := headscale.NewHeadscale(cfg)
+	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 viper.GetString("acl_policy_path") != "" {
-		err = h.LoadACLPolicy(absPath(viper.GetString("acl_policy_path")))
+	if cfg.ACL.PolicyPath != "" {
+		aclPath := util.AbsolutePathFromConfigPath(cfg.ACL.PolicyPath)
+		pol, err := policy.LoadACLPolicyFromPath(aclPath)
 		if err != nil {
-			log.Printf("Could not load the ACL policy: %s", err)
+			log.Fatal().
+				Str("path", aclPath).
+				Err(err).
+				Msg("Could not load the ACL policy")
+		}
+
+		app.ACLPolicy = pol
+	}
+
+	return app, nil
+}
+
+func getHeadscaleCLIClient() (context.Context, v1.HeadscaleServiceClient, *grpc.ClientConn, context.CancelFunc) {
+	cfg, err := types.GetHeadscaleConfig()
+	if err != nil {
+		log.Fatal().
+			Err(err).
+			Caller().
+			Msgf("Failed to load configuration")
+		os.Exit(-1) // we get here if logging is suppressed (i.e., json output)
+	}
+
+	log.Debug().
+		Dur("timeout", cfg.CLI.Timeout).
+		Msgf("Setting timeout")
+
+	ctx, cancel := context.WithTimeout(context.Background(), cfg.CLI.Timeout)
+
+	grpcOptions := []grpc.DialOption{
+		grpc.WithBlock(),
+	}
+
+	address := cfg.CLI.Address
+
+	// If the address is not set, we assume that we are on the server hosting hscontrol.
+	if address == "" {
+		log.Debug().
+			Str("socket", cfg.UnixSocket).
+			Msgf("HEADSCALE_CLI_ADDRESS environment is not set, connecting to unix socket.")
+
+		address = cfg.UnixSocket
+
+		// 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
+		if err != nil {
+			if os.IsPermission(err) {
+				log.Fatal().
+					Err(err).
+					Str("socket", cfg.UnixSocket).
+					Msgf("Unable to read/write to headscale socket, do you have the correct permissions?")
+			}
+		}
+		socket.Close()
+
+		grpcOptions = append(
+			grpcOptions,
+			grpc.WithTransportCredentials(insecure.NewCredentials()),
+			grpc.WithContextDialer(util.GrpcSocketDialer),
+		)
+	} else {
+		// If we are not connecting to a local server, require an API key for authentication
+		apiKey := cfg.CLI.APIKey
+		if apiKey == "" {
+			log.Fatal().Caller().Msgf("HEADSCALE_CLI_API_KEY environment variable needs to be set.")
+		}
+		grpcOptions = append(grpcOptions,
+			grpc.WithPerRPCCredentials(tokenAuth{
+				token: apiKey,
+			}),
+		)
+
+		if cfg.CLI.Insecure {
+			tlsConfig := &tls.Config{
+				// turn of gosec as we are intentionally setting
+				// insecure.
+				//nolint:gosec
+				InsecureSkipVerify: true,
+			}
+
+			grpcOptions = append(grpcOptions,
+				grpc.WithTransportCredentials(credentials.NewTLS(tlsConfig)),
+			)
+		} else {
+			grpcOptions = append(grpcOptions,
+				grpc.WithTransportCredentials(credentials.NewClientTLSFromCert(nil, "")),
+			)
 		}
 	}
 
-	return h, nil
+	log.Trace().Caller().Str("address", address).Msg("Connecting via gRPC")
+	conn, err := grpc.DialContext(ctx, address, grpcOptions...)
+	if err != nil {
+		log.Fatal().Caller().Err(err).Msgf("Could not connect: %v", err)
+		os.Exit(-1) // we get here if logging is suppressed (i.e., json output)
+	}
+
+	client := v1.NewHeadscaleServiceClient(conn)
+
+	return ctx, client, conn, cancel
 }
 
-func loadDerpMap(path string) (*tailcfg.DERPMap, error) {
-	derpFile, err := os.Open(path)
-	if err != nil {
-		return nil, err
-	}
-	defer derpFile.Close()
-	var derpMap tailcfg.DERPMap
-	b, err := io.ReadAll(derpFile)
-	if err != nil {
-		return nil, err
-	}
-	err = yaml.Unmarshal(b, &derpMap)
-	return &derpMap, err
-}
-
-func JsonOutput(result interface{}, errResult error, outputFormat string) {
-	var j []byte
+func SuccessOutput(result interface{}, override string, outputFormat string) {
+	var jsonBytes []byte
 	var err error
 	switch outputFormat {
 	case "json":
-		if errResult != nil {
-			j, err = json.MarshalIndent(ErrorOutput{errResult.Error()}, "", "\t")
-			if err != nil {
-				log.Fatalln(err)
-			}
-		} else {
-			j, err = json.MarshalIndent(result, "", "\t")
-			if err != nil {
-				log.Fatalln(err)
-			}
+		jsonBytes, err = json.MarshalIndent(result, "", "\t")
+		if err != nil {
+			log.Fatal().Err(err).Msg("failed to unmarshal output")
 		}
 	case "json-line":
-		if errResult != nil {
-			j, err = json.Marshal(ErrorOutput{errResult.Error()})
-			if err != nil {
-				log.Fatalln(err)
-			}
-		} else {
-			j, err = json.Marshal(result)
-			if err != nil {
-				log.Fatalln(err)
-			}
+		jsonBytes, err = json.Marshal(result)
+		if err != nil {
+			log.Fatal().Err(err).Msg("failed to unmarshal output")
+		}
+	case "yaml":
+		jsonBytes, err = yaml.Marshal(result)
+		if err != nil {
+			log.Fatal().Err(err).Msg("failed to unmarshal output")
+		}
+	default:
+		//nolint
+		fmt.Println(override)
+
+		return
+	}
+
+	//nolint
+	fmt.Println(string(jsonBytes))
+}
+
+func ErrorOutput(errResult error, override string, outputFormat string) {
+	type errOutput struct {
+		Error string `json:"error"`
+	}
+
+	SuccessOutput(errOutput{errResult.Error()}, override, outputFormat)
+}
+
+func HasMachineOutputFlag() bool {
+	for _, arg := range os.Args {
+		if arg == "json" || arg == "json-line" || arg == "yaml" {
+			return true
 		}
 	}
-	fmt.Println(string(j))
+
+	return false
+}
+
+type tokenAuth struct {
+	token string
+}
+
+// Return value is mapped to request headers.
+func (t tokenAuth) GetRequestMetadata(
+	ctx context.Context,
+	in ...string,
+) (map[string]string, error) {
+	return map[string]string{
+		"authorization": "Bearer " + t.token,
+	}, nil
+}
+
+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,12 +1,10 @@
 package cli
 
 import (
-	"fmt"
 	"github.com/spf13/cobra"
-	"strings"
 )
 
-var version = "dev"
+var Version = "dev"
 
 func init() {
 	rootCmd.AddCommand(versionCmd)
@@ -17,11 +15,7 @@ var versionCmd = &cobra.Command{
 	Short: "Print the version.",
 	Long:  "The version of headscale.",
 	Run: func(cmd *cobra.Command, args []string) {
-		o, _ := cmd.Flags().GetString("output")
-		if strings.HasPrefix(o, "json") {
-			JsonOutput(map[string]string{"version": version}, nil, o)
-			return
-		}
-		fmt.Println(version)
+		output, _ := cmd.Flags().GetString("output")
+		SuccessOutput(map[string]string{"version": Version}, Version, output)
 	},
 }

cmd/headscale/headscale.go

@@ -1,16 +1,43 @@
 package main
 
 import (
-	"log"
+	"os"
+	"time"
 
+	"github.com/jagottsicher/termcolor"
 	"github.com/juanfont/headscale/cmd/headscale/cli"
+	"github.com/rs/zerolog"
+	"github.com/rs/zerolog/log"
 )
 
 func main() {
-	err := cli.LoadConfig("")
-	if err != nil {
-		log.Fatalf(err.Error())
+	var colors bool
+	switch l := termcolor.SupportLevel(os.Stderr); l {
+	case termcolor.Level16M:
+		colors = true
+	case termcolor.Level256:
+		colors = true
+	case termcolor.LevelBasic:
+		colors = true
+	case termcolor.LevelNone:
+		colors = false
+	default:
+		// no color, return text as is.
+		colors = false
 	}
 
+	// Adhere to no-color.org manifesto of allowing users to
+	// turn off color in cli/services
+	if _, noColorIsSet := os.LookupEnv("NO_COLOR"); noColorIsSet {
+		colors = false
+	}
+
+	zerolog.TimeFieldFormat = zerolog.TimeFormatUnix
+	log.Logger = log.Output(zerolog.ConsoleWriter{
+		Out:        os.Stderr,
+		TimeFormat: time.RFC3339,
+		NoColor:    !colors,
+	})
+
 	cli.Execute()
 }

cmd/headscale/headscale_test.go

@@ -1,14 +1,14 @@
 package main
 
 import (
-	"fmt"
-	"io/ioutil"
+	"io/fs"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
 
-	"github.com/juanfont/headscale/cmd/headscale/cli"
+	"github.com/juanfont/headscale/hscontrol/types"
+	"github.com/juanfont/headscale/hscontrol/util"
 	"github.com/spf13/viper"
 	"gopkg.in/check.v1"
 )
@@ -25,11 +25,55 @@ func (s *Suite) SetUpSuite(c *check.C) {
 }
 
 func (s *Suite) TearDownSuite(c *check.C) {
-
 }
 
-func (*Suite) TestPostgresConfigLoading(c *check.C) {
-	tmpDir, err := ioutil.TempDir("", "headscale")
+func (*Suite) TestConfigFileLoading(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)
+	}
+
+	cfgFile := filepath.Join(tmpDir, "config.yaml")
+
+	// Symlink the example config file
+	err = os.Symlink(
+		filepath.Clean(path+"/../../config-example.yaml"),
+		cfgFile,
+	)
+	if err != nil {
+		c.Fatal(err)
+	}
+
+	// Load example config, it should load without validation errors
+	err = types.LoadConfig(cfgFile, true)
+	c.Assert(err, check.IsNil)
+
+	// Test that config file was interpreted correctly
+	c.Assert(viper.GetString("server_url"), check.Equals, "http://127.0.0.1:8080")
+	c.Assert(viper.GetString("listen_addr"), check.Equals, "127.0.0.1:8080")
+	c.Assert(viper.GetString("metrics_listen_addr"), check.Equals, "127.0.0.1:9090")
+	c.Assert(viper.GetString("database.type"), check.Equals, "sqlite")
+	c.Assert(viper.GetString("database.sqlite.path"), check.Equals, "/var/lib/headscale/db.sqlite")
+	c.Assert(viper.GetString("tls_letsencrypt_hostname"), check.Equals, "")
+	c.Assert(viper.GetString("tls_letsencrypt_listen"), check.Equals, ":http")
+	c.Assert(viper.GetString("tls_letsencrypt_challenge_type"), check.Equals, "HTTP-01")
+	c.Assert(viper.GetStringSlice("dns_config.nameservers")[0], check.Equals, "1.1.1.1")
+	c.Assert(
+		util.GetFileMode("unix_socket_permission"),
+		check.Equals,
+		fs.FileMode(0o770),
+	)
+	c.Assert(viper.GetBool("logtail.enabled"), check.Equals, false)
+}
+
+func (*Suite) TestConfigLoading(c *check.C) {
+	tmpDir, err := os.MkdirTemp("", "headscale")
 	if err != nil {
 		c.Fatal(err)
 	}
@@ -41,28 +85,39 @@ func (*Suite) TestPostgresConfigLoading(c *check.C) {
 	}
 
 	// Symlink the example config file
-	err = os.Symlink(filepath.Clean(path+"/../../config.json.postgres.example"), filepath.Join(tmpDir, "config.json"))
+	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 = cli.LoadConfig(tmpDir)
+	err = types.LoadConfig(tmpDir, false)
 	c.Assert(err, check.IsNil)
 
 	// Test that config file was interpreted correctly
 	c.Assert(viper.GetString("server_url"), check.Equals, "http://127.0.0.1:8080")
-	c.Assert(viper.GetString("listen_addr"), check.Equals, "0.0.0.0:8080")
-	c.Assert(viper.GetString("derp_map_path"), check.Equals, "derp.yaml")
-	c.Assert(viper.GetString("db_type"), check.Equals, "postgres")
-	c.Assert(viper.GetString("db_port"), check.Equals, "5432")
+	c.Assert(viper.GetString("listen_addr"), check.Equals, "127.0.0.1:8080")
+	c.Assert(viper.GetString("metrics_listen_addr"), check.Equals, "127.0.0.1:9090")
+	c.Assert(viper.GetString("database.type"), check.Equals, "sqlite")
+	c.Assert(viper.GetString("database.sqlite.path"), check.Equals, "/var/lib/headscale/db.sqlite")
 	c.Assert(viper.GetString("tls_letsencrypt_hostname"), check.Equals, "")
 	c.Assert(viper.GetString("tls_letsencrypt_listen"), check.Equals, ":http")
 	c.Assert(viper.GetString("tls_letsencrypt_challenge_type"), check.Equals, "HTTP-01")
+	c.Assert(viper.GetStringSlice("dns_config.nameservers")[0], check.Equals, "1.1.1.1")
+	c.Assert(
+		util.GetFileMode("unix_socket_permission"),
+		check.Equals,
+		fs.FileMode(0o770),
+	)
+	c.Assert(viper.GetBool("logtail.enabled"), check.Equals, false)
+	c.Assert(viper.GetBool("randomize_client_port"), check.Equals, false)
 }
 
-func (*Suite) TestSqliteConfigLoading(c *check.C) {
-	tmpDir, err := ioutil.TempDir("", "headscale")
+func (*Suite) TestDNSConfigLoading(c *check.C) {
+	tmpDir, err := os.MkdirTemp("", "headscale")
 	if err != nil {
 		c.Fatal(err)
 	}
@@ -74,59 +129,79 @@ func (*Suite) TestSqliteConfigLoading(c *check.C) {
 	}
 
 	// Symlink the example config file
-	err = os.Symlink(filepath.Clean(path+"/../../config.json.sqlite.example"), filepath.Join(tmpDir, "config.json"))
+	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 = cli.LoadConfig(tmpDir)
+	err = types.LoadConfig(tmpDir, false)
 	c.Assert(err, check.IsNil)
 
-	// Test that config file was interpreted correctly
-	c.Assert(viper.GetString("server_url"), check.Equals, "http://127.0.0.1:8080")
-	c.Assert(viper.GetString("listen_addr"), check.Equals, "0.0.0.0:8080")
-	c.Assert(viper.GetString("derp_map_path"), check.Equals, "derp.yaml")
-	c.Assert(viper.GetString("db_type"), check.Equals, "sqlite3")
-	c.Assert(viper.GetString("db_path"), check.Equals, "db.sqlite")
-	c.Assert(viper.GetString("tls_letsencrypt_hostname"), check.Equals, "")
-	c.Assert(viper.GetString("tls_letsencrypt_listen"), check.Equals, ":http")
-	c.Assert(viper.GetString("tls_letsencrypt_challenge_type"), check.Equals, "HTTP-01")
+	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 := ioutil.WriteFile(configFile, configYaml, 0644)
+	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 := ioutil.TempDir("", "headscale")
+	tmpDir, err := os.MkdirTemp("", "headscale")
 	if err != nil {
 		c.Fatal(err)
 	}
-	//defer os.RemoveAll(tmpDir)
-	fmt.Println(tmpDir)
-
-	configYaml := []byte("---\ntls_letsencrypt_hostname: \"example.com\"\ntls_letsencrypt_challenge_type: \"\"\ntls_cert_path: \"abc.pem\"")
+	// 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 = cli.LoadConfig(tmpDir)
+	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://.*")
-	fmt.Println(tmp)
+	c.Assert(
+		tmp,
+		check.Matches,
+		".*Fatal config error: set either tls_letsencrypt_hostname or tls_cert_path/tls_key_path, not both.*",
+	)
+	c.Assert(
+		tmp,
+		check.Matches,
+		".*Fatal config error: the only supported values for tls_letsencrypt_challenge_type are.*",
+	)
+	c.Assert(
+		tmp,
+		check.Matches,
+		".*Fatal config error: server_url must start with https:// or http://.*",
+	)
 
 	// Check configuration validation errors (2)
-	configYaml = []byte("---\nserver_url: \"http://127.0.0.1:8080\"\ntls_letsencrypt_hostname: \"example.com\"\ntls_letsencrypt_challenge_type: \"TLS-ALPN-01\"")
+	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 = cli.LoadConfig(tmpDir)
+	err = types.LoadConfig(tmpDir, false)
 	c.Assert(err, check.IsNil)
 }

config-example.yaml

@@ -0,0 +1,338 @@
+---
+# headscale will look for a configuration file named `config.yaml` (or `config.json`) in the following order:
+#
+# - `/etc/headscale`
+# - `~/.headscale`
+# - current working directory
+
+# The url clients will connect to.
+# Typically this will be a domain like:
+#
+# https://myheadscale.example.com:443
+#
+server_url: http://127.0.0.1:8080
+
+# Address to listen to / bind to on the server
+#
+# For production:
+# 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
+#
+metrics_listen_addr: 127.0.0.1:9090
+
+# Address to listen for gRPC.
+# gRPC is used for controlling a headscale server
+# remotely with the CLI
+# Note: Remote access _only_ works if you have
+# valid certificates.
+#
+# For production:
+# grpc_listen_addr: 0.0.0.0:50443
+grpc_listen_addr: 127.0.0.1:50443
+
+# Allow the gRPC admin interface to run in INSECURE
+# mode. This is not recommended as the traffic will
+# be unencrypted. Only enable if you know what you
+# are doing.
+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.
+  private_key_path: /var/lib/headscale/noise_private.key
+
+# List of IP prefixes to allocate tailaddresses from.
+# Each prefix consists of either an IPv4 or IPv6 address,
+# and the associated prefix length, delimited by a slash.
+# It must be within IP ranges supported by the Tailscale
+# client - i.e., subnets of 100.64.0.0/10 and fd7a:115c:a1e0::/48.
+# See below:
+# IPv6: https://github.com/tailscale/tailscale/blob/22ebb25e833264f58d7c3f534a8b166894a89536/net/tsaddr/tsaddr.go#LL81C52-L81C71
+# 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
+
+  # Strategy used for allocation of IPs to nodes, available options:
+  # - sequential (default): assigns the next free IP from the previous given IP.
+  # - random: assigns the next free IP from a pseudo-random IP generator (crypto/rand).
+  allocation: sequential
+
+# DERP is a relay system that Tailscale uses when a direct
+# connection cannot be established.
+# https://tailscale.com/blog/how-tailscale-works/#encrypted-tcp-relays-derp
+#
+# headscale needs a list of DERP servers that can be presented
+# to the clients.
+derp:
+  server:
+    # If enabled, runs the embedded DERP server and merges it into the rest of the DERP config
+    # The Headscale server_url defined above MUST be using https, DERP requires TLS to be in place
+    enabled: false
+
+    # Region ID to use for the embedded DERP server.
+    # The local DERP prevails if the region ID collides with other region ID coming from
+    # the regular DERP config.
+    region_id: 999
+
+    # Region code and name are displayed in the Tailscale UI to identify a DERP region
+    region_code: "headscale"
+    region_name: "Headscale Embedded DERP"
+
+    # Listens over UDP at the configured address for STUN connections - to help with NAT traversal.
+    # When the embedded DERP server is enabled stun_listen_addr MUST be defined.
+    #
+    # 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_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,
+    # it enables the creation of your very own DERP map entry using a locally available file with the parameter DERP.paths
+    # If you enable the DERP server and set this to false, it is required to add the DERP server to the DERP map using DERP.paths
+    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:
+    ipv4: 1.2.3.4
+    ipv6: 2001:db8::1
+
+  # List of externally available DERP maps encoded in JSON
+  urls:
+    - https://controlplane.tailscale.com/derpmap/default
+
+  # Locally available DERP map files encoded in YAML
+  #
+  # This option is mostly interesting for people hosting
+  # their own DERP servers:
+  # https://tailscale.com/kb/1118/custom-derp-servers/
+  #
+  # paths:
+  #   - /etc/headscale/derp-example.yaml
+  paths: []
+
+  # If enabled, a worker will be set up to periodically
+  # refresh the given sources and update the derpmap
+  # will be set up.
+  auto_update_enabled: true
+
+  # How often should we check for DERP updates?
+  update_frequency: 24h
+
+# Disables the automatic check for headscale updates on startup
+disable_check_updates: false
+
+# Time before an inactive ephemeral node is deleted?
+ephemeral_node_inactivity_timeout: 30m
+
+database:
+  type: sqlite
+
+  # SQLite config
+  sqlite:
+    path: /var/lib/headscale/db.sqlite
+
+  # # Postgres config
+  # postgres:
+  #   # If using a Unix socket to connect to Postgres, set the socket path in the 'host' field and leave 'port' blank.
+  #   host: localhost
+  #   port: 5432
+  #   name: headscale
+  #   user: foo
+  #   pass: bar
+  #   max_open_conns: 10
+  #   max_idle_conns: 10
+  #   conn_max_idle_time_secs: 3600
+
+  #   # If other 'sslmode' is required instead of 'require(true)' and 'disabled(false)', set the 'sslmode' you need
+  #   # in the 'ssl' field. Refers to https://www.postgresql.org/docs/current/libpq-ssl.html Table 34.1.
+  #   ssl: false
+
+### TLS configuration
+#
+## Let's encrypt / ACME
+#
+# headscale supports automatically requesting and setting up
+# TLS for a domain with Let's Encrypt.
+#
+# URL to ACME directory
+acme_url: https://acme-v02.api.letsencrypt.org/directory
+
+# Email to register with ACME provider
+acme_email: ""
+
+# Domain name to request a TLS certificate for:
+tls_letsencrypt_hostname: ""
+
+# Path to store certificates and metadata needed by
+# letsencrypt
+# For production:
+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
+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:
+# :http = port 80
+tls_letsencrypt_listen: ":http"
+
+## Use already defined certificates:
+tls_cert_path: ""
+tls_key_path: ""
+
+log:
+  # Output formatting for logs: text or json
+  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: ""
+
+## DNS
+#
+# headscale supports Tailscale's DNS configuration and MagicDNS.
+# Please have a look to their KB to better understand the concepts:
+#
+# - https://tailscale.com/kb/1054/dns/
+# - 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
+
+  # List of DNS servers to expose to clients.
+  nameservers:
+    - 1.1.1.1
+
+  # 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
+
+  # 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
+
+  # Search domains to inject.
+  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:
+  #   - 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
+
+# Unix socket used for the CLI to connect without authentication
+# Note: for production you will want to set this to something like:
+unix_socket: /var/run/headscale/headscale.sock
+unix_socket_permission: "0770"
+#
+# headscale supports experimental OpenID connect support,
+# it is still being tested and might have some bugs, please
+# help us test it.
+# OpenID Connect
+# oidc:
+#   only_start_if_oidc_is_available: true
+#   issuer: "https://your-oidc.issuer.com/path"
+#   client_id: "your-oidc-client-id"
+#   client_secret: "your-oidc-client-secret"
+#   # Alternatively, set `client_secret_path` to read the secret from the file.
+#   # It resolves environment variables, making integration to systemd's
+#   # `LoadCredential` straightforward:
+#   client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
+#   # client_secret and client_secret_path are mutually exclusive.
+#
+#   # The amount of time from a node is authenticated with OpenID until it
+#   # expires and needs to reauthenticate.
+#   # Setting the value to "0" will mean no expiry.
+#   expiry: 180d
+#
+#   # Use the expiry from the token received from OpenID when the user logged
+#   # in, this will typically lead to frequent need to reauthenticate and should
+#   # only been enabled if you know what you are doing.
+#   # Note: enabling this will cause `oidc.expiry` to be ignored.
+#   use_expiry_from_token: false
+#
+#   # Customize the scopes used in the OIDC flow, defaults to "openid", "profile" and "email" and add custom query
+#   # parameters to the Authorize Endpoint request. Scopes default to "openid", "profile" and "email".
+#
+#   scope: ["openid", "profile", "email", "custom"]
+#   extra_params:
+#     domain_hint: example.com
+#
+#   # List allowed principal domains and/or users. If an authenticated user's domain is not in this list, the
+#   # authentication request will be rejected.
+#
+#   allowed_domains:
+#     - example.com
+#   # Note: Groups from keycloak have a leading '/'
+#   allowed_groups:
+#     - /headscale
+#   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
+
+# Logtail configuration
+# Logtail is Tailscales logging and auditing infrastructure, it allows the control panel
+# to instruct tailscale nodes to log their activity to a remote server.
+logtail:
+  # Enable logtail for this headscales clients.
+  # As there is currently no support for overriding the log server in headscale, this is
+  # disabled by default. Enabling this will make your clients send logs to Tailscale Inc.
+  enabled: false
+
+# Enabling this option makes devices prefer a random port for WireGuard traffic over the
+# default static port 41641. This option is intended as a workaround for some buggy
+# firewall devices. See https://tailscale.com/kb/1181/firewalls/ for more information.
+randomize_client_port: false

config.json.postgres.example

@@ -1,20 +0,0 @@
-{
-    "server_url": "http://127.0.0.1:8080",
-    "listen_addr": "0.0.0.0:8080",
-    "private_key_path": "private.key",
-    "derp_map_path": "derp.yaml",
-    "ephemeral_node_inactivity_timeout": "30m",
-    "db_type": "postgres",
-    "db_host": "localhost",
-    "db_port": 5432,
-    "db_name": "headscale",
-    "db_user": "foo",
-    "db_pass": "bar",
-    "tls_letsencrypt_hostname": "",
-    "tls_letsencrypt_listen": ":http",
-    "tls_letsencrypt_cache_dir": ".cache",
-    "tls_letsencrypt_challenge_type": "HTTP-01",
-    "tls_cert_path": "",
-    "tls_key_path": "",
-    "acl_policy_path": ""
-}

config.json.sqlite.example

@@ -1,16 +0,0 @@
-{
-    "server_url": "http://127.0.0.1:8080",
-    "listen_addr": "0.0.0.0:8080",
-    "private_key_path": "private.key",
-    "derp_map_path": "derp.yaml",
-    "ephemeral_node_inactivity_timeout": "30m",
-    "db_type": "sqlite3",
-    "db_path": "db.sqlite",
-    "tls_letsencrypt_hostname": "",
-    "tls_letsencrypt_listen": ":http",
-    "tls_letsencrypt_cache_dir": ".cache",
-    "tls_letsencrypt_challenge_type": "HTTP-01",
-    "tls_cert_path": "",
-    "tls_key_path": "",
-    "acl_policy_path": ""
-}

db.go

@@ -1,106 +0,0 @@
-package headscale
-
-import (
-	"errors"
-
-	"gorm.io/driver/postgres"
-	"gorm.io/driver/sqlite"
-	"gorm.io/gorm"
-	"gorm.io/gorm/logger"
-)
-
-const dbVersion = "1"
-
-// KV is a key-value store in a psql table. For future use...
-type KV struct {
-	Key   string
-	Value string
-}
-
-func (h *Headscale) initDB() error {
-	db, err := h.openDB()
-	if err != nil {
-		return err
-	}
-	h.db = db
-
-	if h.dbType == "postgres" {
-		db.Exec("create extension if not exists \"uuid-ossp\";")
-	}
-	err = db.AutoMigrate(&Machine{})
-	if err != nil {
-		return err
-	}
-	err = db.AutoMigrate(&KV{})
-	if err != nil {
-		return err
-	}
-	err = db.AutoMigrate(&Namespace{})
-	if err != nil {
-		return err
-	}
-	err = db.AutoMigrate(&PreAuthKey{})
-	if err != nil {
-		return err
-	}
-
-	err = h.setValue("db_version", dbVersion)
-	return err
-}
-
-func (h *Headscale) openDB() (*gorm.DB, error) {
-	var db *gorm.DB
-	var err error
-
-	var log logger.Interface
-	if h.dbDebug {
-		log = logger.Default
-	} else {
-		log = logger.Default.LogMode(logger.Silent)
-	}
-
-	switch h.dbType {
-	case "sqlite3":
-		db, err = gorm.Open(sqlite.Open(h.dbString), &gorm.Config{
-			DisableForeignKeyConstraintWhenMigrating: true,
-			Logger:                                   log,
-		})
-	case "postgres":
-		db, err = gorm.Open(postgres.Open(h.dbString), &gorm.Config{
-			DisableForeignKeyConstraintWhenMigrating: true,
-			Logger:                                   log,
-		})
-	}
-
-	if err != nil {
-		return nil, err
-	}
-
-	return db, nil
-}
-
-// getValue returns the value for the given key in KV
-func (h *Headscale) getValue(key string) (string, error) {
-	var row KV
-	if result := h.db.First(&row, "key = ?", key); errors.Is(result.Error, gorm.ErrRecordNotFound) {
-		return "", errors.New("not found")
-	}
-	return row.Value, nil
-}
-
-// setValue sets value for the given key in KV
-func (h *Headscale) setValue(key string, value string) error {
-	kv := KV{
-		Key:   key,
-		Value: value,
-	}
-
-	_, err := h.getValue(key)
-	if err == nil {
-		h.db.Model(&kv).Where("key = ?", key).Update("value", value)
-		return nil
-	}
-
-	h.db.Create(kv)
-	return nil
-}

derp-example.yaml

@@ -0,0 +1,15 @@
+# If you plan to somehow use headscale, please deploy your own DERP infra: https://tailscale.com/kb/1118/custom-derp-servers/
+regions:
+  900:
+    regionid: 900
+    regioncode: custom
+    regionname: My Region
+    nodes:
+      - name: 900a
+        regionid: 900
+        hostname: myderp.mydomain.no
+        ipv4: 123.123.123.123
+        ipv6: "2604:a880:400:d1::828:b001"
+        stunport: 0
+        stunonly: false
+        derpport: 0

derp.yaml

@@ -1,146 +0,0 @@
-# This file contains some of the official Tailscale DERP servers, 
-# shamelessly taken from https://github.com/tailscale/tailscale/blob/main/net/dnsfallback/dns-fallback-servers.json
-#
-# If you plan to somehow use headscale, please deploy your own DERP infra
-regions: 
-  1:
-    regionid: 1
-    regioncode: nyc
-    regionname: New York City
-    nodes:
-    - name: 1a
-      regionid: 1
-      hostname: derp1.tailscale.com
-      ipv4: 159.89.225.99
-      ipv6: "2604:a880:400:d1::828:b001"
-      stunport: 0
-      stunonly: false
-      derptestport: 0
-    - name: 1b
-      regionid: 1
-      hostname: derp1b.tailscale.com
-      ipv4: 45.55.35.93
-      ipv6: "2604:a880:800:a1::f:2001"
-      stunport: 0
-      stunonly: false
-      derptestport: 0
-  2:
-    regionid: 2
-    regioncode: sfo
-    regionname: San Francisco
-    nodes:
-    - name: 2a
-      regionid: 2
-      hostname: derp2.tailscale.com
-      ipv4: 167.172.206.31
-      ipv6: "2604:a880:2:d1::c5:7001"
-      stunport: 0
-      stunonly: false
-      derptestport: 0
-    - name: 2b
-      regionid: 2
-      hostname: derp2b.tailscale.com
-      ipv4: 64.227.106.23
-      ipv6: "2604:a880:4:1d0::29:9000"
-      stunport: 0
-      stunonly: false
-      derptestport: 0
-  3:
-    regionid: 3
-    regioncode: sin
-    regionname: Singapore
-    nodes:
-    - name: 3a
-      regionid: 3
-      hostname: derp3.tailscale.com
-      ipv4: 68.183.179.66
-      ipv6: "2400:6180:0:d1::67d:8001"
-      stunport: 0
-      stunonly: false
-      derptestport: 0
-  4:
-    regionid: 4
-    regioncode: fra
-    regionname: Frankfurt
-    nodes:
-    - name: 4a
-      regionid: 4
-      hostname: derp4.tailscale.com
-      ipv4: 167.172.182.26
-      ipv6: "2a03:b0c0:3:e0::36e:900"
-      stunport: 0
-      stunonly: false
-      derptestport: 0
-    - name: 4b
-      regionid: 4
-      hostname: derp4b.tailscale.com
-      ipv4: 157.230.25.0
-      ipv6: "2a03:b0c0:3:e0::58f:3001"
-      stunport: 0
-      stunonly: false
-      derptestport: 0
-  5:
-    regionid: 5
-    regioncode: syd
-    regionname: Sydney
-    nodes:
-    - name: 5a
-      regionid: 5
-      hostname: derp5.tailscale.com
-      ipv4: 103.43.75.49
-      ipv6: "2001:19f0:5801:10b7:5400:2ff:feaa:284c"
-      stunport: 0
-      stunonly: false
-      derptestport: 0
-  6:
-    regionid: 6
-    regioncode: blr
-    regionname: Bangalore
-    nodes:
-    - name: 6a
-      regionid: 6
-      hostname: derp6.tailscale.com
-      ipv4: 68.183.90.120
-      ipv6: "2400:6180:100:d0::982:d001"
-      stunport: 0
-      stunonly: false
-      derptestport: 0
-  7:
-    regionid: 7
-    regioncode: tok
-    regionname: Tokyo
-    nodes:
-    - name: 7a
-      regionid: 7
-      hostname: derp7.tailscale.com
-      ipv4: 167.179.89.145
-      ipv6: "2401:c080:1000:467f:5400:2ff:feee:22aa"
-      stunport: 0
-      stunonly: false
-      derptestport: 0
-  8:
-    regionid: 8
-    regioncode: lhr
-    regionname: London
-    nodes:
-    - name: 8a
-      regionid: 8
-      hostname: derp8.tailscale.com
-      ipv4: 167.71.139.179
-      ipv6: "2a03:b0c0:1:e0::3cc:e001"
-      stunport: 0
-      stunonly: false
-      derptestport: 0
-  9:
-    regionid: 9
-    regioncode: sao
-    regionname: São Paulo
-    nodes:
-    - name: 9a
-      regionid: 9
-      hostname: derp9.tailscale.com
-      ipv4: 207.148.3.137
-      ipv6: "2001:19f0:6401:1d9c:5400:2ff:feef:bb82"
-      stunport: 0
-      stunonly: false
-      derptestport: 0

docs/acls.md

@@ -0,0 +1,189 @@
+Headscale implements the same policy ACLs as Tailscale.com, adapted to the self-hosted environment.
+
+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.
+
+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
+long as the ACL's permits this exchange.
+
+## ACLs use case 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 developers and an intern.
+
+The boss should have access to all servers but not to the user's 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.
+
+There's an additional server that acts as a router, connecting the VPN users
+to an internal network `10.20.0.0/16`. Developers must have access to those
+internal resources.
+
+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
+- router.internal
+
+![ACL implementation example](images/headscale-acl-network.png)
+
+## ACL setup
+
+Note: Users will be created automatically when users authenticate with the
+Headscale server.
+
+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
+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/).
+
+Here are the ACL's to implement the same permissions as above:
+
+```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"]
+  },
+  // 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)
+  // and explained [here](https://tailscale.com/blog/rbac-like-it-was-meant-to-be/)
+  "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
+  },
+  // hosts should be defined using its IP addresses and a subnet mask.
+  // 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": {
+    "postgresql.internal": "10.20.0.2/32",
+    "webservers.internal": "10.20.10.1/29"
+  },
+  "acls": [
+    // boss have access to all servers
+    {
+      "action": "accept",
+      "src": ["group:boss"],
+      "dst": [
+        "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, in tcp/22
+    {
+      "action": "accept",
+      "src": ["group:admin"],
+      "proto": "tcp",
+      "dst": [
+        "tag:prod-databases:22",
+        "tag:prod-app-servers:22",
+        "tag:internal:22",
+        "tag:dev-databases:22",
+        "tag:dev-app-servers:22"
+      ]
+    },
+
+    // we also allow admin to ping the servers
+    {
+      "action": "accept",
+      "src": ["group:admin"],
+      "proto": "icmp",
+      "dst": [
+        "tag:prod-databases:*",
+        "tag:prod-app-servers:*",
+        "tag:internal:*",
+        "tag:dev-databases:*",
+        "tag:dev-app-servers:*"
+      ]
+    },
+
+    // developers have access to databases servers and application servers on all ports
+    // they can only view the applications servers in prod and have no access to databases servers in production
+    {
+      "action": "accept",
+      "src": ["group:dev"],
+      "dst": [
+        "tag:dev-databases:*",
+        "tag:dev-app-servers:*",
+        "tag:prod-app-servers:80,443"
+      ]
+    },
+    // 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
+    {
+      "action": "accept",
+      "src": ["group:dev"],
+      "dst": ["10.20.0.0/16:443,5432", "router.internal:0"]
+    },
+
+    // servers should be able to talk to database in tcp/5432. Database should not be able to initiate connections to
+    // applications servers
+    {
+      "action": "accept",
+      "src": ["tag:dev-app-servers"],
+      "proto": "tcp",
+      "dst": ["tag:dev-databases:5432"]
+    },
+    {
+      "action": "accept",
+      "src": ["tag:prod-app-servers"],
+      "dst": ["tag:prod-databases:5432"]
+    },
+
+    // interns have access to dev-app-servers only in reading mode
+    {
+      "action": "accept",
+      "src": ["group:intern"],
+      "dst": ["tag:dev-app-servers:80,443"]
+    },
+
+    // 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:*"] }
+  ]
+}
+```

docs/android-client.md

@@ -0,0 +1,19 @@
+# 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

@@ -0,0 +1,92 @@
+# 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

@@ -0,0 +1,49 @@
+# 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

@@ -0,0 +1,57 @@
+---
+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

@@ -0,0 +1,6 @@
+# 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

@@ -0,0 +1,30 @@
+# 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

@@ -0,0 +1,43 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
+# headscale
+
+`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/).
+
+Join our [Discord](https://discord.gg/c84AZQhmpx) server 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.
+
+## Supporting headscale
+
+If you like `headscale` and find it useful, there is a sponsorship and donation
+buttons available in the repo.
+
+## 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.
+
+## About
+
+`headscale` is maintained by [Kristoffer Dalby](https://kradalby.no/) and [Juan Font](https://font.eu).

docs/logo/headscale3-dots.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xml:space="preserve" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2" viewBox="0 0 1280 640"><circle cx="141.023" cy="338.36" r="117.472" style="fill:#f8b5cb" transform="matrix(.997276 0 0 1.00556 10.0024 -14.823)"/><circle cx="352.014" cy="268.302" r="33.095" style="fill:#a2a2a2" transform="matrix(1.01749 0 0 1 -3.15847 0)"/><circle cx="352.014" cy="268.302" r="33.095" style="fill:#a2a2a2" transform="matrix(1.01749 0 0 1 -3.15847 115.914)"/><circle cx="352.014" cy="268.302" r="33.095" style="fill:#a2a2a2" transform="matrix(1.01749 0 0 1 148.43 115.914)"/><circle cx="352.014" cy="268.302" r="33.095" style="fill:#a2a2a2" transform="matrix(1.01749 0 0 1 148.851 0)"/><circle cx="805.557" cy="336.915" r="118.199" style="fill:#8d8d8d" transform="matrix(.99196 0 0 1 3.36978 -10.2458)"/><circle cx="805.557" cy="336.915" r="118.199" style="fill:#8d8d8d" transform="matrix(.99196 0 0 1 255.633 -10.2458)"/><path d="M680.282 124.808h-68.093v390.325h68.081v-28.23H640V153.228h40.282v-28.42Z" style="fill:#303030"/><path d="M680.282 124.808h-68.093v390.325h68.081v-28.23H640V153.228h40.282v-28.42Z" style="fill:#303030" transform="matrix(-1 0 0 1 1857.19 0)"/></svg>

docs/oidc.md

@@ -0,0 +1,174 @@
+# Configuring Headscale to use OIDC authentication
+
+In order to authenticate users through a centralized solution one must enable the OIDC integration.
+
+Known limitations:
+
+- No dynamic ACL support
+- OIDC groups cannot be used in ACLs
+
+## Basic configuration
+
+In your `config.yaml`, customize this to your liking:
+
+```yaml
+oidc:
+  # Block further startup until the OIDC provider is healthy and available
+  only_start_if_oidc_is_available: true
+  # Specified by your OIDC provider
+  issuer: "https://your-oidc.issuer.com/path"
+  # Specified/generated by your OIDC provider
+  client_id: "your-oidc-client-id"
+  client_secret: "your-oidc-client-secret"
+  # alternatively, set `client_secret_path` to read the secret from the file.
+  # It resolves environment variables, making integration to systemd's
+  # `LoadCredential` straightforward:
+  #client_secret_path: "${CREDENTIALS_DIRECTORY}/oidc_client_secret"
+  # as third option, it's also possible to load the oidc secret from environment variables
+  # set HEADSCALE_OIDC_CLIENT_SECRET to the required value
+
+  # Customize the scopes used in the OIDC flow, defaults to "openid", "profile" and "email" and add custom query
+  # parameters to the Authorize Endpoint request. Scopes default to "openid", "profile" and "email".
+  scope: ["openid", "profile", "email", "custom"]
+  # Optional: Passed on to the browser login request – used to tweak behaviour for the OIDC provider
+  extra_params:
+    domain_hint: example.com
+
+  # Optional: List allowed principal domains and/or users. If an authenticated user's domain is not in this list,
+  # the authentication request will be rejected.
+  allowed_domains:
+    - example.com
+  # Optional. Note that groups from Keycloak have a leading '/'.
+  allowed_groups:
+    - /headscale
+  # Optional.
+  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
+```
+
+## 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:
+
+```hcl
+resource "azuread_application" "headscale" {
+  display_name = "Headscale"
+
+  sign_in_audience = "AzureADMyOrg"
+  fallback_public_client_enabled = false
+
+  required_resource_access {
+    // Microsoft Graph
+    resource_app_id = "00000003-0000-0000-c000-000000000000"
+
+    resource_access {
+      // scope: profile
+      id   = "14dad69e-099b-42c9-810b-d002981feec1"
+      type = "Scope"
+    }
+    resource_access {
+      // scope: openid
+      id   = "37f7f235-527c-4136-accd-4a02d197296e"
+      type = "Scope"
+    }
+    resource_access {
+      // scope: email
+      id   = "64a6cdd6-aab1-4aaf-94b8-3cc8405e90d0"
+      type = "Scope"
+    }
+  }
+  web {
+    # Points at your running Headscale instance
+    redirect_uris = ["https://headscale.example.com/oidc/callback"]
+
+    implicit_grant {
+      access_token_issuance_enabled = false
+      id_token_issuance_enabled = true
+    }
+  }
+
+  group_membership_claims = ["SecurityGroup"]
+  optional_claims {
+    # Expose group memberships
+    id_token {
+      name = "groups"
+    }
+  }
+}
+
+resource "azuread_application_password" "headscale-application-secret" {
+  display_name          = "Headscale Server"
+  application_object_id = azuread_application.headscale.object_id
+}
+
+resource "azuread_service_principal" "headscale" {
+  application_id = azuread_application.headscale.application_id
+}
+
+resource "azuread_service_principal_password" "headscale" {
+  service_principal_id = azuread_service_principal.headscale.id
+  end_date_relative    = "44640h"
+}
+
+output "headscale_client_id" {
+  value = azuread_application.headscale.application_id
+}
+
+output "headscale_client_secret" {
+  value = azuread_application_password.headscale-application-secret.value
+}
+```
+
+And in your Headscale `config.yaml`:
+
+```yaml
+oidc:
+  issuer: "https://login.microsoftonline.com/<tenant-UUID>/v2.0"
+  client_id: "<client-id-from-terraform>"
+  client_secret: "<client-secret-from-terraform>"
+
+  # Optional: add "groups"
+  scope: ["openid", "profile", "email"]
+  extra_params:
+    # Use your own domain, associated with Azure AD
+    domain_hint: example.com
+    # Optional: Force the Azure AD account picker
+    prompt: select_account
+```
+
+## 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.
+
+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.
+
+However if you don't have a domain, or need to add users outside of your domain, you can manually add emails via Google Console.
+
+### Steps
+
+1. Go to [Google Console](https://console.cloud.google.com) and login or create an account if you don't have one.
+2. Create a project (if you don't already have one).
+3. On the left hand menu, go to `APIs and services` -> `Credentials`
+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.
+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"]
+```
+
+You can also use `allowed_domains` and `allowed_users` to restrict the users who can authenticate.

docs/packaging/README.md

@@ -0,0 +1,5 @@
+# Packaging
+
+We use [nFPM](https://nfpm.goreleaser.com/) for making `.deb`, `.rpm` and `.apk`.
+
+This folder contains files we need to package with these releases.

docs/packaging/headscale.systemd.service

@@ -0,0 +1,51 @@
+[Unit]
+After=syslog.target
+After=network.target
+Description=headscale coordination server for Tailscale
+X-Restart-Triggers=/etc/headscale/config.yaml
+
+[Service]
+Type=simple
+User=headscale
+Group=headscale
+ExecStart=/usr/bin/headscale serve
+Restart=always
+RestartSec=5
+
+WorkingDirectory=/var/lib/headscale
+ReadWritePaths=/var/lib/headscale /var/run
+
+AmbientCapabilities=CAP_NET_BIND_SERVICE CAP_CHOWN
+CapabilityBoundingSet=CAP_NET_BIND_SERVICE CAP_CHOWN
+LockPersonality=true
+NoNewPrivileges=true
+PrivateDevices=true
+PrivateMounts=true
+PrivateTmp=true
+ProcSubset=pid
+ProtectClock=true
+ProtectControlGroups=true
+ProtectHome=true
+ProtectHostname=true
+ProtectKernelLogs=true
+ProtectKernelModules=true
+ProtectKernelTunables=true
+ProtectProc=invisible
+ProtectSystem=strict
+RemoveIPC=true
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
+RestrictNamespaces=true
+RestrictRealtime=true
+RestrictSUIDSGID=true
+RuntimeDirectory=headscale
+RuntimeDirectoryMode=0750
+StateDirectory=headscale
+StateDirectoryMode=0750
+SystemCallArchitectures=native
+SystemCallFilter=@chown
+SystemCallFilter=@system-service
+SystemCallFilter=~@privileged
+UMask=0077
+
+[Install]
+WantedBy=multi-user.target

docs/packaging/postinstall.sh

@@ -0,0 +1,86 @@
+#!/bin/sh
+# Determine OS platform
+# shellcheck source=/dev/null
+. /etc/os-release
+
+HEADSCALE_EXE="/usr/bin/headscale"
+BSD_HIER=""
+HEADSCALE_RUN_DIR="/var/run/headscale"
+HEADSCALE_USER="headscale"
+HEADSCALE_GROUP="headscale"
+
+ensure_sudo() {
+	if [ "$(id -u)" = "0" ]; then
+		echo "Sudo permissions detected"
+	else
+		echo "No sudo permission detected, please run as sudo"
+		exit 1
+	fi
+}
+
+ensure_headscale_path() {
+	if [ ! -f "$HEADSCALE_EXE" ]; then
+		echo "headscale not in default path, exiting..."
+		exit 1
+	fi
+
+	printf "Found headscale %s\n" "$HEADSCALE_EXE"
+}
+
+create_headscale_user() {
+	printf "PostInstall: Adding headscale user %s\n" "$HEADSCALE_USER"
+	useradd -s /bin/sh -c "headscale default user" headscale
+}
+
+create_headscale_group() {
+	if command -V systemctl >/dev/null 2>&1; then
+		printf "PostInstall: Adding headscale group %s\n" "$HEADSCALE_GROUP"
+		groupadd "$HEADSCALE_GROUP"
+
+		printf "PostInstall: Adding headscale user %s to group %s\n" "$HEADSCALE_USER" "$HEADSCALE_GROUP"
+		usermod -a -G "$HEADSCALE_GROUP" "$HEADSCALE_USER"
+	fi
+
+	if [ "$ID" = "alpine" ]; then
+		printf "PostInstall: Adding headscale group %s\n" "$HEADSCALE_GROUP"
+		addgroup "$HEADSCALE_GROUP"
+
+		printf "PostInstall: Adding headscale user %s to group %s\n" "$HEADSCALE_USER" "$HEADSCALE_GROUP"
+		addgroup "$HEADSCALE_USER" "$HEADSCALE_GROUP"
+	fi
+}
+
+create_run_dir() {
+	printf "PostInstall: Creating headscale run directory \n"
+	mkdir -p "$HEADSCALE_RUN_DIR"
+
+	printf "PostInstall: Modifying group ownership of headscale run directory \n"
+	chown "$HEADSCALE_USER":"$HEADSCALE_GROUP" "$HEADSCALE_RUN_DIR"
+}
+
+summary() {
+	echo "----------------------------------------------------------------------"
+	echo " headscale package has been successfully installed."
+	echo ""
+	echo " Please follow the next steps to start the software:"
+	echo ""
+	echo "    sudo systemctl enable headscale"
+	echo "    sudo systemctl start headscale"
+	echo ""
+	echo " Configuration settings can be adjusted here:"
+	echo "    ${BSD_HIER}/etc/headscale/config.yaml"
+	echo ""
+	echo "----------------------------------------------------------------------"
+}
+
+#
+# Main body of the script
+#
+{
+	ensure_sudo
+	ensure_headscale_path
+	create_headscale_user
+	create_headscale_group
+	create_run_dir
+	summary
+}

docs/packaging/postremove.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+# Determine OS platform
+# shellcheck source=/dev/null
+. /etc/os-release
+
+if command -V systemctl >/dev/null 2>&1; then
+	echo "Stop and disable headscale service"
+	systemctl stop headscale >/dev/null 2>&1 || true
+	systemctl disable headscale >/dev/null 2>&1 || true
+	echo "Running daemon-reload"
+	systemctl daemon-reload || true
+fi
+
+echo "Removing run directory"
+rm -rf "/var/run/headscale.sock"

docs/proposals/001-acls.md

@@ -0,0 +1,362 @@
+# 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

@@ -0,0 +1,48 @@
+# 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/remote-cli.md

@@ -0,0 +1,100 @@
+# 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

@@ -0,0 +1,4 @@
+cairosvg~=2.7.1
+mkdocs-material~=9.5.18
+mkdocs-minify-plugin~=0.7.1
+pillow~=10.1.0

docs/reverse-proxy.md

@@ -0,0 +1,137 @@
+# Running headscale behind a reverse proxy
+
+!!! 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**.
+
+Running headscale behind a reverse proxy is useful when running multiple applications on the same server, and you want to reuse the same external IP and port - usually tcp/443 for HTTPS.
+
+### WebSockets
+
+The reverse proxy MUST be configured to support WebSockets, as it is needed for clients running Tailscale v1.30+.
+
+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).
+
+### 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
+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
+tls_cert_path: ""
+tls_key_path: ""
+```
+
+## nginx
+
+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
+map $http_upgrade $connection_upgrade {
+    default      upgrade;
+    ''           close;
+}
+
+server {
+    listen 80;
+	listen [::]:80;
+
+	listen 443      ssl http2;
+	listen [::]:443 ssl http2;
+
+    server_name <YOUR_SERVER_NAME>;
+
+    ssl_certificate <PATH_TO_CERT>;
+    ssl_certificate_key <PATH_CERT_KEY>;
+    ssl_protocols TLSv1.2 TLSv1.3;
+
+    location / {
+        proxy_pass http://<IP:PORT>;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_set_header Host $server_name;
+        proxy_redirect http:// https://;
+        proxy_buffering off;
+        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;
+        add_header Strict-Transport-Security "max-age=15552000; includeSubDomains" always;
+    }
+}
+```
+
+## istio/envoy
+
+If you using [Istio](https://istio.io/) ingressgateway or [Envoy](https://www.envoyproxy.io/) as reverse proxy, there are some tips for you. If not set, you may see some debug log in proxy as below:
+
+```log
+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)
+
+### Istio
+
+Same as envoy, we can use `EnvoyFilter` to add upgrade_type.
+
+```yaml
+apiVersion: networking.istio.io/v1alpha3
+kind: EnvoyFilter
+metadata:
+  name: headscale-behind-istio-ingress
+  namespace: istio-system
+spec:
+  configPatches:
+    - applyTo: NETWORK_FILTER
+      match:
+        listener:
+          filterChain:
+            filter:
+              name: envoy.filters.network.http_connection_manager
+      patch:
+        operation: MERGE
+        value:
+          typed_config:
+            "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+            upgrade_configs:
+              - upgrade_type: tailscale-control-protocol
+```
+
+## Caddy
+
+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`.
+
+```
+<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.
+
+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.
+
+```
+<VirtualHost *:443>
+	ServerName <YOUR_SERVER_NAME>
+
+	ProxyPreserveHost On
+	ProxyPass / http://<IP:PORT>/ upgrade=any
+
+	SSLEngine On
+	SSLCertificateFile <PATH_TO_CERT>
+	SSLCertificateKeyFile <PATH_CERT_KEY>
+</VirtualHost>
+```

docs/running-headscale-container.md

@@ -0,0 +1,195 @@
+# 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

@@ -0,0 +1,197 @@
+# 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

@@ -0,0 +1,95 @@
+# 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

@@ -0,0 +1,210 @@
+# 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

@@ -0,0 +1,136 @@
+# 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/tls.md

@@ -0,0 +1,76 @@
+# Running the service via TLS (optional)
+
+## Bring your own certificate
+
+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
+tls_cert_path: ""
+tls_key_path: ""
+```
+
+## 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
+tls_letsencrypt_hostname: ""
+tls_letsencrypt_listen: ":http"
+tls_letsencrypt_cache_dir: ".cache"
+tls_letsencrypt_challenge_type: HTTP-01
+```
+
+### Challenge types
+
+Headscale only supports two values for `tls_letsencrypt_challenge_type`: `HTTP-01` (default) and `TLS-ALPN-01`.
+
+#### HTTP-01
+
+For `HTTP-01`, headscale must be reachable on port 80 for the Let's Encrypt automated validation, in addition to whatever port is configured in `listen_addr`. By default, headscale listens on port 80 on all local IPs for Let's Encrypt automated validation.
+
+If you need to change the ip and/or port used by headscale for the Let's Encrypt validation process, set `tls_letsencrypt_listen` to the appropriate value. This can be handy if you are running headscale as a non-root user (or can't run `setcap`). Keep in mind, however, that Let's Encrypt will _only_ connect to port 80 for the validation callback, so if you change `tls_letsencrypt_listen` you will also need to configure something else (e.g. a firewall rule) to forward the traffic from port 80 to the ip:port combination specified in `tls_letsencrypt_listen`.
+
+#### TLS-ALPN-01
+
+For `TLS-ALPN-01`, headscale listens on the ip:port combination defined in `listen_addr`. Let's Encrypt will _only_ connect to port 443 for the validation callback, so if `listen_addr` is not set to port 443, something else (e.g. a firewall rule) will be required to forward the traffic from port 443 to the ip:port combination specified in `listen_addr`.
+
+### Technical description
+
+Headscale uses [autocert](https://pkg.go.dev/golang.org/x/crypto/acme/autocert), a Golang library providing [ACME protocol](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) verification, to facilitate certificate renewals via [Let's Encrypt](https://letsencrypt.org/about/). Certificates will be renewed automatically, and the following can be expected:
+
+- Certificates provided from Let's Encrypt have a validity of 3 months from date issued.
+- Renewals are only attempted by headscale when 30 days or less remains until certificate expiry.
+- Renewal attempts by autocert are triggered at a random interval of 30-60 minutes.
+- No log output is generated when renewals are skipped, or successful.
+
+#### Checking certificate expiry
+
+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.
+2. Or, check remotely from CLI using `openssl`:
+
+```bash
+$ openssl s_client -servername [hostname] -connect [hostname]:443 | openssl x509 -noout -dates
+(...)
+notBefore=Feb  8 09:48:26 2024 GMT
+notAfter=May  8 09:48:25 2024 GMT
+```
+
+#### Log output from the autocert library
+
+As these log lines are from the autocert library, they are not strictly generated by headscale itself.
+
+```plaintext
+acme/autocert: missing server name
+```
+
+Likely caused by an incoming connection that does not specify a hostname, for example a `curl` request directly against the IP of the server, or an unexpected hostname.
+
+```plaintext
+acme/autocert: host "[foo]" not configured in HostWhitelist
+```
+
+Similarly to the above, this likely indicates an invalid incoming request for an incorrect hostname, commonly just the IP itself.
+
+The source code for autocert can be found [here](https://cs.opensource.google/go/x/crypto/+/refs/tags/v0.19.0:acme/autocert/autocert.go)

docs/web-ui.md

@@ -0,0 +1,15 @@
+# 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).