path: root/usr/src/man/man1m/ipf.1m

'\" te
.\" To view license terms, attribution, and copyright for IP Filter, the default path is /usr/lib/ipf/IPFILTER.LICENCE. If the Solaris operating environment has been installed anywhere other than the default, modify the given path to access the file at the installed
.\" location.
.\" Portions Copyright (c) 2009, Sun Microsystems Inc. All Rights Reserved.
.\" Portions Copyright (c) 2012, Joyent, Inc. All Rights Reserved.
.TH IPF 1M "Nov 26, 2012"
.SH NAME
ipf \- alter packet filtering lists for IP packet input and output
.SH SYNOPSIS
.LP
.nf
\fBipf\fR [\fB-6AdDEInoPRrsvVyzZ\fR] [\fB-l\fR block | pass | nomatch]
     [\fB-T\fR \fIoptionlist\fR] [\fB-F\fR i | o | a | s | S] \fB-f\fR \fIfilename\fR
     [\fB-f\fR \fIfilename\fR...] [\fIzonename\fR]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBipf\fR utility is part of a suite of commands associated with the
Solaris IP Filter feature. See \fBipfilter\fR(5).
.sp
.LP
The \fBipf\fR utility opens the filenames listed (treating a hyphen (\fB-\fR)
as stdin) and parses the file for a set of rules which are to be added or
removed from the packet filter rule set.
.sp
.LP
If there are no parsing problems, each rule processed by \fBipf\fR is added to
the kernel's internal lists. Rules are added to the end of the internal lists,
matching the order in which they appear when given to \fBipf\fR.
.sp
.LP
\fBipf\fR's use is restricted through access to \fB/dev/ipauth\fR,
\fB/dev/ipl\fR, and \fB/dev/ipstate\fR. The default permissions of these files
require \fBipf\fR to be run as root for all operations.
.SS "Enabling Solaris IP Filter Feature"
.sp
.LP
Solaris IP Filter is installed with the Solaris operating system. However,
packet filtering is not enabled by default. Use the following procedure to
activate the Solaris IP Filter feature.
.RS +4
.TP
1.
Assume a role that includes the IP Filter Management rights profile (see
\fBrbac\fR(5)) or become superuser.
.RE
.RS +4
.TP
2.
Configure system and services' firewall policies. See \fBsvc.ipfd\fR(1M) and
\fBipf\fR(4).
.RE
.RS +4
.TP
3.
(Optional) Create a network address translation (NAT) configuration file.
See \fBipnat.conf\fR(4).
.RE
.RS +4
.TP
4.
(Optional) Create an address pool configuration file. See \fBippool\fR(4).
.sp
Create an \fBipool.conf\fR file if you want to refer to a group of addresses as
a single address pool. If you want the address pool configuration file to be
loaded at boot time, create a file called \fB/etc/ipf/ippool.conf\fR in which
to put the address pool. If you do not want the address pool configuration file
to be loaded at boot time, put the \fBippool.conf\fR file in a location other
than \fB/etc/ipf\fR and manually activate the rules.
.RE
.RS +4
.TP
5.
Enable Solaris IP Filter, as follows:
.sp
.in +2
.nf
# \fBsvcadm enable network/ipfilter\fR
.fi
.in -2
.sp

.RE
.sp
.LP
To re-enable packet filtering after it has been temporarily disabled either
reboot the machine or enter the following command:
.sp
.in +2
.nf
# \fBsvcadm enable network/ipfilter\fR
.fi
.in -2
.sp

.sp
.LP
\&...which essentially executes the following \fBipf\fR commands:
.RS +4
.TP
1.
Enable Solaris IP Filter:
.sp
.in +2
.nf
# \fBipf -E\fR
.fi
.in -2
.sp

.RE
.RS +4
.TP
2.
Load \fBippools\fR:
.sp
.in +2
.nf
\fB# ippool -f\fR \fI<ippool configuration file>\fR
.fi
.in -2
.sp

See \fBippool\fR(1M).
.RE
.RS +4
.TP
3.
(Optional) Activate packet filtering:
.sp
.in +2
.nf
\fBipf -f\fR \fI<ipf configuration file>\fR
.fi
.in -2
.sp

.RE
.RS +4
.TP
4.
(Optional) Activate NAT:
.sp
.in +2
.nf
\fBipnat -f\fR \fI<IPNAT configuration file>\fR
.fi
.in -2
.sp

See \fBipnat\fR(1M).
.RE
.LP
Note -
.sp
.RS 2
If you reboot your system, the IPfilter configuration is automatically
activated.
.RE
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-6\fR\fR
.ad
.sp .6
.RS 4n
This option is required to parse IPv6 rules and to have them loaded. Loading of
IPv6 rules is subject to change in the future.
.RE

.sp
.ne 2
.na
\fB\fB-A\fR\fR
.ad
.sp .6
.RS 4n
Set the list to make changes to the active list (default).
.RE

.sp
.ne 2
.na
\fB\fB-d\fR\fR
.ad
.sp .6
.RS 4n
Turn debug mode on. Causes a hex dump of filter rules to be generated as it
processes each one.
.RE

.sp
.ne 2
.na
\fB\fB-D\fR\fR
.ad
.sp .6
.RS 4n
Disable the filter (if enabled). Not effective for loadable kernel versions.
.RE

.sp
.ne 2
.na
\fB\fB-E\fR\fR
.ad
.sp .6
.RS 4n
Enable the filter (if disabled). Not effective for loadable kernel versions.
.RE

.sp
.ne 2
.na
\fB\fB-F\fR \fBi\fR | \fBo\fR | \fBa\fR\fR
.ad
.sp .6
.RS 4n
Specifies which filter list to flush. The parameter should either be \fBi\fR
(input), \fBo\fR (output) or \fBa\fR (remove all filter rules). Either a single
letter or an entire word starting with the appropriate letter can be used. This
option can be before or after any other, with the order on the command line
determining that used to execute options.
.RE

.sp
.ne 2
.na
\fB\fB-F\fR \fBs\fR | \fBS\fR\fR
.ad
.sp .6
.RS 4n
To flush entries from the state table, use the \fB-F\fR option in conjuction
with either \fBs\fR (removes state information about any non-fully established
connections) or \fBS\fR (deletes the entire state table). You can specify only
one of these two options. A fully established connection will show up in
\fBipfstat\fR \fB-s\fR output as \fB4/4\fR, with deviations either way
indicating the connection is not fully established.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR \fIfilename\fR\fR
.ad
.sp .6
.RS 4n
Specifies which files \fBipf\fR should use to get input from for modifying the
packet filter rule lists.
.RE

.sp
.ne 2
.na
\fB\fB-I\fR\fR
.ad
.sp .6
.RS 4n
Set the list to make changes to the inactive list.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR \fBpass\fR | \fBblock\fR | \fBnomatch\fR\fR
.ad
.sp .6
.RS 4n
Toggles default logging of packets. Valid arguments to this option are
\fBpass\fR, \fBblock\fR and \fBnomatch\fR. When an option is set, any packet
which exits filtering and matches the set category is logged. This is most
useful for causing all packets that do not match any of the loaded rules to be
logged.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.sp .6
.RS 4n
Prevents \fBipf\fR from making any ioctl calls or doing anything which would
alter the currently running kernel.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR\fR
.ad
.sp .6
.RS 4n
Force rules by default to be added/deleted to/from the output list, rather than
the (default) input list.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR\fR
.ad
.sp .6
.RS 4n
Add rules as temporary entries in the authentication rule table.
.RE

.sp
.ne 2
.na
\fB\fB-R\fR\fR
.ad
.sp .6
.RS 4n
Disable both IP address-to-hostname resolution and port number-to-service name
resolution.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.sp .6
.RS 4n
Remove matching filter rules rather than add them to the internal lists.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.sp .6
.RS 4n
Swap the currently active filter list to be an alternative list.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR \fIoptionlist\fR\fR
.ad
.sp .6
.RS 4n
Allows run-time changing of IPFilter kernel variables. To allow for changing,
some variables require IPFilter to be in a disabled state (\fB-D\fR), others do
not. The \fIoptionlist\fR parameter is a comma-separated list of tuning
commands. A tuning command is one of the following:
.sp
.ne 2
.na
\fB\fBlist\fR\fR
.ad
.sp .6
.RS 4n
Retrieve a list of all variables in the kernel, their maximum, minimum, and
current value.
.RE

.sp
.ne 2
.na
\fBsingle variable name\fR
.ad
.sp .6
.RS 4n
Retrieve its current value.
.RE

.sp
.ne 2
.na
\fBvariable name with a following assignment\fR
.ad
.sp .6
.RS 4n
To set a new value.
.RE

Examples follow:
.sp
.in +2
.nf
# Print out all IPFilter kernel tunable parameters
ipf -T list

# Display the current TCP idle timeout and then set it to 3600
ipf -D -T fr_tcpidletimeout,fr_tcpidletimeout=3600 -E

# Display current values for fr_pass and fr_chksrc, then set
# fr_chksrc to 1.
ipf -T fr_pass,fr_chksrc,fr_chksrc=1
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.sp .6
.RS 4n
Turn verbose mode on. Displays information relating to rule processing.
.RE

.sp
.ne 2
.na
\fB\fB-V\fR\fR
.ad
.sp .6
.RS 4n
Show version information. This will display the version information compiled
into the \fBipf\fR binary and retrieve it from the kernel code (if running or
present). If it is present in the kernel, information about its current state
will be displayed; for example, whether logging is active, default filtering,
and so forth).
.RE

.sp
.ne 2
.na
\fB\fB-y\fR\fR
.ad
.sp .6
.RS 4n
Manually resync the in-kernel interface list maintained by IP Filter with the
current interface status list.
.RE

.sp
.ne 2
.na
\fB\fB-z\fR\fR
.ad
.sp .6
.RS 4n
For each rule in the input file, reset the statistics for it to zero and
display the statistics prior to them being zeroed.
.RE

.sp
.ne 2
.na
\fB\fB-Z\fR\fR
.ad
.sp .6
.RS 4n
Zero global statistics held in the kernel for filtering only. This does not
affect fragment or state statistics.
.RE

.SH ZONES
.sp
.LP
ipf optionally takes a zone name as an argument, which will change the
ipfilter settings for that zone, rather than the current one. The zonename
option is only available in the Global Zone. Using it in any other zone will
return an error.

.SH FILES
.sp
.ne 2
.na
\fB\fB/dev/ipauth\fR\fR
.ad
.br
.na
\fB\fB/dev/ipl\fR\fR
.ad
.br
.na
\fB\fB/dev/ipstate\fR\fR
.ad
.sp .6
.RS 4n
Links to IP Filter pseudo devices.
.RE

.sp
.ne 2
.na
\fB\fB/etc/ipf/ipf.conf\fR\fR
.ad
.sp .6
.RS 4n
Location of \fBipf\fR startup configuration file. See \fBipf\fR(4).
.RE

.sp
.ne 2
.na
\fB\fB/usr/share/ipfilter/examples/\fR\fR
.ad
.sp .6
.RS 4n
Contains numerous IP Filter examples.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
.TE

.SH SEE ALSO
.sp
.LP
\fBipfstat\fR(1M), \fBipmon\fR(1M), \fBipnat\fR(1M), \fBippool\fR(1M),
\fBsvcadm\fR(1M), \fBsvc.ipfd\fR(1M), \fBipf\fR(4), \fBipnat.conf\fR(4),
\fBippool\fR(4), \fBattributes\fR(5), \fBipfilter\fR(5), \fBzones(5)\fR
.sp
.LP
\fI\fR
.SH DIAGNOSTICS
.sp
.LP
Needs to be run as root for the packet filtering lists to actually be affected
inside the kernel.