6 == Network configuration
8 The central network configuration is located in the file **'/etc/config/network'**. This configuration file is responsible for defining _switch VLANs_, _interface configurations_ and _network routes_.
10 After editing and saving '/etc/config/network' you need to execute '/etc/init.d/network reload' to stop and restart the network before any changes take effect. Rebooting the router is not necessary.
12 Feel free to inform yourself about link:procd.html[netifd] (Network Interface Daemon).
16 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.
20 The 'globals' section contains interface-independent options affecting the network configuration in general.
22 [cols="4*1,4",options="header"]
24 | Name | Type | Required | Default | Description
25 | 'ula_prefix' | IPv6-prefix | no | _(none)_ | IPv6 ULA-Prefix for this device
30 The 'switch' section is responsible for partitioning the switch into several _VLANs_ which appear as independent interfaces in the system although they share the same hardware. **Not every OpenWrt supported device (or architecture, like x86) has a programmable switch**, therefore this section might not be present on some platforms. Please also note, that some switches only support 4Bit-VLANs.
32 The example below shows a typical configuration:
35 config 'switch' 'eth0'
37 option 'enable_vlan' '1'
39 config 'switch_vlan' 'eth0_1'
40 option 'device' 'eth0'
42 option 'ports' '0 1 2 3 5t'
44 config 'switch_vlan' 'eth0_2'
45 option 'device' 'eth0'
50 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.
54 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.
56 A minimal interface declaration consists of the following lines:
59 config 'interface' 'wan'
61 option 'ifname' 'eth0.1'
64 * 'wan' is a unique _logical interface name_
65 * 'dhcp' specifies the _interface protocol_, DHCP in this example
66 * 'eth0.1' is the _physical interface_ associated with this section
68 *CAUTION*: The system limits the interface name length to 15 characters including the automatically added prefix that is added for some protocols (e.g. "6in4-", "pppoa-", "pppoe-") or due to bridge status ("br-"). Depending on the protocol type, the _logical interface name_ may thus be limited to only 9 characters. E.g. 'abcde67890' is a valid interface name for a normal interface using dhcp, but not for a pppoe interface where the final name would be 'pppoe-abcde67890', which is >15 chars. Using a too long name may lead into errors, as some of the settings in network, firewall or dhcp config may be left unapplied.
70 The _interface protocol_ may be one of the following:
72 [cols="1,4,2",options="header"]
74 | Protocol | Description | Program
75 | 'static' | Static configuration with fixed address and netmask | 'ip'/'ifconfig'
76 | 'dhcp' | Address and netmask are assigned by DHCP | 'udhcpc' (Busybox)
77 | 'dhcpv6' | Address and netmask are assigned by DHCPv6 | 'odhcpc6c'
78 | 'ppp' | PPP protocol - dialup modem connections | 'pppd'
79 | 'pppoe' | PPP over Ethernet - DSL broadband connection | 'pppd' + 'plugin rp-pppoe.so'
80 | 'pppoa' | PPP over ATM - DSL connection using a builtin modem | 'pppd' + plugin ...
81 | '3g' | CDMA, UMTS or GPRS connection using an AT-style 3G modem | 'comgt'
82 | 'qmi' | USB modems using QMI protocol | 'uqmi'
83 | 'ncm' | USB modems using NCM protocol | 'comgt-ncm' + ?
84 | 'wwan' | USB modems with protocol autodetection | 'wwan'
85 | 'hnet' | Self-managing home network (HNCP) | 'hnet-full'
86 | 'pptp' | Connection via PPtP VPN | ?
87 | '6in4' | IPv6-in-IPv4 tunnel for use with Tunnel Brokers like HE.net | ?
88 | 'aiccu' | Anything-in-anything tunnel | 'aiccu'
89 | '6to4' | Stateless IPv6 over IPv4 transport | ?
90 | '6rd' | IPv6 rapid deployment | '6rd'
91 | 'dslite' | Dual-Stack Lite | 'ds-lite'
92 | 'l2tp' | PPP over L2TP Pseudowire Tunnel | 'xl2tpd'
93 | 'relay' | relayd pseudo-bridge | 'relayd'
94 | 'gre', 'gretap' | GRE over IPv4 | 'gre' + 'kmod-gre'
95 | 'grev6', 'grev6tap' | GRE over IPv6 | 'gre' + 'kmod-gre6'
96 | 'vti' | VTI over IPv4 | 'vti' + 'kmod-ip_vti'
97 | 'vtiv6' | VTI over IPv6 | 'vti' + 'kmod-ip6_vti'
98 | 'none' | Unspecified protocol, therefore all the other interface settings will be ignored (like disabling the configuration) | -
101 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.
103 === Options valid for all protocol types ===
105 [cols="4*1,4",options="header"]
107 | Name | Type | Required | Default | Description
108 | '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', 'pppoa' or '6in4'_
109 | 'type' | string | no | _(none)_ | If set to "bridge", a bridge containing the given _ifnames_ is created
110 | 'stp' | boolean | no | '0' | Only valid for type "bridge", enables the Spanning Tree Protocol
111 | 'bridge_empty' | boolean | no | '0' | Only valid for type "bridge", enables creating empty bridges
112 | 'igmp_snooping' | boolean | no | '1' | Only valid for type "bridge", sets the multicast_snooping kernel setting for a bridge
113 | 'macaddr' | mac address | no | _(none)_ | Override MAC address of this interface
114 | 'mtu' | number | no | _(none)_ | Override the default MTU on this interface
115 | 'auto' | boolean | no | '0' for proto 'none', else '1' | Specifies whether to bring up interface on boot
116 | 'ipv6' | boolean | no | '1' | Specifies whether to enable (1) or disable (0) IPv6 on this interface
117 | '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
118 | 'enabled' | boolean | no | '1' | enable or disable the interface section
119 | 'ip4table' | string | no | _(none)_ | (ipv4) routing table for routes of this interface. E.g., when proto = dhcp, the dhcp client will add routes to that table
120 | 'ip6table' | string | no | _(none)_ | (ipv6) routing table for routes of this interface. E.g., when proto = dhcp6, the dhcp6 client will add routes to that table
123 === Protocol "static" ===
125 [cols="4*1,4",options="header"]
127 | Name | Type | Required | Default | Description
128 | 'ipaddr' | ip address | yes, if no 'ip6addr' is set. | _(none)_ | IP address.
129 | 'netmask' | netmask | yes, if no 'ip6addr' is set | _(none)_ | Netmask
130 | 'gateway' | ip address | no | _(none)_ | Default gateway
131 | 'broadcast' | ip address | no | _(none)_ | Broadcast address (autogenerated if not set)
132 | 'ip6addr' | ipv6 address | yes, if no 'ipaddr' is set | _(none)_ | Assign given IPv6 address to this interface (CIDR notation)
133 | 'ip6ifaceid' | ipv6 suffix | no | ::1 | Allowed values: 'eui64', 'random', fixed value like '::1:2'. When IPv6 prefix (like 'a:b:c:d::') is received from a delegating server, use the suffix (like '::1') to form the IPv6 address ('a:b:c:d::1') for this interface. Useful with several routers in LAN.
134 | 'ip6gw' | ipv6 address | no | _(none)_ | Assign given IPv6 default gateway to this interface
135 | 'ip6assign' | prefix length | no | _(none)_ | Delegate a prefix of given length to this interface
136 | 'ip6hint' | prefix hint (hex) | no | _(none)_ | Hint the subprefix-ID that should be delegated as hexadecimal number
137 | 'ip6prefix' | ipv6 prefix | no | _(none)_ | IPv6 prefix routed here for use on other interfaces
138 | 'ip6class' | list of strings | no | _(none)_ | Define the IPv6 prefix-classes this interface will accept
139 | 'dns' | list of ip addresses | no | _(none)_ | DNS server(s)
140 | 'dns_search' | list of domain names | no | _(none)_ | Search list for host-name lookup
141 | 'metric' | integer | no | '0' | Specifies the default route metric to use
144 === Protocol "dhcp" ===
146 [cols="4*1,4",options="header"]
148 | Name | Type | Required | Default | Description
149 | 'broadcast' | boolean | no | '0' | Enable the broadcast flag in DHCP requests, required for certain ISPs, e.g. Charter with DOCSIS 3
150 | 'ipaddr' | IP address | no | _(none)_ | IP address to request from the DHCP server
151 | 'hostname' | string | no | _(none)_ | Hostname to include in DHCP requests
152 | 'clientid' | string | no | _system default_ | Override client identifier in DHCP requests
153 | 'vendorid' | string | no | _system default_ | Override the vendor class in DHCP requests
154 | 'dns' | list of ip addresses | no | _(none)_ | Supplement DHCP-assigned DNS server(s), or use only these if peerdns is 0
155 | 'peerdns' | boolean | no | '1' | Use DHCP-provided DNS server(s)
156 | 'defaultroute' | boolean | no | '1' | Whether to create a default route via the received gateway
157 | 'customroutes' | string | no | _(none)_ | Space-separated list of additional routes to insert via the received gateway
158 | 'metric' | integer | no | '0' | Specifies the route metric to use for both default route and custom routes
159 | 'reqopts' | string | no | _(none)_ | Space-separated list of additional DHCP options to request from the server
160 | 'sendopts' | string | no | _(none)_ | Space-separated list of additional DHCP options to send to the server. Syntax: 'option:value' where 'option' is either an integer code or a symbolic name such as 'hostname'.
161 | 'zone' | firewall zone | no | _(none)_ | Firewall zone to which this interface should be added
162 | 'iface6rd' | logical interface | no | _(none)_ | Logical interface template for auto-configuration of 6rd
163 | 'mtu6rd' | integer | no | _system default_ | MTU of the 6rd interface
164 | 'zone6rd' | firewall zone | no | _system default_ | Firewall zone to which the 6rd interface should be added
167 **Note:** To automatically configure 6rd from dhcp you need to create an interface with 'option auto 0' and put its name as the 'iface6rd' parameter. In addition you also need to add its name to a suitable firewall zone in /etc/config/firewall.
169 === Protocol "dhcpv6" ===
171 [cols="4*1,4",options="header"]
173 | Name | Type | Required | Default | Description
174 | 'reqaddress' | [try,force,none] | no | try | Behaviour for requesting addresses
175 | 'reqprefix' | [auto,no,0-64] | no | auto | Behaviour for requesting prefixes (numbers denote hinted prefix length). Use 'no' if you only want a single IPv6 address for the AP itself without a subnet for routing
176 | 'clientid' | hexstring | no | _system default_ | Override client identifier in DHCP requests
177 | 'ifaceid' | ipv6 addr | no | _link-local identifier_ | Override the interface identifier for adresses received via RA
178 | 'dns' | list of ip addresses | no | _(none)_ | Supplement DHCP-assigned DNS server(s), or use only these if peerdns is 0
179 | 'peerdns' | boolean | no | '1' | Use DHCP-provided DNS server(s)
180 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route via the received gateway
181 | 'reqopts' | list of numbers | no | _(none)_ | Specifies a list of additional DHCP options to request
182 | 'noslaaconly' | boolean | no | '0' | Don't allow configuration via SLAAC (RAs) only (implied by reqprefix != no)
183 | 'norelease' | boolean | no | '0' | Don't send a RELEASE when the interface is brought down
184 | 'ip6prefix' | ipv6 prefix | no | _(none)_ | Use an (additional) user-provided IPv6 prefix for distribution to clients
185 | 'iface_dslite' | logical interface | no | _(none)_ | Logical interface template for auto-configuration of DS-Lite
188 **Note:** To automatically configure ds-lite from dhcpv6 you need to create an interface with 'option auto 0' and put its name as the 'iface_dslite' parameter. In addition you also need to add its name to a suitable firewall zone in /etc/config/firewall.
190 === Protocol "ppp" (PPP over Modem) ===
192 *CAUTION*: The package 'ppp' must be installed to use PPP.
194 [cols="4*1,4",options="header"]
196 | Name | Type | Required | Default | Description
197 | 'device' | file path | yes | _(none)_ | Modem device node
198 | 'username' | string | no(?) | _(none)_ | Username for PAP/CHAP authentication
199 | 'password' | string | no(?) | _(none)_ | Password for PAP/CHAP authentication
200 | 'connect' | file path | no | _(none)_ | Path to custom PPP connect script
201 | 'disconnect' | file path | no | _(none)_ | Path to custom PPP disconnect script
202 | 'keepalive' | number | no | _(none)_ | Number of unanswered echo requests before considering the peer dead. The interval between echo requests is 5 seconds.
203 | 'demand' | number | no | _(none)_ | Number of seconds to wait before closing the connection due to inactivity
204 | 'defaultroute' | boolean | no | '1' | Replace existing default route on PPP connect
205 | 'peerdns' | boolean | no | '1' | Use peer-assigned DNS server(s)
206 | 'dns' | list of ip addresses | no | _(none)_ | Override peer-assigned DNS server(s)
207 | 'ipv6' | boolean | no | '0' | Enable IPv6 on the PPP link
208 | 'pppd_options' | string | no | _(none)_ | Additional command line arguments to pass to the pppd daemon
211 === Protocol "pppoe" (PPP over Ethernet) ===
213 *CAUTION*: The packages 'ppp', 'kmod-pppoe' and 'ppp-mod-pppoe' must be installed to use PPPoE.
217 opkg install ppp kmod-pppoe ppp-mod-pppoe
220 [cols="4*1,4",options="header"]
222 | Name | Type | Required | Default | Description
223 | 'username' | string | no(?) | _(none)_ | Username for PAP/CHAP authentication
224 | 'password' | string | no(?) | _(none)_ | Password for PAP/CHAP authentication
225 | 'ac' | string | no | _(none)_ | Specifies the Access Concentrator to connect to. If unset, 'pppd' uses the first discovered one
226 | 'service' | string | no | _(none)_ | Specifies the Service Name to connect to, If unset, 'pppd' uses the first discovered one
227 | 'connect' | file path | no | _(none)_ | Path to custom PPP connect script
228 | 'disconnect' | file path | no | _(none)_ | Path to custom PPP disconnect script
229 | 'keepalive' | number | no | _(none)_ | Number of connection failures before reconnect
230 | 'demand' | number | no | _(none)_ | Number of seconds to wait before closing the connection due to inactivity
231 | 'defaultroute' | boolean | no | '1' | Replace existing default route on PPP connect
232 | 'peerdns' | boolean | no | '1' | Use peer-assigned DNS server(s)
233 | 'dns' | list of ip addresses | no | _(none)_ | Override peer-assigned DNS server(s)
234 | 'ipv6' | boolean | no | '0' | Enable IPv6 on the PPP link
235 | 'pppd_options' | string | no | _(none)_ | Additional command line arguments to pass to the pppd daemon, e.g. **debug**
238 === Protocol "pppoa" (PPP over ATM AAL5) ===
240 *CAUTION*: The package 'ppp-mod-pppoa' must be installed to use PPPoA.
242 [cols="4*1,4",options="header"]
244 | Name | Type | Required | Default | Description
245 | 'vci' | number | no | '35' | PPPoA VCI
246 | 'vpi' | number | no | '8' | PPPoA VPI
247 | 'atmdev' | number | no | '0' | Specifies the ATM adapter number starting with 0. Most systems only have one ATM device and do not need this option
248 | 'encaps' | string | no | 'llc' | PPPoA encapsulation mode: 'llc' (LLC) or 'vc' (VC)
249 | 'username' | string | no(?) | _(none)_ | Username for PAP/CHAP authentication
250 | 'password' | string | no(?) | _(none)_ | Password for PAP/CHAP authentication
251 | 'connect' | file path | no | _(none)_ | Path to custom PPP connect script
252 | 'disconnect' | file path | no | _(none)_ | Path to custom PPP disconnect script
253 | 'keepalive' | number | no | _(none)_ | Number of connection failures before reconnect
254 | 'demand' | number | no | _(none)_ | Number of seconds to wait before closing the connection due to inactivity
255 | 'defaultroute' | boolean | no | '1' | Replace existing default route on PPP connect
256 | 'peerdns' | boolean | no | '1' | Use peer-assigned DNS server(s)
257 | 'dns' | list of ip addresses | no | _(none)_ | Override peer-assigned DNS server(s)
258 | 'ipv6' | boolean | no | '0' | Enable IPv6 on the PPP link
259 | 'pppd_options' | string | no | _(none)_ | Additional command line arguments to pass to the pppd daemon
263 === Protocol "3g" (PPP over EV-DO, CDMA, UMTS or GPRS) ===
265 *CAUTION*: The package 'comgt' must be installed to use 3G.
268 [cols="4*1,4",options="header"]
270 | Name | Type | Required | Default | Description
271 | 'device' | file path | yes | _(none)_ | Modem device node
272 | 'service' | string | yes | 'umts' | 3G service type: 'cdma'/'evdo', 'umts'/'umts_only'/'gprs_only' (...._only options limited to Novatel & Option cards and dongles)
273 | 'apn' | string | yes | _(none)_ | Used APN
274 | 'pincode' | number | no | _(none)_ | PIN code to unlock SIM card
275 | 'dialnumber' | string | no | %%*99***1#%% | Modem dial string e.g. *99#
276 | 'maxwait' | number | no | '20' | Number of seconds to wait for modem to become ready
277 | 'username' | string | no(?) | _(none)_ | Username for PAP/CHAP authentication
278 | 'password' | string | no(?) | _(none)_ | Password for PAP/CHAP authentication
279 | 'keepalive' | number | no | _(none)_ | Number of connection failures before reconnect
280 | 'demand' | number | no | _(none)_ | Number of seconds to wait before closing the connection due to inactivity
281 | 'defaultroute' | boolean | no | '1' | Replace existing default route on PPP connect
282 | 'peerdns' | boolean | no | '1' | Use peer-assigned DNS server(s)
283 | 'dns' | list of ip addresses | no | _(none)_ | Override peer-assigned DNS server(s)
284 | 'ipv6' | boolean | no | '0' | Enable IPv6 on the PPP link
288 === Protocol "qmi" (USB modems using QMI protocol) ===
290 *CAUTION*: The package 'uqmi' must be installed to use QMI.
292 [cols="4*1,4",options="header"]
294 | Name | Type | Required | Default | Description
295 | 'device' | file path | yes | _(none)_ | QMI device node, typically /dev/cdc-wdm0
296 | 'apn' | string | yes | _(none)_ | Used APN
297 | 'pincode' | number | no | _(none)_ | PIN code to unlock SIM card
298 | 'username' | string | no | _(none)_ | Username for PAP/CHAP authentication
299 | 'password' | string | no | _(none)_ | Password for PAP/CHAP authentication
300 | 'auth' | string | no | _(none)_ | Authentication type: pap, chap, both, none
301 | 'modes' | string | no | _(modem default)_ | Allowed network modes, comma separated list of: all, lte, umts, gsm, cdma, td-scdma
302 | 'delay' | number | no | 0 | Seconds to wait before trying to interact with the modem (some ZTE modems require up to 30 s.)
305 === Protocol "ncm" (USB modems using NCM protocol) ===
307 *CAUTION*: The package 'comgt-ncm' + modem specific driver must be installed to use NCM.
309 [cols="4*1,4",options="header"]
311 | Name | Type | Required | Default | Description
312 | 'device' | file path | yes | _(none)_ | NCM device node, typically /dev/cdc-wdm0 or /dev/ttyUSB#
313 | 'apn' | string | yes | _(none)_ | Used APN
314 | 'pincode' | number | no | _(none)_ | PIN code to unlock SIM card
315 | 'username' | string | no | _(none)_ | Username for PAP/CHAP authentication
316 | 'password' | string | no | _(none)_ | Password for PAP/CHAP authentication
317 | 'auth' | string | no | _(none)_ | Authentication type: pap, chap, both, none
318 | 'mode' | string | no | _(modem default)_ | Used network mode, not every device support every mode: preferlte, preferumts, lte, umts, gsm, auto
319 | 'pdptype' | string | no | 'IPV4V6' | Used IP-stack mode, 'IP' (for IPv4), 'IPV6' (for IPv6) or 'IPV4V6' (for dual-stack) (Designated Driver #46844 and later)
320 | 'delay' | number | no | 0 | Seconds to wait before trying to interact with the modem (some modems require up to 30 s.)
323 === Protocol "wwan" (USB modems autodetecting the above 3G/4G protocols) ===
325 *CAUTION*: The package 'wwan' must be installed to use this feature. The "wwan" protocol detects the right protocol (3G/QMI/NCM/MBIM) for the USB Modem model and passes the configuration to the protocol.
327 [cols="4*1,4",options="header"]
329 | Name | Type | Required | Default | Description
330 | 'apn' | string | yes | _(none)_ | Used APN
331 | 'auth' | string | no | _(none)_ | Authentication type: pap, chap, both, none
332 | 'username' | string | no | _(none)_ | Username for PAP/CHAP authentication
333 | 'password' | string | no | _(none)_ | Password for PAP/CHAP authentication
334 | 'pincode' | number | no | _(none)_ | PIN code to unlock SIM card
335 | 'modes' | string | no | _(modem default)_ | Allowed network modes, comma separated list of: all, lte, umts, gsm, cdma, td-scdma
336 | 'delay' | number | no | 0 | Seconds to wait before trying to interact with the modem (some ZTE modems require up to 30 s.)
339 === Protocol "hnet" (Self-managing home network (HNCP)) ===
341 *CAUTION*: The package 'hnet-full' must be installed to use hnet.
342 *CAUTION*: See link:http://tools.ietf.org/html/draft-ietf-homenet-hncp[here] for details.
344 [cols="4*1,4",options="header"]
346 | Name | Type | Required | Default | Description
347 | 'mode' | string | no | auto | Interface mode. One of external, guest, adhoc or hybrid.
348 | 'ip6assign' | integer | no | 64 | IPv6-prefix size to assign to this interface if internal.
349 | 'ip4assign' | integer | no | 24 | IPv4-prefix size to assign to this interface if internal.
350 | 'dnsname' | string | no | <device-name> | DNS-Label to assign to interface.
353 === Protocol "pptp" (Point-to-Point Tunneling Protocol) ===
355 *CAUTION*: The package 'ppp-mod-pptp' must be installed to use 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).
357 [cols="4*1,4",options="header"]
359 | Name | Type | Required | Default | Description
360 | 'server' | ip address | yes | _(none)_ | Remote PPtP server
361 | 'username' | string | no(?) | _(none)_ | Username for PAP/CHAP authentication
362 | 'password' | string | no(?) | _(none)_ | Password for PAP/CHAP authentication
363 | 'keepalive' | number | no | _(none)_ | Number of unanswered echo requests before considering the peer dead. The interval between echo requests is 5 seconds.
364 | 'demand' | number | no | _(none)_ | Number of seconds to wait before closing the connection due to inactivity
365 | 'defaultroute' | boolean | no | '1' | Replace existing default route on PPtP connect
366 | 'peerdns' | boolean | no | '1' | Use peer-assigned DNS server(s)
367 | 'dns' | list of ip addresses | no | _(none)_ | Override peer-assigned DNS server(s)
368 | 'ipv6' | boolean | no | '0' | Enable IPv6 on the PPtP link
369 | 'pppd_options' | string | no | _(none)_ | Additional command line arguments to pass to the pppd daemon
372 === Protocol "6in4" (IPv6-in-IPv4 Tunnel) ===
374 *CAUTION*: The package '6in4' must be installed to use this protocol.
376 [cols="4*1,4",options="header"]
378 | Name | Type | Required | Default | Description
379 | 'ipaddr' | IPv4 address | no | Current WAN IPv4 address | Local IPv4 endpoint address
380 | 'peeraddr' | IPv4 address | yes | _(none)_ | Remote IPv4 endpoint address
381 | 'ip6addr' | IPv6 address (CIDR) | yes | _(none)_ | Local IPv6 address delegated to the tunnel endpoint
382 | 'ip6prefix' | IPv6 prefix | no | _(none)_ | Routed IPv6 prefix for downstream interfaces
383 | 'sourcerouting' | boolean | no | '1' | Whether to route only packets from delegated prefixes
384 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route over the tunnel
385 | 'ttl' | integer | no | '64' | TTL used for the tunnel interface
386 | 'tos' | string | no | _(none)_ | Type Of Service : either "inherit" (the outer header inherits the value of the inner header) or an hexadecimal value. Also known as DSCP.
387 | 'mtu' | integer | no | '1280' | MTU used for the tunnel interface
388 | 'tunnelid' | integer | no | _(none)_ | HE.net global tunnel ID (used for endpoint update)
389 | 'username' | string | no | _(none)_ | HE.net username which you use to login into tunnelbroker, not the User ID shows after you have login int (used for endpoint update)
390 | 'password' | string | no | _(none)_ | HE.net password (used for endpoint update)
391 | 'updatekey' | string | no | _(none)_ | HE.net updatekey, overrides password (used for endpoint update)
392 | 'metric' | integer | no | '0' | Specifies the default route metric to use
395 **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'.
397 **Note:** although ip6prefix isn't required, sourcerouting, enabled by default, will prevent forwarding of packets unless ip6prefix is specified.
399 === Protocol "aiccu" (Automatic IPv6 Connectivity Client Utility) ===
401 *CAUTION*: The package 'aiccu' must be installed to use this protocol. This utility is not meant to be operated in a headless mode. Do not use it if you have some other option. Only AYIYA tunnel type has been tested. For static or heartbeat tunnels, use native 6in4 tunnel instead, perhaps with the he.net Tunnel Broker.
403 [cols="4*1,4",options="header"]
405 | Name | Type | Required | Default | Description
406 | 'username' | string | yes | _(none)_ | Server username
407 | 'password' | string | yes | _(none)_ | Server password
408 | 'protocol' | string | no | _(none)_ | Tunnel setup protocol to use ('tic', 'tsp', 'l2tp')
409 | 'server' | string | no | 'tic.sixxs.net' | Tunnel setup server to use
410 | 'ip6addr' | IPv6 address (CIDR) | no | _(none)_ | Local IPv6 address delegated to the tunnel endpoint (not necessary)
411 | 'ntpsynctimeout' | integer | no | '90' | Wait for NTP sync that many seconds
412 | 'tunnelid' | integer | no | _(none)_ | TIC server tunnel ID
413 | 'ip6prefix' | IPv6 prefix | no | _(none)_ | Routed IPv6 prefix for downstream interfaces
414 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route over the tunnel
415 | 'sourcerouting' | boolean | no | '1' | Whether to route only packets from delegated prefixes
416 | 'tunnelid' | integer | no | _(none)_ | TIC server tunnel ID
417 | 'requiretls' | boolean | no | '0' | Require TLS connection to TIC server
418 | 'nat' | boolean | no | '1' | Notify the user that a NAT-kind network is detected
419 | 'heartbeat' | boolean | no | '1' | Make heartbeats
420 | 'verbose' | boolean | no | '0' | Verbose logging to system log
423 **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 'aiccu-sixbone'.
425 === Protocol "6to4" (IPv6-in-IPv4 Tunnel) ===
427 *CAUTION*: The package '6to4' must be installed to use this protocol.
429 [cols="4*1,4",options="header"]
431 | Name | Type | Required | Default | Description
432 | 'ipaddr' | IPv4 address | no | Current WAN IPv4 address | Local IPv4 endpoint address
433 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route over the tunnel
434 | 'ttl' | integer | no | '64' | TTL used for the tunnel interface
435 | 'tos' | string | no | _(none)_ | Type Of Service : either "inherit" (the outer header inherits the value of the inner header) or an hexadecimal value
436 | 'mtu' | integer | no | '1280' | MTU used for the tunnel interface
437 | 'metric' | integer | no | '0' | Specifies the default route metric to use
438 | 'adv_interface' | string | no | 'lan' | (deprecated) The _logical interface name_ of the network the subnet should be advertised on. Multiple interface names can be given.
439 | 'adv_subnet' | hex number | no | '1' | (deprecated) A subnet ID between '1' and 'FFFF' which selects the advertised /64 prefix from the mapped 6to4 space. The subnet ID is incremented by 1 for every interface specified in 'adv_interface'.
440 | 'adv_valid_lifetime' | integer | no | '300' | (deprecated) Overrides the advertised valid prefix lifetime, in seconds
441 | 'adv_preferred_lifetime' | integer | no | '120' | (deprecated) Overrides the advertised preferred prefix lifetime, in seconds
444 **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'
446 **Note:** If radvd is installed and enabled, the 6to4 scripts will add a temporary prefix and interface declaration to the _radvd_ uci configuration and perform a daemon restart if required. (deprecated)
448 === Protocol "6rd" (IPv6 rapid deployment) ===
450 *CAUTION*: The package '6rd' must be installed to use this protocol.
452 *CAUTION*: The needed tunnel values are usually obtained via the DHCPv4 request for the WAN interface. Try that first. Below is only needed for hardcoding the tunnel.
454 [cols="4*1,4",options="header"]
456 | Name | Type | Required | Default | Description
457 | 'peeraddr' | IPv4 address | yes | no | 6rd - Gateway
458 | 'ipaddr' | IPv4 address | no | Current WAN IPv4 address | Local IPv4 endpoint address
459 | 'ip6prefix' | IPv6 prefix (without length) | yes | no | 6rd-IPv6 Prefix
460 | 'ip6prefixlen' | IPv6 prefix length | yes | no | 6rd-IPv6 Prefix length
461 | 'ip4prefixlen' | IPv6 prefix length | no | 0 | IPv4 common prefix
462 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route over the tunnel
463 | 'ttl' | integer | no | '64' | TTL used for the tunnel interface
464 | 'tos' | string | no | _(none)_ | Type Of Service : either "inherit" (the outer header inherits the value of the inner header) or an hexadecimal value
465 | 'mtu' | integer | no | '1280' | MTU used for the tunnel interface
468 **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 '6rd-wan6'.
470 **Note:** Some ISP's give you the number of bytes you should use from your WAN IP to calculate your IPv6 address. ip4prefixlen expects the _prefix_ bytes of your WAN IP to calculate the IPv6 address. So if your ISP gives you 14 bytes to calculate, enter 18 (32 - 14).
473 === Protocol "dslite" (Dual-Stack Lite) ===
475 *CAUTION*: The package 'ds-lite' must be installed to use this protocol.
477 [cols="4*1,4",options="header"]
479 | Name | Type | Required | Default | Description
480 | 'peeraddr' | IPv6 address | yes | no | DS-Lite AFTR address
481 | 'ip6addr' | IPv6 address | no | Current WAN IPv6 address | Local IPv6 endpoint address
482 | 'tunlink' | Logical Interface | no | Current WAN interface | Tunnel base interface
483 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route over the tunnel
484 | 'ttl' | integer | no | '64' | TTL used for the tunnel interface
485 | 'mtu' | integer | no | '1280' | MTU used for the tunnel interface
488 *CAUTION*: ds-lite operation requires that IPv4 NAT is disabled. You should adjust your settings in /etc/config/firewall accordingly.
490 **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 wan' would result in an interface named 'dslite-wan'.
493 === Protocol "l2tp" (PPP over L2TP Pseudowire Tunnel) ===
495 *CAUTION*: The package 'xl2tpd' must be installed to use this protocol.
497 Most options are similar to protocol "ppp".
499 [cols="4*1,4",options="header"]
501 | Name | Type | Required | Default | Description
502 | 'server' | string | yes | _(none)_ | L2TP server to connect to. Acceptable datatypes are hostname or IP address, with optional port separated by colon ':'. Note that specifying port is only supported recently and should appear in DD release
503 | 'username' | string | no | _(none)_ | Username for PAP/CHAP authentication
504 | 'password' | string | yes if 'username' is provided | _(none)_ | Password for PAP/CHAP authentication
505 | 'ipv6' | bool | no | 0 | Enable IPv6 on the PPP link (IPv6CP)
506 | 'mtu' | int | no | 'pppd' default | Maximum Transmit/Receive Unit, in bytes
507 | 'keepalive' | string | no | _(none)_ | Number of unanswered echo requests before considering the peer dead. The interval between echo requests is 5 seconds.
508 | 'checkup_interval' | int | no | _(none)_ | Number of seconds to pass before checking if the interface is not up since the last setup attempt and retry the connection otherwise. Set it to a value sufficient for a successful L2TP connection for you. It's mainly for the case that netifd sent the connect request yet xl2tpd failed to complete it without the notice of netifd
509 | 'pppd_options' | string | no | _(none)_ | Additional options to pass to 'pppd'
512 The name of the physical interface will be "l2tp-<logical interface name>".
514 === Protocol "relay" (Relayd Pseudo Bridge) ===
516 *CAUTION*: The package 'relayd' must be installed to use this protocol.
518 [cols="4*1,4",options="header"]
520 | Name | Type | Required | Default | Description
521 | 'network' | list of _logical interface names_ | yes | _(none)_ | Specifies the networks between which traffic is relayed
522 | 'gateway' | IPv4 address | no | _(network default)_ | Override the gateway address sent to clients within DHCP responses
523 | 'expiry' | integer | no | '30' | Host expiry timeout in seconds
524 | 'retry' | integer | no | '5' | Number of ARP ping retries before a host is considered dead
525 | 'table' | integer | no | '16800' | Table ID for automatically added routes
526 | 'forward_bcast' | boolean | no | '1' | Enables forwarding of broadcast traffic, '0' disables it
527 | 'forward_dhcp' | boolean | no | '1' | Enables forwarding of DHCP requests and responses, '0' disables it
531 === Common options for GRE protocols ===
533 *CAUTION*: The package 'gre' must be installed to use GRE. Additionally, you need 'kmod-gre' and/or 'kmod-gre6'.
535 Four protocols are defined: "gre", "gretap", "grev6", and "grev6tap". The name of the GRE interface will be 'gre-<logical interface name>' for "gre" and "gretap", and 'grev6-<logical interface name>' for "grev6" and "grev6tap".
537 All four protocols accept the following common options:
539 [cols="4*1,4",options="header"]
541 | Name | Type | Required | Default | Description
542 | 'mtu' | integer | no | 1280 | MTU
543 | 'ttl' | integer | no | 64 | TTL of the encapsulating packets
544 | 'tunlink' | logical interface name | no | _(none)_ | Bind the tunnel to this interface ('dev' option of "ip tunnel")
545 | 'zone' | zone name | no | "wan" | Firewall zone to which the interface will be added
546 | 'tos' | string | no | _(none)_ | Type of Service (IPv4), Traffic Class (IPv6): either "inherit" (the outer header inherits the value of the inner header) or an hexadecimal value
547 | 'ikey' | integer | no | 0 | key for incoming packets
548 | 'okey' | integer | no | 0 | key for outgoing packets
549 | 'icsum' | boolean | no | false | require incoming checksum
550 | 'ocsum' | boolean | no | false | compute outgoing checksum
551 | 'iseqno' | boolean | no | false | require incoming packets serialisation
552 | 'oseqno' | boolean | no | false | perform outgoing packets serialisation
555 === Protocol "gre" (GRE tunnel over IPv4) ===
557 The following options are supported, in addition to all common options above:
559 [cols="4*1,4",options="header"]
561 | Name | Type | Required | Default | Description
562 | 'ipaddr' | IPv4 address | no | WAN IP | Local endpoint
563 | 'peeraddr' | IPv4 address | yes | _(none)_ | Remote endpoint
564 | 'df' | boolean | no | true | Set "Don't Fragment" flag on encapsulating packets
567 === Protocol "gretap" (Ethernet GRE tunnel over IPv4) ===
569 The following options are supported, in addition to all common options above:
571 [cols="4*1,4",options="header"]
573 | Name | Type | Required | Default | Description
574 | 'ipaddr' | IPv4 address | no | WAN IP | Local endpoint
575 | 'peeraddr' | IPv4 address | yes | _(none)_ | Remote endpoint
576 | 'df' | boolean | no | true | Set "Don't Fragment" flag on encapsulating packets
577 | 'network' | logical interface name | no | _(none)_ | Logical network to which the tunnel will be added (bridged)
580 === Protocol "grev6" (GRE tunnel over IPv6) ===
582 The following options are supported, in addition to all common options above:
584 [cols="4*1,4",options="header"]
586 | Name | Type | Required | Default | Description
587 | 'ip6addr' | IPv6 address | no | WAN IP | Local endpoint
588 | 'peer6addr' | IPv6 address | yes | _(none)_ | Remote endpoint
589 | 'weakif' | logical interface name | no | 'lan' | Logical network from which to select the local endpoint if ip6addr parameter is empty and no WAN IP is available
592 === Protocol "grev6tap" (Ethernet GRE tunnel over IPv6) ===
594 The following options are supported, in addition to all common options above:
596 [cols="4*1,4",options="header"]
598 | Name | Type | Required | Default | Description
599 | 'ip6addr' | IPv6 address | no | WAN IP | Local endpoint
600 | 'peer6addr' | IPv6 address | yes | _(none)_ | Remote endpoint
601 | 'weakif' | logical interface name | no | 'lan' | Logical network from which to select the local endpoint if ip6addr is empty and no WAN IP is available
602 | 'network' | logical interface name | no | _(none)_ | Logical network to which the tunnel will be added (bridged)
607 === Protocol "vti" (VTI tunnel over IPv4) ===
609 VTI Tunnels are IPsec policies with a fwmark set. The traffic is redirected to the matching VTI interface.
611 [cols="4*1,4",options="header"]
613 | Name | Type | Required | Default | Description
614 | 'ipaddr' | IPv4 address | no | WAN IP | Local endpoint
615 | 'peeraddr' | IPv4 address | yes | _(none)_ | Remote endpoint
616 | 'mtu' | integer | no | 1280 | MTU
617 | 'tunlink' | logical interface name | no | _(none)_ | Bind the tunnel to this interface ('dev' option of "ip tunnel")
618 | 'zone' | zone name | no | "wan" | Firewall zone to which the interface will be added
619 | 'ikey' | integer | no | 0 | key/fwmark for incoming packets
620 | 'okey' | integer | no | 0 | key/fwmark for outgoing packets
623 === Protocol "vtiv6" (VTI tunnel over IPv6) ===
625 The following options are supported, in addition to all common options above:
627 [cols="4*1,4",options="header"]
629 | Name | Type | Required | Default | Description
630 | 'ip6addr' | IPv6 address | no | WAN IP | Local endpoint
631 | 'peer6addr' | IPv6 address | yes | _(none)_ | Remote endpoint
632 | 'mtu' | integer | no | 1280 | MTU
633 | 'tunlink' | logical interface name | no | _(none)_ | Bind the tunnel to this interface ('dev' option of "ip tunnel")
634 | 'zone' | zone name | no | "wan" | Firewall zone to which the interface will be added
635 | 'ikey' | integer | no | 0 | key/fwmark for incoming packets
636 | 'okey' | integer | no | 0 | key/fwmark for outgoing packets
640 A minimal device declaration consists of the following lines:
643 config device 'eth0.106'
645 option name 'eth0.106'
649 === VLAN Interfaces ===
650 VLAN Interfaces may be configured also. If not, they are created on the fly by netifd. Defining VLANs gives more options.
651 The following options are supported:
653 [cols="4*1,4",options="header"]
655 | Name | Type | Required | Default | Description
656 | 'type' | VLAN Type | no | 802.1q | VLAN type, possible values: 8021q or 8021ad
657 | 'name' | Name | yes | _(none)_ | Name of device, i.e. eth0.5 or vlan5
658 | 'ifname' | Parent interface | yes | _(none)_ | Name of parent/base interface, i.e. eth0
659 | 'vid' | VLAN Id | yes | _(none)_ | VLAN Id
660 | 'macaddr' | MAC | no | _(none)_ | MAC of new interface
663 MAC address option is send upstream but not merged at time of writng.
664 === ATM Bridges (Ethernet over ATM AAL5)
666 *CAUTION*: The package 'br2684ctl' must be installed to use Ethernet over AAL5.
668 ATM bridges use a special config section called 'atm-bridge'.
669 Each 'atm-bridge' section maps the specified ATM curcuit an 'atm#' pseudo ethernet device which can
670 be used for example in conjunction with 'pppoe' to establish a DSL connection to the ISP.
672 A typical bridge section looks like this:
680 * Unit '0' will let 'br2684ctl' create a 'nas0' pseudo device
681 * VPI '8' and VCI '35' specifies the circuit to bridge. Those values are ISP dependant.
683 The 'atm-bridge' section allows the following options:
685 [cols="4*1,4",options="header"]
687 | Name | Type | Required | Default | Description
688 | 'unit' | number | yes | '0' | Specifies the br2684 interface number. If ommitted, '0' is assumed which would result in a 'nas0' pseudo interface.
689 | 'vci' | number | no | '35' | PPPoA VCI
690 | 'vpi' | number | no | '8' | PPPoA VPI
691 | 'atmdev' | number | no | '0' | Specifies the ATM adapter number starting with 0. Most systems only have one ATM device and do not need this option
692 | 'encaps' | string | no | 'llc' | PPPoA encapsulation mode: 'llc' (LLC) or 'vc' (VC)
693 | 'payload' | string | no | 'bridged' | PPPoA forwarding mode: 'routed' or 'bridged'
698 *CAUTION*: This currently only works on devices based on lantiq SoCs.
700 (V)DSL uses a special config section called 'dsl', which typically looks like this:
704 option firmware '/lib/firmware/vdsl.bin'
706 option xfer_mode 'atm'
709 The 'dsl' section allows the following options:
711 [cols="4*1,4",options="header"]
713 | Name | Type | Required | Default | Description
714 | 'annex' | string | yes | 'b' | Specifies the Annex setting (ISP/line dependent). Supported values on lantiq AMAZON and DANUBE devices: b, bdmt, b2, b2p, a, at1, alite, admt, a2, a2p, l, m, m2, m2p. Supported values on lantiq ARX100 "AR9" and VRX200 "VR9" devices: a, b, j
715 | 'firmware' | string | yes | '/lib/firmware/vdsl.bin' | The path to the modem's firmware image *CAUTION*: **Only supported by devices with lantiq SoC. See the xDSL firmware section below for more information **
716 | 'tone' | string | yes | 'bv' | The tone mode (ISP/line dependent). Supported values: a = A43, av = A43 + V43, b = B43, bv = B43 + V43 *CAUTION*: **Only supported by devices with ARX100 "AR9" and VRX200 "VR9" lantiq SoC. This configuration was removed in "Designated Driver" as the driver now auto-detects the correct value**
717 | 'xfer_mode' | string | yes | 'atm' | The transfer mode. Supported values are: atm = Asynchronous Transfer Mode (often used for ADSL connections), ptm = Packet Transfer Mode (often used for VDSL connections) *CAUTION*: **Only supported by devices with ARX100 "AR9" and VRX200 "VR9" lantiq SoC.**
720 === Lantiq xDSL firmware ===
722 Starting with r47631 and r47650 (lantiq: add dsl-vr9-firmware-xdsl / lantiq: add dsl-vrx200-firmware-xdsl-b: add Annex B version of VRX200 DSL firmware) there are redistributable versions of the xDSL firmware available as OpenWrt packages:
724 * dsl-vrx200-firmware-xdsl-a
725 * dsl-vrx200-firmware-xdsl-b
727 A list (incomplete) of other firmware versions, including those with vectoring support, can be found here: link:https:_xdarklight.github.io/lantiq-xdsl-firmware-info/[]
731 Basically create an 'interface' section per IP, but alias interfaces may NOT be of type bridge
733 * For non-bridged interfaces (physdev , that is physical interfaces) the 'ifname' is the <interface-of-network-for-same-phydev>
734 * For cases where the interface is bridged the 'ifname' is br-'base-interface', where 'base-interface' is the name of the primary IP's config section (e.g. for a the default lan interface config, the first alias would use ifname br-lan).
736 A minimal alias definition for a bridged interface might be (for a scenario without vlans):
739 option 'ifname' 'eth0'
740 option 'type' 'bridge'
741 option 'proto' 'static'
742 option 'ipaddr' '192.168.1.1'
743 option 'netmask' '255.255.255.0'
747 config interface lan2
748 option 'ifname' 'br-lan'
749 option 'proto' 'static'
750 option 'ipaddr' '10.0.0.1'
751 option 'netmask' '255.255.255.0'
754 or for a non-bridge interface
757 option 'ifname' 'eth0'
758 option 'proto' 'static'
759 option 'ipaddr' '192.168.1.1'
760 option 'netmask' '255.255.255.0'
764 config interface lan2
765 option 'ifname' 'eth0'
766 option 'proto' 'static'
767 option 'ipaddr' '10.0.0.1'
768 option 'netmask' '255.255.255.0'
771 To see a list of interfaces you can do 'ubus list network.interface.*' and to view the ip of a particular interface (the UCI name not the physical interface), do 'ifstatus <interface>' (e.g. 'ifstatus lan2').
773 === Aliases: notes ===
775 On openwrt 12.09, a lan interface that is first defined as dhcp interface
776 and then has aliases with static ip address could cause problems
777 in routing the lan traffic through the wan zone using the basic lan-wan forwarding provided by openwrt.
778 A solution is: having the basic interface with static address and aliases with dhcp protocol.
780 Another note is related to 'how to refer to the ifname of an interface'.
781 Normally the ifname is 'br-wan' if the interface 'wan' is bridged,
782 else is 'ifname <nic_device>' . Another way to avoid to list always the same
783 device is using 'ifname @interface'. In this way, even if the wan interface
784 is not a bridge, one can refer to the physical device used by the wan interface
789 Static _IPv4 routes_ can be defined on specific interfaces using 'route' sections. As for _aliases_, multiple sections can be attached to an interface.
791 A minimal example looks like this:
794 config 'route' 'name_your_route'
795 option 'interface' 'lan'
796 option 'target' '172.16.123.0'
797 option 'netmask' '255.255.255.0'
798 option 'gateway' '172.16.123.100'
801 * 'lan' is the _logical interface name_ of the parent interface
802 * '172.16.123.0' is the _network address_ of the route
803 * '255.255.255.0' specifies the _route netmask_
805 Legal options for _IPv4 routes_ are:
807 [cols="4*1,4",options="header"]
809 | Name | Type | Required | Default | Description
810 | 'interface' | string | yes | _(none)_ | Specifies the _logical interface name_ of the parent (or master) interface this route belongs to; must refer to one of the defined 'interface' sections
811 | 'target' | ip address | yes | _(none)_ | Network address
812 | 'netmask' | netmask | no | _(none)_ | Route netmask. If omitted, '255.255.255.255' is assumed which makes 'target' a _host address_
813 | 'gateway' | ip address | no | _(none)_ | Network gateway. If omitted, the 'gateway' from the parent interface is taken; if set to '0.0.0.0' no gateway will be specified for the route
814 | 'metric' | number | no | '0' | Specifies the _route metric_ to use
815 | 'mtu' | number | no | _interface MTU_ | Defines a specific MTU for this route
816 | 'table' | routing table | no | _(none)_ | Defines the table ID to use for the route. The ID can be either a numeric table index ranging from 0 to 65535 or a symbolic alias declared in /etc/iproute2/rt_tables. The special aliases local (255), main (254) and default (253) are recognized as well
817 | 'source' | ip address | no | _(none)_ | The preferred source address when sending to destinations covered by the target
818 | 'onlink' | boolean | no | '0' | When enabled gateway is on link even if the gateway does not match any interface prefix
819 | 'type' | string | no | 'unicast' | One of the types outlined in the Routing Types table below
822 To disable a route quickly, the option 'enabled' is not available. Just rewrite the 'route' config section as 'disabled_route' like:
824 config 'disabled_route' 'name_your_route'
827 and it will be recognized by the uci parser but not applied by the '/etc/init.d/network' script.
829 *CAUTION*: It seems that on openwrt 12.09 if a route is defined using a gateway in an address space where a gateway is already defined, it will be not added. Like the lan has the gateway 192.168.1.1 and we want to go to 1.2.3.4 over the gateway 192.168.1.5 within the interface lan, it will not be added. Could be added through 'ip route' commands tough.
832 _IPv6 routes_ can be specified as well by defining one or more 'route6' sections.
834 A minimal example looks like this:
838 option 'interface' 'lan'
839 option 'target' '2001:0DB8:100:F00:BA3::1/64'
840 option 'gateway' '2001:0DB8:99::1'
843 * 'lan' is the _logical interface name_ of the parent interface
844 * '2001:0DB8:100:F00:BA3::1/64' is the routed _IPv6 subnet_ in CIDR notation
845 * '2001:0DB8:99::1' specifies the _IPv6 gateway_ for this route
847 Legal options for _IPv6 routes_ are:
849 [cols="4*1,4",options="header"]
851 | Name | Type | Required | Default | Description
852 | 'interface' | string | yes | _(none)_ | Specifies the _logical interface name_ of the parent (or master) interface this route belongs to; must refer to one of the defined 'interface' sections
853 | 'target' | ipv6 address | yes | _(none)_ | IPv6 network address
854 | 'gateway' | ipv6 address | no | _(none)_ | IPv6 gateway. If omitted, the 'gateway' from the parent interface is taken
855 | 'metric' | number | no | '0' | Specifies the _route metric_ to use
856 | 'mtu' | number | no | _interface MTU_ | Defines a specific MTU for this route
857 | 'table' | routing table | no | _(none)_ | Defines the table ID to use for the route. The ID can be either a numeric table index ranging from 0 to 65535 or a symbolic alias declared in /etc/iproute2/rt_tables. The special aliases local (255), main (254) and default (253) are recognized as well
858 | 'source' | ip address | no | _(none)_ | The preferred source address when sending to destinations covered by the target
859 | 'onlink' | boolean | no | '0' | When enabled gateway is on link even if the gateway does not match any interface prefix
860 | 'type' | string | no | 'unicast' | One of the types outlined in the Routing Types table below
863 === Routing Types ===
865 [cols="1,4",options="header"]
868 | 'unicast' | the route entry describes real paths to the destinations covered by the route prefix.
869 | 'local' | the destinations are assigned to this host. The packets are looped back and delivered locally.
870 | 'broadcast' | the destinations are broadcast addresses. The packets are sent as link broadcasts.
871 | 'multicast' | a special type used for multicast routing. It is not present in normal routing tables.
872 | 'unreachable' | these destinations are unreachable. Packets are discarded and the ICMP message host unreachable is generated. The local senders get an EHOSTUNREACH error.
873 | 'prohibit' | these destinations are unreachable. Packets are discarded and the ICMP message communication administratively prohibited is generated. The local senders get an EACCES error.
874 | 'blackhole' | these destinations are unreachable. Packets are discarded silently. The local senders get an EINVAL error.
875 | 'anycast' | the destinations are anycast addresses assigned to this host. They are mainly equivalent to local with one difference: such addresses are invalid when used as the source address of any packet.
881 netifd supports _IP rule_ declarations which are required to implement policy routing. IPv4 rules can be defined by declaring one or more sections of type 'rule', IPv6 rules are denoted by sections of type 'rule6'. Both types share the same set of defined options.
883 A simple IPv4 rule may look like:
889 option dest '172.16.0.0/16'
893 * '0xFF' is a fwmark to be matched
894 * 'lan' is the incoming _logical interface name_
895 * '172.16.0.0/16' is the destination subnet to match
896 * '100' is the routing table ID to use for the matched traffic
898 Similary, an IPv6 rule looks like:
903 option dest 'fdca:1234::/64'
904 option action 'prohibit'
907 * 'vpn' is the incoming _logical interface name_
908 * 'fdca:1234::/64' is the destination subnet to match
909 * 'prohibit' is a routing action to take
911 The options below are defined for _IP rule_ ('rule' and 'rule6') sections:
913 [cols="4*1,4",options="header"]
915 | Name | Type | Required | Default | Description
916 | 'in' | string | no | _(none)_ | Specifies the incoming _logical interface name_
917 | 'out' | string | no | _(none)_ | Specifies the outgoing _logical interface name_
918 | 'src' | ip subnet | no | _(none)_ | Specifies the source subnet to match (CIDR notation)
919 | 'dest' | ip subnet | no | _(none)_ | Specifies the destination subnet to match (CIDR notation)
920 | 'tos' | integer | no | _(none)_ | Specifies the TOS value to match in IP headers
921 | 'mark' | mark/mask | no | _(none)_ | Specifies the _fwmark_ and optionally its mask to match, e.g. '0xFF' to match mark 255 or '0x0/0x1' to match any even mark value
922 | 'invert' | boolean | no | '0' | If set to '1', the meaning of the match options is inverted
923 | 'priority' | integer | no | _(incrementing)_ | Controls the order of the IP rules, by default the priority is auto-assigned so that they are processed in the same order they're declared in the config file
924 | 'lookup' | routing table | at least one of | _(none)_ | The rule target is a table lookup, the ID can be either a numeric table index ranging from '0' to '65535' or a symbolic alias declared in '/etc/iproute2/rt_tables'. The special aliases 'local' ('255'), 'main' ('254') and 'default' ('253') are recognized as well
925 | 'goto' | rule index | ::: | ::: | The rule target is a jump to another rule specified by its 'priority' value
926 | 'action' | string | ::: | ::: | The rule target is one of the routing actions outlined in the table below
929 === Routing Actions ===
931 [cols="1,4",options="header"]
933 | Action | Description
934 | 'prohibit' | When reaching the rule, respond with _ICMP prohibited_ messages and abort route lookup
935 | 'unreachable' | When reaching the rule, respond with _ICMP unreachable_ messages and abort route lookup
936 | 'blackhole' | When reaching the rule, drop packet and abort route lookup
937 | 'throw' | Stop lookup in the current routing table even if a default route exists
942 Below are a few examples for special, non-standard interface configurations.
944 === Bridge without IP
947 config 'interface' 'example'
948 option 'type' 'bridge'
949 option 'proto' 'none'
950 option 'ifname' 'eth0 eth1'
954 === DHCP without default gateway
958 config 'interface' 'example'
959 option 'proto' 'dhcp'
960 option 'ifname' 'eth0'
961 option 'defaultroute' '0'
967 config 'interface' 'example'
968 option 'proto' 'dhcp'
969 option 'ifname' 'eth0'
972 option 'interface' 'example'
973 option 'proto' 'static'
974 option 'ip6addr' '2001:0DB8:100:F00:BA3::1'
977 === Static IP configuration with multiple dnses
980 config 'interface' 'example'
981 option 'proto' 'static'
982 option 'ifname' 'eth0'
983 option 'ipaddr' '192.168.1.200'
984 option 'netmask' '255.255.255.0'
985 list 'dns' '192.168.1.1'
986 list 'dns' '192.168.10.1'
987 # the priority is: the last dns listed will be the first one
988 # to be chosen for the name resolution.
991 *CAUTION*: Openwrt will use the new dns configured only after a reboot or a '/etc/init.d/dnsmasq restart'.
993 === Static IP configuration and default gateway with non-zero metric
996 config 'interface' 'example'
997 option 'proto' 'static'
998 option 'ifname' 'eth0'
999 option 'ipaddr' '192.168.1.200'
1000 option 'netmask' '255.255.255.0'
1001 option 'dns' '192.168.1.1'
1004 option 'interface' 'example'
1005 option 'target' '0.0.0.0'
1006 option 'netmask' '0.0.0.0'
1007 option 'gateway' '192.168.1.1'
1008 option 'metric' '100'
1011 === PPtP-over-PPPoE internet connection
1014 config 'interface' 'wan'
1015 option 'proto' 'pppoe'
1016 option 'ifname' 'eth1'
1017 option 'username' 'user'
1018 option 'password' 'pass'
1019 option 'timeout' '10'
1021 config 'interface' 'vpn'
1022 option 'proto' 'pptp'
1023 option 'ifname' 'vpn'
1024 option 'username' 'vpnuser'
1025 option 'password' 'vpnpass'
1026 option 'server' 'vpn.example.org'
1029 *CAUTION*: Additionally the "wan" firewall zone must include both interfaces in '/etc/config/firewall':
1034 option 'network' 'wan vpn' # Important
1035 option 'input' 'REJECT'
1036 option 'forward' 'REJECT'
1037 option 'output' 'ACCEPT'
1041 === PPPoA ADSL internet connection
1044 config adsl-device 'adsl'
1048 config interface 'wan'
1049 option proto 'pppoa'
1050 option username 'jbloggs@plusdsl.net'
1051 option password 'XXXXXXXXX'
1057 === listing an interface created by software on the router, like vpn
1059 For example, a vpn interface is normally "tun0". To list it in the uci config files (and therefore in luci):
1061 config interface 'tun0'
1062 option ifname 'tun0'
1066 === Static IPv6-in-IPv4 tunnel
1068 The example below illustrates a static tunnel configuration in '/etc/config/network' file for the Hurricane Electric (he.net) broker.
1069 Option 'ipaddr' specifies the local IPv4 address, 'peeraddr' is the broker IPv4 address and 'ip6addr' the local IPv6 address routed via the tunnel.
1072 config 'interface' 'henet'
1073 option 'proto' '6in4'
1074 option 'ipaddr' '178.24.115.19'
1075 option 'peeraddr' '216.66.80.30'
1076 option 'ip6addr' '2001:0DB8:1f0a:1359::2/64'
1079 *CAUTION*: You should also add an address from your routed IPv6 network to the "lan" interface.
1081 *CAUTION*: To apply IPv6 firewall rules to the tunnel interface, add it to the "wan" zone in '/etc/config/firewall':
1086 option 'network' 'wan henet' # Important
1087 option 'input' 'REJECT'
1088 option 'forward' 'REJECT'
1089 option 'output' 'ACCEPT'
1093 *CAUTION*: If you define a new, dedicated zone just for the tunnel interface,
1094 make sure to set 'option conntrack 1' in order to force enabling connection tracking,
1095 otherwise unidirectional forwarding rules will not work.
1097 *CAUTION*: Don't forget to set up forwarding rules between the LAN and the tunnel if you want to route IPv6 traffic between them.
1099 === Setup behind one-to-one NAT ===
1101 If your public IP, e.g. '178.24.115.19', is not matching the IP address on your WAN interface, your ISP is probably using link:http://shorewall.net/NAT.htm#One-to-one[one-to-one NAT] (aka link:http://en.wikipedia.org/wiki/Network_address_translation#Methods_of_Port_translation[full-cone NAT]) and you won't be able to establish static IPv6-in-IPv4 tunnel. IP address of your WAN interface can be obtained with the following command:
1104 . /lib/functions/network.sh; network_get_ipaddr ip wan; echo $ip
1107 If this is your case you should fill the WAN IP address into 'ipaddr' option instead of your actual public IP that might have been provided to link:http://he.net/[Hurricane Electric] during tunnel creation. (You should always use your public IP while creating Hurricane Electric tunnel, so don't change it just because you are behind one-to-one NAT.) Or you may completely omit the optional 'ipaddr' option and let auto configuration to handle the correct IP. (*WARNING*: Auto configuration is vague. Is 'uci' handling this case?) That would be preferred solution if your WAN IP is dynamic (i.e. obtained via DHCP) or you are not sure. Example of '/etc/config/network' entry:
1110 config 'interface' 'henet'
1111 option 'proto' '6in4'
1112 option 'peeraddr' '216.66.80.30'
1113 option 'ip6addr' '2001:0DB8:1f0a:1359::2/64'
1116 === Dynamic IPv6-in-IPv4 tunnel (HE.net only)
1118 The example below illustrates a dynamic tunnel configuration for the Hurricane Electric (he.net) broker with enabled IP update.
1119 The local IPv4 address is automatically determined and tunnelid, username and password are provided for IP update.
1122 config 'interface' 'henet'
1123 option 'proto' '6in4'
1124 option 'peeraddr' '216.66.80.30'
1125 option 'ip6addr' '2001:0DB8:1f0a:1359::2/64'
1126 option 'tunnelid' '12345'
1127 option 'username' 'myusername'
1128 option 'password' '098f6bcd4621d373cade4e832627b4f6'
1131 === L2TPv3 Pseudowire bridged to LAN
1133 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'.
1136 config 'interface' 'lan'
1137 option 'proto' 'l2tp'
1138 option 'type' 'bridge'
1139 option 'ifname' 'eth0'
1140 option 'ipaddr' '192.168.1.1'
1141 option 'netmask' '255.255.255.0'
1142 option 'localaddr' '178.24.154.19'
1143 option 'peeraddr' '89.44.33.61'
1144 option 'encap' 'udp'
1145 option 'sport' '4000'
1146 option 'dport' '5410'
1149 === Relay between LAN and Wireless Station
1151 This example sets up a 'relayd' pseudo bridge between a wireless client network and LAN, so that it works similarly to the Broadcom Bridged Client mode.
1153 Wireless configuration (excerpt):
1157 option 'device' 'radio0'
1159 option 'ssid' 'Some Wireless Network'
1160 option 'encryption' 'psk2'
1161 option 'key' '12345678'
1162 option 'network' 'wwan'
1165 Network configuration (excerpt):
1167 *CAUTION*: Note that the LAN subnet must be different from the one used by wireless network's DHCP.
1170 config 'interface' 'lan'
1171 option 'ifname' 'eth0.1'
1172 option 'proto' 'static'
1173 option 'ipaddr' '192.168.1.1'
1174 option 'netmask' '255.255.255.0'
1176 config 'interface' 'wwan'
1177 option 'proto' 'dhcp'
1179 config 'interface' 'stabridge'
1180 option 'proto' 'relay'
1181 option 'network' 'lan wwan'
1184 In contrast to true bridging, traffic forwarded in this manner is affected by firewall rules, therefore 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:
1189 option 'network' 'lan wwan' # Important
1190 option 'input' 'ACCEPT'
1191 option 'forward' 'ACCEPT' # Important
1192 option 'output' 'ACCEPT'
1195 === Static addressing of a GRE tunnel
1197 Create a GRE tunnel with static address 10.42.0.253/30, adding it to an existing firewall zone called 'tunnels':
1200 config interface mytunnel
1203 option peeraddr 198.51.100.42
1205 config interface mytunnel_addr
1207 option ifname @mytunnel
1208 option ipaddr 10.42.0.253
1209 option netmask 255.255.255.252
1210 # Fixes IPv6 multicast (long-standing bug in kernel).
1211 # Useful if you run Babel or OSPFv3.
1212 option ip6addr 'fe80::42/64'
1215 == Network management
1217 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.
1219 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.
1221 == Determining Linux interface names
1223 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 as illustrated in the example below which opens port 22 on the interface.
1226 WANIF=$(uci -P/var/state get network.wan.ifname)
1227 iptables -I INPUT -i $WANIF -p tcp --dport 22 -j ACCEPT
1230 The uci state vars are deprecated and not used anymore for network related information link:https:_forum.openwrt.org/viewtopic.php?pid=203787#p203787[Quoting jow in the forum].
1231 Use /lib/functions/network.sh:
1234 source /lib/functions/network.sh
1236 if network_get_ipaddr addr "wan"; then
1241 == Multiple IP addresses
1243 Assigning multiple ip addresses to the same interface:
1245 config interface foo
1247 list ipaddr 10.8.0.1/24
1248 list ipaddr 10.9.0.1/24
1249 list ip6addr fdca:abcd::1/64
1250 list ip6addr fdca:cdef::1/64
1253 Specifying multiple interfaces sharing the same device:
1256 config interface foo
1258 option ipaddr 10.8.0.1
1259 option netmask 255.255.255.0
1260 option ip6addr fdca:abcd::1/64
1262 config interface foo2
1264 option ipaddr 10.9.0.1
1265 option netmask 255.255.255.0
1266 option ip6addr fdca:cdef::1/64