Firewall configuration /etc/config/firewall

OpenWrt's firewall management application firewall is mainly configured through /etc/config/firewall.

Most of the information in this wiki will focus on the configuration files and content. The LuCI and UCI interfaces are user abstractions, ultimately modifying the configuration files.

• The main firewall config file is /etc/config/firewall, and this is edited to modify the firewall settings
  • Create a backup of the firewall config prior to making changes
    • Should changes cause a loss-of-connectivity to the router, you will need to access it in failsafe mode to restore the backup
  • Once the settings are changed, and after double checking changes, reload the firewall via /etc/init.d/firewall reload
    • This is a simple shell script calling fw4 reload, and will print diagnostics to the console as it parses the new firewall configuration. Check for errors!
• Any line using # in the first character is not parsed
  • Comments are utilized to describe, explain, or quickly comment out, a section
• OpenWrt 22.03 and later ships with firewall4 by default, which uses nftables as a backend. It accepts the same UCI configuration syntax as fw3.
• The UCI firewall configuration in /etc/config/firewall covers a reasonable subset of NetFilter rules, but not all of them
  • To provide more functionality, include mechanisms are available.
    • You can either include a shell script with nftables commands, or include nftables snippets at different locations.
      • See Firewall examples for usage (might be outdated!)
• Whenever possible, use the firewall UCI config /etc/config/firewall
  • There are some scenarios where custom nftables rules are required
    • See Netfilter in OpenWrt for more information

LuCI is a good mechanism to view and modify the firewall configuration.

• It is located under Network → Firewall and maps closely to the configuration file sections.
• It takes a little longer to modify the firewall configuration, but has a higher level of organization than the config files.

Make changes and reload using the Save & Apply button.

• LuCI will remove all comment [#] lines from /etc/config/firewall!

UCI is a low-level abstraction to the configuration files and can be accessed remotely through SSH.

uci add firewall rule
uci set firewall.@rule[-1].name='Reject VPN to LAN traffic'
uci set firewall.@rule[-1].src='vpn'
uci set firewall.@rule[-1].dest='lan'
uci set firewall.@rule[-1].proto='all'
uci set firewall.@rule[-1].target='REJECT'
uci commit firewall
service firewall restart

These would be presumed to be the final rules (each proto creates a rule) in the VPN → LAN forward chain, as all packets from VPN will be rejected.

Show firewall configuration:

# uci show firewall
firewall.@rule[20]=rule
firewall.@rule[20].name='Reject VPN to LAN traffic'
firewall.@rule[20].src='vpn'
firewall.@rule[20].dest='lan'
firewall.@rule[20].proto='all'
firewall.@rule[20].target='REJECT'
...

UCI is useful to view the firewall configuration, but not to do any meaningful modifications for the following reasons:

• Essential prior knowledge of where a firewall rule needs to go into the rule array in order to make it work.
• uci does not recognize content within the /etc/firewall.user script.
• uci commit is necessary to save the changes, but still needs /etc/init.d/firewall reload to reload new tables.

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:

config defaults
	option	input			'ACCEPT'
	option	output			'ACCEPT'
	option	forward			'REJECT'
	option	custom_chains		'1'
	option	drop_invalid		'1'
	option	synflood_protect	'1'
	option	synflood_rate		'25/s'
	option	synflood_burst		'50'
	option	tcp_ecn			'1'
	option	tcp_syncookies		'1'
	option	tcp_window_scaling	'1'

A zone section groups one or more interfaces and serves as a source or destination for forwardings, rules and redirects.

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

• MASQUERADE (NAT) of outgoing traffic (WAN) is controlled on a per-zone basis 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 belonging in the same zone.

The forwarding sections control the traffic flow between zones.

config forwarding
	option	src		'lan'
	option	dest		'wan'

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

The 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 the masq option.

The rule section is used to define basic accept, drop, or reject rules to allow or restrict access to specific ports or hosts.

config rule
	option	name		'Reject LAN to WAN for custom IP'
	option	src		'lan'
	option	src_ip		'192.168.1.2'
	option	src_mac		'00:11:22:33:44:55'
	option	src_port	'80'
	option	dest		'wan'
	option	dest_ip		'194.25.2.129'
	option	dest_port	'120'
	option	proto		'tcp'
	option	target		'REJECT'

Below example is based on a inter zone forward case (where zone forward is set to reject) where you have one firewall zone called lan with two interfaces. In one interface you have a server with IP address 172.30.100.1 and the other interface is the default lan interface with 192.168.1.0/24 IP range. This configuration case will allow IPv4 tcp traffic from all IP addresses in the default lan interface to specifically connect only to the server IP address and to the server port 22.

config rule
	option name             'forward ssh to server'
	option family           'ipv4'
	option src              'lan'
	option src_ip           '192.168.1.0/24'
	option dest             'lan'
	option dest_ip          '172.30.100.1'
	option proto            'tcp'
	option dest_port        '22'
	option target           'ACCEPT'

• In OpenWrt firewall, the src and dest are tied to the target:
• 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
• IP address for src_ip and dest_ip can be a specific IP address or use CIDR notations to define a complete interface group of IP addresses as a source or destination, for instance 192.168.1.0/24.
• Port ranges are specified as start-stop, for instance 6666-6670.

Port forwardings (DNAT) are defined by redirect sections. Port Redirects are also commonly known as “port forwarding” or “virtual servers”.

• All incoming traffic on the specified source zone which matches the given rules will be directed to the specified internal host.
• Port ranges are specified as start-stop, for instance 6666-6670.

See also: IPv6 port forwarding

config redirect
	option	name		'DNAT WAN to LAN for SSH'
	option	src		'wan'
	option	src_dport	'19900'
	option	dest		'lan'
	option	dest_ip		'192.168.1.1'
	option	dest_port	'22'
	option	proto		'tcp'
	option	target		'DNAT'

If a src_dport is not included in the config section, packets matching the other config options, on any port, will be forwarded to the destination port specified in that config section. This could pose a security risk to the application running on the destination port the config section opens. One way to test for this issue, is to use Gibson Research Corporation's ShieldsUP! service, and probe the desired ports on your router. The response could be open, closed, or stealth (drop). In cases of open or closed ports, packets are reaching a destination host, and are sending ack/reply packets back. Whereas stealthed ports drop packets; from the perspective of the probing system (Gibson Research), that system cannot definitively know if those packets may, or may not be reaching the destination host.

Masquerade is the most common form of SNAT, changing the source of traffic to WAN to the router's public IP. SNAT can also be done manually:

config redirect
	option	name		'SNAT DMZ 192.168.1.250 to WAN 1.2.3.4 for ICMP'
	option	src		'dmz'
	option	src_ip		'192.168.1.250'
	option	src_dip		'1.2.3.4'
	option	dest		'wan'
	option	proto		'icmp'
	option	target		'SNAT'

See also: List of SNAT options @ OpenWrt SNAPSHOT

Name	Type	Required	Default	Description
name	string	no	string	Name of redirect
src	zone name	yes for DNAT target	(none)	Specifies the traffic source zone. Refers to one of the defined zone names. For typical port forwards this usually is wan.
src_ip	ip address	no	(none)	Match incoming traffic from the specified source IP address.
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.
src_mac	mac address	no	(none)	Match incoming traffic from the specified MAC address.
src_port	port or range	no	(none)	Match incoming traffic originating from the given source port or port range on the client host.
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.
proto	protocol name or number	no	tcp udp	Match incoming traffic using the given protocol. Can be one (or several when using list syntax) of tcp, udp, udplite, icmp, esp, ah, sctp, or all or it can be a numeric value, representing one of these protocols or a different one. A protocol name from /etc/protocols is also allowed. The number 0 is equivalent to all.
dest	zone name	yes for SNAT target	(none)	Specifies the traffic destination zone. Refers to one of the defined zone names. Irrelevant for DNAT target.
dest_ip	ip address	no	(none)	For DNAT, redirect matches incoming traffic to the specified internal host. For SNAT, it matches traffic directed at the given address. For DNAT, if the dest_ip is not specified, the rule is translated in a redirect rule, otherwise it is a DNAT rule.
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).
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. Unsupported in firewall4.
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.
start_date	date (yyyy-mm-dd)	no	(always)	If specifed, only match traffic after the given date (inclusive).
stop_date	date (yyyy-mm-dd)	no	(always)	If specified, only match traffic before the given date (inclusive).
start_time	time (hh:mm:ss)	no	(always)	If specified, only match traffic after the given time of day (inclusive).
stop_time	time (hh:mm:ss)	no	(always)	If specified, only match traffic before the given time of day (inclusive).
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.
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.
utc_time	boolean	no	0	Treat all given time values as UTC time instead of local time.
target	string	no	DNAT	NAT target (DNAT or SNAT) to use when generating the rule.
family	string	no	(auto)	Specifies the address family (ipv4, ipv6 or any) for which the rules are generated. If unspecified, matches the address family of other options in this section and defaults to ipv4.
reflection	boolean	no	1	Activate NAT reflection for this redirect - applicable to DNAT targets.
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.
reflection_zone	list of zone names	no	(none)	List of zones for which reflection should be enabled. Applicable to DNAT targets.
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.
limit_burst	integer	no	5	Maximum initial number of packets to match, allowing a short-term average above limit.
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.
enabled	string	no	1 or yes	Enable the redirect rule or not.
helper	cthelper	no

See also: IP set examples

fw4 supports referencing or creating IP sets to simplify matching of large address or port lists without the need for creating one rule per item to match. fw4 supports fewer options (see below).

prefix_suffix

The order of datatype matches is significant

fw4 has several ways to include custom firewall rules. In all cases, the custom rules need to be written in nftables-style.

One way is to include nftables snippets. There are several possible positions in the nftables structure.

For example, to add custom logging to the input_wan chain:

# /etc/config/firewall
config include
	option	type		'nftables'
	option	path		'/etc/my_custom_firewall_rule.nft'
	option	position	'chain-pre'
	option	chain		'input_wan'
 
# /etc/my_custom_firewall_rule.nft
tcp dport 0-1023 log prefix "Inbound WAN connection attempt to low TCP port: "

To add one or more custom chains:

config include
	option	type		'nftables'
	option	path		'/etc/my_custom_firewall_chain.nft'
	option	position	'table-post'

Supported options:

The possible positions for nftables snippets are:

Run fw4 print to understand the table / chain / rules structure.

Note that -pre can also be written as -prepend, and -post can also be written as -postpend or -append.

Custom rule inclusion through a shell script works similarly as fw3, but the script should use nftables. Option fw4_compatible is required when the path is /etc/firewall.user to indicate to fw4 that the script is compatible with nftables.

config include
	option	enabled		1
	option	type		'script'
	option	path		'/etc/firewall.user'
	option	fw4_compatible	1

Options family and reload from fw3 are no longer supported with fw4.

fw4 includes /etc/nftables.d/*.nft by default, at the beginning of the fw4 table (equivalent to the table-pre position)

It means that custom chains can be created by adding a file ending in .nft in the /etc/nftables.d/ directory.

For package authors that need custom firewall rules, it is possible to add nftables snippets in the following directories, depending on the desired position:

Snippets need to be readable files and their name must end with .nft.

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

config include
	option	path		'/etc/firewall.user'

The /etc/firewall.user script is empty by default.

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