.\"	$OpenBSD: ipf.8,v 1.16 1999/10/12 05:05:00 ericj Exp $
.Dd July 7, 1999
.Dt IPF 8
.Os
.Sh NAME
.Nm ipf
.Nd "manage IP packet filtering and firewalling rules"
.Sh SYNOPSIS
.Nm ipf
.Op Fl AdDEInorsUvyzZ
.Op Fl l Ar category
.Op Fl F Ar list
.Op Fl F Ar table
.Op Fl f Ar filename
.Sh DESCRIPTION
The
.Nm
utility allows the insertion and removal of TCP/IP packet filtering and
firewalling rules.
.Nm
can be used for anything from very simple tasks (i.e., preventing a host from
replying to ping packets), to installing complex rulesets for a firewall to
to protect an entire network.
.Pp
Based on the specified rules,
.Nm
can explicitly deny/permit any inbound or outbound packet on any interface,
filter by IP networks or hosts, selectively filter packets by protocol and/or
protocol options, keep packet state information for TCP, UDP, and ICMP packet
flows, track fragment state information for IP packets (applying the same rules
to all fragments), and much more.
.Pp
.Nm
provides special capabilities for the most common Internet protocols. Both
TCP and UDP packets may be filtered by port number or port range, or ICMP
packets by type/code. Rules may filter packets on any arbitrary combination of
TCP flags, IP options, IP security classes, or Type of Service (TOS).
.Nm
also supports inverted host/net matching.
.Pp
To get started, follow these steps:
.Bl -enum -offset indent
.It
Edit
.Pa /etc/rc.conf
and set
.Cm ipfilter=YES .
This will cause
.Nm
to install the ruleset specified in
.Pa /etc/ipf.rules
each time the system is booted.
.It
Check that the kernel has been compiled with
.Cm option IPFILTER
(see
.Xr options 4 ) .
Refer to
.Xr afterboot 8
for further instructions on compiling a custom kernel.
.It
Edit
.Pa /etc/sysctl.conf
and set
.Cm net.inet.ip.forwarding=1
if this machine is to act as a firewall that also routes traffic or does
Network Address Translation (NAT).
.El
.Pp
Once these steps are complete a rule file may be created. A very
simple rule file might contain the following:
.Pp
.Dl pass in from any to any
.Dl pass out from any to any
.Pp
Here we're passing all packets and not doing any filtering. This is a
recommended starting point since it allows the current configuration to be
tested before formulating and installing a more restrictive ruleset. For
example, the following:
.Pp
.Dl "block in on we0 proto tcp from foo/32 to any"
.Pp
This would block all incoming TCP packets on interface
.Dq we0
from host
.Dq foo
to any internal destination. If this file is
.Pa /etc/ipf.rules
(the default location), the following command will flush the kernel's current
ruleset, install the new ruleset, and enable
.Pq Fl E
.Nm ipf :
.Pp
.Dl "ipf -Fa -f /etc/ipf.rules -E"
.Pp
(This is the exact command executed by the
.Pa /etc/rc
script at boot-time if
.Cm ipfilter=YES
in
.Pa /etc/rc.conf . )
.Pp
Please see
.Xr ipf 5
for a complete description of the
.Nm
rules file format and the example files in
.Pa /usr/share/ipf .
.Pp
In addition to
.Dq active
rulesets (those installed into the kernel which dictate the current filtering
policies),
.Nm
can maintain a separate
.Dq inactive
ruleset simultaneously. Inactive rulesets are useful for debugging pending or
proposed changes to the active ruleset (see
.Fl I
option below).
.Pp
The following options are available:
.Bl -tag -width Ds
.It Fl A
Apply changes to the active ruleset. This is the default.
.It Fl I
Apply changes to the inactive ruleset.
.It Fl D
Disable the filter (if enabled).
.It Fl E
Enable the filter (if disabled).
.It Fl F Ar list
Flush filter lists.
.Ar list
is one of
.Sq i
(input rules),
.Sq o
(output rules),
or
.Sq a
(all filtering rules).
.It Fl F Ar table
Flush entries from state tables. If
.Ar table
is
.Sq s ,
.Nm
removes any state information about connections that are non-fully established.
If
.Sq S ,
.Nm
removes the entire state table. Only one of the two options may be specified.
A fully established connection will appear in
.Ic ipfstat -s output
as
.Dq 4/4 ;
any deviations indicate a connection that has not completed the three-way
handshake.
.It Fl d
Enable debug mode. Causes a hexdump of filter rules to be generated as it
processes each one.
.It Fl f Ar filename
Read, parse, and process the
.Nm
rules contained in
.Ar filename .
If
.Ar filename
is
.Ql - ,
.Nm
reads from the standard input.
All valid rules are installed into the kernel's internal rule list using the
interface described by
.Xr ipf 4 .
Blank lines and lines beginning with
.Ql #
(comments) are ignored.
.It Fl l Ar category
Packet logging.
.Ar category
is one of
.Cm pass ,
.Cm block ,
or
.Cm nomatch .
Any packet which exits filtering and matches the set category is logged. This
is useful for causing all packets which don't match any of the loaded rules to
be logged.
.It Fl n
No change. Prevent
.Nm
from actually changing the state of the in-kernel filtering configuration.
.It Fl o
Force rules to be added/deleted to/from the output list rather than the
(default) input list.
.It Fl s
Swap the active and inactive rulesets.
.It Fl r
Remove matching filter rules rather than add them to the in-kernel lists.
.It Fl v
Enable verbose mode.
.Nm
will echo each of the successfully processed rules to the standard output. The
original rule and any error messages that result will be echoed to standard
error.
.It Fl y
Force
.Nm
to synchronize the IP filter's in-kernel network interface list with the
current system interface list. In particular, if an interface's IP address
changes (i.e., due to a DHCP operation),
.Nm
must be executed with this option.
.It Fl z
For each rule in the input file, display its statistics, then reset them to 0.
.It Fl Z
Globally reset all in-kernel filtering statistics to 0 (does not affect
fragment or state statistics).
.El
.Sh EXAMPLES
To flush all in-kernel filtering lists, install the ruleset contained in
.Pa /etc/ipf.rules
into the active list, and enable IP filtering:
.Pp
.Dl ipf -A -Fa -f /etc/ipf.rules -E
.Pp
It is advisable to work with an inactive filtering list before commiting new
rules to the active in-kernel filtering list. To load a ruleset into the
inactive list:
.Pp
.Dl ipf -I -Fa -f /etc/ipf.rules
.Pp
The verbose
.Pq Fl v
option is useful for verifying that rules are being processed as
expected and is often used in conjunction with the inactive
.Pq Fl I
ruleset:
.Pp
.Dl ipf -I -Fa -vf /etc/ipf.rules
.Pp
After the inactive ruleset has been tested and seems to be processed correctly,
use the
.Fl s
option to swap it with the active ruleset so that it represents the new
filtering policy for the system:
.Pp
.Dl ipf -s
.Pp
Consider a system manager who administers
.Nm
remotely and has made changes to the
.Pa /etc/ipf.rules
file on the remote system. The following command sequence is noteworthy:
.Pp
.Dl ipf -I -Fa -f /etc/ipf.rules
.Dl ipf -s; sleep 10; ipf -s
.Pp
The first command installs the new ruleset into the inactive filtering list.
The second command first swaps the inactive (new) rules with the active (old)
rules. After entering the second command, type some characters. If the
characters are echoed the new ruleset is possibly valid. If not, within 10
seconds the old ruleset will be re-installed. This trick is useful for
minimizing service disruptions.
.Sh NOTES
Rules are checked in the order they are specified. The last matching rule
wins, except when the
.Dq quick
keyword is present (see
.Xr ipf 5 ) .
.Pp
Note that
.Fl F Ns No a
does not affect the state table. To view the current state table, use the
.Xr ipfstat 8
program:
.Pp
.Dl ipfstat -s
.Pp
To remove all active state entries:
.Pp
.Dl ipf -FS
.Sh FILES
.Bl -tag -width /usr/share/ipf/example.* -compact
.It /usr/share/ipf/example.*
sample rule files
.It /dev/ipfauth
ipf authentication socket
.It /dev/ipl
ipf logging socket
.It /dev/ipstate
ipf state socket
.El
.Sh SEE ALSO
.Xr ipf 4 ,
.Xr ipl 4 ,
.Xr ipnat 4 ,
.Xr ipf 5 ,
.Xr ipfstat 8 ,
.Xr ipftest 8 ,
.Xr ipmon 8 ,
.Xr ipnat 8
.Pp
http://coombs.anu.edu.au/~avalon