Setting up an IPSec VPN on OpenWrt used to mean editing /etc/ipsec.conf by hand -- tracking down the right parameters for your topology, debugging misconfigured secrets, and restarting the service after every change. For site-to-site tunnels between branch offices, or road-warrior access for remote employees, the manual approach worked but didn't scale.

Libreswan, the IPSec implementation used in OpenWrt, is a battle-tested VPN stack. But until now, it lacked the configuration layer that makes OpenWrt's ecosystem so powerful: UCI (Unified Configuration Interface). With UCI support, Libreswan joins the rest of OpenWrt's services -- configurable through a consistent interface, scriptable for automation, and manageable at scale.

Why IPSec and Why Libreswan Link to heading

IPSec operates at the network layer, encrypting and authenticating all IP traffic between endpoints. Unlike SSL-based VPNs that work at the application layer, IPSec protects every packet -- TCP, UDP, ICMP -- without per-application configuration. Once the tunnel is up, your entire subnet-to-subnet communication is secured.

Libreswan is the open-source fork of Openswan and the standard IPSec implementation on OpenWrt. It supports:

  • IKEv1 and IKEv2 -- modern key exchange protocols
  • Site-to-site tunnels -- connect two networks permanently
  • Road warrior access -- remote clients connecting from dynamic IPs
  • Hub and spoke topologies -- central office with multiple branch connections
  • Dead Peer Detection (DPD) -- automatically detect and recover from tunnel failures
  • Multiple encryption algorithms -- AES, 3DES, and more with various hashing options

UCI Configuration Link to heading

Instead of editing /etc/ipsec.conf directly, UCI gives you structured configuration sections. A basic site-to-site tunnel between two offices looks like this:

# Global settings
uci set ipsec.default.enabled='1'

# Connection to branch office
uci set ipsec.branch=connection
uci set ipsec.branch.left='203.0.113.1'          # Our public IP
uci set ipsec.branch.leftsubnet='192.168.1.0/24'  # Our LAN
uci set ipsec.branch.right='198.51.100.1'         # Branch public IP
uci set ipsec.branch.rightsubnet='10.0.0.0/24'    # Branch LAN
uci set ipsec.branch.keyexchange='ikev2'
uci set ipsec.branch.type='tunnel'
uci set ipsec.branch.authby='secret'
uci set ipsec.branch.auto='start'

# Pre-shared key
uci set ipsec.branch_secret=secret
uci set ipsec.branch_secret.type='PSK'
uci set ipsec.branch_secret.id='%any'
uci set ipsec.branch_secret.key='your-secure-key-here'

uci commit ipsec
/etc/init.d/ipsec restart

For a road warrior setup where remote clients connect from unknown IPs, the configuration changes slightly:

uci set ipsec.roadwarrior=connection
uci set ipsec.roadwarrior.left='%defaultroute'
uci set ipsec.roadwarrior.leftsubnet='192.168.1.0/24'
uci set ipsec.roadwarrior.right='%any'
uci set ipsec.roadwarrior.rightsourceip='172.16.0.0/24'  # Virtual IPs for clients
uci set ipsec.roadwarrior.keyexchange='ikev2'
uci set ipsec.roadwarrior.type='tunnel'
uci set ipsec.roadwarrior.authby='secret'
uci set ipsec.roadwarrior.auto='add'

The right='%any' tells Libreswan to accept connections from any IP -- essential when your remote users are on hotel WiFi or cellular networks.

Hub and Spoke Topology Link to heading

For organizations with a central office and multiple branches, the hub-and-spoke model centralizes VPN management. All branch offices connect to the hub, and traffic between branches routes through the hub:

                    +-------------+
                    |  Branch A   |
                    | 10.0.1.0/24 |
                    +------+------+
                           |
          +----------------+----------------+
          |                |                |
    +-----+-----+    +-----+-----+    +-----+-----+
    | Branch B  |    |   Hub     |    | Branch C  |
    |10.0.2.0/24|    |192.168.1.0|    |10.0.3.0/24|
    +-----------+    +-----------+    +-----------+

Configure each branch as a separate UCI connection section -- no monolithic config file, no merge conflicts when adding a new site.

Authentication and Security Link to heading

Libreswan supports multiple authentication methods through UCI:

Pre-Shared Keys (PSK) -- simplest, ideal for site-to-site:

uci set ipsec.mytunnel_secret=secret
uci set ipsec.mytunnel_secret.type='PSK'
uci set ipsec.mytunnel_secret.key='your-key'

X.509 Certificates -- strongest, ideal for road warriors:

uci set ipsec.roadwarrior.authby='rsasig'
uci set ipsec.roadwarrior.leftcert='hub-cert.pem'
uci set ipsec.roadwarrior.leftid='@hub.example.com'

XAUTH with username/password -- layered on top of PSK or certificates for additional client authentication:

uci set ipsec.roadwarrior.xauth='server'
uci set ipsec.roadwarrior.rightxauth='client'

Dead Peer Detection Link to heading

Network links fail -- it's not a question of if, but when. DPD (Dead Peer Detection) lets Libreswan automatically detect when a peer stops responding and either re-establish the tunnel or trigger failover:

uci set ipsec.branch.dpddelay='30'      # Check every 30 seconds
uci set ipsec.branch.dpdtimeout='120'   # Declare dead after 120 seconds
uci set ipsec.branch.dpdaction='restart' # Re-establish when peer returns

With DPD enabled, a temporary ISP outage at the branch office recovers automatically. No manual intervention, no midnight phone calls.

LuCI Web Interface Link to heading

Alongside UCI support, a new LuCI application (luci-app-libreswan) provides a browser-based management interface. Navigate to Services -> IPSec VPN to:

  • View all configured VPN connections and their status
  • Add, edit, and remove tunnels without touching the command line
  • Monitor tunnel uptime and traffic statistics
  • Manage certificates and pre-shared keys
  • Debug connection issues with built-in log viewer

The LuCI interface reads and writes the same UCI configuration, so you can switch between the web UI and command line freely -- changes made in one are immediately visible in the other.

Why This Matters Link to heading

Before UCI integration, IPSec on OpenWrt meant:

  1. SSH into the router
  2. Manually edit /etc/ipsec.conf -- hope you get the syntax right
  3. Restart ipsec and check logs for errors
  4. Repeat steps 2-3 until the tunnel works

Now it's:

  1. Run a few uci set commands (or use the LuCI UI)
  2. Commit and restart
  3. Done

For anyone managing multiple OpenWrt devices -- whether it's a single home router, a fleet of branch office gateways, or a managed SD-WAN deployment -- UCI makes IPSec configuration repeatable, scriptable, and auditable. It integrates with OpenWrt's configuration management system, so your VPN settings survive firmware upgrades and can be backed up alongside the rest of your router configuration.

Originally published August 22, 2022 on jaymspatel.blogspot.com