All interface configuration in OpenWrt lives in a single UCI file: /etc/config/network. The netifd daemon reads this file and maintains the corresponding kernel network state. You never edit /etc/network/interfaces or run ip commands directly to persist settings.
File structure
The file contains three types of UCI sections:
| Section type | Purpose |
|---|
config interface | A named logical interface (e.g. lan, wan) |
config device | A named device definition (bridge, alias, VLAN) |
config bridge-vlan | A DSA bridge VLAN membership rule |
config <type> '<name>' followed by indented option and list directives.
Common interface options
| Option | Description |
|---|
proto | Protocol handler: static, dhcp, dhcpv6, pppoe, none, … |
device | Physical or virtual device name (e.g. eth0, br-lan) |
ipaddr | Static IPv4 address |
netmask | Subnet mask (or use CIDR notation in ipaddr, e.g. 192.168.1.1/24) |
gateway | Default gateway for this interface |
dns | Space-separated DNS servers |
ip6addr | Static IPv6 address |
ip6gw | IPv6 default gateway |
metric | Routing metric (lower = preferred) |
mtu | MTU override |
auto | Bring up automatically at boot (default: 1) |
disabled | Set to 1 to disable without removing |
Configuration examples
Static IP
DHCP client
PPPoE
Bridge
VLAN (DSA)
Assign a fixed IPv4 address. Use this for the LAN-side interface of a router.config interface 'lan'
option device br-lan
option proto static
option ipaddr 192.168.1.1
option netmask 255.255.255.0
option dns 8.8.8.8 8.8.4.4
option ipaddr 192.168.1.1/24
Obtain an IPv4 address automatically. Typical for the WAN interface.config interface 'wan'
option device eth0
option proto dhcp
config interface 'wan'
option device eth0
option proto dhcp
option hostname my-router
option metric 10
Point-to-Point Protocol over Ethernet — common for DSL and some fiber ISPs. Requires the ppp and kmod-pppoe packages.config interface 'wan'
option device eth0
option proto pppoe
option username '[email protected]'
option password 'secret'
option ipv6 auto
| PPPoE option | Description |
|---|
username | PPP username supplied by ISP |
password | PPP password |
keepalive | LCP echo interval (e.g. 10 5 = 10 s interval, 5 failures) |
demand | Dial-on-demand (1 to enable) |
ipv6 | Enable IPv6 negotiation (auto or 1) |
A bridge combines multiple ports into a single Layer-2 segment. Declare the bridge device first, then reference it from an interface.config device
option name br-lan
option type bridge
list ports eth1
list ports eth2
list ports eth3
config interface 'lan'
option device br-lan
option proto static
option ipaddr 192.168.1.1/24
Wireless interfaces (e.g. wlan0) are added to the bridge by setting option network 'lan' in the corresponding config wifi-iface section — not by listing them here directly.
DSA-based VLAN configuration, available on OpenWrt 21.02 and later with supported switch hardware.# Define the bridge device
config device
option name br-lan
option type bridge
list ports lan1
list ports lan2
list ports lan3
list ports lan4
list ports wan
# VLAN 10 — LAN ports 1-3 untagged, CPU port tagged
config bridge-vlan
option device br-lan
option vlan 10
list ports 'lan1:u*'
list ports 'lan2:u*'
list ports 'lan3:u*'
list ports 'cpu:t'
# VLAN 20 — Guest network on LAN port 4, CPU tagged
config bridge-vlan
option device br-lan
option vlan 20
list ports 'lan4:u*'
list ports 'cpu:t'
# Logical interfaces bound to each VLAN
config interface 'lan'
option device br-lan.10
option proto static
option ipaddr 192.168.1.1/24
config interface 'guest'
option device br-lan.20
option proto static
option ipaddr 192.168.2.1/24
| Suffix | Meaning |
|---|
u | Egress untagged (strip VLAN tag) |
t | Egress tagged (keep VLAN tag) |
* | This VLAN is the PVID (ingress default) |
Logical interfaces vs physical devices
A key netifd concept is the separation between logical interfaces and physical devices:
- A physical device is a kernel netdev:
eth0, wlan0, br-lan, etc.
- A logical interface is a netifd abstraction with a name like
lan or wan. It has an IP address, a protocol, routing rules, and firewall zone membership.
One physical device can be referenced by only one logical interface at a time. Multiple IPv6 addresses or prefixes can coexist on a single logical interface. netifd automatically creates alias interfaces (e.g. wan_6) when a protocol handler needs to install additional addresses.
Interface management commands
After editing /etc/config/network, apply changes with:
# Bring up a specific logical interface
ifup wan
# Bring down a specific logical interface
ifdown wan
# Reload all interfaces (non-disruptive where possible)
ubus call network reload
ifup/ifdown are thin wrappers around ubus calls to netifd. They operate on logical interface names (e.g. wan), not kernel device names.
# Show all IP addresses
ip addr show
# Show the routing table
ip route show
# Show IPv6 routes
ip -6 route show
# Show netifd interface status via ubus
ubus call network.interface dump
ubus call network.interface.wan status