SierraSoftworks / tailscale-udm

Tailscale on UniFi Dream Machine This repo contains the scripts necessary to install and run a tailscale instance on your UniFi Cloud Gateways. It does so by piggy-backing on the excellent unifi-utilities to provide a persistent service and runs using Tailscale's usermode networking feature. Installation • Run the script to install the latest version of the Tailscale UDM package on your UDM. • Run to start Tailscale. • Follow the on-screen steps to configure Tailscale and connect it to your network. • Confirm that Tailscale is working by running Compatibility **ⓘ You can confirm your UniFi OS (UOS) version by running ** This package is compatible with UniFi OS 2.x or later and is known to work on the following variants of UniFi devices: • Any variant of the UniFi Cloud Gateway (UCG) • Any variant of the UniFi Cloud Key Gen 2 (UCK-G2) • Any variant of the UniFi Dream Machine (UDM) • Any variant of the UniFi Dream Router (UDR) • Any variant of the UniFi Dream Wall (UDW) • Any variant of the UniFi Express (UX) • Any variant of the UniFi NAS Pro (UNAS-PRO) • Any variant of a UniFi device running UniFi OS 2.x or later not listed above or below This package is **NOT** compatible with the following variants of UniFi devices: • 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 (the legacy OS on UDM/UDM Pro) • Any variant of an EoL UniFi device not listed above We expect that it should function on most consumer-grade UniFi devices without issue, but if you do run into any problems, please open an issue and provide the following information: • The device you are running on (e.g. UDM Pro) • The UniFi OS version you are running (e.g. 2.4.8 - this can be found by running ) • The steps you took to install Tailscale and any errors you encountered. **WARNING:** This package is no longer compatible with UniFi OS 1.x (the legacy OS on UDM/UDM Pro). If you are running UniFi OS 1.x and are unable to upgrade to the latest stable version of UniFi OS, you should use the legacy version of this package, which is available in the branch of this repository. The legacy version is no longer maintained and may not work with the latest version of Tailscale. Management Configuring Tailscale You can configure Tailscale using all the normal options, you should be able to find on your path after installation. Restarting Tailscale On UniFi OS 2.x+, Tailscale is managed using and the service. You can restart it using the following command. Upgrading Tailscale Upgrading Tailscale on UniFi OS 2.x+ can be done either using or by using the helper script. Using Using Remove Tailscale To remove Tailscale, you can run the following command, or run the steps below manually. Manual Steps • Kill the daemon with . • Remove the & package using . • Remove the management script and state using . • Remove the script using . • Remove the folder using . Contributing There are clearly lots of folks who are interested in running Tailscale on their UDMs. If you're one of those people and have an idea for how this can be improved, please create a PR and we'll be more than happy to incorporate the changes. Frequently Asked Questions How do I advertise routes? You do this by updating your Tailscale configuration as you would on any other machine, just remember to provide the full path to the binary when doing so. Can I route traffic from machines on my local network to Tailscale endpoints automatically? Yes! As of January 30, 2025, [two][tailscale-pr10828] [changes][tailscale-pr14452] to Tailscale have made this possible. Much credit goes to @tomvoss and @jasonwbarnett, who contributed significant effort to the initial implementation, detailed [in this GitHub issue][tailnet-routing-discussion]. Before going further please read tailscale's [subnet router documentation][tailscale-subnet-router-docs] and familiarize yourself with the concepts of subnet routers, independent of UniFi OS. Prerequisites Before proceeding, please review Tailscale’s [subnet router documentation][tailscale-subnet-router-docs] to understand the core concepts of subnet routing, independent of UniFi OS. **NOTE**: You do not need to manually enable on your UniFi OS device as it is enabled by default. If you want to confirm its status, run: **WARNING**: You should conduct all of these changes over a direct network connection to your UniFi OS device, as you may lose access to the device 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-udm, which will automatically configure Tailscale to use TUN mode. Manually Switching to TUN Mode If you have been running Tailscale on your UniFi device for a while, there is a good chance that you are running in "userspace" networking mode. This mode is not compatible with advertising routes, so you will need to switch to TUN mode. To do so, edit your file and ensure that the variable does **NOT** include the flag. Unless you have manually configured any other options, it should look like this: Then re-configure Tailscale by running , which will update your file to use the new configuration and restart the service. Verifying Your Setup To ensure that Tailscale is running correctly, check for the existence of the tailscale0 network interface: A successful setup should return output similar to: If you see instead, it means you are still running in [userspace networking mode][tailscale-userspace-networking-docs], 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: Example: For more details on available options, see the official [tailscale…