Network configuration
The central network configuration is located in /etc/config/network. This configuration is responsible for defining switch VLANs, interface configurations and network routes.
Sections
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.
Switch
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.
/proc/switch
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.
swconfig
The newer swconfig framework is intended to replace the legacy switch configuration soon. It is currently used on some devices like the D-Link DIR-300.
Swconfig based configurations have a different structure with one extra section per vlan. The example below shows the standard configuration on a D-Link DIR-300 running the Kamikaze 8.09 branch:
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.
Interfaces
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'
wanis a unique logical interface namedhcpspecifies the interface protocol, DHCP in this exampleeth0.1is the physical interface associated with this section
The interface protocol may be one of the following:
| Protocol | Description |
|---|---|
static | Static configuration with fixed address and netmask |
dhcp | Address and netmask are assigned by DHCP |
ppp | PPP protocol - dialup modem connections |
pppoe | PPP over Ethernet - DSL broadband connection |
pppoa | PPP over ATM - DSL connection using a builtin modem |
3g | CDMA, UMTS or GPRS connection using an AT-style 3G modem |
pptp | Connection via PPtP VPN |
6in4 | IPv6-in-IPv4 tunnel |
none | Unspecified protocol |
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.
Options valid for all protocol types
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
ifname | interface name(s) | yes(*) | (none) | Physical interface name to assign to this section, list of interfaces if type bridge is set. (*) This option may be empty or missing if only a wireless interface references this network or if the protocol type is pptp or 6in4 |
type | string | no | (none) | If set to "bridge", a bridge containing the given ifnames is created |
stp | boolean | no | 0 | Only valid for type "bridge", enables the Spanning Tree Protocol |
macaddr | mac address | no | (none) | Override MAC address of this interface |
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 |
Protocol "static"
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
ipaddr | ip address | yes, if no ip6addr is set | (none) | IP address |
netmask | netmask | yes, if no ip6addr is set | (none) | Netmask |
gateway | ip address | no | (none) | Default gateway |
bcast | ip address | no | (none) | Broadcast address (autogenerated if not set) |
ip6addr | ipv6 address | yes, if no ipaddr is set | (none) | Assign given IPv6 address to this interface (CIDR notation) |
ip6gw | ipv6 address | no | (none) | Assign given IPv6 default gateway to this interface |
dns | list of ip addresses | no | (none) | DNS server(s) |
Protocol "dhcp"
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
gateway | string | no | (none) | Supresses DHCP-assigned default gateway if set to 0.0.0.0 |
broadcast | boolean | no | 0 | Enable the broadcast flag in DHCP requests, required for certain ISPs, e.g. Charter with DOCSIS 3 |
hostname | string | no | (none) | Hostname to include in DHCP requests |
clientid | string | no | system default | Override client identifier in DHCP requests |
dns | list of ip addresses | no | (none) | Override DHCP-assigned DNS server(s) |
Protocol "ppp" (PPP over Modem)
The package ppp must be installed to use PPP.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
device | file path | yes | (none) | Modem device node |
username | string | no(?) | (none) | Username for PAP/CHAP authentication |
password | string | no(?) | (none) | Password for PAP/CHAP authentication |
connect | file path | no | (none) | Path to custom PPP connect script |
disconnect | file path | no | (none) | Path to custom PPP disconnect script |
keepalive | number | no | (none) | Number of connection failures before reconnect |
demand | number | no | (none) | Number of seconds to wait before closing the connection due to inactivity |
defaultroute | boolean | no | 1 | Replace existing default route on PPP connect |
peerdns | boolean | no | 1 | Use peer-assigned DNS server(s) |
dns | list of ip addresses | no | (none) | Override peer-assigned DNS server(s) |
ipv6 | boolean | no | 0 | Enable IPv6 on the PPP link |
pppd_options | string | no | (none) | Additional command line arguments to pass to the pppd daemon |
Protocol "pppoe" (PPP over Ethernet)
The package ppp-mod-pppoe must be installed to use PPPoE.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
username | string | no(?) | (none) | Username for PAP/CHAP authentication |
password | string | no(?) | (none) | Password for PAP/CHAP authentication |
connect | file path | no | (none) | Path to custom PPP connect script |
disconnect | file path | no | (none) | Path to custom PPP disconnect script |
keepalive | number | no | (none) | Number of connection failures before reconnect |
demand | number | no | (none) | Number of seconds to wait before closing the connection due to inactivity |
defaultroute | boolean | no | 1 | Replace existing default route on PPP connect |
peerdns | boolean | no | 1 | Use peer-assigned DNS server(s) |
dns | list of ip addresses | no | (none) | Override peer-assigned DNS server(s) |
ipv6 | boolean | no | 0 | Enable IPv6 on the PPP link |
pppd_options | string | no | (none) | Additional command line arguments to pass to the pppd daemon |
Protocol "pppoa" (PPP over ATM)
The package ppp-mod-pppoa must be installed to use PPPoA.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
unit | number | yes | (none) | br2684 interface number |
vci | number | no | 35 | PPPoA VCI |
vpi | number | no | 8 | PPPoA VPI |
atmdev | number | no | (none) | ATM PVC number |
encaps | string | no | llc | PPPoA encapsulation mode: 'llc' (LLC) or 'vc' (VC) |
payload | string | no | bridged | PPPoA forwarding mode: 'routed' or 'bridged' |
username | string | no(?) | (none) | Username for PAP/CHAP authentication |
password | string | no(?) | (none) | Password for PAP/CHAP authentication |
connect | file path | no | (none) | Path to custom PPP connect script |
disconnect | file path | no | (none) | Path to custom PPP disconnect script |
keepalive | number | no | (none) | Number of connection failures before reconnect |
demand | number | no | (none) | Number of seconds to wait before closing the connection due to inactivity |
defaultroute | boolean | no | 1 | Replace existing default route on PPP connect |
peerdns | boolean | no | 1 | Use peer-assigned DNS server(s) |
dns | list of ip addresses | no | (none) | Override peer-assigned DNS server(s) |
ipv6 | boolean | no | 0 | Enable IPv6 on the PPP link |
pppd_options | string | no | (none) | Additional command line arguments to pass to the pppd daemon |
Protocol "3g" (PPP over EV-DO, CDMA, UMTS or GRPS)
The package comgt must be installed to use 3G.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
device | file path | yes | (none) | Modem device node |
service | string | yes | gprs | 3G service type: evdo, cdma, umts or gprs |
apn | string | yes | (none) | Used APN |
pincode | number | no | (none) | PIN code to unlock SIM card |
maxwait | number | no | 20 | Number of seconds to wait for modem to become ready |
username | string | no(?) | (none) | Username for PAP/CHAP authentication |
password | string | no(?) | (none) | Password for PAP/CHAP authentication |
keepalive | number | no | (none) | Number of connection failures before reconnect |
demand | number | no | (none) | Number of seconds to wait before closing the connection due to inactivity |
defaultroute | boolean | no | 1 | Replace existing default route on PPP connect |
peerdns | boolean | no | 1 | Use peer-assigned DNS server(s) |
dns | list of ip addresses | no | (none) | Override peer-assigned DNS server(s) |
ipv6 | boolean | no | 0 | Enable IPv6 on the PPP link |
Protocol "pptp" (Point-to-Point Tunneling Protocol)
The package pptp must be installed to use PPtP.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
server | ip address | yes | (none) | Remote PPtP server |
ipproto | string | no | dhcp | Interface protocol used to obtain IP connectivity before establishing PPtP tunnel |
username | string | no(?) | (none) | Username for PAP/CHAP authentication |
password | string | no(?) | (none) | Password for PAP/CHAP authentication |
buffering | boolean | no | 1 | Enables buffering and reordering of packets, 0 disables it (–nobuffer) |
Additionally all options defined for the corresponding ipproto can be specified |
||||
Protocol "6in4" (IPv6-in-IPv4 Tunnel)
The package 6in4 must be installed to use this protocol.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
ipaddr | IPv4 address | no | Current WAN IPv4 address | Local IPv4 endpoint address |
peeraddr | IPv4 address | yes | (none) | Remote IPv4 endpoint address |
ip6addr | IPv6 address (CIDR) | yes | (none) | Local IPv6 address delegated to the tunnel endpoint |
defaultroute | boolean | no | 1 | Whether to create an IPv6 default route over the tunnel |
ttl | integer | no | 64 | TTL used for the tunnel interface |
mtu | integer | no | 1280 | MTU used for the tunnel interface |
wan_device | string | no | (none) | Interface from where client IPv4 endpoint address is derived (used for endpoint update) |
tunnelid | integer | no | (none) | HE.net global tunnel ID (used for endpoint update) |
username | string | no | (none) | HE.net user ID (used for endpoint update) |
password | string | no | (none) | HE.net password (used for endpoint update) |
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.
Protocol "l2tp" (L2TP Pseudowire Tunnel)
The package l2tpv3tun must be installed to use this protocol.
This protocol is only supported on 2.6.35 and newer kernels.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
localaddr | IPv4 address | yes, if no local6addr is set | (none) | Local IPv4 endpoint address |
peeraddr | IPv4 address | yes, if no peer6addr is set | (none) | Remote IPv4 endpoint address |
local6addr | IPv6 address | yes, if no localaddr is set | (none) | Local IPv6 endpoint address |
peer6addr | IPv6 address | yes, if no peeraddr is set | (none) | Remote IPv6 endpoint address |
encap | string | no | udp | L2TPv3 encapsulation mode, either ip or udp |
sport | port number | no | 1701 | L2TPv3 source port, only applicable to UDP encapsulation |
dport | port number | no | 1701 | L2TPv3 destination port, only applicable to UDP encapsulation |
tunnel_id | integer | no | Next unused tunnel ID | Local L2TPv3 tunnel ID |
peer_tunnel_id | integer | no | Value of tunnel_id | Remote L2TPv3 tunnel ID |
session_id | integer | no | Next unused session ID | Local L2TPv3 session ID |
peer_session_id | integer | no | Value of session_id | Remote L2TPv3 session ID |
Additionally all options defined for the static protocol type can be specified |
||||
Aliases
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'
lanis the logical interface name of the parent interfacestaticis the alias interface protocol10.0.0.1specifies the alias ip address255.255.255.0specifies 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.
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
interface | string | yes | (none) | Specifies the logical interface name of the parent (or master) interface this alias is belonging to, must refer to one of the defined interface sections |
proto | string | yes | (none) | Specifies the alias interface protocol |
ipaddr | ip address | yes, if no ip6addr is set | (none) | IP address |
netmask | netmask | yes, if no ip6addr is set | (none) | Netmask |
gateway | ip address | no | (none) | Default gateway |
bcast | ip address | no | (none) | Broadcast address (autogenerated if not set) |
ip6addr | ipv6 address | yes, if no ipaddr is set | (none) | IPv6 address (CIDR notation) |
ip6gw | ipv6 address | no | (none) | IPv6 default gateway |
dns | list of ip addresses | no | (none) | DNS server(s) |
layer | integer | no | 3 | Selects the interface to attach to for stacked protocols (tun over bridge over eth, ppp over eth or similar). 3: attach to layer 3 interface (tun*, ppp* if parent is layer 3 else fallback to 2) 2: attach to layer 2 interface (br-* if parent is bridge else fallback to layer 1) 1: attach to layer 1 interface (eth*, wlan*) |
IPv4 Routes
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'
lanis the logical interface name of the parent interface172.16.123.0is the network address of the route255.255.255.0specifies the route netmask
Legal options for IPv4 routes are:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
interface | string | yes | (none) | Specifies the logical interface name of the parent (or master) interface this route is belonging to, must refer to one of the defined interface sections |
target | ip address | yes | (none) | Network address |
netmask | netmask | no | (none) | Route netmask. If ommitted, 255.255.255.255 is assumed which makes target a host address |
gateway | ip address | no | (none) | Network gateway. If ommitted, the gateway from the parent interface is taken, if set to 0.0.0.0 no gateway will be specified for the route |
metric | number | no | 0 | Specifies the route metric to use |
mtu | number | no | interface MTU | Define a specific MTU for this route |
IPv6 Routes
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'
lanis the logical interface name of the parent interface2001:0DB8:100:F00:BA3::1/64is the routed IPv6 subnet in CIDR notation2001:0DB8:99::1specifies the IPv6 gateway for this route
Legal options for IPv6 routes are:
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
interface | string | yes | (none) | Specifies the logical interface name of the parent (or master) interface this route is belonging to, must refer to one of the defined interface sections |
target | ipv6 address | yes | (none) | IPv6 network address |
gateway | ipv6 address | no | (none) | IPv6 gateway. If ommitted, the gateway from the parent interface is taken |
metric | number | no | 0 | Specifies the route metric to use |
mtu | number | no | interface MTU | Define a specific MTU for this route |
Examples
Below are a few examples for special, non-standard interface configurations.
Bridge without IP
config 'interface' 'example'
option 'type' 'bridge'
option 'proto' 'none'
option 'ifname' 'eth0 eth1'
option 'auto' '1'
DHCP without default gateway
config 'interface' 'example'
option 'proto' 'dhcp'
option 'ifname' 'eth0'
option 'gateway' '0.0.0.0'
DHCP and IPv6
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'
Static IP configuration and default gateway with non-zero metric
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'
PPtP-over-PPPoE internet connection
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'
option 'input' 'REJECT'
option 'forward' 'REJECT'
option 'output' 'ACCEPT'
option 'masq' '1'
Static IPv6-in-IPv4 tunnel
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'
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.
Dynamic IPv6-in-IPv4 tunnel (HE.net only)
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.
L2TPv3 Pseudowire bridged to LAN
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'
doc/uci/network.txt · Last modified: 2010/08/09 04:39 by jow