.TH "UFW FRAMEWORK" "8" "" "Nov 2024" "Nov 2024"

.SH NAME
ufw\-framework \- using the ufw framework
.PP
.SH DESCRIPTION
\fBufw\fR provides both a command line interface and a framework for managing a
netfilter firewall. While the \fBufw\fR command provides an easy to use
interface for managing a firewall, the \fBufw\fR framework provides the
administrator methods to customize default behavior and add rules not
supported by the command line tool. In this way, \fBufw\fR can take full
advantage of Linux netfilter's power and flexibility.

.SH OVERVIEW
.PP
The framework provides boot time initialization, rules files for adding custom
rules, a method for loading netfilter modules, configuration of kernel
parameters and configuration of IPv6. The framework consists of the following
files:
.TP
#STATE_PREFIX#/ufw\-init
initialization script
.TP
#CONFIG_PREFIX#/ufw/before.init
initialization customization script run before ufw is initialized
.TP
#CONFIG_PREFIX#/ufw/after.init
initialization customization script run after ufw is initialized
.TP
#CONFIG_PREFIX#/ufw/before[6].rules
rules file containing rules evaluated before UI added rules
.TP
#CONFIG_PREFIX#/ufw/user[6].rules
rules file containing UI added rules (managed with the \fBufw\fR command)
.TP
#CONFIG_PREFIX#/ufw/after[6].rules
rules file containing rules evaluated after UI added rules
.TP
#CONFIG_PREFIX#/default/ufw
high level configuration
.TP
#CONFIG_PREFIX#/ufw/sysctl.conf
kernel network tunables
.TP
#CONFIG_PREFIX#/ufw/ufw.conf
additional high level configuration

.SH "BOOT INITIALIZATION"
.PP
\fBufw\fR is started on boot with #STATE_PREFIX#/ufw\-init. This script is a
standard SysV style initscript used by the \fBufw\fR command and should not be
modified. The #CONFIG_PREFIX#/before.init and #CONFIG_PREFIX#/after.init
scripts may be used to perform any additional firewall configuration that is
not yet supported in ufw itself and if they exist and are executable, ufw\-init
will execute these scripts. ufw\-init will exit with error if either of these
scripts exit with error. ufw\-init supports the following arguments:
.TP
start:
loads the firewall
.TP
stop:
unloads the firewall
.TP
restart:
reloads the firewall
.TP
force\-reload:
same as restart
.TP
status:
basic status of the firewall
.TP
force\-stop:
same as stop, except does not check if the firewall is already loaded
.TP
flush\-all:
flushes the built\-in chains, deletes all non\-built\-in chains and resets the
policy to ACCEPT
.PP
ufw\-init will call before.init and after.init with start, stop, status and
flush\-all, but typically, if used, these scripts need only implement start and
stop.
.PP
\fBufw\fR uses many user\-defined chains in addition to the built\-in iptables
chains. If MANAGE_BUILTINS in #CONFIG_PREFIX#/default/ufw is set to 'yes', on
stop and reload the built\-in chains are flushed. If it is set to 'no', on stop
and reload the \fBufw\fR secondary chains are removed and the \fBufw\fR primary
chains are flushed. In addition to flushing the \fBufw\fR specific chains, it
keeps the primary chains in the same order with respect to any other
user\-defined chains that may have been added. This allows for \fBufw\fR to
interoperate with other software that may manage their own firewall rules.
.PP
To ensure your firewall is loading on boot, you must integrate this script
into the boot process. Consult your distribution's documentation for the proper
way to modify your boot process if \fBufw\fR is not already integrated.

.SH "RULES FILES"
.PP
\fBufw\fR is in part a front\-end for \fBiptables\-restore\fR, with its rules
saved in #CONFIG_PREFIX#/ufw/before.rules, #CONFIG_PREFIX#/ufw/after.rules and
#CONFIG_PREFIX#/ufw/user.rules. Administrators can customize \fBbefore.rules\fR
and \fBafter.rules\fR as desired using the standard \fBiptables\-restore\fR
syntax. Rules are evaluated as follows: \fBbefore.rules\fR first,
\fBuser.rules\fR next, and \fBafter.rules\fR last. IPv6 rules are evaluated in
the same way, with the rules files named \fBbefore6.rules\fR, \fBuser6.rules\fR
and \fBafter6.rules\fR. Please note that \fBufw status\fR only shows rules
added with \fBufw\fR and not the rules found in the #CONFIG_PREFIX#/ufw rules
files.
.PP
\fBImportant\fR: \fBufw\fR only uses the *filter table by default. You
may add any other tables such as *nat, *raw and *mangle as desired. For each
table a corresponding COMMIT statement is required.
.PP
After modifying any of these files, you must reload \fBufw\fR for the rules to
take effect.  See the EXAMPLES section for common uses of these rules files.

.SH MODULES
.PP
Netfilter has many different connection tracking modules. These modules are
aware of the underlying protocol and allow the administrator to simplify his or
her rule sets. You can adjust which netfilter modules to load by adjusting
IPT_MODULES in #CONFIG_PREFIX#/default/ufw. Some popular modules to load are:

  nf_conntrack_ftp
  nf_nat_ftp
  nf_conntrack_irc
  nf_nat_irc
  nf_conntrack_netbios_ns
  nf_conntrack_pptp
  nf_conntrack_tftp
  nf_nat_tftp
  nf_conntrack_sane
.PP
Unconditional loading of connection tracking modules (nf_conntrack_*) in this
manner is deprecated. \fBufw\fR continues to support the functionality but new
configuration should only contain the specific modules required for the site.
For more information, see CONNECTION HELPERS.

.SH "KERNEL PARAMETERS"
.PP
\fBufw\fR will read in #CONFIG_PREFIX#/ufw/sysctl.conf on boot when enabled.
Please note that #CONFIG_PREFIX#/ufw/sysctl.conf overrides values in the
system systcl.conf (usually #CONFIG_PREFIX#/sysctl.conf). Administrators can
change the file used by modifying #CONFIG_PREFIX#/default/ufw.

.SH IPV6
.PP
IPv6 is enabled by default. When disabled, all incoming, outgoing and forwarded
packets are dropped, with the exception of traffic on the loopback interface.
To adjust this behavior, set IPV6 to 'yes' in #CONFIG_PREFIX#/default/ufw. See
the \fBufw\fR manual page for details.

.SH EXAMPLES
.PP
As mentioned, \fBufw\fR loads its rules files into the kernel by using the
\fBiptables\-restore\fR and \fBip6tables\-restore\fR commands. Users wanting
to add rules to the \fBufw\fR rules files manually must be familiar with
these as well as the \fBiptables\fR and \fBip6tables\fR commands. Below are
some common examples of using the \fBufw\fR rules files.  All examples assume
IPv4 only and that DEFAULT_FORWARD_POLICY in #CONFIG_PREFIX#/default/ufw is
set to DROP.
.SS
IP Masquerading
.PP
To allow IP masquerading for computers from the 10.0.0.0/8 network on eth1 to
share the single IP address on eth0:
.TP
Edit #CONFIG_PREFIX#/ufw/sysctl.conf to have:
 net.ipv4.ip_forward=1
.TP
Add to the end of #CONFIG_PREFIX#/ufw/before.rules, after the *filter section:
 *nat
 :POSTROUTING ACCEPT [0:0]
 \-A POSTROUTING \-s 10.0.0.0/8 \-o eth0 \-j MASQUERADE
 COMMIT
.TP
If your firewall is using IPv6 tunnels or 6to4 and is also doing NAT, then you should not usually masquerade protocol '41' (ipv6) packets. For example, instead of the above, #CONFIG_PREFIX#/ufw/before.rules can be adjusted to have:
 *nat
 :POSTROUTING ACCEPT [0:0]
 \-A POSTROUTING \-s 10.0.0.0/8 ! \-\-protocol 41 \-o eth0 \-j MASQUERADE
 COMMIT
.TP
Add the \fBufw route\fR to allow the traffic:
 ufw route allow in on eth1 out on eth0 from 10.0.0.0/8
.SS
Port Redirections
.PP
To forward tcp port 80 on eth0 to go to the webserver at 10.0.0.2:
.TP
Edit #CONFIG_PREFIX#/ufw/sysctl.conf to have:
 net.ipv4.ip_forward=1
.TP
Add to the end of #CONFIG_PREFIX#/ufw/before.rules, after the *filter section:
 *nat
 :PREROUTING ACCEPT [0:0]
 \-A PREROUTING \-p tcp \-i eth0 \-\-dport 80 \-j DNAT \\
   \-\-to\-destination 10.0.0.2:80
 COMMIT
.TP
Add the \fBufw route\fR rule to allow the traffic:
 ufw route allow in on eth0 to 10.0.0.2 port 80 proto tcp

.SS
Egress filtering
.PP
To block RFC1918 addresses going out of eth0:
.TP
Add the \fBufw route\fR rules to reject the traffic:
 ufw route reject out on eth0 to 10.0.0.0/8
 ufw route reject out on eth0 to 172.16.0.0/12
 ufw route reject out on eth0 to 192.168.0.0/16

.SS
Full example
.PP
This example combines the other examples and demonstrates a simple routing
firewall. \fBWarning\fR: this setup is only an example to demonstrate
the functionality of the \fBufw\fR framework in a concise and simple manner
and should not be used in production without understanding what each part
does and does not do. Your firewall will undoubtedly want to be less open.
.PP
This router/firewall has two interfaces: eth0 (Internet facing) and eth1
(internal LAN). Internal clients have addresses on the 10.0.0.0/8 network
and should be able to connect to anywhere on the Internet. Connections
to port 80 from the Internet should be forwarded to 10.0.0.2. Access to
ssh port 22 from the administrative workstation (10.0.0.100) to this machine
should be allowed. Also make sure no internal traffic goes to the Internet.
.TP
Edit #CONFIG_PREFIX#/ufw/sysctl.conf to have:
  net.ipv4.ip_forward=1
.TP
Add to the end of #CONFIG_PREFIX#/ufw/before.rules, after the *filter section:
 *nat
 :PREROUTING ACCEPT [0:0]
 :POSTROUTING ACCEPT [0:0]
 \-A PREROUTING \-p tcp \-i eth0 \-\-dport 80 \-j DNAT \\
   \-\-to\-destination 10.0.0.2:80
 \-A POSTROUTING \-s 10.0.0.0/8 \-o eth0 \-j MASQUERADE
 COMMIT
.TP
Add the necessary \fBufw\fR rules:
 ufw route reject out on eth0 to 10.0.0.0/8
 ufw route reject out on eth0 to 172.16.0.0/12
 ufw route reject out on eth0 to 192.168.0.0/16
 ufw route allow in on eth1 out on eth0 from 10.0.0.0/8
 ufw route allow in on eth0 to 10.0.0.2 port 80 proto tcp
 ufw allow in on eth1 from 10.0.0.100 to any port 22 proto tcp

.SH "CONNECTION HELPERS"
.PP
Various protocols require the use of netfilter connection tracking helpers to
group related packets into RELATED flows to make rulesets clearer and more
precise. For example, with a couple of kernel modules and a couple of rules, a
ruleset could simply allow a connection to FTP port 21, then the kernel would
examine the traffic and mark the other FTP data packets as RELATED to the
initial connection.
.PP
When the helpers were first introduced, one could only configure the modules as
part of module load (eg, if your FTP server listened on a different port than
21, you'd have to load the nf_conntrack_ftp module specifying the correct
port). Over time it was understood that unconditionally using connection
helpers could lead to abuse, in part because some protocols allow user
specified data that would allow traversing the firewall in undesired ways. As
of kernel 4.7, automatic conntrack helper assignment (ie, handling packets for
a given port and all IP addresses) is disabled (the old behavior can be
restored by setting net/netfilter/nf_conntrack_helper=1 in
#CONFIG_PREFIX#/ufw/sysctl.conf). Firewalls should now instead use the CT
target to associate traffic with a particular helper and then set RELATED rules
to use the helper. This allows sites to tailor the use of helpers and help
avoid abuse.
.PP
In general, to use helpers securely, the following needs to happen:
.IP 1.
net/netfilter/nf_conntrack_helper should be set to 0 (default)
.IP 2.
create a rule for the start of a connection (eg for FTP, port 21)
.IP 3.
create a helper rule to associate the helper with this connection
.IP 4.
create a helper rule to associate a RELATED flow with this connection
.IP 5.
if needed, add the corresponding nf_conntrack_* module to IPT_MODULES
.IP 6.
optionally add the corresponding nf_nat_* module to IPT_MODULES
.PP
In general it is desirable to make connection helper rules as specific as
possible and ensure anti\-spoofing is correctly setup for your site to avoid
security issues in your ruleset. For more information, see ANTI\-SPOOFING,
above, and <https://home.regit.org/netfilter-en/secure-use-of-helpers/>.
.PP
Currently helper rules must be managed in via the RULES FILES. A future version
of \fBufw\fR will introduce syntax for working with helper rules.

.SH NOTES
.PP
When using ufw with libvirt and bridging, packets may be blocked. The
libvirt team recommends that the following sysctl's be set to disable netfilter
on the bridge:

  net.bridge.bridge-nf-call-ip6tables = 0
  net.bridge.bridge-nf-call-iptables = 0
  net.bridge.bridge-nf-call-arptables = 0

Note that the bridge module must be loaded in to the kernel before these values
are set. One way to ensure this works properly with ufw is to add 'bridge' to
IPT_MODULES in #CONFIG_PREFIX#/default/ufw, and then add the above rules to
#CONFIG_PREFIX#/ufw/sysctl.conf.

Alternatively to disabling netfilter on the bridge, you can configure iptables
to allow all traffic to be forwarded across the bridge. Eg, add to
#CONFIG_PREFIX#/ufw/before.rules within the *filter section:

  -I FORWARD -m physdev --physdev-is-bridged -j ACCEPT

.PP
When using ufw with LXD or Incus, additional rules for the bridge (by default,
lxdbr0) are needed for the guests for DHCP, DNS and outbound connections. Eg:

  ufw allow in on lxdbr0 to any port 67 proto udp
  ufw allow in on lxdbr0 to any port 53
  ufw route allow in on lxdbr0 from XXX.YYY.ZZZ.0/24

The first two rules limit access from the guests to the host to only DHCP and
DNS while the 3rd rule allows access from the guests on the XXX.YYY.ZZZ.0/24
subnet (as configured by LXD or Incus) to the world. Adjust as necessary for
your environment (site requirements, name of the bridge, bridge network, etc).

To allow traffic from the outside to your guests, then additional rules are
needed. Eg, to allow HTTPS to the 10.210.254.123 guest:

  ufw route allow out on lxdbr0 to 10.210.254.123 port 443 proto tcp

Note: when thinking of 'in on lxdbr0' vs 'out on lxdbr0', think of the traffic
in the context of the host and the guest: if the traffic is from the guest into
or through the host, then an 'in on lxdbr0' should be used; if the traffic is
from anywhere out to the guest, then an 'out on lxdbr0' should be used. As
always, additional rules may be needed depending on your default policy.

.SH SEE ALSO
.PP
\fBufw\fR(8), \fBiptables\fR(8), \fBip6tables\fR(8), \fBiptables\-restore\fR(8), \fBip6tables\-restore\fR(8), \fBsysctl\fR(8), \fBsysctl.conf\fR(5)

.SH AUTHOR
.PP
ufw is Copyright 2008-2024, Canonical Ltd.