Tailscale on UniFi OS

This repo provides the scripts needed to install and run Tailscale on your UniFi Cloud Gateways. It provides a persistent service, automatic updates, and a default configuration which works well on most UniFi Cloud Gateways out of the box.

Installation

1. Run the install.sh script to install the latest version of the Tailscale UniFi package on your device.

   # Install the latest version of Tailscale UniFi
   curl -sSLq https://raw.githubusercontent.com/SierraSoftworks/tailscale-unifi/main/install.sh | sh

2. Run tailscale up to start Tailscale.

3. Follow the on-screen steps to configure Tailscale and connect it to your network.

4. Confirm that Tailscale is working by running tailscale status

Compatibility

Tip

You can confirm your UniFi OS (UOS) version by running /usr/bin/ubnt-device-info firmware_detail

This package is compatible with UniFi OS 2.x or later and works on the following UniFi families:

• Any variant of the UniFi Cloud Gateway family
• Any variant of the UniFi Control Plane family
• Any variant of the UniFi Independent Gateway family
• Any UniFi device running UniFi OS 2.x or later and not listed above or below

Note

These devices are supported only in userspace networking mode, because their kernel does not support the required modules.

• Any variant of the UniFi Next-Gen NVR family
• Any variant of the UniFi Next-Gen Storage family

Important

This package is NOT compatible with these UniFi device variants:

• Any variant of the UniFi Cloud Key Gen 1 (UCK-G1)
• Any variant of the UniFi Security Gateway (USG)
• Any variant of the UniFi Travel Router (UTR)
• Any variant of a UniFi device running BusyBox
• Any variant of a UniFi device running UniFi OS 1.x (Legacy OS w/ Podman)
• Any variant of a UniFi device that has reached end-of-life (EoL) and is not listed above

We expect this to work on most UniFi devices, but if you run into any problems, please open an issue and include the device you are running on, the UniFi OS version you are running, and the steps you took to install Tailscale, along with any errors you encountered.

Warning

This package is no longer compatible with UniFi OS 1.x (Legacy OS w/ Podman). If you cannot upgrade to the latest stable UniFi OS version, use the latest v2.x release from the legacy branch of this repository. We no longer maintain support for UniFi OS 1.x.

Management

Configuring Tailscale

You can configure Tailscale using the normal tailscale up options; it should be on your path after installation.

tailscale up --advertise-routes=10.0.0.0/24 --advertise-exit-node

Restarting Tailscale

Tailscale is managed using systemd and the tailscaled service (in the same way as any other Linux system). You can restart it using the following command.

systemctl restart tailscaled

Upgrading Tailscale

Upgrading Tailscale on UniFi OS can be done with apt or the manage.sh helper script.

Using apt

apt update && apt install -y tailscale

Using manage.sh

/data/tailscale/manage.sh update

# Or, if you are connected over Tailscale and want to run the update anyway
nohup /data/tailscale/manage.sh update!

Remove Tailscale

To remove Tailscale, run the following command.

/data/tailscale/manage.sh uninstall

Contributing

If you have an idea for how this can be improved, please create a PR, and we’ll be happy to incorporate the changes.

Frequently Asked Questions

How do I configure environment variables for tailscaled?

Add any TS_ environment variables to /data/tailscale/tailscale-env. For example:

TS_TUN_DISABLE_TCP_GRO=1

Then run /data/tailscale/manage.sh install. The installer replaces the managed environment section in /etc/default/tailscaled (and removes/overwrites any existing TS_* entries there) and restarts the tailscaled service with the new configuration. Removing a TS_ entry from tailscale-env and running the installer again also removes it from the managed section.

How do I advertise routes?

Set your Tailscale configuration as you would on any other machine.

# Specify the routes you'd like to advertise using their CIDR notation
tailscale up --advertise-routes="10.0.0.0/24,192.168.0.0/24"

Can I automatically route traffic from machines on my local network to Tailscale endpoints?

Yes! As of January 30, 2025, two changes to Tailscale made this possible. Much credit goes to @tomvoss and @jasonwbarnett, who contributed significant effort to the initial implementation, detailed in this GitHub discussion. Before continuing, review Tailscale’s subnet router documentation and make sure you understand subnet routers independently of UniFi OS.

Prerequisites

Note

You do not need to manually enable net.ipv4.ip_forward on your UniFi OS device, as it is enabled by default. If you want to confirm its status, run:

sysctl net.ipv4.ip_forward

Warning

Make these changes over a direct network connection to your UniFi OS device, as you may lose access if you misconfigure Tailscale or other network settings.

Switch to TUN mode

The quickest way to switch to TUN mode is to install the latest version of tailscale-unifi, which automatically configures Tailscale to use TUN mode on compatible devices. Keep in mind that devices which only support userspace networking mode cannot be used in this manner.

curl -sSLq https://raw.githubusercontent.com/SierraSoftworks/tailscale-unifi/main/install.sh | sh

Manually Switching to TUN Mode

If you have been running Tailscale on your UniFi device for a while, you may be using “userspace” networking mode. This mode is not compatible with advertising routes, so you need to switch to TUN mode first.

Edit your /data/tailscale/tailscale-env file and ensure that the TAILSCALED_FLAGS variable does NOT include the --tun userspace-networking flag. Unless you have manually configured any other options, it should look like this:

PORT="41641"
TAILSCALED_FLAGS=""
TAILSCALE_FLAGS=""
TAILSCALE_AUTOUPDATE="true"
TAILSCALE_CHANNEL="stable"

Then re-configure Tailscale by running /data/tailscale/manage.sh install, which updates your /etc/default/tailscaled file to use the new configuration and restarts the tailscaled service.

Verifying Your Setup

To ensure that Tailscale is running correctly, check for the existence of the tailscale0 network interface:

ip link show tailscale0

A successful setup should return output similar to:

129: tailscale0: <POINTOPOINT,MULTICAST,NOARP,UP,LOWER_UP> mtu 1280 qdisc pfifo_fast state UNKNOWN mode DEFAULT group default qlen 500
    link/none

If you see Device "tailscale0" does not exist, you are still running in userspace networking mode, which will not work. Follow the steps above to switch to TUN mode and try again.

Final Configuration

Once you have verified that you are not running in userspace networking mode, proceed with configuring Tailscale:

tailscale up --advertise-exit-node --advertise-routes="<one-or-more-local-subnets>" --snat-subnet-routes=false --accept-routes --reset

Example:

tailscale up --advertise-exit-node --advertise-routes="10.0.0.0/24" --snat-subnet-routes=false --accept-routes --reset

For more details on available options, see the official tailscale up command documentation.

Why can’t I see a Tailscale network interface?

Legacy versions of the tailscale-unifi script configured Tailscale to run in userspace networking mode on the device instead of as a TUN interface, so you wouldn’t see it in the ip addr list.

If you are running an older version of tailscale-unifi, you can switch to TUN mode by following the instructions above.

Does this support Tailscale SSH?

You bet. Make sure you’re running the latest version of Tailscale, then run tailscale up --ssh to enable it. You’ll need to set up SSH ACLs in your account by following this guide.

# Update Tailscale to its latest version
/data/tailscale/manage.sh update!

# Enable SSH advertisement through Tailscale
tailscale up --ssh

How do I generate HTTPS certificates with Tailscale?

Tailscale can generate valid HTTPS certificates for your device using Let’s Encrypt. This requires MagicDNS and HTTPS to be enabled in your Tailscale admin console.

# Generate a certificate
/data/tailscale/manage.sh cert generate

# Renew an existing certificate before it expires. If it is the active UniFi
# certificate, the same UniFi certificate record is updated automatically.
/data/tailscale/manage.sh cert renew

# Install certificate into UniFi OS
/data/tailscale/manage.sh cert install-unifi

# Restart UniFi Core after the initial installation
systemctl restart unifi-core

Certificates expire after 90 days. The hostname is automatically determined from your Tailscale configuration.

On UniFi OS, a systemd timer is automatically installed when you generate your first certificate. This timer runs weekly to check and renew certificates before they expire. If the active UniFi certificate still matches the previously installed Tailscale certificate, renewal updates its files and database record and restarts UniFi Core. A different active certificate is left untouched.