Static Routes on OpenWrt: IPv4, IPv6, and netifd Routing Tables

netifd lets OpenWrt define static IP routes in /etc/config/network. Unlike a temporary ip route add, a route or route6 section is managed by UCI and can be reloaded with its interface.¹

Scope: This is about static routes, not dynamic routing protocols. Before applying a route, know which interface reaches the next hop and keep a console or SSH recovery path in case management traffic loses its return route.

1. Basic IPv4 routes

An IPv4 route is a route section attached to a logical interface. The source's minimal example is:

1
2
3
4
5

config route 'route_example_1'
        option interface 'lan'
        option target '172.16.123.0'
        option netmask '255.255.255.0'
        option gateway '172.16.123.100'

Here lan is the interface carrying the route, 172.16.123.0 is the destination network, and 255.255.255.0 is the netmask. Replace these values with the actual topology; they are not universal defaults.

A default route in table 100 can be declared as follows:

1
2
3
4
5

config route 'route_example_2'
        option interface 'vpn'
        option target '0.0.0.0/0'
        option table '100'
        option gateway '10.72.197.110'

vpn is the logical interface, 0.0.0.0/0 covers all IPv4 destinations, and table 100 is a separate routing table. Define an alias in /etc/iproute2/rt_tables if a symbolic name is preferred. The UCI declaration is the persistent equivalent of:

1

ip route add default via 10.72.197.110 table 100

2. route options

Multiple route sections can be attached to one interface. In a real configuration I use names such as route_lan_iot or route_vpn_default so that I do not accidentally edit an existing route.

3. IPv6 routes

IPv6 uses a route6 section:

1
2
3
4

config route6
        option interface 'lan'
        option target '2001:0DB8:100:F00:BA3::1/64'
        option gateway '2001:0DB8:99::1'

lan is the logical interface, 2001:0DB8:100:F00:BA3::1/64 is the routed IPv6 subnet in CIDR notation, and 2001:0DB8:99::1 is the IPv6 gateway. 2001:0DB8::/32 is a documentation prefix; use the real prefix in a live network.

4. route6 options

5. Routing types

The source also lists the meanings of the type values:

6. Check the result on the router

After editing /etc/config/network, I inspect UCI and both route tables before closing the management session:

1
2
3

uci show network
ip route show
ip -6 route show

If the route is absent, re-check interface, target, gateway, table, and disabled. Do not add a default route to main merely for testing; a wrong default route can remove the return path for LuCI or SSH.

Conclusion

OpenWrt static routing has three pieces that must agree: the logical interface, the destination/prefix, and the gateway/table. Use route for IPv4 and route6 for IPv6; options such as metric, mtu, source, onlink, type, proto, and disabled matter only when the topology needs them. I keep UCI as the source of truth and use ip route show and ip -6 route show to verify the result.

Sources