Modify Teleport VPN Subnet on Ubiquiti UniFi Gateway

Posted on by

Current lines of the UniFi Gateway devices, such as the UXG-Fiber that I am using, include a built in VPN server called Teleport. The idea is a simple, zero-configuration VPN solution. When activated, the VPN is configured automatically by selecting an unused subnet from the 192.168.X.0/24 range.

While initial deployment was as simple as advertised, I quickly ran into a problem where UniFi assigned a subnet that overlapped with a subnet on an upstream router. Teleport, being a zero-configuration service, gave no way to actually set what subnet is in use. Insert some curiosity and a solution.

Requirements

  • Administrative access to the UniFi OS Control Plane (Cloud Key or equivalent).
  • SSH access to the UniFi OS Control Plane (Cloud Key or equivalent), required to access the MongoDB.

Summary Steps

  • Gain SSH Access to the UniFi OS Control Plane
  • Determine the Site_ID Value for the Teleport Configuration
  • Modify the Teleport Subnet

Gain SSH Access to the UniFi OS Control Plane

The first step is to log in to your UniFi Control Plane. In this guide, I’m using an on-premise Cloud Key Plus Gen 2 device. Once logged in, enable SSH access to the Control Plane. Be sure you’re enabling access to the Control Plane and not to an individual device.

Network > Control Plane > Console > SSH

You’ll be prompted to accept a warning about the terms of use and to set a password for the SSH access. Allow a moment for provisioning, then use your preferred SSH client to log in to the Cloud Key or equivalent.

The password that was set will be for logging in as root.

Determine the Site_ID Value for the Teleport Configuration

If you only have a single site, then you will only have one result when querying the Teleport configuration. If you have multiple sites as with this guide, then you’ll need to determine which one to target. In this guide, there are two sites but only one has the Teleport service enabled which will make it simple to determine which to modify.

Start by logging in to the Cloud Key or equivalent as root with the previously set password, access the MongoDB, and switch to the ace database. Here is a sample session. The commands run will be in bold.

Linux UCKNOC1F1R 3.18.44-ui-qcom #1 SMP Mon Sep 22 15:23:34 CST 2025 aarch64

Firmware version: v4.4.3
[Trimmed]
Welcome to the CloudKey Plus!

root@UCKNOC1F1R:~# mongo –port 27117
MongoDB shell version v3.6.23
connecting to: mongodb://127.0.0.1:27117/?gssapiServiceName=mongodb
Implicit session: session { “id” : UUID(“7d7*****-****-****-****-*********d09”) }
MongoDB server version: 3.6.23
Welcome to the MongoDB shell.
For interactive help, type “help”.
[Trimmed]
Server has startup warnings:
[Trimmed]
> use ace
switched to db ace

Now we need to query for the for the key that we will modify. Again, if you only have one site then expect only a single result. The ObjectId and site_id values will be shortened for readability, but kept consistent. Actual values are much longer.

> db.setting.find({ key: “teleport”})
{ “_id” : ObjectId(“62a***389”), “subnet_cidr” : “192.168.65.1/24”, “site_id” : “53c***a62”, “key” : “teleport”, “enabled” : true }
{ “_id” : ObjectId(“693***590”), “key” : “teleport”, “site_id” : “693***57f”, “enabled” : true }

In this sample, we got two results but only one has a subnet_cidr key. This is the site that I need to modify and the subnet that is conflicting with my upstream. Make a note of the site_id. In this example, it is 53c***a62 (shortened).

Modify the Teleport Subnet

Now we need to disable the Teleport service from the management web interface, update the subnet_cidr value for the appropriate site, query again to verify that the correct site was modified, then re-enable the Teleport service. This time, I modified the find query to include the site_id that we’re working with so that only the desired site gets modified or queried.

After the Teleport service has been disabled in the web interface, here is a sample for inserting the desired subnet_cidr into the MongoDB. I’ll set the value and then query the value back to confirm.

> db.setting.update({ key: “teleport”, site_id: “53c***a62”}, { $set: { subnet_cidr: “10.64.47.1/24”} })

WriteResult({ “nMatched” : 1, “nUpserted” : 0, “nModified” : 1 })

> db.setting.find({ key: “teleport”, site_id: “53c***a62”})
{ “_id” : ObjectId(“62a***389”), “subnet_cidr” : “10.64.47.1/24”, “site_id” : “53c***a62”, “key” : “teleport”, “enabled” : true }

We can see that the desired subnet_cidr is returned in the query. One of the challenges here was that I could not find a way to push the new value to the UXG-Fiber after the Teleport service had already been enabled. Changing other settings to trigger a provision, or using the legacy web interface to force a full reprovision did not have the desired impact. Instead, I ended up toggling off the Teleport configuration, then writing the subnet to the database, and then re-enabling the Teleport service.

Do be aware that turning the Teleport service off and back on will remove the client configurations. You will need to recreate the Teleport client as well.

That’s it! This setting will persist across reboots but will be removed if the Teleport service is disabled.

Additional important observations:

  • The Teleport VPN service will remove the subnet configuration value from the database when disabled, then select a new random subnet when subsequently enabled.
  • If the database contains a subnet_cidr value when the service is changed from disabled to enabled, then the service will adopt the value presently in the database.
  • The Teleport VPN service on the UXG will NAT all VPN clients. Traffic from the clients will appear to source from the gateway on the UXG. This happens even when NAT is globally disabled on the UXG. If it is necessary to be able to route traffic to a VPN client, the Teleport service is not ideal.

Environment

  • UniFi Cloud Key Plus Gen 2 (UniFi OS v4.4.3)
  • UniFi Network (Firmware v9.5.21)
  • UXG Fiber (Firmware v4.3.1)

Resources