Networking Overview

An introduction to OpenWrt’s networking stack, UCI-based configuration, and the netifd daemon that manages network interfaces.

OpenWrt replaces the networking configuration of a typical Linux distribution with a unified, UCI-based system. All network settings are declared in plain-text UCI files under /etc/config/, and a single daemon — netifd — reads those files and keeps the running kernel state in sync.

The networking stack

Three layers work together to bring up and manage network connectivity:

Layer	Component	Role
Configuration	UCI (/etc/config/network)	Declarative source of truth for all interface settings
Daemon	netifd	Translates UCI config into kernel interface state
Kernel	Linux netdev / DSA / mac80211	Actual packet forwarding and wireless drivers

netifd — the network interface daemon

netifd (/sbin/netifd) is the OpenWrt Network Interface Configuration Daemon. It:

• Watches /etc/config/network for changes via ubus/uci events
• Creates, configures, and tears down kernel network interfaces
• Manages protocol handlers (static, DHCP, PPPoE, WireGuard, …) as plug-in shell/ucode scripts under /lib/netifd/proto/
• Exposes a ubus API (network.*) that other daemons and the ifup/ifdown tools call

netifd is intentionally stateless with respect to the filesystem — on every bring-up it re-reads the UCI config. You never need to edit /etc/network/interfaces or similar files on OpenWrt.

/etc/config/network — central network configuration

Every logical interface, physical device alias, bridge, and routing hint is declared in /etc/config/network. The file uses standard UCI syntax:

config interface 'loopback'
    option device  lo
    option proto   static
    option ipaddr  127.0.0.1
    option netmask 255.0.0.0

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

config interface 'wan'
    option device  eth0
    option proto   dhcp

Each config interface block defines a logical interface — a named abstraction that netifd maps to one or more physical devices.

Supported protocol types

Protocol	option proto value	Description
Static IP	static	Manually assigned address, gateway, DNS
DHCP client	dhcp	IPv4 address from a DHCP server
DHCPv6 client	dhcpv6	IPv6 address/prefix from a DHCPv6 server
PPPoE	pppoe	Point-to-Point over Ethernet (DSL/fiber)
WireGuard	wireguard	WireGuard VPN tunnel
6in4	6in4	IPv6-in-IPv4 static tunnel
6to4	6to4	Automatic 6-to-4 tunnel (RFC 3056)
DS-Lite	dslite	Dual-Stack Lite (IPv4-in-IPv6)
None	none	Unmanaged — bring the device up without an address

Protocol scripts live in /lib/netifd/proto/. Additional protocols are installed by separate packages (e.g. odhcp6c for dhcpv6, ppp for pppoe).

Bridging

A bridge interface combines multiple physical ports into a single Layer-2 domain. In OpenWrt you declare a config device of type bridge and list its member ports:

config device
    option name    br-lan
    option type    bridge
    list   ports   eth0
    list   ports   eth1

The config interface 'lan' section then references br-lan as its device.

VLANs (DSA style)

Modern OpenWrt uses the Distributed Switch Architecture (DSA) kernel driver for switch chips. VLANs are configured through config bridge-vlan sections rather than swconfig:

config bridge-vlan
    option device  br-lan
    option vlan    1
    list   ports   'lan1:u*'
    list   ports   'lan2:u*'
    list   ports   'cpu:t'

config bridge-vlan
    option device  br-lan
    option vlan    2
    list   ports   'lan3:u*'
    list   ports   'cpu:t'

Port suffixes: u = untagged, t = tagged, * = PVID (primary VLAN).

DSA-based VLAN configuration is not compatible with the legacy swconfig approach used on older OpenWrt releases (pre-21.02). Check your target platform before applying VLAN config.

Explore the networking subsystems

Network Interfaces

UCI config structure, common interface scenarios (static, DHCP, PPPoE, bridge, VLAN), and interface management commands.

Wireless Configuration

Configuring Wi-Fi radios and virtual APs via /etc/config/wireless, applying changes, and WPA2/WPA3 examples.

IPv6

DHCPv6, SLAAC, tunnel protocols, odhcp6c/odhcpd, and prefix delegation.

Firewall

nftables-based fw4 firewall, zone/forwarding/rule/redirect configuration, and port forwarding.