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.

Start with one workloadThe steps

Written for
The engineer who will do the work
Or run by Pilae
At a fixed price, then operated

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.

  1. 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.
  2. 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 /16 from 100.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 in devices.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 groups client scope whose Group Membership mapper has full group path turned off. Then, under Settings, Groups, turn on JWT group sync with the groups claim, 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.

  1. 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.

  2. The Linux drop rule. Tailscale’s Linux client drops traffic from 100.64.0.0/10 that 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"] }
    ]
  3. 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 managementURL written with its port (https://netbird.example.com:443), disableUpdateSettings and disableProfiles, 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 install flags.
  • 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 managementURL key 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

  1. Prepare: A NetBird routing peer in that network, and a Network whose resources and policy are written but switched off.
  2. Test: A machine without Tailscale reaches the resources through NetBird.
  3. Switch: The policy goes on; the Tailscale router stops advertising the route.
  4. Check: People in each group reach what they need, and nothing more.
  5. Roll back if needed: The policy goes off and the route is advertised again.
  1. 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.
  2. 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.
  3. Source addresses. NetBird masquerades routed traffic by default, as Tailscale does. If your Tailscale router ran with --snat-subnet-routes=false and a return route for 100.64.0.0/10, turn masquerade off on the Linux routing peer and point the return route at the NetBird range instead.
  4. 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 from autoApprovers. Advertising it again is the way back.
  5. 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 disableNetworks MDM key, or the --disable-networks service flag on Linux, stops people from changing it.

Step 7: remove Tailscale

  1. Check that nothing still uses it. Every device appears as a NetBird peer, and a fresh device export shows lastSeen no longer moving for the machines that switched.
  2. Uninstall the client on each machine. On Linux, check that no ts-input chain 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.
  3. 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.
  4. 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.
  5. 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?

No. NetBird documents no importer for the tailnet policy file, and its access model is built differently: groups, one-way or two-way policies between groups, and networks with routing peers. Each rule is rewritten by hand, ideally as Terraform with the NetBird provider. The exported policy file is still the specification you rewrite from, and its tests become your test plan.

Can Tailscale and NetBird run on the same machine during the move?

On laptops and servers it can work, but neither vendor documents the pair, so it is tested on each operating system in the pilot. Both draw addresses from 100.64.0.0/10, so the NetBird range is chosen to avoid every Tailscale address, and on Linux, Tailscale's firewall drops traffic from that block arriving on any other interface until its disable-linux-cgnat-drop-rule node attribute is set. iOS and Android run one VPN at a time, so phones switch outright.

Do our device posture rules come across?

As rules, yes; as configuration, no. NetBird posture checks on operating system version, client version, country, network range, running processes and device certificates are in the Community Edition and are attached to policies. Posture read from an MDM or EDR tool, such as Intune, CrowdStrike or SentinelOne, needs the NetBird Enterprise Commercial License.

Is NetBird open source?

Yes. The clients are BSD-3-Clause and the management, signal and relay servers are AGPL-3.0, both OSI-approved licences. The Community Edition has no licence key and no time limit. Active-active high availability, SCIM provisioning, EDR and MDM integrations, traffic-flow logging, audit event streaming and peer approval need the NetBird Enterprise Commercial License, held in your name if you need them.

How long does a Tailscale to NetBird migration take?

It depends on the length of the policy file, the number of routed networks and how your laptops are managed, not on the number of devices: an MDM installs the client everywhere at once, while every rule and network is moved and tested on its own. The export in step 1 settles the scope, and Pilae quotes the move at a fixed price once it is done.

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.

Start with one workload

  • 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%.