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) |
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) |
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.
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.
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.
Headscale is open to code contributions for bug fixes without discussion.
If you find mistakes in the documentation, please submit a fix to the documentation.
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.
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.
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.
Headscale is open to code contributions for bug fixes without discussion.
If you find mistakes in the documentation, please submit a fix to the documentation.
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.
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.
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.
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:
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.
Please follow the steps outlined in the upgrade guide to update your existing Headscale installation. Its best to update from one stable version to the next (e.g. 0.26.0 → 0.27.1 → 0.28.0) in case you are multiple releases behind. You should always pick the latest available patch release.
Be sure to check the changelog for version specific upgrade instructions and breaking changes.
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:
An environment with 1000 servers
they rarely "move" (change their endpoints)
new nodes are added rarely
An environment with 80 laptops/phones (end user devices)
nodes move often, e.g. switching from home to office
Headscale calculates a map of all nodes that need to talk to each other, creating this "world map" requires a lot of CPU time. When an event that requires changes to this map happens, the whole "world" is recalculated, and a new "world map" is created for every node in the network.
This means that under certain conditions, Headscale can likely handle 100s of devices (maybe more), if there is little to no change happening in the network. For example, in Scenario 1, the process of computing the world map is 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.
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.
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.
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.
A frequent use case is to allow traffic only from one node to another, but not the other way around. For example, the workstation of an administrator should be able to connect to all nodes but the nodes themselves shouldn't be able to connect back to the administrator's node. Why do all nodes see the administrator's workstation in the output of tailscale status?
This is essentially how Tailscale works. If traffic is allowed to flow in one direction, then both nodes see each other in their output of tailscale status. Traffic is still filtered according to the ACL, with the exception of tailscale ping which is always allowed in either direction.
See also https://tailscale.com/kb/1087/device-visibility.
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:
headscale policy get --bypass-grpc-and-access-database-directly > policy.jsonpolicy.json. Use the command headscale policy check --file policy.json to validate the policy.headscale policy set --bypass-grpc-and-access-database-directly --file policy.jsonFull 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.
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 setting the environment variable TS_NO_LOGS_NO_SUPPORT=true or by passing the flag --no-logs-no-support to tailscaled. See https://tailscale.com/kb/1011/log-mesh-traffic#opting-out-of-client-logging for details.
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.
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.
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.
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:
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.
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 → 0.27.1 → 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.
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:
An environment with 1000 servers
they rarely "move" (change their endpoints)
new nodes are added rarely
An environment with 80 laptops/phones (end user devices)
nodes move often, e.g. switching from home to office
Headscale calculates a map of all nodes that need to talk to each other, creating this "world map" requires a lot of CPU time. When an event that requires changes to this map happens, the whole "world" is recalculated, and a new "world map" is created for every node in the network.
This means that under certain conditions, Headscale can likely handle 100s of devices (maybe more), if there is little to no change happening in the network. For example, in Scenario 1, the process of computing the world map is 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.
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.
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.
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.
A frequent use case is to allow traffic only from one node to another, but not the other way around. For example, the workstation of an administrator should be able to connect to all nodes but the nodes themselves shouldn't be able to connect back to the administrator's node. Why do all nodes see the administrator's workstation in the output of tailscale status?
This is essentially how Tailscale works. If traffic is allowed to flow in one direction, then both nodes see each other in their output of tailscale status. Traffic is still filtered according to the ACL, with the exception of tailscale ping which is always allowed in either direction.
See also https://tailscale.com/kb/1087/device-visibility.
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:
headscale policy get --bypass-grpc-and-access-database-directly > policy.jsonpolicy.json. Use the command headscale policy check --file policy.json to validate the policy.headscale policy set --bypass-grpc-and-access-database-directly --file policy.jsonFull 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.
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.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: Nodes should reconnect within a few seconds and pickup their newly assigned IP addresses.
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 setting the environment variable TS_NO_LOGS_NO_SUPPORT=true or by passing the flag --no-logs-no-support to tailscaled. See https://tailscale.com/kb/1011/log-mesh-traffic#opting-out-of-client-logging for details.
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:
autogroup:internet, autogroup:nonroot, autogroup:member, autogroup:tagged, autogroup:selfHeadscale 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:
autogroup:internet, autogroup:nonroot, autogroup:member, autogroup:tagged, autogroup:selfJoin our Discord server for announcements and community support.
Please report bugs via GitHub issues
Join our Discord server for announcements and community support.
Please report bugs via GitHub issues
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.
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.
If you like to support the development of headscale, please consider a donation via ko-fi.com/headscale. Thank you!
If you like to support the development of headscale, please consider a donation via ko-fi.com/headscale. Thank you!
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.
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.
Please see Sponsor for more information.
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.
Headscale is maintained by Kristoffer Dalby and Juan Font.
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.
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.
Please see Sponsor for more information.
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.
Headscale is maintained by Kristoffer Dalby and Juan Font.
Headscale implements the same policy ACLs as Tailscale.com, adapted to the self-hosted environment.
For instance, instead of referring to users when defining groups you must use users (which are the equivalent to user/logins in Tailscale.com).
Please check https://tailscale.com/kb/1018/acls/ for further information.
When using ACL's the User borders are no longer applied. All machines whichever the User have the ability to communicate with other hosts as long as the ACL's permits this exchange.
To enable and configure ACLs in Headscale, you need to specify the path to your ACL policy file in the policy.path key in config.yaml.
Your ACL policy file must be formatted using huJSON.
Info on how these policies are written can be found here.
Please reload or restart Headscale after updating the ACL file. Headscale may be reloaded either via its systemd service (sudo systemctl reload headscale) or by sending a SIGHUP signal (sudo kill -HUP $(pidof headscale)) to the main process. Headscale logs the result of ACL policy processing after each reload.
Allow All: If you define an ACL file but completely omit the "acls" field from its content, 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.
{}
+ ACLs - Headscale ACLs
Headscale implements the same policy ACLs as Tailscale.com, adapted to the self-hosted environment.
For instance, instead of referring to users when defining groups you must use users (which are the equivalent to user/logins in Tailscale.com).
Please check https://tailscale.com/kb/1018/acls/ for further information.
When using ACL's the User borders are no longer applied. All machines whichever the User have the ability to communicate with other hosts as long as the ACL's permits this exchange.
ACL Setup¶
To enable and configure ACLs in Headscale, you need to specify the path to your ACL policy file in the policy.path key in config.yaml.
Your ACL policy file must be formatted using huJSON.
Info on how these policies are written can be found here.
Please reload or restart Headscale after updating the ACL file. Headscale may be reloaded either via its systemd service (sudo systemctl reload headscale) or by sending a SIGHUP signal (sudo kill -HUP $(pidof headscale)) to the main process. Headscale logs the result of ACL policy processing after each reload.
Simple Examples¶
-
Allow All: If you define an ACL file but completely omit the "acls" field from its content, 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.
-
Deny All: To prevent all communication within your tailnet, you can include an empty array for the "acls" field in your policy file.
{
"acls": []
}
diff --git a/development/ref/api/index.html b/development/ref/api/index.html
index 62f07dba..0361197d 100644
--- a/development/ref/api/index.html
+++ b/development/ref/api/index.html
@@ -1,4 +1,4 @@
- API - Headscale API¶
Headscale provides a HTTP REST API and a gRPC interface which may be used to integrate a web interface, remote control Headscale or provide a base for custom integration and tooling.
Both interfaces require 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
+ API - Headscale API¶
Headscale provides a HTTP REST API and a gRPC interface which may be used to integrate a web interface, remote control Headscale or provide a base for custom integration and tooling.
Both interfaces require 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:
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:
and to expire an API key:
REST API¶
- API endpoint:
/api/v1, e.g. https://headscale.example.com/api/v1 - Documentation:
/swagger, e.g. https://headscale.example.com/swagger - Headscale Version:
/version, e.g. https://headscale.example.com/version - Authenticate using HTTP Bearer authentication by sending the API key with the HTTP
Authorization: Bearer <API_KEY> header.
Start by creating an API key and test it with the examples below. Read the API documentation provided by your Headscale server at /swagger for details.
curl -H "Authorization: Bearer <API_KEY>" \
diff --git a/development/ref/configuration/index.html b/development/ref/configuration/index.html
index 294931b6..3f7de1db 100644
--- a/development/ref/configuration/index.html
+++ b/development/ref/configuration/index.html
@@ -1,4 +1,4 @@
- Configuration - Headscale Configuration¶
- Headscale loads its configuration from a YAML file
- It searches for
config.yaml in the following paths: /etc/headscale$HOME/.headscale- the current working directory
- To load the configuration from a different path, use:
- the command line flag
-c, --config - the environment variable
HEADSCALE_CONFIG
- Validate the configuration file with:
headscale configtest
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.
- Development version: https://github.com/juanfont/headscale/blob/main/config-example.yaml
- Version 0.28.0: https://github.com/juanfont/headscale/blob/v0.28.0/config-example.yaml
# Development version
+ Configuration - Headscale Configuration¶
- Headscale loads its configuration from a YAML file
- It searches for
config.yaml in the following paths: /etc/headscale$HOME/.headscale- the current working directory
- To load the configuration from a different path, use:
- the command line flag
-c, --config - the environment variable
HEADSCALE_CONFIG
- Validate the configuration file with:
headscale configtest
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.
- Development version: https://github.com/juanfont/headscale/blob/main/config-example.yaml
- Version 0.28.0: https://github.com/juanfont/headscale/blob/v0.28.0/config-example.yaml
# Development version
wget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml
# Version 0.28.0
diff --git a/development/ref/debug/index.html b/development/ref/debug/index.html
index 3cb5b969..c54b7f97 100644
--- a/development/ref/debug/index.html
+++ b/development/ref/debug/index.html
@@ -1,4 +1,4 @@
- Debug - Headscale Debugging and troubleshooting¶
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.
Tailscale¶
The Tailscale client itself offers many commands to introspect its state as well as the state of the network:
- Check local network conditions:
tailscale netcheck - Get the client status:
tailscale status --json - Get DNS status:
tailscale dns status --all - Client logs:
tailscale debug daemon-logs - Client netmap:
tailscale debug netmap - Test DERP connection:
tailscale debug derp headscale - And many more, see:
tailscale debug --help
Many of the commands are helpful when trying to understand differences between Headscale and Tailscale SaaS.
Headscale¶
Application logging¶
The log levels debug and trace can be useful to get more information from Headscale.
log:
+ Debug - Headscale Debugging and troubleshooting¶
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.
Tailscale¶
The Tailscale client itself offers many commands to introspect its state as well as the state of the network:
- Check local network conditions:
tailscale netcheck - Get the client status:
tailscale status --json - Get DNS status:
tailscale dns status --all - Client logs:
tailscale debug daemon-logs - Client netmap:
tailscale debug netmap - Test DERP connection:
tailscale debug derp headscale - And many more, see:
tailscale debug --help
Many of the commands are helpful when trying to understand differences between Headscale and Tailscale SaaS.
Headscale¶
Application logging¶
The log levels debug and trace can be useful to get more information from Headscale.
Database logging¶
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:
diff --git a/development/ref/derp/index.html b/development/ref/derp/index.html
index 04ac2742..09731794 100644
--- a/development/ref/derp/index.html
+++ b/development/ref/derp/index.html
@@ -1,4 +1,4 @@
- DERP - Headscale DERP¶
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.
Configuration¶
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.
Enable embedded DERP¶
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.yamlderp:
+ DERP - Headscale DERP¶
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.
Configuration¶
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.
Enable embedded DERP¶
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.yamlderp:
server:
enabled: true
ipv4: 198.51.100.1
diff --git a/development/ref/dns/index.html b/development/ref/dns/index.html
index 6d91f308..fd78025a 100644
--- a/development/ref/dns/index.html
+++ b/development/ref/dns/index.html
@@ -1,4 +1,4 @@
- DNS - Headscale DNS¶
Headscale supports most DNS features from Tailscale. DNS related settings can be configured within the dns section of the configuration file.
Setting extra DNS records¶
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:
- Use the
dns.extra_records option in the configuration file for entries that are static and don't change while Headscale is running. Those entries are processed when Headscale is starting up and changes to the configuration require a restart of Headscale. - For dynamic DNS records that may be added, updated or removed while Headscale is running or DNS records that are generated by scripts the option
dns.extra_records_path in the configuration file is useful. Set it to the absolute path of the JSON file containing DNS records and Headscale processes this file as it detects changes.
An example use case is to serve multiple apps on the same host via a reverse proxy like NGINX, in this case a Prometheus monitoring stack. This allows to nicely access the service with "http://grafana.myvpn.example.com" instead of the hostname and port combination "http://hostname-in-magic-dns.myvpn.example.com:3000".
Limitations
Currently, only A and AAAA records are processed by Tailscale.
-
Configure extra DNS records using one of the available configuration options:
config.yamldns:
+ DNS - Headscale DNS¶
Headscale supports most DNS features from Tailscale. DNS related settings can be configured within the dns section of the configuration file.
Setting extra DNS records¶
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:
- Use the
dns.extra_records option in the configuration file for entries that are static and don't change while Headscale is running. Those entries are processed when Headscale is starting up and changes to the configuration require a restart of Headscale. - For dynamic DNS records that may be added, updated or removed while Headscale is running or DNS records that are generated by scripts the option
dns.extra_records_path in the configuration file is useful. Set it to the absolute path of the JSON file containing DNS records and Headscale processes this file as it detects changes.
An example use case is to serve multiple apps on the same host via a reverse proxy like NGINX, in this case a Prometheus monitoring stack. This allows to nicely access the service with "http://grafana.myvpn.example.com" instead of the hostname and port combination "http://hostname-in-magic-dns.myvpn.example.com:3000".
Limitations
Currently, only A and AAAA records are processed by Tailscale.
-
Configure extra DNS records using one of the available configuration options:
config.yamldns:
...
extra_records:
- name: "grafana.myvpn.example.com"
diff --git a/development/ref/integration/reverse-proxy/index.html b/development/ref/integration/reverse-proxy/index.html
index 5a60c9e6..a2a91cb3 100644
--- a/development/ref/integration/reverse-proxy/index.html
+++ b/development/ref/integration/reverse-proxy/index.html
@@ -1,4 +1,4 @@
- Reverse proxy - Headscale Running headscale behind a reverse proxy¶
Community documentation
This page is not actively maintained by the headscale authors and is written by community members. It is not verified by headscale developers.
It might be outdated and it might miss necessary steps.
Running headscale behind a reverse proxy is useful when running multiple applications on the same server, and you want to reuse the same external IP and port - usually tcp/443 for HTTPS.
WebSockets¶
The reverse proxy MUST be configured to support WebSockets to communicate with Tailscale clients.
WebSockets support is also required when using the Headscale embedded DERP server. In this case, you will also need to expose the UDP port used for STUN (by default, udp/3478). Please check our config-example.yaml.
Cloudflare¶
Running headscale behind a cloudflare proxy or cloudflare tunnel is not supported and will not work as Cloudflare does not support WebSocket POSTs as required by the Tailscale protocol. See this issue
TLS¶
Headscale can be configured not to use TLS, leaving it to the reverse proxy to handle. Add the following configuration values to your headscale config file.
config.yamlserver_url: https://<YOUR_SERVER_NAME> # This should be the FQDN at which headscale will be served
+ Reverse proxy - Headscale Running headscale behind a reverse proxy¶
Community documentation
This page is not actively maintained by the headscale authors and is written by community members. It is not verified by headscale developers.
It might be outdated and it might miss necessary steps.
Running headscale behind a reverse proxy is useful when running multiple applications on the same server, and you want to reuse the same external IP and port - usually tcp/443 for HTTPS.
WebSockets¶
The reverse proxy MUST be configured to support WebSockets to communicate with Tailscale clients.
WebSockets support is also required when using the Headscale embedded DERP server. In this case, you will also need to expose the UDP port used for STUN (by default, udp/3478). Please check our config-example.yaml.
Cloudflare¶
Running headscale behind a cloudflare proxy or cloudflare tunnel is not supported and will not work as Cloudflare does not support WebSocket POSTs as required by the Tailscale protocol. See this issue
TLS¶
Headscale can be configured not to use TLS, leaving it to the reverse proxy to handle. Add the following configuration values to your headscale config file.
config.yamlserver_url: https://<YOUR_SERVER_NAME> # This should be the FQDN at which headscale will be served
listen_addr: 0.0.0.0:8080
metrics_listen_addr: 0.0.0.0:9090
tls_cert_path: ""
diff --git a/development/ref/integration/tools/index.html b/development/ref/integration/tools/index.html
index f7cf81cf..039b75df 100644
--- a/development/ref/integration/tools/index.html
+++ b/development/ref/integration/tools/index.html
@@ -1 +1 @@
- Tools - Headscale Tools related to headscale¶
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.
- headscale-operator - Headscale Kubernetes Operator
- tailscale-manager - Dynamically manage Tailscale route advertisements
- headscalebacktosqlite - Migrate headscale from PostgreSQL back to SQLite
- headscale-pf - Populates user groups based on user groups in Jumpcloud or Authentik
- headscale-client-go - A Go client implementation for the Headscale HTTP API.
- headscale-zabbix - A Zabbix Monitoring Template for the Headscale Service.
- tailscale-exporter - A Prometheus exporter for Headscale that provides network-level metrics using the Headscale API.
\ No newline at end of file
+ Tools - Headscale Tools related to headscale¶
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.
- headscale-operator - Headscale Kubernetes Operator
- tailscale-manager - Dynamically manage Tailscale route advertisements
- headscalebacktosqlite - Migrate headscale from PostgreSQL back to SQLite
- headscale-pf - Populates user groups based on user groups in Jumpcloud or Authentik
- headscale-client-go - A Go client implementation for the Headscale HTTP API.
- headscale-zabbix - A Zabbix Monitoring Template for the Headscale Service.
- tailscale-exporter - A Prometheus exporter for Headscale that provides network-level metrics using the Headscale API.
\ No newline at end of file
diff --git a/development/ref/integration/web-ui/index.html b/development/ref/integration/web-ui/index.html
index ff45d76b..ae8c17cc 100644
--- a/development/ref/integration/web-ui/index.html
+++ b/development/ref/integration/web-ui/index.html
@@ -1 +1 @@
- Web UI - Headscale Web interfaces for headscale¶
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.
- headscale-ui - A web frontend for the headscale Tailscale-compatible coordination server
- HeadscaleUi - A static headscale admin ui, no backend environment required
- Headplane - An advanced Tailscale inspired frontend for headscale
- headscale-admin - Headscale-Admin is meant to be a simple, modern web interface for headscale
- ouroboros - Ouroboros is designed for users to manage their own devices, rather than for admins
- unraid-headscale-admin - A simple headscale admin UI for Unraid, it offers Local (
docker exec) and API Mode - headscale-console - WebAssembly-based client supporting SSH, VNC and RDP with optional self-service capabilities
- headscale-piying - headscale web ui,support visual ACL configuration
- HeadControl - Minimal Headscale admin dashboard, built with Go and HTMX
- Headscale Manager - Headscale UI for Android
You can ask for support on our Discord server in the "web-interfaces" channel.
\ No newline at end of file
+ Web UI - Headscale Web interfaces for headscale¶
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.
- headscale-ui - A web frontend for the headscale Tailscale-compatible coordination server
- HeadscaleUi - A static headscale admin ui, no backend environment required
- Headplane - An advanced Tailscale inspired frontend for headscale
- headscale-admin - Headscale-Admin is meant to be a simple, modern web interface for headscale
- ouroboros - Ouroboros is designed for users to manage their own devices, rather than for admins
- unraid-headscale-admin - A simple headscale admin UI for Unraid, it offers Local (
docker exec) and API Mode - headscale-console - WebAssembly-based client supporting SSH, VNC and RDP with optional self-service capabilities
- headscale-piying - headscale web ui,support visual ACL configuration
- HeadControl - Minimal Headscale admin dashboard, built with Go and HTMX
- Headscale Manager - Headscale UI for Android
You can ask for support on our Discord server in the "web-interfaces" channel.
\ No newline at end of file
diff --git a/development/ref/oidc/index.html b/development/ref/oidc/index.html
index 45b574eb..2afb8b53 100644
--- a/development/ref/oidc/index.html
+++ b/development/ref/oidc/index.html
@@ -1,4 +1,4 @@
- OpenID Connect - Headscale OpenID Connect¶
Headscale supports authentication via external identity providers using OpenID Connect (OIDC). It features:
- Auto configuration via OpenID Connect Discovery Protocol
- Proof Key for Code Exchange (PKCE) code verification
- Authorization based on a user's domain, email address or group membership
- Synchronization of standard OIDC claims
Please see limitations for known issues and limitations.
Configuration¶
OpenID requires configuration in Headscale and your identity provider:
- Headscale: The
oidc section of the Headscale configuration contains all available configuration options along with a description and their default values. - Identity provider: Please refer to the official documentation of your identity provider for specific instructions. Additionally, there might be some useful hints in the Identity provider specific configuration section below.
Basic configuration¶
A basic configuration connects Headscale to an identity provider and typically requires:
- OpenID Connect Issuer URL from the identity provider. Headscale uses the OpenID Connect Discovery Protocol 1.0 to automatically obtain OpenID configuration parameters (example:
https://sso.example.com). - Client ID from the identity provider (example:
headscale). - Client secret generated by the identity provider (example:
generated-secret). - Redirect URI for your identity provider (example:
https://headscale.example.com/oidc/callback).
oidc:
+ OpenID Connect - Headscale OpenID Connect¶
Headscale supports authentication via external identity providers using OpenID Connect (OIDC). It features:
- Auto configuration via OpenID Connect Discovery Protocol
- Proof Key for Code Exchange (PKCE) code verification
- Authorization based on a user's domain, email address or group membership
- Synchronization of standard OIDC claims
Please see limitations for known issues and limitations.
Configuration¶
OpenID requires configuration in Headscale and your identity provider:
- Headscale: The
oidc section of the Headscale configuration contains all available configuration options along with a description and their default values. - Identity provider: Please refer to the official documentation of your identity provider for specific instructions. Additionally, there might be some useful hints in the Identity provider specific configuration section below.
Basic configuration¶
A basic configuration connects Headscale to an identity provider and typically requires:
- OpenID Connect Issuer URL from the identity provider. Headscale uses the OpenID Connect Discovery Protocol 1.0 to automatically obtain OpenID configuration parameters (example:
https://sso.example.com). - Client ID from the identity provider (example:
headscale). - Client secret generated by the identity provider (example:
generated-secret). - Redirect URI for your identity provider (example:
https://headscale.example.com/oidc/callback).
oidc:
issuer: "https://sso.example.com"
client_id: "headscale"
client_secret: "generated-secret"
diff --git a/development/ref/registration/index.html b/development/ref/registration/index.html
index 43917500..32405d82 100644
--- a/development/ref/registration/index.html
+++ b/development/ref/registration/index.html
@@ -1,4 +1,4 @@
- Registration methods - Headscale Registration methods¶
Headscale supports multiple ways to register a node. The preferred registration method depends on the identity of a node and your use case.
Identity model¶
Tailscale's identity model distinguishes between personal and tagged nodes:
- A personal node (or user-owned node) is owned by a human and typically refers to end-user devices such as laptops, workstations or mobile phones. End-user devices are managed by a single user.
- A tagged node (or service-based node or non-human node) provides services to the network. Common examples include web- and database servers. Those nodes are typically managed by a team of users. Some additional restrictions apply for tagged nodes, e.g. a tagged node is not allowed to Tailscale SSH into a personal node.
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.
Registration methods¶
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.
Web authentication¶
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:
- Headscale CLI (described in this documentation)
- Headscale API
- Or delegated to an identity provider via OpenID Connect
Web authentication relies on the presence of a Headscale user. Use the headscale users command to create a new user:
headscale users create <USER>
+ Registration methods - Headscale Registration methods¶
Headscale supports multiple ways to register a node. The preferred registration method depends on the identity of a node and your use case.
Identity model¶
Tailscale's identity model distinguishes between personal and tagged nodes:
- A personal node (or user-owned node) is owned by a human and typically refers to end-user devices such as laptops, workstations or mobile phones. End-user devices are managed by a single user.
- A tagged node (or service-based node or non-human node) provides services to the network. Common examples include web- and database servers. Those nodes are typically managed by a team of users. Some additional restrictions apply for tagged nodes, e.g. a tagged node is not allowed to Tailscale SSH into a personal node.
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.
Registration methods¶
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.
Web authentication¶
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:
- Headscale CLI (described in this documentation)
- Headscale API
- Or delegated to an identity provider via OpenID Connect
Web authentication relies on the presence of a Headscale user. Use the headscale users command to create a new user:
Run tailscale up to login your personal device:
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 registration key required to approve the node:
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 ACL. A simple example looks like this:
The user alice can register nodes tagged with tag:server{
diff --git a/development/ref/routes/index.html b/development/ref/routes/index.html
index 35c1d971..81499a04 100644
--- a/development/ref/routes/index.html
+++ b/development/ref/routes/index.html
@@ -1,4 +1,4 @@
- Routes - Headscale Routes¶
Headscale supports route advertising and can be used to manage subnet routers and exit nodes for a tailnet.
- Subnet routers may be used to connect an existing network such as a virtual private cloud or an on-premise network with your tailnet. Use a subnet router to access devices where Tailscale can't be installed or to gradually rollout Tailscale.
- Exit nodes can be used to route all Internet traffic for another Tailscale node. Use it to securely access the Internet on an untrusted Wi-Fi or to access online services that expect traffic from a specific IP address.
Subnet router¶
The setup of a subnet router requires double opt-in, once from a subnet router and once on the control server to allow its use within the tailnet. Optionally, use autoApprovers to automatically approve routes from a subnet router.
Setup a subnet router¶
Configure a node as subnet router¶
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
+ Routes - Headscale Routes¶
Headscale supports route advertising and can be used to manage subnet routers and exit nodes for a tailnet.
- Subnet routers may be used to connect an existing network such as a virtual private cloud or an on-premise network with your tailnet. Use a subnet router to access devices where Tailscale can't be installed or to gradually rollout Tailscale.
- Exit nodes can be used to route all Internet traffic for another Tailscale node. Use it to securely access the Internet on an untrusted Wi-Fi or to access online services that expect traffic from a specific IP address.
Subnet router¶
The setup of a subnet router requires double opt-in, once from a subnet router and once on the control server to allow its use within the tailnet. Optionally, use autoApprovers to automatically approve routes from a subnet router.
Setup a subnet router¶
Configure a node as subnet router¶
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
If the node is already registered, it can advertise new routes or update previously announced routes with:
Finally, enable IP forwarding to route traffic.
Enable the subnet router on the control server¶
The routes of a tailnet can be displayed with the headscale nodes list-routes command. A subnet router with the hostname myrouter announced the IPv4 networks 10.0.0.0/8 and 192.168.0.0/24. Those need to be approved before they can be used.
$ headscale nodes list-routes
ID | Hostname | Approved | Available | Serving (Primary)
diff --git a/development/ref/tags/index.html b/development/ref/tags/index.html
index 365fad1e..00b11bbf 100644
--- a/development/ref/tags/index.html
+++ b/development/ref/tags/index.html
@@ -1,4 +1,4 @@
- Tags - Headscale Tags¶
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:
- using the
--advertise-tags flag, see web authentication for tagged devices - using a tagged pre authenticated key, see how to create and use it
Administrators can manage tags with:
- Headscale CLI
- Headscale API
Common operations¶
Manage tags for a node¶
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
+ Tags - Headscale Tags¶
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:
- using the
--advertise-tags flag, see web authentication for tagged devices - using a tagged pre authenticated key, see how to create and use it
Administrators can manage tags with:
- Headscale CLI
- Headscale API
Common operations¶
Manage tags for a node¶
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:
Convert from personal to tagged node¶
Use the headscale nodes tag command to convert a personal (user-owned) node to a tagged node:
The node is now owned by the special user tagged-devices and has the specified tags assigned to it.
Convert from tagged to personal node¶
Tagged nodes can return to personal (user-owned) nodes by re-authenticating with:
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 registration key required to approve the node: