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_. After editing and saving '/etc/config/network' you need to execute ----
5 /etc/init.d/network reload
6 ---- to stop and restart the network before any changes take effect. Rebooting the router is not necessary.
8 * https:_dev.openwrt.org/browser/branches/attitude_adjustment/package/base-files/files/etc/config/network
9 * https:_dev.openwrt.org/browser/trunk/package/base-files/files/etc/config/network
11 Feel free to inform yourself about [[doc/techref/netifd|netifd]] (Network Interface Daemon).
15 Below is an overview of the section types that may be defined in the network configuration.
16 A minimal network configuration for a router usually consists of at least two _interfaces_ ('lan' and 'wan') and a _switch_ section if applicable.
19 CAUTION: The globals section is available in Barrier Breaker and later releases.
21 The 'globals' section contains interface-independent options affecting the network configuration in general.
25 | Name | Type | Required | Default | Description
26 | 'ula_prefix' | IPv6-prefix | no | _(none)_ | IPv6 [[wp>Unique local address|ULA]]-Prefix for this device
31 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.
33 There are currently two different configuration formats in use, one for the legacy '/proc/switch/' API and one for the newer '[[doc/techref/swconfig|swconfig]]'-based switch configuration.
37 This variant is actually only found on Broadcom devices like the WRT54GL.
39 A typical configuration for it looks like this:
42 config 'switch' 'eth0'
43 option 'vlan0' '0 1 2 3 5*'
47 The 'eth0' identifier specifies the switch the section is belonging to.
48 VLANs are defined by 'vlan#' options with '#' being the VLAN number.
49 For further information refer to the [[doc:uci:network::switch|switch documentation]].
53 The newer '[[doc/techref/swconfig|swconfig]]'-framework is intended to replace the legacy switch configuration.
55 Configuration for swconfig have a slightly different structure with one extra section per VLAN.
56 The example below shows a typical configuration:
59 config 'switch' 'eth0'
61 option 'enable_vlan' '1'
63 config 'switch_vlan' 'eth0_1'
64 option 'device' 'eth0'
66 option 'ports' '0 1 2 3 5t'
68 config 'switch_vlan' 'eth0_2'
69 option 'device' 'eth0'
74 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.
75 The complete layout is explained in the [[doc:uci:network::switch|switch documentation]].
80 Sections of the type 'interface' declare logical networks serving as containers for IP address settings, [[doc:uci:network#aliases|aliases]], [[doc:uci:network#ipv4.routes|routes]], physical interface names and [[doc:uci:firewall#zones|firewall rules]] - they play a central role within the OpenWrt configuration concept.
82 A minimal interface declaration consists of the following lines:
85 config 'interface' 'wan'
87 option 'ifname' 'eth0.1'
90 * 'wan' is a unique _logical interface name_
91 * 'dhcp' specifies the _interface protocol_, DHCP in this example
92 * 'eth0.1' is the _physical interface_ associated with this section
94 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.
96 The _interface protocol_ may be one of the following:
100 | Protocol | Description | Program
101 | 'static' | Static configuration with fixed address and netmask | 'ip'/'ifconfig'
102 | 'dhcp' | Address and netmask are assigned by DHCP | 'udhcpc' (Busybox)
103 | 'dhcpv6' | Address and netmask are assigned by DHCPv6 | 'odhcpc6c'
104 | 'ppp' | PPP protocol - dialup modem connections | 'pppd'
105 | 'pppoe' | PPP over Ethernet - DSL broadband connection | 'pppd' + 'plugin rp-pppoe.so'
106 | 'pppoa' | PPP over ATM - DSL connection using a builtin modem | 'pppd' + plugin ...
107 | '3g' | CDMA, UMTS or GPRS connection using an AT-style 3G modem | 'comgt'
108 | 'qmi' | USB modems using QMI protocol | 'uqmi'
109 | 'ncm' | USB modems using NCM protocol | 'comgt-ncm' + ?
110 | 'wwan' | USB modems with protocol autodetection | 'wwan'
111 | 'hnet' | Self-managing home network (HNCP) | 'hnet-full'
112 | 'pptp' | Connection via PPtP VPN | ?
113 | '6in4' | IPv6-in-IPv4 tunnel for use with Tunnel Brokers like HE.net | ?
114 | 'aiccu' | Anything-in-anything tunnel | 'aiccu'
115 | '6to4' | Stateless IPv6 over IPv4 transport | ?
116 | '6rd' | IPv6 rapid deployment | '6rd'
117 | 'dslite' | Dual-Stack Lite | 'ds-lite'
118 | 'l2tp' | PPP over L2TP Pseudowire Tunnel | 'xl2tpd'
119 | 'relay' | relayd pseudo-bridge | 'relayd'
120 | 'gre', 'gretap' | GRE over IPv4 | 'gre' + 'kmod-gre'
121 | 'grev6', 'grev6tap' | GRE over IPv6 | 'gre' + 'kmod-gre6'
122 | 'vti' | VTI over IPv4 | 'vti' + 'kmod-ip_vti'
123 | 'vtiv6' | VTI over IPv6 | 'vti' + 'kmod-ip6_vti'
124 | 'none' | Unspecified protocol, therefore all the other interface settings will be ignored (like disabling the configuration) | -
127 Depending on the used _interface protocol_ several other options may be required for a complete interface declaration.
128 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.
130 CAUTION: In openwrt 12.09, if an interface section has no protocol defined (not even 'none' ), the other settings are completely ignored. The result is that, if the interface section is mentioning a physical network interface (i.e. eth0), this will be down even if a cable is connected (with proto 'none' the interface is up). (could be that more testing is needed)
132 === Options valid for all protocol types ===
136 | Name | Type | Required | Default | Description
137 | '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'_
138 | 'type' | string | no | _(none)_ | If set to "bridge", a bridge containing the given _ifnames_ is created Wlan interface names are not predictable, therfore you cannot reference them directly in the network config
139 | 'stp' | boolean | no | '0' | Only valid for type "bridge", enables the Spanning Tree Protocol
140 | 'bridge_empty' | boolean | no | '0' | Only valid for type "bridge", enables creating empty bridges
141 | 'igmp_snooping' | boolean | no | '1' | Only valid for type "bridge", sets the multicast_snooping kernel setting for a bridge
142 | 'macaddr' | mac address | no | _(none)_ | Override MAC address of this interface
143 | 'mtu' | number | no | _(none)_ | Override the default MTU on this interface
144 | 'auto' | boolean | no | '0' for proto 'none', else '1' | Specifies whether to bring up interface on boot
145 | 'ipv6' | boolean | no | '1' | Specifies whether to enable (1) or disable (0) IPv6 on this interface (Barrier Breaker and later only)
146 | 'accept_ra' | boolean | no | '1' for protocol 'dhcp', else '0' | **deprecated:** Specifies whether to accept IPv6 Router Advertisements on this interface (On Attitude Adjustment 12.09 and earlier versions)
147 | 'send_rs' | boolean | no | '1' for protocol 'static', else '0' | **deprecated:** Specifies whether to send Router Solicitations on this interface (On Attitude Adjustment 12.09 and earlier versions)
148 | '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
149 | 'enabled' | boolean | no | '1' | enable or disable the interface section
150 | '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
151 | '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
154 === Protocol "static" ===
158 | Name | Type | Required | Default | Description
159 | 'ipaddr' | ip address | yes, if no 'ip6addr' is set. | _(none)_ | IP address. [openwrt 12.09] It could be a list of ipaddr , that is: several ipaddresses will be assigned to the interface. If, instead of a list, several ipaddr are specified as options, only the last is applied.
160 | 'netmask' | netmask | yes, if no 'ip6addr' is set | _(none)_ | Netmask
161 | 'gateway' | ip address | no | _(none)_ | Default gateway
162 | 'broadcast' | ip address | no | _(none)_ | Broadcast address (autogenerated if not set)
163 | 'ip6addr' | ipv6 address | yes, if no 'ipaddr' is set | _(none)_ | Assign given IPv6 address to this interface (CIDR notation)
164 | '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.
165 | 'ip6gw' | ipv6 address | no | _(none)_ | Assign given IPv6 default gateway to this interface
166 | 'ip6assign' | prefix length | no | _(none)_ | Delegate a prefix of given length to this interface (Barrier Breaker and later only)
167 | 'ip6hint' | prefix hint (hex) | no | _(none)_ | Hint the subprefix-ID that should be delegated as hexadecimal number (Barrier Breaker and later only)
168 | 'ip6prefix' | ipv6 prefix | no | _(none)_ | IPv6 prefix routed here for use on other interfaces (Barrier Breaker and later only)
169 | 'ip6class' | list of strings | no | _(none)_ | Define the IPv6 prefix-classes this interface will accept
170 | 'dns' | list of ip addresses | no | _(none)_ | DNS server(s)
171 | 'dns_search' | list of domain names | no | _(none)_ | Search list for host-name lookup
172 | 'metric' | integer | no | '0' | Specifies the default route metric to use
175 === Protocol "dhcp" ===
179 | Name | Type | Required | Default | Description
180 | '[line-through]*gateway*' | [line-through]*string* | [line-through]*no* | [line-through]*_(none)_* | [line-through]*Suppresses DHCP-assigned default gateway if set to 0.0.0.0*
181 | 'broadcast' | boolean | no | '0' | Enable the broadcast flag in DHCP requests, required for certain ISPs, e.g. Charter with DOCSIS 3
182 | 'ipaddr' | IP address | no | _(none)_ | IP address to request from the DHCP server
183 | 'hostname' | string | no | _(none)_ | Hostname to include in DHCP requests
184 | 'clientid' | string | no | _system default_ | Override client identifier in DHCP requests
185 | 'vendorid' | string | no | _system default_ | Override the vendor class in DHCP requests
186 | 'dns' | list of ip addresses | no | _(none)_ | Supplement DHCP-assigned DNS server(s), or use only these if peerdns is 0
187 | 'peerdns' | boolean | no | '1' | Use DHCP-provided DNS server(s)
188 | 'defaultroute' | boolean | no | '1' | Whether to create a default route via the received gateway
189 | 'customroutes' | string | no | _(none)_ | Space-separated list of additional routes to insert via the received gateway
190 | 'metric' | integer | no | '0' | Specifies the route metric to use for both default route and custom routes
191 | 'reqopts' | string | no | _(none)_ | Space-separated list of additional DHCP options to request from the server
192 | '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'.
193 | 'zone' | firewall zone | no | _(none)_ | Firewall zone to which this interface should be added
194 | 'iface6rd' | logical interface | no | _(none)_ | Logical interface template for auto-configuration of 6rd
195 | 'mtu6rd' | integer | no | _system default_ | MTU of the 6rd interface
196 | 'zone6rd' | firewall zone | no | _system default_ | Firewall zone to which the 6rd interface should be added
199 **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.
201 CAUTION: These parameters are handled partially by netifd (in 'interface.c') and partially by a shell script in 'lib/netifd/proto/dhcp.sh'.
203 CAUTION: It seems that if an interface is configured as dhcp client, at least on OpenWrt 10.03, the default route received by dhcp
204 will be the only one listed and will remove other default route/metrics defined for other interfaces if those interfaces comes "before" the interface with dhcp in terms of "ifname" values. For example:
212 config interface wan2
218 The interface with dhcp comes after (because eth1 comes after eth0 in a lexicografical order)
219 and will overwrite the default routes set up by the interface "wan". While is not true the contrary.
228 config interface wan2
234 Both default routes set up by wan and wan2 will appear in the routing table.
236 === Protocol "dhcpv6" ===
238 CAUTION: The package 'odhcp6c' must be installed to use dhcpv6.
242 | Name | Type | Required | Default | Description
243 | 'reqaddress' | [try,force,none] | no | try | Behaviour for requesting addresses
244 | '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
245 | 'clientid' | hexstring | no | _system default_ | Override client identifier in DHCP requests
246 | 'ifaceid' | ipv6 addr | no | _link-local identifier_ | Override the interface identifier for adresses received via RA
247 | 'dns' | list of ip addresses | no | _(none)_ | Supplement DHCP-assigned DNS server(s), or use only these if peerdns is 0
248 | 'peerdns' | boolean | no | '1' | Use DHCP-provided DNS server(s)
249 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route via the received gateway
250 | 'reqopts' | list of numbers | no | _(none)_ | Specifies a list of additional DHCP options to request
251 | 'noslaaconly' | boolean | no | '0' | Don't allow configuration via SLAAC (RAs) only (implied by reqprefix != no)
252 | 'norelease' | boolean | no | '0' | Don't send a RELEASE when the interface is brought down
253 | 'ip6prefix' | ipv6 prefix | no | _(none)_ | Use an (additional) user-provided IPv6 prefix for distribution to clients
254 | 'iface_dslite' | logical interface | no | _(none)_ | Logical interface template for auto-configuration of DS-Lite
257 **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.
259 === Protocol "ppp" (PPP over Modem) ===
261 CAUTION: The package 'ppp' must be installed to use PPP.
265 | Name | Type | Required | Default | Description
266 | 'device' | file path | yes | _(none)_ | Modem device node
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 unanswered echo requests before considering the peer dead. The interval between echo requests is 5 seconds.
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
280 === Protocol "pppoe" (PPP over Ethernet) ===
282 CAUTION: The packages 'ppp', 'kmod-pppoe' and 'ppp-mod-pppoe' must be installed to use PPPoE.
286 opkg install ppp kmod-pppoe ppp-mod-pppoe
291 | Name | Type | Required | Default | Description
292 | 'username' | string | no(?) | _(none)_ | Username for PAP/CHAP authentication
293 | 'password' | string | no(?) | _(none)_ | Password for PAP/CHAP authentication
294 | 'ac' | string | no | _(none)_ | Specifies the Access Concentrator to connect to. If unset, 'pppd' uses the first discovered one
295 | 'service' | string | no | _(none)_ | Specifies the Service Name to connect to, If unset, 'pppd' uses the first discovered one
296 | 'connect' | file path | no | _(none)_ | Path to custom PPP connect script
297 | 'disconnect' | file path | no | _(none)_ | Path to custom PPP disconnect script
298 | 'keepalive' | number | no | _(none)_ | Number of connection failures before reconnect
299 | 'demand' | number | no | _(none)_ | Number of seconds to wait before closing the connection due to inactivity
300 | 'defaultroute' | boolean | no | '1' | Replace existing default route on PPP connect
301 | 'peerdns' | boolean | no | '1' | Use peer-assigned DNS server(s)
302 | 'dns' | list of ip addresses | no | _(none)_ | Override peer-assigned DNS server(s)
303 | 'ipv6' | boolean | no | '0' | Enable IPv6 on the PPP link
304 | 'pppd_options' | string | no | _(none)_ | Additional command line arguments to pass to the pppd daemon, e.g. **debug**
307 === Protocol "pppoa" (PPP over ATM AAL5) ===
309 CAUTION: The package 'ppp-mod-pppoa' must be installed to use PPPoA.
313 | Name | Type | Required | Default | Description
314 | 'vci' | number | no | '35' | PPPoA VCI
315 | 'vpi' | number | no | '8' | PPPoA VPI
316 | '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
317 | 'encaps' | string | no | 'llc' | PPPoA encapsulation mode: 'llc' (LLC) or 'vc' (VC)
318 | 'username' | string | no(?) | _(none)_ | Username for PAP/CHAP authentication
319 | 'password' | string | no(?) | _(none)_ | Password for PAP/CHAP authentication
320 | 'connect' | file path | no | _(none)_ | Path to custom PPP connect script
321 | 'disconnect' | file path | no | _(none)_ | Path to custom PPP disconnect script
322 | 'keepalive' | number | no | _(none)_ | Number of connection failures before reconnect
323 | 'demand' | number | no | _(none)_ | Number of seconds to wait before closing the connection due to inactivity
324 | 'defaultroute' | boolean | no | '1' | Replace existing default route on PPP connect
325 | 'peerdns' | boolean | no | '1' | Use peer-assigned DNS server(s)
326 | 'dns' | list of ip addresses | no | _(none)_ | Override peer-assigned DNS server(s)
327 | 'ipv6' | boolean | no | '0' | Enable IPv6 on the PPP link
328 | 'pppd_options' | string | no | _(none)_ | Additional command line arguments to pass to the pppd daemon
332 === Protocol "3g" (PPP over EV-DO, CDMA, UMTS or GPRS) ===
334 CAUTION: The package 'comgt' must be installed to use 3G. Check [[doc:recipes:3gdongle]] for further help with that.
339 | Name | Type | Required | Default | Description
340 | 'device' | file path | yes | _(none)_ | Modem device node
341 | 'service' | string | yes | 'umts' | 3G service type: 'cdma'/'evdo', 'umts'/'umts_only'/'gprs_only' (...._only options limited to Novatel & Option cards and dongles)
342 | 'apn' | string | yes | _(none)_ | Used APN
343 | 'pincode' | number | no | _(none)_ | PIN code to unlock SIM card
344 | 'dialnumber' | string | no | %%*99***1#%% | Modem dial string e.g. *99#
345 | 'maxwait' | number | no | '20' | Number of seconds to wait for modem to become ready
346 | 'username' | string | no(?) | _(none)_ | Username for PAP/CHAP authentication
347 | 'password' | string | no(?) | _(none)_ | Password for PAP/CHAP authentication
348 | 'keepalive' | number | no | _(none)_ | Number of connection failures before reconnect
349 | 'demand' | number | no | _(none)_ | Number of seconds to wait before closing the connection due to inactivity
350 | 'defaultroute' | boolean | no | '1' | Replace existing default route on PPP connect
351 | 'peerdns' | boolean | no | '1' | Use peer-assigned DNS server(s)
352 | 'dns' | list of ip addresses | no | _(none)_ | Override peer-assigned DNS server(s)
353 | 'ipv6' | boolean | no | '0' | Enable IPv6 on the PPP link
357 === Protocol "qmi" (USB modems using QMI protocol) ===
359 CAUTION: The package 'uqmi' must be installed to use QMI.
363 | Name | Type | Required | Default | Description
364 | 'device' | file path | yes | _(none)_ | QMI device node, typically /dev/cdc-wdm0
365 | 'apn' | string | yes | _(none)_ | Used APN
366 | 'pincode' | number | no | _(none)_ | PIN code to unlock SIM card
367 | 'username' | string | no | _(none)_ | Username for PAP/CHAP authentication
368 | 'password' | string | no | _(none)_ | Password for PAP/CHAP authentication
369 | 'auth' | string | no | _(none)_ | Authentication type: pap, chap, both, none
370 | 'modes' | string | no | _(modem default)_ | Allowed network modes, comma separated list of: all, lte, umts, gsm, cdma, td-scdma
371 | 'delay' | number | no | 0 | Seconds to wait before trying to interact with the modem (some ZTE modems require up to 30 s.)
374 === Protocol "ncm" (USB modems using NCM protocol) ===
376 CAUTION: The package 'comgt-ncm' + modem specific driver must be installed to use NCM.
380 | Name | Type | Required | Default | Description
381 | 'device' | file path | yes | _(none)_ | NCM device node, typically /dev/cdc-wdm0 or /dev/ttyUSB#
382 | 'apn' | string | yes | _(none)_ | Used APN
383 | 'pincode' | number | no | _(none)_ | PIN code to unlock SIM card
384 | 'username' | string | no | _(none)_ | Username for PAP/CHAP authentication
385 | 'password' | string | no | _(none)_ | Password for PAP/CHAP authentication
386 | 'auth' | string | no | _(none)_ | Authentication type: pap, chap, both, none
387 | 'mode' | string | no | _(modem default)_ | Used network mode, not every device support every mode: preferlte, preferumts, lte, umts, gsm, auto
388 | 'pdptype' | string | no | 'IPV4V6' | Used IP-stack mode, 'IP' (for IPv4), 'IPV6' (for IPv6) or 'IPV4V6' (for dual-stack) (Designated Driver #46844 and later)
389 | 'delay' | number | no | 0 | Seconds to wait before trying to interact with the modem (some modems require up to 30 s.)
392 === Protocol "wwan" (USB modems autodetecting above protocols) ===
394 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.
398 | Name | Type | Required | Default | Description
399 | 'apn' | string | yes | _(none)_ | Used APN
400 | 'auth' | string | no | _(none)_ | Authentication type: pap, chap, both, none
401 | 'username' | string | no | _(none)_ | Username for PAP/CHAP authentication
402 | 'password' | string | no | _(none)_ | Password for PAP/CHAP authentication
403 | 'pincode' | number | no | _(none)_ | PIN code to unlock SIM card
404 | 'modes' | string | no | _(modem default)_ | Allowed network modes, comma separated list of: all, lte, umts, gsm, cdma, td-scdma
405 | 'delay' | number | no | 0 | Seconds to wait before trying to interact with the modem (some ZTE modems require up to 30 s.)
408 === Protocol "hnet" (Self-managing home network (HNCP)) ===
410 CAUTION: The package 'hnet-full' must be installed to use hnet.
411 CAUTION: See http:_tools.ietf.org/html/draft-ietf-homenet-hncp for details.
415 | Name | Type | Required | Default | Description
416 | 'mode' | string | no | auto | Interface mode. One of external, guest, adhoc or hybrid.
417 | 'ip6assign' | integer | no | 64 | IPv6-prefix size to assign to this interface if internal.
418 | 'ip4assign' | integer | no | 24 | IPv4-prefix size to assign to this interface if internal.
419 | 'dnsname' | string | no | <device-name> | DNS-Label to assign to interface.
422 === Protocol "pptp" (Point-to-Point Tunneling Protocol) ===
424 CAUTION: The package 'pptp' must be installed to use PPtP. There is a separate Howto for this: [[doc:howto:vpn.client.pptp]]. You need to have another section to configure the "parent" device, and you might need to add "<vpn>" to your "wan" zone in the firewall (<vpn> being the "logical interface name" of this section).
428 | Name | Type | Required | Default | Description
429 | 'server' | ip address | yes | _(none)_ | Remote PPtP server
430 | 'username' | string | no(?) | _(none)_ | Username for PAP/CHAP authentication
431 | 'password' | string | no(?) | _(none)_ | Password for PAP/CHAP authentication
432 | 'buffering' | boolean | no | '1' | [line-through]*Enables buffering and reordering of packets, '0' disables it ('--nobuffer')* pptp buffering option removed in r32482
433 | 'keepalive' | integer | no | ? | Number of attempts to reconnect
434 | 'defaultroute' | boolean | no | '1' | Whether to create a default route over the tunnel
435 | 'peerdns' | boolean | no | '1' |Use PPTP-provided DNS server(s)
436 | 'delegate' | boolean | no | ? |Use builtin IPv6-management
437 | 'iface' | string | no(?) | 'pptp-<vpn>' | Name of the physical interface. Defaults to 'pptp-<vpn>' no matter what you use
440 === Protocol "6in4" (IPv6-in-IPv4 Tunnel) ===
442 CAUTION: The package '6in4' must be installed to use this protocol.
446 | Name | Type | Required | Default | Description
447 | 'ipaddr' | IPv4 address | no | Current WAN IPv4 address | Local IPv4 endpoint address
448 | 'peeraddr' | IPv4 address | yes | _(none)_ | Remote IPv4 endpoint address
449 | 'ip6addr' | IPv6 address (CIDR) | yes | _(none)_ | Local IPv6 address delegated to the tunnel endpoint
450 | 'ip6prefix' | IPv6 prefix | no | _(none)_ | Routed IPv6 prefix for downstream interfaces (Barrier Breaker and later only)
451 | 'sourcerouting' | boolean | no | '1' | Whether to route only packets from delegated prefixes (Barrier Breaker and later only)
452 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route over the tunnel
453 | 'ttl' | integer | no | '64' | TTL used for the tunnel interface
454 | '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. (Chaos Calmer and later only)
455 | 'mtu' | integer | no | '1280' | MTU used for the tunnel interface
456 | 'tunnelid' | integer | no | _(none)_ | HE.net global tunnel ID (used for endpoint update)
457 | '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)
458 | 'password' | string | no | _(none)_ | [line-through]*md5sum of* HE.net password (used for endpoint update)
459 | 'updatekey' | string | no | _(none)_ | HE.net updatekey, overrides password (used for endpoint update)
460 | 'metric' | integer | no | '0' | Specifies the default route metric to use
463 **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'.
465 **Note:** HE.net has introduced updatekey as default for new tunnels in February 2014. Support added to Openwrt trunk by r39646.
467 **Note:** as of r41358 **username**, **password** and **updatekey** are all plaintext entries.
469 **Note:** although ip6prefix isn't required, sourcerouting, enabled by default, will prevent forwarding of packets unless ip6prefix is specified.
471 === Protocol "aiccu" (Automatic IPv6 Connectivity Client Utility) ===
473 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.
475 CAUTION: This protocol is available for Barrier Breaker and newer versions only.
479 | Name | Type | Required | Default | Description
480 | 'username' | string | yes | _(none)_ | Server username
481 | 'password' | string | yes | _(none)_ | Server password
482 | 'protocol' | string | no | _(none)_ | Tunnel setup protocol to use ('tic', 'tsp', 'l2tp')
483 | 'server' | string | no | 'tic.sixxs.net' | Tunnel setup server to use
484 | 'ip6addr' | IPv6 address (CIDR) | no | _(none)_ | Local IPv6 address delegated to the tunnel endpoint (not necessary)
485 | 'ntpsynctimeout' | integer | no | '90' | Wait for NTP sync that many seconds
486 | 'tunnelid' | integer | no | _(none)_ | TIC server tunnel ID
487 | 'ip6prefix' | IPv6 prefix | no | _(none)_ | Routed IPv6 prefix for downstream interfaces
488 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route over the tunnel
489 | 'sourcerouting' | boolean | no | '1' | Whether to route only packets from delegated prefixes
490 | 'tunnelid' | integer | no | _(none)_ | TIC server tunnel ID
491 | 'requiretls' | boolean | no | '0' | Require TLS connection to TIC server
492 | 'nat' | boolean | no | '1' | Notify the user that a NAT-kind network is detected
493 | 'heartbeat' | boolean | no | '1' | Make heartbeats
494 | 'verbose' | boolean | no | '0' | Verbose logging to system log
497 **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'.
499 === Protocol "6to4" (IPv6-in-IPv4 Tunnel) ===
501 CAUTION: The package '6to4' must be installed to use this protocol.
505 | Name | Type | Required | Default | Description
506 | 'ipaddr' | IPv4 address | no | Current WAN IPv4 address | Local IPv4 endpoint address
507 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route over the tunnel
508 | 'ttl' | integer | no | '64' | TTL used for the tunnel interface
509 | 'tos' | string | no | _(none)_ | Type Of Service : either "inherit" (the outer header inherits the value of the inner header) or an hexadecimal value (Chaos Calmer and later only)
510 | 'mtu' | integer | no | '1280' | MTU used for the tunnel interface
511 | 'metric' | integer | no | '0' | Specifies the default route metric to use
512 | '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.
513 | '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'.
514 | 'adv_valid_lifetime' | integer | no | '300' | (deprecated) Overrides the advertised valid prefix lifetime, in seconds
515 | 'adv_preferred_lifetime' | integer | no | '120' | (deprecated) Overrides the advertised preferred prefix lifetime, in seconds (see also [[doc:uci:radvd#prefix|radvd prefix options]])
518 **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'
520 **Note:** If [[doc:uci:radvd|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)
522 === Protocol "6rd" (IPv6 rapid deployment) ===
524 CAUTION: The package '6rd' must be installed to use this protocol.
526 CAUTION: The needed tunnel values are usually obtained via the DHCPv4 request for the WAN interface. Try that [[doc/uci/network6#rd_tunnel_isp-provided_ipv6_transition|first]]. Below is only needed for hardcoding the tunnel.
530 | Name | Type | Required | Default | Description
531 | 'peeraddr' | IPv4 address | yes | no | 6rd - Gateway
532 | 'ipaddr' | IPv4 address | no | Current WAN IPv4 address | Local IPv4 endpoint address
533 | 'ip6prefix' | IPv6 prefix (without length) | yes | no | 6rd-IPv6 Prefix
534 | 'ip6prefixlen' | IPv6 prefix length | yes | no | 6rd-IPv6 Prefix length
535 | 'ip4prefixlen' | IPv6 prefix length | no | 0 | IPv4 common prefix
536 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route over the tunnel
537 | 'ttl' | integer | no | '64' | TTL used for the tunnel interface
538 | 'tos' | string | no | _(none)_ | Type Of Service : either "inherit" (the outer header inherits the value of the inner header) or an hexadecimal value (Chaos Calmer and later only)
539 | 'mtu' | integer | no | '1280' | MTU used for the tunnel interface
542 **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'.
544 **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).
547 === Protocol "dslite" (Dual-Stack Lite) ===
549 CAUTION: The package 'ds-lite' must be installed to use this protocol.
553 | Name | Type | Required | Default | Description
554 | 'peeraddr' | IPv6 address | yes | no | DS-Lite AFTR address
555 | 'ip6addr' | IPv6 address | no | Current WAN IPv6 address | Local IPv6 endpoint address
556 | 'tunlink' | Logical Interface | no | Current WAN interface | Tunnel base interface
557 | 'defaultroute' | boolean | no | '1' | Whether to create an IPv6 default route over the tunnel
558 | 'ttl' | integer | no | '64' | TTL used for the tunnel interface
559 | 'mtu' | integer | no | '1280' | MTU used for the tunnel interface
562 CAUTION: ds-lite operation requires that IPv4 NAT is disabled. You should adjust your settings in /etc/config/firewall accordingly.
564 **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'.
567 === Protocol "l2tp" (PPP over L2TP Pseudowire Tunnel) ===
569 CAUTION: The package 'xl2tpd' must be installed to use this protocol.
571 Most options are similar to protocol "ppp".
575 | Name | Type | Required | Default | Description
576 | '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
577 | 'username' | string | no | _(none)_ | Username for PAP/CHAP authentication
578 | 'password' | string | yes if 'username' is provided | _(none)_ | Password for PAP/CHAP authentication
579 | 'ipv6' | bool | no | 0 | Enable IPv6 on the PPP link (IPv6CP)
580 | 'mtu' | int | no | 'pppd' default | Maximum Transmit/Receive Unit, in bytes
581 | 'keepalive' | string | no | _(none)_ | Number of unanswered echo requests before considering the peer dead. The interval between echo requests is 5 seconds.
582 | '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
583 | 'pppd_options' | string | no | _(none)_ | Additional options to pass to 'pppd'
586 The name of the physical interface will be "l2tp-<logical interface name>".
588 === Protocol "relay" (Relayd Pseudo Bridge) ===
590 CAUTION: The package 'relayd' must be installed to use this protocol.
594 | Name | Type | Required | Default | Description
595 | 'network' | list of _logical interface names_ | yes | _(none)_ | Specifies the networks between which traffic is relayed
596 | 'gateway' | IPv4 address | no | _(network default)_ | Override the gateway address sent to clients within DHCP responses
597 | 'expiry' | integer | no | '30' | Host expiry timeout in seconds
598 | 'retry' | integer | no | '5' | Number of ARP ping retries before a host is considered dead
599 | 'table' | integer | no | '16800' | Table ID for automatically added routes
600 | 'forward_bcast' | boolean | no | '1' | Enables forwarding of broadcast traffic, '0' disables it
601 | 'forward_dhcp' | boolean | no | '1' | Enables forwarding of DHCP requests and responses, '0' disables it
605 === Common options for GRE protocols ===
607 CAUTION: The package 'gre' must be installed to use GRE. Additionally, you need 'kmod-gre' and/or 'kmod-gre6'.
609 GRE support has been introduced in Barrier Breaker. Four protocols are defined: "gre", "gretap", "grev6", and "grev6tap".
610 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".
612 All four protocols accept the following common options:
616 | Name | Type | Required | Default | Description
617 | 'mtu' | integer | no | 1280 | MTU
618 | 'ttl' | integer | no | 64 | TTL of the encapsulating packets
619 | 'tunlink' | logical interface name | no | _(none)_ | Bind the tunnel to this interface ('dev' option of "ip tunnel")
620 | 'zone' | zone name | no | "wan" | Firewall zone to which the interface will be added
621 | '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 (Chaos Calmer and later only) |
622 | 'ikey' | integer | no | 0 | key for incoming packets
623 | 'okey' | integer | no | 0 | key for outgoing packets
624 | 'icsum' | boolean | no | false | require incoming checksum
625 | 'ocsum' | boolean | no | false | compute outgoing checksum
626 | 'iseqno' | boolean | no | false | require incoming packets serialisation
627 | 'oseqno' | boolean | no | false | perform outgoing packets serialisation
630 === Protocol "gre" (GRE tunnel over IPv4) ===
632 The following options are supported, in addition to all common options above:
636 | Name | Type | Required | Default | Description
637 | 'ipaddr' | IPv4 address | no | WAN IP | Local endpoint
638 | 'peeraddr' | IPv4 address | yes | _(none)_ | Remote endpoint
639 | 'df' | boolean | no | true | Set "Don't Fragment" flag on encapsulating packets
642 === Protocol "gretap" (Ethernet GRE tunnel over IPv4) ===
644 The following options are supported, in addition to all common options above:
648 | Name | Type | Required | Default | Description
649 | 'ipaddr' | IPv4 address | no | WAN IP | Local endpoint
650 | 'peeraddr' | IPv4 address | yes | _(none)_ | Remote endpoint
651 | 'df' | boolean | no | true | Set "Don't Fragment" flag on encapsulating packets
652 | 'network' | logical interface name | no | _(none)_ | Logical network to which the tunnel will be added (bridged)
655 === Protocol "grev6" (GRE tunnel over IPv6) ===
657 The following options are supported, in addition to all common options above:
661 | Name | Type | Required | Default | Description
662 | 'ip6addr' | IPv6 address | no | WAN IP | Local endpoint
663 | 'peer6addr' | IPv6 address | yes | _(none)_ | Remote endpoint
664 | '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
667 === Protocol "grev6tap" (Ethernet GRE tunnel over IPv6) ===
669 The following options are supported, in addition to all common options above:
673 | Name | Type | Required | Default | Description
674 | 'ip6addr' | IPv6 address | no | WAN IP | Local endpoint
675 | 'peer6addr' | IPv6 address | yes | _(none)_ | Remote endpoint
676 | '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
677 | 'network' | logical interface name | no | _(none)_ | Logical network to which the tunnel will be added (bridged)
682 === Protocol "vti" (VTI tunnel over IPv4) ===
684 VTI Tunnels are IPsec policies with a fwmark set. The traffic is redirected to the matching VTI interface.
688 | Name | Type | Required | Default | Description
689 | 'ipaddr' | IPv4 address | no | WAN IP | Local endpoint
690 | 'peeraddr' | IPv4 address | yes | _(none)_ | Remote endpoint
691 | 'mtu' | integer | no | 1280 | MTU
692 | 'tunlink' | logical interface name | no | _(none)_ | Bind the tunnel to this interface ('dev' option of "ip tunnel")
693 | 'zone' | zone name | no | "wan" | Firewall zone to which the interface will be added
694 | 'ikey' | integer | no | 0 | key/fwmark for incoming packets
695 | 'okey' | integer | no | 0 | key/fwmark for outgoing packets
698 === Protocol "vtiv6" (VTI tunnel over IPv6) ===
700 The following options are supported, in addition to all common options above:
704 | Name | Type | Required | Default | Description
705 | 'ip6addr' | IPv6 address | no | WAN IP | Local endpoint
706 | 'peer6addr' | IPv6 address | yes | _(none)_ | Remote endpoint
707 | 'mtu' | integer | no | 1280 | MTU
708 | 'tunlink' | logical interface name | no | _(none)_ | Bind the tunnel to this interface ('dev' option of "ip tunnel")
709 | 'zone' | zone name | no | "wan" | Firewall zone to which the interface will be added
710 | 'ikey' | integer | no | 0 | key/fwmark for incoming packets
711 | 'okey' | integer | no | 0 | key/fwmark for outgoing packets
715 A minimal device declaration consists of the following lines:
718 config device 'eth0.106'
720 option name 'eth0.106'
724 === VLAN Interfaces ===
725 VLAN Interfaces may be configured also. If not, they are created on the fly by netifd. Defining VLANs gives more options.
726 The following options are supported:
730 | Name | Type | Required | Default | Description
731 | 'type' | VLAN Type | no | 802.1q | VLAN type, possible values: 8021q or 8021ad
732 | 'name' | Name | yes | _(none)_ | Name of device, i.e. eth0.5 or vlan5
733 | 'ifname' | Parent interface | yes | _(none)_ | Name of parent/base interface, i.e. eth0
734 | 'vid' | VLAN Id | yes | _(none)_ | VLAN Id
735 | 'macaddr' | MAC | no | _(none)_ | MAC of new interface
738 MAC address option is send upstream but not merged at time of writng.
739 === ATM Bridges (Ethernet over ATM AAL5)
741 CAUTION: The package 'br2684ctl' must be installed to use Ethernet over AAL5.
743 ATM bridges use a special config section called 'atm-bridge'.
744 Each 'atm-bridge' section maps the specified ATM curcuit an 'atm#' pseudo ethernet device which can
745 be used for example in conjunction with 'pppoe' to establish a DSL connection to the ISP.
747 A typical bridge section looks like this:
755 * Unit '0' will let 'br2684ctl' create a 'nas0' pseudo device
756 * VPI '8' and VCI '35' specifies the circuit to bridge. Those values are ISP dependant.
758 The 'atm-bridge' section allows the following options:
762 | Name | Type | Required | Default | Description
763 | 'unit' | number | yes | '0' | Specifies the br2684 interface number. If ommitted, '0' is assumed which would result in a 'nas0' pseudo interface.
764 | 'vci' | number | no | '35' | PPPoA VCI
765 | 'vpi' | number | no | '8' | PPPoA VPI
766 | '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
767 | 'encaps' | string | no | 'llc' | PPPoA encapsulation mode: 'llc' (LLC) or 'vc' (VC)
768 | 'payload' | string | no | 'bridged' | PPPoA forwarding mode: 'routed' or 'bridged'
773 CAUTION: This currently only works on devices based on [[doc/hardware/soc/soc.lantiq|lantiq SoCs]].
775 (V)DSL uses a special config section called 'dsl', which typically looks like this:
779 option firmware '/lib/firmware/vdsl.bin'
781 option xfer_mode 'atm'
784 The 'dsl' section allows the following options:
788 | Name | Type | Required | Default | Description
789 | '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
790 | '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 **
791 | '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**
792 | '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.**
795 === Lantiq xDSL firmware ===
797 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:
799 * dsl-vrx200-firmware-xdsl-a
800 * dsl-vrx200-firmware-xdsl-b
802 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/[]
806 Basically create an 'interface' section per IP, but alias interfaces may NOT be of type bridge
808 * For non-bridged interfaces (physdev , that is physical interfaces) the 'ifname' is the <interface-of-network-for-same-phydev>
809 * 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).
811 A minimal alias definition for a bridged interface might be (for a scenario without vlans):
814 option 'ifname' 'eth0'
815 option 'type' 'bridge'
816 option 'proto' 'static'
817 option 'ipaddr' '192.168.1.1'
818 option 'netmask' '255.255.255.0'
822 config interface lan2
823 option 'ifname' 'br-lan'
824 option 'proto' 'static'
825 option 'ipaddr' '10.0.0.1'
826 option 'netmask' '255.255.255.0'
829 or for a non-bridge interface
832 option 'ifname' 'eth0'
833 option 'proto' 'static'
834 option 'ipaddr' '192.168.1.1'
835 option 'netmask' '255.255.255.0'
839 config interface lan2
840 option 'ifname' 'eth0'
841 option 'proto' 'static'
842 option 'ipaddr' '10.0.0.1'
843 option 'netmask' '255.255.255.0'
846 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').
848 === Aliases: notes ===
850 On openwrt 12.09, a lan interface that is first defined as dhcp interface
851 and then has aliases with static ip address could cause problems
852 in routing the lan traffic through the wan zone using the basic lan-wan forwarding provided by openwrt.
853 A solution is: having the basic interface with static address and aliases with dhcp protocol.
855 Another note is related to 'how to refer to the ifname of an interface'.
856 Normally the ifname is 'br-wan' if the interface 'wan' is bridged,
857 else is 'ifname <nic_device>' . Another way to avoid to list always the same
858 device is using 'ifname @interface'. In this way, even if the wan interface
859 is not a bridge, one can refer to the physical device used by the wan interface
864 Static _IPv4 routes_ can be defined on specific interfaces using 'route' sections. As for _aliases_, multiple sections can be attached to an interface.
866 A minimal example looks like this:
869 config 'route' 'name_your_route'
870 option 'interface' 'lan'
871 option 'target' '172.16.123.0'
872 option 'netmask' '255.255.255.0'
873 option 'gateway' '172.16.123.100'
876 * 'lan' is the _logical interface name_ of the parent interface
877 * '172.16.123.0' is the _network address_ of the route
878 * '255.255.255.0' specifies the _route netmask_
880 Legal options for _IPv4 routes_ are:
884 | Name | Type | Required | Default | Description
885 | '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
886 | 'target' | ip address | yes | _(none)_ | Network address
887 | 'netmask' | netmask | no | _(none)_ | Route netmask. If omitted, '255.255.255.255' is assumed which makes 'target' a _host address_
888 | '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
889 | 'metric' | number | no | '0' | Specifies the _route metric_ to use
890 | 'mtu' | number | no | _interface MTU_ | Defines a specific MTU for this route
891 | '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
892 | 'source' | ip address | no | _(none)_ | The preferred source address when sending to destinations covered by the target
893 | 'onlink' | boolean | no | '0' | When enabled gateway is on link even if the gateway does not match any interface prefix (Barrier Breaker and later only)
894 | 'type' | string | no | 'unicast' | One of the types outlined in the Routing Types table below (Barrier Breaker and later only)
897 To disable a route quickly, the option 'enabled' is not available. Just rewrite the 'route' config section as 'disabled_route' like:
899 config 'disabled_route' 'name_your_route'
902 and it will be recognized by the uci parser but not applied by the '/etc/init.d/network' script.
904 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.
907 _IPv6 routes_ can be specified as well by defining one or more 'route6' sections.
909 A minimal example looks like this:
913 option 'interface' 'lan'
914 option 'target' '2001:0DB8:100:F00:BA3::1/64'
915 option 'gateway' '2001:0DB8:99::1'
918 * 'lan' is the _logical interface name_ of the parent interface
919 * '2001:0DB8:100:F00:BA3::1/64' is the routed _IPv6 subnet_ in CIDR notation
920 * '2001:0DB8:99::1' specifies the _IPv6 gateway_ for this route
922 Legal options for _IPv6 routes_ are:
926 | Name | Type | Required | Default | Description
927 | '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
928 | 'target' | ipv6 address | yes | _(none)_ | IPv6 network address
929 | 'gateway' | ipv6 address | no | _(none)_ | IPv6 gateway. If omitted, the 'gateway' from the parent interface is taken
930 | 'metric' | number | no | '0' | Specifies the _route metric_ to use
931 | 'mtu' | number | no | _interface MTU_ | Defines a specific MTU for this route
932 | '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
933 | 'source' | ip address | no | _(none)_ | The preferred source address when sending to destinations covered by the target
934 | 'onlink' | boolean | no | '0' | When enabled gateway is on link even if the gateway does not match any interface prefix (Barrier Breaker and later only)
935 | 'type' | string | no | 'unicast' | One of the types outlined in the Routing Types table below (Barrier Breaker and later only)
938 === Routing Types ===
943 | 'unicast' | the route entry describes real paths to the destinations covered by the route prefix.
944 | 'local' | the destinations are assigned to this host. The packets are looped back and delivered locally.
945 | 'broadcast' | the destinations are broadcast addresses. The packets are sent as link broadcasts.
946 | 'multicast' | a special type used for multicast routing. It is not present in normal routing tables.
947 | 'unreachable' | these destinations are unreachable. Packets are discarded and the ICMP message host unreachable is generated. The local senders get an EHOSTUNREACH error.
948 | 'prohibit' | these destinations are unreachable. Packets are discarded and the ICMP message communication administratively prohibited is generated. The local senders get an EACCES error.
949 | 'blackhole' | these destinations are unreachable. Packets are discarded silently. The local senders get an EINVAL error.
950 | '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.
956 Since OpenWrt Barrier Breaker, netifd supports _IP rule_ declarations which are required to implement policy routing.
957 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.
959 A simple IPv4 rule may look like:
965 option dest '172.16.0.0/16'
969 * '0xFF' is a [[http:_www.tldp.org/HOWTO/Adv-Routing-HOWTO/lartc.netfilter.html|fwmark]] to be matched
970 * 'lan' is the incoming _logical interface name_
971 * '172.16.0.0/16' is the destination subnet to match
972 * '100' is the routing table ID to use for the matched traffic
974 Similary, an IPv6 rule looks like:
979 option dest 'fdca:1234::/64'
980 option action 'prohibit'
983 * 'vpn' is the incoming _logical interface name_
984 * 'fdca:1234::/64' is the destination subnet to match
985 * 'prohibit' is a routing action to take
987 The options below are defined for _IP rule_ ('rule' and 'rule6') sections:
991 | Name | Type | Required | Default | Description
992 | 'in' | string | no | _(none)_ | Specifies the incoming _logical interface name_
993 | 'out' | string | no | _(none)_ | Specifies the outgoing _logical interface name_
994 | 'src' | ip subnet | no | _(none)_ | Specifies the source subnet to match (CIDR notation)
995 | 'dest' | ip subnet | no | _(none)_ | Specifies the destination subnet to match (CIDR notation)
996 | 'tos' | integer | no | _(none)_ | Specifies the TOS value to match in IP headers
997 | '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
998 | 'invert' | boolean | no | '0' | If set to '1', the meaning of the match options is inverted
999 | '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
1000 | '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
1001 | 'goto' | rule index | ::: | ::: | The rule target is a jump to another rule specified by its 'priority' value
1002 | 'action' | string | ::: | ::: | The rule target is one of the routing actions outlined in the table below
1005 === Routing Actions ===
1009 | Action | Description
1010 | 'prohibit' | When reaching the rule, respond with _ICMP prohibited_ messages and abort route lookup
1011 | 'unreachable' | When reaching the rule, respond with _ICMP unreachable_ messages and abort route lookup
1012 | 'blackhole' | When reaching the rule, drop packet and abort route lookup
1013 | 'throw' | Stop lookup in the current routing table even if a default route exists
1018 Below are a few examples for special, non-standard interface configurations.
1020 === Bridge without IP
1023 config 'interface' 'example'
1024 option 'type' 'bridge'
1025 option 'proto' 'none'
1026 option 'ifname' 'eth0 eth1'
1030 === DHCP without default gateway
1034 config 'interface' 'example'
1035 option 'proto' 'dhcp'
1036 option 'ifname' 'eth0'
1037 option 'defaultroute' '0'
1040 CAUTION: Older versions of OpenWRT used this instead, but this method is deprecated and no longer works in Chaos Calmer:
1043 config 'interface' 'example'
1044 option 'proto' 'dhcp'
1045 option 'ifname' 'eth0'
1046 option 'gateway' '0.0.0.0'
1052 config 'interface' 'example'
1053 option 'proto' 'dhcp'
1054 option 'ifname' 'eth0'
1057 option 'interface' 'example'
1058 option 'proto' 'static'
1059 option 'ip6addr' '2001:0DB8:100:F00:BA3::1'
1062 === Static IP configuration with multiple dnses
1065 config 'interface' 'example'
1066 option 'proto' 'static'
1067 option 'ifname' 'eth0'
1068 option 'ipaddr' '192.168.1.200'
1069 option 'netmask' '255.255.255.0'
1070 list 'dns' '192.168.1.1'
1071 list 'dns' '192.168.10.1'
1072 # the priority is: the last dns listed will be the first one
1073 # to be chosen for the name resolution.
1076 CAUTION: Openwrt will use the new dns configured only after a reboot or a '/etc/init.d/dnsmasq restart'.
1078 === Static IP configuration and default gateway with non-zero metric
1081 config 'interface' 'example'
1082 option 'proto' 'static'
1083 option 'ifname' 'eth0'
1084 option 'ipaddr' '192.168.1.200'
1085 option 'netmask' '255.255.255.0'
1086 option 'dns' '192.168.1.1'
1089 option 'interface' 'example'
1090 option 'target' '0.0.0.0'
1091 option 'netmask' '0.0.0.0'
1092 option 'gateway' '192.168.1.1'
1093 option 'metric' '100'
1096 === PPtP-over-PPPoE internet connection
1099 config 'interface' 'wan'
1100 option 'proto' 'pppoe'
1101 option 'ifname' 'eth1'
1102 option 'username' 'user'
1103 option 'password' 'pass'
1104 option 'timeout' '10'
1106 config 'interface' 'vpn'
1107 option 'proto' 'pptp'
1108 option 'ifname' 'vpn'
1109 option 'username' 'vpnuser'
1110 option 'password' 'vpnpass'
1111 option 'server' 'vpn.example.org'
1114 CAUTION: Additionally the "wan" firewall zone must include both interfaces in '/etc/config/firewall':
1119 option 'network' 'wan vpn' # Important
1120 option 'input' 'REJECT'
1121 option 'forward' 'REJECT'
1122 option 'output' 'ACCEPT'
1126 === PPPoA ADSL internet connection
1129 config adsl-device 'adsl'
1133 config interface 'wan'
1134 option proto 'pppoa'
1135 option username 'jbloggs@plusdsl.net'
1136 option password 'XXXXXXXXX'
1142 === listing an interface created by software on the router, like vpn
1144 For example, a vpn interface is normally "tun0". To list it in the uci config files (and therefore in luci):
1146 config interface 'tun0'
1147 option ifname 'tun0'
1151 === Static IPv6-in-IPv4 tunnel
1153 The example below illustrates a static tunnel configuration in '/etc/config/network' file for the Hurricane Electric (he.net) broker.
1154 Option 'ipaddr' specifies the local IPv4 address, 'peeraddr' is the broker IPv4 address and 'ip6addr' the local IPv6 address routed via the tunnel.
1157 config 'interface' 'henet'
1158 option 'proto' '6in4'
1159 option 'ipaddr' '178.24.115.19'
1160 option 'peeraddr' '216.66.80.30'
1161 option 'ip6addr' '2001:0DB8:1f0a:1359::2/64'
1164 CAUTION: You should also add an address from your routed IPv6 network to the "lan" interface.
1166 CAUTION: To apply IPv6 firewall rules to the tunnel interface, add it to the "wan" zone in '/etc/config/firewall':
1171 option 'network' 'wan henet' # Important
1172 option 'input' 'REJECT'
1173 option 'forward' 'REJECT'
1174 option 'output' 'ACCEPT'
1178 CAUTION: If you define a new, dedicated [[doc/uci/firewall#zones|zone]] just for the tunnel interface,
1179 make sure to set 'option conntrack 1' in order to [[doc/uci/firewall#note.on.connection.tracking.notrack|force enabling connection tracking]],
1180 otherwise [[doc/uci/firewall#forwardings|unidirectional forwarding rules]] will not work.
1182 CAUTION: Don't forget to set up [[doc:uci:firewall#forwarding.ipv6.tunnel.traffic|forwarding rules]] between the LAN and the tunnel if you want to route IPv6 traffic between them.
1184 === Setup behind one-to-one NAT ===
1186 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:
1190 uci -P/var/state get network.wan.ipaddr
1193 * Trunk/Attitude Adjustment
1195 . /lib/functions/network.sh; network_get_ipaddr ip wan; echo $ip
1198 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 [[doc:uci:network#protocol.6in4.ipv6-in-ipv4.tunnel|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:
1201 config 'interface' 'henet'
1202 option 'proto' '6in4'
1203 option 'peeraddr' '216.66.80.30'
1204 option 'ip6addr' '2001:0DB8:1f0a:1359::2/64'
1207 **Note:** you could probably try to define [[doc:uci:network#aliases|alias]] for WAN interface with your public IP address. Then you could use your public IP in 'ipaddr' option and system would find its way to your WAN interface that has only private IP address because of the one-to-one NAT. (WARNING: However, it didn't really worked for me. I got this advice on IRC and it looks reasonable, thats why I put it here anyway. If it was **not** supposed to fix it, just delete this note.)
1209 === Dynamic IPv6-in-IPv4 tunnel (HE.net only)
1211 The example below illustrates a dynamic tunnel configuration for the Hurricane Electric (he.net) broker with enabled IP update.
1212 The local IPv4 address is automatically determined and tunnelid, username and password are provided for IP update.
1215 config 'interface' 'henet'
1216 option 'proto' '6in4'
1217 option 'peeraddr' '216.66.80.30'
1218 option 'ip6addr' '2001:0DB8:1f0a:1359::2/64'
1219 option 'tunnelid' '12345'
1220 option 'username' 'myusername'
1221 option 'password' '098f6bcd4621d373cade4e832627b4f6'
1224 CAUTION: You should also add an address from your routed IPv6 network to the "lan" interface.
1226 CAUTION: To apply IPv6 firewall rules to the tunnel interface, add it to the "wan" firewall zone, see example above for details.
1228 CAUTION: The password entered above should be the md5sum of the password you use to log in to tunnelbroker.net.
1230 === L2TPv3 Pseudowire bridged to LAN
1232 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'.
1235 config 'interface' 'lan'
1236 option 'proto' 'l2tp'
1237 option 'type' 'bridge'
1238 option 'ifname' 'eth0'
1239 option 'ipaddr' '192.168.1.1'
1240 option 'netmask' '255.255.255.0'
1241 option 'localaddr' '178.24.154.19'
1242 option 'peeraddr' '89.44.33.61'
1243 option 'encap' 'udp'
1244 option 'sport' '4000'
1245 option 'dport' '5410'
1248 === Relay between LAN and Wireless Station
1250 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.
1252 Wireless configuration (excerpt):
1256 option 'device' 'radio0'
1258 option 'ssid' 'Some Wireless Network'
1259 option 'encryption' 'psk2'
1260 option 'key' '12345678'
1261 option 'network' 'wwan'
1264 Network configuration (excerpt):
1266 CAUTION: Note that the LAN subnet must be different from the one used by wireless network's DHCP.
1269 config 'interface' 'lan'
1270 option 'ifname' 'eth0.1'
1271 option 'proto' 'static'
1272 option 'ipaddr' '192.168.1.1'
1273 option 'netmask' '255.255.255.0'
1275 config 'interface' 'wwan'
1276 option 'proto' 'dhcp'
1278 config 'interface' 'stabridge'
1279 option 'proto' 'relay'
1280 option 'network' 'lan wwan'
1283 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:
1288 option 'network' 'lan wwan' # Important
1289 option 'input' 'ACCEPT'
1290 option 'forward' 'ACCEPT' # Important
1291 option 'output' 'ACCEPT'
1294 === Static addressing of a GRE tunnel
1296 Create a GRE tunnel with static address 10.42.0.253/30, adding it to an existing firewall zone called 'tunnels':
1299 config interface mytunnel
1302 option peeraddr 198.51.100.42
1304 config interface mytunnel_addr
1306 option ifname @mytunnel
1307 option ipaddr 10.42.0.253
1308 option netmask 255.255.255.252
1309 # Fixes IPv6 multicast (long-standing bug in kernel).
1310 # Useful if you run Babel or OSPFv3.
1311 option ip6addr 'fe80::42/64'
1314 == Network management
1316 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.
1318 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.
1320 == Determining Linux interface names
1322 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.
1325 WANIF=$(uci -P/var/state get network.wan.ifname)
1326 iptables -I INPUT -i $WANIF -p tcp --dport 22 -j ACCEPT
1329 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].
1330 Use /lib/functions/network.sh:
1333 source /lib/functions/network.sh
1335 if network_get_ipaddr addr "wan"; then
1340 == Multiple IP addresses
1342 Assigning multiple ip addresses to the same interface:
1344 config interface foo
1346 list ipaddr 10.8.0.1/24
1347 list ipaddr 10.9.0.1/24
1348 list ip6addr fdca:abcd::1/64
1349 list ip6addr fdca:cdef::1/64
1352 Specifying multiple interfaces sharing the same device:
1355 config interface foo
1357 option ipaddr 10.8.0.1
1358 option netmask 255.255.255.0
1359 option ip6addr fdca:abcd::1/64
1361 config interface foo2
1363 option ipaddr 10.9.0.1
1364 option netmask 255.255.255.0
1365 option ip6addr fdca:cdef::1/64