OpenWrt Network Configuration with UCI: Devices and Interfaces

This guide keeps the complete practical workflow for editing /etc/config/network. UCI separates physical devices, bridges, logical interfaces, addresses, and routes. Confusing these layers can immediately disconnect LAN or SSH.

1. Prepare and back up

Use wired LAN or a console when changing WAN, bridge, or VLAN settings. Record the model, release, current address, and recovery method. Create a configuration archive and a direct copy:

sysupgrade -b /tmp/config-backup.tar.gzcp /etc/config/network /tmp/network.beforeubus call system boardip -br linkip -br addr

2. Inspect the current model

cat /etc/config/networkuci show networkip addrip route

A config device describes a low-level device or bridge. A config interface describes a logical network such as lan or wan. A logical name is not necessarily an Ethernet card name. Wireless interfaces should normally be attached through the network option in /etc/config/wireless; do not assume dynamic Wi-Fi names are stable devices.

3. Common interface declarations

DHCP client:

config interface 'wan'        option device 'eth0.2'        option proto 'dhcp'

IPv6 DHCP client:

config interface 'wan6'        option device 'eth0.2'        option proto 'dhcpv6'

Static LAN:

config interface 'lan'        option device 'br-lan'        option proto 'static'        option ipaddr '192.168.1.1'        option netmask '255.255.255.0'

These device names are examples. Match them to the actual target layout.

4. Edit with UCI

1. Read values before editing:

uci get network.lan.deviceuci get network.lan.protouci get network.lan.ipaddruci get network.lan.netmask

2. Set the sample LAN address:

uci set network.lan.ipaddr='192.168.1.1'uci set network.lan.netmask='255.255.255.0'

3. Create a logical interface only after confirming the real device/VLAN:

uci set network.guest='interface'uci set network.guest.device='br-guest'uci set network.guest.proto='static'uci set network.guest.ipaddr='192.168.20.1'uci set network.guest.netmask='255.255.255.0'

4. Review uncommitted changes:

uci changes networkuci show network

5. Undo them if wrong:

uci revert network

6. Commit only after review:

uci commit network

5. Apply and verify

/etc/init.d/network reloadifdown lanifup lanip -br addrip routeubus call network.interface.lan statusubus call network.interface.wan statuslogread -e netifdping -c 3 192.168.1.1

Changing a bridge or WAN over SSH can cut the session immediately. From a client verify DHCP, gateway, DNS, the new LuCI address, and a WAN default route before rebooting.

6. Recovery

Try the new address, then use wired LAN or UART. If the change was committed, restore the copy:

cp /tmp/network.before /etc/config/networkuci commit network/etc/init.d/network restart

If the device is unreachable, use the target-specific failsafe procedure. Do not blindly delete /etc/config.

{{< ads >}}

Source

Source: OpenWrt Network configuration.