The firewall configuration located in /etc/config/firewall.

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 his own when needed.

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 that are not covered by the first two. 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.

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.

• firewall (or firewall3) and its dependencies (pre-installed)
  • iptables (pre-installed)
  • iptables-mod-? (optional), see OPKG Netfilter Packages.

Below is an overview of the section types that may be defined in the firewall configuration. 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. (The forwarding section is not strictly required when there are no more than two zones as the rule can then be set as the 'global default' for that zone.)

The defaults section declares global firewall settings which do not belong to specific zones. The following options are defined within this section:

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.

• INPUT rules for a zone describe what happens to traffic trying to reach the router itself through an interface in that zone.
• OUTPUT rules for a zone describe what happens to traffic originating from the router itself going through an interface in that zone.
• FORWARD rules for a zone describe what happens to traffic passing between different interfaces in that zone.

The options below are defined within zone sections:

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.

Below is a listing of allowed option within forwardings:

The iptables rules generated for this section rely on the state match which needs connection tracking to work. At least one of the src or dest zones needs to have connection tracking enabled through either the masq or the conntrack option.

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.

Redirects are also commonly known as "port forwarding", and "virtual servers".

Port ranges are specified as start:stop, for instance 6666:6670. This is similar to the iptables syntax.

The options below are valid for redirects:

On Attitude Adjustment, for NAT reflection to work, you must specify option dest lan in the redirect section (even though we're using a DNAT target).

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.

Up to Firewall v2, version 57 and below the rules behave like redirects and are tied to the given source zone and match incoming traffic occuring there.

In later versions the rules are defined as follows:

• If src and dest are given, the rule matches forwarded traffic
• If only src is given, the rule matches incoming traffic
• If only dest is given, the rule matches outgoing traffic
• If neither src nor dest are given, the rule defaults to an outgoing traffic rule

Port ranges are specified as start:stop, for instance 6666:6670. This is similar to the iptables syntax.

Valid options for this section are:

Available icmp type names for icmp_type:

It is possible to include custom firewall scripts by specifying one or more include sections in the firewall configuration.

There is only one possible parameter for includes:

Includes of type script may contain arbitary commands, for example advanced iptables rules or tc commands required for traffic shaping.

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.

The UCI firewall version 3 supports referencing or creating ipsets to simplify matching of huge address or port lists without the need for creating one rule per item to match,

The following options are defined for ipsets:

The table below outlines the possible combinations of storage methods and matched datatypes as well as the usable IP address family. The order of the datatype matches is significant.

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, e.g.

config rule
        option src wan
        option src_ip fdca:f00:ba3::/64
        option target ACCEPT

… is automatically treated as IPv6 only rule.

Similar, such a rule:

config rule
        option src wan
        option dest_ip 88.77.66.55
        option target REJECT

… is detected as IPv4 only.

Rules without IP addresses are automatically added to iptables and ip6tables, unless overridden by the family option. Redirect rules (portforwards) are always IPv4 (for now) since there is no IPv6 DNAT support (yet).

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:

config rule
        option src              wan
        option dest_port        22
        option target           ACCEPT
        option proto            tcp

This example enables machines on the internet to use SSH to access your router.

If you want to permit access to one host or subnet you should describe src_ip field:

config rule
        option src              wan
        option src_ip           '12.34.56.64/28'
        option dest_port        22
        option target           ACCEPT
        option proto            tcp

This example enables ssh access to host from entire 12.34.56.64/28 subnet.

This example forwards http (but not HTTPS) traffic to the webserver running on 192.168.1.10:

config redirect
        option src       wan
        option src_dport 80
        option proto     tcp
        option dest      lan
        option dest_ip   192.168.1.10

This other example forwards one arbitrary port that you define to a box running ssh.

config redirect
        option src       wan
        option src_dport 5555
        option proto     tcp
        option dest      lan
        option dest_ip   192.168.1.100
        option dest_port 22

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.

To do this, just add the `conntrack` option to the WAN zone:

config zone
        option name             wan
        list   network          'wan'
        list   network          'wan6'
        option input            REJECT
        option output           ACCEPT
        option forward          REJECT
        option masq             0
        option mtu_fix          1
        option conntrack        1

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:

config redirect
        option name     'icmp DNAT'
        option src      'wan'
        option src_dip   '1.2.3.4'
        option proto    'icmp'
        option dest     'dmz'
        option dest_ip  '192.168.1.79'
        option target   'DNAT'

config redirect
        option name     'icmp SNAT'
        option src      'dmz'
        option src_ip   '192.168.1.79'
        option src_dip  '1.2.3.4'
        option proto    'icmp'
        option dest     'wan'
        option target   'SNAT'

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 openwrt could wonder of adding additional forwarding rules but no, it is not needed. The forwarding rules are added by the firewall appliance itself.

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.

Suppose that you have two routers, connected each other through the lan zone (both have static ip and dhcp disabled), and only one of them is connected to the internet through the wan zone. In other words the situation is:

internet <----> wan (172.22.13.228) | router 1 | lan (192.168.1.254) <----> lan (192.168.1.1) | router 2 | wan (no connection)

If both routers have the default openwrt configuration (with the exceptions mentioned above), then a device on the lan side of the router 1 can communicate through the internet if it has the router 1 as gateway, this because the packet flow between devices is managed by routing. In our case the router 2 has no proper setup in terms of gateway, as the default openwrt configuration expects that a wan connection on the router 2 is provided.

Anyway suppose that on the router 1 we have the following rule:

config redirect
        option target 'DNAT'
        option src 'wan'
        option dest 'lan'
        option proto 'tcp'
        option src_dip '172.22.13.228'
        option src_dport '2023'
        option dest_ip '192.168.1.1'
        option dest_port '23'
        option name 'Telnet to new Router' 

This rule is redirecting the tcp packets on the port 2023 with destination the wan ip of the router 1 (172.22.13.228) towards the lan ip of the router 2. The router 2 cannot reply to those packets because we didn't adjust its routing table, that is we didn't specify that the gateway to reply to "wan" sources is the router 1. Indeed those redirected packets will have an source ip external from the (default) "lan" zone 192.168.1.0/24.

We can solve this activating the masquerading on the "lan" zone on the router 1, in this way.

config zone
        option name 'lan'
        option network 'lan'
        option input 'ACCEPT'
        option output 'ACCEPT'
        option forward 'REJECT'
        option masq '1'

This setup will provide the following effect (that is the effect intended by the masquerading): if a packet, belonging to a certain connection, is coming into the lan zone with a source ip belonging to another zone, keep track of the connection, taking note of the source ip of that connection, and modify the source ip with the ip of the router in the lan zone (that is: source_ip from a.b.c.d to 192.168.1.254).
Then deliver the packet to the intended destination (that is, 192.168.1.1, the router2). Afterwards, if a packet from 192.168.1.1 is coming back towards 192.168.1.254, belonging to the connection tracked before, changed back the destination ip (here is the second effect of the masquerading) with the source ip memorized before (that is, dest_ip from 192.168.1.254 to a.b.c.d ). In this way, for the point of view of the router 2, the router 2 just communicate with a device with an ip belonging to its "lan" zone , and therefore the default routing is working without problem.

At least one side effect of this setup is that every device in the lan zone of the router 1 cannot see any "wan" ip, and this could be not wanted for several reasons (one of which: if you setup a proper gateway, there is no need for this masquerading). But this was just a "special case" to expose in brief how the masquerading works and how it could be applied to zones that usually don't use it. An improvement of "masquerading only for a specific device in the zone" could be the following:

config zone
        option name 'lan'
        option network 'lan'
        option input 'ACCEPT'
        option output 'ACCEPT'
        option forward 'REJECT'
        option masq '1'
        option masq_dest '192.168.1.1/32'

This provide the masquerading feature only if the packets are send towards the destination 192.168.1.1/32 (this subnet should belong to the lan zone).

To open port 80 so that a local webserver at 2001:db8:42::1337 can be reached from the Internet:

config rule
        option src       wan
        option proto     tcp
        option dest      lan
        option dest_ip   2001:db8:42::1337
        option dest_port 80
        option family    ipv6
        option target    ACCEPT

To open SSH access to all IPv6 hosts in the local network:

config rule
        option src       wan
        option proto     tcp
        option dest      lan
        option dest_port 22
        option family    ipv6
        option target    ACCEPT

To open all TCP/UDP port between 1024 and 65535 towards the local IPv6 network:

config rule
        option src       wan
        option proto     tcpudp
        option dest      lan
        option dest_port 1024:65535
        option family    ipv6
        option target    ACCEPT

Source NAT changes an outgoing packet so that it looks as though the OpenWrt system is the source of the packet.

Define source NAT for UDP and TCP traffic directed to port 123 originating from the host with the IP address 10.55.34.85. The source address is rewritten to 63.240.161.99:

config redirect
        option src              lan
        option dest             wan
        option src_ip           10.55.34.85
        option src_dip          63.240.161.99
        option dest_port        123
        option target           SNAT

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.

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.

Most users won't want this. Its usage is similar to SNAT, but as the the destination IP address isn't changed, machines on the destination network need to be aware that they'll receive and answer requests from a public IP address that isn't necessarily theirs. Port forwarding in this fashion is typically used for load balancing.

config redirect
        option src              wan
        option src_dport        80
        option dest             lan
        option dest_port        80
        option proto            tcp

The following rule blocks all connection attempts to the specified host address.

config rule
        option src              lan
        option dest             wan
        option dest_ip          123.45.67.89
        option target           REJECT

The following rule blocks all connection attempts from the client to the Internet.

config rule
        option src              lan
        option dest             wan
        option src_mac          00:00:00:00:00:00
        option target           REJECT

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).
The package iptables-mod-ipopt must be installed to provide xt_time.

config rule
        option src              lan
        option dest             wan
        option src_ip           192.168.1.27
        option proto            all
        option extra            '-m time --weekdays Mon,Tue,Wed,Thu,Fri --timestart 21:00 --timestop 09:00'
        option target           REJECT

Using firewall v3 and later the example becomes:

config rule
        option src              lan
        option dest             wan
        option src_ip           192.168.1.27
        option proto            all
        option start_time       21:00
        option stop_time        09:00
        option weekdays         'mon tue wed thu fri'
        option target           REJECT

The example below creates a forward rule rejecting traffic from lan to wan on the ports 1000-1100.

config rule
        option src              lan
        option dest             wan
        option dest_port        1000-1100
        option proto            tcpudp
        option target           REJECT

The example below creates an output rule which prevents the router from pinging the address 8.8.8.8.

Only supported by the Firewall v2, version 58 and above

config rule
        option dest             wan
        option dest_ip          8.8.8.8
        option proto            icmp
        option target           REJECT

The rule below redirects all outgoing HTTP traffic from lan through a proxy server listening at port 3128 on the router itself.

config redirect
	option src              lan
	option proto            tcp
	option src_dport        80
	option dest_port        3128
	option dest_ip          192.168.1.1

The following rule redirects all outgoing HTTP traffic from lan through an external proxy at 192.168.1.100 listening on port 3128. It assumes the OpenWrt lan address to be 192.168.1.1 - this is needed to masquerade redirected traffic towards the proxy.

config redirect
        option src              lan
        option proto            tcp
        option src_ip           !192.168.1.100
        option src_dport        80
        option dest_ip          192.168.1.100
        option dest_port        3128
        option target           DNAT

config redirect
        option dest             lan
        option proto            tcp
        option src_dip          192.168.1.1
        option dest_ip          192.168.1.100
        option dest_port        3128
        option target           SNAT

The following rule redirects all WAN ports for all protocols to the internal host 192.168.1.2.

config redirect
	option src              wan
	option proto            all
	option dest_ip          192.168.1.2

This example enables proper forwarding of IPSec traffic through the wan.

# AH protocol
config rule
        option src              wan
        option dest             lan
        option proto            ah
        option target           ACCEPT

# ESP protocol
config rule
        option src              wan
        option dest             lan
        option proto            esp
        option target           ACCEPT

For some configurations you also have to open port 500/UDP.

# ISAKMP protocol
config rule
        option src              wan
        option dest             lan
        option proto            udp
        option src_port         500
        option dest_port        500
        option target           ACCEPT

Scenario: having one or more vpn tunnels using openvpn, with the need of defining a zone to forward the traffic between the vpn interfaces and the lan.

First list the interfaces in /etc/config/network, for example in the following way: (be careful on the limits of interface naming in terms of name length, read more)

config interface 'tun0'
	option ifname 'tun0'
	option proto 'none'

config interface 'tun1'
        option ifname 'tun1'
        option proto 'none'

Then create the zone in /etc/config/firewall, for example one zone for all the vpn interfaces.

config zone
        option name             vpn_tunnel
        list   network          'tun0'
	list   network          'tun1'
        option input            ACCEPT
          #the traffic towards the router from the interface will be accepted
          #(as for the lan communications)
        option output           ACCEPT
          #the traffic from the router to the interface will be accepted
        option forward          REJECT
          #traffic from this zone to other zones is normally rejected

Then we want to communicate with the "lan" zone, therefore we need forwardings in both ways (from lan to wan and viceversa)

config forwarding
        option src              lan
        option dest             vpn_tunnel
        #if a packet from lan wants to go to the vpn_tunnel zone
        #let it pass

config forwarding
        option src              vpn_tunnel
        option dest             lan
        #if a packet from vpn_tunnel wants to go to the lan zone
        #let it pass

This will create a lot of "automatic" iptables rules (because automatic scripting is not 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 less expert users.

In general remember that forwardings are relying how routing rules are defined, and afterwards which zones are defined on which interfaces.

This example declares a zone which maches any Linux network device whose name begins with "ppp".

Only supported by the Firewall v2, version 58 and above

config zone
        option name             example
        option input            ACCEPT
        option output           ACCEPT
        option forward          REJECT
        option device           'ppp+'

This example declares a zone which maches any TCP stream in the 10.21.0.0/16 subnet.

Only supported by the Firewall v2, version 58 and above

config zone
        option name             example
        option input            ACCEPT
        option output           ACCEPT
        option forward          REJECT
        option subnet           '10.21.0.0/16'
        option extra            '-p tcp'

This example declares a zone which maches any TCP stream from and to port 22.

Only supported by the Firewall v2, version 58 and above

config zone
        option name             example
        option input            ACCEPT
        option output           ACCEPT
        option forward          REJECT
        option extra_src        '-p tcp --sport 22'
        option extra_dest       '-p tcp --dport 22'

This example is for IPv6 tunnels only, and does not apply to native dual-stack interfaces.

Unverified Information! From my experience all you need to do is just add the interface name of your ipv6 tunnel to the wan zone of your firewall. This worked for me Remove the information below if this is the correct way to proceed.

Caveat: The above will only work if the tunnel is bringing IPv6 connectivity to the router itself. If you use the tunnel to route a prefix into your lan as well, you will additionally need to allow Inter-Zone Forwarding from wan to lan (not enabled by default). Creating a separate firewall zone (as described below) is a cleaner solution, though.

IPv6 packets are by default not forwarded from lan to your wan6 interface and vice versa. Make sure to add net.ipv6.conf.all.forwarding=1 in /etc/sysctl.conf to enable it permanently. Assuming your tunnel interface is called henet, add the following sections to /etc/config/firewall to create a new zone wan6, covering henet and allowing forwarding betweeen wan6 and lan in both directions:

config zone
	option name wan6
	option network henet
	option family ipv6
	option input ACCEPT
	option output ACCEPT
	option forward REJECT

config forwarding
	option dest lan
	option src wan6
#you don't need the below as you can a firewall rule to open the port that you need
config forwarding
	option dest wan6
	option src lan

The family option ensures that the zone and all associated entries (rule, forwarding and redirect sections) are only added to ip6tables but not iptables.

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.

config include
       option path /etc/firewall.user

config include
       option path /etc/firewall.vpn

The syntax for the includes is Linux standard, and therefore different from UCI's; its documentation can be found in netfilter.

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.

The firewall can be permananently disabled by executing /etc/init.d/firewall disable. Note that disable does not flush the rules, so it might be required to issue a stop before. Use enable to activate the firewall again.

Run /etc/init.d/firewall stop to flush all rules and set the policies to ACCEPT. To restart the firewall, run /etc/init.d/firewall start.

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.

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.

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.

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 hypothetical attacker. While dropping slightly increases security, it can also complicate the debugging of network issues or cause unwanted side-effects on client programs.

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).

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.

Also there is an interesting article which that claims dropping connections doesnt make you any safer - Drop versus Reject.

DROP

• less information is exposed
• less attack surface
• client software may not cope well with it (hangs until connection times out)
• may complicate network debugging (where was traffic dropped and why)

REJECT

• may expose information (like the ip at which traffic was actually blocked)
• client software can recover faster from rejected connection attempts
• network debugging easier (routing and firewall issues clearly distinguishable)

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.

NOTRACK will render certain ipables extensions unusable, for example the MASQUERADE target or the state match will not work!

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 .

Only available in Barrier Breaker. Revoked in Chaos Calmer RC1 and onwards due to various problems.

From r42048 to r44873, there was a new setting activated by default which causes the packets with the established state, completely bypass iptables filter table. This is to help with network performance and unless you need all packets to be counted by iptables filter or have some specific rules which would apply to already established connections, you should leave it active.

This behavior can be disabled by editing /etc/sysctl.conf :

net.netfilter.nf_conntrack_skip_filter=0

and then activating the new setting:

sysctl -p

or be temporarily turned off untill the next reboot by issuing :

sysctl -w net.netfilter.nf_conntrack_skip_filter=0

If you made a mistake you can delete a rule this way.

First, issue this command to find the index of the rule:

# iptables -L -t raw --line-numbers

Now to delete, e.g. the third rule from chain OUTPUT, execute:

# iptables -t raw -D OUTPUT 3

It is possible to observe the iptables commands generated by the firewall program, this is useful to track down iptables errors during firewall restarts or to verify the outcome of certain uci rules.

In order to see the rules as they're executed, run the fw command with the FW_TRACE environment variable set to 1 (one):

# FW_TRACE=1 fw reload

To direct the output to a file for later inspection, use the command below:

# FW_TRACE=1 fw reload 2>/tmp/iptables.log

If you are using the firewall3, you can enable debug mode using the -d switch:

# fw3 -d reload 2>/tmp/iptables.log

Furthermore it is also possible to print the to-be generated ruleset using the print command in conjunction with the -4 and -6 switches:

# fw3 -4 print > /tmp/ipv4.rules
# fw3 -6 print > /tmp/ipv6.rules

Could it be that the enable option is available for every section of the firewall file?