Network configuration /etc/config/network

See also: IPv4 configuration, IPv6 configuration, Static routes, WAN interface protocols, Network scripting, DHCP client scripting

The default OpenWrt network stack of a typical home router looks like this:

Your device may vary slightly in features or numbering scheme. A minimal network configuration for a router usually consists of at least two interfaces (lan and wan) and their associated devices (br-lan and eth0), as well as a switch section if applicable.

Note that the labels WAN and LAN can mean different things depending on the context.

The central network configuration is handled by the UCI network subsystem, and stored in the file /etc/config/network. This UCI subsystem is responsible for defining switch VLANs, interface configurations and network routes. After network configuration customization you need to reload or restart the network service to apply the changes.

The network service manages both wired and wireless networking with netifid and wifi respectively.

Individual interfaces can be brought up with ifup name or down with ifdown name where name corresponds to the logical interface name of the corresponding config interface section. Keep in mind that ifup is normally enough to reload an interface since it includes ifdown.

Note that wireless interfaces are managed externally and ifup may break the relation to existing bridges. In such a case it is required to run wifi up after ifup in order to re-establish the bridge connection.

# Soft network reload
service network reload
 
# Hard network restart
service network restart
 
# Reconnect interface
ifdown wan6
ifup wan6
 
# Wireless reload
wifi down
wifi up
 
# List interfaces
ubus list network.interface.*
 
# Status information
ifstatus wan6

Here an example network UCI subsystem with default settings for a TL-WR1043ND:

config interface 'loopback'
	option device 'lo'
	option proto 'static'
	option ipaddr '127.0.0.1'
	option netmask '255.0.0.0'
 
config globals 'globals'
	option ula_prefix 'fd27:70fa:5c1d::/48'
 
config device 'lan_br'
	option name 'br-lan'
	option type 'bridge'
	list ports 'eth0.1'
 
config interface 'lan'
	option device 'br-lan'
	option proto 'static'
	option netmask '255.255.255.0'
	option ip6assign '60'
	option ipaddr '192.168.1.1'
 
config interface 'wan'
	option device 'eth0.2'
	option proto 'dhcp'
 
config interface 'wan6'
	option device 'eth0.2'
	option proto 'dhcpv6'
 
config switch
	option name 'switch0'
	option reset '1'
	option enable_vlan '1'
 
config switch_vlan
	option device 'switch0'
	option vlan '1'
	option ports '1 2 3 4 5t'
 
config switch_vlan
	option device 'switch0'
	option vlan '2'
	option ports '0 5t'

The globals section contains interface-independent options affecting the network configuration in general.

config globals 'globals'
	option ula_prefix 'fd27:70fa:5c1d::/48'

The device section is optional when L2 and L3 is the same device, i.e. MAC and IP on the same physical interface.

config device 'lan_br'
	option name 'br-lan'
	option type 'bridge'
	list ports 'eth0.1'

Other example: enable flow control for interface eth2:

config device                          
        option name 'eth2'                        
        option rxpause '1'             
        option txpause '1'

TODO: move everything related to bridges and layer 2 here.

Sections of the type interface declare logical networks serving as containers for IP address settings, aliases, routes, physical interface names and firewall rules - they play a central role within the OpenWrt configuration concept.

A minimal interface declaration consists of the following lines:

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

• wan is a unique logical interface name
• dhcp specifies the interface protocol, DHCP in this example
• eth0.2 is the physical interface associated with this section

The interface protocol may be one of the following:

Depending on the used interface protocol several other options may be required for a complete interface declaration. The corresponding options for each protocol are listed below. Options marked as “yes” in the “Required” column must be defined in the interface section if the corresponding protocol is used, options marked as “no” may be defined but can be omitted as well.

If an interface section has no protocol defined (not even none ), the other settings are completely ignored. The result is that, if the interface section is mentioning a physical network interface (i.e. eth0), this will be down even if a cable is connected (with proto 'none' the interface is up).

Common options options valid for all protocol types.

Name	Type	Required	Default	Description
device	string	yes(*)	(none)	L3 device name, such as eth0.1, eth2, tun0, br-lan, etc. Needs to match the name option of the respective device section. Do not specify wireless interfaces as their names and behavior can be dynamic and unpredictable, instead assign wireless interfaces to bridges using the network option in wireless configuration. This option may be empty or missing if only a wireless interface references this network or if the protocol is pptp, pppoa, 6in4, etc.
mtu	number	no	(none)	Override the default MTU on this interface
auto	boolean	no	0 for proto none, else 1	Specifies whether to bring up interface on boot
ipv6	boolean	no	1	Specifies whether to enable (1) or disable (0) IPv6 on this interface (Barrier Breaker and later only)
force_link	boolean	no	1 for protocol static, else 0	Specifies whether ip address, route, and optionally gateway are assigned to the interface regardless of the link being active ('1') or only after the link has become active ('0'); when set to '1', carrier sense events do not invoke hotplug handlers
disabled	boolean	no	0	enable or disable the interface section
ip4table	string	no	(none)	IPv4 routing table for routes of this interface, see: ip rule show; ip route show table <ip4table>
ip6table	string	no	(none)	IPv6 routing table for routes of this interface, see: ip -6 rule show; ip -6 route show table <ip6table>

All bridge settings are optional.

Name	Type	Default	Range	Description
bridge_empty	boolean	0	0, 1	Enables creating empty bridges
vlan_filtering	boolean	0	0, 1	Enables VLAN aware bridge mode
igmp_snooping	boolean	0	0, 1	Enables IGMP snooping on the bridge, an optimization that only sends multicast traffic to ports with multicast clients or routers
multicast_querier	boolean	(igmp_snooping setting)	0, 1	IGMP Enables the bridge as a multicast querier, which keeps the multicast group to port mappings current. Only one querier is elected per subnet
query_interval	number	12500	-	IGMP Interval in 1/100 seconds between querier general queries (so default is 125 seconds)
query_response_interval	number	1000	(less than query_interval)	IGMP Max time in 1/100 seconds responses to queries should be sent (increase to make IGMP less bursty)
last_member_interval	number	100	-	IGMP Max time in 1/100s responses to queries after “leave group” messages (the leave latency)
hash_max	number	512	-	IGMP Size of kernel multicast hash table (larger to avoid collisions that disable snooping)
robustness	number	2	-	IGMP Sets Startup Query Count and Last Member Count. Also combined with query_interval and query_response_interval to calculate Group Membership Interval and “other querier” timeout (both other values must be set)
stp	boolean	0	0, 1	Enables the Spanning Tree Protocol (STP) which prevents network loops (and resulting packet storms)
forward_delay	number	2	2 - 30	STP Delay in seconds between port state transitions from Listening → Learning → Forwarding (i.e. bridge ports will be blocked for 2x this value when brought up) NOTE The default 2 is below the minimum 802.1D standard of 4, and STP will be ignored by conforming switches. Set to at least 4 to work with non-OpenWrt switches!
hello_time	number	2	1 - 10	STP Seconds between STP packets
priority	number	32767	0 - 65535	STP Bridge Priority. Lowest priority bridge becomes the Root of the Spanning Tree; most switches default to 32768
ageing_time	number	300	10 - 1000000	STP Expire in seconds for dynamic MAC entries in the Filtering DB
max_age	number	20	6 - 40	STP After current Root Bridge absent this many seconds, attempt to become the Root Bridge (effects the speed a dead bridge is identified)

, see: DSA networking

For many users, the default switch configuration is sufficient. Should the user need to configure the switch differently, LuCI, UCI, or direct editing of /etc/config/network may be used to achieve different configurations. Prior to any reconfiguration of the switch, an understanding of the default configuration is important. As an example, some devices have a single switch-connected interface, and other have two or more.

See also:

• swconfig
• VLAN
• Switch Documentation (Older content, but does give discuss single-interface configuration)

The identifier for the switch(es) may be obtained using:

# swconfig list
Found: switch0 - ag71xx-mdio.0

With the identifier known, the configuration can be viewed:

# swconfig dev switch0 show
Global attributes:
	enable_vlan: 1
	enable_mirror_rx: 0
	enable_mirror_tx: 0
	mirror_monitor_port: 0
	mirror_source_port: 0
	arl_age_time: 300
	arl_table: address resolution table
[...]

There are three types of switch-related configuration stanzas, switch, switch_vlan, and switch_port.

Not all options are available on all hardware. Some limitations may be found with swconfig dev <dev> help. After making changes, check the output of swconfig to determine if the configuration was accepted by the switch hardware.

: The list of options may be incomplete. The details of each option need additional discovery and documentation, including checking of the underlying code. The source of restrictions on value ranges has yet to be identified. Valid values should be confirmed in the code.