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 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 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: https://github.com/juanfont/headscale/blob/main/config-example.yaml
- Version 0.23.0: https://github.com/juanfont/headscale/blob/v0.23.0/config-example.yaml
# Development version
+ Configuration - Headscale Configuration¶
- Headscale loads its configuration from a YAML file
- It searches for
config.yaml in the following paths: /etc/headscale$HOME/.headscale- the current working directory
- 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: https://github.com/juanfont/headscale/blob/main/config-example.yaml
- Version 0.23.0: https://github.com/juanfont/headscale/blob/v0.23.0/config-example.yaml
# 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.
-
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.
-
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:
If the node is already registered, it can advertise exit capabilities like this:
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:
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:
and to expire a key:
Download and configure headscale¶
-
Download the headscale binary from GitHub's release page. Make sure to use the same version as on the server.
-
Put the binary somewhere in your PATH, e.g. /usr/local/bin/headscale
-
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.
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.
- Click the following prebuilt template:
- Click "Deploy Application" on the template page to start deployment. Upon completion, two applications appear: headscale, and one of its web interfaces.
- Once deployment concludes, click 'Details' on the headscale application page to navigate to the application's details.
- 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.
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.
- Click the following prebuilt template:
- Click "Deploy Application" on the template page to start deployment. Upon completion, two applications appear: headscale, and one of its web interfaces.
- Once deployment concludes, click 'Details' on the headscale application page to navigate to the application's details.
- 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.
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.
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.
Arch Linux¶
Arch Linux offers a package for headscale, install via:
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¶
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.
\ 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¶
-
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¶
-
Prepare a directory on the host Docker node in your directory of choice, used to hold headscale configuration and the SQLite database:
-
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.
Using packages for Debian/Ubuntu (recommended)¶
It is recommended to use our DEB packages to install headscale on a Debian based system as those packages configure a 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.
-
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.
Using packages for Debian/Ubuntu (recommended)¶
It is recommended to use our DEB packages to install headscale on a Debian based system as those packages configure a 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.
-
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.
-
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. ↩
\ 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.
-
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. ↩
\ 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 adc477d7..220964be 100644
Binary files a/development/sitemap.xml.gz and b/development/sitemap.xml.gz differ
diff --git a/development/usage/connect/android/index.html b/development/usage/connect/android/index.html
index ca0e2292..9fe7b72e 100644
--- a/development/usage/connect/android/index.html
+++ b/development/usage/connect/android/index.html
@@ -1 +1 @@
- 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