SOP-010: WireGuard Persistence on UISP Routers

Created: 2026-02-14
Status: Production Ready
Tested On: Moruca-Kumaka-UISP-R (firmware 5.4.2)

Overview

Problem: UISP Routers do NOT persist CLI changes across reboots. Commands like ip, wg set, iptables apply immediately but are lost on reboot. This is unlike EdgeRouters which have persistent /config/config.boot.

Solution: Startup scripts in /mnt/data/on_boot.d/. Scripts in this directory execute automatically on boot and /mnt/data/ persists across reboots and firmware upgrades.

Important: The UISP Router GUI does NOT support WireGuard Client configuration. GUI only supports IPsec Site-to-Site and WireGuard Server. You must use CLI and a startup script for WireGuard Client (site-to-site VPN).

Prerequisites

• UISP Router with SSH access
• WireGuard keys from WG Easy server
• VPN IP assigned (e.g., 10.8.0.x)
• LAN subnet defined (e.g., 10.1.0.0/20)
• Server public key, endpoint, preshared key

Server Constants

Server Public Key: [See Infisical /credentials/wireguard/]
Server Endpoint:   wireguard.karetechsolutions.com:51820
VPN Network:       10.8.0.0/22

Procedure

Step 1: Gather Configuration from WG Easy

docker exec wg-easy sqlite3 /etc/wireguard/wg-easy.db \
  "SELECT name, ipv4_address, private_key, public_key, pre_shared_key, server_allowed_ips
   FROM clients_table WHERE name = '<ROUTER_NAME>';"

You will need: VPN IP, Private Key, Preshared Key, LAN Subnet.

Step 2: Find LAN Interface

ssh ubnt@<ROUTER_IP>
ip addr show | grep "inet 10\."
# Common: switch0.1 (VLAN), br0 (bridge)

Step 3: Create Startup Script

mkdir -p /mnt/data/on_boot.d/
cat > /mnt/data/on_boot.d/wireguard-startup.sh << 'EOF'
#!/bin/sh
# WireGuard Startup Script for <ROUTER_NAME>
sleep 15
logger "WireGuard startup script starting..."
 
ip link add dev wg0 type wireguard
ip address add <VPN_IP>/32 dev wg0
ip link set dev wg0 mtu 1420 up
 
echo "<PRIVATE_KEY>" > /tmp/privkey
echo "<PRESHARED_KEY>" > /tmp/psk
 
wg set wg0 \
  private-key /tmp/privkey \
  peer '<SERVER_PUBLIC_KEY>' \
  preshared-key /tmp/psk \
  endpoint wireguard.karetechsolutions.com:51820 \
  allowed-ips 10.8.0.0/22,<LAN_SUBNET> \
  persistent-keepalive 25
 
rm /tmp/privkey /tmp/psk
ip route add 10.8.0.0/22 dev wg0
 
iptables -I FORWARD 1 -i wg0 -j ACCEPT
iptables -I FORWARD 1 -o wg0 -j ACCEPT
iptables -t nat -I POSTROUTING 1 -o <LAN_INTERFACE> -j MASQUERADE
 
logger "WireGuard startup script completed successfully"
EOF
chmod +x /mnt/data/on_boot.d/wireguard-startup.sh

Replace these placeholders:

• <ROUTER_NAME> — Router description
• <VPN_IP> — Router VPN IP (e.g., 10.8.0.54)
• <PRIVATE_KEY> — WireGuard private key
• <PRESHARED_KEY> — WireGuard preshared key
• <SERVER_PUBLIC_KEY> — [From Infisical /credentials/wireguard/]
• <LAN_SUBNET> — LAN subnet (e.g., 10.1.0.0/20)
• <LAN_INTERFACE> — LAN interface name (e.g., switch0.1)

Step 4: Test Script

sh /mnt/data/on_boot.d/wireguard-startup.sh
sleep 5
wg show
wg show | grep "latest handshake"  # Should show seconds ago
ping -c 3 10.8.0.1

Step 5: Test Persistence (Reboot)

WARNING: This will briefly take the router offline.

reboot
# After ~2-3 minutes:
ssh ubnt@<ROUTER_IP>
wg show | grep "latest handshake"

Verification Checklist

• Script exists: /mnt/data/on_boot.d/wireguard-startup.sh
• Script is executable
• All placeholders replaced (no <...> text remains)
• Manual test: script runs without errors
• Manual test: handshake appears
• Manual test: ping 10.8.0.1 succeeds
• Reboot test: WireGuard auto-restores

Troubleshooting

No handshake after script runs:

• Wrong private or preshared key
• Firewall blocking UDP 51820
• DNS resolution failure for endpoint
• Router cannot reach endpoint IP

Can ping router but not LAN devices:

• Verify NAT MASQUERADE rule: iptables -t nat -L POSTROUTING -n -v
• Verify LAN interface is correct

Script lost after firmware upgrade:

• /mnt/data/ should persist normally
• Some factory resets may wipe it — keep backup in /home/karetech/scripts/<router>-wireguard-startup.sh

EdgeRouter vs UISP Router