Headscale: Awesome Self-Hosted Tailscale Control Server
Networking has undergone significant transformations in recent years, driven by many open-source projects that present new possibilities. If you are a home lab enthusiast, you may host many self-hosted services in your lab. Accessing these services remotely or when traveling presents challenges and possibly security issues if you open ports to the Internet. Tailscale and its open-source alternative, Headscale, offer unique solutions as we move towards more decentralized and private networks. Let’s look at Headscale, an excellent way to host your Tailscale control server, be self-sufficient with the Tailscale open-source project, and control all aspects of your connectivity.
Table of contents
- What is Tailscale?
- What is Headscale?
- The Value of Open Source in Networking
- Harnessing the Potential of Headscale
- In-depth into Headscale’s Inner Workings
- Installing Headscale – What’s required?
- Practical Example: Setting up a Self-Hosted Tailscale Network
- Frequently Asked Questions
- What are the benefits of a self-hosted Tailscale network?
- Can I use Headscale for my personal use?
- How can I contribute to the Headscale project?
- How secure is Headscale?
- Can Headscale be used on multiple platforms?
- Is it challenging to manage a Headscale network?
- Does Headscale support traffic between clients?
- Wrapping Up
- Other posts you may enjoy
What is Tailscale?
Tailscale is a powerful tool that creates a secure, private network between your devices, regardless of their location. It leverages WireGuard, a modern VPN protocol, to establish encrypted peer-to-peer connections. With the Tailscale network, you gain secure access to your devices and services as if you were on the same local network.
All components of Tailscale are open source, with the exception of the GUI clients for proprietary operating systems like Windows and macOS/iOS, as well as the control server.
Functioning as a central hub for the exchange of Wireguard public keys, the control server is integral to the operation of the Tailscale network. It is responsible for assigning IP addresses to clients, establishing user boundaries, facilitating machine sharing between users, and managing the advertised routes of your nodes.
In Tailscale’s terminology, a “tailnet” refers to a private network assigned to an individual user or an organization by Tailscale. This tailnet is a private space in the network structure designed for secure, managed interactions.
What is Headscale?
Headscale, on the other hand, is an open-source implementation of the Tailscale control server. Developed to give users control over their private networks, Headscale allows users to host their own Tailscale networks. As a completely open-source project, it empowers you to manage and operate your network without relying on Tailscale’s hosted solution.
Headscale aims to equip self-hosting enthusiasts and hobbyists with an open-source server that they can employ for their various projects and labs. It offers a focused implementation, accommodating a single Tailnet. This makes it ideal for personal use or for small open-source organizations.
Headscale features
Headscale boasts a variety of features, which include:
Comprehensive support for fundamental Tailscale features
Customizable DNS
Split DNS capabilities
Node registration functionality
Single-Sign-On facilitated through Open ID Connect
Pre-authenticated keys
Taildrop feature for File Sharing
Access Control Lists for security and permissions management
MagicDNS, a simplified DNS management feature
Capability to support multiple IP ranges within the tailnet
Dual stack compatibility, supporting both IPv4 and IPv6
Routing advertising, encompassing exit nodes
Ephemeral nodes for temporary network members
An embedded DERP server for reliable connectivity.
The Value of Open Source in Networking
The open-source model has been instrumental in developing many innovative networking tools, and Headscale is a prime example of this. As an open-source alternative to Tailscale’s control server, it allows for customization and control that isn’t typically possible with commercial offerings. The fact that it’s an open-source project also allows users to contribute to its development, resulting in a tool that continually evolves and improves based on community input.
Harnessing the Potential of Headscale
Setting up Headscale: The Basics
Headscale operates in sync with the Tailscale clients, managing their access to your private network. Its installation involves creating a config file, typically in a YAML format, where you define key aspects like your server’s IP address, private keys, and more.
Headscale can be set up on multiple operating systems, including Linux and Windows. It ensures that your Tailscale network is secure, efficient, and completely self-hosted.
Notable Features of Headscale
Headscale, being feature complete, supports all Tailscale clients, including their Windows and Android app. This means connecting devices running these operating systems to your Headscale-hosted Tailscale network.
How Headscale Fits in Your Use Case
Whether you are looking to secure your personal data, manage a private network for a project, or even host a larger corporate network, Headscale has valuable tools to offer. With Headscale, you can have direct control over your private network without compromising on security or performance.
Contributing to Headscale: Open Source Collaboration
One of the beautiful aspects of Headscale is that it is a project that invites contribution from its users. Open source code allows users to submit bug reports, suggest features, and even contribute to the project’s development. The growing number of contributors is a testament to the project’s success and the value it offers.
In-depth into Headscale’s Inner Workings
Understanding Headscale’s Architecture
Headscale’s architecture is based around the Tailscale protocol. This protocol is built on WireGuard and uses it to establish encrypted VPN connections between nodes on a network. The role of Headscale is essentially to coordinate these nodes, a feature that’s very valuable for those wanting to self-host their networks.
At the heart of Headscale is its server, which you can host on your own infrastructure. The server is responsible for managing the private keys of the nodes, and it’s crucial for the successful operation of your private network. It’s worth noting that these keys are only used for authentication purposes; they do not have access to your network traffic.
The Headscale Web UI: Simplifying Network Management
A notable addon for Headscale is the Headscale Web UI, a handy tool that offers a graphical interface for managing your Tailscale network. Through the Web UI, you can monitor network activity, manage access to your network, and adjust various settings as per your requirements. This feature makes network management more accessible and user-friendly, especially for those new to the networking world.
You can check out that project here: GitHub – gurucomputing/headscale-ui: A web frontend for the headscale Tailscale-compatible coordination server
Headscale’s Cross-Platform Support
Headscale is designed to support a wide range of platforms. The Headscale server can be set up on various operating systems, including Linux and Windows. Meanwhile, Tailscale clients – which are compatible with Headscale – are available for even more platforms. This means you can connect a wide variety of devices to your self-hosted Tailscale network, making Headscale a highly versatile tool for managing your private network.
Installing Headscale – What’s required?
It is important to note the developer for Headscale makes mention in the Github repository, they do not encourage or support the use of containers or reverse proxies for Headscale. So, this is something to keep in mind.
However, you will find community projects like here: https://headscale.net/running-headscale-container/ that show how to get up and running with Headscale in a Docker container.
So for the purposes of this install walkthrough, I am using an Ubuntu 22.04 virtual machine.
First we need to download the .deb file used for the installation of headscale. To do that, I used the latest version of headscale (at the time of this writing) as an example. Below is the command I used:
wget --output-document=headscale.deb https://github.com/juanfont/headscale/releases/download/v0.22.3/headscale_0.22.3_linux_amd64.deb
Now, we install the package.
sudo dpkg --install headscale.deb
Now we enable the headscale service.
sudo systemctl enable headscale
Now we need to customize the server URL and the listen address.
Start the headscale service and get the status of the service.
sudo systemctl start headscale
systemctl status headscale
Now we need to create a namespace/user. The namespace directive appears to now be deprecated. Even if you issue the namespaces command, you will see it creates a user.
sudo headscale namespaces create <your namespace>
or
sudo headscale users create <your user> 
You can use the following command to list the namespaces/users:
sudo headscale namespaces list
Now we can create a preauthkey to authenticate with a client. As an example, you can use the following to create your preauth key along with the expiration time:
sudo headscale --user <your user/namespace> preauthkeys create --expiration <expiration time>
Installing the Tailscale client and connecting a client to headscale
Now that we have the headscale server running, we can install Tailscale and connect our client. First, let’s install the tailscale client. On an Ubuntu 22.04 workstation, you can use the command:
curl -fsSL https://tailscale.com/install.sh | sh
After the client installation, to connect the client, you can use the command:
sudo tailscale up --login-server <your server URL> --authkey <your authkey generated in the previous step>
Once you connect your client, you can see the connected client with the command:
sudo headscale nodes list 
Practical Example: Setting up a Self-Hosted Tailscale Network
Let’s consider a simple example to demonstrate the practical application of these technologies. Suppose you have a set of devices scattered across various locations – your home PC, your work laptop, a server in a data center, and a mobile device. With Tailscale and Headscale, you can connect these devices into a single Tailnet (Tailscale network), regardless of their geographical locations or the networks they’re connected to.
After setting up the Headscale server on an operating system of your choice and configuring it using the config file, you can install the Tailscale clients on your devices and connect them to your Tailscale network.
Frequently Asked Questions
What are the benefits of a self-hosted Tailscale network?
A self-hosted Tailscale network gives you complete control over your network configuration and data. This ensures higher privacy and allows for custom configuration based on your unique needs.
Can I use Headscale for my personal use?
Absolutely. Headscale is suitable for both personal and professional use. It’s a great tool for managing access to your devices and services securely.
How can I contribute to the Headscale project?
You can contribute to the Headscale project by submitting bug reports, suggesting new features, or even writing code. The project is open source, and contributions from the community are always welcome.
How secure is Headscale?
Headscale, as a self-hosted Tailscale control server, adopts the same high-level security measures as Tailscale. This includes using encryption for all network traffic, securing data in transit. However, the security of a Headscale network is also largely determined by the security measures implemented by the user, including server configurations, access control policies, and the secure handling of private keys.
Can Headscale be used on multiple platforms?
Yes, Headscale is versatile and can be used on various operating systems. Its functionality spans Linux, Windows, macOS, and more. This cross-platform compatibility makes it suitable for diverse environments with different operating systems.
Is it challenging to manage a Headscale network?
setting up and managing a Headscale network requires some technical understanding, its design aims to simplify the management of complex network topologies. Tools like the web UI and config files make it easier to manage the network. An active community and ample documentation are also available to help users navigate any challenges.
Does Headscale support traffic between clients?
Headscale does support traffic between clients. This is one of the features that makes it a powerful tool for creating private networks. However, how the traffic flows – directly between clients or via the server – can depend on the network configuration and settings in the individual client setups.
Wrapping Up
Open-source tools like Tailscale and Headscale are transforming how we manage our networks, offering excellent control, security, and versatility. Whether you’re a hobbyist looking for a convenient way to manage your devices or a business seeking a robust solution for your networking needs, these tools offer significant advantages.
As open-source projects, both Tailscale and Headscale offer the potential for community-driven development, creating continuous improvement and customization opportunities. Headscale, a self-hosted implementation of Tailscale’s control server, is an excellent way for home lab enthusiasts to connect their nodes and access private resources without needing to open ports on their firewall.
I find your tutorial interesting. However, it would be a more comprehensive and complete tutorial if you had included the fact that certain ports needed to be opened in the host system.