4 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_.
6 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.
8 Feel free to inform yourself about link:https://www.lede-project.org/docs/procd.html[netifd] (Network Interface Daemon).
12 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.
16 The 'globals' section contains interface-independent options affecting the network configuration in general.
18 [cols="4*1,4",options="header"]
20 | Name | Type | Required | Default | Description
21 | 'ula_prefix' | IPv6-prefix | no | _(none)_ | IPv6 ULA-Prefix for this device
26 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.
28 There are currently two different configuration formats in use, one for the legacy '/proc/switch/' API and one for the newer swconfig-based switch configuration.
32 This variant is actually only found on Broadcom devices like the WRT54GL.
34 A typical configuration for it looks like this:
37 config 'switch' 'eth0'
38 option 'vlan0' '0 1 2 3 5*'
42 The 'eth0' identifier specifies the switch the section is belonging to.
43 VLANs are defined by 'vlan#' options with '#' being the VLAN number.
47 The newer swconfig framework is intended to replace the legacy switch configuration.
49 Configuration for swconfig have a slightly different structure with one extra section per VLAN.
50 The example below shows a typical configuration:
53 config 'switch' 'eth0'
55 option 'enable_vlan' '1'
57 config 'switch_vlan' 'eth0_1'
58 option 'device' 'eth0'
60 option 'ports' '0 1 2 3 5t'
62 config 'switch_vlan' 'eth0_2'
63 option 'device' 'eth0'
68 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.
72 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.
74 A minimal interface declaration consists of the following lines:
77 config 'interface' 'wan'
79 option 'ifname' 'eth0.1'
82 * 'wan' is a unique _logical interface name_
83 * 'dhcp' specifies the _interface protocol_, DHCP in this example
84 * 'eth0.1' is the _physical interface_ associated with this section
86 *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.
88 The _interface protocol_ may be one of the following:
90 [cols="1,4,2",options="header"]
92 | Protocol | Description | Program
93 | 'static' | Static configuration with fixed address and netmask | 'ip'/'ifconfig'
94 | 'dhcp' | Address and netmask are assigned by DHCP | 'udhcpc' (Busybox)
95 | 'dhcpv6' | Address and netmask are assigned by DHCPv6 | 'odhcpc6c'
96 | 'ppp' | PPP protocol - dialup modem connections | 'pppd'
97 | 'pppoe' | PPP over Ethernet - DSL broadband connection | 'pppd' + 'plugin rp-pppoe.so'
98 | 'pppoa' | PPP over ATM - DSL connection using a builtin modem | 'pppd' + plugin ...
99 | '3g' | CDMA, UMTS or GPRS connection using an AT-style 3G modem | 'comgt'
100 | 'qmi' | USB modems using QMI protocol | 'uqmi'
101 | 'ncm' | USB modems using NCM protocol | 'comgt-ncm' + ?
102 | 'wwan' | USB modems with protocol autodetection | 'wwan'
103 | 'hnet' | Self-managing home network (HNCP) | 'hnet-full'
104 | 'pptp' | Connection via PPtP VPN | ?
105 | '6in4' | IPv6-in-IPv4 tunnel for use with Tunnel Brokers like HE.net | ?
106 | 'aiccu' | Anything-in-anything tunnel | 'aiccu'
107 | '6to4' | Stateless IPv6 over IPv4 transport | ?
108 | '6rd' | IPv6 rapid deployment | '6rd'
109 | 'dslite' | Dual-Stack Lite | 'ds-lite'
110 | 'l2tp' | PPP over L2TP Pseudowire Tunnel | 'xl2tpd'
111 | 'relay' | relayd pseudo-bridge | 'relayd'
112 | 'gre', 'gretap' | GRE over IPv4 | 'gre' + 'kmod-gre'
113 | 'grev6', 'grev6tap' | GRE over IPv6 | 'gre' + 'kmod-gre6'
114 | 'vti' | VTI over IPv4 | 'vti' + 'kmod-ip_vti'
115 | 'vtiv6' | VTI over IPv6 | 'vti' + 'kmod-ip6_vti'
116 | 'none' | Unspecified protocol, therefore all the other interface settings will be ignored (like disabling the configuration) | -
119 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.
121 === Options valid for all protocol types ===
123 [cols="4*1,4",options="header"]
125 | Name | Type | Required | Default | Description
126 | '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'_
127 | 'type' | string | no | _(none)_ | If set to "bridge", a bridge containing the given _ifnames_ is created
128 | 'stp' | boolean | no | '0' | Only valid for type "bridge", enables the Spanning Tree Protocol
129 | 'bridge_empty' | boolean | no | '0' | Only valid for type "bridge", enables creating empty bridges
130 | 'igmp_snooping' | boolean | no | '1' | Only valid for type "bridge", sets the multicast_snooping kernel setting for a bridge
131 | 'macaddr' | mac address | no | _(none)_ | Override MAC address of this interface
132 | 'mtu' | number | no | _(none)_ | Override the default MTU on this interface
133 | 'auto' | boolean | no | '0' for proto 'none', else '1' | Specifies whether to bring up interface on boot
134 | 'ipv6' | boolean | no | '1' | Specifies whether to enable (1) or disable (0) IPv6 on this interface
135 | '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
136 | 'enabled' | boolean | no | '1' | enable or disable the interface section
137 | '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
138 | '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
141 === Protocol "static" ===
143 [cols="4*1,4",options="header"]
145 | Name | Type | Required | Default | Description
146 | 'ipaddr' | ip address | yes, if no 'ip6addr' is set. | _(none)_ | IP address.
147 | 'netmask' | netmask | yes, if no 'ip6addr' is set | _(none)_ | Netmask
148 | 'gateway' | ip address | no | _(none)_ | Default gateway
149 | 'broadcast' | ip address | no | _(none)_ | Broadcast address (autogenerated if not set)
150 | 'ip6addr' | ipv6 address | yes, if no 'ipaddr' is set | _(none)_ | Assign given IPv6 address to this interface (CIDR notation)
151 | '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.
152 | 'ip6gw' | ipv6 address | no | _(none)_ | Assign given IPv6 default gateway to this interface
153 | 'ip6assign' | prefix length | no | _(none)_ | Delegate a prefix of given length to this interface
154 | 'ip6hint' | prefix hint (hex) | no | _(none)_ | Hint the subprefix-ID that should be delegated as hexadecimal number
155 | 'ip6prefix' | ipv6 prefix | no | _(none)_ | IPv6 prefix routed here for use on other interfaces
156 | 'ip6class' | list of strings | no | _(none)_ | Define the IPv6 prefix-classes this interface will accept
157 | 'dns' | list of ip addresses | no | _(none)_ | DNS server(s)
158 | 'dns_search' | list of domain names | no | _(none)_ | Search list for host-name lookup
159 | 'metric' | integer | no | '0' | Specifies the default route metric to use
162 === Protocol "dhcp" ===
164 [cols="4*1,4",options="header"]
166 | Name | Type | Required | Default | Description
167 | 'broadcast' | boolean | no | '0' | Enable the broadcast flag in DHCP requests, required for certain ISPs, e.g. Charter with DOCSIS 3
168 | 'ipaddr' | IP address | no | _(none)_ | IP address to request from the DHCP server
169 | 'hostname' | string | no | _(none)_ | Hostname to include in DHCP requests
170 | 'clientid' | string | no | _system default_ | Override client identifier in DHCP requests
171 | 'vendorid' | string | no | _system default_ | Override the vendor class in DHCP requests
172 | 'dns' | list of ip addresses | no | _(none)_ | Supplement DHCP-assigned DNS server(s), or use only these if peerdns is 0
173 | 'peerdns' | boolean | no | '1' | Use DHCP-provided DNS server(s)
174 | 'defaultroute' | boolean | no | '1' | Whether to create a default route via the received gateway
175 | 'customroutes' | string | no | _(none)_ | Space-separated list of additional routes to insert via the received gateway
176 | 'metric' | integer | no | '0' | Specifies the route metric to use for both default route and custom routes
177 | 'reqopts' | string | no | _(none)_ | Space-separated list of additional DHCP options to request from the server
178 | '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'.
179 | 'zone' | firewall zone | no | _(none)_ | Firewall zone to which this interface should be added
180 | 'iface6rd' | logical interface | no | _(none)_ | Logical interface template for auto-configuration of 6rd
181 | 'mtu6rd' | integer | no | _system default_ | MTU of the 6rd interface
182 | 'zone6rd' | firewall zone | no | _system default_ | Firewall zone to which the 6rd interface should be added
185 **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.
187 === Protocol "dhcpv6" ===
189 [cols="4*1,4",options="header"]
191 | Name | Type | Required | Default | Description
192 | 'reqaddress' | [try,force,none] | no | try | Behaviour for requesting addresses
193 | '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
194 | 'clientid' | hexstring | no | _system default_ | Override client identifier in DHCP requests
195 | 'ifaceid' | ipv6 addr | no | _link-local identifier_ | Override the interface identifier for adresses received via RA
196 | 'dns' | list of ip addresses | no | _(none)_ | Supplement DHCP-assigned DNS server(s), or use only these if peerdns is 0
197 | 'peerdns' | boolean | no | '1' | Use DHCP-provided DNS server(s)
198 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route via the received gateway
199 | 'reqopts' | list of numbers | no | _(none)_ | Specifies a list of additional DHCP options to request
200 | 'noslaaconly' | boolean | no | '0' | Don't allow configuration via SLAAC (RAs) only (implied by reqprefix != no)
201 | 'norelease' | boolean | no | '0' | Don't send a RELEASE when the interface is brought down
202 | 'ip6prefix' | ipv6 prefix | no | _(none)_ | Use an (additional) user-provided IPv6 prefix for distribution to clients
203 | 'iface_dslite' | logical interface | no | _(none)_ | Logical interface template for auto-configuration of DS-Lite
206 **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.
208 === Protocol "ppp" (PPP over Modem) ===
210 *CAUTION*: The package 'ppp' must be installed to use PPP.
212 [cols="4*1,4",options="header"]
214 | Name | Type | Required | Default | Description
215 | 'device' | file path | yes | _(none)_ | Modem device node
216 | 'username' | string | no(?) | _(none)_ | Username for PAP/CHAP authentication
217 | 'password' | string | no(?) | _(none)_ | Password for PAP/CHAP authentication
218 | 'connect' | file path | no | _(none)_ | Path to custom PPP connect script
219 | 'disconnect' | file path | no | _(none)_ | Path to custom PPP disconnect script
220 | 'keepalive' | number | no | _(none)_ | Number of unanswered echo requests before considering the peer dead. The interval between echo requests is 5 seconds.
221 | 'demand' | number | no | _(none)_ | Number of seconds to wait before closing the connection due to inactivity
222 | 'defaultroute' | boolean | no | '1' | Replace existing default route on PPP connect
223 | 'peerdns' | boolean | no | '1' | Use peer-assigned DNS server(s)
224 | 'dns' | list of ip addresses | no | _(none)_ | Override peer-assigned DNS server(s)
225 | 'ipv6' | boolean | no | '0' | Enable IPv6 on the PPP link
226 | 'pppd_options' | string | no | _(none)_ | Additional command line arguments to pass to the pppd daemon
229 === Protocol "pppoe" (PPP over Ethernet) ===
231 *CAUTION*: The packages 'ppp', 'kmod-pppoe' and 'ppp-mod-pppoe' must be installed to use PPPoE.
235 opkg install ppp kmod-pppoe ppp-mod-pppoe
238 [cols="4*1,4",options="header"]
240 | Name | Type | Required | Default | Description
241 | 'username' | string | no(?) | _(none)_ | Username for PAP/CHAP authentication
242 | 'password' | string | no(?) | _(none)_ | Password for PAP/CHAP authentication
243 | 'ac' | string | no | _(none)_ | Specifies the Access Concentrator to connect to. If unset, 'pppd' uses the first discovered one
244 | 'service' | string | no | _(none)_ | Specifies the Service Name to connect to, If unset, 'pppd' uses the first discovered one
245 | 'connect' | file path | no | _(none)_ | Path to custom PPP connect script
246 | 'disconnect' | file path | no | _(none)_ | Path to custom PPP disconnect script
247 | 'keepalive' | number | no | _(none)_ | Number of connection failures before reconnect
248 | 'demand' | number | no | _(none)_ | Number of seconds to wait before closing the connection due to inactivity
249 | 'defaultroute' | boolean | no | '1' | Replace existing default route on PPP connect
250 | 'peerdns' | boolean | no | '1' | Use peer-assigned DNS server(s)
251 | 'dns' | list of ip addresses | no | _(none)_ | Override peer-assigned DNS server(s)
252 | 'ipv6' | boolean | no | '0' | Enable IPv6 on the PPP link
253 | 'pppd_options' | string | no | _(none)_ | Additional command line arguments to pass to the pppd daemon, e.g. **debug**
256 === Protocol "pppoa" (PPP over ATM AAL5) ===
258 *CAUTION*: The package 'ppp-mod-pppoa' must be installed to use PPPoA.
260 [cols="4*1,4",options="header"]
262 | Name | Type | Required | Default | Description
263 | 'vci' | number | no | '35' | PPPoA VCI
264 | 'vpi' | number | no | '8' | PPPoA VPI
265 | '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
266 | 'encaps' | string | no | 'llc' | PPPoA encapsulation mode: 'llc' (LLC) or 'vc' (VC)
267 | 'username' | string | no(?) | _(none)_ | Username for PAP/CHAP authentication
268 | 'password' | string | no(?) | _(none)_ | Password for PAP/CHAP authentication
269 | 'connect' | file path | no | _(none)_ | Path to custom PPP connect script
270 | 'disconnect' | file path | no | _(none)_ | Path to custom PPP disconnect script
271 | 'keepalive' | number | no | _(none)_ | Number of connection failures before reconnect
272 | 'demand' | number | no | _(none)_ | Number of seconds to wait before closing the connection due to inactivity
273 | 'defaultroute' | boolean | no | '1' | Replace existing default route on PPP connect
274 | 'peerdns' | boolean | no | '1' | Use peer-assigned DNS server(s)
275 | 'dns' | list of ip addresses | no | _(none)_ | Override peer-assigned DNS server(s)
276 | 'ipv6' | boolean | no | '0' | Enable IPv6 on the PPP link
277 | 'pppd_options' | string | no | _(none)_ | Additional command line arguments to pass to the pppd daemon
281 === Protocol "3g" (PPP over EV-DO, CDMA, UMTS or GPRS) ===
283 *CAUTION*: The package 'comgt' must be installed to use 3G.
286 [cols="4*1,4",options="header"]
288 | Name | Type | Required | Default | Description
289 | 'device' | file path | yes | _(none)_ | Modem device node
290 | 'service' | string | yes | 'umts' | 3G service type: 'cdma'/'evdo', 'umts'/'umts_only'/'gprs_only' (...._only options limited to Novatel & Option cards and dongles)
291 | 'apn' | string | yes | _(none)_ | Used APN
292 | 'pincode' | number | no | _(none)_ | PIN code to unlock SIM card
293 | 'dialnumber' | string | no | %%*99***1#%% | Modem dial string e.g. *99#
294 | 'maxwait' | number | no | '20' | Number of seconds to wait for modem to become ready
295 | 'username' | string | no(?) | _(none)_ | Username for PAP/CHAP authentication
296 | 'password' | string | no(?) | _(none)_ | Password for PAP/CHAP authentication
297 | 'keepalive' | number | no | _(none)_ | Number of connection failures before reconnect
298 | 'demand' | number | no | _(none)_ | Number of seconds to wait before closing the connection due to inactivity
299 | 'defaultroute' | boolean | no | '1' | Replace existing default route on PPP connect
300 | 'peerdns' | boolean | no | '1' | Use peer-assigned DNS server(s)
301 | 'dns' | list of ip addresses | no | _(none)_ | Override peer-assigned DNS server(s)
302 | 'ipv6' | boolean | no | '0' | Enable IPv6 on the PPP link
306 === Protocol "qmi" (USB modems using QMI protocol) ===
308 *CAUTION*: The package 'uqmi' must be installed to use QMI.
310 [cols="4*1,4",options="header"]
312 | Name | Type | Required | Default | Description
313 | 'device' | file path | yes | _(none)_ | QMI device node, typically /dev/cdc-wdm0
314 | 'apn' | string | yes | _(none)_ | Used APN
315 | 'pincode' | number | no | _(none)_ | PIN code to unlock SIM card
316 | 'username' | string | no | _(none)_ | Username for PAP/CHAP authentication
317 | 'password' | string | no | _(none)_ | Password for PAP/CHAP authentication
318 | 'auth' | string | no | _(none)_ | Authentication type: pap, chap, both, none
319 | 'modes' | string | no | _(modem default)_ | Allowed network modes, comma separated list of: all, lte, umts, gsm, cdma, td-scdma
320 | 'delay' | number | no | 0 | Seconds to wait before trying to interact with the modem (some ZTE modems require up to 30 s.)
323 === Protocol "ncm" (USB modems using NCM protocol) ===
325 *CAUTION*: The package 'comgt-ncm' + modem specific driver must be installed to use NCM.
327 [cols="4*1,4",options="header"]
329 | Name | Type | Required | Default | Description
330 | 'device' | file path | yes | _(none)_ | NCM device node, typically /dev/cdc-wdm0 or /dev/ttyUSB#
331 | 'apn' | string | yes | _(none)_ | Used APN
332 | 'pincode' | number | no | _(none)_ | PIN code to unlock SIM card
333 | 'username' | string | no | _(none)_ | Username for PAP/CHAP authentication
334 | 'password' | string | no | _(none)_ | Password for PAP/CHAP authentication
335 | 'auth' | string | no | _(none)_ | Authentication type: pap, chap, both, none
336 | 'mode' | string | no | _(modem default)_ | Used network mode, not every device support every mode: preferlte, preferumts, lte, umts, gsm, auto
337 | 'pdptype' | string | no | 'IPV4V6' | Used IP-stack mode, 'IP' (for IPv4), 'IPV6' (for IPv6) or 'IPV4V6' (for dual-stack) (Designated Driver #46844 and later)
338 | 'delay' | number | no | 0 | Seconds to wait before trying to interact with the modem (some modems require up to 30 s.)
341 === Protocol "wwan" (USB modems autodetecting the above 3G/4G protocols) ===
343 *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.
345 [cols="4*1,4",options="header"]
347 | Name | Type | Required | Default | Description
348 | 'apn' | string | yes | _(none)_ | Used APN
349 | 'auth' | string | no | _(none)_ | Authentication type: pap, chap, both, none
350 | 'username' | string | no | _(none)_ | Username for PAP/CHAP authentication
351 | 'password' | string | no | _(none)_ | Password for PAP/CHAP authentication
352 | 'pincode' | number | no | _(none)_ | PIN code to unlock SIM card
353 | 'modes' | string | no | _(modem default)_ | Allowed network modes, comma separated list of: all, lte, umts, gsm, cdma, td-scdma
354 | 'delay' | number | no | 0 | Seconds to wait before trying to interact with the modem (some ZTE modems require up to 30 s.)
357 === Protocol "hnet" (Self-managing home network (HNCP)) ===
359 *CAUTION*: The package 'hnet-full' must be installed to use hnet.
360 *CAUTION*: See link:http://tools.ietf.org/html/draft-ietf-homenet-hncp[here] for details.
362 [cols="4*1,4",options="header"]
364 | Name | Type | Required | Default | Description
365 | 'mode' | string | no | auto | Interface mode. One of external, guest, adhoc or hybrid.
366 | 'ip6assign' | integer | no | 64 | IPv6-prefix size to assign to this interface if internal.
367 | 'ip4assign' | integer | no | 24 | IPv4-prefix size to assign to this interface if internal.
368 | 'dnsname' | string | no | <device-name> | DNS-Label to assign to interface.
371 === Protocol "pptp" (Point-to-Point Tunneling Protocol) ===
373 *CAUTION*: The package '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).
375 [cols="4*1,4",options="header"]
377 | Name | Type | Required | Default | Description
378 | 'server' | ip address | yes | _(none)_ | Remote PPtP server
379 | 'username' | string | no(?) | _(none)_ | Username for PAP/CHAP authentication
380 | 'password' | string | no(?) | _(none)_ | Password for PAP/CHAP authentication
381 | 'keepalive' | integer | no | ? | Number of attempts to reconnect
382 | 'defaultroute' | boolean | no | '1' | Whether to create a default route over the tunnel
383 | 'peerdns' | boolean | no | '1' |Use PPTP-provided DNS server(s)
384 | 'delegate' | boolean | no | ? |Use builtin IPv6-management
385 | 'iface' | string | no(?) | 'pptp-<vpn>' | Name of the physical interface. Defaults to 'pptp-<vpn>' no matter what you use
388 === Protocol "6in4" (IPv6-in-IPv4 Tunnel) ===
390 *CAUTION*: The package '6in4' must be installed to use this protocol.
392 [cols="4*1,4",options="header"]
394 | Name | Type | Required | Default | Description
395 | 'ipaddr' | IPv4 address | no | Current WAN IPv4 address | Local IPv4 endpoint address
396 | 'peeraddr' | IPv4 address | yes | _(none)_ | Remote IPv4 endpoint address
397 | 'ip6addr' | IPv6 address (CIDR) | yes | _(none)_ | Local IPv6 address delegated to the tunnel endpoint
398 | 'ip6prefix' | IPv6 prefix | no | _(none)_ | Routed IPv6 prefix for downstream interfaces
399 | 'sourcerouting' | boolean | no | '1' | Whether to route only packets from delegated prefixes
400 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route over the tunnel
401 | 'ttl' | integer | no | '64' | TTL used for the tunnel interface
402 | '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.
403 | 'mtu' | integer | no | '1280' | MTU used for the tunnel interface
404 | 'tunnelid' | integer | no | _(none)_ | HE.net global tunnel ID (used for endpoint update)
405 | '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)
406 | 'password' | string | no | _(none)_ | HE.net password (used for endpoint update)
407 | 'updatekey' | string | no | _(none)_ | HE.net updatekey, overrides password (used for endpoint update)
408 | 'metric' | integer | no | '0' | Specifies the default route metric to use
411 **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'.
413 **Note:** although ip6prefix isn't required, sourcerouting, enabled by default, will prevent forwarding of packets unless ip6prefix is specified.
415 === Protocol "aiccu" (Automatic IPv6 Connectivity Client Utility) ===
417 *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.
419 [cols="4*1,4",options="header"]
421 | Name | Type | Required | Default | Description
422 | 'username' | string | yes | _(none)_ | Server username
423 | 'password' | string | yes | _(none)_ | Server password
424 | 'protocol' | string | no | _(none)_ | Tunnel setup protocol to use ('tic', 'tsp', 'l2tp')
425 | 'server' | string | no | 'tic.sixxs.net' | Tunnel setup server to use
426 | 'ip6addr' | IPv6 address (CIDR) | no | _(none)_ | Local IPv6 address delegated to the tunnel endpoint (not necessary)
427 | 'ntpsynctimeout' | integer | no | '90' | Wait for NTP sync that many seconds
428 | 'tunnelid' | integer | no | _(none)_ | TIC server tunnel ID
429 | 'ip6prefix' | IPv6 prefix | no | _(none)_ | Routed IPv6 prefix for downstream interfaces
430 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route over the tunnel
431 | 'sourcerouting' | boolean | no | '1' | Whether to route only packets from delegated prefixes
432 | 'tunnelid' | integer | no | _(none)_ | TIC server tunnel ID
433 | 'requiretls' | boolean | no | '0' | Require TLS connection to TIC server
434 | 'nat' | boolean | no | '1' | Notify the user that a NAT-kind network is detected
435 | 'heartbeat' | boolean | no | '1' | Make heartbeats
436 | 'verbose' | boolean | no | '0' | Verbose logging to system log
439 **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'.
441 === Protocol "6to4" (IPv6-in-IPv4 Tunnel) ===
443 *CAUTION*: The package '6to4' must be installed to use this protocol.
445 [cols="4*1,4",options="header"]
447 | Name | Type | Required | Default | Description
448 | 'ipaddr' | IPv4 address | no | Current WAN IPv4 address | Local IPv4 endpoint address
449 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route over the tunnel
450 | 'ttl' | integer | no | '64' | TTL used for the tunnel interface
451 | 'tos' | string | no | _(none)_ | Type Of Service : either "inherit" (the outer header inherits the value of the inner header) or an hexadecimal value
452 | 'mtu' | integer | no | '1280' | MTU used for the tunnel interface
453 | 'metric' | integer | no | '0' | Specifies the default route metric to use
454 | '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.
455 | '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'.
456 | 'adv_valid_lifetime' | integer | no | '300' | (deprecated) Overrides the advertised valid prefix lifetime, in seconds
457 | 'adv_preferred_lifetime' | integer | no | '120' | (deprecated) Overrides the advertised preferred prefix lifetime, in seconds
460 **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'
462 **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)
464 === Protocol "6rd" (IPv6 rapid deployment) ===
466 *CAUTION*: The package '6rd' must be installed to use this protocol.
468 *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.
470 [cols="4*1,4",options="header"]
472 | Name | Type | Required | Default | Description
473 | 'peeraddr' | IPv4 address | yes | no | 6rd - Gateway
474 | 'ipaddr' | IPv4 address | no | Current WAN IPv4 address | Local IPv4 endpoint address
475 | 'ip6prefix' | IPv6 prefix (without length) | yes | no | 6rd-IPv6 Prefix
476 | 'ip6prefixlen' | IPv6 prefix length | yes | no | 6rd-IPv6 Prefix length
477 | 'ip4prefixlen' | IPv6 prefix length | no | 0 | IPv4 common prefix
478 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route over the tunnel
479 | 'ttl' | integer | no | '64' | TTL used for the tunnel interface
480 | 'tos' | string | no | _(none)_ | Type Of Service : either "inherit" (the outer header inherits the value of the inner header) or an hexadecimal value
481 | 'mtu' | integer | no | '1280' | MTU used for the tunnel interface
484 **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'.
486 **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).
489 === Protocol "dslite" (Dual-Stack Lite) ===
491 *CAUTION*: The package 'ds-lite' must be installed to use this protocol.
493 [cols="4*1,4",options="header"]
495 | Name | Type | Required | Default | Description
496 | 'peeraddr' | IPv6 address | yes | no | DS-Lite AFTR address
497 | 'ip6addr' | IPv6 address | no | Current WAN IPv6 address | Local IPv6 endpoint address
498 | 'tunlink' | Logical Interface | no | Current WAN interface | Tunnel base interface
499 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route over the tunnel
500 | 'ttl' | integer | no | '64' | TTL used for the tunnel interface
501 | 'mtu' | integer | no | '1280' | MTU used for the tunnel interface
504 *CAUTION*: ds-lite operation requires that IPv4 NAT is disabled. You should adjust your settings in /etc/config/firewall accordingly.
506 **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'.
509 === Protocol "l2tp" (PPP over L2TP Pseudowire Tunnel) ===
511 *CAUTION*: The package 'xl2tpd' must be installed to use this protocol.
513 Most options are similar to protocol "ppp".
515 [cols="4*1,4",options="header"]
517 | Name | Type | Required | Default | Description
518 | '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
519 | 'username' | string | no | _(none)_ | Username for PAP/CHAP authentication
520 | 'password' | string | yes if 'username' is provided | _(none)_ | Password for PAP/CHAP authentication
521 | 'ipv6' | bool | no | 0 | Enable IPv6 on the PPP link (IPv6CP)
522 | 'mtu' | int | no | 'pppd' default | Maximum Transmit/Receive Unit, in bytes
523 | 'keepalive' | string | no | _(none)_ | Number of unanswered echo requests before considering the peer dead. The interval between echo requests is 5 seconds.
524 | '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
525 | 'pppd_options' | string | no | _(none)_ | Additional options to pass to 'pppd'
528 The name of the physical interface will be "l2tp-<logical interface name>".
530 === Protocol "relay" (Relayd Pseudo Bridge) ===
532 *CAUTION*: The package 'relayd' must be installed to use this protocol.
534 [cols="4*1,4",options="header"]
536 | Name | Type | Required | Default | Description
537 | 'network' | list of _logical interface names_ | yes | _(none)_ | Specifies the networks between which traffic is relayed
538 | 'gateway' | IPv4 address | no | _(network default)_ | Override the gateway address sent to clients within DHCP responses
539 | 'expiry' | integer | no | '30' | Host expiry timeout in seconds
540 | 'retry' | integer | no | '5' | Number of ARP ping retries before a host is considered dead
541 | 'table' | integer | no | '16800' | Table ID for automatically added routes
542 | 'forward_bcast' | boolean | no | '1' | Enables forwarding of broadcast traffic, '0' disables it
543 | 'forward_dhcp' | boolean | no | '1' | Enables forwarding of DHCP requests and responses, '0' disables it
547 === Common options for GRE protocols ===
549 *CAUTION*: The package 'gre' must be installed to use GRE. Additionally, you need 'kmod-gre' and/or 'kmod-gre6'.
551 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".
553 All four protocols accept the following common options:
555 [cols="4*1,4",options="header"]
557 | Name | Type | Required | Default | Description
558 | 'mtu' | integer | no | 1280 | MTU
559 | 'ttl' | integer | no | 64 | TTL of the encapsulating packets
560 | 'tunlink' | logical interface name | no | _(none)_ | Bind the tunnel to this interface ('dev' option of "ip tunnel")
561 | 'zone' | zone name | no | "wan" | Firewall zone to which the interface will be added
562 | '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
563 | 'ikey' | integer | no | 0 | key for incoming packets
564 | 'okey' | integer | no | 0 | key for outgoing packets
565 | 'icsum' | boolean | no | false | require incoming checksum
566 | 'ocsum' | boolean | no | false | compute outgoing checksum
567 | 'iseqno' | boolean | no | false | require incoming packets serialisation
568 | 'oseqno' | boolean | no | false | perform outgoing packets serialisation
571 === Protocol "gre" (GRE tunnel over IPv4) ===
573 The following options are supported, in addition to all common options above:
575 [cols="4*1,4",options="header"]
577 | Name | Type | Required | Default | Description
578 | 'ipaddr' | IPv4 address | no | WAN IP | Local endpoint
579 | 'peeraddr' | IPv4 address | yes | _(none)_ | Remote endpoint
580 | 'df' | boolean | no | true | Set "Don't Fragment" flag on encapsulating packets
583 === Protocol "gretap" (Ethernet GRE tunnel over IPv4) ===
585 The following options are supported, in addition to all common options above:
587 [cols="4*1,4",options="header"]
589 | Name | Type | Required | Default | Description
590 | 'ipaddr' | IPv4 address | no | WAN IP | Local endpoint
591 | 'peeraddr' | IPv4 address | yes | _(none)_ | Remote endpoint
592 | 'df' | boolean | no | true | Set "Don't Fragment" flag on encapsulating packets
593 | 'network' | logical interface name | no | _(none)_ | Logical network to which the tunnel will be added (bridged)
596 === Protocol "grev6" (GRE tunnel over IPv6) ===
598 The following options are supported, in addition to all common options above:
600 [cols="4*1,4",options="header"]
602 | Name | Type | Required | Default | Description
603 | 'ip6addr' | IPv6 address | no | WAN IP | Local endpoint
604 | 'peer6addr' | IPv6 address | yes | _(none)_ | Remote endpoint
605 | '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
608 === Protocol "grev6tap" (Ethernet GRE tunnel over IPv6) ===
610 The following options are supported, in addition to all common options above:
612 [cols="4*1,4",options="header"]
614 | Name | Type | Required | Default | Description
615 | 'ip6addr' | IPv6 address | no | WAN IP | Local endpoint
616 | 'peer6addr' | IPv6 address | yes | _(none)_ | Remote endpoint
617 | '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
618 | 'network' | logical interface name | no | _(none)_ | Logical network to which the tunnel will be added (bridged)
623 === Protocol "vti" (VTI tunnel over IPv4) ===
625 VTI Tunnels are IPsec policies with a fwmark set. The traffic is redirected to the matching VTI interface.
627 [cols="4*1,4",options="header"]
629 | Name | Type | Required | Default | Description
630 | 'ipaddr' | IPv4 address | no | WAN IP | Local endpoint
631 | 'peeraddr' | IPv4 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
639 === Protocol "vtiv6" (VTI tunnel over IPv6) ===
641 The following options are supported, in addition to all common options above:
643 [cols="4*1,4",options="header"]
645 | Name | Type | Required | Default | Description
646 | 'ip6addr' | IPv6 address | no | WAN IP | Local endpoint
647 | 'peer6addr' | IPv6 address | yes | _(none)_ | Remote endpoint
648 | 'mtu' | integer | no | 1280 | MTU
649 | 'tunlink' | logical interface name | no | _(none)_ | Bind the tunnel to this interface ('dev' option of "ip tunnel")
650 | 'zone' | zone name | no | "wan" | Firewall zone to which the interface will be added
651 | 'ikey' | integer | no | 0 | key/fwmark for incoming packets
652 | 'okey' | integer | no | 0 | key/fwmark for outgoing packets
656 A minimal device declaration consists of the following lines:
659 config device 'eth0.106'
661 option name 'eth0.106'
665 === VLAN Interfaces ===
666 VLAN Interfaces may be configured also. If not, they are created on the fly by netifd. Defining VLANs gives more options.
667 The following options are supported:
669 [cols="4*1,4",options="header"]
671 | Name | Type | Required | Default | Description
672 | 'type' | VLAN Type | no | 802.1q | VLAN type, possible values: 8021q or 8021ad
673 | 'name' | Name | yes | _(none)_ | Name of device, i.e. eth0.5 or vlan5
674 | 'ifname' | Parent interface | yes | _(none)_ | Name of parent/base interface, i.e. eth0
675 | 'vid' | VLAN Id | yes | _(none)_ | VLAN Id
676 | 'macaddr' | MAC | no | _(none)_ | MAC of new interface
679 MAC address option is send upstream but not merged at time of writng.
680 === ATM Bridges (Ethernet over ATM AAL5)
682 *CAUTION*: The package 'br2684ctl' must be installed to use Ethernet over AAL5.
684 ATM bridges use a special config section called 'atm-bridge'.
685 Each 'atm-bridge' section maps the specified ATM curcuit an 'atm#' pseudo ethernet device which can
686 be used for example in conjunction with 'pppoe' to establish a DSL connection to the ISP.
688 A typical bridge section looks like this:
696 * Unit '0' will let 'br2684ctl' create a 'nas0' pseudo device
697 * VPI '8' and VCI '35' specifies the circuit to bridge. Those values are ISP dependant.
699 The 'atm-bridge' section allows the following options:
701 [cols="4*1,4",options="header"]
703 | Name | Type | Required | Default | Description
704 | 'unit' | number | yes | '0' | Specifies the br2684 interface number. If ommitted, '0' is assumed which would result in a 'nas0' pseudo interface.
705 | 'vci' | number | no | '35' | PPPoA VCI
706 | 'vpi' | number | no | '8' | PPPoA VPI
707 | '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
708 | 'encaps' | string | no | 'llc' | PPPoA encapsulation mode: 'llc' (LLC) or 'vc' (VC)
709 | 'payload' | string | no | 'bridged' | PPPoA forwarding mode: 'routed' or 'bridged'
714 *CAUTION*: This currently only works on devices based on lantiq SoCs.
716 (V)DSL uses a special config section called 'dsl', which typically looks like this:
720 option firmware '/lib/firmware/vdsl.bin'
722 option xfer_mode 'atm'
725 The 'dsl' section allows the following options:
727 [cols="4*1,4",options="header"]
729 | Name | Type | Required | Default | Description
730 | '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
731 | '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 **
732 | '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**
733 | '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.**
736 === Lantiq xDSL firmware ===
738 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:
740 * dsl-vrx200-firmware-xdsl-a
741 * dsl-vrx200-firmware-xdsl-b
743 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/[]
747 Basically create an 'interface' section per IP, but alias interfaces may NOT be of type bridge
749 * For non-bridged interfaces (physdev , that is physical interfaces) the 'ifname' is the <interface-of-network-for-same-phydev>
750 * 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).
752 A minimal alias definition for a bridged interface might be (for a scenario without vlans):
755 option 'ifname' 'eth0'
756 option 'type' 'bridge'
757 option 'proto' 'static'
758 option 'ipaddr' '192.168.1.1'
759 option 'netmask' '255.255.255.0'
763 config interface lan2
764 option 'ifname' 'br-lan'
765 option 'proto' 'static'
766 option 'ipaddr' '10.0.0.1'
767 option 'netmask' '255.255.255.0'
770 or for a non-bridge interface
773 option 'ifname' 'eth0'
774 option 'proto' 'static'
775 option 'ipaddr' '192.168.1.1'
776 option 'netmask' '255.255.255.0'
780 config interface lan2
781 option 'ifname' 'eth0'
782 option 'proto' 'static'
783 option 'ipaddr' '10.0.0.1'
784 option 'netmask' '255.255.255.0'
787 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').
789 === Aliases: notes ===
791 On openwrt 12.09, a lan interface that is first defined as dhcp interface
792 and then has aliases with static ip address could cause problems
793 in routing the lan traffic through the wan zone using the basic lan-wan forwarding provided by openwrt.
794 A solution is: having the basic interface with static address and aliases with dhcp protocol.
796 Another note is related to 'how to refer to the ifname of an interface'.
797 Normally the ifname is 'br-wan' if the interface 'wan' is bridged,
798 else is 'ifname <nic_device>' . Another way to avoid to list always the same
799 device is using 'ifname @interface'. In this way, even if the wan interface
800 is not a bridge, one can refer to the physical device used by the wan interface
805 Static _IPv4 routes_ can be defined on specific interfaces using 'route' sections. As for _aliases_, multiple sections can be attached to an interface.
807 A minimal example looks like this:
810 config 'route' 'name_your_route'
811 option 'interface' 'lan'
812 option 'target' '172.16.123.0'
813 option 'netmask' '255.255.255.0'
814 option 'gateway' '172.16.123.100'
817 * 'lan' is the _logical interface name_ of the parent interface
818 * '172.16.123.0' is the _network address_ of the route
819 * '255.255.255.0' specifies the _route netmask_
821 Legal options for _IPv4 routes_ are:
823 [cols="4*1,4",options="header"]
825 | Name | Type | Required | Default | Description
826 | '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
827 | 'target' | ip address | yes | _(none)_ | Network address
828 | 'netmask' | netmask | no | _(none)_ | Route netmask. If omitted, '255.255.255.255' is assumed which makes 'target' a _host address_
829 | '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
830 | 'metric' | number | no | '0' | Specifies the _route metric_ to use
831 | 'mtu' | number | no | _interface MTU_ | Defines a specific MTU for this route
832 | '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
833 | 'source' | ip address | no | _(none)_ | The preferred source address when sending to destinations covered by the target
834 | 'onlink' | boolean | no | '0' | When enabled gateway is on link even if the gateway does not match any interface prefix
835 | 'type' | string | no | 'unicast' | One of the types outlined in the Routing Types table below
838 To disable a route quickly, the option 'enabled' is not available. Just rewrite the 'route' config section as 'disabled_route' like:
840 config 'disabled_route' 'name_your_route'
843 and it will be recognized by the uci parser but not applied by the '/etc/init.d/network' script.
845 *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.
848 _IPv6 routes_ can be specified as well by defining one or more 'route6' sections.
850 A minimal example looks like this:
854 option 'interface' 'lan'
855 option 'target' '2001:0DB8:100:F00:BA3::1/64'
856 option 'gateway' '2001:0DB8:99::1'
859 * 'lan' is the _logical interface name_ of the parent interface
860 * '2001:0DB8:100:F00:BA3::1/64' is the routed _IPv6 subnet_ in CIDR notation
861 * '2001:0DB8:99::1' specifies the _IPv6 gateway_ for this route
863 Legal options for _IPv6 routes_ are:
865 [cols="4*1,4",options="header"]
867 | Name | Type | Required | Default | Description
868 | '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
869 | 'target' | ipv6 address | yes | _(none)_ | IPv6 network address
870 | 'gateway' | ipv6 address | no | _(none)_ | IPv6 gateway. If omitted, the 'gateway' from the parent interface is taken
871 | 'metric' | number | no | '0' | Specifies the _route metric_ to use
872 | 'mtu' | number | no | _interface MTU_ | Defines a specific MTU for this route
873 | '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
874 | 'source' | ip address | no | _(none)_ | The preferred source address when sending to destinations covered by the target
875 | 'onlink' | boolean | no | '0' | When enabled gateway is on link even if the gateway does not match any interface prefix
876 | 'type' | string | no | 'unicast' | One of the types outlined in the Routing Types table below
879 === Routing Types ===
881 [cols="1,4",options="header"]
884 | 'unicast' | the route entry describes real paths to the destinations covered by the route prefix.
885 | 'local' | the destinations are assigned to this host. The packets are looped back and delivered locally.
886 | 'broadcast' | the destinations are broadcast addresses. The packets are sent as link broadcasts.
887 | 'multicast' | a special type used for multicast routing. It is not present in normal routing tables.
888 | 'unreachable' | these destinations are unreachable. Packets are discarded and the ICMP message host unreachable is generated. The local senders get an EHOSTUNREACH error.
889 | 'prohibit' | these destinations are unreachable. Packets are discarded and the ICMP message communication administratively prohibited is generated. The local senders get an EACCES error.
890 | 'blackhole' | these destinations are unreachable. Packets are discarded silently. The local senders get an EINVAL error.
891 | '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.
897 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.
899 A simple IPv4 rule may look like:
905 option dest '172.16.0.0/16'
909 * '0xFF' is a fwmark to be matched
910 * 'lan' is the incoming _logical interface name_
911 * '172.16.0.0/16' is the destination subnet to match
912 * '100' is the routing table ID to use for the matched traffic
914 Similary, an IPv6 rule looks like:
919 option dest 'fdca:1234::/64'
920 option action 'prohibit'
923 * 'vpn' is the incoming _logical interface name_
924 * 'fdca:1234::/64' is the destination subnet to match
925 * 'prohibit' is a routing action to take
927 The options below are defined for _IP rule_ ('rule' and 'rule6') sections:
929 [cols="4*1,4",options="header"]
931 | Name | Type | Required | Default | Description
932 | 'in' | string | no | _(none)_ | Specifies the incoming _logical interface name_
933 | 'out' | string | no | _(none)_ | Specifies the outgoing _logical interface name_
934 | 'src' | ip subnet | no | _(none)_ | Specifies the source subnet to match (CIDR notation)
935 | 'dest' | ip subnet | no | _(none)_ | Specifies the destination subnet to match (CIDR notation)
936 | 'tos' | integer | no | _(none)_ | Specifies the TOS value to match in IP headers
937 | '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
938 | 'invert' | boolean | no | '0' | If set to '1', the meaning of the match options is inverted
939 | '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
940 | '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
941 | 'goto' | rule index | ::: | ::: | The rule target is a jump to another rule specified by its 'priority' value
942 | 'action' | string | ::: | ::: | The rule target is one of the routing actions outlined in the table below
945 === Routing Actions ===
947 [cols="1,4",options="header"]
949 | Action | Description
950 | 'prohibit' | When reaching the rule, respond with _ICMP prohibited_ messages and abort route lookup
951 | 'unreachable' | When reaching the rule, respond with _ICMP unreachable_ messages and abort route lookup
952 | 'blackhole' | When reaching the rule, drop packet and abort route lookup
953 | 'throw' | Stop lookup in the current routing table even if a default route exists
958 Below are a few examples for special, non-standard interface configurations.
960 === Bridge without IP
963 config 'interface' 'example'
964 option 'type' 'bridge'
965 option 'proto' 'none'
966 option 'ifname' 'eth0 eth1'
970 === DHCP without default gateway
974 config 'interface' 'example'
975 option 'proto' 'dhcp'
976 option 'ifname' 'eth0'
977 option 'defaultroute' '0'
983 config 'interface' 'example'
984 option 'proto' 'dhcp'
985 option 'ifname' 'eth0'
988 option 'interface' 'example'
989 option 'proto' 'static'
990 option 'ip6addr' '2001:0DB8:100:F00:BA3::1'
993 === Static IP configuration with multiple dnses
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 list 'dns' '192.168.1.1'
1002 list 'dns' '192.168.10.1'
1003 # the priority is: the last dns listed will be the first one
1004 # to be chosen for the name resolution.
1007 *CAUTION*: Openwrt will use the new dns configured only after a reboot or a '/etc/init.d/dnsmasq restart'.
1009 === Static IP configuration and default gateway with non-zero metric
1012 config 'interface' 'example'
1013 option 'proto' 'static'
1014 option 'ifname' 'eth0'
1015 option 'ipaddr' '192.168.1.200'
1016 option 'netmask' '255.255.255.0'
1017 option 'dns' '192.168.1.1'
1020 option 'interface' 'example'
1021 option 'target' '0.0.0.0'
1022 option 'netmask' '0.0.0.0'
1023 option 'gateway' '192.168.1.1'
1024 option 'metric' '100'
1027 === PPtP-over-PPPoE internet connection
1030 config 'interface' 'wan'
1031 option 'proto' 'pppoe'
1032 option 'ifname' 'eth1'
1033 option 'username' 'user'
1034 option 'password' 'pass'
1035 option 'timeout' '10'
1037 config 'interface' 'vpn'
1038 option 'proto' 'pptp'
1039 option 'ifname' 'vpn'
1040 option 'username' 'vpnuser'
1041 option 'password' 'vpnpass'
1042 option 'server' 'vpn.example.org'
1045 *CAUTION*: Additionally the "wan" firewall zone must include both interfaces in '/etc/config/firewall':
1050 option 'network' 'wan vpn' # Important
1051 option 'input' 'REJECT'
1052 option 'forward' 'REJECT'
1053 option 'output' 'ACCEPT'
1057 === PPPoA ADSL internet connection
1060 config adsl-device 'adsl'
1064 config interface 'wan'
1065 option proto 'pppoa'
1066 option username 'jbloggs@plusdsl.net'
1067 option password 'XXXXXXXXX'
1073 === listing an interface created by software on the router, like vpn
1075 For example, a vpn interface is normally "tun0". To list it in the uci config files (and therefore in luci):
1077 config interface 'tun0'
1078 option ifname 'tun0'
1082 === Static IPv6-in-IPv4 tunnel
1084 The example below illustrates a static tunnel configuration in '/etc/config/network' file for the Hurricane Electric (he.net) broker.
1085 Option 'ipaddr' specifies the local IPv4 address, 'peeraddr' is the broker IPv4 address and 'ip6addr' the local IPv6 address routed via the tunnel.
1088 config 'interface' 'henet'
1089 option 'proto' '6in4'
1090 option 'ipaddr' '178.24.115.19'
1091 option 'peeraddr' '216.66.80.30'
1092 option 'ip6addr' '2001:0DB8:1f0a:1359::2/64'
1095 *CAUTION*: You should also add an address from your routed IPv6 network to the "lan" interface.
1097 *CAUTION*: To apply IPv6 firewall rules to the tunnel interface, add it to the "wan" zone in '/etc/config/firewall':
1102 option 'network' 'wan henet' # Important
1103 option 'input' 'REJECT'
1104 option 'forward' 'REJECT'
1105 option 'output' 'ACCEPT'
1109 *CAUTION*: If you define a new, dedicated zone just for the tunnel interface,
1110 make sure to set 'option conntrack 1' in order to force enabling connection tracking,
1111 otherwise unidirectional forwarding rules will not work.
1113 *CAUTION*: Don't forget to set up forwarding rules between the LAN and the tunnel if you want to route IPv6 traffic between them.
1115 === Setup behind one-to-one NAT ===
1117 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:
1120 . /lib/functions/network.sh; network_get_ipaddr ip wan; echo $ip
1123 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:
1126 config 'interface' 'henet'
1127 option 'proto' '6in4'
1128 option 'peeraddr' '216.66.80.30'
1129 option 'ip6addr' '2001:0DB8:1f0a:1359::2/64'
1132 === Dynamic IPv6-in-IPv4 tunnel (HE.net only)
1134 The example below illustrates a dynamic tunnel configuration for the Hurricane Electric (he.net) broker with enabled IP update.
1135 The local IPv4 address is automatically determined and tunnelid, username and password are provided for IP update.
1138 config 'interface' 'henet'
1139 option 'proto' '6in4'
1140 option 'peeraddr' '216.66.80.30'
1141 option 'ip6addr' '2001:0DB8:1f0a:1359::2/64'
1142 option 'tunnelid' '12345'
1143 option 'username' 'myusername'
1144 option 'password' '098f6bcd4621d373cade4e832627b4f6'
1147 === L2TPv3 Pseudowire bridged to LAN
1149 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'.
1152 config 'interface' 'lan'
1153 option 'proto' 'l2tp'
1154 option 'type' 'bridge'
1155 option 'ifname' 'eth0'
1156 option 'ipaddr' '192.168.1.1'
1157 option 'netmask' '255.255.255.0'
1158 option 'localaddr' '178.24.154.19'
1159 option 'peeraddr' '89.44.33.61'
1160 option 'encap' 'udp'
1161 option 'sport' '4000'
1162 option 'dport' '5410'
1165 === Relay between LAN and Wireless Station
1167 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.
1169 Wireless configuration (excerpt):
1173 option 'device' 'radio0'
1175 option 'ssid' 'Some Wireless Network'
1176 option 'encryption' 'psk2'
1177 option 'key' '12345678'
1178 option 'network' 'wwan'
1181 Network configuration (excerpt):
1183 *CAUTION*: Note that the LAN subnet must be different from the one used by wireless network's DHCP.
1186 config 'interface' 'lan'
1187 option 'ifname' 'eth0.1'
1188 option 'proto' 'static'
1189 option 'ipaddr' '192.168.1.1'
1190 option 'netmask' '255.255.255.0'
1192 config 'interface' 'wwan'
1193 option 'proto' 'dhcp'
1195 config 'interface' 'stabridge'
1196 option 'proto' 'relay'
1197 option 'network' 'lan wwan'
1200 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:
1205 option 'network' 'lan wwan' # Important
1206 option 'input' 'ACCEPT'
1207 option 'forward' 'ACCEPT' # Important
1208 option 'output' 'ACCEPT'
1211 === Static addressing of a GRE tunnel
1213 Create a GRE tunnel with static address 10.42.0.253/30, adding it to an existing firewall zone called 'tunnels':
1216 config interface mytunnel
1219 option peeraddr 198.51.100.42
1221 config interface mytunnel_addr
1223 option ifname @mytunnel
1224 option ipaddr 10.42.0.253
1225 option netmask 255.255.255.252
1226 # Fixes IPv6 multicast (long-standing bug in kernel).
1227 # Useful if you run Babel or OSPFv3.
1228 option ip6addr 'fe80::42/64'
1231 == Network management
1233 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.
1235 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.
1237 == Determining Linux interface names
1239 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.
1242 WANIF=$(uci -P/var/state get network.wan.ifname)
1243 iptables -I INPUT -i $WANIF -p tcp --dport 22 -j ACCEPT
1246 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].
1247 Use /lib/functions/network.sh:
1250 source /lib/functions/network.sh
1252 if network_get_ipaddr addr "wan"; then
1257 == Multiple IP addresses
1259 Assigning multiple ip addresses to the same interface:
1261 config interface foo
1263 list ipaddr 10.8.0.1/24
1264 list ipaddr 10.9.0.1/24
1265 list ip6addr fdca:abcd::1/64
1266 list ip6addr fdca:cdef::1/64
1269 Specifying multiple interfaces sharing the same device:
1272 config interface foo
1274 option ipaddr 10.8.0.1
1275 option netmask 255.255.255.0
1276 option ip6addr fdca:abcd::1/64
1278 config interface foo2
1280 option ipaddr 10.9.0.1
1281 option netmask 255.255.255.0
1282 option ip6addr fdca:cdef::1/64