The central network configuration is located in /etc/config/network. This configuration is responsible for defining switch VLANs, interface configurations and network routes.

Hint: After editing /etc/config/network you need to execute

/etc/init.d/network restart

Below is an overview of the section types that may be defined in the network configuration. A minimal network configuration for a router usually consists of at least two interfaces (lan and wan) and a switch section if applicable.

The switch section is responsible for partitionating the switch into several VLANs which appear as independant interfaces in the system although they share the same hardware. Not every OpenWrt supported device has a programmable switch, therefore this section might not be present on some platforms.

There are currently two different configuration formats in use, one for the legacy /proc/switch/ API and one for the newer swconfig based switch infrastructure.

This variant is only found on Broadcom devices like the WRT54GL.

A typical configuration for it looks like this:

config 'switch' 'eth0'
        option 'vlan0' '0 1 2 3 5*'
        option 'vlan1' '4 5'

The eth0 identifier specifies the switch the section is belonging to. VLANs are defined by vlan# options with # being the VLAN number. For further information refer to the switch documentation.

The newer swconfig framework is intended to replace the legacy switch configuration.

The typical filepath for the config is /etc/config/network

Swconfig based configurations have a different structure with one extra section per vlan. The example below shows a typical configuration:

config 'switch' 'eth0'
        option 'reset' '1'
        option 'enable_vlan' '1'

config 'switch_vlan' 'eth0_1'
        option 'device' 'eth0'
        option 'vlan' '1'
        option 'ports' '0 1 2 3 5t'

config 'switch_vlan' 'eth0_2'
        option 'device' 'eth0'
        option 'vlan' '2'
        option 'ports' '4 5t'

Common properties are defined within the switch section, vlan specific properties are located in additional switch_vlan sections linked to the switch section through the device option. The complete layout is explained in the switch documentation.

Sections of the type interface declare logical networks serving as container 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 'ifname' 'eth0.1'

• wan is a unique logical interface name
• dhcp specifies the interface protocol, DHCP in this example
• eth0.1 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.

The package ppp must be installed to use PPP.

The package ppp-mod-pppoe must be installed to use PPPoE.

The package ppp-mod-pppoa must be installed to use PPPoA.

The package comgt must be installed to use 3G. Check 3gdongle for further help with that.

The package pptp must be installed to use PPtP. There is a separate Howto for this: vpn.client.pptp. You need to have another section to configure the "parent" device, and you might need to add "<vpn>" to your "wan" zone in the firewall (<vpn> being the "logical interface name" of this section).

The package 6in4 must be installed to use this protocol.

Note: This protocol type does not need an ifname option set in the interface section. The interface name is derived from the section name, e.g. config interface sixbone would result in an interface named 6in4-sixbone.

The package 6to4 must be installed to use this protocol.

Note: This protocol type does not need an ifname option set in the interface section. The interface name is derived from the section name, e.g. config interface wan6 would result in an interface named 6to4-wan6.
Note: If radvd is installed an enabled, the 6to4 scripts will add a temporary prefix and interface declaration to the radvd uci configuration and perform a daemon restart if required.

The package l2tpv3tun must be installed to use this protocol.
This protocol is only supported on 2.6.35 and newer kernels.

The package relayd must be installed to use this protocol.

The package br2684ctl must be installed to use Ethernet over AAL5.

ATM bridges use a special config section called atm-bridge. Each atm-bridge section maps the specified ATM curcuit an atm# pseudo ethernet device which can be used for example in conjunction with pppoe to establish a DSL connection to the ISP.

A typical bridge section looks like this:

config atm-bridge
       option unit     '0'
       option vpi      '8'
       option vci      '35'

• Unit 0 will let br2684ctl create a nas0 pseudo device
• VPI 0 and VCI 35 specifies the circuit to bridge. Those values are ISP dependant.

The atm-bridge section allows the following options:

Alias sections can be used to define further IPv4 and IPv6 addresses for interfaces. They also allow combinations like DHCP on the main interface and a static IPv6 address in the alias, for example to deploy IPv6 on wan while keeping normal internet connectivity. Each interface can have multiple aliases attached to it.

A minimal alias declaration consists of the following lines:

config 'alias'
        option 'interface' 'lan'
        option 'proto' 'static'
        option 'ipaddr' '10.0.0.1'
        option 'netmask' '255.255.255.0'

• lan is the logical interface name of the parent interface
• static is the alias interface protocol
• 10.0.0.1 specifies the alias ip address
• 255.255.255.0 specifies the alias netmask

At the time of writing, only the static protocol type is allowed for aliases. Defined options for alias sections are listed below.

It is possible to define arbitary IPv4 routes on specific interfaces using route sections. As for aliases, multiple sections can be attached to an interface.

A minimial example looks like this:

config 'route'
        option 'interface' 'lan'
        option 'target' '172.16.123.0'
        option 'netmask' '255.255.255.0'

• lan is the logical interface name of the parent interface
• 172.16.123.0 is the network address of the route
• 255.255.255.0 specifies the route netmask

Legal options for IPv4 routes are:

IPv6 routes can be specified as well by defining one or more route6 sections.

A minimial example looks like this:

config 'route6'
        option 'interface' 'lan'
        option 'target' '2001:0DB8:100:F00:BA3::1/64'
        option 'gateway' '2001:0DB8:99::1'

• lan is the logical interface name of the parent interface
• 2001:0DB8:100:F00:BA3::1/64 is the routed IPv6 subnet in CIDR notation
• 2001:0DB8:99::1 specifies the IPv6 gateway for this route

Legal options for IPv6 routes are:

Below are a few examples for special, non-standard interface configurations.

config 'interface' 'example'
        option 'type'    'bridge'
        option 'proto'   'none'
        option 'ifname'  'eth0 eth1'
        option 'auto'    '1'

config 'interface' 'example'
        option 'proto'   'dhcp'
        option 'ifname'  'eth0'
        option 'gateway' '0.0.0.0'

config 'interface' 'example'
        option 'proto'     'dhcp'
        option 'ifname'    'eth0'

config 'alias'
        option 'interface' 'example'
        option 'proto'     'static'
        option 'ip6addr'   '2001:0DB8:100:F00:BA3::1'

config 'interface' 'example'
        option 'proto'     'static'
        option 'ifname'    'eth0'
        option 'ipaddr'    '192.168.1.200'
        option 'netmask'   '255.255.255.0'
        option 'dns'       '192.168.1.1'

config 'route'
        option 'interface' 'example'
        option 'target'    '0.0.0.0'
        option 'netmask'   '0.0.0.0'
        option 'gateway'   '192.168.1.1'
        option 'metric'    '100'

config 'interface' 'wan'
        option 'proto'     'pppoe'
        option 'ifname'    'eth1'
        option 'username'  'user'
        option 'password'  'pass'
        option 'timeout'   '10'

config 'interface' 'vpn'
        option 'proto'     'pptp'
        option 'ifname'    'vpn'
        option 'username'  'vpnuser'
        option 'password'  'vpnpass'
        option 'server'    'vpn.example.org'

Additionally the "wan" firewall zone must include both interfaces in /etc/config/firewall:

config 'zone'
        option 'name'      'wan'
        option 'network'   'wan vpn'  # Important
        option 'input'     'REJECT'
        option 'forward'   'REJECT'
        option 'output'    'ACCEPT'
        option 'masq'      '1'

The example below illustrates a static tunnel configuration for the Hurricane Electric (he.net) broker. Option ipaddr specifies the local IPv4 address, peeraddr is the broker IPv4 address and ip6addr the local IPv6 address routed via the tunnel.

config 'interface' 'henet'
        option 'proto'     '6in4'
        option 'ipaddr'    '178.24.115.19'
        option 'peeraddr'  '216.66.80.30'
        option 'ip6addr'   '2001:0DB8:1f0a:1359::2/64'

To apply IPv6 firewall rules to the tunnel interface, add it to the "wan" zone in /etc/config/firewall:

config 'zone'
        option 'name'      'wan'
        option 'network'   'wan henet'  # Important
        option 'input'     'REJECT'
        option 'forward'   'REJECT'
        option 'output'    'ACCEPT'
        option 'masq'      '1'

If you define a new, dedicated zone just for the tunnel interface, make sure to set option conntrack 1 in order to force enabling connection tracking, otherwise unidirectional forwarding rules will not work.

The example below illustrates a dynamic tunnel configuration for the Hurricane Electric (he.net) broker with enabled IP update. The local IPv4 address is automatically determined and tunnelid, username and password are provided for IP update.

config 'interface' 'henet'
        option 'proto'     '6in4'
        option 'peeraddr'  '216.66.80.30'
        option 'ip6addr'   '2001:0DB8:1f0a:1359::2/64'
        option 'tunnelid'  '12345'
        option 'username'  '098f6bcd4621d373cade4e832627b4f6'
        option 'password'  'secret'

To apply IPv6 firewall rules to the tunnel interface, add it to the "wan" firewall zone, see example above for details.

This example establishes a Pseudowire Tunnel and bridges it to the LAN ports. The existing lan interface is reused with protocol l2tp instead of static.

config 'interface' 'lan'
        option 'proto'     'l2tp'
        option 'type'      'bridge'
        option 'ifname'    'eth0'
        option 'ipaddr'    '192.168.1.1'
        option 'netmask'   '255.255.255.0'
        option 'localaddr' '178.24.154.19'
        option 'peeraddr'  '89.44.33.61'
        option 'encap'     'udp'
        option 'sport'     '4000'
        option 'dport'     '5410'

This example setups a relayd pseudo bridge between a wireless client network and LAN, so that it works similar to the Broadcom Bridged Client mode.

Wireless configuration (excerpt):

config wifi-iface
        option 'device'     'radio0'
        option 'mode'       'sta'
        option 'ssid'       'Some Wireless Network'
        option 'encryption' 'psk2'
        option 'key'        '12345678'
        option 'network'    'wwan'

Network configuration (excerpt):
Note that the LAN subnet must be different from the one used by wireless network's DHCP.

config 'interface' 'lan'
        option 'ifname'     'eth0.1'
        option 'proto'      'static'
        option 'ipaddr'     '192.168.1.1'
        option 'netmask'    '255.255.255.0'

config 'interface' 'wwan'
        option 'proto'      'dhcp'

config 'interface' 'stabridge'
        option 'proto'      'relay'
        option 'network'    'lan wwan'

In contrast to true bridging, traffic forwarded in this manner is affected by firewall rules, therfore both the wireless client network and the lan network should be covered by the same LAN firewall zone with forward policy set to accept to allow traffic flow between both interfaces:

config 'zone'
        option 'name'        'lan'
        option 'network'     'lan wwan'  # Important
        option 'input'       'ACCEPT'
        option 'forward'     'ACCEPT'    # Important
        option 'output'      'ACCEPT'

The complete network configuration can be re-applied by running /etc/init.d/network restart. 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. An ifup implies a prior ifdown so there is no need to invoke both when reloading an interface.

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.

In order to derive a Linux interface name like eth1 from a logical network name like wan for use in scripts or tools like ifconfig and route the uci utility can be used like illustrated in the iptables example below which opens port 22 on the interface.

WANIF=$(uci -P/var/state get network.wan.ifname)
iptables -I INPUT -i $WANIF -p tcp --dport 22 -j ACCEPT