OS-8361 IPD 4 (man page renumbering) tracking issue

Reviewed by: Brian Bennett <brian.bennett@joyent.com>
Approved by: Brian Bennett <brian.bennett@joyent.com>

1 files changed, 554 insertions, 0 deletions

diff --git a/usr/src/man/man8/ipf.8 b/usr/src/man/man8/ipf.8
new file mode 100644
index 0000000000..d2c04493b6
--- /dev/null
+++ b/usr/src/man/man8/ipf.8
@@ -0,0 +1,554 @@
+'\" 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) 2015, Joyent, Inc.
+.TH IPF 8 "May 17, 2020"
+.SH NAME
+ipf \- alter packet filtering lists for IP packet input and output
+.SH SYNOPSIS
+.nf
+\fBipf\fR [\fB-6AdDEGInoPRrsvVyzZ\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
+The \fBipf\fR utility is part of a suite of commands associated with the
+Solaris IP Filter feature. See \fBipfilter\fR(7).
+.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"
+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(7)) or become superuser.
+.RE
+.RS +4
+.TP
+2.
+Configure system and services' firewall policies. See \fBsvc.ipfd\fR(8) and
+\fBipf\fR(5).
+.RE
+.RS +4
+.TP
+3.
+(Optional) Create a network address translation (NAT) configuration file.
+See \fBipnat\fR(5).
+.RE
+.RS +4
+.TP
+4.
+(Optional) Create an address pool configuration file. See \fBippool\fR(5).
+.sp
+Create an \fBippool.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(8).
+.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(8).
+.RE
+.LP
+Note -
+.sp
+.RS 2
+If you reboot your system, the IPfilter configuration is automatically
+activated.
+.RE
+.SH OPTIONS
+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 conjunction
+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-G\fR\fR
+.ad
+.sp .6
+.RS 4n
+Make changes to the Global Zone-controlled ipfilter for the zone given as an
+argument. See the \fBZONES\fR section for more information.
+.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
+Each non-global zone has two ipfilter instances: the in-zone ipfilter, which
+can be controlled from both the zone itself and the global zone, and the
+Global Zone-controlled (GZ-controlled) instance, which can only be controlled
+from the Global Zone. The non-global zone is not able to observe or control
+the GZ-controlled ipfilter.
+
+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. If the \fB-G\fR option is specified with this argument, the
+Global Zone-controlled ipfilter is operated on. If \fB-G\fR is not specified,
+the in-zone ipfilter is operated on. Note that ipf differs from the other
+ipfilter tools in how the zone name is specified. It takes the zone name as the
+last argument, while all of the other tools take the zone name as an argument
+to the \fB-G\fR and \fB-z\fR options.
+
+.SH FILES
+.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(5).
+.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
+See \fBattributes\fR(7) 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
+.BR ipf (5),
+.BR ipnat (5),
+.BR ippool (5),
+.BR attributes (7),
+.BR ipfilter (7),
+.BR zones (7),
+.BR ipfstat (8),
+.BR ipmon (8),
+.BR ipnat (8),
+.BR ippool (8),
+.BR svc.ipfd (8),
+.BR svcadm (8)
+.sp
+.LP
+\fI\fR
+.SH DIAGNOSTICS
+Needs to be run as root for the packet filtering lists to actually be affected
+inside the kernel.