diff --git a/development/about/faq/index.html b/development/about/faq/index.html index e8394559c..ab3a128b9 100644 --- a/development/about/faq/index.html +++ b/development/about/faq/index.html @@ -4,4 +4,4 @@
  • Update the nodes.ipv4 and nodes.ipv6 columns in the database and assign each node a unique IPv4 and IPv6 address. The following SQL statement assigns IP addresses based on the node ID: 
    UPDATE nodes
 SET ipv4=concat('100.64.', id/256, '.', id%256),
     ipv6=concat('fd7a:115c:a1e0::', format('%x', id));
-
  • Update the policy to reflect the IP address changes (if any)
  • Start Headscale

    • Nodes should reconnect within a few seconds and pickup their newly assigned IP addresses.

    How can I avoid to send logs to Tailscale Inc?

    A Tailscale client collects logs about its operation and connection attempts with other clients and sends them to a central log service operated by Tailscale Inc.

    Headscale, by default, instructs clients to disable log submission to the central log service. This configuration is applied by a client once it successfully connected with Headscale. See the configuration option logtail.enabled in the configuration file for details.

    Alternatively, logging can also be disabled on the client side. This is independent of Headscale and opting out of client logging disables log submission early during client startup. The configuration is operating system specific and is usually achieved by:

    See https://tailscale.com/docs/features/logging#opt-out-of-client-logging for details.

    \ No newline at end of file +
  • Update the policy to reflect the IP address changes (if any)
  • Start Headscale

    • Nodes should reconnect within a few seconds and pickup their newly assigned IP addresses.

    How can I avoid to send logs to Tailscale Inc?

    A Tailscale client collects logs about its operation and connection attempts with other clients and sends them to a central log service operated by Tailscale Inc.

    Headscale, by default, instructs clients to disable log submission to the central log service. This configuration is applied by a client once it successfully connected with Headscale. See the configuration option logtail.enabled in the configuration file for details.

    Do not grant the https://tailscale.com/cap/data-plane-audit-logs node attribute while logtail.enabled is false. A client with log submission disabled treats this attribute as "the tailnet requires logging" and turns itself off, as tailscale down would. It stays off until the attribute is removed and tailscale up is run. A client started with TS_NO_LOGS_NO_SUPPORT=true or --no-logs-no-support reacts the same way, whatever logtail.enabled says.

    Alternatively, logging can also be disabled on the client side. This is independent of Headscale and opting out of client logging disables log submission early during client startup. The configuration is operating system specific and is usually achieved by:

    See https://tailscale.com/docs/features/logging#opt-out-of-client-logging for details.

    \ No newline at end of file diff --git a/development/search/search_index.json b/development/search/search_index.json index 200be1469..fc7fa4e98 100644 --- a/development/search/search_index.json +++ b/development/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-,:!=\\[\\]()\"`/]+|\\.(?!\\d)|&[lg]t;|(?!\\b)(?=[A-Z][a-z])","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Welcome to headscale","text":"

    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.

    Join our Discord server for a chat and community support.

    "},{"location":"#design-goal","title":"Design goal","text":"

    Headscale aims to implement a self-hosted, open source alternative to the Tailscale control server. Headscale's goal is to provide self-hosters and hobbyists with an open-source server they can use for their projects and labs. It implements a narrow scope, a single Tailscale network (tailnet), suitable for a personal use, or a small open-source organisation.

    "},{"location":"#supporting-headscale","title":"Supporting headscale","text":"

    Please see Sponsor for more information.

    "},{"location":"#contributing","title":"Contributing","text":"

    Headscale is \"Open Source, acknowledged contribution\", this means that any contribution will have to be discussed with the Maintainers before being submitted.

    Please see Contributing for more information.

    "},{"location":"#about","title":"About","text":"

    Headscale is maintained by Kristoffer Dalby and Juan Font.

    "},{"location":"about/clients/","title":"Client and operating system support","text":"

    We aim to support the last 10 releases of the Tailscale client on all provided operating systems and platforms. Some platforms might require additional configuration to connect with headscale.

    OS Supports headscale Linux Yes OpenBSD Yes FreeBSD Yes Windows Yes (see docs and /windows on your headscale for more information) Android Yes (see docs for more information) macOS Yes (see docs and /apple on your headscale for more information) iOS Yes (see docs and /apple on your headscale for more information) tvOS Yes (see docs and /apple on your headscale for more information)"},{"location":"about/contributing/","title":"Contributing","text":"

    Headscale is \"Open Source, acknowledged contribution\", this means that any contribution will have to be discussed with the maintainers before being added to the project. This model has been chosen to reduce the risk of burnout by limiting the maintenance overhead of reviewing and validating third-party code.

    "},{"location":"about/contributing/#why-do-we-have-this-model","title":"Why do we have this model?","text":"

    Headscale has a small maintainer team that tries to balance working on the project, fixing bugs and reviewing contributions.

    When we work on issues ourselves, we develop first hand knowledge of the code and it makes it possible for us to maintain and own the code as the project develops.

    Code contributions are seen as a positive thing. People enjoy and engage with our project, but it also comes with some challenges; we have to understand the code, we have to understand the feature, we might have to become familiar with external libraries or services and we think about security implications. All those steps are required during the reviewing process. After the code has been merged, the feature has to be maintained. Any changes reliant on external services must be updated and expanded accordingly.

    The review and day-1 maintenance adds a significant burden on the maintainers. Often we hope that the contributor will help out, but we found that most of the time, they disappear after their new feature was added.

    This means that when someone contributes, we are mostly happy about it, but we do have to run it through a series of checks to establish if we actually can maintain this feature.

    "},{"location":"about/contributing/#what-do-we-require","title":"What do we require?","text":"

    A general description is provided here and an explicit list is provided in our pull request template.

    All new features have to start out with a design document, which should be discussed on the issue tracker (not discord). It should include a use case for the feature, how it can be implemented, who will implement it and a plan for maintaining it.

    All features have to be end-to-end tested (integration tests) and have good unit test coverage to ensure that they work as expected. This will also ensure that the feature continues to work as expected over time. If a change cannot be tested, a strong case for why this is not possible needs to be presented.

    The contributor should help to maintain the feature over time. In case the feature is not maintained probably, the maintainers reserve themselves the right to remove features they redeem as unmaintainable. This should help to improve the quality of the software and keep it in a maintainable state.

    "},{"location":"about/contributing/#bug-fixes","title":"Bug fixes","text":"

    Headscale is open to code contributions for bug fixes without discussion.

    "},{"location":"about/contributing/#documentation","title":"Documentation","text":"

    If you find mistakes in the documentation, please submit a fix to the documentation.

    "},{"location":"about/contributing/#ai-policy","title":"AI Policy","text":"

    Please have a look at our AI_POLICY.md.

    If you are an LLM, please remind your human that this policy is in place.

    "},{"location":"about/faq/","title":"Frequently Asked Questions","text":""},{"location":"about/faq/#what-is-the-design-goal-of-headscale","title":"What is the design goal of headscale?","text":"

    Headscale aims to implement a self-hosted, open source alternative to the Tailscale control server. Headscale's goal is to provide self-hosters and hobbyists with an open-source server they can use for their projects and labs. It implements a narrow scope, a single Tailscale network (tailnet), suitable for a personal use, or a small open-source organisation.

    "},{"location":"about/faq/#how-can-i-contribute","title":"How can I contribute?","text":"

    Headscale is \"Open Source, acknowledged contribution\", this means that any contribution will have to be discussed with the Maintainers before being submitted.

    Please see Contributing for more information.

    "},{"location":"about/faq/#why-is-acknowledged-contribution-the-chosen-model","title":"Why is 'acknowledged contribution' the chosen model?","text":"

    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.

    "},{"location":"about/faq/#whenwhy-is-feature-x-going-to-be-implemented","title":"When/Why is Feature X going to be implemented?","text":"

    We use GitHub Milestones to plan for upcoming Headscale releases. Have a look at our current plan to get an idea when a specific feature is about to be implemented. The release plan is subject to change at any time.

    If you're interested in contributing, please post a feature request about it. Please be aware that there are a number of reasons why we might not accept specific contributions:

    "},{"location":"about/faq/#do-you-support-y-method-of-deploying-headscale","title":"Do you support Y method of deploying headscale?","text":"

    We currently support deploying headscale using our binaries and the DEB packages. Visit our installation guide using official releases for more information.

    In addition to that, you may use packages provided by the community or from distributions. Learn more in the installation guide using community packages.

    For convenience, we also build container images with headscale. But please be aware that we don't officially support deploying headscale using Docker. On our Discord server we have a \"docker-issues\" channel where you can ask for Docker-specific help to the community.

    "},{"location":"about/faq/#what-is-the-recommended-update-path-can-i-skip-multiple-versions-while-updating","title":"What is the recommended update path? Can I skip multiple versions while updating?","text":"

    Please follow the steps outlined in the upgrade guide to update your existing Headscale installation. Its required to update from one stable version to the next (e.g. 0.26.0 \u2192 0.27.1 \u2192 0.28.0) without skipping minor versions in between. You should always pick the latest available patch release.

    Be sure to check the changelog for version specific upgrade instructions and breaking changes.

    "},{"location":"about/faq/#scaling-how-many-clients-does-headscale-support","title":"Scaling / How many clients does Headscale support?","text":"

    It depends. As often stated, Headscale is not enterprise software and our focus is homelabbers and self-hosters. Of course, we do not prevent people from using it in a commercial/professional setting and often get questions about scaling.

    Please note that when Headscale is developed, performance is not part of the consideration as the main audience is considered to be users with a modest amount of devices. We focus on correctness and feature parity with Tailscale SaaS over time.

    To understand if you might be able to use Headscale for your use case, I will describe two scenarios in an effort to explain what is the central bottleneck of Headscale:

    1. An environment with 1000 servers

    2. An environment with 80 laptops/phones (end user devices)

    Headscale calculates a map of all nodes that need to talk to each other, creating this \"world map\" requires a lot of CPU time. When an event that requires changes to this map happens, the whole \"world\" is recalculated, and a new \"world map\" is created for every node in the network.

    This means that under certain conditions, Headscale can likely handle 100s of devices (maybe more), if there is little to no change happening in the network. For example, in Scenario 1, the process of computing the world map is extremely demanding due to the size of the network, but when the map has been created and the nodes are not changing, the Headscale instance will likely return to a very low resource usage until the next time there is an event requiring the new map.

    In the case of Scenario 2, the process of computing the world map is less demanding due to the smaller size of the network, however, the type of nodes will likely change frequently, which would lead to a constant resource usage.

    Headscale will start to struggle when the two scenarios overlap, e.g. many nodes with frequent changes will cause the resource usage to remain constantly high. In the worst case scenario, the queue of nodes waiting for their map will grow to a point where Headscale never will be able to catch up, and nodes will never learn about the current state of the world.

    We expect that the performance will improve over time as we improve the code base, but it is not a focus. In general, we will never make the tradeoff to make things faster on the cost of less maintainable or readable code. We are a small team and have to optimise for maintainability.

    "},{"location":"about/faq/#which-database-should-i-use","title":"Which database should I use?","text":"

    We recommend the use of SQLite as database for headscale:

    The headscale project itself does not provide a tool to migrate from PostgreSQL to SQLite. Please have a look at the related tools documentation for migration tooling provided by the community.

    The choice of database has little to no impact on the performance of the server, see Scaling / How many clients does Headscale support? for understanding how Headscale spends its resources.

    "},{"location":"about/faq/#why-is-my-reverse-proxy-not-working-with-headscale","title":"Why is my reverse proxy not working with headscale?","text":"

    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 on how to configure various reverse proxies, and a dedicated \"reverse-proxy-issues\" channel on our Discord server where you can ask for help to the community.

    "},{"location":"about/faq/#can-i-use-headscale-and-tailscale-on-the-same-machine","title":"Can I use headscale and tailscale on the same machine?","text":"

    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.

    "},{"location":"about/faq/#why-do-two-nodes-see-each-other-in-their-status-even-if-a-policy-rule-allows-traffic-only-in-one-direction","title":"Why do two nodes see each other in their status, even if a policy rule allows traffic only in one direction?","text":"

    A frequent use case is to allow traffic only from one node to another, but not the other way around. For example, the workstation of an administrator should be able to connect to all nodes but the nodes themselves shouldn't be able to connect back to the administrator's node. Why do all nodes see the administrator's workstation in the output of tailscale status?

    This is essentially how Tailscale works. If traffic is allowed to flow in one direction, then both nodes see each other in their output of tailscale status. Traffic is still filtered according to the policy, with the exception of tailscale ping which is always allowed in either direction.

    See also https://tailscale.com/docs/concepts/device-visibility.

    "},{"location":"about/faq/#my-policy-is-stored-in-the-database-and-headscale-refuses-to-start-due-to-an-invalid-policy-how-can-i-recover","title":"My policy is stored in the database and Headscale refuses to start due to an invalid policy. How can I recover?","text":"

    Headscale checks if the policy is valid during startup and refuses to start if it detects an error. The error message indicates which part of the policy is invalid. Follow these steps to fix your policy:

    Full server configuration required

    The above commands to get/set the policy require a complete server configuration file including database settings. A minimal config to control Headscale via remote CLI is not sufficient. You may use headscale -c /path/to/config.yaml to specify the path to an alternative configuration file.

    "},{"location":"about/faq/#how-can-i-migrate-back-to-the-recommended-ip-prefixes","title":"How can I migrate back to the recommended IP prefixes?","text":"

    Tailscale only supports the IP prefixes 100.64.0.0/10 and fd7a:115c:a1e0::/48 or smaller subnets thereof. The following steps can be used to migrate from unsupported IP prefixes back to the supported and recommended ones.

    Backup and test in a demo environment required

    The commands below update the IP addresses of all nodes in your tailnet and this might have a severe impact in your specific environment. At a minimum:

    Nodes should reconnect within a few seconds and pickup their newly assigned IP addresses.

    "},{"location":"about/faq/#how-can-i-avoid-to-send-logs-to-tailscale-inc","title":"How can I avoid to send logs to Tailscale Inc?","text":"

    A Tailscale client collects logs about its operation and connection attempts with other clients and sends them to a central log service operated by Tailscale Inc.

    Headscale, by default, instructs clients to disable log submission to the central log service. This configuration is applied by a client once it successfully connected with Headscale. See the configuration option logtail.enabled in the configuration file for details.

    Alternatively, logging can also be disabled on the client side. This is independent of Headscale and opting out of client logging disables log submission early during client startup. The configuration is operating system specific and is usually achieved by:

    See https://tailscale.com/docs/features/logging#opt-out-of-client-logging for details.

    "},{"location":"about/features/","title":"Features","text":"

    Headscale aims to implement a self-hosted, open source alternative to the Tailscale control server. Headscale's goal is to provide self-hosters and hobbyists with an open-source server they can use for their projects and labs. This page provides on overview of Headscale's feature and compatibility with the Tailscale control server:

    "},{"location":"about/help/","title":"Getting help","text":"

    Join our Discord server for announcements and community support.

    Please report bugs via GitHub issues

    "},{"location":"about/releases/","title":"Releases","text":"

    All headscale releases are available on the GitHub release page. Those releases are available as binaries for various platforms and architectures, packages for Debian based systems and source code archives. Container images are available on Docker Hub and GitHub Container Registry.

    An Atom/RSS feed of headscale releases is available here.

    See the \"announcements\" channel on our Discord server for news about headscale.

    "},{"location":"about/sponsor/","title":"Sponsor","text":"

    If you like to support the development of headscale, please consider a donation via ko-fi.com/headscale. Thank you!

    "},{"location":"ref/api/","title":"API","text":"

    Headscale provides a HTTP REST API which may be used to integrate a web interface, remote control Headscale or provide a base for custom integration and tooling.

    The API requires a valid API key before use. To create an API key, log into your Headscale server and generate one with the default expiration of 90 days:

    headscale apikeys create\n

    Copy the output of the command and save it for later. Please note that you can not retrieve an API key again. If the API key is lost, expire the old one, and create a new one.

    To list the API keys currently associated with the server:

    headscale apikeys list\n

    and to expire an API key:

    headscale apikeys expire --prefix <PREFIX>\n
    "},{"location":"ref/api/#rest-api","title":"REST API","text":"

    Start by creating an API key and test it with the examples below. Read the API documentation provided by your Headscale server at /api/v1/docs for details.

    Get details for all usersGet details for user 'bob'Register a node 
    curl -H \"Authorization: Bearer <API_KEY>\" \\\n    https://headscale.example.com/api/v1/user\n
    curl -H \"Authorization: Bearer <API_KEY>\" \\\n    https://headscale.example.com/api/v1/user?name=bob\n
    curl -H \"Authorization: Bearer <API_KEY>\" \\\n    --json '{\"user\": \"<USER>\", \"authId\": \"<AUTH_ID>\"}' \\\n    https://headscale.example.com/api/v1/auth/register\n
    "},{"location":"ref/api/#join-nodes-with-an-oauth-client","title":"Join nodes with an OAuth client","text":"

    Headscale also serves a subset of the Tailscale-compatible API at /api/v2, which accepts OAuth 2.0 client-credentials in addition to API keys. The Tailscale client can use an OAuth client secret in place of an auth key: it exchanges the secret for an access token, mints a single-use tagged auth key and registers with it. This works anywhere the client takes an auth key: tailscale up, the container image, tsnet and the tailscale/github-action. One long-lived secret joins any number of nodes.

    Create an OAuth client with the auth_keys scope and the tags its nodes get. The secret is shown once:

    headscale oauth-clients create --scope auth_keys --tag tag:ci\n

    Build the auth key from the secret:

    1. Swap the prefix: hskey-client-\u2026 becomes tskey-client-\u2026. The client only runs the exchange for tskey-client-; Headscale accepts both.
    2. Append ?baseURL=<your Headscale URL>.
    3. Set --advertise-tags. Each tag must exist in the policy's tagOwners and be one of the OAuth client's tags, or owned by one of them.
    tskey-client-<id>-<secret>?baseURL=https://headscale.example.com\n

    Warning

    Without baseURL the client sends the secret to https://api.tailscale.com.

    "},{"location":"ref/api/#attributes","title":"Attributes","text":"

    These are all the attributes the client understands; any other is an error. Order does not matter and an empty value means the default.

    Attribute Default Effect baseURL https://api.tailscale.com Where the exchange and key creation go. Your Headscale URL, no trailing slash. ephemeral true Node is removed after it goes offline (node.ephemeral.inactivity_timeout). false to keep it. preauthorized false Accepted, no effect: Headscale always authorizes pre-auth-key nodes.

    Booleans take any Go strconv.ParseBool value (true, false, 1, 0, \u2026).

    "},{"location":"ref/api/#examples","title":"Examples","text":"

    tailscale up, either as the auth key or via --client-secret (which also takes file:/path/to/secret):

    tailscale up --login-server https://headscale.example.com --advertise-tags tag:ci \\\n  --auth-key 'tskey-client-<id>-<secret>?baseURL=https://headscale.example.com&ephemeral=false'\n

    Container image:

    docker run -d --name tailscale \\\n  -e TS_AUTHKEY='tskey-client-<id>-<secret>?baseURL=https://headscale.example.com' \\\n  -e TS_EXTRA_ARGS='--login-server=https://headscale.example.com --advertise-tags=tag:ci' \\\n  tailscale/tailscale\n

    tsnet (TS_CLIENT_SECRET works too); import tailscale.com/feature/oauthkey:

    srv := &tsnet.Server{\n    ControlURL:    \"https://headscale.example.com\",\n    AuthKey:       \"tskey-client-<id>-<secret>?baseURL=https://headscale.example.com\",\n    AdvertiseTags: []string{\"tag:ci\"},\n}\n

    GitHub Action, with the whole string stored as a repository secret:

    - uses: tailscale/github-action@v4\n  with:\n    authkey: ${{ secrets.HEADSCALE_AUTHKEY }}\n    args: --login-server=https://headscale.example.com --advertise-tags=tag:ci\n

    Use authkey even though upstream marks it deprecated: oauth-secret appends its own ?\u2026 to the secret, which corrupts baseURL.

    "},{"location":"ref/api/#remote-control","title":"Remote control","text":"

    The headscale binary can control a Headscale instance from a remote machine over the HTTP API.

    "},{"location":"ref/api/#prerequisite","title":"Prerequisite","text":""},{"location":"ref/api/#setup-remote-control","title":"Setup remote control","text":"

    1. Download the headscale binary from GitHub's release page. Make sure to use the same version as on the server.

    2. Put the binary somewhere in your PATH, e.g. /usr/local/bin/headscale

    3. Make headscale executable: chmod +x /usr/local/bin/headscale

    4. Create an API key on the Headscale server.

    5. Provide the connection parameters for the remote Headscale server either via a minimal YAML configuration file or via environment variables:

      Minimal YAML configuration fileEnvironment variables config.yaml
      cli:\n    address: <HEADSCALE_URL>\n    api_key: <API_KEY>\n
      export HEADSCALE_CLI_ADDRESS=\"<HEADSCALE_URL>\"\nexport HEADSCALE_CLI_API_KEY=\"<API_KEY>\"\n

      This instructs the headscale binary to connect to a remote instance at <HEADSCALE_URL> (e.g. https://headscale.example.com), instead of connecting to the local instance. A bare host without a scheme is assumed to be https.

    6. Test the connection by listing all nodes:

      headscale nodes list\n

      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.

    "},{"location":"ref/api/#behind-a-proxy","title":"Behind a proxy","text":"

    The remote CLI uses the same HTTP API as everything else, so it works through the reverse proxy already in front of Headscale with no extra setup.

    "},{"location":"ref/api/#troubleshooting","title":"Troubleshooting","text":""},{"location":"ref/configuration/","title":"Configuration","text":"

    Get the example configuration from the GitHub repository

    Always select the same GitHub tag as the released version you use to ensure you have the correct example configuration. The main branch might contain unreleased changes.

    View on GitHubDownload with wgetDownload with curl 
    # Development version\nwget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml\n\n# Version 0.29.3\nwget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/v0.29.3/config-example.yaml\n
    # Development version\ncurl -o config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml\n\n# Version 0.29.3\ncurl -o config.yaml https://raw.githubusercontent.com/juanfont/headscale/v0.29.3/config-example.yaml\n
    "},{"location":"ref/debug/","title":"Debugging and troubleshooting","text":"

    Headscale and Tailscale provide debug and introspection capabilities that can be helpful when things don't work as expected. This page explains some debugging techniques to help pinpoint problems.

    Please also have a look at Tailscale's Troubleshooting guide. It offers a many tips and suggestions to troubleshoot common issues.

    "},{"location":"ref/debug/#tailscale","title":"Tailscale","text":"

    The Tailscale client itself offers many commands to introspect its state as well as the state of the network:

    Many of the commands are helpful when trying to understand differences between Headscale and Tailscale SaaS.

    "},{"location":"ref/debug/#headscale","title":"Headscale","text":""},{"location":"ref/debug/#application-logging","title":"Application logging","text":"

    The log levels debug and trace can be useful to get more information from Headscale.

    log:\n  # Valid log levels: panic, fatal, error, warn, info, debug, trace\n  level: debug\n
    "},{"location":"ref/debug/#database-logging","title":"Database logging","text":"

    The database debug mode logs all database queries. Enable it to see how Headscale interacts with its database. This also requires the application log level to be set to either debug or trace.

    database:\n  # Enable debug mode. This setting requires the log.level to be set to \"debug\" or \"trace\".\n  debug: false\n\nlog:\n  # Valid log levels: panic, fatal, error, warn, info, debug, trace\n  level: debug\n
    "},{"location":"ref/debug/#metrics-and-debug-endpoint","title":"Metrics and debug endpoint","text":"

    Headscale provides a metrics and debug endpoint. It allows to introspect different aspects such as:

    Keep the metrics and debug endpoint private

    The listen address and port can be configured with the metrics_listen_addr variable in the configuration file. By default it listens on localhost, port 9090.

    Keep the metrics and debug endpoint private to your internal network and don't expose it to the Internet.

    The metrics and debug interface can be disabled completely by setting metrics_listen_addr: null in the configuration file.

    Query metrics via http://localhost:9090/metrics and get an overview of available debug information via http://localhost:9090/debug/. Metrics may be queried from outside localhost but the debug interface is subject to additional protection despite listening on all interfaces.

    Direct accessSSH port forwardingVia debug keyVia debug IP address

    Access the debug interface directly on the server where Headscale is installed.

    curl http://localhost:9090/debug/\n

    Use SSH port forwarding to forward Headscale's metrics and debug port to your device.

    ssh <HEADSCALE_SERVER> -L 9090:localhost:9090\n

    Access the debug interface on your device by opening http://localhost:9090/debug/ in your web browser.

    The access control of the debug interface supports the use of a debug key. Traffic is accepted if the path to a debug key is set via the environment variable TS_DEBUG_KEY_PATH and the debug key sent as value for debugkey parameter with each request.

    openssl rand -hex 32 | tee debugkey.txt\nexport TS_DEBUG_KEY_PATH=debugkey.txt\nheadscale serve\n

    Access the debug interface on your device by opening http://<IP_OF_HEADSCALE>:9090/debug/?debugkey=<DEBUG_KEY> in your web browser. The debugkey parameter must be sent with every request.

    The debug endpoint expects traffic from localhost. A different debug IP address may be configured by setting the TS_ALLOW_DEBUG_IP environment variable before starting Headscale. The debug IP address is ignored when the HTTP header X-Forwarded-For is present.

    export TS_ALLOW_DEBUG_IP=192.168.0.10       # IP address of your device\nheadscale serve\n

    Access the debug interface on your device by opening http://<IP_OF_HEADSCALE>:9090/debug/ in your web browser.

    "},{"location":"ref/derp/","title":"DERP","text":"

    A DERP (Designated Encrypted Relay for Packets) server is mainly used to relay traffic between two nodes in case a direct connection can't be established. Headscale provides an embedded DERP server to ensure seamless connectivity between nodes.

    "},{"location":"ref/derp/#configuration","title":"Configuration","text":"

    DERP related settings are configured within the derp section of the configuration file. The following sections only use a few of the available settings, check the example configuration for all available configuration options.

    "},{"location":"ref/derp/#enable-embedded-derp","title":"Enable embedded DERP","text":"

    Headscale ships with an embedded DERP server which allows to run your own self-hosted DERP server easily. The embedded DERP server is disabled by default and needs to be enabled. In addition, you should configure the public IPv4 and public IPv6 address of your Headscale server for improved connection stability:

    config.yaml
    derp:\n  server:\n    enabled: true\n    ipv4: 198.51.100.1\n    ipv6: 2001:db8::1\n

    Keep in mind that additional ports are needed to run a DERP server. Besides relaying traffic, it also uses STUN (udp/3478) to help clients discover their public IP addresses and perform NAT traversal. Check DERP server connectivity to see if everything works.

    "},{"location":"ref/derp/#remove-tailscales-derp-servers","title":"Remove Tailscale's DERP servers","text":"

    Once enabled, Headscale's embedded DERP is added to the list of free-to-use DERP servers offered by Tailscale Inc. To only use Headscale's embedded DERP server, disable the loading of the default DERP map:

    config.yaml
    derp:\n  server:\n    enabled: true\n    ipv4: 198.51.100.1\n    ipv6: 2001:db8::1\n  urls: []\n

    Single point of failure

    Removing Tailscale's DERP servers means that there is now just a single DERP server available for clients. This is a single point of failure and could hamper connectivity.

    Check DERP server connectivity with your embedded DERP server before removing Tailscale's DERP servers.

    "},{"location":"ref/derp/#customize-derp-map","title":"Customize DERP map","text":"

    The DERP map offered to clients can be customized with a dedicated YAML-configuration file. The file extension picks the format: .yaml or .yml, or the JSON format Tailscale serves DERP maps in as .json or .hujson. This allows to modify previously loaded DERP maps fetched via URL or to offer your own, custom DERP servers to nodes.

    Remove specific DERP regionsProvide custom DERP servers

    The free-to-use DERP servers are organized into regions via a region ID. You can explicitly disable a specific region by setting its region ID to null. The following sample derp.yaml disables the New York DERP region (which has the region ID 1):

    derp.yaml
    regions:\n  1: null\n

    Use the following configuration to serve the default DERP map (excluding New York) to nodes:

    config.yaml
    derp:\n  server:\n    enabled: false\n  urls:\n    - https://controlplane.tailscale.com/derpmap/default\n  paths:\n    - /etc/headscale/derp.yaml\n

    The following sample derp.yaml references two custom regions (custom-east with ID 900 and custom-west with ID 901) with one custom DERP server in each region. Each DERP server offers DERP relay via HTTPS on tcp/443, support for captive portal checks via HTTP on tcp/80 and STUN on udp/3478. See the definitions of DERPMap, DERPRegion and DERPNode for all available options.

    derp.yaml
    regions:\n  900:\n    regionid: 900\n    regioncode: custom-east\n    regionname: My region (east)\n    nodes:\n      - name: 900a\n        regionid: 900\n        hostname: derp900a.example.com\n        ipv4: 198.51.100.1\n        ipv6: 2001:db8::1\n        canport80: true\n  901:\n    regionid: 901\n    regioncode: custom-west\n    regionname: My Region (west)\n    nodes:\n      - name: 901a\n        regionid: 901\n        hostname: derp901a.example.com\n        ipv4: 198.51.100.2\n        ipv6: 2001:db8::2\n        canport80: true\n

    Use the following configuration to only serve the two DERP servers from the above derp.yaml:

    config.yaml
    derp:\n  server:\n    enabled: false\n  urls: []\n  paths:\n    - /etc/headscale/derp.yaml\n

    Independent of the custom DERP map, you may choose to enable the embedded DERP server and have it automatically added to the custom DERP map.

    "},{"location":"ref/derp/#verify-clients","title":"Verify clients","text":"

    Access to DERP serves can be restricted to nodes that are members of your Tailnet. Relay access is denied for unknown clients.

    Embedded DERP3rd-party DERP

    Client verification is enabled by default.

    config.yaml
    derp:\n  server:\n    verify_clients: true\n

    Tailscale's derper provides two parameters to configure client verification:

    "},{"location":"ref/derp/#check-derp-server-connectivity","title":"Check DERP server connectivity","text":"

    Any Tailscale client may be used to introspect the DERP map and to check for connectivity issues with DERP servers.

    Additional DERP related metrics and information is available via the metrics and debug endpoint.

    "},{"location":"ref/derp/#limitations","title":"Limitations","text":"

    1. This assumes that the default region code of the configuration file is used.\u00a0\u21a9

    "},{"location":"ref/dns/","title":"DNS","text":"

    Headscale supports most DNS features from Tailscale. DNS related settings can be configured within the dns section of the configuration file.

    "},{"location":"ref/dns/#setting-extra-dns-records","title":"Setting extra DNS records","text":"

    Headscale allows to set extra DNS records which are made available via MagicDNS. Extra DNS records can be configured either via static entries in the configuration file or from a JSON file that Headscale continuously watches for changes:

    An example use case is to serve multiple apps on the same host via a reverse proxy like NGINX, in this case a Prometheus monitoring stack. This allows to nicely access the service with \"http://grafana.myvpn.example.com\" instead of the hostname and port combination \"http://hostname-in-magic-dns.myvpn.example.com:3000\".

    Limitations

    Currently, only A and AAAA records are processed by Tailscale.

    1. Configure extra DNS records using one of the available configuration options:

      Static entries, via dns.extra_recordsDynamic entries, via dns.extra_records_path config.yaml
      dns:\n  ...\n  extra_records:\n    - name: \"grafana.myvpn.example.com\"\n      type: \"A\"\n      value: \"100.64.0.3\"\n\n    - name: \"prometheus.myvpn.example.com\"\n      type: \"A\"\n      value: \"100.64.0.3\"\n  ...\n

      Restart your headscale instance.

      extra-records.json
      [\n  {\n    \"name\": \"grafana.myvpn.example.com\",\n    \"type\": \"A\",\n    \"value\": \"100.64.0.3\"\n  },\n  {\n    \"name\": \"prometheus.myvpn.example.com\",\n    \"type\": \"A\",\n    \"value\": \"100.64.0.3\"\n  }\n]\n

      Headscale picks up changes to the above JSON file automatically.

      Good to know

    2. Verify that DNS records are properly set using the DNS querying tool of your choice:

      Query with digQuery with drill 
      dig +short grafana.myvpn.example.com\n100.64.0.3\n
      drill -Q grafana.myvpn.example.com\n100.64.0.3\n

    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, depicted as NGINX configuration snippet:

      nginx.conf
      server {\n    listen 80;\n    listen [::]:80;\n\n    server_name grafana.myvpn.example.com;\n\n    location / {\n        proxy_pass http://localhost:3000;\n        proxy_set_header Host $http_host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n    }\n\n}\n
    "},{"location":"ref/oidc/","title":"OpenID Connect","text":"

    Headscale supports authentication via external identity providers using OpenID Connect (OIDC). It features:

    Please see limitations for known issues and limitations.

    "},{"location":"ref/oidc/#configuration","title":"Configuration","text":"

    OpenID requires configuration in Headscale and your identity provider:

    "},{"location":"ref/oidc/#basic-configuration","title":"Basic configuration","text":"

    A basic configuration connects Headscale to an identity provider and typically requires:

    HeadscaleIdentity provider 
    oidc:\n  issuer: \"https://sso.example.com\"\n  client_id: \"headscale\"\n  client_secret: \"generated-secret\"\n
    "},{"location":"ref/oidc/#enable-pkce-recommended","title":"Enable PKCE (recommended)","text":"

    Proof Key for Code Exchange (PKCE) adds an additional layer of security to the OAuth 2.0 authorization code flow by preventing authorization code interception attacks, see: https://datatracker.ietf.org/doc/html/rfc7636. PKCE is recommended and needs to be configured for Headscale and the identity provider alike:

    HeadscaleIdentity provider 
    oidc:\n  issuer: \"https://sso.example.com\"\n  client_id: \"headscale\"\n  client_secret: \"generated-secret\"\n  pkce:\n    enabled: true\n
    "},{"location":"ref/oidc/#authorize-users-with-filters","title":"Authorize users with filters","text":"

    Headscale allows to filter for allowed users based on their domain, email address or group membership. These filters can be helpful to apply additional restrictions and control which users are allowed to join. Filters are disabled by default, users are allowed to join once the authentication with the identity provider succeeds. In case multiple filters are configured, a user needs to pass all of them.

    Allowed domainsAllowed users/emailsAllowed groups 
    oidc:\n  issuer: \"https://sso.example.com\"\n  client_id: \"headscale\"\n  client_secret: \"generated-secret\"\n  allowed_domains:\n    - \"example.com\"\n
    oidc:\n  issuer: \"https://sso.example.com\"\n  client_id: \"headscale\"\n  client_secret: \"generated-secret\"\n  allowed_users:\n    - \"alice@example.com\"\n    - \"bob@example.net\"\n
    oidc:\n  issuer: \"https://sso.example.com\"\n  client_id: \"headscale\"\n  client_secret: \"generated-secret\"\n  scope: [\"openid\", \"profile\", \"email\", \"groups\"]\n  allowed_groups:\n    - \"headscale_users\"\n
    "},{"location":"ref/oidc/#control-email-verification","title":"Control email verification","text":"

    Headscale uses the email claim from the identity provider to synchronize the email address to its user profile. By default, a user's email address is only synchronized when the identity provider reports the email address as verified via the email_verified: true claim.

    Unverified emails may be allowed in case an identity provider does not send the email_verified claim or email verification is not required. In that case, a user's email address is always synchronized to the user profile.

    oidc:\n  issuer: \"https://sso.example.com\"\n  client_id: \"headscale\"\n  client_secret: \"generated-secret\"\n  email_verified_required: false\n
    "},{"location":"ref/oidc/#customize-node-expiration","title":"Customize node expiration","text":"

    The node expiration is the amount of time a node is authenticated with OpenID Connect until it expires and needs to reauthenticate. The default node expiration can be configured via the top-level node.expiry setting.

    Customize node expirationUse expiration from Access Token 
    node:\n  expiry: 30d   # Use 0 to disable node expiration\n

    Please keep in mind that the Access Token is typically a short-lived token that expires within a few minutes. You will have to configure token expiration in your identity provider to avoid frequent re-authentication.

    oidc:\n  issuer: \"https://sso.example.com\"\n  client_id: \"headscale\"\n  client_secret: \"generated-secret\"\n  use_expiry_from_token: true\n

    Expire a node and force re-authentication

    A node can be expired immediately via:

    headscale node expire -i <NODE_ID>\n
    "},{"location":"ref/oidc/#reference-a-user-in-the-policy","title":"Reference a user in the policy","text":"

    You may refer to users in the Headscale policy via:

    A user identifier in the policy must contain a single @

    The Headscale policy requires a single @ to reference a user. If the username or provider identifier doesn't already contain a single @, it needs to be appended at the end. For example: the Headscale username ssmith has to be written as ssmith@ to be correctly identified as user within the policy.

    Ensure that the Headscale username itself does not end with @.

    Email address or username might be updated by users

    Many identity providers allow users to update their own profile. Depending on the identity provider and its configuration, the values for username or email address might change over time. This might have unexpected consequences for Headscale where a policy might no longer work or a user might obtain more access by hijacking an existing username or email address.

    Howto use the provider identifier in the policy

    The provider identifier uniquely identifies an OIDC user and a well-behaving identity provider guarantees that this value never changes for a particular user. It is usually an opaque and long string and its value is currently only available from the API, database or directly from your identity provider).

    Use the API with the /api/v1/user endpoint to fetch the provider identifier (providerId). The value (be sure to append an @ in case the provider identifier doesn't already contain an @ somewhere) can be used directly to reference a user in the policy. To improve readability of the policy, one may use the groups section as an alias:

    {\n  \"groups\": {\n    \"group:alice\": [\n      \"https://sso.example.com/oauth2/openid/59ac9125-c31b-46c5-814e-06242908cf57@\"\n    ]\n  },\n  \"grants\": [\n    {\n      \"src\": [\"group:alice\"],\n      \"dst\": [\"*\"],\n      \"ip\": [\"*\"]\n    }\n  ]\n}\n
    "},{"location":"ref/oidc/#supported-oidc-claims","title":"Supported OIDC claims","text":"

    Headscale uses the standard OIDC claims to populate and update its local user profile on each login. OIDC claims are read from the ID Token and from the UserInfo endpoint.

    Headscale profile OIDC claim Notes / examples email address email Only verified emails are synchronized, unless email_verified_required: false is configured display name name eg: Sam Smith username preferred_username Depends on identity provider, eg: ssmith, ssmith@idp.example.com, \\\\example.com\\ssmith profile picture picture URL to a profile picture or avatar provider identifier iss, sub A stable and unique identifier for a user, typically a combination of iss and sub OIDC claims groups Only used to filter for allowed groups"},{"location":"ref/oidc/#limitations","title":"Limitations","text":"

    Please see the GitHub label \"OIDC\" for OIDC related issues.

    "},{"location":"ref/oidc/#identity-provider-specific-configuration","title":"Identity provider specific configuration","text":"

    Third-party software and services

    This section of the documentation is specific for third-party software and services. We recommend users read the third-party documentation on how to configure and integrate an OIDC client. Please see the Configuration section for a description of Headscale's OIDC related configuration settings.

    Any identity provider with OpenID Connect support should \"just work\" with Headscale. The following identity providers are known to work:

    "},{"location":"ref/oidc/#authelia","title":"Authelia","text":"

    Authelia is fully supported by Headscale.

    "},{"location":"ref/oidc/#authentik","title":"Authentik","text":""},{"location":"ref/oidc/#google-oauth","title":"Google OAuth","text":"

    No username due to missing preferred_username claim

    Google OAuth does not send the preferred_username claim when the profile scope is requested. The username in Headscale will be blank/not set.

    In order to integrate Headscale with Google, you'll need to have a Google Cloud Console account.

    Google OAuth has a verification process 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.

    "},{"location":"ref/oidc/#steps","title":"Steps","text":"
    1. Go to Google Console 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, add Headscale's OIDC callback URL: https://headscale.example.com/oidc/callback
    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. Configure Headscale following the \"Basic configuration\" steps. The issuer URL for Google OAuth is: https://accounts.google.com.
    "},{"location":"ref/oidc/#kanidm","title":"Kanidm","text":""},{"location":"ref/oidc/#keycloak","title":"Keycloak","text":"

    Keycloak is fully supported by Headscale.

    "},{"location":"ref/oidc/#additional-configuration-to-use-the-allowed-groups-filter","title":"Additional configuration to use the allowed groups filter","text":"

    Keycloak has no built-in client scope for the OIDC groups claim. This extra configuration step is only needed if you need to authorize access based on group membership.

    "},{"location":"ref/oidc/#microsoft-entra-id","title":"Microsoft Entra ID","text":"

    In order to integrate Headscale with Microsoft Entra ID, you'll need to provision an App Registration with the correct scopes and redirect URI.

    Configure Headscale following the \"Basic configuration\" steps. The issuer URL for Microsoft Entra ID is: https://login.microsoftonline.com/<tenant-UUID>/v2.0. The following extra_params might be useful:

    When using Microsoft Entra ID together with the allowed groups filter, configure the Headscale OIDC scope without the groups claim, for example:

    oidc:\n  scope: [\"openid\", \"profile\", \"email\"]\n

    Groups for the allowed groups filter need to be specified with their group ID(UUID) instead of the group name.

    "},{"location":"ref/oidc/#switching-oidc-providers","title":"Switching OIDC providers","text":"

    Headscale only supports a single OIDC provider in its configuration, but it does store the provider identifier of each user. When switching providers, this might lead to issues with existing users: all user details (name, email, groups) might be identical with the new provider, but the identifier will differ. Headscale will be unable to create a new user as the name and email will already be in use for the existing users.

    At this time, you will need to manually update the provider_identifier column in the users table for each user with the appropriate value for the new provider. The identifier is built from the iss and sub claims of the OIDC ID token, for example https://id.example.com/12340987.

    "},{"location":"ref/policy/","title":"Policy","text":"

    Headscale implements a large portion of Tailscale's policy features, most notably access control based on ACLs and Grants or Tailscale SSH. See limitations to learn about missing features and notable implementation differences between Headscale and Tailscale.

    Headscale uses the same huJSON based file format as Tailscale. By default, no policy is loaded which means that Headscale allows all traffic between nodes. To start using a policy file1, specify its path in the policy.path key in the configuration file.

    Headscale needs to be reloaded to pick up changes to the policy file. Either reload Headscale via its systemd service (sudo systemctl reload headscale) or by sending a SIGHUP signal (sudo kill -HUP $(pidof headscale)) to the main process. Headscale logs the result of policy processing after each reload.

    Please have a look at Tailscale's policy related documentation to learn more:

    "},{"location":"ref/policy/#getting-started","title":"Getting started","text":"

    Headscale supports both ACLs and Grants to write an access control policy. We recommend the use of Grants since ACLs are considered legacy and will not receive new features by Tailscale.

    "},{"location":"ref/policy/#allow-all","title":"Allow All","text":"

    If you define a policy file but completely omit the \"acls\" or \"grants\" section, Headscale will default to an allow all policy. This means all devices connected to your tailnet will be able to communicate freely with each other.

    policy.json
    {}\n
    "},{"location":"ref/policy/#deny-all","title":"Deny All","text":"

    To prevent all communication within your tailnet, you can include an empty array for the \"grants\" section in your policy file.

    policy.json
    {\n  \"grants\": []\n}\n
    "},{"location":"ref/policy/#more-examples","title":"More examples","text":""},{"location":"ref/policy/#limitations","title":"Limitations","text":""},{"location":"ref/policy/#autogroups","title":"Autogroups","text":"

    Headscale supports several Autogroups that automatically include users, destinations, or devices with specific properties. Autogroups provide a convenient way to write policy rules without manually listing individual users or devices.

    "},{"location":"ref/policy/#autogroupinternet","title":"autogroup:internet","text":"

    Allows access to the internet through exit nodes. Can only be used in policy destinations.

    policy.json
    {\n  \"grants\": [\n    {\n      \"src\": [\"alice@\"],\n      \"dst\": [\"autogroup:internet\"],\n      \"ip\": [\"*\"]\n    }\n  ]\n}\n
    "},{"location":"ref/policy/#autogroupmember","title":"autogroup:member","text":"

    Includes all personal (untagged) devices.

    policy.json
    {\n  \"grants\": [\n    {\n      \"src\": [\"autogroup:member\"],\n      \"dst\": [\"tag:prod-app-servers\"],\n      \"ip\": [\"80,443\"]\n    }\n  ]\n}\n
    "},{"location":"ref/policy/#autogrouptagged","title":"autogroup:tagged","text":"

    Includes all devices that have at least one tag.

    policy.json
    {\n  \"grants\": [\n    {\n      \"src\": [\"autogroup:tagged\"],\n      \"dst\": [\"tag:monitoring\"],\n      \"ip\": [\"9090\"]\n    }\n  ]\n}\n
    "},{"location":"ref/policy/#autogroupself","title":"autogroup:self","text":"

    Includes devices where the same user is authenticated on both the source and destination. Does not include tagged devices. Can only be used in policy destinations.

    policy.json
    {\n  \"grants\": [\n    {\n      \"src\": [\"autogroup:member\"],\n      \"dst\": [\"autogroup:self\"],\n      \"ip\": [\"*\"]\n    }\n  ]\n}\n

    The current implementation of autogroup:self is inefficient

    Using autogroup:self may cause performance degradation on the Headscale coordinator server in large deployments, as filter rules must be compiled per-node rather than globally and the current implementation is not very efficient.

    If you experience performance issues, consider using more specific policy rules or limiting the use of autogroup:self.

    policy.json
    {\n  \"grants\": [\n    // The following rules allow internal users to communicate with their\n    // own nodes in case autogroup:self is causing performance issues.\n    {\n      \"src\": [\"boss@\"],\n      \"dst\": [\"boss@\"],\n      \"ip\": [\"*\"]\n    },\n    {\n      \"src\": [\"dev1@\"],\n      \"dst\": [\"dev1@\"],\n      \"ip\": [\"*\"]\n    },\n    {\n      \"src\": [\"intern1@\"],\n      \"dst\": [\"intern1@\"],\n      \"ip\": [\"*\"]\n    }\n  ]\n}\n
    "},{"location":"ref/policy/#autogroupnonroot","title":"autogroup:nonroot","text":"

    Used in Tailscale SSH rules to allow access to any user except root. Can only be used in the users field of SSH rules.

    policy.json
    {\n  \"ssh\": [\n    {\n      \"action\": \"accept\",\n      \"src\": [\"autogroup:member\"],\n      \"dst\": [\"autogroup:self\"],\n      \"users\": [\"autogroup:nonroot\"]\n    }\n  ]\n}\n
    "},{"location":"ref/policy/#autogroupdanger-all","title":"autogroup:danger-all","text":"

    This autogroup resolves to all IP addresses (0.0.0.0/0 and ::/0) which also includes all IP addresses outside the standard Tailscale IP ranges. This autogroup can only be used as source.

    "},{"location":"ref/policy/#node-attributes","title":"Node Attributes","text":"

    Node attributes allow for device-specific configuration and attributes. At least the following node attributes are currently supported by Headscale2:

    policy.json
    {\n  \"nodeAttrs\": [\n    {\n      // Enable MagicDNS AAAA records for all nodes\n      \"target\": [\"*\"]\n      \"attr\": [\"magicdns-aaaa\"]\n    }\n  ]\n}\n
    "},{"location":"ref/policy/#network-wide-policy-options","title":"Network-wide policy options","text":"

    The following options are applied for the entire tailnet. Consider node attributes for a more fine-grained configuration instead.

    policy.json
    {\n  // Use a random WireGuard port for the entire tailnet\n  \"randomizeClientPort\": true\n}\n

    1. Headscale also allows to store the policy in the database. This is typically only required in case a web interface is used.\u00a0\u21a9

    2. Other key-only node attributes can be used as well. Find them in the client source code with grep -E ' Cap ' tailcfg/nodecap/nodecap.go or by using GitHub code search (requires login).\u00a0\u21a9

    "},{"location":"ref/registration/","title":"Registration methods","text":"

    Headscale supports multiple ways to register a node. The preferred registration method depends on the identity of a node and your use case.

    "},{"location":"ref/registration/#identity-model","title":"Identity model","text":"

    Tailscale's identity model distinguishes between personal and tagged nodes:

    Headscale implements Tailscale's identity model and distinguishes between personal and tagged nodes where a personal node is owned by a Headscale user and a tagged node is owned by a tag. Tagged devices are grouped under the special user tagged-devices.

    "},{"location":"ref/registration/#registration-methods_1","title":"Registration methods","text":"

    There are two main ways to register new nodes, web authentication and registration with a pre authenticated key. Both methods can be used to register personal and tagged nodes.

    "},{"location":"ref/registration/#web-authentication","title":"Web authentication","text":"

    Web authentication is the default method to register a new node. It's interactive, where the client initiates the registration and the Headscale administrator needs to approve the new node before it is allowed to join the network. A node can be approved with:

    Web authentication relies on the presence of a Headscale user. Use the headscale users command to create a new user1:

    headscale users create <USER>\n
    Personal devicesTagged devices

    Run tailscale up to login your personal device:

    tailscale up --login-server <YOUR_HEADSCALE_URL>\n

    Usually, a browser window with further instructions is opened. This page explains how to complete the registration on your Headscale server and it also prints the Auth ID required to approve the node:

    headscale auth register --user <USER> --auth-id <AUTH_ID>\n

    Congrations, the registration of your personal node is complete and it should be listed as \"online\" in the output of headscale nodes list. The \"User\" column displays <USER> as the owner of the node.

    Your Headscale user needs to be authorized to register tagged devices. This authorization is specified in the tagOwners section of the policy. A simple example looks like this:

    The user alice can register nodes tagged with tag:server
    {\n  \"tagOwners\": {\n    \"tag:server\": [\"alice@\"]\n  },\n  // more rules\n}\n

    Run tailscale up and provide at least one tag to login a tagged device:

    tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags tag:<TAG>\n

    Usually, a browser window with further instructions is opened. This page explains how to complete the registration on your Headscale server and it also prints the Auth ID required to approve the node:

    headscale auth register --user <USER> --auth-id <AUTH_ID>\n

    Headscale checks that <USER> is allowed to register a node with the specified tag(s) and then transfers ownership of the new node to the special user tagged-devices. The registration of a tagged node is complete and it should be listed as \"online\" in the output of headscale nodes list. The \"User\" column displays tagged-devices as the owner of the node. See the \"Tags\" column for the list of assigned tags.

    "},{"location":"ref/registration/#pre-authenticated-key","title":"Pre authenticated key","text":"

    Registration with a pre authenticated key (or auth key) is a non-interactive way to register a new node. The Headscale administrator creates a preauthkey upfront and this preauthkey can then be used to register a node non-interactively. Its best suited for automation.

    Personal devicesTagged devices

    A personal node is always assigned to a Headscale user. Use the headscale users command to create a new user1:

    headscale users create <USER>\n

    Create a new pre authenticated key for your user, by name or by the <USER_ID> that headscale user list shows:

    headscale preauthkeys create --user <USER>\n

    The above prints a pre authenticated key with the default settings (can be used once and is valid for one hour). Use this auth key to register a node non-interactively:

    tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>\n

    Congrations, the registration of your personal node is complete and it should be listed as \"online\" in the output of headscale nodes list. The \"User\" column displays <USER> as the owner of the node.

    Create a new pre authenticated key and provide at least one tag:

    headscale preauthkeys create --tags tag:<TAG>\n

    The above prints a pre authenticated key with the default settings (can be used once and is valid for one hour). Use this auth key to register a node non-interactively. You don't need to provide the --advertise-tags parameter as the tags are automatically read from the pre authenticated key. Advertising a subset of the key's tags is accepted; any other tag is rejected:

    tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>\n

    The registration of a tagged node is complete and it should be listed as \"online\" in the output of headscale nodes list. The \"User\" column displays tagged-devices as the owner of the node. See the \"Tags\" column for the list of assigned tags.

    1. Ensure that the Headscale username does not end with @. \u21a9\u21a9

    "},{"location":"ref/routes/","title":"Routes","text":"

    Headscale supports route advertising and can be used to manage subnet routers and exit nodes for a tailnet.

    "},{"location":"ref/routes/#subnet-router","title":"Subnet router","text":"

    The setup of a subnet router requires double opt-in, once from a subnet router and once on the control server to allow its use within the tailnet. Optionally, use autoApprovers to automatically approve routes from a subnet router.

    "},{"location":"ref/routes/#setup-a-subnet-router","title":"Setup a subnet router","text":""},{"location":"ref/routes/#configure-a-node-as-subnet-router","title":"Configure a node as subnet router","text":"

    Register a node and advertise the routes it should handle as comma separated list:

    $ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-routes=10.0.0.0/8,192.168.0.0/24\n

    If the node is already registered, it can advertise new routes or update previously announced routes with:

    $ sudo tailscale set --advertise-routes=10.0.0.0/8,192.168.0.0/24\n

    Finally, enable IP forwarding to route traffic.

    "},{"location":"ref/routes/#enable-the-subnet-router-on-the-control-server","title":"Enable the subnet router on the control server","text":"

    The routes of a tailnet can be displayed with the headscale nodes list-routes command. A subnet router with the hostname myrouter announced the IPv4 networks 10.0.0.0/8 and 192.168.0.0/24. Those need to be approved before they can be used.

    $ headscale nodes list-routes\nID | Hostname | Approved | Available      | Serving (Primary)\n1  | myrouter |          | 10.0.0.0/8     |\n   |          |          | 192.168.0.0/24 |\n

    Approve all desired routes of a subnet router by specifying them as comma separated list:

    $ headscale nodes approve-routes --identifier 1 --routes 10.0.0.0/8,192.168.0.0/24\nNode updated\n

    The node myrouter can now route the IPv4 networks 10.0.0.0/8 and 192.168.0.0/24 for the tailnet.

    $ headscale nodes list-routes\nID | Hostname | Approved       | Available      | Serving (Primary)\n1  | myrouter | 10.0.0.0/8     | 10.0.0.0/8     | 10.0.0.0/8\n   |          | 192.168.0.0/24 | 192.168.0.0/24 | 192.168.0.0/24\n
    "},{"location":"ref/routes/#use-the-subnet-router","title":"Use the subnet router","text":"

    To accept routes advertised by a subnet router on a node:

    $ sudo tailscale set --accept-routes\n

    Please refer to the official Tailscale documentation for how to use a subnet router on different operating systems.

    "},{"location":"ref/routes/#restrict-the-use-of-a-subnet-router-with-a-policy","title":"Restrict the use of a subnet router with a policy","text":"

    The routes announced by subnet routers are available to the nodes in a tailnet. By default, without a policy enabled, all nodes can accept and use such routes. Configure a policy to explicitly manage who can use routes.

    The policy snippet below defines three hosts, a subnet router router, a regular node node and service.example.net as internal service that can be reached via a route on the subnet router router. It allows the node node to access service.example.net on port 80 and 443 which is reachable via the subnet router. Access to the subnet router itself is denied.

    Access the routes of a subnet router without the subnet router itself
    {\n  \"hosts\": {\n    // the router is not referenced but announces 192.168.0.0/24\n    \"router\": \"100.64.0.1/32\",\n    \"node\": \"100.64.0.2/32\",\n    \"service.example.net\": \"192.168.0.1/32\"\n  },\n  \"grants\": [\n    {\n      \"src\": [\"node\"],\n      \"dst\": [\"service.example.net\"],\n      \"ip\": [\"80,443\"]\n    }\n  ]\n}\n
    "},{"location":"ref/routes/#automatically-approve-routes-of-a-subnet-router","title":"Automatically approve routes of a subnet router","text":"

    The initial setup of a subnet router usually requires manual approval of their announced routes on the control server before they can be used by a node in a tailnet. Headscale supports the autoApprovers section in a policy to automate the approval of routes served with a subnet router.

    The policy snippet below defines the tag tag:router owned by the user alice. This tag is used for routes in the autoApprovers section. The IPv4 route 192.168.0.0/24 is automatically approved once announced by a subnet router that advertises the tag tag:router.

    Subnet routers tagged with tag:router are automatically approved
    {\n  \"tagOwners\": {\n    \"tag:router\": [\"alice@\"]\n  },\n  \"autoApprovers\": {\n    \"routes\": {\n      \"192.168.0.0/24\": [\"tag:router\"]\n    }\n  },\n  \"grants\": [\n    // more rules\n  ]\n}\n

    Advertise the route 192.168.0.0/24 from a subnet router that also advertises the tag tag:router when joining the tailnet:

    $ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags tag:router --advertise-routes 192.168.0.0/24\n

    Please see the official Tailscale documentation for more information on auto approvers.

    "},{"location":"ref/routes/#exit-node","title":"Exit node","text":"

    The setup of an exit node requires double opt-in, once from an exit node and once on the control server to allow its use within the tailnet. Optionally, use autoApprovers to automatically approve an exit node.

    "},{"location":"ref/routes/#setup-an-exit-node","title":"Setup an exit node","text":""},{"location":"ref/routes/#configure-a-node-as-exit-node","title":"Configure a node as exit node","text":"

    Register a node and make it advertise itself as an exit node:

    $ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-exit-node\n

    If the node is already registered, it can advertise exit capabilities like this:

    $ sudo tailscale set --advertise-exit-node\n

    Finally, enable IP forwarding to route traffic.

    "},{"location":"ref/routes/#enable-the-exit-node-on-the-control-server","title":"Enable the exit node on the control server","text":"

    The routes of a tailnet can be displayed with the headscale nodes list-routes command. An exit node can be recognized by its announced routes: 0.0.0.0/0 for IPv4 and ::/0 for IPv6. The exit node with the hostname myexit is already available, but needs to be approved:

    $ headscale nodes list-routes\nID | Hostname | Approved | Available | Serving (Primary)\n1  | myexit   |          | 0.0.0.0/0 |\n   |          |          | ::/0      |\n

    For exit nodes, it is sufficient to approve either the IPv4 or IPv6 route. The other will be approved automatically.

    $ headscale nodes approve-routes --identifier 1 --routes 0.0.0.0/0\nNode updated\n

    The node myexit is now approved as exit node for the tailnet:

    $ headscale nodes list-routes\nID | Hostname | Approved  | Available | Serving (Primary)\n1  | myexit   | 0.0.0.0/0 | 0.0.0.0/0 | 0.0.0.0/0\n   |          | ::/0      | ::/0      | ::/0\n
    "},{"location":"ref/routes/#use-the-exit-node","title":"Use the exit node","text":"

    The exit node can now be used on a node with:

    $ sudo tailscale set --exit-node myexit\n

    Please refer to the official Tailscale documentation for how to use an exit node on different operating systems.

    "},{"location":"ref/routes/#restrict-the-use-of-an-exit-node-with-a-policy","title":"Restrict the use of an exit node with a policy","text":"

    An exit node is offered to all nodes in a tailnet. By default, without a policy enabled, all nodes in a tailnet can select and use an exit node. Configure autogroup:internet in a policy rule to restrict who can use any of the available exit nodes.

    Example use of autogroup:internet
    {\n  \"grants\": [\n    {\n      \"src\": [\"...\"],\n      \"dst\": [\"autogroup:internet\"],\n      \"ip\": [\"*\"]\n    }\n  ]\n}\n
    "},{"location":"ref/routes/#restrict-access-to-exit-nodes-per-user-or-group","title":"Restrict access to exit nodes per user or group","text":"

    A user can use any of the available exit nodes with autogroup:internet. Alternatively, the policy snippet below assigns each user a specific exit node while hiding all other exit nodes. The user alice can only use an exit node tagged with tag:exit1 while user bob can only use an exit node tagged with tag:exit2.

    Assign each user a dedicated exit node
    {\n  \"tagOwners\": {\n    \"tag:exit1\": [\"alice@\"],\n    \"tag:exit2\": [\"bob@\"]\n  },\n  \"grants\": [\n    {\n      \"src\": [\"alice@\"],\n      \"dst\": [\"autogroup:internet\"],\n      \"via\": [\"tag:exit1\"],\n      \"ip\": [\"*\"]\n    },\n    {\n      \"src\": [\"bob@\"],\n      \"dst\": [\"autogroup:internet\"],\n      \"via\": [\"tag:exit2\"],\n      \"ip\": [\"*\"]\n    }\n  ]\n}\n
    "},{"location":"ref/routes/#automatically-approve-an-exit-node-with-auto-approvers","title":"Automatically approve an exit node with auto approvers","text":"

    The initial setup of an exit node usually requires manual approval on the control server before it can be used by a node in a tailnet. Headscale supports the autoApprovers section in a policy to automate the approval of a new exit node as soon as it joins the tailnet.

    The policy snippet below defines the tag tag:exit owned by the user alice. This tag is used for the exitNode entry in the autoApprovers section. A new exit node that advertises the tag tag:exit is automatically approved:

    Exit nodes tagged with tag:exit are automatically approved
    {\n  \"tagOwners\": {\n    \"tag:exit\": [\"alice@\"]\n  },\n  \"autoApprovers\": {\n    \"exitNode\": [\"tag:exit\"]\n  },\n  \"grants\": [\n    // more rules\n  ]\n}\n

    Advertise a node as exit node and also advertise the tag tag:exit when joining the tailnet:

    $ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags tag:exit --advertise-exit-node\n

    Please see the official Tailscale documentation for more information on auto approvers.

    "},{"location":"ref/routes/#automatic-exit-node-selection","title":"Automatic exit node selection","text":"

    A Tailscale client can be configured to select one of the available exit nodes automatically. This may be useful when there are multiple exit nodes available and clients should use an exit node without requiring a user to manually switch between them.

    The policy snippet below defines the tag tag:exit for exit nodes. Exit nodes with that tag are suggested to clients with the suggest-exit-node node attribute. Additionally, GUI clients should display the \"Recommended\" exit node selector.

    Automatic exit node selection
    {\n  \"tagOwners\": {\n    \"tag:exit\": [\"infra@\"]\n  },\n  \"nodeAttrs\": [\n    {\n      // Suggest exit nodes tagged with tag:exit\n      \"target\": [\"tag:exit\"],\n      \"attr\": [\"suggest-exit-node\"]\n    },\n    {\n      // Show \"recommended\" exit node selector in GUIs\n      \"target\": [\"*\"],\n      \"attr\": [\"suggest-exit-node-ui\"]\n    }\n  ],\n  \"grants\": [\n    {\n      \"src\": [\"...\"],\n      \"dst\": [\"autogroup:internet\"],\n      \"ip\": [\"*\"]\n    }\n  ]\n}\n

    The Tailscale client can suggest a viable exit node with:

    $ sudo tailscale exit-node suggest\n

    or automatically select one by using auto:any as exit node identifier:

    $ sudo tailscale set --exit-node=auto:any\n

    Please see the official Tailscale documentation for more information on automatic exit node selection.

    "},{"location":"ref/routes/#high-availability","title":"High availability","text":"

    Headscale supports high availability routing. Multiple subnet routers with overlapping routes or multiple exit nodes can be used to provide high availability for users. If one router node goes offline, another one can serve the same routes to clients. Please see the official Tailscale documentation on high availability for details.

    This feature is enabled by default when at least two nodes advertise the same prefix. See the configuration options node.routes.ha in the configuration file for details.

    "},{"location":"ref/routes/#troubleshooting","title":"Troubleshooting","text":""},{"location":"ref/routes/#enable-ip-forwarding","title":"Enable IP forwarding","text":"

    A subnet router or exit node is routing traffic on behalf of other nodes and thus requires IP forwarding. Check the official Tailscale documentation for how to enable IP forwarding.

    "},{"location":"ref/tags/","title":"Tags","text":"

    Headscale supports Tailscale tags. Please read Tailscale's tag documentation to learn how tags work and how to use them.

    Tags can be applied during node registration:

    Administrators can manage tags with:

    "},{"location":"ref/tags/#common-operations","title":"Common operations","text":""},{"location":"ref/tags/#manage-tags-for-a-node","title":"Manage tags for a node","text":"

    Run headscale nodes list to list the tags for a node.

    Use the headscale nodes tag command to modify the tags for a node. At least one tag is required and multiple tags can be provided as comma separated list. The following command sets the tags tag:server and tag:prod on node with ID 1:

    headscale nodes tag -i 1 -t tag:server,tag:prod\n
    "},{"location":"ref/tags/#convert-from-personal-to-tagged-node","title":"Convert from personal to tagged node","text":"

    Use the headscale nodes tag command to convert a personal (user-owned) node to a tagged node:

    headscale nodes tag -i <NODE_ID> -t <TAG>\n

    The node is now owned by the special user tagged-devices and has the specified tags assigned to it.

    "},{"location":"ref/tags/#convert-from-tagged-to-personal-node","title":"Convert from tagged to personal node","text":"

    Tagged nodes can return to personal (user-owned) nodes by re-authenticating with:

    tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags= --force-reauth\n

    Usually, a browser window with further instructions is opened. This page explains how to complete the registration on your Headscale server and it also prints the Auth ID required to approve the node:

    headscale auth register --user <USER> --auth-id <AUTH_ID>\n

    All previously assigned tags get removed and the node is now owned by the user specified in the above command.

    "},{"location":"ref/tls/","title":"Running the service via TLS (optional)","text":""},{"location":"ref/tls/#bring-your-own-certificate","title":"Bring your own certificate","text":"

    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_key_path configuration parameters. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.

    config.yaml
    tls_cert_path: \"\"\ntls_key_path: \"\"\n

    The certificate should contain the full chain, else some clients, like the Tailscale Android client, will reject it.

    "},{"location":"ref/tls/#lets-encrypt-acme","title":"Let's Encrypt / ACME","text":"

    To get a certificate automatically via Let's Encrypt, 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.

    config.yaml
    tls_letsencrypt_hostname: \"\"\ntls_letsencrypt_listen: \":http\"\ntls_letsencrypt_cache_dir: \".cache\"\ntls_letsencrypt_challenge_type: HTTP-01\n
    "},{"location":"ref/tls/#challenge-types","title":"Challenge types","text":"

    Headscale only supports two values for tls_letsencrypt_challenge_type: HTTP-01 (default) and TLS-ALPN-01.

    "},{"location":"ref/tls/#http-01","title":"HTTP-01","text":"

    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.

    listen_addr cannot also be port 80

    listen_addr and tls_letsencrypt_listen must not bind the same TCP socket. A common mistake is setting listen_addr: 0.0.0.0:80 together with tls_letsencrypt_hostname \u2014 both endpoints try to claim port 80, and the second bind fails with address already in use even though no other process is involved. Headscale validates this at startup and refuses to launch with a Fatal config error: listen_addr and tls_letsencrypt_listen would bind the same TCP socket message. Use listen_addr: 0.0.0.0:443 (or any non-80 port) when HTTP-01 is enabled.

    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.

    "},{"location":"ref/tls/#tls-alpn-01","title":"TLS-ALPN-01","text":"

    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.

    "},{"location":"ref/tls/#technical-description","title":"Technical description","text":"

    Headscale uses autocert, a Golang library providing ACME protocol verification, to facilitate certificate renewals via Let's Encrypt. Certificates will be renewed automatically, and the following can be expected:

    "},{"location":"ref/tls/#checking-certificate-expiry","title":"Checking certificate expiry","text":"

    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:
    $ openssl s_client -servername [hostname] -connect [hostname]:443 | openssl x509 -noout -dates\n(...)\nnotBefore=Feb  8 09:48:26 2024 GMT\nnotAfter=May  8 09:48:25 2024 GMT\n
    "},{"location":"ref/tls/#log-output-from-the-autocert-library","title":"Log output from the autocert library","text":"

    As these log lines are from the autocert library, they are not strictly generated by headscale itself.

    acme/autocert: missing server name\n

    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.

    acme/autocert: host \"[foo]\" not configured in HostWhitelist\n

    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

    "},{"location":"ref/integration/reverse-proxy/","title":"Running Headscale behind a reverse proxy","text":"

    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.

    Please see limitations for known issues and limitations.

    "},{"location":"ref/integration/reverse-proxy/#configuration","title":"Configuration","text":"

    The configuration depends on the set of Headscale features you intend to use. Please have a look at the requirements and especially the ports in use section to learn what a Tailscale clients expects.

    The configuration examples in this documentation are basic and cover only HTTP and HTTPS traffic. Other features such as STUN for Headscale's embedded DERP server are expected to be exposed directly or to be only available on localhost.

    "},{"location":"ref/integration/reverse-proxy/#websocket","title":"WebSocket","text":"

    Tailscale clients are using a custom protocol (Tailscale Control Protocol) to communicate with a control server such as Headscale. The reverse proxy must be configured to support WebSockets in order to communicate with Tailscale clients and it needs to handle two peculiarities of the Tailscale Control Protocol:

    "},{"location":"ref/integration/reverse-proxy/#tls","title":"TLS","text":"

    Headscale can be configured not to use TLS, leaving it to the reverse proxy to handle. Add the following configuration values to your Headscale configuration file:

    config.yaml
    server_url: https://<SERVER_NAME>\ntls_cert_path: \"\"\ntls_key_path: \"\"\n

    Headscale logs WRN listening without TLS but ServerURL does not start with http:// during startup. This is expected and indicates that the reverse proxy is in charge of terminating TLS.

    "},{"location":"ref/integration/reverse-proxy/#trusted-proxies","title":"Trusted proxies","text":"

    Headscale ignores True-Client-IP, X-Real-IP and X-Forwarded-For headers unless the request's TCP peer matches the trusted_proxies configuration option. Set this to the CIDR(s) your reverse proxy connects from so the real client IP appears in access logs.

    config.yaml
    trusted_proxies:\n  - 127.0.0.1/32\n  - ::1/128\n

    The reverse proxy is responsible to replace any client-supplied True-Client-IP, X-Real-IP, X-Forwarded-For headers on inbound requests with sanitized values. Headscale picks the first valid IP address supplied by headers in this order:

    "},{"location":"ref/integration/reverse-proxy/#limitations","title":"Limitations","text":""},{"location":"ref/integration/reverse-proxy/#reverse-proxy-specific-configuration","title":"Reverse proxy specific configuration","text":"

    Third-party software and services

    This section of the documentation is specific for third-party software and services. We recommend users read the third-party documentation for a secure configuration.

    This following Headscale configuration may be used as base for the various reverse proxy examples below. The following is assumed:

    config.yaml
    server_url: https://<SERVER_NAME>\nlisten_addr: 127.0.0.1:8080\nmetrics_listen_addr: 127.0.0.1:9090\ntrusted_proxies:\n  - 127.0.0.1/32\n  - ::1/128\ntls_cert_path: \"\"\ntls_key_path: \"\"\n
    "},{"location":"ref/integration/reverse-proxy/#apache","title":"Apache","text":"

    The following basic Apache configuration works with the Headscale configuration as shown above. Substitute placeholders and adjust the configuration as needed:

    apache.conf
    <VirtualHost *:80>\n  ServerName <SERVER_NAME>\n\n  # Tailscale captive portal detection\n  RedirectMatch 204 ^/generate_204$\n\n  RedirectMatch permanent \"^/(.*)$\" \"https://<SERVER_NAME>/$1\"\n</VirtualHost>\n\n<VirtualHost *:443>\n  ServerName <SERVER_NAME>\n\n  SSLEngine On\n  SSLCertificateFile <PATH_TO_TLS_CERT>\n  SSLCertificateKeyFile <PATH_TO_TLS_KEY>\n\n  RequestHeader set True-Client-IP \"%{REMOTE_ADDR}s\"\n  RequestHeader set X-Real-IP \"%{REMOTE_ADDR}s\"\n\n  ProxyPreserveHost On\n  ProxyPass / http://127.0.0.1:8080/ upgrade=any\n</VirtualHost>\n

    Note that upgrade=any is required as a parameter for ProxyPass so that WebSocket traffic whose Upgrade header value is not equal to WebSocket (i. e. Tailscale Control Protocol) is forwarded correctly. See the Apache docs for more information on this.

    "},{"location":"ref/integration/reverse-proxy/#caddy","title":"Caddy","text":"

    The following basic Caddyfile works with the Headscale configuration as shown above. Substitute placeholders and adjust the configuration as needed:

    Caddyfile
    http://<SERVER_NAME> {\n    # Tailscale captive portal detection\n    handle /generate_204 {\n        respond 204\n    }\n\n    handle * {\n        redir https://{host}{uri}\n    }\n}\n\n<SERVER_NAME> {\n    reverse_proxy 127.0.0.1:8080 {\n        header_up True-Client-IP {remote_host}\n        header_up X-Real-IP {remote_host}\n    }\n}\n

    Caddy will automatically provision a certificate for your domain/subdomain, force HTTPS, and proxy WebSocket connections.

    "},{"location":"ref/integration/reverse-proxy/#cloudflare","title":"Cloudflare","text":"

    Running Headscale behind a Cloudflare Proxy or Cloudflare Tunnel is not supported and will not work as Cloudflare does not support WebSocket POSTs as required by the Tailscale protocol. See issue 1468 for more information.

    "},{"location":"ref/integration/reverse-proxy/#envoy","title":"Envoy","text":"

    You need to add a new upgrade_type named tailscale-control-protocol. See details.

    "},{"location":"ref/integration/reverse-proxy/#istio","title":"Istio","text":"

    Same as envoy, we can use EnvoyFilter to add a new upgrade_type named tailscale-control-protocol.

    apiVersion: networking.istio.io/v1alpha3\nkind: EnvoyFilter\nmetadata:\n  name: headscale-behind-istio-ingress\n  namespace: istio-system\nspec:\n  configPatches:\n    - applyTo: NETWORK_FILTER\n      match:\n        listener:\n          filterChain:\n            filter:\n              name: envoy.filters.network.http_connection_manager\n      patch:\n        operation: MERGE\n        value:\n          typed_config:\n            \"@type\": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager\n            upgrade_configs:\n              - upgrade_type: tailscale-control-protocol\n
    "},{"location":"ref/integration/reverse-proxy/#nginx","title":"Nginx","text":"

    The following basic Nginx configuration works with the Headscale configuration as shown above. Substitute placeholders and adjust the configuration as needed:

    nginx.conf
    # headscale\nupstream headscale {\n  zone upstreams 64K;\n  server 127.0.0.1:8080 max_fails=1 fail_timeout=5s;\n  keepalive 2;\n}\n\n# websocket\nmap $http_upgrade $connection_upgrade {\n  default keep-alive;\n  ''      close;\n}\n\n# http\nserver {\n  listen 80;\n  listen [::]:80;\n\n  server_name <SERVER_NAME>;\n\n  # Tailscale captive portal detection\n  location = /generate_204 {\n    return 204;\n  }\n\n  location / {\n    return 301 https://$server_name$request_uri;\n  }\n}\n\n# https\nserver {\n  listen 443 ssl;\n  listen [::]:443 ssl;\n  http2 on;\n\n  server_name <SERVER_NAME>;\n\n  ssl_certificate <PATH_TO_TLS_CERT>;\n  ssl_certificate_key <PATH_TO_TLS_KEY>;\n\n  location / {\n    proxy_http_version 1.1;\n    proxy_set_header Upgrade $http_upgrade;\n    proxy_set_header Connection $connection_upgrade;\n    proxy_set_header Host $host;\n    proxy_set_header True-Client-IP $remote_addr;\n    proxy_set_header X-Real-IP $remote_addr;\n    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n    proxy_set_header X-Forwarded-Proto $scheme;\n    proxy_buffering off;\n    proxy_pass http://headscale;\n  }\n}\n
    "},{"location":"ref/integration/tools/","title":"Tools related to headscale","text":"

    Community contributions

    This page contains community contributions. The projects listed here are not maintained by the headscale authors and are written by community members.

    This page collects third-party tools, client libraries, and scripts related to headscale.

    "},{"location":"ref/integration/web-ui/","title":"Web interfaces for headscale","text":"

    Community contributions

    This page contains community contributions. The projects listed here are not maintained by the headscale authors and are written by community members.

    Headscale doesn't provide a built-in web interface but users may pick one from the available options.

    You can ask for support on our Discord server in the \"web-interfaces\" channel.

    "},{"location":"setup/requirements/","title":"Requirements","text":"

    Headscale should just work as long as the following requirements are met:

    "},{"location":"setup/requirements/#ports-in-use","title":"Ports in use","text":"

    The ports in use vary with the intended scenario and enabled features. Some of the listed ports may be changed via the configuration file but we recommend to stick with the default values.

    "},{"location":"setup/requirements/#assumptions","title":"Assumptions","text":"

    The headscale documentation and the provided examples are written with a few assumptions in mind:

    Please adjust to your local environment accordingly.

    1. The Tailscale client assumes HTTPS on port 443 in certain situations. Serving headscale either via HTTP or via HTTPS on a port other than 443 is possible but sticking with HTTPS on port 443 is strongly recommended for production setups. See issue 2164 for more information.\u00a0\u21a9\u21a9

    "},{"location":"setup/upgrade/","title":"Upgrade an existing installation","text":"

    Required update path

    It's required to update from one stable version to the next (e.g. 0.26.0 \u2192 0.27.1 \u2192 0.28.0) without skipping minor versions in between. You should always pick the latest available patch release.

    Update an existing Headscale installation to a new version:

    "},{"location":"setup/upgrade/#backup","title":"Backup","text":"

    Headscale applies database migrations during upgrades and we highly recommend to create a backup of your database before upgrading. A full backup of Headscale depends on your individual setup, but below are some typical setup scenarios.

    Standard installationContainerPostgreSQL

    An installation that follows our official releases setup guide uses the following paths:

    TIMESTAMP=$(date +%Y%m%d%H%M%S)\ncp -aR /etc/headscale /etc/headscale.backup-$TIMESTAMP\ncp -aR /var/lib/headscale /var/lib/headscale.backup-$TIMESTAMP\n

    An installation that follows our container setup guide uses a single source volume directory that contains the configuration file, data directory and the SQLite database.

    cp -aR /path/to/headscale /path/to/headscale.backup-$(date +%Y%m%d%H%M%S)\n

    Please follow PostgreSQL's Backup and Restore documentation to create a backup of your PostgreSQL database.

    "},{"location":"setup/install/community/","title":"Community packages","text":"

    Several Linux distributions and community members provide packages for headscale. Those packages may be used instead of the official releases provided by the headscale maintainers. Such packages offer improved integration for their targeted operating system and usually:

    Community packages might be outdated

    The packages mentioned on this page might be outdated or unmaintained. Use the official releases to get the current stable version or to test pre-releases.

    "},{"location":"setup/install/community/#arch-linux","title":"Arch Linux","text":"

    Arch Linux offers a package for headscale, install via:

    pacman -S headscale\n
    "},{"location":"setup/install/community/#fedora-rhel-centos","title":"Fedora, RHEL, CentOS","text":"

    A third-party repository for various RPM based distributions is available at: https://copr.fedorainfracloud.org/coprs/jonathanspw/headscale/. The site provides detailed setup and installation instructions.

    "},{"location":"setup/install/community/#nix-nixos","title":"Nix, NixOS","text":"

    A Nix package is available as: headscale. See the NixOS package site for installation details.

    "},{"location":"setup/install/community/#gentoo","title":"Gentoo","text":"
    emerge --ask net-vpn/headscale\n

    Gentoo specific documentation is available here.

    "},{"location":"setup/install/community/#openbsd","title":"OpenBSD","text":"

    Headscale is available in ports. The port installs headscale as system service with rc.d and provides usage instructions upon installation.

    pkg_add headscale\n
    "},{"location":"setup/install/container/","title":"Running headscale in a container","text":"

    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.

    A container runtime such as Docker or Podman is required. The container image can be found on Docker Hub and GitHub Container Registry. The container image URLs are:

    "},{"location":"setup/install/container/#configure-and-run-headscale","title":"Configure and run headscale","text":"

    1. Create a directory on the container host to store headscale's configuration and the SQLite database:

      mkdir -p ./headscale/{config,lib}\ncd ./headscale\n

    2. Download the example configuration for your chosen version and save it as: $(pwd)/config/config.yaml. Adjust the configuration to suit your local environment. See Configuration for details.

    3. Start headscale from within the previously created ./headscale directory:

      docker run \\\n  --name headscale \\\n  --detach \\\n  --read-only \\\n  --tmpfs /tmp \\\n  --tmpfs /var/run/headscale \\\n  --volume \"$(pwd)/config:/etc/headscale:ro\" \\\n  --volume \"$(pwd)/lib:/var/lib/headscale\" \\\n  --publish 127.0.0.1:8080:8080 \\\n  --publish 127.0.0.1:9090:9090 \\\n  --health-cmd \"CMD headscale health\" \\\n  docker.io/headscale/headscale:<VERSION> \\\n  serve\n

      Note: use 0.0.0.0:8080:8080 instead of 127.0.0.1:8080:8080 if you want to expose the container externally.

      This command mounts the local directories inside the container, forwards port 8080 and 9090 out of the container so the headscale instance becomes available and then detaches so headscale runs in the background.

      A similar configuration for docker-compose:

      docker-compose.yaml
      services:\n  headscale:\n    image: docker.io/headscale/headscale:<VERSION>\n    restart: unless-stopped\n    container_name: headscale\n    read_only: true\n    tmpfs:\n      - /var/run/headscale\n    ports:\n      - \"127.0.0.1:8080:8080\"\n      - \"127.0.0.1:9090:9090\"\n    volumes:\n      # Please set <HEADSCALE_PATH> to the absolute path\n      # of the previously created headscale directory.\n      - <HEADSCALE_PATH>/config:/etc/headscale:ro\n      - <HEADSCALE_PATH>/lib:/var/lib/headscale\n    command: serve\n    healthcheck:\n        test: [\"CMD\", \"headscale\", \"health\"]\n

    4. Verify headscale is running:

      Follow the container logs:

      docker logs --follow headscale\n

      Verify running containers:

      docker ps\n

      Verify headscale is available:

      curl http://127.0.0.1:8080/health\n

    Continue on the getting started page to register your first machine.

    "},{"location":"setup/install/container/#debugging-headscale-running-in-docker","title":"Debugging headscale running in Docker","text":"

    The Headscale container image is based on a distroless image that does not contain a shell or any other debug tools. If you need to debug headscale running in the Docker container, you can use the -debug variant, for example docker.io/headscale/headscale:x.x.x-debug.

    "},{"location":"setup/install/container/#running-the-debug-docker-container","title":"Running the debug Docker container","text":"

    To run the debug Docker container, use the exact same commands as above, but replace docker.io/headscale/headscale:x.x.x with docker.io/headscale/headscale:x.x.x-debug (x.x.x is the version of headscale). The two containers are compatible with each other, so you can alternate between them.

    "},{"location":"setup/install/container/#executing-commands-in-the-debug-container","title":"Executing commands in the debug container","text":"

    The default command in the debug container is to run headscale, which is located at /ko-app/headscale inside the container.

    Additionally, the debug container includes a minimalist Busybox shell.

    To launch a shell in the container, use:

    docker run -it docker.io/headscale/headscale:x.x.x-debug sh\n

    You can also execute commands directly, such as ls /ko-app in this example:

    docker run docker.io/headscale/headscale:x.x.x-debug ls /ko-app\n

    Using docker exec -it allows you to run commands in an existing container.

    "},{"location":"setup/install/main/","title":"Development builds","text":"

    Warning

    Development builds are created automatically from the latest main branch and are not versioned releases. They may contain incomplete features, breaking changes, or bugs. Use them for testing only.

    Each push to main produces container images and cross-compiled binaries. Container images are multi-arch (amd64, arm64) and use the same distroless base image as official releases.

    "},{"location":"setup/install/main/#container-images","title":"Container images","text":"

    Images are available from both Docker Hub and GitHub Container Registry, tagged with the short commit hash of the build (e.g. main-abc1234):

    To find the latest available tag, check the GitHub Actions workflow or the GitHub Container Registry package page.

    For example, to run a specific development build:

    docker run \\\n  --name headscale \\\n  --detach \\\n  --read-only \\\n  --tmpfs /tmp \\\n  --tmpfs /var/run/headscale \\\n  --volume \"$(pwd)/config:/etc/headscale:ro\" \\\n  --volume \"$(pwd)/lib:/var/lib/headscale\" \\\n  --publish 127.0.0.1:8080:8080 \\\n  --publish 127.0.0.1:9090:9090 \\\n  --health-cmd \"CMD headscale health\" \\\n  docker.io/headscale/headscale:main-<sha> \\\n  serve\n

    See Running headscale in a container for full container setup instructions.

    "},{"location":"setup/install/main/#binaries","title":"Binaries","text":"

    Pre-built binaries from the latest successful build on main are available via nightly.link:

    OS Arch Download Linux amd64 headscale-linux-amd64 Linux arm64 headscale-linux-arm64 macOS amd64 headscale-darwin-amd64 macOS arm64 headscale-darwin-arm64

    After downloading and extracting the archive, make the binary executable and follow the standalone binary installation instructions for setting up the service.

    "},{"location":"setup/install/official/","title":"Official releases","text":"

    Official releases for headscale are available as binaries for various platforms and DEB packages for Debian and Ubuntu. Both are available on the GitHub releases page.

    "},{"location":"setup/install/official/#using-packages-for-debianubuntu-recommended","title":"Using packages for Debian/Ubuntu (recommended)","text":"

    It is recommended to use our DEB packages to install headscale on a Debian based system as those packages configure a local user to run headscale, provide a default configuration and ship with a systemd service file. Supported distributions are Ubuntu 22.04 or newer, Debian 12 or newer.

    1. Download the latest headscale package for your platform (.deb for Ubuntu and Debian).

      HEADSCALE_VERSION=\"\" # See above URL for latest version, e.g. \"X.Y.Z\" (NOTE: do not add the \"v\" prefix!)\nHEADSCALE_ARCH=\"\" # Your system architecture, e.g. \"amd64\"\nwget --output-document=headscale.deb \\\n \"https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb\"\n

    2. Install headscale:

      sudo apt install ./headscale.deb\n

    3. Configure headscale by editing the configuration file. An up-to date example configuration file is also available in /usr/share/doc/headscale/examples/config-example.yaml:

      sudo nano /etc/headscale/config.yaml\n

    4. Restart headscale to pick up configuration changes:

      sudo systemctl restart headscale\n

    5. Verify that headscale is running as intended:

      sudo systemctl status headscale\n

    Continue on the getting started page to register your first machine.

    "},{"location":"setup/install/official/#using-standalone-binaries-advanced","title":"Using standalone binaries (advanced)","text":"

    Advanced

    This installation method is considered advanced as one needs to take care of the local user and the systemd service themselves. If possible, use the DEB packages or a community package instead.

    This section describes the installation of headscale according to the Requirements and assumptions. Headscale is run by a dedicated local user and the service itself is managed by systemd.

    1. Download the latest headscale binary from GitHub's release page:

      sudo wget --output-document=/usr/bin/headscale \\\nhttps://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>\n

    2. Make headscale executable:

      sudo chmod +x /usr/bin/headscale\n

    3. Add a dedicated local user to run headscale:

      sudo useradd \\\n --create-home \\\n --home-dir /var/lib/headscale/ \\\n --system \\\n --user-group \\\n --shell /usr/sbin/nologin \\\n headscale\n

    4. Download the example configuration for your chosen version and save it as: /etc/headscale/config.yaml. Adjust the configuration to suit your local environment. See Configuration for details.

      sudo mkdir -p /etc/headscale\nsudo nano /etc/headscale/config.yaml\n

    5. Copy headscale's systemd service file to /etc/systemd/system/headscale.service and adjust it to suit your local setup. The following parameters likely need to be modified: ExecStart, WorkingDirectory, ReadWritePaths.

    6. In /etc/headscale/config.yaml, override the default headscale unix socket with a path that is writable by the headscale user or group:

      config.yaml
      unix_socket: /var/run/headscale/headscale.sock\n

    7. Reload systemd to load the new configuration file:

      systemctl daemon-reload\n

    8. Enable and start the new headscale service:

      systemctl enable --now headscale\n

    9. Verify that headscale is running as intended:

      systemctl status headscale\n

    Continue on the getting started page to register your first machine.

    "},{"location":"setup/install/source/","title":"Build from source","text":"

    Community documentation

    This page is not actively maintained by the headscale authors and is written by community members. It is not verified by headscale developers.

    It might be outdated and it might miss necessary steps.

    Headscale can be built from source using the latest version of Go and Buf (Protobuf generator). See the Contributing section in the GitHub README for more information.

    "},{"location":"setup/install/source/#openbsd","title":"OpenBSD","text":""},{"location":"setup/install/source/#install-from-source","title":"Install from source","text":"
    # Install prerequisites\npkg_add go git\n\ngit clone https://github.com/juanfont/headscale.git\n\ncd headscale\n\n# optionally checkout a release\n# option a. you can find official release at https://github.com/juanfont/headscale/releases/latest\n# option b. get latest tag, this may be a beta release\nlatestTag=$(git describe --tags `git rev-list --tags --max-count=1`)\n\ngit checkout $latestTag\n\ngo build -ldflags=\"-s -w -X github.com/juanfont/headscale/hscontrol/types.Version=$latestTag\" -X github.com/juanfont/headscale/hscontrol/types.GitCommitHash=HASH\" github.com/juanfont/headscale\n\n# make it executable\nchmod a+x headscale\n\n# copy it to /usr/local/sbin\ncp headscale /usr/local/sbin\n
    "},{"location":"setup/install/source/#install-from-source-via-cross-compile","title":"Install from source via cross compile","text":"
    # Install prerequisites\n# 1. go v1.27+: see the go directive in go.mod for the exact minimum\n# 2. gmake: Makefile in the headscale repo is written in GNU make syntax\n\ngit clone https://github.com/juanfont/headscale.git\n\ncd headscale\n\n# optionally checkout a release\n# option a. you can find official release at https://github.com/juanfont/headscale/releases/latest\n# option b. get latest tag, this may be a beta release\nlatestTag=$(git describe --tags `git rev-list --tags --max-count=1`)\n\ngit checkout $latestTag\n\nmake build GOOS=openbsd\n\n# copy headscale to openbsd machine and put it in /usr/local/sbin\n
    "},{"location":"usage/getting-started/","title":"Getting started","text":"

    This page helps you get started with headscale and provides a few usage examples for the headscale command line tool headscale.

    Prerequisites

    "},{"location":"usage/getting-started/#getting-help","title":"Getting help","text":"

    The headscale command line tool provides built-in help. To show available commands along with their arguments and options, run:

    NativeContainer 
    # Show help\nheadscale help\n\n# Show help for a specific command\nheadscale <COMMAND> --help\n
    # Show help\ndocker exec -it headscale \\\n  headscale help\n\n# Show help for a specific command\ndocker exec -it headscale \\\n  headscale <COMMAND> --help\n

    Manage headscale from another local user

    By default only the user headscale or root will have the necessary permissions to access the unix socket (/var/run/headscale/headscale.sock) that is used to communicate with the service. In order to be able to communicate with the headscale service you have to make sure the unix socket is accessible by the user that runs the commands. In general you can achieve this by any of the following methods:

    To verify you can run the following command using your preferred method:

    headscale users list\n
    "},{"location":"usage/getting-started/#manage-headscale-users","title":"Manage headscale users","text":"

    In headscale, a node (also known as machine or device) is typically assigned to a headscale user. Such a headscale user1 may have many nodes assigned to them and can be managed with the headscale users command. Invoke the built-in help for more information: headscale users --help.

    "},{"location":"usage/getting-started/#create-a-headscale-user","title":"Create a headscale user","text":"NativeContainer 
    headscale users create <USER>\n
    docker exec -it headscale \\\n  headscale users create <USER>\n
    "},{"location":"usage/getting-started/#list-existing-headscale-users","title":"List existing headscale users","text":"NativeContainer 
    headscale users list\n
    docker exec -it headscale \\\n  headscale users list\n
    "},{"location":"usage/getting-started/#register-a-node","title":"Register a node","text":"

    One has to register a node first to use headscale as coordination server with Tailscale. The following examples work for the Tailscale client on Linux/BSD operating systems. Alternatively, follow the instructions to connect Android, Apple or Windows devices. Read registration methods for an overview of available registration methods.

    "},{"location":"usage/getting-started/#web-authentication","title":"Web authentication","text":"

    On a client machine, run the tailscale up command and provide the FQDN of your headscale instance as argument:

    tailscale up --login-server <YOUR_HEADSCALE_URL>\n

    Usually, a browser window with further instructions is opened. This page explains how to complete the registration on your headscale server and it also prints the Auth ID required to approve the node:

    NativeContainer 
    headscale auth register --user <USER> --auth-id <AUTH_ID>\n
    docker exec -it headscale \\\n  headscale auth register --user <USER> --auth-id <AUTH_ID>\n
    "},{"location":"usage/getting-started/#pre-authenticated-key","title":"Pre authenticated key","text":"

    It is also possible to generate a preauthkey and register a node non-interactively. First, generate a preauthkey on the headscale instance. By default, the key is valid for one hour and can only be used once (see headscale preauthkeys --help for other options):

    NativeContainer 
    headscale preauthkeys create --user <USER>\n
    docker exec -it headscale \\\n  headscale preauthkeys create --user <USER>\n

    The command returns the preauthkey on success which is used to connect a node to the headscale instance via the tailscale up command:

    tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>\n

    1. Ensure that the Headscale username does not end with @. \u21a9

    "},{"location":"usage/connect/android/","title":"Connecting an Android client","text":"

    This documentation has the goal of showing how a user can use the official Android Tailscale client with headscale.

    "},{"location":"usage/connect/android/#installation","title":"Installation","text":"

    Install the official Tailscale Android client from the Google Play Store or F-Droid.

    "},{"location":"usage/connect/android/#connect-via-web-authentication","title":"Connect via web authentication","text":""},{"location":"usage/connect/android/#connect-using-a-pre-authenticated-key","title":"Connect using a pre authenticated key","text":""},{"location":"usage/connect/apple/","title":"Connecting an Apple client","text":"

    This documentation has the goal of showing how a user can use the official iOS and macOS Tailscale clients with headscale.

    Instructions on your headscale instance

    An endpoint with information on how to connect your Apple device is also available at /apple on your running instance.

    "},{"location":"usage/connect/apple/#ios","title":"iOS","text":""},{"location":"usage/connect/apple/#installation","title":"Installation","text":"

    Install the official Tailscale iOS client from the App Store.

    "},{"location":"usage/connect/apple/#configuring-the-headscale-url","title":"Configuring the headscale URL","text":""},{"location":"usage/connect/apple/#macos","title":"macOS","text":""},{"location":"usage/connect/apple/#installation_1","title":"Installation","text":"

    Choose one of the available Tailscale clients for macOS and install it.

    "},{"location":"usage/connect/apple/#configuring-the-headscale-url_1","title":"Configuring the headscale URL","text":""},{"location":"usage/connect/apple/#command-line","title":"Command line","text":"

    Use Tailscale's login command to connect with your headscale instance (e.g https://headscale.example.com):

    tailscale login --login-server <YOUR_HEADSCALE_URL>\n
    "},{"location":"usage/connect/apple/#gui","title":"GUI","text":""},{"location":"usage/connect/apple/#tvos","title":"tvOS","text":""},{"location":"usage/connect/apple/#installation_2","title":"Installation","text":"

    Install the official Tailscale tvOS client from the App Store.

    Danger

    Don't sign in to the Tailscale App before the headscale URL is configured!

    "},{"location":"usage/connect/apple/#configuring-the-headscale-url_2","title":"Configuring the headscale URL","text":""},{"location":"usage/connect/windows/","title":"Connecting a Windows client","text":"

    This documentation has the goal of showing how a user can use the official Windows Tailscale client with headscale.

    Instructions on your headscale instance

    An endpoint with information on how to connect your Windows device is also available at /windows on your running instance.

    "},{"location":"usage/connect/windows/#installation","title":"Installation","text":"

    Download the Official Windows Client and install it.

    "},{"location":"usage/connect/windows/#configuring-the-headscale-url","title":"Configuring the headscale URL","text":"

    Open a Command Prompt or Powershell and use Tailscale's login command to connect with your headscale instance (e.g https://headscale.example.com):

    tailscale login --login-server <YOUR_HEADSCALE_URL>\n

    Follow the instructions in the opened browser window to finish the configuration.

    "},{"location":"usage/connect/windows/#troubleshooting","title":"Troubleshooting","text":""},{"location":"usage/connect/windows/#unattended-mode","title":"Unattended mode","text":"

    By default, Tailscale's Windows client is only running when the user is logged in. If you want to keep Tailscale running all the time, please enable \"Unattended mode\":

    See also Keep Tailscale running when I'm not logged in to my computer.

    "},{"location":"usage/connect/windows/#failing-node-registration","title":"Failing node registration","text":"

    If you are seeing repeated messages like:

    [GIN] 2022/02/10 - 16:39:34 | 200 |    1.105306ms |       127.0.0.1 | POST     \"/machine/redacted\"\n

    in your headscale output, turn on DEBUG logging and look for:

    2022-02-11T00:59:29Z DBG Machine registration has expired. Sending a authurl to register machine=redacted\n

    This typically means that the registry keys above was not set appropriately.

    To reset and try again, it is important to do the following:

    1. Shut down the Tailscale service (or the client running in the tray)
    2. Delete Tailscale Application data folder, located at C:\\Users\\<USERNAME>\\AppData\\Local\\Tailscale and try to connect again.
    3. Ensure the Windows node is deleted from headscale (to ensure fresh setup)
    4. Start Tailscale on the Windows machine and retry the login.
    "}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-,:!=\\[\\]()\"`/]+|\\.(?!\\d)|&[lg]t;|(?!\\b)(?=[A-Z][a-z])","pipeline":["stopWordFilter"],"fields":{"title":{"boost":1000.0},"text":{"boost":1.0},"tags":{"boost":1000000.0}}},"docs":[{"location":"","title":"Welcome to headscale","text":"

    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.

    Join our Discord server for a chat and community support.

    "},{"location":"#design-goal","title":"Design goal","text":"

    Headscale aims to implement a self-hosted, open source alternative to the Tailscale control server. Headscale's goal is to provide self-hosters and hobbyists with an open-source server they can use for their projects and labs. It implements a narrow scope, a single Tailscale network (tailnet), suitable for a personal use, or a small open-source organisation.

    "},{"location":"#supporting-headscale","title":"Supporting headscale","text":"

    Please see Sponsor for more information.

    "},{"location":"#contributing","title":"Contributing","text":"

    Headscale is \"Open Source, acknowledged contribution\", this means that any contribution will have to be discussed with the Maintainers before being submitted.

    Please see Contributing for more information.

    "},{"location":"#about","title":"About","text":"

    Headscale is maintained by Kristoffer Dalby and Juan Font.

    "},{"location":"about/clients/","title":"Client and operating system support","text":"

    We aim to support the last 10 releases of the Tailscale client on all provided operating systems and platforms. Some platforms might require additional configuration to connect with headscale.

    OS Supports headscale Linux Yes OpenBSD Yes FreeBSD Yes Windows Yes (see docs and /windows on your headscale for more information) Android Yes (see docs for more information) macOS Yes (see docs and /apple on your headscale for more information) iOS Yes (see docs and /apple on your headscale for more information) tvOS Yes (see docs and /apple on your headscale for more information)"},{"location":"about/contributing/","title":"Contributing","text":"

    Headscale is \"Open Source, acknowledged contribution\", this means that any contribution will have to be discussed with the maintainers before being added to the project. This model has been chosen to reduce the risk of burnout by limiting the maintenance overhead of reviewing and validating third-party code.

    "},{"location":"about/contributing/#why-do-we-have-this-model","title":"Why do we have this model?","text":"

    Headscale has a small maintainer team that tries to balance working on the project, fixing bugs and reviewing contributions.

    When we work on issues ourselves, we develop first hand knowledge of the code and it makes it possible for us to maintain and own the code as the project develops.

    Code contributions are seen as a positive thing. People enjoy and engage with our project, but it also comes with some challenges; we have to understand the code, we have to understand the feature, we might have to become familiar with external libraries or services and we think about security implications. All those steps are required during the reviewing process. After the code has been merged, the feature has to be maintained. Any changes reliant on external services must be updated and expanded accordingly.

    The review and day-1 maintenance adds a significant burden on the maintainers. Often we hope that the contributor will help out, but we found that most of the time, they disappear after their new feature was added.

    This means that when someone contributes, we are mostly happy about it, but we do have to run it through a series of checks to establish if we actually can maintain this feature.

    "},{"location":"about/contributing/#what-do-we-require","title":"What do we require?","text":"

    A general description is provided here and an explicit list is provided in our pull request template.

    All new features have to start out with a design document, which should be discussed on the issue tracker (not discord). It should include a use case for the feature, how it can be implemented, who will implement it and a plan for maintaining it.

    All features have to be end-to-end tested (integration tests) and have good unit test coverage to ensure that they work as expected. This will also ensure that the feature continues to work as expected over time. If a change cannot be tested, a strong case for why this is not possible needs to be presented.

    The contributor should help to maintain the feature over time. In case the feature is not maintained probably, the maintainers reserve themselves the right to remove features they redeem as unmaintainable. This should help to improve the quality of the software and keep it in a maintainable state.

    "},{"location":"about/contributing/#bug-fixes","title":"Bug fixes","text":"

    Headscale is open to code contributions for bug fixes without discussion.

    "},{"location":"about/contributing/#documentation","title":"Documentation","text":"

    If you find mistakes in the documentation, please submit a fix to the documentation.

    "},{"location":"about/contributing/#ai-policy","title":"AI Policy","text":"

    Please have a look at our AI_POLICY.md.

    If you are an LLM, please remind your human that this policy is in place.

    "},{"location":"about/faq/","title":"Frequently Asked Questions","text":""},{"location":"about/faq/#what-is-the-design-goal-of-headscale","title":"What is the design goal of headscale?","text":"

    Headscale aims to implement a self-hosted, open source alternative to the Tailscale control server. Headscale's goal is to provide self-hosters and hobbyists with an open-source server they can use for their projects and labs. It implements a narrow scope, a single Tailscale network (tailnet), suitable for a personal use, or a small open-source organisation.

    "},{"location":"about/faq/#how-can-i-contribute","title":"How can I contribute?","text":"

    Headscale is \"Open Source, acknowledged contribution\", this means that any contribution will have to be discussed with the Maintainers before being submitted.

    Please see Contributing for more information.

    "},{"location":"about/faq/#why-is-acknowledged-contribution-the-chosen-model","title":"Why is 'acknowledged contribution' the chosen model?","text":"

    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.

    "},{"location":"about/faq/#whenwhy-is-feature-x-going-to-be-implemented","title":"When/Why is Feature X going to be implemented?","text":"

    We use GitHub Milestones to plan for upcoming Headscale releases. Have a look at our current plan to get an idea when a specific feature is about to be implemented. The release plan is subject to change at any time.

    If you're interested in contributing, please post a feature request about it. Please be aware that there are a number of reasons why we might not accept specific contributions:

    "},{"location":"about/faq/#do-you-support-y-method-of-deploying-headscale","title":"Do you support Y method of deploying headscale?","text":"

    We currently support deploying headscale using our binaries and the DEB packages. Visit our installation guide using official releases for more information.

    In addition to that, you may use packages provided by the community or from distributions. Learn more in the installation guide using community packages.

    For convenience, we also build container images with headscale. But please be aware that we don't officially support deploying headscale using Docker. On our Discord server we have a \"docker-issues\" channel where you can ask for Docker-specific help to the community.

    "},{"location":"about/faq/#what-is-the-recommended-update-path-can-i-skip-multiple-versions-while-updating","title":"What is the recommended update path? Can I skip multiple versions while updating?","text":"

    Please follow the steps outlined in the upgrade guide to update your existing Headscale installation. Its required to update from one stable version to the next (e.g. 0.26.0 \u2192 0.27.1 \u2192 0.28.0) without skipping minor versions in between. You should always pick the latest available patch release.

    Be sure to check the changelog for version specific upgrade instructions and breaking changes.

    "},{"location":"about/faq/#scaling-how-many-clients-does-headscale-support","title":"Scaling / How many clients does Headscale support?","text":"

    It depends. As often stated, Headscale is not enterprise software and our focus is homelabbers and self-hosters. Of course, we do not prevent people from using it in a commercial/professional setting and often get questions about scaling.

    Please note that when Headscale is developed, performance is not part of the consideration as the main audience is considered to be users with a modest amount of devices. We focus on correctness and feature parity with Tailscale SaaS over time.

    To understand if you might be able to use Headscale for your use case, I will describe two scenarios in an effort to explain what is the central bottleneck of Headscale:

    1. An environment with 1000 servers

    2. An environment with 80 laptops/phones (end user devices)

    Headscale calculates a map of all nodes that need to talk to each other, creating this \"world map\" requires a lot of CPU time. When an event that requires changes to this map happens, the whole \"world\" is recalculated, and a new \"world map\" is created for every node in the network.

    This means that under certain conditions, Headscale can likely handle 100s of devices (maybe more), if there is little to no change happening in the network. For example, in Scenario 1, the process of computing the world map is extremely demanding due to the size of the network, but when the map has been created and the nodes are not changing, the Headscale instance will likely return to a very low resource usage until the next time there is an event requiring the new map.

    In the case of Scenario 2, the process of computing the world map is less demanding due to the smaller size of the network, however, the type of nodes will likely change frequently, which would lead to a constant resource usage.

    Headscale will start to struggle when the two scenarios overlap, e.g. many nodes with frequent changes will cause the resource usage to remain constantly high. In the worst case scenario, the queue of nodes waiting for their map will grow to a point where Headscale never will be able to catch up, and nodes will never learn about the current state of the world.

    We expect that the performance will improve over time as we improve the code base, but it is not a focus. In general, we will never make the tradeoff to make things faster on the cost of less maintainable or readable code. We are a small team and have to optimise for maintainability.

    "},{"location":"about/faq/#which-database-should-i-use","title":"Which database should I use?","text":"

    We recommend the use of SQLite as database for headscale:

    The headscale project itself does not provide a tool to migrate from PostgreSQL to SQLite. Please have a look at the related tools documentation for migration tooling provided by the community.

    The choice of database has little to no impact on the performance of the server, see Scaling / How many clients does Headscale support? for understanding how Headscale spends its resources.

    "},{"location":"about/faq/#why-is-my-reverse-proxy-not-working-with-headscale","title":"Why is my reverse proxy not working with headscale?","text":"

    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 on how to configure various reverse proxies, and a dedicated \"reverse-proxy-issues\" channel on our Discord server where you can ask for help to the community.

    "},{"location":"about/faq/#can-i-use-headscale-and-tailscale-on-the-same-machine","title":"Can I use headscale and tailscale on the same machine?","text":"

    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.

    "},{"location":"about/faq/#why-do-two-nodes-see-each-other-in-their-status-even-if-a-policy-rule-allows-traffic-only-in-one-direction","title":"Why do two nodes see each other in their status, even if a policy rule allows traffic only in one direction?","text":"

    A frequent use case is to allow traffic only from one node to another, but not the other way around. For example, the workstation of an administrator should be able to connect to all nodes but the nodes themselves shouldn't be able to connect back to the administrator's node. Why do all nodes see the administrator's workstation in the output of tailscale status?

    This is essentially how Tailscale works. If traffic is allowed to flow in one direction, then both nodes see each other in their output of tailscale status. Traffic is still filtered according to the policy, with the exception of tailscale ping which is always allowed in either direction.

    See also https://tailscale.com/docs/concepts/device-visibility.

    "},{"location":"about/faq/#my-policy-is-stored-in-the-database-and-headscale-refuses-to-start-due-to-an-invalid-policy-how-can-i-recover","title":"My policy is stored in the database and Headscale refuses to start due to an invalid policy. How can I recover?","text":"

    Headscale checks if the policy is valid during startup and refuses to start if it detects an error. The error message indicates which part of the policy is invalid. Follow these steps to fix your policy:

    Full server configuration required

    The above commands to get/set the policy require a complete server configuration file including database settings. A minimal config to control Headscale via remote CLI is not sufficient. You may use headscale -c /path/to/config.yaml to specify the path to an alternative configuration file.

    "},{"location":"about/faq/#how-can-i-migrate-back-to-the-recommended-ip-prefixes","title":"How can I migrate back to the recommended IP prefixes?","text":"

    Tailscale only supports the IP prefixes 100.64.0.0/10 and fd7a:115c:a1e0::/48 or smaller subnets thereof. The following steps can be used to migrate from unsupported IP prefixes back to the supported and recommended ones.

    Backup and test in a demo environment required

    The commands below update the IP addresses of all nodes in your tailnet and this might have a severe impact in your specific environment. At a minimum:

    Nodes should reconnect within a few seconds and pickup their newly assigned IP addresses.

    "},{"location":"about/faq/#how-can-i-avoid-to-send-logs-to-tailscale-inc","title":"How can I avoid to send logs to Tailscale Inc?","text":"

    A Tailscale client collects logs about its operation and connection attempts with other clients and sends them to a central log service operated by Tailscale Inc.

    Headscale, by default, instructs clients to disable log submission to the central log service. This configuration is applied by a client once it successfully connected with Headscale. See the configuration option logtail.enabled in the configuration file for details.

    Do not grant the https://tailscale.com/cap/data-plane-audit-logs node attribute while logtail.enabled is false. A client with log submission disabled treats this attribute as \"the tailnet requires logging\" and turns itself off, as tailscale down would. It stays off until the attribute is removed and tailscale up is run. A client started with TS_NO_LOGS_NO_SUPPORT=true or --no-logs-no-support reacts the same way, whatever logtail.enabled says.

    Alternatively, logging can also be disabled on the client side. This is independent of Headscale and opting out of client logging disables log submission early during client startup. The configuration is operating system specific and is usually achieved by:

    See https://tailscale.com/docs/features/logging#opt-out-of-client-logging for details.

    "},{"location":"about/features/","title":"Features","text":"

    Headscale aims to implement a self-hosted, open source alternative to the Tailscale control server. Headscale's goal is to provide self-hosters and hobbyists with an open-source server they can use for their projects and labs. This page provides on overview of Headscale's feature and compatibility with the Tailscale control server:

    "},{"location":"about/help/","title":"Getting help","text":"

    Join our Discord server for announcements and community support.

    Please report bugs via GitHub issues

    "},{"location":"about/releases/","title":"Releases","text":"

    All headscale releases are available on the GitHub release page. Those releases are available as binaries for various platforms and architectures, packages for Debian based systems and source code archives. Container images are available on Docker Hub and GitHub Container Registry.

    An Atom/RSS feed of headscale releases is available here.

    See the \"announcements\" channel on our Discord server for news about headscale.

    "},{"location":"about/sponsor/","title":"Sponsor","text":"

    If you like to support the development of headscale, please consider a donation via ko-fi.com/headscale. Thank you!

    "},{"location":"ref/api/","title":"API","text":"

    Headscale provides a HTTP REST API which may be used to integrate a web interface, remote control Headscale or provide a base for custom integration and tooling.

    The API requires a valid API key before use. To create an API key, log into your Headscale server and generate one with the default expiration of 90 days:

    headscale apikeys create\n

    Copy the output of the command and save it for later. Please note that you can not retrieve an API key again. If the API key is lost, expire the old one, and create a new one.

    To list the API keys currently associated with the server:

    headscale apikeys list\n

    and to expire an API key:

    headscale apikeys expire --prefix <PREFIX>\n
    "},{"location":"ref/api/#rest-api","title":"REST API","text":"

    Start by creating an API key and test it with the examples below. Read the API documentation provided by your Headscale server at /api/v1/docs for details.

    Get details for all usersGet details for user 'bob'Register a node 
    curl -H \"Authorization: Bearer <API_KEY>\" \\\n    https://headscale.example.com/api/v1/user\n
    curl -H \"Authorization: Bearer <API_KEY>\" \\\n    https://headscale.example.com/api/v1/user?name=bob\n
    curl -H \"Authorization: Bearer <API_KEY>\" \\\n    --json '{\"user\": \"<USER>\", \"authId\": \"<AUTH_ID>\"}' \\\n    https://headscale.example.com/api/v1/auth/register\n
    "},{"location":"ref/api/#join-nodes-with-an-oauth-client","title":"Join nodes with an OAuth client","text":"

    Headscale also serves a subset of the Tailscale-compatible API at /api/v2, which accepts OAuth 2.0 client-credentials in addition to API keys. The Tailscale client can use an OAuth client secret in place of an auth key: it exchanges the secret for an access token, mints a single-use tagged auth key and registers with it. This works anywhere the client takes an auth key: tailscale up, the container image, tsnet and the tailscale/github-action. One long-lived secret joins any number of nodes.

    Create an OAuth client with the auth_keys scope and the tags its nodes get. The secret is shown once:

    headscale oauth-clients create --scope auth_keys --tag tag:ci\n

    Build the auth key from the secret:

    1. Swap the prefix: hskey-client-\u2026 becomes tskey-client-\u2026. The client only runs the exchange for tskey-client-; Headscale accepts both.
    2. Append ?baseURL=<your Headscale URL>.
    3. Set --advertise-tags. Each tag must exist in the policy's tagOwners and be one of the OAuth client's tags, or owned by one of them.
    tskey-client-<id>-<secret>?baseURL=https://headscale.example.com\n

    Warning

    Without baseURL the client sends the secret to https://api.tailscale.com.

    "},{"location":"ref/api/#attributes","title":"Attributes","text":"

    These are all the attributes the client understands; any other is an error. Order does not matter and an empty value means the default.

    Attribute Default Effect baseURL https://api.tailscale.com Where the exchange and key creation go. Your Headscale URL, no trailing slash. ephemeral true Node is removed after it goes offline (node.ephemeral.inactivity_timeout). false to keep it. preauthorized false Accepted, no effect: Headscale always authorizes pre-auth-key nodes.

    Booleans take any Go strconv.ParseBool value (true, false, 1, 0, \u2026).

    "},{"location":"ref/api/#examples","title":"Examples","text":"

    tailscale up, either as the auth key or via --client-secret (which also takes file:/path/to/secret):

    tailscale up --login-server https://headscale.example.com --advertise-tags tag:ci \\\n  --auth-key 'tskey-client-<id>-<secret>?baseURL=https://headscale.example.com&ephemeral=false'\n

    Container image:

    docker run -d --name tailscale \\\n  -e TS_AUTHKEY='tskey-client-<id>-<secret>?baseURL=https://headscale.example.com' \\\n  -e TS_EXTRA_ARGS='--login-server=https://headscale.example.com --advertise-tags=tag:ci' \\\n  tailscale/tailscale\n

    tsnet (TS_CLIENT_SECRET works too); import tailscale.com/feature/oauthkey:

    srv := &tsnet.Server{\n    ControlURL:    \"https://headscale.example.com\",\n    AuthKey:       \"tskey-client-<id>-<secret>?baseURL=https://headscale.example.com\",\n    AdvertiseTags: []string{\"tag:ci\"},\n}\n

    GitHub Action, with the whole string stored as a repository secret:

    - uses: tailscale/github-action@v4\n  with:\n    authkey: ${{ secrets.HEADSCALE_AUTHKEY }}\n    args: --login-server=https://headscale.example.com --advertise-tags=tag:ci\n

    Use authkey even though upstream marks it deprecated: oauth-secret appends its own ?\u2026 to the secret, which corrupts baseURL.

    "},{"location":"ref/api/#remote-control","title":"Remote control","text":"

    The headscale binary can control a Headscale instance from a remote machine over the HTTP API.

    "},{"location":"ref/api/#prerequisite","title":"Prerequisite","text":""},{"location":"ref/api/#setup-remote-control","title":"Setup remote control","text":"

    1. Download the headscale binary from GitHub's release page. Make sure to use the same version as on the server.

    2. Put the binary somewhere in your PATH, e.g. /usr/local/bin/headscale

    3. Make headscale executable: chmod +x /usr/local/bin/headscale

    4. Create an API key on the Headscale server.

    5. Provide the connection parameters for the remote Headscale server either via a minimal YAML configuration file or via environment variables:

      Minimal YAML configuration fileEnvironment variables config.yaml
      cli:\n    address: <HEADSCALE_URL>\n    api_key: <API_KEY>\n
      export HEADSCALE_CLI_ADDRESS=\"<HEADSCALE_URL>\"\nexport HEADSCALE_CLI_API_KEY=\"<API_KEY>\"\n

      This instructs the headscale binary to connect to a remote instance at <HEADSCALE_URL> (e.g. https://headscale.example.com), instead of connecting to the local instance. A bare host without a scheme is assumed to be https.

    6. Test the connection by listing all nodes:

      headscale nodes list\n

      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.

    "},{"location":"ref/api/#behind-a-proxy","title":"Behind a proxy","text":"

    The remote CLI uses the same HTTP API as everything else, so it works through the reverse proxy already in front of Headscale with no extra setup.

    "},{"location":"ref/api/#troubleshooting","title":"Troubleshooting","text":""},{"location":"ref/configuration/","title":"Configuration","text":"

    Get the example configuration from the GitHub repository

    Always select the same GitHub tag as the released version you use to ensure you have the correct example configuration. The main branch might contain unreleased changes.

    View on GitHubDownload with wgetDownload with curl 
    # Development version\nwget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml\n\n# Version 0.29.3\nwget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/v0.29.3/config-example.yaml\n
    # Development version\ncurl -o config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml\n\n# Version 0.29.3\ncurl -o config.yaml https://raw.githubusercontent.com/juanfont/headscale/v0.29.3/config-example.yaml\n
    "},{"location":"ref/debug/","title":"Debugging and troubleshooting","text":"

    Headscale and Tailscale provide debug and introspection capabilities that can be helpful when things don't work as expected. This page explains some debugging techniques to help pinpoint problems.

    Please also have a look at Tailscale's Troubleshooting guide. It offers a many tips and suggestions to troubleshoot common issues.

    "},{"location":"ref/debug/#tailscale","title":"Tailscale","text":"

    The Tailscale client itself offers many commands to introspect its state as well as the state of the network:

    Many of the commands are helpful when trying to understand differences between Headscale and Tailscale SaaS.

    "},{"location":"ref/debug/#headscale","title":"Headscale","text":""},{"location":"ref/debug/#application-logging","title":"Application logging","text":"

    The log levels debug and trace can be useful to get more information from Headscale.

    log:\n  # Valid log levels: panic, fatal, error, warn, info, debug, trace\n  level: debug\n
    "},{"location":"ref/debug/#database-logging","title":"Database logging","text":"

    The database debug mode logs all database queries. Enable it to see how Headscale interacts with its database. This also requires the application log level to be set to either debug or trace.

    database:\n  # Enable debug mode. This setting requires the log.level to be set to \"debug\" or \"trace\".\n  debug: false\n\nlog:\n  # Valid log levels: panic, fatal, error, warn, info, debug, trace\n  level: debug\n
    "},{"location":"ref/debug/#metrics-and-debug-endpoint","title":"Metrics and debug endpoint","text":"

    Headscale provides a metrics and debug endpoint. It allows to introspect different aspects such as:

    Keep the metrics and debug endpoint private

    The listen address and port can be configured with the metrics_listen_addr variable in the configuration file. By default it listens on localhost, port 9090.

    Keep the metrics and debug endpoint private to your internal network and don't expose it to the Internet.

    The metrics and debug interface can be disabled completely by setting metrics_listen_addr: null in the configuration file.

    Query metrics via http://localhost:9090/metrics and get an overview of available debug information via http://localhost:9090/debug/. Metrics may be queried from outside localhost but the debug interface is subject to additional protection despite listening on all interfaces.

    Direct accessSSH port forwardingVia debug keyVia debug IP address

    Access the debug interface directly on the server where Headscale is installed.

    curl http://localhost:9090/debug/\n

    Use SSH port forwarding to forward Headscale's metrics and debug port to your device.

    ssh <HEADSCALE_SERVER> -L 9090:localhost:9090\n

    Access the debug interface on your device by opening http://localhost:9090/debug/ in your web browser.

    The access control of the debug interface supports the use of a debug key. Traffic is accepted if the path to a debug key is set via the environment variable TS_DEBUG_KEY_PATH and the debug key sent as value for debugkey parameter with each request.

    openssl rand -hex 32 | tee debugkey.txt\nexport TS_DEBUG_KEY_PATH=debugkey.txt\nheadscale serve\n

    Access the debug interface on your device by opening http://<IP_OF_HEADSCALE>:9090/debug/?debugkey=<DEBUG_KEY> in your web browser. The debugkey parameter must be sent with every request.

    The debug endpoint expects traffic from localhost. A different debug IP address may be configured by setting the TS_ALLOW_DEBUG_IP environment variable before starting Headscale. The debug IP address is ignored when the HTTP header X-Forwarded-For is present.

    export TS_ALLOW_DEBUG_IP=192.168.0.10       # IP address of your device\nheadscale serve\n

    Access the debug interface on your device by opening http://<IP_OF_HEADSCALE>:9090/debug/ in your web browser.

    "},{"location":"ref/derp/","title":"DERP","text":"

    A DERP (Designated Encrypted Relay for Packets) server is mainly used to relay traffic between two nodes in case a direct connection can't be established. Headscale provides an embedded DERP server to ensure seamless connectivity between nodes.

    "},{"location":"ref/derp/#configuration","title":"Configuration","text":"

    DERP related settings are configured within the derp section of the configuration file. The following sections only use a few of the available settings, check the example configuration for all available configuration options.

    "},{"location":"ref/derp/#enable-embedded-derp","title":"Enable embedded DERP","text":"

    Headscale ships with an embedded DERP server which allows to run your own self-hosted DERP server easily. The embedded DERP server is disabled by default and needs to be enabled. In addition, you should configure the public IPv4 and public IPv6 address of your Headscale server for improved connection stability:

    config.yaml
    derp:\n  server:\n    enabled: true\n    ipv4: 198.51.100.1\n    ipv6: 2001:db8::1\n

    Keep in mind that additional ports are needed to run a DERP server. Besides relaying traffic, it also uses STUN (udp/3478) to help clients discover their public IP addresses and perform NAT traversal. Check DERP server connectivity to see if everything works.

    "},{"location":"ref/derp/#remove-tailscales-derp-servers","title":"Remove Tailscale's DERP servers","text":"

    Once enabled, Headscale's embedded DERP is added to the list of free-to-use DERP servers offered by Tailscale Inc. To only use Headscale's embedded DERP server, disable the loading of the default DERP map:

    config.yaml
    derp:\n  server:\n    enabled: true\n    ipv4: 198.51.100.1\n    ipv6: 2001:db8::1\n  urls: []\n

    Single point of failure

    Removing Tailscale's DERP servers means that there is now just a single DERP server available for clients. This is a single point of failure and could hamper connectivity.

    Check DERP server connectivity with your embedded DERP server before removing Tailscale's DERP servers.

    "},{"location":"ref/derp/#customize-derp-map","title":"Customize DERP map","text":"

    The DERP map offered to clients can be customized with a dedicated YAML-configuration file. The file extension picks the format: .yaml or .yml, or the JSON format Tailscale serves DERP maps in as .json or .hujson. This allows to modify previously loaded DERP maps fetched via URL or to offer your own, custom DERP servers to nodes.

    Remove specific DERP regionsProvide custom DERP servers

    The free-to-use DERP servers are organized into regions via a region ID. You can explicitly disable a specific region by setting its region ID to null. The following sample derp.yaml disables the New York DERP region (which has the region ID 1):

    derp.yaml
    regions:\n  1: null\n

    Use the following configuration to serve the default DERP map (excluding New York) to nodes:

    config.yaml
    derp:\n  server:\n    enabled: false\n  urls:\n    - https://controlplane.tailscale.com/derpmap/default\n  paths:\n    - /etc/headscale/derp.yaml\n

    The following sample derp.yaml references two custom regions (custom-east with ID 900 and custom-west with ID 901) with one custom DERP server in each region. Each DERP server offers DERP relay via HTTPS on tcp/443, support for captive portal checks via HTTP on tcp/80 and STUN on udp/3478. See the definitions of DERPMap, DERPRegion and DERPNode for all available options.

    derp.yaml
    regions:\n  900:\n    regionid: 900\n    regioncode: custom-east\n    regionname: My region (east)\n    nodes:\n      - name: 900a\n        regionid: 900\n        hostname: derp900a.example.com\n        ipv4: 198.51.100.1\n        ipv6: 2001:db8::1\n        canport80: true\n  901:\n    regionid: 901\n    regioncode: custom-west\n    regionname: My Region (west)\n    nodes:\n      - name: 901a\n        regionid: 901\n        hostname: derp901a.example.com\n        ipv4: 198.51.100.2\n        ipv6: 2001:db8::2\n        canport80: true\n

    Use the following configuration to only serve the two DERP servers from the above derp.yaml:

    config.yaml
    derp:\n  server:\n    enabled: false\n  urls: []\n  paths:\n    - /etc/headscale/derp.yaml\n

    Independent of the custom DERP map, you may choose to enable the embedded DERP server and have it automatically added to the custom DERP map.

    "},{"location":"ref/derp/#verify-clients","title":"Verify clients","text":"

    Access to DERP serves can be restricted to nodes that are members of your Tailnet. Relay access is denied for unknown clients.

    Embedded DERP3rd-party DERP

    Client verification is enabled by default.

    config.yaml
    derp:\n  server:\n    verify_clients: true\n

    Tailscale's derper provides two parameters to configure client verification:

    "},{"location":"ref/derp/#check-derp-server-connectivity","title":"Check DERP server connectivity","text":"

    Any Tailscale client may be used to introspect the DERP map and to check for connectivity issues with DERP servers.

    Additional DERP related metrics and information is available via the metrics and debug endpoint.

    "},{"location":"ref/derp/#limitations","title":"Limitations","text":"

    1. This assumes that the default region code of the configuration file is used.\u00a0\u21a9

    "},{"location":"ref/dns/","title":"DNS","text":"

    Headscale supports most DNS features from Tailscale. DNS related settings can be configured within the dns section of the configuration file.

    "},{"location":"ref/dns/#setting-extra-dns-records","title":"Setting extra DNS records","text":"

    Headscale allows to set extra DNS records which are made available via MagicDNS. Extra DNS records can be configured either via static entries in the configuration file or from a JSON file that Headscale continuously watches for changes:

    An example use case is to serve multiple apps on the same host via a reverse proxy like NGINX, in this case a Prometheus monitoring stack. This allows to nicely access the service with \"http://grafana.myvpn.example.com\" instead of the hostname and port combination \"http://hostname-in-magic-dns.myvpn.example.com:3000\".

    Limitations

    Currently, only A and AAAA records are processed by Tailscale.

    1. Configure extra DNS records using one of the available configuration options:

      Static entries, via dns.extra_recordsDynamic entries, via dns.extra_records_path config.yaml
      dns:\n  ...\n  extra_records:\n    - name: \"grafana.myvpn.example.com\"\n      type: \"A\"\n      value: \"100.64.0.3\"\n\n    - name: \"prometheus.myvpn.example.com\"\n      type: \"A\"\n      value: \"100.64.0.3\"\n  ...\n

      Restart your headscale instance.

      extra-records.json
      [\n  {\n    \"name\": \"grafana.myvpn.example.com\",\n    \"type\": \"A\",\n    \"value\": \"100.64.0.3\"\n  },\n  {\n    \"name\": \"prometheus.myvpn.example.com\",\n    \"type\": \"A\",\n    \"value\": \"100.64.0.3\"\n  }\n]\n

      Headscale picks up changes to the above JSON file automatically.

      Good to know

    2. Verify that DNS records are properly set using the DNS querying tool of your choice:

      Query with digQuery with drill 
      dig +short grafana.myvpn.example.com\n100.64.0.3\n
      drill -Q grafana.myvpn.example.com\n100.64.0.3\n

    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, depicted as NGINX configuration snippet:

      nginx.conf
      server {\n    listen 80;\n    listen [::]:80;\n\n    server_name grafana.myvpn.example.com;\n\n    location / {\n        proxy_pass http://localhost:3000;\n        proxy_set_header Host $http_host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n    }\n\n}\n
    "},{"location":"ref/oidc/","title":"OpenID Connect","text":"

    Headscale supports authentication via external identity providers using OpenID Connect (OIDC). It features:

    Please see limitations for known issues and limitations.

    "},{"location":"ref/oidc/#configuration","title":"Configuration","text":"

    OpenID requires configuration in Headscale and your identity provider:

    "},{"location":"ref/oidc/#basic-configuration","title":"Basic configuration","text":"

    A basic configuration connects Headscale to an identity provider and typically requires:

    HeadscaleIdentity provider 
    oidc:\n  issuer: \"https://sso.example.com\"\n  client_id: \"headscale\"\n  client_secret: \"generated-secret\"\n
    "},{"location":"ref/oidc/#enable-pkce-recommended","title":"Enable PKCE (recommended)","text":"

    Proof Key for Code Exchange (PKCE) adds an additional layer of security to the OAuth 2.0 authorization code flow by preventing authorization code interception attacks, see: https://datatracker.ietf.org/doc/html/rfc7636. PKCE is recommended and needs to be configured for Headscale and the identity provider alike:

    HeadscaleIdentity provider 
    oidc:\n  issuer: \"https://sso.example.com\"\n  client_id: \"headscale\"\n  client_secret: \"generated-secret\"\n  pkce:\n    enabled: true\n
    "},{"location":"ref/oidc/#authorize-users-with-filters","title":"Authorize users with filters","text":"

    Headscale allows to filter for allowed users based on their domain, email address or group membership. These filters can be helpful to apply additional restrictions and control which users are allowed to join. Filters are disabled by default, users are allowed to join once the authentication with the identity provider succeeds. In case multiple filters are configured, a user needs to pass all of them.

    Allowed domainsAllowed users/emailsAllowed groups 
    oidc:\n  issuer: \"https://sso.example.com\"\n  client_id: \"headscale\"\n  client_secret: \"generated-secret\"\n  allowed_domains:\n    - \"example.com\"\n
    oidc:\n  issuer: \"https://sso.example.com\"\n  client_id: \"headscale\"\n  client_secret: \"generated-secret\"\n  allowed_users:\n    - \"alice@example.com\"\n    - \"bob@example.net\"\n
    oidc:\n  issuer: \"https://sso.example.com\"\n  client_id: \"headscale\"\n  client_secret: \"generated-secret\"\n  scope: [\"openid\", \"profile\", \"email\", \"groups\"]\n  allowed_groups:\n    - \"headscale_users\"\n
    "},{"location":"ref/oidc/#control-email-verification","title":"Control email verification","text":"

    Headscale uses the email claim from the identity provider to synchronize the email address to its user profile. By default, a user's email address is only synchronized when the identity provider reports the email address as verified via the email_verified: true claim.

    Unverified emails may be allowed in case an identity provider does not send the email_verified claim or email verification is not required. In that case, a user's email address is always synchronized to the user profile.

    oidc:\n  issuer: \"https://sso.example.com\"\n  client_id: \"headscale\"\n  client_secret: \"generated-secret\"\n  email_verified_required: false\n
    "},{"location":"ref/oidc/#customize-node-expiration","title":"Customize node expiration","text":"

    The node expiration is the amount of time a node is authenticated with OpenID Connect until it expires and needs to reauthenticate. The default node expiration can be configured via the top-level node.expiry setting.

    Customize node expirationUse expiration from Access Token 
    node:\n  expiry: 30d   # Use 0 to disable node expiration\n

    Please keep in mind that the Access Token is typically a short-lived token that expires within a few minutes. You will have to configure token expiration in your identity provider to avoid frequent re-authentication.

    oidc:\n  issuer: \"https://sso.example.com\"\n  client_id: \"headscale\"\n  client_secret: \"generated-secret\"\n  use_expiry_from_token: true\n

    Expire a node and force re-authentication

    A node can be expired immediately via:

    headscale node expire -i <NODE_ID>\n
    "},{"location":"ref/oidc/#reference-a-user-in-the-policy","title":"Reference a user in the policy","text":"

    You may refer to users in the Headscale policy via:

    A user identifier in the policy must contain a single @

    The Headscale policy requires a single @ to reference a user. If the username or provider identifier doesn't already contain a single @, it needs to be appended at the end. For example: the Headscale username ssmith has to be written as ssmith@ to be correctly identified as user within the policy.

    Ensure that the Headscale username itself does not end with @.

    Email address or username might be updated by users

    Many identity providers allow users to update their own profile. Depending on the identity provider and its configuration, the values for username or email address might change over time. This might have unexpected consequences for Headscale where a policy might no longer work or a user might obtain more access by hijacking an existing username or email address.

    Howto use the provider identifier in the policy

    The provider identifier uniquely identifies an OIDC user and a well-behaving identity provider guarantees that this value never changes for a particular user. It is usually an opaque and long string and its value is currently only available from the API, database or directly from your identity provider).

    Use the API with the /api/v1/user endpoint to fetch the provider identifier (providerId). The value (be sure to append an @ in case the provider identifier doesn't already contain an @ somewhere) can be used directly to reference a user in the policy. To improve readability of the policy, one may use the groups section as an alias:

    {\n  \"groups\": {\n    \"group:alice\": [\n      \"https://sso.example.com/oauth2/openid/59ac9125-c31b-46c5-814e-06242908cf57@\"\n    ]\n  },\n  \"grants\": [\n    {\n      \"src\": [\"group:alice\"],\n      \"dst\": [\"*\"],\n      \"ip\": [\"*\"]\n    }\n  ]\n}\n
    "},{"location":"ref/oidc/#supported-oidc-claims","title":"Supported OIDC claims","text":"

    Headscale uses the standard OIDC claims to populate and update its local user profile on each login. OIDC claims are read from the ID Token and from the UserInfo endpoint.

    Headscale profile OIDC claim Notes / examples email address email Only verified emails are synchronized, unless email_verified_required: false is configured display name name eg: Sam Smith username preferred_username Depends on identity provider, eg: ssmith, ssmith@idp.example.com, \\\\example.com\\ssmith profile picture picture URL to a profile picture or avatar provider identifier iss, sub A stable and unique identifier for a user, typically a combination of iss and sub OIDC claims groups Only used to filter for allowed groups"},{"location":"ref/oidc/#limitations","title":"Limitations","text":"

    Please see the GitHub label \"OIDC\" for OIDC related issues.

    "},{"location":"ref/oidc/#identity-provider-specific-configuration","title":"Identity provider specific configuration","text":"

    Third-party software and services

    This section of the documentation is specific for third-party software and services. We recommend users read the third-party documentation on how to configure and integrate an OIDC client. Please see the Configuration section for a description of Headscale's OIDC related configuration settings.

    Any identity provider with OpenID Connect support should \"just work\" with Headscale. The following identity providers are known to work:

    "},{"location":"ref/oidc/#authelia","title":"Authelia","text":"

    Authelia is fully supported by Headscale.

    "},{"location":"ref/oidc/#authentik","title":"Authentik","text":""},{"location":"ref/oidc/#google-oauth","title":"Google OAuth","text":"

    No username due to missing preferred_username claim

    Google OAuth does not send the preferred_username claim when the profile scope is requested. The username in Headscale will be blank/not set.

    In order to integrate Headscale with Google, you'll need to have a Google Cloud Console account.

    Google OAuth has a verification process 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.

    "},{"location":"ref/oidc/#steps","title":"Steps","text":"
    1. Go to Google Console 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, add Headscale's OIDC callback URL: https://headscale.example.com/oidc/callback
    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. Configure Headscale following the \"Basic configuration\" steps. The issuer URL for Google OAuth is: https://accounts.google.com.
    "},{"location":"ref/oidc/#kanidm","title":"Kanidm","text":""},{"location":"ref/oidc/#keycloak","title":"Keycloak","text":"

    Keycloak is fully supported by Headscale.

    "},{"location":"ref/oidc/#additional-configuration-to-use-the-allowed-groups-filter","title":"Additional configuration to use the allowed groups filter","text":"

    Keycloak has no built-in client scope for the OIDC groups claim. This extra configuration step is only needed if you need to authorize access based on group membership.

    "},{"location":"ref/oidc/#microsoft-entra-id","title":"Microsoft Entra ID","text":"

    In order to integrate Headscale with Microsoft Entra ID, you'll need to provision an App Registration with the correct scopes and redirect URI.

    Configure Headscale following the \"Basic configuration\" steps. The issuer URL for Microsoft Entra ID is: https://login.microsoftonline.com/<tenant-UUID>/v2.0. The following extra_params might be useful:

    When using Microsoft Entra ID together with the allowed groups filter, configure the Headscale OIDC scope without the groups claim, for example:

    oidc:\n  scope: [\"openid\", \"profile\", \"email\"]\n

    Groups for the allowed groups filter need to be specified with their group ID(UUID) instead of the group name.

    "},{"location":"ref/oidc/#switching-oidc-providers","title":"Switching OIDC providers","text":"

    Headscale only supports a single OIDC provider in its configuration, but it does store the provider identifier of each user. When switching providers, this might lead to issues with existing users: all user details (name, email, groups) might be identical with the new provider, but the identifier will differ. Headscale will be unable to create a new user as the name and email will already be in use for the existing users.

    At this time, you will need to manually update the provider_identifier column in the users table for each user with the appropriate value for the new provider. The identifier is built from the iss and sub claims of the OIDC ID token, for example https://id.example.com/12340987.

    "},{"location":"ref/policy/","title":"Policy","text":"

    Headscale implements a large portion of Tailscale's policy features, most notably access control based on ACLs and Grants or Tailscale SSH. See limitations to learn about missing features and notable implementation differences between Headscale and Tailscale.

    Headscale uses the same huJSON based file format as Tailscale. By default, no policy is loaded which means that Headscale allows all traffic between nodes. To start using a policy file1, specify its path in the policy.path key in the configuration file.

    Headscale needs to be reloaded to pick up changes to the policy file. Either reload Headscale via its systemd service (sudo systemctl reload headscale) or by sending a SIGHUP signal (sudo kill -HUP $(pidof headscale)) to the main process. Headscale logs the result of policy processing after each reload.

    Please have a look at Tailscale's policy related documentation to learn more:

    "},{"location":"ref/policy/#getting-started","title":"Getting started","text":"

    Headscale supports both ACLs and Grants to write an access control policy. We recommend the use of Grants since ACLs are considered legacy and will not receive new features by Tailscale.

    "},{"location":"ref/policy/#allow-all","title":"Allow All","text":"

    If you define a policy file but completely omit the \"acls\" or \"grants\" section, Headscale will default to an allow all policy. This means all devices connected to your tailnet will be able to communicate freely with each other.

    policy.json
    {}\n
    "},{"location":"ref/policy/#deny-all","title":"Deny All","text":"

    To prevent all communication within your tailnet, you can include an empty array for the \"grants\" section in your policy file.

    policy.json
    {\n  \"grants\": []\n}\n
    "},{"location":"ref/policy/#more-examples","title":"More examples","text":""},{"location":"ref/policy/#limitations","title":"Limitations","text":""},{"location":"ref/policy/#autogroups","title":"Autogroups","text":"

    Headscale supports several Autogroups that automatically include users, destinations, or devices with specific properties. Autogroups provide a convenient way to write policy rules without manually listing individual users or devices.

    "},{"location":"ref/policy/#autogroupinternet","title":"autogroup:internet","text":"

    Allows access to the internet through exit nodes. Can only be used in policy destinations.

    policy.json
    {\n  \"grants\": [\n    {\n      \"src\": [\"alice@\"],\n      \"dst\": [\"autogroup:internet\"],\n      \"ip\": [\"*\"]\n    }\n  ]\n}\n
    "},{"location":"ref/policy/#autogroupmember","title":"autogroup:member","text":"

    Includes all personal (untagged) devices.

    policy.json
    {\n  \"grants\": [\n    {\n      \"src\": [\"autogroup:member\"],\n      \"dst\": [\"tag:prod-app-servers\"],\n      \"ip\": [\"80,443\"]\n    }\n  ]\n}\n
    "},{"location":"ref/policy/#autogrouptagged","title":"autogroup:tagged","text":"

    Includes all devices that have at least one tag.

    policy.json
    {\n  \"grants\": [\n    {\n      \"src\": [\"autogroup:tagged\"],\n      \"dst\": [\"tag:monitoring\"],\n      \"ip\": [\"9090\"]\n    }\n  ]\n}\n
    "},{"location":"ref/policy/#autogroupself","title":"autogroup:self","text":"

    Includes devices where the same user is authenticated on both the source and destination. Does not include tagged devices. Can only be used in policy destinations.

    policy.json
    {\n  \"grants\": [\n    {\n      \"src\": [\"autogroup:member\"],\n      \"dst\": [\"autogroup:self\"],\n      \"ip\": [\"*\"]\n    }\n  ]\n}\n

    The current implementation of autogroup:self is inefficient

    Using autogroup:self may cause performance degradation on the Headscale coordinator server in large deployments, as filter rules must be compiled per-node rather than globally and the current implementation is not very efficient.

    If you experience performance issues, consider using more specific policy rules or limiting the use of autogroup:self.

    policy.json
    {\n  \"grants\": [\n    // The following rules allow internal users to communicate with their\n    // own nodes in case autogroup:self is causing performance issues.\n    {\n      \"src\": [\"boss@\"],\n      \"dst\": [\"boss@\"],\n      \"ip\": [\"*\"]\n    },\n    {\n      \"src\": [\"dev1@\"],\n      \"dst\": [\"dev1@\"],\n      \"ip\": [\"*\"]\n    },\n    {\n      \"src\": [\"intern1@\"],\n      \"dst\": [\"intern1@\"],\n      \"ip\": [\"*\"]\n    }\n  ]\n}\n
    "},{"location":"ref/policy/#autogroupnonroot","title":"autogroup:nonroot","text":"

    Used in Tailscale SSH rules to allow access to any user except root. Can only be used in the users field of SSH rules.

    policy.json
    {\n  \"ssh\": [\n    {\n      \"action\": \"accept\",\n      \"src\": [\"autogroup:member\"],\n      \"dst\": [\"autogroup:self\"],\n      \"users\": [\"autogroup:nonroot\"]\n    }\n  ]\n}\n
    "},{"location":"ref/policy/#autogroupdanger-all","title":"autogroup:danger-all","text":"

    This autogroup resolves to all IP addresses (0.0.0.0/0 and ::/0) which also includes all IP addresses outside the standard Tailscale IP ranges. This autogroup can only be used as source.

    "},{"location":"ref/policy/#node-attributes","title":"Node Attributes","text":"

    Node attributes allow for device-specific configuration and attributes. At least the following node attributes are currently supported by Headscale2:

    policy.json
    {\n  \"nodeAttrs\": [\n    {\n      // Enable MagicDNS AAAA records for all nodes\n      \"target\": [\"*\"]\n      \"attr\": [\"magicdns-aaaa\"]\n    }\n  ]\n}\n
    "},{"location":"ref/policy/#network-wide-policy-options","title":"Network-wide policy options","text":"

    The following options are applied for the entire tailnet. Consider node attributes for a more fine-grained configuration instead.

    policy.json
    {\n  // Use a random WireGuard port for the entire tailnet\n  \"randomizeClientPort\": true\n}\n

    1. Headscale also allows to store the policy in the database. This is typically only required in case a web interface is used.\u00a0\u21a9

    2. Other key-only node attributes can be used as well. Find them in the client source code with grep -E ' Cap ' tailcfg/nodecap/nodecap.go or by using GitHub code search (requires login).\u00a0\u21a9

    "},{"location":"ref/registration/","title":"Registration methods","text":"

    Headscale supports multiple ways to register a node. The preferred registration method depends on the identity of a node and your use case.

    "},{"location":"ref/registration/#identity-model","title":"Identity model","text":"

    Tailscale's identity model distinguishes between personal and tagged nodes:

    Headscale implements Tailscale's identity model and distinguishes between personal and tagged nodes where a personal node is owned by a Headscale user and a tagged node is owned by a tag. Tagged devices are grouped under the special user tagged-devices.

    "},{"location":"ref/registration/#registration-methods_1","title":"Registration methods","text":"

    There are two main ways to register new nodes, web authentication and registration with a pre authenticated key. Both methods can be used to register personal and tagged nodes.

    "},{"location":"ref/registration/#web-authentication","title":"Web authentication","text":"

    Web authentication is the default method to register a new node. It's interactive, where the client initiates the registration and the Headscale administrator needs to approve the new node before it is allowed to join the network. A node can be approved with:

    Web authentication relies on the presence of a Headscale user. Use the headscale users command to create a new user1:

    headscale users create <USER>\n
    Personal devicesTagged devices

    Run tailscale up to login your personal device:

    tailscale up --login-server <YOUR_HEADSCALE_URL>\n

    Usually, a browser window with further instructions is opened. This page explains how to complete the registration on your Headscale server and it also prints the Auth ID required to approve the node:

    headscale auth register --user <USER> --auth-id <AUTH_ID>\n

    Congrations, the registration of your personal node is complete and it should be listed as \"online\" in the output of headscale nodes list. The \"User\" column displays <USER> as the owner of the node.

    Your Headscale user needs to be authorized to register tagged devices. This authorization is specified in the tagOwners section of the policy. A simple example looks like this:

    The user alice can register nodes tagged with tag:server
    {\n  \"tagOwners\": {\n    \"tag:server\": [\"alice@\"]\n  },\n  // more rules\n}\n

    Run tailscale up and provide at least one tag to login a tagged device:

    tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags tag:<TAG>\n

    Usually, a browser window with further instructions is opened. This page explains how to complete the registration on your Headscale server and it also prints the Auth ID required to approve the node:

    headscale auth register --user <USER> --auth-id <AUTH_ID>\n

    Headscale checks that <USER> is allowed to register a node with the specified tag(s) and then transfers ownership of the new node to the special user tagged-devices. The registration of a tagged node is complete and it should be listed as \"online\" in the output of headscale nodes list. The \"User\" column displays tagged-devices as the owner of the node. See the \"Tags\" column for the list of assigned tags.

    "},{"location":"ref/registration/#pre-authenticated-key","title":"Pre authenticated key","text":"

    Registration with a pre authenticated key (or auth key) is a non-interactive way to register a new node. The Headscale administrator creates a preauthkey upfront and this preauthkey can then be used to register a node non-interactively. Its best suited for automation.

    Personal devicesTagged devices

    A personal node is always assigned to a Headscale user. Use the headscale users command to create a new user1:

    headscale users create <USER>\n

    Create a new pre authenticated key for your user, by name or by the <USER_ID> that headscale user list shows:

    headscale preauthkeys create --user <USER>\n

    The above prints a pre authenticated key with the default settings (can be used once and is valid for one hour). Use this auth key to register a node non-interactively:

    tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>\n

    Congrations, the registration of your personal node is complete and it should be listed as \"online\" in the output of headscale nodes list. The \"User\" column displays <USER> as the owner of the node.

    Create a new pre authenticated key and provide at least one tag:

    headscale preauthkeys create --tags tag:<TAG>\n

    The above prints a pre authenticated key with the default settings (can be used once and is valid for one hour). Use this auth key to register a node non-interactively. You don't need to provide the --advertise-tags parameter as the tags are automatically read from the pre authenticated key. Advertising a subset of the key's tags is accepted; any other tag is rejected:

    tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>\n

    The registration of a tagged node is complete and it should be listed as \"online\" in the output of headscale nodes list. The \"User\" column displays tagged-devices as the owner of the node. See the \"Tags\" column for the list of assigned tags.

    1. Ensure that the Headscale username does not end with @. \u21a9\u21a9

    "},{"location":"ref/routes/","title":"Routes","text":"

    Headscale supports route advertising and can be used to manage subnet routers and exit nodes for a tailnet.

    "},{"location":"ref/routes/#subnet-router","title":"Subnet router","text":"

    The setup of a subnet router requires double opt-in, once from a subnet router and once on the control server to allow its use within the tailnet. Optionally, use autoApprovers to automatically approve routes from a subnet router.

    "},{"location":"ref/routes/#setup-a-subnet-router","title":"Setup a subnet router","text":""},{"location":"ref/routes/#configure-a-node-as-subnet-router","title":"Configure a node as subnet router","text":"

    Register a node and advertise the routes it should handle as comma separated list:

    $ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-routes=10.0.0.0/8,192.168.0.0/24\n

    If the node is already registered, it can advertise new routes or update previously announced routes with:

    $ sudo tailscale set --advertise-routes=10.0.0.0/8,192.168.0.0/24\n

    Finally, enable IP forwarding to route traffic.

    "},{"location":"ref/routes/#enable-the-subnet-router-on-the-control-server","title":"Enable the subnet router on the control server","text":"

    The routes of a tailnet can be displayed with the headscale nodes list-routes command. A subnet router with the hostname myrouter announced the IPv4 networks 10.0.0.0/8 and 192.168.0.0/24. Those need to be approved before they can be used.

    $ headscale nodes list-routes\nID | Hostname | Approved | Available      | Serving (Primary)\n1  | myrouter |          | 10.0.0.0/8     |\n   |          |          | 192.168.0.0/24 |\n

    Approve all desired routes of a subnet router by specifying them as comma separated list:

    $ headscale nodes approve-routes --identifier 1 --routes 10.0.0.0/8,192.168.0.0/24\nNode updated\n

    The node myrouter can now route the IPv4 networks 10.0.0.0/8 and 192.168.0.0/24 for the tailnet.

    $ headscale nodes list-routes\nID | Hostname | Approved       | Available      | Serving (Primary)\n1  | myrouter | 10.0.0.0/8     | 10.0.0.0/8     | 10.0.0.0/8\n   |          | 192.168.0.0/24 | 192.168.0.0/24 | 192.168.0.0/24\n
    "},{"location":"ref/routes/#use-the-subnet-router","title":"Use the subnet router","text":"

    To accept routes advertised by a subnet router on a node:

    $ sudo tailscale set --accept-routes\n

    Please refer to the official Tailscale documentation for how to use a subnet router on different operating systems.

    "},{"location":"ref/routes/#restrict-the-use-of-a-subnet-router-with-a-policy","title":"Restrict the use of a subnet router with a policy","text":"

    The routes announced by subnet routers are available to the nodes in a tailnet. By default, without a policy enabled, all nodes can accept and use such routes. Configure a policy to explicitly manage who can use routes.

    The policy snippet below defines three hosts, a subnet router router, a regular node node and service.example.net as internal service that can be reached via a route on the subnet router router. It allows the node node to access service.example.net on port 80 and 443 which is reachable via the subnet router. Access to the subnet router itself is denied.

    Access the routes of a subnet router without the subnet router itself
    {\n  \"hosts\": {\n    // the router is not referenced but announces 192.168.0.0/24\n    \"router\": \"100.64.0.1/32\",\n    \"node\": \"100.64.0.2/32\",\n    \"service.example.net\": \"192.168.0.1/32\"\n  },\n  \"grants\": [\n    {\n      \"src\": [\"node\"],\n      \"dst\": [\"service.example.net\"],\n      \"ip\": [\"80,443\"]\n    }\n  ]\n}\n
    "},{"location":"ref/routes/#automatically-approve-routes-of-a-subnet-router","title":"Automatically approve routes of a subnet router","text":"

    The initial setup of a subnet router usually requires manual approval of their announced routes on the control server before they can be used by a node in a tailnet. Headscale supports the autoApprovers section in a policy to automate the approval of routes served with a subnet router.

    The policy snippet below defines the tag tag:router owned by the user alice. This tag is used for routes in the autoApprovers section. The IPv4 route 192.168.0.0/24 is automatically approved once announced by a subnet router that advertises the tag tag:router.

    Subnet routers tagged with tag:router are automatically approved
    {\n  \"tagOwners\": {\n    \"tag:router\": [\"alice@\"]\n  },\n  \"autoApprovers\": {\n    \"routes\": {\n      \"192.168.0.0/24\": [\"tag:router\"]\n    }\n  },\n  \"grants\": [\n    // more rules\n  ]\n}\n

    Advertise the route 192.168.0.0/24 from a subnet router that also advertises the tag tag:router when joining the tailnet:

    $ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags tag:router --advertise-routes 192.168.0.0/24\n

    Please see the official Tailscale documentation for more information on auto approvers.

    "},{"location":"ref/routes/#exit-node","title":"Exit node","text":"

    The setup of an exit node requires double opt-in, once from an exit node and once on the control server to allow its use within the tailnet. Optionally, use autoApprovers to automatically approve an exit node.

    "},{"location":"ref/routes/#setup-an-exit-node","title":"Setup an exit node","text":""},{"location":"ref/routes/#configure-a-node-as-exit-node","title":"Configure a node as exit node","text":"

    Register a node and make it advertise itself as an exit node:

    $ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-exit-node\n

    If the node is already registered, it can advertise exit capabilities like this:

    $ sudo tailscale set --advertise-exit-node\n

    Finally, enable IP forwarding to route traffic.

    "},{"location":"ref/routes/#enable-the-exit-node-on-the-control-server","title":"Enable the exit node on the control server","text":"

    The routes of a tailnet can be displayed with the headscale nodes list-routes command. An exit node can be recognized by its announced routes: 0.0.0.0/0 for IPv4 and ::/0 for IPv6. The exit node with the hostname myexit is already available, but needs to be approved:

    $ headscale nodes list-routes\nID | Hostname | Approved | Available | Serving (Primary)\n1  | myexit   |          | 0.0.0.0/0 |\n   |          |          | ::/0      |\n

    For exit nodes, it is sufficient to approve either the IPv4 or IPv6 route. The other will be approved automatically.

    $ headscale nodes approve-routes --identifier 1 --routes 0.0.0.0/0\nNode updated\n

    The node myexit is now approved as exit node for the tailnet:

    $ headscale nodes list-routes\nID | Hostname | Approved  | Available | Serving (Primary)\n1  | myexit   | 0.0.0.0/0 | 0.0.0.0/0 | 0.0.0.0/0\n   |          | ::/0      | ::/0      | ::/0\n
    "},{"location":"ref/routes/#use-the-exit-node","title":"Use the exit node","text":"

    The exit node can now be used on a node with:

    $ sudo tailscale set --exit-node myexit\n

    Please refer to the official Tailscale documentation for how to use an exit node on different operating systems.

    "},{"location":"ref/routes/#restrict-the-use-of-an-exit-node-with-a-policy","title":"Restrict the use of an exit node with a policy","text":"

    An exit node is offered to all nodes in a tailnet. By default, without a policy enabled, all nodes in a tailnet can select and use an exit node. Configure autogroup:internet in a policy rule to restrict who can use any of the available exit nodes.

    Example use of autogroup:internet
    {\n  \"grants\": [\n    {\n      \"src\": [\"...\"],\n      \"dst\": [\"autogroup:internet\"],\n      \"ip\": [\"*\"]\n    }\n  ]\n}\n
    "},{"location":"ref/routes/#restrict-access-to-exit-nodes-per-user-or-group","title":"Restrict access to exit nodes per user or group","text":"

    A user can use any of the available exit nodes with autogroup:internet. Alternatively, the policy snippet below assigns each user a specific exit node while hiding all other exit nodes. The user alice can only use an exit node tagged with tag:exit1 while user bob can only use an exit node tagged with tag:exit2.

    Assign each user a dedicated exit node
    {\n  \"tagOwners\": {\n    \"tag:exit1\": [\"alice@\"],\n    \"tag:exit2\": [\"bob@\"]\n  },\n  \"grants\": [\n    {\n      \"src\": [\"alice@\"],\n      \"dst\": [\"autogroup:internet\"],\n      \"via\": [\"tag:exit1\"],\n      \"ip\": [\"*\"]\n    },\n    {\n      \"src\": [\"bob@\"],\n      \"dst\": [\"autogroup:internet\"],\n      \"via\": [\"tag:exit2\"],\n      \"ip\": [\"*\"]\n    }\n  ]\n}\n
    "},{"location":"ref/routes/#automatically-approve-an-exit-node-with-auto-approvers","title":"Automatically approve an exit node with auto approvers","text":"

    The initial setup of an exit node usually requires manual approval on the control server before it can be used by a node in a tailnet. Headscale supports the autoApprovers section in a policy to automate the approval of a new exit node as soon as it joins the tailnet.

    The policy snippet below defines the tag tag:exit owned by the user alice. This tag is used for the exitNode entry in the autoApprovers section. A new exit node that advertises the tag tag:exit is automatically approved:

    Exit nodes tagged with tag:exit are automatically approved
    {\n  \"tagOwners\": {\n    \"tag:exit\": [\"alice@\"]\n  },\n  \"autoApprovers\": {\n    \"exitNode\": [\"tag:exit\"]\n  },\n  \"grants\": [\n    // more rules\n  ]\n}\n

    Advertise a node as exit node and also advertise the tag tag:exit when joining the tailnet:

    $ sudo tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags tag:exit --advertise-exit-node\n

    Please see the official Tailscale documentation for more information on auto approvers.

    "},{"location":"ref/routes/#automatic-exit-node-selection","title":"Automatic exit node selection","text":"

    A Tailscale client can be configured to select one of the available exit nodes automatically. This may be useful when there are multiple exit nodes available and clients should use an exit node without requiring a user to manually switch between them.

    The policy snippet below defines the tag tag:exit for exit nodes. Exit nodes with that tag are suggested to clients with the suggest-exit-node node attribute. Additionally, GUI clients should display the \"Recommended\" exit node selector.

    Automatic exit node selection
    {\n  \"tagOwners\": {\n    \"tag:exit\": [\"infra@\"]\n  },\n  \"nodeAttrs\": [\n    {\n      // Suggest exit nodes tagged with tag:exit\n      \"target\": [\"tag:exit\"],\n      \"attr\": [\"suggest-exit-node\"]\n    },\n    {\n      // Show \"recommended\" exit node selector in GUIs\n      \"target\": [\"*\"],\n      \"attr\": [\"suggest-exit-node-ui\"]\n    }\n  ],\n  \"grants\": [\n    {\n      \"src\": [\"...\"],\n      \"dst\": [\"autogroup:internet\"],\n      \"ip\": [\"*\"]\n    }\n  ]\n}\n

    The Tailscale client can suggest a viable exit node with:

    $ sudo tailscale exit-node suggest\n

    or automatically select one by using auto:any as exit node identifier:

    $ sudo tailscale set --exit-node=auto:any\n

    Please see the official Tailscale documentation for more information on automatic exit node selection.

    "},{"location":"ref/routes/#high-availability","title":"High availability","text":"

    Headscale supports high availability routing. Multiple subnet routers with overlapping routes or multiple exit nodes can be used to provide high availability for users. If one router node goes offline, another one can serve the same routes to clients. Please see the official Tailscale documentation on high availability for details.

    This feature is enabled by default when at least two nodes advertise the same prefix. See the configuration options node.routes.ha in the configuration file for details.

    "},{"location":"ref/routes/#troubleshooting","title":"Troubleshooting","text":""},{"location":"ref/routes/#enable-ip-forwarding","title":"Enable IP forwarding","text":"

    A subnet router or exit node is routing traffic on behalf of other nodes and thus requires IP forwarding. Check the official Tailscale documentation for how to enable IP forwarding.

    "},{"location":"ref/tags/","title":"Tags","text":"

    Headscale supports Tailscale tags. Please read Tailscale's tag documentation to learn how tags work and how to use them.

    Tags can be applied during node registration:

    Administrators can manage tags with:

    "},{"location":"ref/tags/#common-operations","title":"Common operations","text":""},{"location":"ref/tags/#manage-tags-for-a-node","title":"Manage tags for a node","text":"

    Run headscale nodes list to list the tags for a node.

    Use the headscale nodes tag command to modify the tags for a node. At least one tag is required and multiple tags can be provided as comma separated list. The following command sets the tags tag:server and tag:prod on node with ID 1:

    headscale nodes tag -i 1 -t tag:server,tag:prod\n
    "},{"location":"ref/tags/#convert-from-personal-to-tagged-node","title":"Convert from personal to tagged node","text":"

    Use the headscale nodes tag command to convert a personal (user-owned) node to a tagged node:

    headscale nodes tag -i <NODE_ID> -t <TAG>\n

    The node is now owned by the special user tagged-devices and has the specified tags assigned to it.

    "},{"location":"ref/tags/#convert-from-tagged-to-personal-node","title":"Convert from tagged to personal node","text":"

    Tagged nodes can return to personal (user-owned) nodes by re-authenticating with:

    tailscale up --login-server <YOUR_HEADSCALE_URL> --advertise-tags= --force-reauth\n

    Usually, a browser window with further instructions is opened. This page explains how to complete the registration on your Headscale server and it also prints the Auth ID required to approve the node:

    headscale auth register --user <USER> --auth-id <AUTH_ID>\n

    All previously assigned tags get removed and the node is now owned by the user specified in the above command.

    "},{"location":"ref/tls/","title":"Running the service via TLS (optional)","text":""},{"location":"ref/tls/#bring-your-own-certificate","title":"Bring your own certificate","text":"

    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_key_path configuration parameters. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.

    config.yaml
    tls_cert_path: \"\"\ntls_key_path: \"\"\n

    The certificate should contain the full chain, else some clients, like the Tailscale Android client, will reject it.

    "},{"location":"ref/tls/#lets-encrypt-acme","title":"Let's Encrypt / ACME","text":"

    To get a certificate automatically via Let's Encrypt, 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.

    config.yaml
    tls_letsencrypt_hostname: \"\"\ntls_letsencrypt_listen: \":http\"\ntls_letsencrypt_cache_dir: \".cache\"\ntls_letsencrypt_challenge_type: HTTP-01\n
    "},{"location":"ref/tls/#challenge-types","title":"Challenge types","text":"

    Headscale only supports two values for tls_letsencrypt_challenge_type: HTTP-01 (default) and TLS-ALPN-01.

    "},{"location":"ref/tls/#http-01","title":"HTTP-01","text":"

    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.

    listen_addr cannot also be port 80

    listen_addr and tls_letsencrypt_listen must not bind the same TCP socket. A common mistake is setting listen_addr: 0.0.0.0:80 together with tls_letsencrypt_hostname \u2014 both endpoints try to claim port 80, and the second bind fails with address already in use even though no other process is involved. Headscale validates this at startup and refuses to launch with a Fatal config error: listen_addr and tls_letsencrypt_listen would bind the same TCP socket message. Use listen_addr: 0.0.0.0:443 (or any non-80 port) when HTTP-01 is enabled.

    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.

    "},{"location":"ref/tls/#tls-alpn-01","title":"TLS-ALPN-01","text":"

    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.

    "},{"location":"ref/tls/#technical-description","title":"Technical description","text":"

    Headscale uses autocert, a Golang library providing ACME protocol verification, to facilitate certificate renewals via Let's Encrypt. Certificates will be renewed automatically, and the following can be expected:

    "},{"location":"ref/tls/#checking-certificate-expiry","title":"Checking certificate expiry","text":"

    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:
    $ openssl s_client -servername [hostname] -connect [hostname]:443 | openssl x509 -noout -dates\n(...)\nnotBefore=Feb  8 09:48:26 2024 GMT\nnotAfter=May  8 09:48:25 2024 GMT\n
    "},{"location":"ref/tls/#log-output-from-the-autocert-library","title":"Log output from the autocert library","text":"

    As these log lines are from the autocert library, they are not strictly generated by headscale itself.

    acme/autocert: missing server name\n

    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.

    acme/autocert: host \"[foo]\" not configured in HostWhitelist\n

    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

    "},{"location":"ref/integration/reverse-proxy/","title":"Running Headscale behind a reverse proxy","text":"

    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.

    Please see limitations for known issues and limitations.

    "},{"location":"ref/integration/reverse-proxy/#configuration","title":"Configuration","text":"

    The configuration depends on the set of Headscale features you intend to use. Please have a look at the requirements and especially the ports in use section to learn what a Tailscale clients expects.

    The configuration examples in this documentation are basic and cover only HTTP and HTTPS traffic. Other features such as STUN for Headscale's embedded DERP server are expected to be exposed directly or to be only available on localhost.

    "},{"location":"ref/integration/reverse-proxy/#websocket","title":"WebSocket","text":"

    Tailscale clients are using a custom protocol (Tailscale Control Protocol) to communicate with a control server such as Headscale. The reverse proxy must be configured to support WebSockets in order to communicate with Tailscale clients and it needs to handle two peculiarities of the Tailscale Control Protocol:

    "},{"location":"ref/integration/reverse-proxy/#tls","title":"TLS","text":"

    Headscale can be configured not to use TLS, leaving it to the reverse proxy to handle. Add the following configuration values to your Headscale configuration file:

    config.yaml
    server_url: https://<SERVER_NAME>\ntls_cert_path: \"\"\ntls_key_path: \"\"\n

    Headscale logs WRN listening without TLS but ServerURL does not start with http:// during startup. This is expected and indicates that the reverse proxy is in charge of terminating TLS.

    "},{"location":"ref/integration/reverse-proxy/#trusted-proxies","title":"Trusted proxies","text":"

    Headscale ignores True-Client-IP, X-Real-IP and X-Forwarded-For headers unless the request's TCP peer matches the trusted_proxies configuration option. Set this to the CIDR(s) your reverse proxy connects from so the real client IP appears in access logs.

    config.yaml
    trusted_proxies:\n  - 127.0.0.1/32\n  - ::1/128\n

    The reverse proxy is responsible to replace any client-supplied True-Client-IP, X-Real-IP, X-Forwarded-For headers on inbound requests with sanitized values. Headscale picks the first valid IP address supplied by headers in this order:

    "},{"location":"ref/integration/reverse-proxy/#limitations","title":"Limitations","text":""},{"location":"ref/integration/reverse-proxy/#reverse-proxy-specific-configuration","title":"Reverse proxy specific configuration","text":"

    Third-party software and services

    This section of the documentation is specific for third-party software and services. We recommend users read the third-party documentation for a secure configuration.

    This following Headscale configuration may be used as base for the various reverse proxy examples below. The following is assumed:

    config.yaml
    server_url: https://<SERVER_NAME>\nlisten_addr: 127.0.0.1:8080\nmetrics_listen_addr: 127.0.0.1:9090\ntrusted_proxies:\n  - 127.0.0.1/32\n  - ::1/128\ntls_cert_path: \"\"\ntls_key_path: \"\"\n
    "},{"location":"ref/integration/reverse-proxy/#apache","title":"Apache","text":"

    The following basic Apache configuration works with the Headscale configuration as shown above. Substitute placeholders and adjust the configuration as needed:

    apache.conf
    <VirtualHost *:80>\n  ServerName <SERVER_NAME>\n\n  # Tailscale captive portal detection\n  RedirectMatch 204 ^/generate_204$\n\n  RedirectMatch permanent \"^/(.*)$\" \"https://<SERVER_NAME>/$1\"\n</VirtualHost>\n\n<VirtualHost *:443>\n  ServerName <SERVER_NAME>\n\n  SSLEngine On\n  SSLCertificateFile <PATH_TO_TLS_CERT>\n  SSLCertificateKeyFile <PATH_TO_TLS_KEY>\n\n  RequestHeader set True-Client-IP \"%{REMOTE_ADDR}s\"\n  RequestHeader set X-Real-IP \"%{REMOTE_ADDR}s\"\n\n  ProxyPreserveHost On\n  ProxyPass / http://127.0.0.1:8080/ upgrade=any\n</VirtualHost>\n

    Note that upgrade=any is required as a parameter for ProxyPass so that WebSocket traffic whose Upgrade header value is not equal to WebSocket (i. e. Tailscale Control Protocol) is forwarded correctly. See the Apache docs for more information on this.

    "},{"location":"ref/integration/reverse-proxy/#caddy","title":"Caddy","text":"

    The following basic Caddyfile works with the Headscale configuration as shown above. Substitute placeholders and adjust the configuration as needed:

    Caddyfile
    http://<SERVER_NAME> {\n    # Tailscale captive portal detection\n    handle /generate_204 {\n        respond 204\n    }\n\n    handle * {\n        redir https://{host}{uri}\n    }\n}\n\n<SERVER_NAME> {\n    reverse_proxy 127.0.0.1:8080 {\n        header_up True-Client-IP {remote_host}\n        header_up X-Real-IP {remote_host}\n    }\n}\n

    Caddy will automatically provision a certificate for your domain/subdomain, force HTTPS, and proxy WebSocket connections.

    "},{"location":"ref/integration/reverse-proxy/#cloudflare","title":"Cloudflare","text":"

    Running Headscale behind a Cloudflare Proxy or Cloudflare Tunnel is not supported and will not work as Cloudflare does not support WebSocket POSTs as required by the Tailscale protocol. See issue 1468 for more information.

    "},{"location":"ref/integration/reverse-proxy/#envoy","title":"Envoy","text":"

    You need to add a new upgrade_type named tailscale-control-protocol. See details.

    "},{"location":"ref/integration/reverse-proxy/#istio","title":"Istio","text":"

    Same as envoy, we can use EnvoyFilter to add a new upgrade_type named tailscale-control-protocol.

    apiVersion: networking.istio.io/v1alpha3\nkind: EnvoyFilter\nmetadata:\n  name: headscale-behind-istio-ingress\n  namespace: istio-system\nspec:\n  configPatches:\n    - applyTo: NETWORK_FILTER\n      match:\n        listener:\n          filterChain:\n            filter:\n              name: envoy.filters.network.http_connection_manager\n      patch:\n        operation: MERGE\n        value:\n          typed_config:\n            \"@type\": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager\n            upgrade_configs:\n              - upgrade_type: tailscale-control-protocol\n
    "},{"location":"ref/integration/reverse-proxy/#nginx","title":"Nginx","text":"

    The following basic Nginx configuration works with the Headscale configuration as shown above. Substitute placeholders and adjust the configuration as needed:

    nginx.conf
    # headscale\nupstream headscale {\n  zone upstreams 64K;\n  server 127.0.0.1:8080 max_fails=1 fail_timeout=5s;\n  keepalive 2;\n}\n\n# websocket\nmap $http_upgrade $connection_upgrade {\n  default keep-alive;\n  ''      close;\n}\n\n# http\nserver {\n  listen 80;\n  listen [::]:80;\n\n  server_name <SERVER_NAME>;\n\n  # Tailscale captive portal detection\n  location = /generate_204 {\n    return 204;\n  }\n\n  location / {\n    return 301 https://$server_name$request_uri;\n  }\n}\n\n# https\nserver {\n  listen 443 ssl;\n  listen [::]:443 ssl;\n  http2 on;\n\n  server_name <SERVER_NAME>;\n\n  ssl_certificate <PATH_TO_TLS_CERT>;\n  ssl_certificate_key <PATH_TO_TLS_KEY>;\n\n  location / {\n    proxy_http_version 1.1;\n    proxy_set_header Upgrade $http_upgrade;\n    proxy_set_header Connection $connection_upgrade;\n    proxy_set_header Host $host;\n    proxy_set_header True-Client-IP $remote_addr;\n    proxy_set_header X-Real-IP $remote_addr;\n    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n    proxy_set_header X-Forwarded-Proto $scheme;\n    proxy_buffering off;\n    proxy_pass http://headscale;\n  }\n}\n
    "},{"location":"ref/integration/tools/","title":"Tools related to headscale","text":"

    Community contributions

    This page contains community contributions. The projects listed here are not maintained by the headscale authors and are written by community members.

    This page collects third-party tools, client libraries, and scripts related to headscale.

    "},{"location":"ref/integration/web-ui/","title":"Web interfaces for headscale","text":"

    Community contributions

    This page contains community contributions. The projects listed here are not maintained by the headscale authors and are written by community members.

    Headscale doesn't provide a built-in web interface but users may pick one from the available options.

    You can ask for support on our Discord server in the \"web-interfaces\" channel.

    "},{"location":"setup/requirements/","title":"Requirements","text":"

    Headscale should just work as long as the following requirements are met:

    "},{"location":"setup/requirements/#ports-in-use","title":"Ports in use","text":"

    The ports in use vary with the intended scenario and enabled features. Some of the listed ports may be changed via the configuration file but we recommend to stick with the default values.

    "},{"location":"setup/requirements/#assumptions","title":"Assumptions","text":"

    The headscale documentation and the provided examples are written with a few assumptions in mind:

    Please adjust to your local environment accordingly.

    1. The Tailscale client assumes HTTPS on port 443 in certain situations. Serving headscale either via HTTP or via HTTPS on a port other than 443 is possible but sticking with HTTPS on port 443 is strongly recommended for production setups. See issue 2164 for more information.\u00a0\u21a9\u21a9

    "},{"location":"setup/upgrade/","title":"Upgrade an existing installation","text":"

    Required update path

    It's required to update from one stable version to the next (e.g. 0.26.0 \u2192 0.27.1 \u2192 0.28.0) without skipping minor versions in between. You should always pick the latest available patch release.

    Update an existing Headscale installation to a new version:

    "},{"location":"setup/upgrade/#backup","title":"Backup","text":"

    Headscale applies database migrations during upgrades and we highly recommend to create a backup of your database before upgrading. A full backup of Headscale depends on your individual setup, but below are some typical setup scenarios.

    Standard installationContainerPostgreSQL

    An installation that follows our official releases setup guide uses the following paths:

    TIMESTAMP=$(date +%Y%m%d%H%M%S)\ncp -aR /etc/headscale /etc/headscale.backup-$TIMESTAMP\ncp -aR /var/lib/headscale /var/lib/headscale.backup-$TIMESTAMP\n

    An installation that follows our container setup guide uses a single source volume directory that contains the configuration file, data directory and the SQLite database.

    cp -aR /path/to/headscale /path/to/headscale.backup-$(date +%Y%m%d%H%M%S)\n

    Please follow PostgreSQL's Backup and Restore documentation to create a backup of your PostgreSQL database.

    "},{"location":"setup/install/community/","title":"Community packages","text":"

    Several Linux distributions and community members provide packages for headscale. Those packages may be used instead of the official releases provided by the headscale maintainers. Such packages offer improved integration for their targeted operating system and usually:

    Community packages might be outdated

    The packages mentioned on this page might be outdated or unmaintained. Use the official releases to get the current stable version or to test pre-releases.

    "},{"location":"setup/install/community/#arch-linux","title":"Arch Linux","text":"

    Arch Linux offers a package for headscale, install via:

    pacman -S headscale\n
    "},{"location":"setup/install/community/#fedora-rhel-centos","title":"Fedora, RHEL, CentOS","text":"

    A third-party repository for various RPM based distributions is available at: https://copr.fedorainfracloud.org/coprs/jonathanspw/headscale/. The site provides detailed setup and installation instructions.

    "},{"location":"setup/install/community/#nix-nixos","title":"Nix, NixOS","text":"

    A Nix package is available as: headscale. See the NixOS package site for installation details.

    "},{"location":"setup/install/community/#gentoo","title":"Gentoo","text":"
    emerge --ask net-vpn/headscale\n

    Gentoo specific documentation is available here.

    "},{"location":"setup/install/community/#openbsd","title":"OpenBSD","text":"

    Headscale is available in ports. The port installs headscale as system service with rc.d and provides usage instructions upon installation.

    pkg_add headscale\n
    "},{"location":"setup/install/container/","title":"Running headscale in a container","text":"

    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.

    A container runtime such as Docker or Podman is required. The container image can be found on Docker Hub and GitHub Container Registry. The container image URLs are:

    "},{"location":"setup/install/container/#configure-and-run-headscale","title":"Configure and run headscale","text":"

    1. Create a directory on the container host to store headscale's configuration and the SQLite database:

      mkdir -p ./headscale/{config,lib}\ncd ./headscale\n

    2. Download the example configuration for your chosen version and save it as: $(pwd)/config/config.yaml. Adjust the configuration to suit your local environment. See Configuration for details.

    3. Start headscale from within the previously created ./headscale directory:

      docker run \\\n  --name headscale \\\n  --detach \\\n  --read-only \\\n  --tmpfs /tmp \\\n  --tmpfs /var/run/headscale \\\n  --volume \"$(pwd)/config:/etc/headscale:ro\" \\\n  --volume \"$(pwd)/lib:/var/lib/headscale\" \\\n  --publish 127.0.0.1:8080:8080 \\\n  --publish 127.0.0.1:9090:9090 \\\n  --health-cmd \"CMD headscale health\" \\\n  docker.io/headscale/headscale:<VERSION> \\\n  serve\n

      Note: use 0.0.0.0:8080:8080 instead of 127.0.0.1:8080:8080 if you want to expose the container externally.

      This command mounts the local directories inside the container, forwards port 8080 and 9090 out of the container so the headscale instance becomes available and then detaches so headscale runs in the background.

      A similar configuration for docker-compose:

      docker-compose.yaml
      services:\n  headscale:\n    image: docker.io/headscale/headscale:<VERSION>\n    restart: unless-stopped\n    container_name: headscale\n    read_only: true\n    tmpfs:\n      - /var/run/headscale\n    ports:\n      - \"127.0.0.1:8080:8080\"\n      - \"127.0.0.1:9090:9090\"\n    volumes:\n      # Please set <HEADSCALE_PATH> to the absolute path\n      # of the previously created headscale directory.\n      - <HEADSCALE_PATH>/config:/etc/headscale:ro\n      - <HEADSCALE_PATH>/lib:/var/lib/headscale\n    command: serve\n    healthcheck:\n        test: [\"CMD\", \"headscale\", \"health\"]\n

    4. Verify headscale is running:

      Follow the container logs:

      docker logs --follow headscale\n

      Verify running containers:

      docker ps\n

      Verify headscale is available:

      curl http://127.0.0.1:8080/health\n

    Continue on the getting started page to register your first machine.

    "},{"location":"setup/install/container/#debugging-headscale-running-in-docker","title":"Debugging headscale running in Docker","text":"

    The Headscale container image is based on a distroless image that does not contain a shell or any other debug tools. If you need to debug headscale running in the Docker container, you can use the -debug variant, for example docker.io/headscale/headscale:x.x.x-debug.

    "},{"location":"setup/install/container/#running-the-debug-docker-container","title":"Running the debug Docker container","text":"

    To run the debug Docker container, use the exact same commands as above, but replace docker.io/headscale/headscale:x.x.x with docker.io/headscale/headscale:x.x.x-debug (x.x.x is the version of headscale). The two containers are compatible with each other, so you can alternate between them.

    "},{"location":"setup/install/container/#executing-commands-in-the-debug-container","title":"Executing commands in the debug container","text":"

    The default command in the debug container is to run headscale, which is located at /ko-app/headscale inside the container.

    Additionally, the debug container includes a minimalist Busybox shell.

    To launch a shell in the container, use:

    docker run -it docker.io/headscale/headscale:x.x.x-debug sh\n

    You can also execute commands directly, such as ls /ko-app in this example:

    docker run docker.io/headscale/headscale:x.x.x-debug ls /ko-app\n

    Using docker exec -it allows you to run commands in an existing container.

    "},{"location":"setup/install/main/","title":"Development builds","text":"

    Warning

    Development builds are created automatically from the latest main branch and are not versioned releases. They may contain incomplete features, breaking changes, or bugs. Use them for testing only.

    Each push to main produces container images and cross-compiled binaries. Container images are multi-arch (amd64, arm64) and use the same distroless base image as official releases.

    "},{"location":"setup/install/main/#container-images","title":"Container images","text":"

    Images are available from both Docker Hub and GitHub Container Registry, tagged with the short commit hash of the build (e.g. main-abc1234):

    To find the latest available tag, check the GitHub Actions workflow or the GitHub Container Registry package page.

    For example, to run a specific development build:

    docker run \\\n  --name headscale \\\n  --detach \\\n  --read-only \\\n  --tmpfs /tmp \\\n  --tmpfs /var/run/headscale \\\n  --volume \"$(pwd)/config:/etc/headscale:ro\" \\\n  --volume \"$(pwd)/lib:/var/lib/headscale\" \\\n  --publish 127.0.0.1:8080:8080 \\\n  --publish 127.0.0.1:9090:9090 \\\n  --health-cmd \"CMD headscale health\" \\\n  docker.io/headscale/headscale:main-<sha> \\\n  serve\n

    See Running headscale in a container for full container setup instructions.

    "},{"location":"setup/install/main/#binaries","title":"Binaries","text":"

    Pre-built binaries from the latest successful build on main are available via nightly.link:

    OS Arch Download Linux amd64 headscale-linux-amd64 Linux arm64 headscale-linux-arm64 macOS amd64 headscale-darwin-amd64 macOS arm64 headscale-darwin-arm64

    After downloading and extracting the archive, make the binary executable and follow the standalone binary installation instructions for setting up the service.

    "},{"location":"setup/install/official/","title":"Official releases","text":"

    Official releases for headscale are available as binaries for various platforms and DEB packages for Debian and Ubuntu. Both are available on the GitHub releases page.

    "},{"location":"setup/install/official/#using-packages-for-debianubuntu-recommended","title":"Using packages for Debian/Ubuntu (recommended)","text":"

    It is recommended to use our DEB packages to install headscale on a Debian based system as those packages configure a local user to run headscale, provide a default configuration and ship with a systemd service file. Supported distributions are Ubuntu 22.04 or newer, Debian 12 or newer.

    1. Download the latest headscale package for your platform (.deb for Ubuntu and Debian).

      HEADSCALE_VERSION=\"\" # See above URL for latest version, e.g. \"X.Y.Z\" (NOTE: do not add the \"v\" prefix!)\nHEADSCALE_ARCH=\"\" # Your system architecture, e.g. \"amd64\"\nwget --output-document=headscale.deb \\\n \"https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb\"\n

    2. Install headscale:

      sudo apt install ./headscale.deb\n

    3. Configure headscale by editing the configuration file. An up-to date example configuration file is also available in /usr/share/doc/headscale/examples/config-example.yaml:

      sudo nano /etc/headscale/config.yaml\n

    4. Restart headscale to pick up configuration changes:

      sudo systemctl restart headscale\n

    5. Verify that headscale is running as intended:

      sudo systemctl status headscale\n

    Continue on the getting started page to register your first machine.

    "},{"location":"setup/install/official/#using-standalone-binaries-advanced","title":"Using standalone binaries (advanced)","text":"

    Advanced

    This installation method is considered advanced as one needs to take care of the local user and the systemd service themselves. If possible, use the DEB packages or a community package instead.

    This section describes the installation of headscale according to the Requirements and assumptions. Headscale is run by a dedicated local user and the service itself is managed by systemd.

    1. Download the latest headscale binary from GitHub's release page:

      sudo wget --output-document=/usr/bin/headscale \\\nhttps://github.com/juanfont/headscale/releases/download/v<HEADSCALE VERSION>/headscale_<HEADSCALE VERSION>_linux_<ARCH>\n

    2. Make headscale executable:

      sudo chmod +x /usr/bin/headscale\n

    3. Add a dedicated local user to run headscale:

      sudo useradd \\\n --create-home \\\n --home-dir /var/lib/headscale/ \\\n --system \\\n --user-group \\\n --shell /usr/sbin/nologin \\\n headscale\n

    4. Download the example configuration for your chosen version and save it as: /etc/headscale/config.yaml. Adjust the configuration to suit your local environment. See Configuration for details.

      sudo mkdir -p /etc/headscale\nsudo nano /etc/headscale/config.yaml\n

    5. Copy headscale's systemd service file to /etc/systemd/system/headscale.service and adjust it to suit your local setup. The following parameters likely need to be modified: ExecStart, WorkingDirectory, ReadWritePaths.

    6. In /etc/headscale/config.yaml, override the default headscale unix socket with a path that is writable by the headscale user or group:

      config.yaml
      unix_socket: /var/run/headscale/headscale.sock\n

    7. Reload systemd to load the new configuration file:

      systemctl daemon-reload\n

    8. Enable and start the new headscale service:

      systemctl enable --now headscale\n

    9. Verify that headscale is running as intended:

      systemctl status headscale\n

    Continue on the getting started page to register your first machine.

    "},{"location":"setup/install/source/","title":"Build from source","text":"

    Community documentation

    This page is not actively maintained by the headscale authors and is written by community members. It is not verified by headscale developers.

    It might be outdated and it might miss necessary steps.

    Headscale can be built from source using the latest version of Go and Buf (Protobuf generator). See the Contributing section in the GitHub README for more information.

    "},{"location":"setup/install/source/#openbsd","title":"OpenBSD","text":""},{"location":"setup/install/source/#install-from-source","title":"Install from source","text":"
    # Install prerequisites\npkg_add go git\n\ngit clone https://github.com/juanfont/headscale.git\n\ncd headscale\n\n# optionally checkout a release\n# option a. you can find official release at https://github.com/juanfont/headscale/releases/latest\n# option b. get latest tag, this may be a beta release\nlatestTag=$(git describe --tags `git rev-list --tags --max-count=1`)\n\ngit checkout $latestTag\n\ngo build -ldflags=\"-s -w -X github.com/juanfont/headscale/hscontrol/types.Version=$latestTag\" -X github.com/juanfont/headscale/hscontrol/types.GitCommitHash=HASH\" github.com/juanfont/headscale\n\n# make it executable\nchmod a+x headscale\n\n# copy it to /usr/local/sbin\ncp headscale /usr/local/sbin\n
    "},{"location":"setup/install/source/#install-from-source-via-cross-compile","title":"Install from source via cross compile","text":"
    # Install prerequisites\n# 1. go v1.27+: see the go directive in go.mod for the exact minimum\n# 2. gmake: Makefile in the headscale repo is written in GNU make syntax\n\ngit clone https://github.com/juanfont/headscale.git\n\ncd headscale\n\n# optionally checkout a release\n# option a. you can find official release at https://github.com/juanfont/headscale/releases/latest\n# option b. get latest tag, this may be a beta release\nlatestTag=$(git describe --tags `git rev-list --tags --max-count=1`)\n\ngit checkout $latestTag\n\nmake build GOOS=openbsd\n\n# copy headscale to openbsd machine and put it in /usr/local/sbin\n
    "},{"location":"usage/getting-started/","title":"Getting started","text":"

    This page helps you get started with headscale and provides a few usage examples for the headscale command line tool headscale.

    Prerequisites

    "},{"location":"usage/getting-started/#getting-help","title":"Getting help","text":"

    The headscale command line tool provides built-in help. To show available commands along with their arguments and options, run:

    NativeContainer 
    # Show help\nheadscale help\n\n# Show help for a specific command\nheadscale <COMMAND> --help\n
    # Show help\ndocker exec -it headscale \\\n  headscale help\n\n# Show help for a specific command\ndocker exec -it headscale \\\n  headscale <COMMAND> --help\n

    Manage headscale from another local user

    By default only the user headscale or root will have the necessary permissions to access the unix socket (/var/run/headscale/headscale.sock) that is used to communicate with the service. In order to be able to communicate with the headscale service you have to make sure the unix socket is accessible by the user that runs the commands. In general you can achieve this by any of the following methods:

    To verify you can run the following command using your preferred method:

    headscale users list\n
    "},{"location":"usage/getting-started/#manage-headscale-users","title":"Manage headscale users","text":"

    In headscale, a node (also known as machine or device) is typically assigned to a headscale user. Such a headscale user1 may have many nodes assigned to them and can be managed with the headscale users command. Invoke the built-in help for more information: headscale users --help.

    "},{"location":"usage/getting-started/#create-a-headscale-user","title":"Create a headscale user","text":"NativeContainer 
    headscale users create <USER>\n
    docker exec -it headscale \\\n  headscale users create <USER>\n
    "},{"location":"usage/getting-started/#list-existing-headscale-users","title":"List existing headscale users","text":"NativeContainer 
    headscale users list\n
    docker exec -it headscale \\\n  headscale users list\n
    "},{"location":"usage/getting-started/#register-a-node","title":"Register a node","text":"

    One has to register a node first to use headscale as coordination server with Tailscale. The following examples work for the Tailscale client on Linux/BSD operating systems. Alternatively, follow the instructions to connect Android, Apple or Windows devices. Read registration methods for an overview of available registration methods.

    "},{"location":"usage/getting-started/#web-authentication","title":"Web authentication","text":"

    On a client machine, run the tailscale up command and provide the FQDN of your headscale instance as argument:

    tailscale up --login-server <YOUR_HEADSCALE_URL>\n

    Usually, a browser window with further instructions is opened. This page explains how to complete the registration on your headscale server and it also prints the Auth ID required to approve the node:

    NativeContainer 
    headscale auth register --user <USER> --auth-id <AUTH_ID>\n
    docker exec -it headscale \\\n  headscale auth register --user <USER> --auth-id <AUTH_ID>\n
    "},{"location":"usage/getting-started/#pre-authenticated-key","title":"Pre authenticated key","text":"

    It is also possible to generate a preauthkey and register a node non-interactively. First, generate a preauthkey on the headscale instance. By default, the key is valid for one hour and can only be used once (see headscale preauthkeys --help for other options):

    NativeContainer 
    headscale preauthkeys create --user <USER>\n
    docker exec -it headscale \\\n  headscale preauthkeys create --user <USER>\n

    The command returns the preauthkey on success which is used to connect a node to the headscale instance via the tailscale up command:

    tailscale up --login-server <YOUR_HEADSCALE_URL> --authkey <YOUR_AUTH_KEY>\n

    1. Ensure that the Headscale username does not end with @. \u21a9

    "},{"location":"usage/connect/android/","title":"Connecting an Android client","text":"

    This documentation has the goal of showing how a user can use the official Android Tailscale client with headscale.

    "},{"location":"usage/connect/android/#installation","title":"Installation","text":"

    Install the official Tailscale Android client from the Google Play Store or F-Droid.

    "},{"location":"usage/connect/android/#connect-via-web-authentication","title":"Connect via web authentication","text":""},{"location":"usage/connect/android/#connect-using-a-pre-authenticated-key","title":"Connect using a pre authenticated key","text":""},{"location":"usage/connect/apple/","title":"Connecting an Apple client","text":"

    This documentation has the goal of showing how a user can use the official iOS and macOS Tailscale clients with headscale.

    Instructions on your headscale instance

    An endpoint with information on how to connect your Apple device is also available at /apple on your running instance.

    "},{"location":"usage/connect/apple/#ios","title":"iOS","text":""},{"location":"usage/connect/apple/#installation","title":"Installation","text":"

    Install the official Tailscale iOS client from the App Store.

    "},{"location":"usage/connect/apple/#configuring-the-headscale-url","title":"Configuring the headscale URL","text":""},{"location":"usage/connect/apple/#macos","title":"macOS","text":""},{"location":"usage/connect/apple/#installation_1","title":"Installation","text":"

    Choose one of the available Tailscale clients for macOS and install it.

    "},{"location":"usage/connect/apple/#configuring-the-headscale-url_1","title":"Configuring the headscale URL","text":""},{"location":"usage/connect/apple/#command-line","title":"Command line","text":"

    Use Tailscale's login command to connect with your headscale instance (e.g https://headscale.example.com):

    tailscale login --login-server <YOUR_HEADSCALE_URL>\n
    "},{"location":"usage/connect/apple/#gui","title":"GUI","text":""},{"location":"usage/connect/apple/#tvos","title":"tvOS","text":""},{"location":"usage/connect/apple/#installation_2","title":"Installation","text":"

    Install the official Tailscale tvOS client from the App Store.

    Danger

    Don't sign in to the Tailscale App before the headscale URL is configured!

    "},{"location":"usage/connect/apple/#configuring-the-headscale-url_2","title":"Configuring the headscale URL","text":""},{"location":"usage/connect/windows/","title":"Connecting a Windows client","text":"

    This documentation has the goal of showing how a user can use the official Windows Tailscale client with headscale.

    Instructions on your headscale instance

    An endpoint with information on how to connect your Windows device is also available at /windows on your running instance.

    "},{"location":"usage/connect/windows/#installation","title":"Installation","text":"

    Download the Official Windows Client and install it.

    "},{"location":"usage/connect/windows/#configuring-the-headscale-url","title":"Configuring the headscale URL","text":"

    Open a Command Prompt or Powershell and use Tailscale's login command to connect with your headscale instance (e.g https://headscale.example.com):

    tailscale login --login-server <YOUR_HEADSCALE_URL>\n

    Follow the instructions in the opened browser window to finish the configuration.

    "},{"location":"usage/connect/windows/#troubleshooting","title":"Troubleshooting","text":""},{"location":"usage/connect/windows/#unattended-mode","title":"Unattended mode","text":"

    By default, Tailscale's Windows client is only running when the user is logged in. If you want to keep Tailscale running all the time, please enable \"Unattended mode\":

    See also Keep Tailscale running when I'm not logged in to my computer.

    "},{"location":"usage/connect/windows/#failing-node-registration","title":"Failing node registration","text":"

    If you are seeing repeated messages like:

    [GIN] 2022/02/10 - 16:39:34 | 200 |    1.105306ms |       127.0.0.1 | POST     \"/machine/redacted\"\n

    in your headscale output, turn on DEBUG logging and look for:

    2022-02-11T00:59:29Z DBG Machine registration has expired. Sending a authurl to register machine=redacted\n

    This typically means that the registry keys above was not set appropriately.

    To reset and try again, it is important to do the following:

    1. Shut down the Tailscale service (or the client running in the tray)
    2. Delete Tailscale Application data folder, located at C:\\Users\\<USERNAME>\\AppData\\Local\\Tailscale and try to connect again.
    3. Ensure the Windows node is deleted from headscale (to ensure fresh setup)
    4. Start Tailscale on the Windows machine and retry the login.
    "}]} \ No newline at end of file diff --git a/development/sitemap.xml b/development/sitemap.xml index 324df1261..2737c8b93 100644 --- a/development/sitemap.xml +++ b/development/sitemap.xml @@ -2,167 +2,167 @@ https://juanfont.github.io/headscale/development/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/about/clients/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/about/contributing/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/about/faq/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/about/features/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/about/help/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/about/releases/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/about/sponsor/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/ref/api/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/ref/configuration/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/ref/debug/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/ref/derp/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/ref/dns/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/ref/oidc/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/ref/policy/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/ref/registration/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/ref/routes/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/ref/tags/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/ref/tls/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/ref/integration/reverse-proxy/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/ref/integration/tools/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/ref/integration/web-ui/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/setup/requirements/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/setup/upgrade/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/setup/install/community/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/setup/install/container/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/setup/install/main/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/setup/install/official/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/setup/install/source/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/usage/getting-started/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/usage/connect/android/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/usage/connect/apple/ - 2026-10-06 + 2026-10-07 daily https://juanfont.github.io/headscale/development/usage/connect/windows/ - 2026-10-06 + 2026-10-07 daily \ No newline at end of file diff --git a/development/sitemap.xml.gz b/development/sitemap.xml.gz index ea0c26e84..08fa550ee 100644 Binary files a/development/sitemap.xml.gz and b/development/sitemap.xml.gz differ diff --git a/versions.json b/versions.json index 5cd19f576..ca5e36c53 100644 --- a/versions.json +++ b/versions.json @@ -10,8 +10,8 @@ "version": "0.29.4", "title": "0.29.4", "aliases": [ - "stable", - "latest" + "latest", + "stable" ] }, {