Network Interfaces

How to configure logical network interfaces in OpenWrt using /etc/config/network, with examples for static IP, DHCP, PPPoE, bridges, and DSA VLANs.

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

Each section begins with 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

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

CIDR notation is also accepted:

option ipaddr   192.168.1.1/24

DHCP client

Obtain an IPv4 address automatically. Typical for the WAN interface.

config interface 'wan'
    option device  eth0
    option proto   dhcp

Optional tuning:

config interface 'wan'
    option device    eth0
    option proto     dhcp
    option hostname  my-router
    option metric    10

PPPoE

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 '[e-mail]'
    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)

Bridge

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.

VLAN (DSA)

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

Port suffix reference:

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.

Inspect the current state with standard Linux tools:

# 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