6 include::uci_menu.inc[]
8 == Firewall Configuration
10 The firewall configuration located in **'/etc/config/firewall'**.
14 OpenWrt relies on netfilter for packet filtering, NAT and mangling. The UCI Firewall provides a configuration interface that abstracts from the **iptables** system to provide a simplified configuration model that is fit for most regular purposes while enabling the user to supply needed iptables rules on their own when needed.
16 UCI Firewall maps two or more _Interfaces_ together into _Zones_ that are used to describe default rules for a given interface, forwarding rules between interfaces and extra rules. In the config file, default rules come _first_ but they are the last to take effect. The netfilter system is a chained processing filter where packets pass through various rules. The first rule that matches is executed, often leading to another rule-chain until a packet hits either ACCEPT or DROP/REJECT. Such an outcome is final, therefore the default rules take effect last and the most specific rule takes effect first. Zones are also used to configure _masquerading_ also known as NAT (network-address-translation) as well as port forwarding rules, which are more generally known as redirects.
18 Zones must always be mapped onto one or more Interfaces which ultimately map onto physical devices; therefore zones cannot be used to specify networks (subnets) and the generated iptables rules operate on interfaces exclusively. The difference is that interfaces can be used to reach destinations not part of their own subnet, when their subnet contains another gateway. Usually however, forwarding is done between lan and wan interfaces, with the router serving as 'edge' gateway to the internet. The default configuration of UCI Firewall provides for such a common setup.
22 * **'firewall'** (or **'firewall3'**) and its dependencies (_pre-installed_)
23 * **'iptables'** (_pre-installed_)
24 * **'iptables-mod-?'** (_optional_) - depends on what speial feature is required
28 Below is an overview of the section types that may be defined in the firewall configuration.
29 A minimal firewall configuration for a router usually consists of one _defaults_ section, at least two _zones_ ('lan' and 'wan') and one _forwarding_ to allow traffic from 'lan' to 'wan'.
33 The 'defaults' section declares global firewall settings which do not belong to specific zones.
34 The following options are defined within this section:
36 [cols="4*1,4",options="header"]
38 | Name | Type | Required | Default | Description
39 | 'input' | string | no | 'REJECT' | Set policy for the 'INPUT' chain of the 'filter' table.
40 | 'output' | string | no | 'REJECT' | Set policy for the 'OUTPUT' chain of the 'filter' table.
41 | 'forward' | string | no | 'REJECT' | Set policy for the 'FORWARD' chain of the 'filter' table.
42 | 'drop_invalid' | boolean | no | '0' | Drop invalid packets (e.g. not matching any active connection).
43 | 'synflood_protect' | boolean | no | '0' | Enable SYN flood protection.
44 | 'synflood_rate' | string | no | '25' | Set rate limit (packets/second) for SYN packets above which the traffic is considered a flood.
45 | 'synflood_burst' | string | no | '50' | Set burst limit for SYN packets above which the traffic is considered a flood if it exceeds the allowed rate.
46 | 'tcp_syncookies' | boolean | no | '1' | Enable the use of SYN cookies.
47 | 'tcp_ecn' | boolean | no | '0' |
48 | 'tcp_westwood' | boolean | no | '0' |
49 | 'tcp_window_scaling' | boolean | no | '1' | Enable TCP window scaling.
50 | 'accept_redirects' | boolean | no | '0' |
51 | 'accept_source_route' | boolean | no | '0' |
52 | 'custom_chains' | boolean | no | '1' |
53 | 'disable_ipv6' | boolean | no | '0' | Disable IPv6 firewall rules.
58 A 'zone' section groups one or more _interfaces_ and serves as a _source_ or _destination_ for _forwardings_, _rules_ and _redirects_. Masquerading (NAT) of outgoing traffic is controlled on a per-zone basis. Note that masquerading is defined on the _outgoing_ interface.
60 * INPUT rules for a zone describe what happens to traffic trying to reach the router itself through an interface in that zone.
61 * OUTPUT rules for a zone describe what happens to traffic originating from the router itself going through an interface in that zone.
62 * FORWARD rules for a zone describe what happens to traffic passing between different interfaces in that zone.
64 The options below are defined within 'zone' sections:
66 [cols="4*1,4",options="header"]
68 | Name | Type | Required | Default | Description
69 | 'name' | zone name | yes | _(none)_ | Unique zone name. 11 characters is the maximum working firewall zone name length.
70 | 'network' | list | no | _(none)_ | List of interfaces attached to this zone. If omitted and neither extra* options, subnets or devices are given, the value of 'name' is used by default. Alias interfaces defined in the network config cannot be used as valid 'standalone' networks.
71 | 'masq' | boolean | no | '0' | Specifies whether _outgoing_ zone traffic should be masqueraded - this is typically enabled on the _wan_ zone
72 | 'masq_src' | list of subnets | no | '0.0.0.0/0' | Limit masquerading to the given source subnets. Negation is possible by prefixing the subnet with '!'. multiple subnets are allowed.
73 | 'masq_dest' | list of subnets | no | '0.0.0.0/0' | Limit masquerading to the given destination subnets. Negation is possible by prefixing the subnet with '!'. multiple subnets are allowed.
74 | 'conntrack' | boolean | no | '1' if masquerading is used, '0' otherwise | Force connection tracking for this zone
75 | 'mtu_fix' | boolean | no | '0' | Enable MSS clamping for _outgoing_ zone traffic
76 | 'input' | string | no | 'DROP' | Default policy ('ACCEPT', 'REJECT', 'DROP') for _incoming_ zone traffic
77 | 'forward' | string | no | 'DROP' | Default policy ('ACCEPT', 'REJECT', 'DROP') for _forwarded_ zone traffic
78 | 'output' | string | no | 'DROP' | Default policy ('ACCEPT', 'REJECT', 'DROP') for _outgoing_ zone traffic
79 | 'family' | string | no | 'any' | Protocol family ('ipv4', 'ipv6' or 'any') to generate iptables rules for
80 | 'log' | boolean | no | '0' | Create log rules for rejected and dropped traffic in this zone
81 | 'log_limit' | string | no | '10/minute' | Limits the amount of log messages per interval
82 | 'device' | list | no | _(none)_ | List of raw network device names attached to this zone, e.g. 'ppp+' to match any PPP interface
83 | 'subnet' | list | no | _(none)_ | List of IP subnets attached to this zone
84 | 'extra' | string | no | _(none)_ | Extra arguments passed directly to iptables. Note that these options are passed to both source and destination classification rules, therfore direction-specific options like '--dport' should not be used here - in this case the 'extra_src' and 'extra_dest' options should be used instead
85 | 'extra_src' | string | no | _Value of 'extra'_ | Extra arguments passed directly to iptables for source classification rules
86 | 'extra_dest' | string | no | _Value of 'extra'_ | Extra arguments passed directly to iptables for destination classification rules
91 The 'forwarding' sections control the traffic flow between _zones_ and may enable MSS clamping for specific directions. Only one direction is covered by a 'forwarding' rule. To allow bidirectional traffic flows between two _zones_, two _forwardings_ are required, with 'src' and 'dest' reversed in each.
93 Below is a listing of allowed option within _forwardings_:
95 [cols="4*1,4",options="header"]
97 | Name | Type | Required | Default | Description
98 | 'src' | zone name | yes | _(none)_ | Specifies the traffic _source zone_. Must refer to one of the defined _zone names_
99 | 'dest' | zone name | yes | _(none)_ | Specifies the traffic _destination zone_. Must refer to one of the defined _zone names_
100 | 'family' | string | no | 'any' | Protocol family ('ipv4', 'ipv6' or 'any') to generate iptables rules for
103 CAUTION: The _iptables_ rules generated for this section rely on the _state match_ which needs connection tracking to work.
104 At least one of the 'src' or 'dest' zones needs to have _connection tracking_ enabled through either the 'masq' or the 'conntrack' option.
108 Port forwardings (DNAT) are defined by 'redirect' sections. All _incoming_ traffic on the specified _source zone_ which matches the given rules will be directed to the specified internal host.
110 _Redirects are also commonly known as "port forwarding", and "virtual servers"._
112 Port ranges are specified as 'start:stop', for instance '6666:6670'. This is similar to the iptables syntax.
114 The options below are valid for _redirects_:
116 [cols="4*1,4",options="header"]
118 | Name | Type | Required | Default | Description
119 | 'src' | zone name | yes for 'DNAT' target | _(none)_ | Specifies the traffic _source zone_. Must refer to one of the defined _zone names_. For typical port forwards this usually is 'wan'
120 | 'src_ip' | ip address | no | _(none)_ | Match incoming traffic from the specified _source ip address_
121 | 'src_dip' | ip address | yes for 'SNAT' target | _(none)_ | For _DNAT_, match incoming traffic directed at the given _destination ip address_. For _SNAT_ rewrite the _source address_ to the given address.
122 | 'src_mac' | mac address | no | _(none)_ | Match incoming traffic from the specified _mac address_
123 | 'src_port' | port or range | no | _(none)_ | Match incoming traffic originating from the given _source port or port range_ on the client host
124 | 'src_dport' | port or range | no | _(none)_ | For _DNAT_, match incoming traffic directed at the given _destination port or port range_ on this host. For _SNAT_ rewrite the _source ports_ to the given value.
125 | 'proto' | protocol name or number | yes | _tcpudp_ | Match incoming traffic using the given _protocol_
126 | 'dest' | zone name | yes for 'SNAT' target | _(none)_ | Specifies the traffic _destination zone_. Must refer to one of the defined _zone names_.
127 | 'dest_ip' | ip address | yes for 'DNAT' target | _(none)_ | For _DNAT_, redirect matched incoming traffic to the specified internal host. For _SNAT_, match traffic directed at the given address. For _DNAT_ if the 'dest_ip' value matches the local ip addresses of the router, as shown in the 'ifconfig', then the rule is translated in a DNAT + input 'accept' rule. Otherwise it is a DNAT + forward rule
128 | 'dest_port' | port or range | no | _(none)_ | For _DNAT_, redirect matched incoming traffic to the given port on the internal host. For _SNAT_, match traffic directed at the given ports. Only a single port or range can be specified, not disparate ports as with Rules (below)
129 | 'ipset' | string | no | _(none)_ | If specified, match traffic against the given ipset. The match can be inverted by prefixing the value with an exclamation mark
130 | 'mark' | string | no | _(none)_ | If specified, match traffic against the given firewall mark, e.g. '0xFF' to match mark 255 or '0x0/0x1' to match any even mark value. The match can be inverted by prefixing the value with an exclamation mark, e.g. '!0x10' to match all but mark #16.
131 | 'start_date' | date ('yyyy-mm-dd') | no | _(always)_ | If specifed, only match traffic after the given date (inclusive).
132 | 'stop_date' | date ('yyyy-mm-dd') | no | _(always)_ | If specified, only match traffic before the given date (inclusive).
133 | 'start_time' | time ('hh:mm:ss') | no | _(always)_ | If specified, only match traffic after the given time of day (inclusive).
134 | 'stop_time' | time ('hh:mm:ss') | no | _(always)_ | If specified, only match traffic before the given time of day (inclusive).
135 | 'weekdays' | list of weekdays | no | _(always)_ | If specified, only match traffic during the given week days, e.g. 'sun mon thu fri' to only match on sundays, mondays, thursdays and fridays. The list can be inverted by prefixing it with an exclamation mark, e.g. '! sat sun' to always match but on saturdays and sundays.
136 | 'monthdays' | list of dates | no | _(always)_ | If specified, only match traffic during the given days of the month, e.g. '2 5 30' to only match on every 2nd, 5th and 30rd day of the month. The list can be inverted by prefixing it with an exclamation mark, e.g. '! 31' to always match but on the 31st of the month.
137 | 'utc_time' | boolean | no | '0' | Treat all given time values as UTC time instead of local time.
138 | 'target' | string | no | 'DNAT' | NAT target ('DNAT' or 'SNAT') to use when generating the rule
139 | 'family' | string | no | 'any' | Protocol family ('ipv4', 'ipv6' or 'any') to generate iptables rules for.
140 | 'reflection' | boolean | no | '1' | Activate NAT reflection for this redirect - applicable to 'DNAT' targets.
141 | 'reflection_src' | string | no | 'internal' | The source address to use for NAT-reflected packets if 'reflection' is '1'. This can be 'internal' or 'external', specifying which interface’s address to use. Applicable to 'DNAT' targets.
142 | 'limit' | string | no | _(none)_ | Maximum average matching rate; specified as a number, with an optional '/second', '/minute', '/hour' or '/day' suffix. Examples: '3/second', '3/sec' or '3/s'.
143 | 'limit_burst' | integer | no | '5' | Maximum initial number of packets to match, allowing a short-term average above 'limit'
144 | 'extra' | string | no | _(none)_ | Extra arguments to pass to iptables. Useful mainly to specify additional match options, such as '-m policy %%--%%dir in' for IPsec.
145 | 'enabled' | string | no | '1' or 'yes' | Enable the redirect rule or not.
150 Sections of the type 'rule' can be used to define basic accept or reject rules to allow or restrict access to specific ports or hosts.
152 The rules are defined as follows:
153 * If 'src' and 'dest' are given, the rule matches _forwarded_ traffic
154 * If only 'src' is given, the rule matches _incoming_ traffic
155 * If only 'dest' is given, the rule matches _outgoing_ traffic
156 * If neither 'src' nor 'dest' are given, the rule defaults to an _outgoing_ traffic rule
158 Port ranges are specified as 'start:stop', for instance '6666:6670'. This is similar to the iptables syntax.
160 Valid options for this section are:
162 [cols="4*1,4",options="header"]
164 | Name | Type | Required | Default | Description
165 | 'src' | zone name | no | _(none)_ | Specifies the traffic _source zone_. Must refer to one of the defined _zone names_
166 | 'src_ip' | ip address | no | _(none)_ | Match incoming traffic from the specified _source ip address_
167 | 'src_mac' | mac address | no | _(none)_ | Match incoming traffic from the specified _mac address_
168 | 'src_port' | port or range | no | _(none)_ | Match incoming traffic from the specified _source port_ or _port range_, if relevant 'proto' is specified. Multiple ports can be specified like '80 443 465'
169 | 'proto' | protocol name or number | no | 'tcpudp' | Match incoming traffic using the given _protocol_. Can be one of 'tcp', 'udp', 'tcpudp', 'udplite', 'icmp', 'esp', 'ah', 'sctp', or 'all' or it can be a numeric value. A protocol name from '/etc/protocols' is also allowed. The number 0 is equivalent to 'all'.
170 | 'icmp_type' | list of type names or numbers | no | any | For _protocol_ 'icmp' select specific icmp types to match. Values can be either exact icmp type numbers or type names (see below).
171 | 'dest' | zone name | no | _(none)_ | Specifies the traffic _destination zone_. Must refer to one of the defined _zone names_, or * for any zone. If specified, the rule applies to _forwarded_ traffic; otherwise, it is treated as _input_ rule.
172 | 'dest_ip' | ip address | no | _(none)_ | Match incoming traffic directed to the specified _destination ip address_. With no dest zone, this is treated as an input rule!
173 | 'dest_port' | port or range | no | _(none)_ | Match incoming traffic directed at the given _destination port or port range_, if relevant 'proto' is specified. Multiple ports can be specified like '80 443 465'
174 | 'ipset' | string | no | _(none)_ | If specified, match traffic against the given ipset. The match can be inverted by prefixing the value with an exclamation mark
175 | 'mark' | mark/mask | no | _(none)_ | If specified, match traffic against the given firewall mark, e.g. '0xFF' to match mark 255 or '0x0/0x1' to match any even mark value. The match can be inverted by prefixing the value with an exclamation mark, e.g. '!0x10' to match all but mark #16.
176 | 'start_date' | date ('yyyy-mm-dd') | no | _(always)_ | If specifed, only match traffic after the given date (inclusive).
177 | 'stop_date' | date ('yyyy-mm-dd') | no | _(always)_ | If specified, only match traffic before the given date (inclusive).
178 | 'start_time' | time ('hh:mm:ss') | no | _(always)_ | If specified, only match traffic after the given time of day (inclusive).
179 | 'stop_time' | time ('hh:mm:ss') | no | _(always)_ | If specified, only match traffic before the given time of day (inclusive).
180 | 'weekdays' | list of weekdays | no | _(always)_ | If specified, only match traffic during the given week days, e.g. 'sun mon thu fri' to only match on sundays, mondays, thursdays and fridays. The list can be inverted by prefixing it with an exclamation mark, e.g. '! sat sun' to always match but on saturdays and sundays.
181 | 'monthdays' | list of dates | no | _(always)_ | If specified, only match traffic during the given days of the month, e.g. '2 5 30' to only match on every 2nd, 5th and 30rd day of the month. The list can be inverted by prefixing it with an exclamation mark, e.g. '! 31' to always match but on the 31st of the month.
182 | 'utc_time' | boolean | no | '0' | Treat all given time values as UTC time instead of local time.
183 | 'target' | string | yes | 'DROP' | Firewall action ('ACCEPT', 'REJECT', 'DROP', 'MARK', 'NOTRACK') for matched traffic
184 | 'set_mark' | mark/mask | yes for target 'MARK' | _(none)_ | Zeroes out the bits given by mask and ORs value into the packet mark. If mask is omitted, 0xFFFFFFFF is assumed
185 | 'set_xmark' | ::: | ::: | ::: | Zeroes out the bits given by mask and XORs value into the packet mark. If mask is omitted, 0xFFFFFFFF is assumed
186 | 'family' | string | no | 'any' | Protocol family ('ipv4', 'ipv6' or 'any') to generate iptables rules for.
187 | 'limit' | string | no | _(none)_ | Maximum average matching rate; specified as a number, with an optional '/second', '/minute', '/hour' or '/day' suffix. Examples: '3/minute', '3/min' or '3/m'.
188 | 'limit_burst' | integer | no | '5' | Maximum initial number of packets to match, allowing a short-term average above 'limit'
189 | 'extra' | string | no | _(none)_ | Extra arguments to pass to iptables. Useful mainly to specify additional match options, such as '-m policy %%--%%dir in' for IPsec.
190 | 'enabled' | boolean | no | yes | Enable or disable rule.
193 Available icmp type names for _icmp_type_:
197 | 'address-mask-reply' | 'host-redirect' | 'pong' | 'time-exceeded'
198 | 'address-mask-request' | 'host-unknown' | 'port-unreachable' | 'timestamp-reply'
199 | 'any' | 'host-unreachable' | 'precedence-cutoff' | 'timestamp-request'
200 | 'communication-prohibited' | 'ip-header-bad' | 'protocol-unreachable' | 'TOS-host-redirect'
201 | 'destination-unreachable' | 'network-prohibited' | 'redirect' | 'TOS-host-unreachable'
202 | 'echo-reply' | 'network-redirect' | 'required-option-missing' | 'TOS-network-redirect'
203 | 'echo-request' | 'network-unknown' | 'router-advertisement' | 'TOS-network-unreachable'
204 | 'fragmentation-needed' | 'network-unreachable' | 'router-solicitation' | 'ttl-exceeded'
205 | 'host-precedence-violation' | 'parameter-problem' | 'source-quench' | 'ttl-zero-during-reassembly'
206 | 'host-prohibited' | 'ping' | 'source-route-failed' | 'ttl-zero-during-transit'
211 It is possible to include custom firewall scripts by specifying one or more 'include' sections in the firewall configuration.
213 There is only one possible parameter for _includes_:
215 [cols="4*1,4",options="header"]
217 | Name | Type | Required | Default | Description
218 | 'enabled' | boolean | no | '1' | Allows to disable the corresponding include without having to delete the section
219 | 'type' | string | no | 'script' | Specifies the type of the include, can be 'script' for traditional shell script includes or 'restore' for plain files in _iptables-restore_ format
220 | 'path' | file name | yes | '/etc/firewall.user' | Specifies a shell script to execute on boot or firewall restarts
221 | 'family' | string | no | 'any' | Specifies the address family ('ipv4', 'ipv6' or 'any') for which the include is called
222 | 'reload' | boolean | no | '0' | Specifies whether the include should be called on reload - this is only needed if the include injects rules into internal chains
225 Includes of type 'script' may contain arbitary commands, for example advanced iptables rules or tc commands required for traffic shaping.
227 CAUTION: Since custom iptables rules are meant to be more specific than the generic ones, you must make sure to use '-I' (insert) instead of '-A' (append) so that the rules appear **before** the default rules.
232 The UCI firewall version 3 supports referencing or creating http://ipset.netfilter.org/[ipsets] to simplify matching of
233 huge address or port lists without the need for creating one rule per item to match,
235 The following options are defined for _ipsets_:
237 [cols="4*1,4",options="header"]
239 | Name | Type | Required | Default | Description
240 | 'enabled' | boolean | no | '1' | Allows to disable the declaration fo the ipset without the need to delete the section
241 | 'external' | string | no | _(none)_ | If the 'external' option is set to a name, the firewall will simply reference an already existing ipset pointed to by the name. If the 'external' option is unset, the firewall will create the ipset on start and destroy it on stop
242 | 'name' | string | yes if 'external' is unset \\ no if 'external' is set | _(none)_ if 'external' is unset \\ value of 'external' if 'external' is set | Specifies the firewall internal name of the ipset which is used to reference the set in rules or redirects
243 | 'family' | string | no | 'ipv4' | Protocol family ('ipv4' or 'ipv6') to create ipset for. Only applicable to storage types 'hash' and 'list', the 'bitmap' type implies 'ipv4'.
244 | 'storage' | string | no | _varies_ | Specifies the storage method ('bitmap', 'hash' or 'list') used by the ipset, the default varies depending on the used datatypes (see 'match' option below). In most cases the storage method can be automatically inferred from the datatype combination but in some cases multiple choices are possible (e.g. 'bitmap:ip' vs. 'hash:ip').
245 | 'match' | list of direction/type tuples | yes | _(none)_ | Specifies the matched data types ('ip', 'port', 'mac', 'net' or 'set') and their direction ('src' or 'dest'). The direction is joined with the datatype by an underscore to form a tuple, e.g. 'src_port' to match source ports or 'dest_net' to match destination CIDR ranges.
246 | 'iprange' | IP range | yes for storage type 'bitmap' with datatype 'ip' | _(none)_ | Specifies the IP range to cover, see ipset. Only applicable to the 'hash' storage type.
247 | 'portrange' | Port range | yes for storage type 'bitmap' with datatype 'port' | _(none)_ | Specifies the port range to cover, see ipset. Only applicable to the 'hash' storage type.
248 | 'netmask' | integer | no | '32' | If specified, network addresses will be stored in the set instead of IP host addresses. Value must be between '1' and '32', see ipset. Only applicable to the 'bitmap' storage type with match 'ip' or the 'hash' storage type with match 'ip'.
249 | 'maxelem' | integer | no | '65536' | Limits the number of items that can be added to the set, only applicable to the 'hash' and 'list' storage types.
250 | 'hashsize' | integer | no | '1024' | Specifies the initial hash size of the set, only applicable to the 'hash' storage type.
251 | 'timeout' | integer | no | '0' | Specifies the default timeout for entries added to the set. A value of '0' means no timeout.
254 === Possible Storage / Match Combinations ===
256 The table below outlines the possible combinations of storage methods and matched datatypes as well as the usable IP address family.
257 The order of the datatype matches is significant.
261 | Family | Storage | Match | Notes
262 | 'ipv4' | 'bitmap' | 'ip' | Requries 'iprange' option
263 | 'ipv4' | 'bitmap' | 'ip mac' | Requires 'iprange' option
264 | 'ipv4' | 'bitmap' | 'port' | Requires 'portrange' option
265 | _any_ | 'hash' | 'ip' | -
266 | _any_ | 'hash' | 'net' | -
267 | _any_ | 'hash' | 'ip port' | -
268 | _any_ | 'hash' | 'net port' | -
269 | _any_ | 'hash' | 'ip port ip' | -
270 | _any_ | 'hash' | 'ip port net' | -
271 | - | 'list' | 'set' | Meta type to create a set-of-sets
276 As described above, the option 'family' is used for distinguishing between IPv4, IPv6 and both protocols. However the family is inferred automatically if IPv6 addresses are used, the following is automatically treated as an IPv6 only rule.
281 option src_ip fdca:f00:ba3::/64
286 Similar, such a rule is detected as IPv4 only.
291 option dest_ip 88.77.66.55
295 Rules without IP addresses are automatically added to iptables and ip6tables, unless overridden by the family option.
296 Redirect rules (portforwards) are always IPv4 (for now) since there is no IPv6 DNAT support (yet).
302 The default configuration accepts all LAN traffic, but blocks all incoming WAN traffic on ports not currently used for connections or NAT. To open a port for a service, add a 'rule' section:
311 This example enables machines on the internet to use SSH to access your router.
313 === Opening ports for selected subnet/host
315 If you want to permit access to one host or subnet you should describe _src_ip_ field:
319 option src_ip '12.34.56.64/28'
325 This example enables ssh access to the host from the entire _12.34.56.64/28_ subnet.
327 === Port forwarding for IPv4 (Destination NAT/DNAT)
329 This example forwards http (but not HTTPS) traffic to the webserver running on 192.168.1.10:
337 option dest_ip 192.168.1.10
340 This other example forwards one arbitrary port that you define to a box running ssh.
345 option src_dport 5555
348 option dest_ip 192.168.1.100
352 === Stateful firewall without NAT
354 If your LAN is running with public IP addresses, then you definitely don't want NAT (masquerading). But you may still want to run a stateful firewall on the router, so that machines on the LAN are not reachable from the Internet.
356 To do this, just add the `conntrack` option to the WAN zone:
365 option forward REJECT
371 === DNAT/SNAT redirects and forwarding combination
373 Given a couple of redirect (DNAT and SNAT, like to redirect the traffic from an host to and from a specific ip address) such as:
377 option name 'icmp DNAT'
379 option src_dip '1.2.3.4'
382 option dest_ip '192.168.1.79'
386 option name 'icmp SNAT'
388 option src_ip '192.168.1.79'
389 option src_dip '1.2.3.4'
395 Someone could ask "_Ok, the packet source or destination is changed, but still has to be forwarded towards the right network interface to reach the endpoint_". So the administrator of the device could wonder of adding additional forwarding rules but no, it is not needed. The forwarding rules are added by the firewall appliance itself.
397 The same applies to the masquerading, the rules are applied _before_ the global masquerading (if a masquerading is set), therefore they will not be overridden (at least the SNAT) by the masquerading mechanism.
399 === Port accept for IPv6
401 To open port 80 so that a local webserver at '2001:db8:42::1337' can be reached from the Internet:
408 option dest_ip 2001:db8:42::1337
414 To open SSH access to all IPv6 hosts in the local network:
426 To open all TCP/UDP port between 1024 and 65535 towards the local IPv6 network:
433 option dest_port 1024:65535
438 === Source NAT (SNAT)
440 Source NAT changes an outgoing packet so that it looks as though the OpenWrt system is the source of the packet.
442 Define source NAT for UDP and TCP traffic directed to port 123 originating from the host with the IP address 10.55.34.85.
443 The source address is rewritten to 63.240.161.99:
449 option src_ip 10.55.34.85
450 option src_dip 63.240.161.99
455 When used alone, Source NAT is used to restrict a computer's access to the internet, but allow it to access a few services by forwarding what appear to be a few local services, e.g. NTP, to the internet. While DNAT hides the local network from the internet, SNAT hides the internet from the local network.
457 Source NAT and destination NAT are combined and used dynamically in IP masquerading to make computers with private (192.168.x.x, etc.) IP address appear on the internet with the OpenWrt router's public WAN ip address.
459 === Block access to the Internet using MAC
461 The following rule blocks all connection attempts from the client to the Internet.
467 option src_mac 00:00:00:00:00:00
471 === Block access to the Internet for specific IP on certain times
473 The following rule blocks all connection attempts to the internet from 192.168.1.27 on weekdays between 21:00pm and 09:00am (times are specified in UTC unless the --kerneltz switch is used).
475 CAUTION: The package 'iptables-mod-ipopt' must be installed to provide 'xt_time'.
481 option src_ip 192.168.1.27
483 option start_time 21:00
484 option stop_time 09:00
485 option weekdays 'mon tue wed thu fri'
489 === Restricted forwarding rule
491 The example below creates a _forward_ rule rejecting traffic from lan to wan on the ports 1000-1100.
497 option dest_port 1000-1100
502 === Simple output rule
504 The example below creates an _output_ rule which prevents the router from pinging the address '8.8.8.8'.
509 option dest_ip 8.8.8.8
514 === Transparent proxy rule (same host)
516 The rule below redirects all outgoing HTTP traffic from _lan_ through a proxy server listening at port 3128 on the router itself.
523 option dest_port 3128
524 option dest_ip 192.168.1.1
527 === Transparent proxy rule (external)
529 The following rule redirects all outgoing HTTP traffic from _lan_ through an external proxy at 192.168.1.100 listening on port 3128.
530 It assumes the _lan_ address to be 192.168.1.1 - this is needed to masquerade redirected traffic towards the proxy.
536 option src_ip !192.168.1.100
538 option dest_ip 192.168.1.100
539 option dest_port 3128
545 option src_dip 192.168.1.1
546 option dest_ip 192.168.1.100
547 option dest_port 3128
551 === IPSec passthrough
553 This example enables proper forwarding of IPSec traffic through the wan.
571 For some configurations you also have to open port 500/UDP.
584 === Zone declaration for semi non-UCI interfaces, manually listed in the network config, and forwardings
586 Scenario: having one or more vpn tunnels using openvpn,
587 with the need of defining a zone to forward the traffic between the
588 vpn interfaces and the lan.
590 First list the interfaces in **/etc/config/network**,
591 for example in the following way: (be careful on the limits of interface naming in terms of name length.
594 config interface 'tun0'
598 config interface 'tun1'
603 Then create the zone in **/etc/config/firewall**, for example one zone for all the vpn interfaces.
607 option name vpn_tunnel
611 #the traffic towards the router from the interface will be accepted
612 #(as for the lan communications)
614 #the traffic from the router to the interface will be accepted
615 option forward REJECT
616 #traffic from this zone to other zones is normally rejected
619 Then we want to communicate with the "lan" zone, therefore we need forwardings in both ways
620 (from lan to wan and viceversa)
625 option dest vpn_tunnel
626 #if a packet from lan wants to go to the vpn_tunnel zone
630 option src vpn_tunnel
632 #if a packet from vpn_tunnel wants to go to the lan zone
636 This will create a lot of "automatic" iptables rules (because automatic scripting is not
637 as efficient as raw iptable commands in /etc/firewall.user) but those rules will be more clear in the luci webinterface and also more readable for
640 In general remember that forwardings are relying how routing rules are defined, and afterwards which zones are
641 defined on which interfaces.
643 === Zone declaration for non-UCI interfaces
645 This example declares a zone which maches any Linux network device whose name begins with "ppp".
652 option forward REJECT
656 === Zone declaration for a specific subnet and protocol
658 This example declares a zone which maches any TCP stream in the '10.21.0.0/16' subnet.
665 option forward REJECT
666 option subnet '10.21.0.0/16'
667 option extra '-p tcp'
671 === Zone declaration for a specific protocol and port
673 This example declares a zone which maches any TCP stream from and to port '22'.
680 option forward REJECT
681 option extra_src '-p tcp --sport 22'
682 option extra_dest '-p tcp --dport 22'
685 === Manual iptables rules
687 Traditional iptables rules, in the standard iptables unix command form, can be specified in an external file and included in the firewall config file. It is possible to include multiple files this way.
690 option path /etc/firewall.user
693 option path /etc/firewall.vpn
696 The syntax for the includes is Linux standard, and therefore different from UCI's.
698 == Firewall management
700 After a configuration change, firewall rules are rebuilt by executing '/etc/init.d/firewall restart'; calling '/etc/init.d/firewall stop' will flush all rules and set the policies to ACCEPT on all standard chains. To manually start the firewall, call '/etc/init.d/firewall start'.
702 The firewall can be permananently disabled by executing '/etc/init.d/firewall disable'.
703 Note that 'disable' does not flush the rules, so it might be required to issue a 'stop' before.
704 Use 'enable' to activate the firewall again.
706 === Temporarily disable firewall
708 Run '/etc/init.d/firewall stop' to flush all rules and set the policies to ACCEPT.
709 To restart the firewall, run '/etc/init.d/firewall start'.
713 In addition to _includes_ it is possible to let the firewall execute _hotplug handlers_ when interfaces are added to a zone or removed from it. This is useful to create rules for interfaces with dynamic ip configurations (dhcp, pppoe) on the fly.
715 Each time an interface is added or removed from a zone, all scripts in the '/etc/hotplug.d/firewall/' directory are executed. Scripts must be named in the form 'NN-name' with 'NN' being a numeric index between '00' and '99'. The 'name' can be freely choosen.
717 Once a handler script is invoked, the information about the event is passed through the environment. The table below lists defined variables and their meaning.
721 | Variable | Description
722 | ACTION | Type of the event: 'add' if an interface was added, 'remove' if it was removed
723 | ZONE | Name of the firewall zone the interface was added to
724 | INTERFACE | OpenWrt name of the interface, for example "lan" or "wan" - corresponds to the interfaces defined in '/etc/config/network'
725 | DEVICE | The physical interface involved, for example "eth0" or "ppp0"
728 == Implications of DROP vs. REJECT
730 The decision whether to _drop_ or to _reject_ traffic should be done on a case-by-case basis. Many people see dropping traffic as a security advantage over rejecting it because it exposes less information to a potential attacker. While dropping slightly increases security, it can also complicate the debugging of network issues or cause unwanted side-effects on client programs.
732 If traffic is _rejected_, the router will respond with an ICMP error message ("destination port unreachable") causing the connection attempt to fail immediately. This also means that for each connection attempt a certain amount of response traffic is generated. This can cause harm if the firewall is "attacked" with many simultaneous connection attempts; the resulting "backfire" of ICMP responses can clog up all available bandwidth and make the connection unusable (DoS).
734 When connection attempts are _dropped_ the client is not aware of the blocking and will continue to re-transmit its packets until the connection eventually times out. Depending on the way the client software is implemented, this could result in frozen or hanging programs that need to wait until a timeout occurs before they're able to continue.
736 Also there is an interesting article which that claims dropping connections doesnt make you any safer - link:http://www.chiark.greenend.org.uk/~peterb/network/drop-vs-reject[Drop versus Reject]
740 * less information is exposed
741 * less attack surface
742 * client software may not cope well with it (hangs until connection times out)
743 * may complicate network debugging (where was traffic dropped and why)
747 * may expose information (like the ip at which traffic was actually blocked)
748 * client software can recover faster from rejected connection attempts
749 * network debugging easier (routing and firewall issues clearly distinguishable)
752 == Notes on connection tracking
756 By default, the firewall will disable connection tracking for a zone if no masquerading is enabled. This is achieved by generating _NOTRACK_ firewall rules matching all traffic passing via interfaces referenced by the firewall zone. The purpose of _NOTRACK_ is to speed up routing and save memory by circumventing resource intensive connection tracking in cases where it is not needed. You can check if connection tracking is disabled by issuing 'iptables -t raw -vnL', it will list all rules, check for _NOTRACK_ target.
758 CAUTION: _NOTRACK_ will render certain ipables extensions unusable, for example the _MASQUERADE_ target or the _state_ match will not work!
760 If connection tracking is required, for example by custom rules in '/etc/firewall.user', the 'conntrack' option must be enabled in the corresponding zone to disable _NOTRACK_. It should appear as 'option 'conntrack' '1' ' in the right zone in '/etc/config/firewall'. For further information see http://security.maruhn.com/iptables-tutorial/x4772.html .
762 == Debug generated rule set
764 It is possible to observe the iptables commands generated by the firewall program,
765 this is useful to track down iptables errors during firewall restarts or to verify
766 the outcome of certain uci rules.
768 You can enable debug mode using the '-d' switch:
770 # fw3 -d reload 2>/tmp/iptables.log
773 Furthermore it is also possible to print the to-be generated ruleset using the 'print' command in conjunction with the '-4' and '-6' switches:
775 # fw3 -4 print > /tmp/ipv4.rules
776 # fw3 -6 print > /tmp/ipv6.rules
781 === INPUT (destined to router)
785 | Table | Chain | Type | Description
786 | raw | 'PREROUTING' | system |
787 | ::: | 'notrack' | internal | Internal chain for NOTRACK rules
788 | mangle | 'PREROUTING' | system |
789 | ::: | 'fwmark' | internal | Internal chain for MARK rules
790 | nat | 'PREROUTING' | system |
791 | ::: | 'delegate_prerouting' | internal | Internal chain to hold toplevel prerouting rules, dispatches traffic to the corresponding 'zone__name__prerouting' chains
792 | ::: | 'prerouting_rule' | user | Container chain for custom user prerouting rules (firewall.user)
793 | ::: | 'zone__name__prerouting' | internal | Per-zone container chains for DNAT (port forwarding) rules
794 | ::: | 'prerouting__name__rule' | user | Per-zone container chains for custom user prerouting rules (firewall.user)
795 | mangle | 'INPUT' | system |
796 | filter | 'INPUT' | system |
797 | ::: | 'delegate_input' | internal | Internal chain to hold toplevel input rules, dispatches traffic to the corresponding 'zone__name__input' chains
798 | ::: | 'input_rule' | user | Container chain for custom user input rules (firewall.user)
799 | ::: | 'syn_flood' | internal | Internal chain to match and drop syn flood attempts
800 | ::: | 'zone__name__input' | internal | Per-zone container chains for input rules
801 | ::: | 'input__name__rule' | user | Per-zone container chains for custom user input rules (firewall.user)
804 === OUTPUT (originating from router)
808 | Table | Chain | Type | Description
809 | raw | 'OUTPUT' | system |
810 | mangle | 'OUTPUT' | system |
811 | nat | 'OUTPUT' | system |
812 | filter | 'OUTPUT' | system |
813 | ::: | 'delegate_output' | internal | Internal chain to hold toplevel output rules, dispatches traffic to the corresponding 'zone__name__output' chains
814 | ::: | 'output_rule' | user | Container chain for custom user output rules (firewall.user)
815 | ::: | 'zone__name__output' | internal | Per-zone container chains for output rules
816 | ::: | 'output__name__rule' | user | Per-zone container chains for custom user output rules (firewall.user)
817 | mangle | 'POSTROUTING' | system |
818 | nat | 'POSTROUTING' | system |
819 | ::: | 'delegate_postrouting' | internal | Internal chain to hold toplevel postrouting rules, dispatches traffic to the corresponding 'zone__name__postrouting' chains
820 | ::: | 'postrouting_rule' | user | Container chain for custom user postrouting rules (firewall.user)
821 | ::: | 'zone__name__postrouting' | internal | Per-zone container chains for postrouting rules (masq, snat)
822 | ::: | 'postrouting__name__rule' | user | Per-zone container chains for custom user postrouting rules (firewall.user)
825 === FORWARD (relayed through router)
829 | Table | Chain | Type | Description
830 | raw | 'PREROUTING' | system |
831 | ::: | 'notrack' | internal | Internal chain for NOTRACK rules
832 | mangle | 'PREROUTING' | system |
833 | ::: | 'fwmark' | internal | Internal chain for MARK rules
834 | nat | 'PREROUTING' | system |
835 | ::: | 'delegate_prerouting' | internal | Internal chain to hold toplevel prerouting rules, dispatches traffic to the corresponding 'zone__name__prerouting' chains
836 | ::: | 'prerouting_rule' | user | Container chain for custom user prerouting rules (firewall.user)
837 | ::: | 'zone__name__prerouting' | internal | Per-zone container chains for DNAT (port forwarding) rules
838 | ::: | 'prerouting__name__rule' | user | Per-zone container chains for custom user prerouting rules (firewall.user)
839 | mangle | 'FORWARD' | system |
840 | ::: | 'mssfix' | internal | Internal chain to hold for TCPMSS rules (mtu_fix)
841 | filter | 'FORWARD' | system |
842 | ::: | 'delegate_forward' | internal | Internal chain to hold toplevel forward rules, dispatches traffic to the corresponding 'zone__name__forward' chains
843 | ::: | 'forwarding_rule' | user | Container chain for custom user forward rules (firewall.user)
844 | ::: | 'zone__name__forward' | internal | Per-zone container chains for output rules
845 | ::: | 'forwarding__name__rule' | user | Per-zone container chains for custom user forward rules (firewall.user)
846 | mangle | 'POSTROUTING' | system |
847 | nat | 'POSTROUTING' | system |
848 | ::: | 'delegate_postrouting' | internal | Internal chain to hold toplevel postrouting rules, dispatches traffic to the corresponding 'zone__name__postrouting' chains
849 | ::: | 'postrouting_rule' | user | Container chain for custom user postrouting rules (firewall.user)
850 | ::: | 'zone__name__postrouting' | internal | Per-zone container chains for postrouting rules (masq, snat)
851 | ::: | 'postrouting__name__rule' | user | Per-zone container chains for custom user postrouting rules (firewall.user)