Wireguard is a free and open-source VPN, designed to be easy to use, fast, and secure. It outperforms IPsec and OpenVPN, and it can make a good site-to-site or remote access VPN solution. This post covers UniFi OS Console like the UDM-Pro, but Wireguard also can be used on Ubiquiti EdgeRouters.
Ubiquiti's new UniFi Teleport VPN uses Wireguard under the hood. Teleport is a new option for remote access, offering better performance but less configurability than L2TP/IPsec. To use Teleport, you need to meet these requirements:
- One of the following UniFi OS Consoles:
- A Dream Machine or Dream Machine Pro running 1.12.0 or later.
- A Dream Router or Dream Machine Pro Special Edition running 2.4.0 or later.
- UniFi Network version 7.1 or later.
- A client device capable of running the WiFiman mobile app (Android/iOS).
- The UniFi OS Console must have Remote Access enabled.
While Teleport is easy to setup, it currently doesn't support Windows or macOS clients. You also have no control over networking settings, such as IP addresses or ports. Teleport can't be used for a site-to-site VPN either.
The good news is that Ubiquiti has confirmed that full native Wireguard support in UniFi is coming. For now, Wireguard still needs to be manually installed. Ubiquiti provided the GPL source code for the UDM kernel, and Carlos Talbot has a public repo with all of the necessary code. His instructions and code are available on GitHub. For this to survive reboots and firmware updates, we'll also need to install the UDM On-Boot utility.
Step 1: Install Wireguard
Download the latest Wireguard package:
curl -LJo wireguard-kmod.tar.Z https://github.com/tusc/wireguard-kmod/releases/download/v06-01-22/wireguard-kmod-06-01-22.tar.Z
Extract the files:
tar -C /mnt/data -xvzf wireguard-kmod.tar.Z
Make the setup script executable, and run it:
cd /mnt/data/wireguard
chmod +x setup_wireguard.sh
./setup_wireguard.sh
At this point, Wireguard is now installed and running, but it needs to be configured.
Step 2: Configure Wireguard
First, you will need to generate a private/public key pair, to use for the Wireguard interface on the UDM. You can place these in the /etc/wireguard/ directory, or make a new subdirectory for your keys.
cd /etc/wireguard
mkdir server_keys
wg genkey | tee privatekey | wg pubkey > publickey
Then, you can use cat or more to view the keys that are generated. You'll need them for the configuration file.
cat publickey
cat privatekey
Your keys will look something like this, always ending with an equals sign: S45DFJCTcr7q7esdfjkhaKixEg6lWYl+hfIb48sK7bwVXmKyVE=
Next, copy the sample configuration into wg0.conf, which is the default config file. You can use vim or another CLI text editor to modify the configuration file.
cp /etc/wireguard/wg0.conf.sample /etc/wireguard/wg0.conf
vim /etc/wireguard/wg0.conf
Inside the config file, you should modify the sample config lines as needed, and the placeholder text for your keys. Replace <private key> with the actual private key you just generated.
Note: In vim, use "i" to enter insert mode. Make the changes you need to make, then hit the escape key. Type in ":w" (without the quotation marks) and hit the enter key to save. Then hit CTRL+Z to exit.
This configuration file can be used to create a site-to-site tunnel to another UDM, or create a remote access solution for phones or laptops. Here, we're configuring a site to site tunnel between two UDMs.
The top part of the configuration is for the UDM you're currently on. Here, you define the IP address of the Wireguard interface, which UDP port it listens on (default = 51820), and the private key.
The bottom part of the config file is for your peers - either the other UDM you are connecting, or the phone or laptop you want to have remote access. You can define multiple peers by adding another [peer], and adding the PublicKey, Endpoint, and AllowedIPs arguments.
The endpoint can be an IP address, or a hostname. If you don't have a public static IP address, you'll probably want to configure dynamic DNS and point to that hostname, to avoid issues when the DHCP WAN address changes.
By default, Wireguard doesn't send any keepalive packets, and doesn't listen for incoming traffic. You can modify this by adding persistent-keepalive <number of seconds between messages>, which is recommended for site to site tunnels.
Example Site To Site Configuration
Site A:
[Interface]
Address = 172.16.99.1/24
ListenPort = 51820
PrivateKey = <private key of Site A UDM>
[Peer]
PublicKey = <public key of Site B UDM>
Endpoint = <dynamic DNS hostname>:51820
AllowedIPs = 172.16.99.2/32, 192.168.20.0/24
PersistentKeepalive = 20
Site B:
[Interface]
Address = 172.16.99.2/24
ListenPort = 51820
PrivateKey = <private key>
[Peer]
PublicKey = S45DFJCTcr7q7esdfjkhaKixEg6lWYl+hfIb48sK7bwVXmKyVE=
Endpoint = <public IP>:51820
AllowedIPs = 172.16.99.2/32, 192.168.10.0/24, 192.168.11.0/24
PersistentKeepalive = 20
With these configurations, we're using 172.16.99.0/24 as the tunnel network. You want this to be a unique subnet at both sites, that isn't currently in use. This is the internal network that the Wireguard server and any connected clients use for their tunnel interfaces.
The first AllowedIP argument defines the peer's IP address, with a /32 mask. Then, you add any additional local networks you want them to have access to. With our configuration:
- Site A will have access to Site B's 192.168.10.0/24 and 192.168.11.0/24 network
- Site B will have access to Site A's 192.168.20.0/24 network
The AllowedIPs argument defines what networks the peer is able to access, so modify and add to that list as needed. You want to avoid subnet conflicts, so make sure to not have the same subnet at both locations.
Step 3: Install the On-Boot Utility
Now that Wireguard is configured, we need to install the UDM on-boot-script utility. This will be used to automatically run the setup_wireguard.sh script on a reboot. Without this, you would need to run that manually every time you restart the UDM.
Install the on-boot utility:
curl -fsL "https://raw.githubusercontent.com/boostchicken-dev/udm-utilities/HEAD/on-boot-script/remote_install.sh" | /bin/sh
To ensure on-boot is enabled, enter the unifi-os shell:
unifi-os shell
Check udm-boot status with:
systemctl status udm-boot
If not enabled, run:
systemctl enable udm-boot
And then exit the unifi-os shell
exit
Now the configuration will persist, but one more step is needed to bring the tunnel interface up automatically. You can either add "wg-quick up wg0" to the end of the existing setup_wireguard.sh script:
echo "wg-quick up wg0" >> /mnt/data/on_boot.d/setup_wireguard.sh
Or, you can create a small executable script in the /mnt/data/on_boot.d directory:
cd /mnt/data/on_boot.d
touch wgup.sh
chmod +x wgup.sh
vim wgup.sh
wgup.sh should contain:
#!/bin/sh
wg-quick up wg0
Step 4: Test, and Check Wireguard Status
After following these steps for both sides of the tunnel, you should test that everything is working, and reboot to see if the on-boot utility is setup correctly. You can show the status of wireguard with the wg command.
wg
The wg command should display information like this:
# wg
interface: wg0
public key: Hsdf93jkhaKixEg6lWYl+hfIb48sK7bwVXmKyVE=
private key: (hidden)
listening port: 51820
peer: S45DFJCTcr7q7esdfjkhaKixEg6lWYl+hfIb48sK7bwVXmKyVE=
endpoint: <public IP>:51820
allowed ips: 192.168.95.1/32, 192.168.1.0/24
latest handshake: 1 minute, 43 seconds ago
transfer: 30.17 KiB received, 27.20 KiB sent
If wg returns nothing, use the wg-quick up command to activate it:
wg-quick up wg0
HostiFi
Contact HostiFi for all your UniFi and UISP hosting needs at support@hostifi.com, or by using the live chat on our website. HostiFi Pro offers professional network services, specialising in Ubiquiti hardware and software.
