An open source, self-hosted implementation of the Tailscale control server
github.com
github.com
The entire premise of Tailscale SaaS builds on creating tunnels around your firewalls, then enabling the user to police what is allowed to be routed through these tunnels in a intuitive and unified way.
Headscale seems to have nailed down the part of bypassing the firewall and doing fancy NAT-traversal, but can they also fulfill the second part by providing enough of their own security to make up for anything they just bypassed, or will they descend to just being a tool for exposing anything to the internet to fuck around with your local network admin? To me, not giving your Tailscale implementation any way for the user to understand or veto what the control server is instructing the clients to do while also not auditing your servers code at all sure seems daring…
I definitely have more time to spend on it now, I have half a work week vs sometime in the evenings or weekends if I had excess energy after having my other job.
Did they really roll-their-own for those functions? I thought this was just a control layer on top of Tailscale’s stock services on the backend, are they facilitating connections with novel methods? Apologies if I’m asking obvious questions, I use ZeroTier pretty regularly, but I am not too familiar with Tailscale.
Also I believe it implements a lower layer of the network stack so more options are supported, though I haven't needed to investigate in detail.
Tailscale is still running for now, but I'm getting closer and closer to decommissioning it and switching entirely to Netbird.
Here's a gh issue for it.
Headscale has been on HN many times.
So here's my proposal: commit to ipv6-only overlay network in the unique local address (ULA) range, then split up the remaining 121 bits into 20 low bits for device addresses (~1M) and 101 high bits that are the hash of the server's public key. Federate by adding the public key of the other instance and use policy and ACLs to manage comms between nodes.
I think it's a nice idea, but the maintainer kradalby said it's out of scope when I brought it up in 2023: https://github.com/juanfont/headscale/issues/1370
It is packaged in openbsd, and that package is the server I am using.
Especially in the unlikely event that you used Nix for the deployment.
> * Does it work well?
Very well! There are some limitations (see link above), but what's implemented is reliable.
> * Do you recommend it?
Yes, provided your requirements fit headscale's capabilities. If you need things like device trust attestation (e.g. Kandji MDM or Crowdstrike Falcon integration), SCIM provisioning, or various other enterprise features you may find it inadequate. If you can afford to pay for Tailscale, you should just use Tailscale because it's really good.
> * Do your users care?
They like it way better than our previous OpenVPN setup, that's for sure. I don't think they care about Headscale vs commercial Tailscale - the backend implementation is largely invisible to them.
> * Is it difficult? Do you have to maintain it or is it basically set it and forget it?
Not hard at all to set up, and it requires little maintenance attention. I have barely had to touch the control plane (other than version upgrades) since setting it up a year ago.
> * What was memorable about setting it up?
We had to do some custom coding to have automatic user offboarding when employees leave the company, and to emulate app connectors / dynamic routing (this is now OSS! https://github.com/singlestore-labs/tailscale-manager).
And I've been contributing to the headscale codebase to smooth out some quirks that affected our SSO integration. The headscale authors have been pretty flexible in welcoming outside contributors.
> * Why did you go for Headscale vs Tailscale or Netbird or some other solution?
vs Tailscale: It was way easier to build this myself than to get funding to use the commercial solution. I'm not good navigating corporate politics, but I am pretty good at building infrastructure and writing code.
vs Netbird: Mostly because I already liked Tailscale from using it at home, I like its implementation, and I like the way Tailscale (the company) have behaved. The handful of folks I know who work there are people I deeply respect.
- How much effort do you put into key management compared to plain WireGuard?
- How automated is the onboarding process; do you generate and hand over keys?
- How do you cope without the commercial Tailscale dashboard?
- Do you run some kind of dashboard or metrics system?
- How long did it take to set up?
- Were there any gotchas?There are a couple open source dashboard options but right now only this one comes to mind: https://github.com/tale/headplane
The one I've deployed is https://github.com/gurucomputing/headscale-ui, which is basic but does what I need.
Less effort than plain wireguard; the only key management I do is for non-human clients
> - How automated is the onboarding process; do you generate and hand over keys?
Fully automated. Auth is done via OIDC to my company's SSO provider, so users can enroll their own machines without IT involvement.
> - How do you cope without the commercial Tailscale dashboard?
I don't really miss it. The headscale CLI tool is pretty good, and I use one of the headscale web UI projects (three are several: https://headscale.net/stable/ref/integration/web-ui/?h=web) for quick access to a few features (https://github.com/gurucomputing/headscale-ui)
> - Do you run some kind of dashboard or metrics system?
Yes, I scrape headscale's Prometheus metrics endpoint and have put together a simple Grafana dashboard. The metrics it emits are somewhat limited, but enough to keep an eye on its health.
> - How long did it take to set up?
I had a prototype up and running on Kubernetes with OIDC integration and a web UI in about 1 day of hacking. Going into full production took a few months, but the majority of that time was about planning the migration of all the existing users from OpenVPN.
Come to think of it, maybe I should share my terraform modules for deploying it.
> - Were there any gotchas?
A few, yeah:
- Setting up mobile clients is a bit fiddly, because they hide the "connect to a non-default control plane URL" under a debug menu. The mac and windows apps are similar - it's too easy for users to accidentally try to connect to tailscale.com instead of your headscale instance. If you have the ability to deploy MDM profiles (mac) or windows registry tweaks this is easy to fix, and the headscale server will even generate the configs for you.
- The headscale control plane doesn't support any kind of HA or replication. This doesn't disqualify it since tailscale can handle brief control plane outages without breaking the network, but it's likely to be a concern for serious enterprise users. It's possible to use an external Postgres database, so you can at least replicate data that way, but only one headscale server replica can be active at a time because they don't share runtime state.
- The tailscale API is not fully implemented, so you can't use things like the tailscale Kubernetes operator.
- Some features are missing: tailscale funnel, tailscale serve, app connectors, `autogroup:self` ACLs, SCIM provisioning, SSO group membership sync, and I forget what else. These may or may not be important to you.
For app connectors, I wrote an app to emulate the core functionality: https://github.com/singlestore-labs/tailscale-manager (it's in Haskell, but deployers don't need to care about that)
It's possible to implement group sync with some custom scripting - a python app to scrape your LDAP (or whatever) and generate tailscale ACLs isn't hard to write. But you do have to write it.
`autogroup:self` might be a big deal - you would need this if you want to stop users from seeing or connecting directly to each other's devices. I think there is an implementation of this coming in the next release of headscale.
Summary: headscale is great if you have relatively simple needs and can't afford to pay for Tailscale. You will probably outgrow it if you're running a serious business and need to comply with fancy audit requirements.
We considered it as well but there was a feature missing that meant we couldn’t use it for one of our main requirements. Had that not been the case, we’d have rolled it out.
Sorry I can't provide any more details but I really don't remember the specifics. We were in touch with Tailscale engineers and they offered some workarounds that we had already worked out but that wouldn't help us achieve what we were after.
We are still running the old headscale, because we have some integrations that will need to be ported to the new control plane. According to "headscale node list | wc" we have ~250 nodes, most of them are servers.
One thing I really don't love about tailscale some of the magic it does with the routing tables and adding firewall rules, but it has mostly not been an issue. Tailscale has worked really quite well.
The moment the inevitable enshitification will start at Tailscale, this feature will go away.
I’m saying this as a currently super happy Tailscale customer who was burned multiple times in the past by other companies being sold or running out of VC money
[1]: they have three: https://tailscale.com/kb/1065/macos-variants
"This repository contains the majority of Tailscale's open source code. Notably, it includes the tailscaled daemon and the tailscale CLI tool. The tailscaled daemon runs on Linux, Windows, macOS, and to varying degrees on FreeBSD and OpenBSD. The Tailscale iOS and Android apps use this repo's code, but this repo doesn't contain the mobile GUI code."
and
"The macOS, iOS, and Windows clients use the code in this repository but additionally include small GUI wrappers. The GUI wrappers on non-open source platforms are themselves not open source."
Moreover, there's https://github.com/tailscale/tailscale-chocolatey to aid the build process. I haven't built it or run it.
On the other hand, while I suppose the Windows app is probably reasonably straightforward to replicate, I guess it would be much harder to produce an iOS or Android app because of the vagaries of mobile programming.
Android client is open source (and you can get in from F-Droid, even), so that only leaves iOS I guess.
*In my perfect world everybody would care about open source, but the evidence is pretty clear that only a tiny minority of people actually do, even among engineers
on iOS you also need a special entitlement that's only available on specific request and only to known developers, so practically impossible for any open source project to acquire.
The reason I can't use Tailscale at work is because it routes traffic through servers we can't control.
I would _love_ to use tailscale at work. It would solve so many problems. I am okay with being forced to open ports. But tunneling traffic through them is extremely worrysome.
yes. Battery usage is super bad, mainly because of their DNS features which forces every DNS resolution to go through their network extension. At least recent updates have stopped the background power usage when you disconnect from the network in the app.
>But tunneling traffic through them is extremely worrysome.
it only does that in case of super bad NATs that make the usual NAT traversal techniques impossible. And presumably, the traffic is end-to-end-encrypted, so it doesn't matter if they have to be in the loop.
If you don't trust them to properly end-to-end encrypt, then it really doesn't matter whether they are in the loop for forwarding a packet or not because if you don't trust them to encrypt properly, all bets are off to begin with.
If you trust them however, it doesn't matter where the traffic is flowing through because only the intended machine is able to decrypt it.
I’m using their MagicDNS feature with three domains and I think that’s the reason
You can run your own DERP servers and exclude the Tailscale ones even if you don’t run your own Headscale server: https://tailscale.com/kb/1118/custom-derp-servers
That feels right to me. Headscale is mostly used by home labbers and small hobby users, it competes with self-hosted OpenVPN and WireGuard, not Pulsesecure, Cisco Anyconnect or GlobalProtect. It's a way to introduce Tailscale to people who love to try new shiny tech in their spare time, but don't want to give up control over their infrastructure.
Those people will then bring their Tailscale expertise and enthusiasm to work. Work really doesn't like managing IT infrastructure unless it's one of their core competencies.
Sure, some companies will actually choose Headscale over Tailscale proper, but I suspect that's a small minority (especially if you take company size and the money involved into account). That's just cost of revenue, not unlike Facebook advertising or billboards on the side of a road in Silicon Valley.
I have the same memory. But they may not feel that way forever. Many a company started by attracting developers with a generous free tier or open-source offering, then started to clamp down once the going got tough.
Heck, it happened to one of Tailscale's competitors, ZeroTier, which used to release their client software under GPLv3 but eventually switched to BSL.
People sometimes dismiss Tailscale as "just" a WireGuard orchestrator, but it's actually much more than that - From a product perspective, WireGuard is just an implementation detail.
I opted for Netbird myself because Headscale's UI felt too basic for me back then. Has that improved over the years probably?
In terms of stability, Netbird has been pretty good for me. I've been using Netbird as the backhaul network for my laptop, phone and inter-site k3s cluster for several years without major issues.
One major downside of Netbird is that its Android client can be quite a battery drainer [1]. (It keeps your fingers warm during winter, though!) As for Tailscale, it offers some neat features like Funnel, which is missing in Netbird, but in my case, covered by DNS and k8s Ingress.
Tailscale or having Headscale hosted somewhere else allows you to do that.
This statement sugggests that publishing the Headscale control server source code is not enough to allow the user to "understand or veto what the control server is instructing the clients to do".
If using the Headscale control server, the user can "understand or veto" anything "the control server is instructing the clients to do". This may be accomplished by reading, editing and compiling the source code.
If using the Tailscale control server, the user can only "understand or veto what the control server is instruction the clients to do" to the extent that the Tailscale company permits. The user is prohibited from editing or compiling the source code.
Not all users want the option to read, edit and compile third party software that they use. Some users may be comfortable relying on the ongoing assurances of companies funded by Silicon Valley VC. For those users that want the option of 100% open source projects, not dependent on venture capital, Headscale can be useful.
The author of Headscale calls the Tailscale coordination server "essentially a shared dropbox for public keys".
It's semi-frequent in my case, and it's painful every time it does that since Tailscale's official DERP servers are very slow (they seem to have some aggressive QoS). It would be nice if Tailscale supported using regular TURN servers so I could just use one of the hosted solutions.
Finding a cloud or VPS provider with free or cheap bandwidth (egress and ingress) is likely the biggest issue.