From 86a6057f42458e5f3730b738e29f311daf324af9 Mon Sep 17 00:00:00 2001 From: github-actions Date: Mon, 9 Dec 2024 16:16:13 +0000 Subject: [PATCH] Deployed 08bd4b9b to development with MkDocs 1.6.1 and mike 2.1.3 --- development/404.html | 2 +- development/about/clients/index.html | 2 +- development/about/contributing/index.html | 2 +- development/about/faq/index.html | 2 +- development/about/features/index.html | 2 +- development/about/help/index.html | 2 +- development/about/releases/index.html | 2 +- development/about/sponsor/index.html | 2 +- development/index.html | 2 +- development/ref/acls/index.html | 2 +- development/ref/configuration/index.html | 2 +- development/ref/dns/index.html | 2 +- development/ref/exit-node/index.html | 2 +- .../ref/integration/reverse-proxy/index.html | 2 +- development/ref/integration/tools/index.html | 2 +- development/ref/integration/web-ui/index.html | 2 +- development/ref/oidc/index.html | 2 +- development/ref/remote-cli/index.html | 2 +- development/ref/tls/index.html | 2 +- development/setup/install/cloud/index.html | 2 +- .../setup/install/community/index.html | 2 +- .../setup/install/container/index.html | 2 +- development/setup/install/official/index.html | 2 +- development/setup/install/source/index.html | 2 +- development/setup/requirements/index.html | 2 +- development/setup/upgrade/index.html | 2 +- development/sitemap.xml | 58 +++++++++--------- development/sitemap.xml.gz | Bin 437 -> 437 bytes development/usage/connect/android/index.html | 2 +- development/usage/connect/apple/index.html | 2 +- development/usage/connect/windows/index.html | 2 +- development/usage/getting-started/index.html | 2 +- 32 files changed, 59 insertions(+), 59 deletions(-) diff --git a/development/404.html b/development/404.html index a04f6b9d..98e099bb 100644 --- a/development/404.html +++ b/development/404.html @@ -1 +1 @@ - Headscale

404 - Not found

\ No newline at end of file + Headscale

404 - Not found

\ No newline at end of file diff --git a/development/about/clients/index.html b/development/about/clients/index.html index 7f11e934..21caca0b 100644 --- a/development/about/clients/index.html +++ b/development/about/clients/index.html @@ -1 +1 @@ - Clients - Headscale
Skip to content

Client and operating system support

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)
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)
\ No newline at end of file + Clients - Headscale
Skip to content

Client and operating system support

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)
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)
\ No newline at end of file diff --git a/development/about/contributing/index.html b/development/about/contributing/index.html index 70bed058..9f0018d7 100644 --- a/development/about/contributing/index.html +++ b/development/about/contributing/index.html @@ -1 +1 @@ - Contributing - Headscale
Skip to content

Contributing

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

Why do we have this model?

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

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

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

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

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

What do we require?

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

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

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

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

Bug fixes

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

Documentation

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

\ No newline at end of file + Contributing - Headscale
Skip to content

Contributing

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

Why do we have this model?

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

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

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

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

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

What do we require?

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

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

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

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

Bug fixes

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

Documentation

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

\ No newline at end of file diff --git a/development/about/faq/index.html b/development/about/faq/index.html index 55d9e30d..563bb24b 100644 --- a/development/about/faq/index.html +++ b/development/about/faq/index.html @@ -1 +1 @@ - FAQ - Headscale
Skip to content

Frequently Asked Questions

What is the design goal of headscale?

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

How can I contribute?

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

Please see Contributing for more information.

Why is 'acknowledged contribution' the chosen model?

Both maintainers have full-time jobs and families, and we want to avoid burnout. We also want to avoid frustration from contributors when their PRs are not accepted.

We are more than happy to exchange emails, or to have dedicated calls before a PR is submitted.

When/Why is Feature X going to be implemented?

We don't know. We might be working on it. If you're interested in contributing, please post a feature request about it.

Please be aware that there are a number of reasons why we might not accept specific contributions:

  • It is not possible to implement the feature in a way that makes sense in a self-hosted environment.
  • Given that we are reverse-engineering Tailscale to satisfy our own curiosity, we might be interested in implementing the feature ourselves.
  • You are not sending unit and integration tests with it.

Do you support Y method of deploying headscale?

We currently support deploying headscale using our binaries and the DEB packages. Visit our installation guide using official releases 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 Docker 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.

Which database should I use?

We recommend the use of SQLite as database for headscale:

  • SQLite is simple to setup and easy to use
  • It scales well for all of headscale's usecases
  • Development and testing happens primarily on SQLite
  • PostgreSQL is still supported, but is considered to be in "maintenance mode"

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

Why is my reverse proxy not working with headscale?

We don't know. We don't use reverse proxies with headscale ourselves, so we don't have any experience with them. We have community documentation 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.

Can I use headscale and tailscale on the same machine?

Running headscale on a machine that is also in the tailnet can cause problems with subnet routers, traffic relay nodes, and MagicDNS. It might work, but it is not supported.

\ No newline at end of file + FAQ - Headscale
Skip to content

Frequently Asked Questions

What is the design goal of headscale?

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

How can I contribute?

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

Please see Contributing for more information.

Why is 'acknowledged contribution' the chosen model?

Both maintainers have full-time jobs and families, and we want to avoid burnout. We also want to avoid frustration from contributors when their PRs are not accepted.

We are more than happy to exchange emails, or to have dedicated calls before a PR is submitted.

When/Why is Feature X going to be implemented?

We don't know. We might be working on it. If you're interested in contributing, please post a feature request about it.

Please be aware that there are a number of reasons why we might not accept specific contributions:

  • It is not possible to implement the feature in a way that makes sense in a self-hosted environment.
  • Given that we are reverse-engineering Tailscale to satisfy our own curiosity, we might be interested in implementing the feature ourselves.
  • You are not sending unit and integration tests with it.

Do you support Y method of deploying headscale?

We currently support deploying headscale using our binaries and the DEB packages. Visit our installation guide using official releases 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 Docker 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.

Which database should I use?

We recommend the use of SQLite as database for headscale:

  • SQLite is simple to setup and easy to use
  • It scales well for all of headscale's usecases
  • Development and testing happens primarily on SQLite
  • PostgreSQL is still supported, but is considered to be in "maintenance mode"

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

Why is my reverse proxy not working with headscale?

We don't know. We don't use reverse proxies with headscale ourselves, so we don't have any experience with them. We have community documentation 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.

Can I use headscale and tailscale on the same machine?

Running headscale on a machine that is also in the tailnet can cause problems with subnet routers, traffic relay nodes, and MagicDNS. It might work, but it is not supported.

\ No newline at end of file diff --git a/development/about/features/index.html b/development/about/features/index.html index 07d17939..f85fb978 100644 --- a/development/about/features/index.html +++ b/development/about/features/index.html @@ -1 +1 @@ - Features - Headscale
Skip to content

Features

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

\ No newline at end of file + Features - Headscale
Skip to content

Features

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

\ No newline at end of file diff --git a/development/about/help/index.html b/development/about/help/index.html index 79dba586..40a24e42 100644 --- a/development/about/help/index.html +++ b/development/about/help/index.html @@ -1 +1 @@ - Getting help - Headscale
Skip to content
\ No newline at end of file + Getting help - Headscale
Skip to content
\ No newline at end of file diff --git a/development/about/releases/index.html b/development/about/releases/index.html index bac770bd..022ffa7c 100644 --- a/development/about/releases/index.html +++ b/development/about/releases/index.html @@ -1 +1 @@ - Releases - Headscale
Skip to content

Releases

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.

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

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

\ No newline at end of file + Releases - Headscale
Skip to content

Releases

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.

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

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

\ No newline at end of file diff --git a/development/about/sponsor/index.html b/development/about/sponsor/index.html index 4070d2a9..a0063efe 100644 --- a/development/about/sponsor/index.html +++ b/development/about/sponsor/index.html @@ -1 +1 @@ - Sponsor - Headscale
Skip to content

Sponsor

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

\ No newline at end of file + Sponsor - Headscale
Skip to content

Sponsor

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

\ No newline at end of file diff --git a/development/index.html b/development/index.html index 549ed0ad..9e07412f 100644 --- a/development/index.html +++ b/development/index.html @@ -1 +1 @@ - Headscale
Skip to content

Welcome to headscale

Headscale is an open source, self-hosted implementation of the Tailscale control server.

This page contains the documentation for the latest version of headscale. Please also check our FAQ.

Join our Discord server for a chat and community support.

Design goal

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

Supporting headscale

Please see Sponsor for more information.

Contributing

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

Please see Contributing for more information.

About

Headscale is maintained by Kristoffer Dalby and Juan Font.

\ No newline at end of file + Headscale
Skip to content

Welcome to headscale

Headscale is an open source, self-hosted implementation of the Tailscale control server.

This page contains the documentation for the latest version of headscale. Please also check our FAQ.

Join our Discord server for a chat and community support.

Design goal

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

Supporting headscale

Please see Sponsor for more information.

Contributing

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

Please see Contributing for more information.

About

Headscale is maintained by Kristoffer Dalby and Juan Font.

\ No newline at end of file diff --git a/development/ref/acls/index.html b/development/ref/acls/index.html index eaa200de..95f17130 100644 --- a/development/ref/acls/index.html +++ b/development/ref/acls/index.html @@ -1,4 +1,4 @@ - ACLs - Headscale
Skip to content

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.

ACLs use case example

Let's build an example use case for a small business (It may be the place where ACL's are the most useful).

We have a small company with a boss, an admin, two developers and an intern.

The boss should have access to all servers but not to the user's hosts. Admin should also have access to all hosts except that their permissions should be limited to maintaining the hosts (for example purposes). The developers can do anything they want on dev hosts but only watch on productions hosts. Intern can only interact with the development servers.

There's an additional server that acts as a router, connecting the VPN users to an internal network 10.20.0.0/16. Developers must have access to those internal resources.

Each user have at least a device connected to the network and we have some servers.

  • database.prod
  • database.dev
  • app-server1.prod
  • app-server1.dev
  • billing.internal
  • router.internal

ACL implementation example

ACL setup

Note: Users will be created automatically when users authenticate with the headscale server.

ACLs have to be written in huJSON.

When registering the servers we will need to add the flag --advertise-tags=tag:<tag1>,tag:<tag2>, and the user that is registering the server should be allowed to do it. Since anyone can add tags to a server they can register, the check of the tags is done on headscale server and only valid tags are applied. A tag is valid if the user that is registering it is allowed to do it.

To use ACLs in headscale, you must edit your config.yaml file. In there you will find a policy.path parameter. This will need to point to your ACL file. More info on how these policies are written can be found here.

Here are the ACL's to implement the same permissions as above:

{
+ 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.
 
ACLs use case example
 
Let's build an example use case for a small business (It may be the place where ACL's are the most useful).
 
We have a small company with a boss, an admin, two developers and an intern.
 
The boss should have access to all servers but not to the user's hosts. Admin should also have access to all hosts except that their permissions should be limited to maintaining the hosts (for example purposes). The developers can do anything they want on dev hosts but only watch on productions hosts. Intern can only interact with the development servers.
 
There's an additional server that acts as a router, connecting the VPN users to an internal network 10.20.0.0/16. Developers must have access to those internal resources.
 
Each user have at least a device connected to the network and we have some servers.
 
     
  • database.prod
    •  
  • database.dev
    •  
  • app-server1.prod
    •  
  • app-server1.dev
    •  
  • billing.internal
    •  
  • router.internal
    •  
 
ACL implementation example
 
ACL setup
 
Note: Users will be created automatically when users authenticate with the headscale server.
 
ACLs have to be written in huJSON.
 
When registering the servers we will need to add the flag --advertise-tags=tag:<tag1>,tag:<tag2>, and the user that is registering the server should be allowed to do it. Since anyone can add tags to a server they can register, the check of the tags is done on headscale server and only valid tags are applied. A tag is valid if the user that is registering it is allowed to do it.
 
To use ACLs in headscale, you must edit your config.yaml file. In there you will find a policy.path parameter. This will need to point to your ACL file. More info on how these policies are written can be found here.
 
Here are the ACL's to implement the same permissions as above:
 
{
   // groups are collections of users having a common scope. A user can be in multiple groups
   // groups cannot be composed of groups
   "groups": {
diff --git a/development/ref/configuration/index.html b/development/ref/configuration/index.html
index 9192f207..334246c2 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
      •  
     
    •  
  • Use the command line flag -c, --config to load the configuration from a different path
    •  
  • 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
+ 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
      •  
     
    •  
  • Use the command line flag -c, --config to load the configuration from a different path
    •  
  • 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
 wget -O config.yaml https://raw.githubusercontent.com/juanfont/headscale/main/config-example.yaml
 
 # Version 0.23.0
diff --git a/development/ref/dns/index.html b/development/ref/dns/index.html
index 985d9086..ff5efa77 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 and DNS releated settings can be configured in the configuration file within the dns section.
 
Setting custom DNS records
 
 
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 allows to set custom DNS records which are made available via MagicDNS. 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
 
Not all types of records are supported, especially no CNAME records.
 
 
     
  1.  
    Update the configuration file to contain the desired records like so:
     
    dns:
+ DNS - Headscale      
     
      
      
     
      
     
     
     
     
      
     
     
     
     
     
      
     
     
     
     
           
    DNS
     
    Headscale supports most DNS features from Tailscale and DNS releated settings can be configured in the configuration file within the dns section.
     
    Setting custom DNS records
     
     
    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 allows to set custom DNS records which are made available via MagicDNS. 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
     
    Not all types of records are supported, especially no CNAME records.
     
     
       
    1.  
      Update the configuration file to contain the desired records like so:
       
      dns:
   ...
   extra_records:
     - name: "prometheus.myvpn.example.com"
diff --git a/development/ref/exit-node/index.html b/development/ref/exit-node/index.html
index 95b1c330..ab400b0c 100644
--- a/development/ref/exit-node/index.html
+++ b/development/ref/exit-node/index.html
@@ -1,4 +1,4 @@
- Exit node - Headscale      
       
        
        
       
        
       
       
       
       
        
       
       
       
       
       
        
       
       
       
       
             
      Exit Nodes
       
      On the node
       
      Register the node and make it advertise itself as an exit node:
       
      $ sudo tailscale up --login-server https://headscale.example.com --advertise-exit-node
+ Exit node - Headscale      
       
        
        
       
        
       
       
       
       
        
       
       
       
       
       
        
       
       
       
       
             
      Exit Nodes
       
      On the node
       
      Register the node and make it advertise itself as an exit node:
       
      $ sudo tailscale up --login-server https://headscale.example.com --advertise-exit-node
 
       
      If the node is already registered, it can advertise exit capabilities like this:
       
      $ sudo tailscale set --advertise-exit-node
 
       
      To use a node as an exit node, IP forwarding must be enabled on the node. Check the official Tailscale documentation for how to enable IP forwarding.
       
      On the control server
       
      $ # list nodes
 $ headscale routes list
diff --git a/development/ref/integration/reverse-proxy/index.html b/development/ref/integration/reverse-proxy/index.html
index 26aaa5c2..6c0f452e 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.
       
      server_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.
       
      server_url: https://<YOUR_SERVER_NAME> # This should be the FQDN at which headscale will be served
 listen_addr: 0.0.0.0:8080
 metrics_listen_addr: 0.0.0.0:9090
 tls_cert_path: ""
diff --git a/development/ref/integration/tools/index.html b/development/ref/integration/tools/index.html
index b323c8b9..f927b0d0 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 and scripts related to headscale.
       
        
       Name Repository Link Description 
               
       tailscale-manager Github Dynamically manage Tailscale route advertisements 
       
       headscalebacktosqlite Github Migrate headscale from PostgreSQL back to SQLite 
              
       
       
        
        
        
       
       
       
          
\ 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 and scripts related to headscale.
       
        
       Name Repository Link Description 
               
       tailscale-manager Github Dynamically manage Tailscale route advertisements 
       
       headscalebacktosqlite Github Migrate headscale from PostgreSQL back to SQLite 
              
       
       
        
        
        
       
       
       
          
\ 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 15f9012b..e21cf10a 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.
       
        
       Name Repository Link Description 
               
       headscale-webui Github A simple headscale web UI for small-scale deployments. 
       
       headscale-ui Github A web frontend for the headscale Tailscale-compatible coordination server 
       
       HeadscaleUi GitHub A static headscale admin ui, no backend enviroment required 
       
       Headplane GitHub An advanced Tailscale inspired frontend for headscale 
       
       headscale-admin Github Headscale-Admin is meant to be a simple, modern web interface for headscale 
       
       ouroboros Github Ouroboros is designed for users to manage their own devices, rather than for admins 
              
       
      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.
       
        
       Name Repository Link Description 
               
       headscale-webui Github A simple headscale web UI for small-scale deployments. 
       
       headscale-ui Github A web frontend for the headscale Tailscale-compatible coordination server 
       
       HeadscaleUi GitHub A static headscale admin ui, no backend enviroment required 
       
       Headplane GitHub An advanced Tailscale inspired frontend for headscale 
       
       headscale-admin Github Headscale-Admin is meant to be a simple, modern web interface for headscale 
       
       ouroboros Github Ouroboros is designed for users to manage their own devices, rather than for admins 
              
       
      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 d303a07d..4eeb9d25 100644
--- a/development/ref/oidc/index.html
+++ b/development/ref/oidc/index.html
@@ -1,4 +1,4 @@
- OIDC authentication - Headscale      
       
        
        
       
        
       
       
       
       
        
       
       
       
       
       
        
       
       
       
       
             
      Configuring headscale to use OIDC authentication
       
      In order to authenticate users through a centralized solution one must enable the OIDC integration.
       
      Known limitations:
       
         
      • No dynamic ACL support
        •  
      • OIDC groups cannot be used in ACLs
        •  
       
      Basic configuration
       
      In your config.yaml, customize this to your liking:
       
      oidc:
+ OIDC authentication - Headscale      
       
        
        
       
        
       
       
       
       
        
       
       
       
       
       
        
       
       
       
       
             
      Configuring headscale to use OIDC authentication
       
      In order to authenticate users through a centralized solution one must enable the OIDC integration.
       
      Known limitations:
       
         
      • No dynamic ACL support
        •  
      • OIDC groups cannot be used in ACLs
        •  
       
      Basic configuration
       
      In your config.yaml, customize this to your liking:
       
      oidc:
   # Block further startup until the OIDC provider is healthy and available
   only_start_if_oidc_is_available: true
   # Specified by your OIDC provider
diff --git a/development/ref/remote-cli/index.html b/development/ref/remote-cli/index.html
index aabc5fb2..8b36d480 100644
--- a/development/ref/remote-cli/index.html
+++ b/development/ref/remote-cli/index.html
@@ -1,4 +1,4 @@
- Remote CLI - Headscale      
       
        
        
       
        
       
       
       
       
        
       
       
       
       
       
        
       
       
       
       
             
      Controlling headscale with remote CLI
       
      This documentation has the goal of showing a user how-to control a headscale instance from a remote machine with the headscale command line binary.
       
      Prerequisite
       
         
      • A workstation to run headscale (any supported platform, e.g. Linux).
        •  
      • A headscale server with gRPC enabled.
        •  
      • Connections to the gRPC port (default: 50443) are allowed.
        •  
      • Remote access requires an encrypted connection via TLS.
        •  
      • An API key to authenticate with the headscale server.
        •  
       
      Create an API key
       
      We need to create an API key to authenticate with the remote headscale server when using it from our workstation.
       
      To create an API key, log into your headscale server and generate a key:
       
      headscale apikeys create --expiration 90d
+ Remote CLI - Headscale      
       
        
        
       
        
       
       
       
       
        
       
       
       
       
       
        
       
       
       
       
             
      Controlling headscale with remote CLI
       
      This documentation has the goal of showing a user how-to control a headscale instance from a remote machine with the headscale command line binary.
       
      Prerequisite
       
         
      • A workstation to run headscale (any supported platform, e.g. Linux).
        •  
      • A headscale server with gRPC enabled.
        •  
      • Connections to the gRPC port (default: 50443) are allowed.
        •  
      • Remote access requires an encrypted connection via TLS.
        •  
      • An API key to authenticate with the headscale server.
        •  
       
      Create an API key
       
      We need to create an API key to authenticate with the remote headscale server when using it from our workstation.
       
      To create an API key, log into your headscale server and generate a key:
       
      headscale apikeys create --expiration 90d
 
       
      Copy the output of the command and save it for later. Please note that you can not retrieve a key again, if the key is lost, expire the old one, and create a new key.
       
      To list the keys currently associated with the server:
       
      headscale apikeys list
 
       
      and to expire a key:
       
      headscale apikeys expire --prefix "<PREFIX>"
 
       
      Download and configure headscale
       
         
      1.  
        Download the headscale binary from GitHub's release page. Make sure to use the same version as on the server.
         
        2.  
      2.  
        Put the binary somewhere in your PATH, e.g. /usr/local/bin/headscale
         
        3.  
      3.  
        Make headscale executable:
         
        chmod +x /usr/local/bin/headscale
diff --git a/development/ref/tls/index.html b/development/ref/tls/index.html
index 41de8dac..0402e92b 100644
--- a/development/ref/tls/index.html
+++ b/development/ref/tls/index.html
@@ -1,4 +1,4 @@
- TLS - Headscale      
         
          
          
         
          
         
         
         
         
          
         
         
         
         
         
          
         
         
         
         
               
        Running the service via TLS (optional)
         
        Bring your own certificate
         
        Headscale can be configured to expose its web service via TLS. To configure the certificate and key file manually, set the tls_cert_path and tls_cert_path configuration parameters. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.
         
        tls_cert_path: ""
+ TLS - Headscale      
         
          
          
         
          
         
         
         
         
          
         
         
         
         
         
          
         
         
         
         
               
        Running the service via TLS (optional)
         
        Bring your own certificate
         
        Headscale can be configured to expose its web service via TLS. To configure the certificate and key file manually, set the tls_cert_path and tls_cert_path configuration parameters. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.
         
        tls_cert_path: ""
 tls_key_path: ""
 
         
        The certificate should contain the full chain, else some clients, like the Tailscale Android client, will reject it.
         
        Let's Encrypt / ACME
         
        To get a certificate automatically via Let's Encrypt, 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.
         
        tls_letsencrypt_hostname: ""
 tls_letsencrypt_listen: ":http"
diff --git a/development/setup/install/cloud/index.html b/development/setup/install/cloud/index.html
index 70d2b596..3af89b62 100644
--- a/development/setup/install/cloud/index.html
+++ b/development/setup/install/cloud/index.html
@@ -1 +1 @@
- Cloud - Headscale      
         
          
          
         
          
         
         
         
         
          
         
         
         
         
         
          
         
         
         
         
               
        Running headscale in a cloud
         
         
        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.
         
         
        Sealos
         
        Deploy headscale as service on Sealos.
         
           
        1. Click the following prebuilt template:
          2.  
         
         
           
        1. Click "Deploy Application" on the template page to start deployment. Upon completion, two applications appear: headscale, and one of its web interfaces.
          2.  
        2. Once deployment concludes, click 'Details' on the headscale application page to navigate to the application's details.
          3.  
        3. Wait for the application's status to switch to running. For accessing the headscale server, the Public Address associated with port 8080 is the address of the headscale server. To access the headscale console, simply append /admin/ to the headscale public URL.
          4.  
         
         
        Remote CLI
         
        Headscale can be managed remotely via its remote CLI support. See our Controlling headscale with remote CLI documentation for details.
         
         
         
          
          
          
         
         
         
            
\ No newline at end of file
+ Cloud - Headscale      
         
          
          
         
          
         
         
         
         
          
         
         
         
         
         
          
         
         
         
         
               
        Running headscale in a cloud
         
         
        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.
         
         
        Sealos
         
        Deploy headscale as service on Sealos.
         
           
        1. Click the following prebuilt template:
          2.  
         
         
           
        1. Click "Deploy Application" on the template page to start deployment. Upon completion, two applications appear: headscale, and one of its web interfaces.
          2.  
        2. Once deployment concludes, click 'Details' on the headscale application page to navigate to the application's details.
          3.  
        3. Wait for the application's status to switch to running. For accessing the headscale server, the Public Address associated with port 8080 is the address of the headscale server. To access the headscale console, simply append /admin/ to the headscale public URL.
          4.  
         
         
        Remote CLI
         
        Headscale can be managed remotely via its remote CLI support. See our Controlling headscale with remote CLI documentation for details.
         
         
         
          
          
          
         
         
         
            
\ No newline at end of file
diff --git a/development/setup/install/community/index.html b/development/setup/install/community/index.html
index 5299fa38..336d5106 100644
--- a/development/setup/install/community/index.html
+++ b/development/setup/install/community/index.html
@@ -1,4 +1,4 @@
- Community packages - Headscale      
         
          
          
         
          
         
         
         
         
          
         
         
         
         
         
          
         
         
         
         
               
        Community packages
         
        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:
         
           
        • setup a dedicated user account to run headscale
          •  
        • provide a default configuration
          •  
        • install headscale as system service
          •  
         
         
        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.
         
        Packaging status
         
         
        Arch Linux
         
        Arch Linux offers a package for headscale, install via:
         
        pacman -S headscale
+ Community packages - Headscale      
         
          
          
         
          
         
         
         
         
          
         
         
         
         
         
          
         
         
         
         
               
        Community packages
         
        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:
         
           
        • setup a dedicated user account to run headscale
          •  
        • provide a default configuration
          •  
        • install headscale as system service
          •  
         
         
        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.
         
        Packaging status
         
         
        Arch Linux
         
        Arch Linux offers a package for headscale, install via:
         
        pacman -S headscale
 
         
        The AUR package headscale-git can be used to build the current development version.
         
        Fedora, RHEL, CentOS
         
        A third-party repository for various RPM based distributions is available at: https://copr.fedorainfracloud.org/coprs/jonathanspw/headscale/. The site provides detailed setup and installation instructions.
         
        Nix, NixOS
         
        A Nix package is available as: headscale. See the NixOS package site for installation details.
         
        Gentoo
         
        emerge --ask net-vpn/headscale
 
         
        Gentoo specific documentation is available here.
         
        OpenBSD
         
        Headscale is available in ports. The port installs headscale as system service with rc.d and provides usage instructions upon installation.
         
        pkg_add headscale
 
         
         
          
          
          
         
         
         
            
\ No newline at end of file
diff --git a/development/setup/install/container/index.html b/development/setup/install/container/index.html
index e3727efb..7c1805c0 100644
--- a/development/setup/install/container/index.html
+++ b/development/setup/install/container/index.html
@@ -1,4 +1,4 @@
- Container - Headscale      
         
          
          
         
          
         
         
         
         
          
         
         
         
         
         
          
         
         
         
         
               
        Running headscale in a container
         
         
        Community documentation
         
        This page is not actively maintained by the headscale authors and is written by community members. It is not verified by headscale developers.
         
        It might be outdated and it might miss necessary steps.
         
         
        This documentation has the goal of showing a user how-to set up and run headscale in a container. Docker is used as the reference container implementation, but there is no reason that it should not work with alternatives like Podman. The Docker image can be found on Docker Hub here.
         
        Configure and run headscale
         
           
        1.  
          Prepare a directory on the host Docker node in your directory of choice, used to hold headscale configuration and the SQLite database:
           
          mkdir -p ./headscale/config
+ Container - Headscale      
           
            
            
           
            
           
           
           
           
            
           
           
           
           
           
            
           
           
           
           
                 
          Running headscale in a container
           
           
          Community documentation
           
          This page is not actively maintained by the headscale authors and is written by community members. It is not verified by headscale developers.
           
          It might be outdated and it might miss necessary steps.
           
           
          This documentation has the goal of showing a user how-to set up and run headscale in a container. Docker is used as the reference container implementation, but there is no reason that it should not work with alternatives like Podman. The Docker image can be found on Docker Hub here.
           
          Configure and run headscale
           
             
          1.  
            Prepare a directory on the host Docker node in your directory of choice, used to hold headscale configuration and the SQLite database:
             
            mkdir -p ./headscale/config
 cd ./headscale
 
             
            2.  
          2.  
            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
 sudo nano /etc/headscale/config.yaml
diff --git a/development/setup/install/official/index.html b/development/setup/install/official/index.html
index 884592d1..633b0f9a 100644
--- a/development/setup/install/official/index.html
+++ b/development/setup/install/official/index.html
@@ -1,4 +1,4 @@
- Official releases - Headscale      
             
              
              
             
              
             
             
             
             
              
             
             
             
             
             
              
             
             
             
             
                   
            Official releases
             
            Official releases for headscale are available as binaries for various platforms and DEB packages for Debian and Ubuntu. Both are available on the GitHub releases page.
              
            It is recommended to use our DEB packages to install headscale on a Debian based system as those packages configure a user to run headscale, provide a default configuration and ship with a systemd service file. Supported distributions are Ubuntu 20.04 or newer, Debian 11 or newer.
             
               
            1.  
              Download the latest headscale package 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!)
+ Official releases - Headscale      
               
                
                
               
                
               
               
               
               
                
               
               
               
               
               
                
               
               
               
               
                     
              Official releases
               
              Official releases for headscale are available as binaries for various platforms and DEB packages for Debian and Ubuntu. Both are available on the GitHub releases page.
                
              It is recommended to use our DEB packages to install headscale on a Debian based system as those packages configure a user to run headscale, provide a default configuration and ship with a systemd service file. Supported distributions are Ubuntu 20.04 or newer, Debian 11 or newer.
               
                 
              1.  
                Download the latest headscale package 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!)
 HEADSCALE_ARCH="" # Your system architecture, e.g. "amd64"
 wget --output-document=headscale.deb \
  "https://github.com/juanfont/headscale/releases/download/v${HEADSCALE_VERSION}/headscale_${HEADSCALE_VERSION}_linux_${HEADSCALE_ARCH}.deb"
diff --git a/development/setup/install/source/index.html b/development/setup/install/source/index.html
index 0e9084f0..ee2db787 100644
--- a/development/setup/install/source/index.html
+++ b/development/setup/install/source/index.html
@@ -1,4 +1,4 @@
- Build from source - Headscale      
                 
                  
                  
                 
                  
                 
                 
                 
                 
                  
                 
                 
                 
                 
                 
                  
                 
                 
                 
                 
                       
                Build from source
                 
                 
                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.
                 
                OpenBSD
                 
                Install from source
                 
                # Install prerequistes
+ Build from source - Headscale      
                 
                  
                  
                 
                  
                 
                 
                 
                 
                  
                 
                 
                 
                 
                 
                  
                 
                 
                 
                 
                       
                Build from source
                 
                 
                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.
                 
                OpenBSD
                 
                Install from source
                 
                # Install prerequistes
 pkg_add go
 
 git clone https://github.com/juanfont/headscale.git
diff --git a/development/setup/requirements/index.html b/development/setup/requirements/index.html
index dd6ea278..5785e7ba 100644
--- a/development/setup/requirements/index.html
+++ b/development/setup/requirements/index.html
@@ -1 +1 @@
- Requirements and Assumptions - Headscale      
                 
                  
                  
                 
                  
                 
                 
                 
                 
                  
                 
                 
                 
                 
                 
                  
                 
                 
                 
                 
                       
                Requirements
                 
                Headscale should just work as long as the following requirements are met:
                 
                   
                • A server with a public IP address for headscale. A dual-stack setup with a public IPv4 and a public IPv6 address is recommended.
                  •  
                • Headscale is served via HTTPS on port 4431.
                  •  
                • A reasonably modern Linux or BSD based operating system.
                  •  
                • A dedicated user account to run headscale.
                  •  
                • A little bit of command line knowledge to configure and operate headscale.
                  •  
                 
                Assumptions
                 
                The headscale documentation and the provided examples are written with a few assumptions in mind:
                 
                   
                • Headscale is running as system service via a dedicated user headscale.
                  •  
                • The configuration is loaded from /etc/headscale/config.yaml.
                  •  
                • SQLite is used as database.
                  •  
                • The data directory for headscale (used for private keys, ACLs, SQLite database, …) is located in /var/lib/headscale.
                  •  
                • URLs and values that need to be replaced by the user are either denoted as <VALUE_TO_CHANGE> or use placeholder values such as headscale.example.com.
                  •  
                 
                Please adjust to your local environment accordingly.
                 
                 
                 
                   
                1.  
                  The Tailscale client assumes HTTPS on port 443 in certain situations. Serving headscale either via HTTP or via HTTPS on a port other than 443 is possible but sticking with HTTPS on port 443 is strongly recommended for production setups. See issue 2164 for more information. ↩
                   
                  2.  
                 
                 
                 
                  
                  
                  
                 
                 
                 
                    
\ No newline at end of file
+ Requirements and Assumptions - Headscale      
                 
                  
                  
                 
                  
                 
                 
                 
                 
                  
                 
                 
                 
                 
                 
                  
                 
                 
                 
                 
                       
                Requirements
                 
                Headscale should just work as long as the following requirements are met:
                 
                   
                • A server with a public IP address for headscale. A dual-stack setup with a public IPv4 and a public IPv6 address is recommended.
                  •  
                • Headscale is served via HTTPS on port 4431.
                  •  
                • A reasonably modern Linux or BSD based operating system.
                  •  
                • A dedicated user account to run headscale.
                  •  
                • A little bit of command line knowledge to configure and operate headscale.
                  •  
                 
                Assumptions
                 
                The headscale documentation and the provided examples are written with a few assumptions in mind:
                 
                   
                • Headscale is running as system service via a dedicated user headscale.
                  •  
                • The configuration is loaded from /etc/headscale/config.yaml.
                  •  
                • SQLite is used as database.
                  •  
                • The data directory for headscale (used for private keys, ACLs, SQLite database, …) is located in /var/lib/headscale.
                  •  
                • URLs and values that need to be replaced by the user are either denoted as <VALUE_TO_CHANGE> or use placeholder values such as headscale.example.com.
                  •  
                 
                Please adjust to your local environment accordingly.
                 
                 
                 
                   
                1.  
                  The Tailscale client assumes HTTPS on port 443 in certain situations. Serving headscale either via HTTP or via HTTPS on a port other than 443 is possible but sticking with HTTPS on port 443 is strongly recommended for production setups. See issue 2164 for more information. ↩
                   
                  2.  
                 
                 
                 
                  
                  
                  
                 
                 
                 
                    
\ No newline at end of file
diff --git a/development/setup/upgrade/index.html b/development/setup/upgrade/index.html
index 7e75f716..8d302cb5 100644
--- a/development/setup/upgrade/index.html
+++ b/development/setup/upgrade/index.html
@@ -1 +1 @@
- Upgrade - Headscale      
                 
                  
                  
                 
                  
                 
                 
                 
                 
                  
                 
                 
                 
                 
                 
                  
                 
                 
                 
                 
                       
                Upgrade an existing installation
                 
                An existing headscale installation can be updated to a new version:
                 
                   
                • Read the announcement on the GitHub releases page for the new version. It lists the changes of the release along with possible breaking changes.
                  •  
                • Create a backup of your database.
                  •  
                • Update headscale to the new version, preferably by following the same installation method.
                  •  
                • Compare and update the configuration file.
                  •  
                • Restart headscale.
                  •  
                 
                 
                  
                  
                  
                 
                 
                 
                    
\ No newline at end of file
+ Upgrade - Headscale      
                 
                  
                  
                 
                  
                 
                 
                 
                 
                  
                 
                 
                 
                 
                 
                  
                 
                 
                 
                 
                       
                Upgrade an existing installation
                 
                An existing headscale installation can be updated to a new version:
                 
                   
                • Read the announcement on the GitHub releases page for the new version. It lists the changes of the release along with possible breaking changes.
                  •  
                • Create a backup of your database.
                  •  
                • Update headscale to the new version, preferably by following the same installation method.
                  •  
                • Compare and update the configuration file.
                  •  
                • Restart headscale.
                  •  
                 
                 
                  
                  
                  
                 
                 
                 
                    
\ No newline at end of file
diff --git a/development/sitemap.xml b/development/sitemap.xml
index a71471fc..12d737d2 100644
--- a/development/sitemap.xml
+++ b/development/sitemap.xml
@@ -2,118 +2,118 @@
 
     
          https://juanfont.github.io/headscale/development/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/about/clients/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/about/contributing/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/about/faq/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/about/features/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/about/help/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/about/releases/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/about/sponsor/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/ref/acls/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/ref/configuration/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/ref/dns/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/ref/exit-node/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/ref/oidc/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/ref/remote-cli/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/ref/tls/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/ref/integration/reverse-proxy/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/ref/integration/tools/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/ref/integration/web-ui/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/setup/requirements/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/setup/upgrade/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/setup/install/cloud/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/setup/install/community/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/setup/install/container/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/setup/install/official/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/setup/install/source/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/usage/getting-started/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/usage/connect/android/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/usage/connect/apple/
-         2024-12-08
+         2024-12-09
     
     
          https://juanfont.github.io/headscale/development/usage/connect/windows/
-         2024-12-08
+         2024-12-09
     
 
\ No newline at end of file
diff --git a/development/sitemap.xml.gz b/development/sitemap.xml.gz
index adc477d759761595232a7cba61a2aa06dbc7eb23..220964be250038a57e6218f0094780fb8da5a422 100644
GIT binary patch
delta 392
zcmV;30eAkj1GNJOABzYG05evR2OodKIwbCGPq00JBGEPnSyV-;PTziX6AZg=2kK%=
zps5cON&P;*-qv(@hssF#(mfBy?f^MZ#5`ZRpFh6$U%S`w>D+2!kb@d$zI2O7`R3fV
zZ3Cmg>I)B4XUAdD3A@LlI}R`1_;k>*JGj4nj&q_g?p|2k{AxZ=lx3JvmUe#~klX@3
za_|XUgm*|(R>$kIG&EDFa7hWKfb8RW9`1J`?K$VA@Emf;zB~5upJ&X
zt$1yshh_$9@^5xnz)P!O=foCB#SBb^1fC5=hYMwv8r~k$5l!Kb5tAVNZUX3`Ok+Y?D!kP)dGtQ5dZ)k_P5Ib

delta 392
zcmV;30eAkj1GNJOABzYGfZPBO!tSx?j>Fe(d^+gZ9o*kO$2n6NcQ34Nel?F1p$v19rCooAL~a2e
zIrt1N!aHOtE1g|rxR8@h*ba}H
z)^u&6hh_$9@^5xnz)P!O=foDs#SBb^44w@|hYKN7HNaD0az11>f}({!rMXov+O3T+
zMYIwfxFzY4A{gPJ6oV0z3M&f<^m=g_0TMGcl~9u}0Ul_zq$zJiq}`!f(P)|IO?RGz
zEIwxyv(%zJDq7cuNj?mcq4 Android - Headscale      
                 
                  
                  
                 
                  
                 
                 
                 
                 
                  
                 
                 
                 
                 
                 
                  
                 
                 
                 
                 
                       
                Connecting an Android client
                 
                This documentation has the goal of showing how a user can use the official Android Tailscale client with headscale.
                 
                Installation
                 
                Install the official Tailscale Android client from the Google Play Store or F-Droid.
                 
                Configuring the headscale URL
                 
                   
                • Open the app and select the settings menu in the upper-right corner
                  •  
                • Tap on Accounts
                  •  
                • In the kebab menu icon (three dots) in the upper-right corner select Use an alternate server
                  •  
                • Enter your server URL (e.g https://headscale.example.com) and follow the instructions
                  •  
                 
                 
                  
                  
                  
                 
                 
                 
                    
\ No newline at end of file
+ Android - Headscale      
                 
                  
                  
                 
                  
                 
                 
                 
                 
                  
                 
                 
                 
                 
                 
                  
                 
                 
                 
                 
                       
                Connecting an Android client
                 
                This documentation has the goal of showing how a user can use the official Android Tailscale client with headscale.
                 
                Installation
                 
                Install the official Tailscale Android client from the Google Play Store or F-Droid.
                 
                Configuring the headscale URL
                 
                   
                • Open the app and select the settings menu in the upper-right corner
                  •  
                • Tap on Accounts
                  •  
                • In the kebab menu icon (three dots) in the upper-right corner select Use an alternate server
                  •  
                • Enter your server URL (e.g https://headscale.example.com) and follow the instructions
                  •  
                 
                 
                  
                  
                  
                 
                 
                 
                    
\ No newline at end of file
diff --git a/development/usage/connect/apple/index.html b/development/usage/connect/apple/index.html
index 8eae9460..ffdc2235 100644
--- a/development/usage/connect/apple/index.html
+++ b/development/usage/connect/apple/index.html
@@ -1,2 +1,2 @@
- Apple - Headscale      
                 
                  
                  
                 
                  
                 
                 
                 
                 
                  
                 
                 
                 
                 
                 
                  
                 
                 
                 
                 
                       
                Connecting an Apple client
                 
                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.
                 
                 
                iOS
                 
                Installation
                 
                Install the official Tailscale iOS client from the App Store.
                 
                Configuring the headscale URL
                 
                   
                • Open Tailscale and make sure you are not logged in to any account
                  •  
                • Open Settings on the iOS device
                  •  
                • Scroll down to the third party apps section, under Game Center or TV Provider
                  •  
                • Find Tailscale and select it
                  •  
                • If the iOS device was previously logged into Tailscale, switch the Reset Keychain toggle to on
                  •  
                • Enter the URL of your headscale instance (e.g https://headscale.example.com) under Alternate Coordination Server URL
                  •  
                • Restart the app by closing it from the iOS app switcher, open the app and select the regular sign in option (non-SSO). It should open up to the headscale authentication page.
                  •  
                • Enter your credentials and log in. Headscale should now be working on your iOS device.
                  •  
                 
                macOS
                 
                Installation
                 
                Choose one of the available Tailscale clients for macOS and install it.
                 
                Configuring the headscale URL
                 
                Command line
                 
                Use Tailscale's login command to connect with your headscale instance (e.g https://headscale.example.com):
                 
                tailscale login --login-server <YOUR_HEADSCALE_URL>
+ Apple - Headscale      
                 
                  
                  
                 
                  
                 
                 
                 
                 
                  
                 
                 
                 
                 
                 
                  
                 
                 
                 
                 
                       
                Connecting an Apple client
                 
                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.
                 
                 
                iOS
                 
                Installation
                 
                Install the official Tailscale iOS client from the App Store.
                 
                Configuring the headscale URL
                 
                   
                • Open Tailscale and make sure you are not logged in to any account
                  •  
                • Open Settings on the iOS device
                  •  
                • Scroll down to the third party apps section, under Game Center or TV Provider
                  •  
                • Find Tailscale and select it
                  •  
                • If the iOS device was previously logged into Tailscale, switch the Reset Keychain toggle to on
                  •  
                • Enter the URL of your headscale instance (e.g https://headscale.example.com) under Alternate Coordination Server URL
                  •  
                • Restart the app by closing it from the iOS app switcher, open the app and select the regular sign in option (non-SSO). It should open up to the headscale authentication page.
                  •  
                • Enter your credentials and log in. Headscale should now be working on your iOS device.
                  •  
                 
                macOS
                 
                Installation
                 
                Choose one of the available Tailscale clients for macOS and install it.
                 
                Configuring the headscale URL
                 
                Command line
                 
                Use Tailscale's login command to connect with your headscale instance (e.g https://headscale.example.com):
                 
                tailscale login --login-server <YOUR_HEADSCALE_URL>
 
                 
                GUI
                 
                   
                • ALT + Click the Tailscale icon in the menu and hover over the Debug menu
                  •  
                • Under Custom Login Server, select Add Account...
                  •  
                • Enter the URL of your headscale instance (e.g https://headscale.example.com) and press Add Account
                  •  
                • Follow the login procedure in the browser
                  •  
                 
                tvOS
                 
                Installation
                 
                Install the official Tailscale tvOS client from the App Store.
                 
                 
                Danger
                 
                Don't open the Tailscale App after installation!
                 
                 
                Configuring the headscale URL
                 
                   
                • Open Settings (the Apple tvOS settings) > Apps > Tailscale
                  •  
                • Under ALTERNATE COORDINATION SERVER URL, select URL
                  •  
                • Enter the URL of your headscale instance (e.g https://headscale.example.com) and press OK
                  •  
                • Return to the tvOS Home screen
                  •  
                • Open Tailscale
                  •  
                • Click the button Install VPN configuration and confirm the appearing popup by clicking the Allow button
                  •  
                • Scan the QR code and follow the login procedure
                  •  
                 
                 
                  
                  
                  
                 
                 
                 
                    
\ No newline at end of file
diff --git a/development/usage/connect/windows/index.html b/development/usage/connect/windows/index.html
index 7b98d3ff..894040a5 100644
--- a/development/usage/connect/windows/index.html
+++ b/development/usage/connect/windows/index.html
@@ -1,4 +1,4 @@
- Windows - Headscale      
                 
                  
                  
                 
                  
                 
                 
                 
                 
                  
                 
                 
                 
                 
                 
                  
                 
                 
                 
                 
                       
                Connecting a Windows client
                 
                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.
                 
                 
                Installation
                 
                Download the Official Windows Client and install it.
                 
                Configuring the headscale URL
                 
                Open a Command Prompt or Powershell and use Tailscale's login command to connect with your headscale instance (e.g https://headscale.example.com):
                 
                tailscale login --login-server <YOUR_HEADSCALE_URL>
+ Windows - Headscale      
                 
                  
                  
                 
                  
                 
                 
                 
                 
                  
                 
                 
                 
                 
                 
                  
                 
                 
                 
                 
                       
                Connecting a Windows client
                 
                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.
                 
                 
                Installation
                 
                Download the Official Windows Client and install it.
                 
                Configuring the headscale URL
                 
                Open a Command Prompt or Powershell and use Tailscale's login command to connect with your headscale instance (e.g https://headscale.example.com):
                 
                tailscale login --login-server <YOUR_HEADSCALE_URL>
 
                 
                Follow the instructions in the opened browser window to finish the configuration.
                 
                Troubleshooting
                 
                Unattended mode
                 
                By default, Tailscale's Windows client is only running when the user is logged in. If you want to keep Tailscale running all the time, please enable "Unattended mode":
                 
                   
                • Click on the Tailscale tray icon and select Preferences
                  •  
                • Enable Run unattended
                  •  
                • Confirm the "Unattended mode" message
                  •  
                 
                See also Keep Tailscale running when I'm not logged in to my computer
                 
                Failing node registration
                 
                If you are seeing repeated messages like:
                 
                [GIN] 2022/02/10 - 16:39:34 | 200 |    1.105306ms |       127.0.0.1 | POST     "/machine/redacted"
 
                 
                in your headscale output, turn on DEBUG logging and look for:
                 
                2022-02-11T00:59:29Z DBG Machine registration has expired. Sending a authurl to register machine=redacted
 
                 
                This typically means that the registry keys above was not set appropriately.
                 
                To reset and try again, it is important to do the following:
                 
                   
                1. Shut down the Tailscale service (or the client running in the tray)
                  2.  
                2. Delete Tailscale Application data folder, located at C:\Users\<USERNAME>\AppData\Local\Tailscale and try to connect again.
                  3.  
                3. Ensure the Windows node is deleted from headscale (to ensure fresh setup)
                  4.  
                4. Start Tailscale on the Windows machine and retry the login.
                  5.  
                 
                 
                  
                  
                  
                 
                 
                 
                    
\ No newline at end of file
diff --git a/development/usage/getting-started/index.html b/development/usage/getting-started/index.html
index 8bbd53ef..ad8f163c 100644
--- a/development/usage/getting-started/index.html
+++ b/development/usage/getting-started/index.html
@@ -1,4 +1,4 @@
- Getting started - Headscale      
                 
                  
                  
                 
                  
                 
                 
                 
                 
                  
                 
                 
                 
                 
                 
                  
                 
                 
                 
                 
                       
                Getting started
                 
                This page helps you get started with headscale and provides a few usage examples for the headscale command line tool headscale.
                 
                 
                Prerequisites
                  
                 
                Getting help
                 
                The headscale command line tool provides built-in help. To show available commands along with their arguments and options, run:
                 
                 
                 
                 
                # Show help
+ Getting started - Headscale      
                 
                  
                  
                 
                  
                 
                 
                 
                 
                  
                 
                 
                 
                 
                 
                  
                 
                 
                 
                 
                       
                Getting started
                 
                This page helps you get started with headscale and provides a few usage examples for the headscale command line tool headscale.
                 
                 
                Prerequisites
                  
                 
                Getting help
                 
                The headscale command line tool provides built-in help. To show available commands along with their arguments and options, run:
                 
                 
                 
                 
                # Show help
 headscale help
 
 # Show help for a specific command