How to migrate from Tailscale to NetBird
Export the tailnet, rewrite the policy file as NetBird groups and policies, pilot both clients, move routed networks one at a time, then remove Tailscale.
In short
- NetBird has no importer for the tailnet policy file: groups, tags, grants, subnet routers and exit nodes are rewritten as NetBird groups, policies, networks and exit nodes, rule by rule.
- Tailscale and NetBird both draw addresses from 100.64.0.0/10, so the NetBird range is set to avoid every Tailscale address, and Linux pilots need Tailscale’s CGNAT drop rule turned off.
- Each routed network moves on its own: its NetBird policy is switched on as the Tailscale route is withdrawn, and the reverse is the way back.
- Uninstalling Tailscale does not remove a device from the tailnet, and revoking an auth key does not remove the devices it enrolled: both are removed in the admin console or through the API.
On this page (10)
Moving from Tailscale to NetBird is a re-enrolment and a rewrite, not an import. The two are built the same way: WireGuard tunnels between devices, a coordination service that hands out keys and policy, and relays for the connections that cannot go direct. What changes is who runs the coordination service, and nothing carries across on its own. Every device enrols again with the NetBird client, and NetBird has no importer for the tailnet policy file, so each rule, tag, subnet router and exit node is rewritten as NetBird groups, policies, networks and exit nodes. This guide covers the order we do it in, running both clients on a pilot group, and moving routed networks one at a time.
Why teams move from Tailscale to NetBird
Three reasons come up again and again.
- The coordination service runs where you decide. Tailscale operates the service that holds your device list, your users and your policy file. NetBird’s management, signal and relay servers run on machines you choose, in the country you choose.
- An open-source server with no licence key. The NetBird servers are AGPL-3.0, and the Community Edition needs no licence key and no call to NetBird’s licence service. Its anonymous usage metrics can be switched off in the server configuration.
- No per-user subscription. Tailscale’s paid plans are priced per user. A self-hosted NetBird costs the machines it runs on and its operation, so contractors and service accounts cost nothing extra.
What you give up is real. Tailscale runs the coordination service and its relays for you; with NetBird the relay is yours, in the places you deploy it. Tailscale rejects a policy file whose tests fail, and NetBird has no equivalent. On the Community Edition, peer approval, SCIM provisioning, posture from MDM and EDR tools, traffic-flow logging, audit event streaming and active-active high availability need the NetBird Enterprise Commercial License. And someone has to run the servers, which is the part Pilae takes on.
Step 1: export the tailnet
Take stock from Tailscale itself, so the rewrite starts from what exists rather than from memory.
- Devices and users. On the Machines page of the admin console, the download icon at the top right opens Export devices data to CSV; the Users page has the same for users. Both need the Owner, Admin, Network admin or IT admin role (the user export also accepts Auditor), and both are a snapshot with columns you cannot choose.
- The detail behind them. The Tailscale API returns what the CSV leaves out: each device’s addresses, tags, and advertised and enabled routes, the policy file as written, and the DNS settings. Create an API access token on the Keys page of the admin console.
# The tailnet "-" means the tailnet of the token
export TS_API_KEY=tskey-api-...
api() { curl -s -H "Authorization: Bearer $TS_API_KEY" "https://api.tailscale.com/api/v2/tailnet/-/$1"; }
api 'devices?fields=all' > devices.json # addresses, tags, advertisedRoutes, enabledRoutes, lastSeen
api acl > policy.hujson # the policy file, comments included
api users > users.json
api 'keys?all=true' > keys.json # auth keys, API tokens and OAuth clients
api dns/nameservers > dns-nameservers.json
api dns/split-dns > dns-split.json
From these files, mark four things per device: the tags it carries, the subnets it routes (an exit node advertises the default routes 0.0.0.0/0 and ::/0), whether it is a Tailscale SSH target, and when it was last seen. Devices nobody has seen in months are not enrolled again. The keys list shows which pipelines, containers or scripts enrol devices on their own: each one will need a NetBird setup key.
Step 2: build the NetBird server and choose its range
Settle what is hard to change later before the first device joins.
- The management hostname. Every client is enrolled against it, so choose it once.
- The network range. NetBird gives a new account a random
/16from100.64.0.0/10, the block Tailscale uses too, and changing the range later re-addresses every peer at once. Under Settings, Networks, set a range that contains none of the Tailscale addresses indevices.json. The same page sets the DNS domain your peers’ names end in. - Sign-in. Add Keycloak as an external identity provider under Settings, Identity Providers, with an OpenID Connect client that has client authentication on, the redirect URL NetBird displays, and a
groupsclient scope whose Group Membership mapper has full group path turned off. Then, under Settings, Groups, turn on JWT group sync with thegroupsclaim, and set JWT allow groups if only some people may enrol. Entra ID works the same way, but by default sends group object IDs rather than names. SCIM provisioning needs the commercial licence, so groups arrive in the token at sign-in. - The default policy. A new account has a policy that lets the All group reach the All group. It allows everything, so nothing you write restricts anything until that one is deleted.
Step 3: rewrite the policy file as groups and policies
The policy file is the specification. Read it section by section and decide where each piece goes.
| Tailscale | NetBird |
|---|---|
groups |
Groups from the groups claim, or created in NetBird |
Tags and tagOwners |
Groups placed on servers by their setup key |
grants and acls |
Policies: source and destination groups, protocol, ports |
hosts and ipsets |
Network resources: an address, a subnet or a domain |
| Subnet routers | Networks with routing peers |
autogroup:internet |
Exit nodes |
autoApprovers |
No equivalent: an administrator sets routing peers |
postures and srcPosture |
Posture checks attached to policies |
ssh |
Policies with the NetBird SSH protocol |
tests and sshTests |
No equivalent: a test plan run from pilot machines |
| MagicDNS names | Peer names under your DNS domain |
| Split DNS nameservers | Nameservers with match domains, and custom zones for records |
Policies. Both systems deny by default, and a Tailscale rule only allows, so each one becomes an accepting NetBird policy without reordering. A NetBird policy names source and destination groups, a protocol (all, TCP, UDP, ICMP or NetBird SSH), ports or port ranges, and a direction. One-way is the default to aim for: only the source can open a connection. A destination can also be a network resource, for systems that run no client. Grants that carry application capabilities (app) have no NetBird counterpart, so list them and decide on each with its owner.
Posture. NetBird’s checks on operating system version, client version, country, network range, running processes and device certificates are in the Community Edition. Posture read from Intune, CrowdStrike, SentinelOne and other MDM or EDR tools needs the commercial licence.
SSH. Tailscale SSH rules become policies with the NetBird SSH protocol. Limited access maps each source group to the local users it may log in as. By default NetBird SSH asks the person to sign in through your identity provider when they connect, which is close to Tailscale’s check mode. The SSH server is off by default: it is turned on for each target peer, with netbird up --allow-server-ssh, and in the dashboard. NetBird’s SSH documentation does not cover session recording, so if you rely on Tailscale’s, plan that separately.
Tests. Every accept and deny line in Tailscale’s tests becomes a connection your test plan attempts from a pilot machine in that group, after every policy change. Rules nobody can explain are removed rather than copied: this is the moment to do it.
We write the result as Terraform with NetBird’s provider, so every policy is a reviewed commit:
# Tailscale: { "src": ["group:finance"], "dst": ["tag:erp"], "ip": ["tcp:443"] }
data "netbird_group" "finance" {
name = "finance" # synced from the groups claim at sign-in
}
resource "netbird_group" "erp" {
name = "erp" # replaces tag:erp
}
resource "netbird_setup_key" "erp_servers" {
name = "erp servers"
type = "reusable"
usage_limit = 3
auto_groups = [netbird_group.erp.id]
}
resource "netbird_policy" "finance_to_erp" {
name = "finance to erp"
enabled = true
rule {
name = "https only"
action = "accept"
bidirectional = false
enabled = true
protocol = "tcp"
ports = ["443"]
sources = [data.netbird_group.finance.id]
destinations = [netbird_group.erp.id]
}
}
Step 4: run both clients on a pilot group
Start with the IT team and a few people on each operating system, plus the servers they reach. Tailscale’s own documentation says it usually cannot run beside another VPN without a workaround, and that conflicts occur when both use the same address space. NetBird’s documentation does not cover running beside Tailscale. Three things decide whether it works, and each is tested on every operating system in the pilot before the next wave.
-
Separate addresses. The range chosen in step 2 keeps NetBird peers clear of every Tailscale address. Check it again before each new wave, since new Tailscale devices keep receiving addresses until the end.
-
The Linux drop rule. Tailscale’s Linux client drops traffic from
100.64.0.0/10that does not arrive on its own interface, which includes everything NetBird delivers. Tailscale documents a node attribute that turns the rule off for the devices you target, and advises keeping reverse path filtering on when you use it. Windows and macOS have no such rule."nodeAttrs": [ { "target": ["tag:netbird-pilot"], "attr": ["disable-linux-cgnat-drop-rule"] } ] -
DNS. Both clients install a resolver on the machine, and Tailscale notes that operating systems order resolvers in their own ways, so it cannot guarantee the order in which nameservers are queried. During the pilot, we give NetBird only match-domain nameservers and custom zones, for the internal domains that will move to it, and leave any global nameserver with Tailscale until it is removed. On Linux, NetBird’s match domains need systemd-resolved. Test name resolution on each operating system.
Phones do not run both: iOS and Android allow one VPN at a time, so a pilot phone switches outright. Tailscale’s device approval has a NetBird counterpart, peer approval, but it needs the commercial licence; on the Community Edition, enrolment is controlled by who may sign in (JWT allow groups) and by setup keys with an expiry and a usage limit.
Step 5: roll out the client
When the pilot holds, enrol everyone who needs access, before any network moves.
- Laptops through your MDM. NetBird documents the rollout for Intune, Jamf Pro, Kandji and Group Policy, and covers JumpCloud and other MDMs with the same pattern. Push the configuration first, with
managementURLwritten with its port (https://netbird.example.com:443),disableUpdateSettingsanddisableProfiles, then install the standard MSI or PKG with no arguments. People open NetBird, click Connect and sign in through the browser. Choose one owner for client updates, NetBird’s automatic updates or the MDM, never both. Deploying the client this way is in the Community Edition; it is the MDM posture integration that needs the licence. - Linux laptops have no MDM channel. Your configuration management installs the client and sets the same options with
netbird service installflags. - Servers join with setup keys created under Settings, Setup Keys: one-off, or reusable with a usage limit and an expiry, each placing its peers in the groups that replace their Tailscale tags.
netbird up --management-url https://netbird.example.com:443 --setup-key <key>enrols one. A peer stays enrolled when its key expires or is revoked. - Short-lived workloads that used ephemeral Tailscale keys get ephemeral setup keys, whose peers are removed after a while offline.
- Phones are pointed at your server from the app: on Android, Change Server in the menu; on iOS, the app settings, or the
managementURLkey of NetBird’s iOS MDM policy.
Peer session expiration, under Settings, Authentication, makes every device enrolled through sign-in authenticate again on a schedule, so a disabled account stops connecting at its next expiry. Peers enrolled with a setup key are exempt.
Step 6: move routed networks one at a time
A network that a Tailscale subnet router reaches today moves on its own, once everyone who uses it has NetBird. Each machine must get a route to it from one client only, which is why the NetBird policy stays off until the moment Tailscale withdraws its route.
Moving one routed network, with a way back
- Prepare: A NetBird routing peer in that network, and a Network whose resources and policy are written but switched off.
- Test: A machine without Tailscale reaches the resources through NetBird.
- Switch: The policy goes on; the Tailscale router stops advertising the route.
- Check: People in each group reach what they need, and nothing more.
- Roll back if needed: The policy goes off and the route is advertised again.
- A routing peer per network. In NetBird, a Network lists resources (single addresses, subnets or domains) and the routing peers that forward to them. We put the routing peer on its own machine or virtual machine rather than on the Tailscale router, which keeps the two clients’ firewall rules apart. Several routing peers on one Network give failover. Network Routes, the older feature, is deprecated for everything but exit nodes.
- Least privilege. Resources are not in the All group, so nothing behind a routing peer is reachable without a policy. Prefer single hosts to whole subnets where the old rule allowed less.
- Source addresses. NetBird masquerades routed traffic by default, as Tailscale does. If your Tailscale router ran with
--snat-subnet-routes=falseand a return route for100.64.0.0/10, turn masquerade off on the Linux routing peer and point the return route at the NetBird range instead. - The switch. Turn the NetBird policy on, then run
tailscale set --advertise-routes=on the Tailscale router with the routes it keeps, and remove the moved route fromautoApprovers. Advertising it again is the way back. - Exit nodes are set from the Peers view, with Add Exit Node on a routing peer, distribution groups and a policy from the users’ group to that peer. With Auto Apply on, devices in those groups use it at once; with it off, people choose it in their client. Where Tailscale forced an exit node through a system policy, NetBird’s
disableNetworksMDM key, or the--disable-networksservice flag on Linux, stops people from changing it.
Step 7: remove Tailscale
- Check that nothing still uses it. Every device appears as a NetBird peer, and a fresh device export shows
lastSeenno longer moving for the machines that switched. - Uninstall the client on each machine. On Linux, check that no
ts-inputchain or other Tailscale firewall rule is left behind, because a leftover drop rule still blocks NetBird traffic. Tailscale’s uninstall instructions list the state files to delete on each platform. - Remove the devices from the tailnet. Uninstalling the client does not remove a device. Remove each one from the Machines page, or with
DELETE /api/v2/device/{id}for many at once. - Revoke what can still enrol. Revoke auth keys and API access tokens on the Keys page, and OAuth clients on the Trust credentials page. Revoking an auth key does not remove the devices it enrolled, which is why step 3 comes first.
- Keep a record and end the subscription. Archive the final policy file and exports, then end the plan once the Machines page is empty.
Running NetBird in production
The control plane is small, but every laptop depends on it to join, sign in again and receive policy.
- Management, signal and relay. Traffic runs directly between devices and is relayed only when it cannot, encrypted end to end. The management server is published on port 443, because laptops reach it before they are on any private network, and STUN needs UDP 3478. Running the relay as its own service keeps relayed sessions up while management restarts.
- PostgreSQL, not SQLite. SQLite is the default and handles neither concurrent writes nor a second management instance.
- Backups with the key. The database, the data directory and
config.yaml, which holds the store encryption key, are backed up together. A restore without that key cannot read setup keys or API tokens, and a restored server is only found by clients under the hostname they enrolled with. - Two update paths. The server is upgraded on its own schedule; clients through the MDM or NetBird’s automatic updates.
Pilae operates NetBird this way: PostgreSQL instead of SQLite, the relay as its own service, sign-in through Keycloak or Entra ID, and policies, routes, DNS and posture checks as Terraform in your repository. It runs on a dedicated machine on your premises or in Pilae Cloud, published through the gate on port 443 with UDP 3478 open for STUN. The database, the configuration and the encryption key are backed up daily, encrypted, to an offsite location in the country your contract names, and on Enterprise a restore test every month is recorded in the console. The Pilae Agent tries each upgrade on a copy and applies it in your window once you approve it.
Let Pilae run the move
Pilae runs Tailscale to NetBird migrations at a fixed price: the tailnet export, the server and sign-on, the policy file rewritten as code, the pilot, the client rollout through your MDM, the move of each routed network and the removal of Tailscale. Where you need features of the NetBird Enterprise Commercial License, the licence is held in your name and named in the proposal. Then we operate NetBird for you under a contract that, from the Business plan, includes a monthly availability commitment with service credits. See migration services for what the fixed price covers, or tell us about your tailnet and we will scope it.
Questions
Can NetBird import our Tailscale policy file?
Can Tailscale and NetBird run on the same machine during the move?
Do our device posture rules come across?
Is NetBird open source?
How long does a Tailscale to NetBird migration take?
Let us run the move for you
An inventory, a parallel run and a cutover plan, at a fixed price. Then we operate the app.
- Go deeperSaaS migrationA fixed-scope migration off Google Workspace, Microsoft 365, Zapier, Airtable and ChatGPT to open-source apps, with a parallel run and a cutover plan.
- CheckManaged operationsPatching, daily encrypted backups, monitoring and incident response for your open-source apps, under an SLA with an availability commitment of up to 99.9%.
