svn commit: r269898 - projects/ipfw/sbin/ipfw
Alexander V. Chernikov
melifaro at FreeBSD.org
Wed Aug 13 00:19:19 UTC 2014
Author: melifaro
Date: Wed Aug 13 00:19:18 2014
New Revision: 269898
URL: http://svnweb.freebsd.org/changeset/base/269898
Log:
Document most of the changes that have happened.
Modified:
projects/ipfw/sbin/ipfw/ipfw.8
Modified: projects/ipfw/sbin/ipfw/ipfw.8
==============================================================================
--- projects/ipfw/sbin/ipfw/ipfw.8 Wed Aug 13 00:18:16 2014 (r269897)
+++ projects/ipfw/sbin/ipfw/ipfw.8 Wed Aug 13 00:19:18 2014 (r269898)
@@ -1,7 +1,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd May 31, 2014
+.Dd Aug 13, 2014
.Dt IPFW 8
.Os
.Sh NAME
@@ -48,17 +48,43 @@ in-kernel NAT.
.Brq Cm firewall | altq | one_pass | debug | verbose | dyn_keepalive
.Ss LOOKUP TABLES
.Nm
-.Cm table Ar number Cm add Ar addr Ns Oo / Ns Ar masklen Oc Op Ar value
+.Cm table Ar name Cm create Ar create-options
.Nm
-.Cm table Ar number Cm delete Ar addr Ns Op / Ns Ar masklen
+.Cm table Ar name Cm destroy
.Nm
-.Cm table
-.Brq Ar number | all
-.Cm flush
+.Cm table Ar name Cm modify Ar modify-options
+.Nm
+.Cm table Ar name Cm swap Ar name
+.Nm
+.Cm table Ar name Cm add Ar table-key Op Ar value
+.Nm
+.Cm table Ar name Cm add Op Ar table-key Ar value ...
+.Nm
+.Cm table Ar name Cm atomic add Op Ar table-key Ar value ...
+.Nm
+.Cm table Ar name Cm delete Op Ar table-key ...
+.Nm
+.Cm table Ar name Cm lookup Ar addr
+.Nm
+.Cm table Ar name Cm lock
+.Nm
+.Cm table Ar name Cm unlock
.Nm
.Cm table
-.Brq Ar number | all
+.Brq Ar name | all
.Cm list
+.Nm
+.Cm table
+.Brq Ar name | all
+.Cm info
+.Nm
+.Cm table
+.Brq Ar name | all
+.Cm detail
+.Nm
+.Cm table
+.Brq Ar name | all
+.Cm flush
.Ss DUMMYNET CONFIGURATION (TRAFFIC SHAPER AND PACKET SCHEDULER)
.Nm
.Brq Cm pipe | queue | sched
@@ -822,10 +848,11 @@ It is possible to use the
.Cm tablearg
keyword with a skipto for a
.Em computed
-skipto, but care should be used, as no destination caching
-is possible in this case so the rules are always walked to find it,
-starting from the
-.Cm skipto .
+skipto. Skipto may work either in O(log(N)) or in O(1) depending
+on amount of memory and/or sysctl variables.
+See the
+.Sx SYSCTL VARIABLES
+section for more details.
.It Cm call Ar number | tablearg
The current rule number is saved in the internal stack and
ruleset processing continues with the first rule numbered
@@ -1152,7 +1179,7 @@ with multiple addresses) is provided for
its use is discouraged.
.It Ar addr : Oo Cm not Oc Bro
.Cm any | me | me6 |
-.Cm table Ns Pq Ar number Ns Op , Ns Ar value
+.Cm table Ns Pq Ar name Ns Op , Ns Ar value
.Ar | addr-list | addr-set
.Brc
.Bl -tag -width indent
@@ -1164,8 +1191,8 @@ matches any IP address configured on an
matches any IPv6 address configured on an interface in the system.
The address list is evaluated at the time the packet is
analysed.
-.It Cm table Ns Pq Ar number Ns Op , Ns Ar value
-Matches any IPv4 address for which an entry exists in the lookup table
+.It Cm table Ns Pq Ar name Ns Op , Ns Ar value
+Matches any IPv4 or IPv6 address for which an entry exists in the lookup table
.Ar number .
If an optional 32-bit unsigned
.Ar value
@@ -1359,6 +1386,19 @@ and IPsec encapsulated security payload
.It Cm fib Ar fibnum
Matches a packet that has been tagged to use
the given FIB (routing table) number.
+.It Cm flow Ar table Ns Pq Ar name Ns Op , Ns Ar value
+Search for the flow entry in lookup table
+.Ar name .
+If not found, the match fails.
+Otherwise, the match succeeds and
+.Cm tablearg
+is set to the value extracted from the table.
+.Pp
+This option can be useful to quickly dispatch traffic based on
+certain packet fields.
+See the
+.Sx LOOKUP TABLES
+section below for more information on lookup tables.
.It Cm flow-id Ar labels
Matches IPv6 packets containing any of the flow labels given in
.Ar labels .
@@ -1550,9 +1590,9 @@ of source and destination addresses and
specified.
Currently,
only IPv4 flows are supported.
-.It Cm lookup Bro Cm dst-ip | dst-port | src-ip | src-port | uid | jail Brc Ar N
+.It Cm lookup Bro Cm dst-ip | dst-port | src-ip | src-port | uid | jail Brc Ar name
Search an entry in lookup table
-.Ar N
+.Ar name
that matches the field specified as argument.
If not found, the match fails.
Otherwise, the match succeeds and
@@ -1617,13 +1657,19 @@ and they are always printed as hexadecim
option is used, in which case symbolic resolution will be attempted).
.It Cm proto Ar protocol
Matches packets with the corresponding IP protocol.
-.It Cm recv | xmit | via Brq Ar ifX | Ar if Ns Cm * | Ar table Ns Pq Ar number Ns Op , Ns Ar value | Ar ipno | Ar any
+.It Cm recv | xmit | via Brq Ar ifX | Ar if Ns Cm * | Ar table Ns Po Ar name Ns Oo , Ns Ar value Oc Pc | Ar ipno | Ar any
Matches packets received, transmitted or going through,
respectively, the interface specified by exact name
.Po Ar ifX Pc ,
by device name
.Po Ar if* Pc ,
by IP address, or through some interface.
+Table
+.Ar name
+may be used to match interface by its kernel ifindex.
+See the
+.Sx LOOKUP TABLES
+section below for more information on lookup tables.
.Pp
The
.Cm via
@@ -1818,15 +1864,24 @@ connected networks instead of all source
.Sh LOOKUP TABLES
Lookup tables are useful to handle large sparse sets of
addresses or other search keys (e.g., ports, jail IDs, interface names).
-In the rest of this section we will use the term ``address''.
-There may be up to 65535 different lookup tables, numbered 0 to 65534.
+In the rest of this section we will use the term ``key''.
+Table name needs to match the following spec:
+.Ar table-name .
+There may be up to 65535 different lookup tables.
.Pp
+The following table types are supported:
+.Bl -tag -width indent
+.It Ar table-type : Ar cidr | iface | number | flow
+.It Ar table-key : Ar addr Ns Oo / Ns Ar masklen Oc | iface-name | number | flow-spec
+.It Ar flow-spec : Ar flow-field Ns Op , Ns Ar flow-spec
+.It Ar flow-field : src-ip | proto | src-port | dst-ip | dst-port
+.It Cm cidr
+matches IPv4 or IPv6 address.
Each entry is represented by an
.Ar addr Ns Op / Ns Ar masklen
and will match all addresses with base
.Ar addr
-(specified as an IPv4/IPv6 address, a hostname or an unsigned integer)
-and mask width of
+(specified as an IPv4/IPv6 address, or a hostname) and mask width of
.Ar masklen
bits.
If
@@ -1834,29 +1889,159 @@ If
is not specified, it defaults to 32 for IPv4 and 128 for IPv6.
When looking up an IP address in a table, the most specific
entry will match.
-Associated with each entry is a 32-bit unsigned
-.Ar value ,
-which can optionally be checked by a rule matching code.
-When adding an entry, if
-.Ar value
-is not specified, it defaults to 0.
+.It Cm iface
+matches interface names.
+Each entry is represented by string treated as interface name.
+Wildcards are not supported.
+.It Cm number
+maches protocol ports, uids/gids or jail IDs.
+Each entry is represented by 32-bit unsigned integer.
+Ranges are not supported.
+.It Cm flow
+Matches packet fields specified by
+.Ar flow
+type suboptions with table entries.
+.El
.Pp
-An entry can be added to a table
-.Pq Cm add ,
-or removed from a table
-.Pq Cm delete .
-A table can be examined
-.Pq Cm list
-or flushed
-.Pq Cm flush .
+The following value format types are supported:
+.Bl -tag -width indent
+.It Ar value-ftype : Ar number | ip
+.It Cm number
+Default for
+.Ar number
+value type.
+Shows values as unsigned integer.
+.It Cm ip
+Show values as IPv4 addresses.
+.El
.Pp
-Internally, each table is stored in a Radix tree, the same way as
-the routing table (see
-.Xr route 4 ) .
+Tables require explicit creation via
+.Cm create
+before use.
+.Pp
+The following creation options are supported:
+.Bl -tag -width indent
+.It Ar create-options : Ar create-option | create-options
+.It Ar create-option : Cm type Ar table-type | Cm ftype Ar value-ftype | Cm algo Ar algo-desc |
+.Cm limit Ar number | Cm locked
+.It Cm type
+Table key type.
+.It Cm ftype
+Table value format type.
+Affects userland formatting only.
+.It Cm algo
+Table algorithm to use (see below).
+.It Cm limit
+Maximum number of items that may be inserted into table.
+.It Cm locked
+Restrict any table modifications.
+.El
+.Pp
+Some of these options may be modified later via
+.Cm modify
+keyword.
+The following options can be changed:
+.Bl -tag -width indent
+.It Ar modify-options : Ar modify-option | modify-options
+.It Ar modify-option : Cm ftype Ar value-ftype | Cm limit Ar number
+.It Cm ftype
+Set table value format type.
+Affects userland formatting only.
+.It Cm limit
+Alter maximum number of items that may be inserted into table.
+.El
+.Pp
+Additionally, table can be locked or unlocked using
+.Cm lock
+or
+.Cm unlock
+commands.
+.Pp
+Tables of the same
+.Ar type
+and
+.Ar valtype
+can be swapped with each other using
+.Cm swap Ar name
+command.
+Swap may fail if tables limits are set and data exchange
+would result in limits hit.
+Operation is performed atomically.
+.Pp
+One or more entries can be added to a table at once using
+.Cm add
+command.
+Addition of all items are performed atomically.
+By default, error in addition of one entry does not influence
+addition of other entries. However, non-zero error code is returned
+in that case.
+Special
+.Cm atomic
+keyword may be specified before
+.Cm add
+to indicate all-or-none add request.
+.Pp
+One or more entries can be removed from a table at once using
+.Cm delete
+command.
+By default, error in removal of one entry does not influence
+removing of other entries. However, non-zero error code is returned
+in that case.
+.Pp
+It may be possible to check what entry will be found on particular
+.Ar table-key
+using
+.Cm lookup
+.Ae table-key
+command.
+This functionality is optional and may be unsupported in some algorithms.
.Pp
-Lookup tables currently support only ports, jail IDs, IPv4/IPv6 addresses
-and interface names.
-Wildcards is not supported for interface names.
+The following operations can be performed on
+.Ar one
+or
+.Cm all
+tables:
+.Bl -tag -width indent
+.It Cm list
+List all entries.
+.It Cm flush
+Removes all entries.
+.It Cm info
+Shows generic table information.
+.It Cm detail
+Shows generic table information and algo-specific data.
+.El
+.Pp
+The following lookup algorithms are supported:
+.Bl -tag -width indent
+.It Ar algo-desc : algo-name | "algo-name algo-data"
+.It Ar algo-name: Ar cidr:radix | cidr:hash | iface:arrray | number:array | flow:hash
+.It Cm cidr:radix
+Separate Radix trees for IPv4 and IPv6, the same way as the routing table (see
+.Xr route 4 ) .
+Default choice for
+.Ar
+cidr
+type.
+.It Cm cidr:hash
+Separate auto-growing hashes for IPv4 and IPv6.
+Accepts entries with the same mask length specified initially via
+.Cm "cidr:hash masks=/v4,/v6"
+algorithm creation options.
+Assume /32 and /128 masks by default.
+Search removes host bits (according to mask) from supplied address and checks
+resulting key in appropriate hash.
+Mostly optimized for /64 and byte-ranged IPv6 masks.
+.It Cm iface:arrray
+Array storing sorted indexes for entries which are presented in the system.
+Optimized for very fast lookup.
+.It Cm number:array
+Array storing sorted u32 numbers.
+.It Cm flow:hash
+Auto-growing hash storing flow entries.
+Search calculates hash on required packet fields and searches for matching
+entries in selected bucket.
+.El
.Pp
The
.Cm tablearg
@@ -1865,6 +2050,14 @@ the argument for a rule action, action p
This can significantly reduce number of rules in some configurations.
If two tables are used in a rule, the result of the second (destination)
is used.
+.Pp
+The following value types are supported:
+.Bl -tag -width indent
+.It Ar value-type : Ar number
+.It Cm number
+Default value type.
+If value is not specified, defaults to 0.
+.El
The
.Cm tablearg
argument can be used with the following actions:
@@ -3221,30 +3414,42 @@ Then we classify traffic using a single
.Dl "ipfw pipe 1 config bw 1000Kbyte/s"
.Dl "ipfw pipe 4 config bw 4000Kbyte/s"
.Dl "..."
-.Dl "ipfw table 1 add 192.168.2.0/24 1"
-.Dl "ipfw table 1 add 192.168.0.0/27 4"
-.Dl "ipfw table 1 add 192.168.0.2 1"
+.Dl "ipfw table T1 create type cidr"
+.Dl "ipfw table T1 add 192.168.2.0/24 1"
+.Dl "ipfw table T1 add 192.168.0.0/27 4"
+.Dl "ipfw table T1 add 192.168.0.2 1"
.Dl "..."
-.Dl "ipfw add pipe tablearg ip from table(1) to any"
+.Dl "ipfw add pipe tablearg ip from 'table(T1)' to any"
.Pp
Using the
.Cm fwd
action, the table entries may include hostnames and IP addresses.
.Pp
-.Dl "ipfw table 1 add 192.168.2.0/24 10.23.2.1"
-.Dl "ipfw table 1 add 192.168.0.0/27 router1.dmz"
+.Dl "ipfw table T2 create type cidr ftype ip"
+.Dl "ipfw table T2 add 192.168.2.0/24 10.23.2.1"
+.Dl "ipfw table T21 add 192.168.0.0/27 router1.dmz"
.Dl "..."
.Dl "ipfw add 100 fwd tablearg ip from any to table(1)"
.Pp
In the following example per-interface firewall is created:
.Pp
-.Dl "ipfw table 10 add vlan20 12000"
-.Dl "ipfw table 10 add vlan30 13000"
-.Dl "ipfw table 20 add vlan20 22000"
-.Dl "ipfw table 20 add vlan30 23000"
+.Dl "ipfw table IN create type iface"
+.Dl "ipfw table IN add vlan20 12000"
+.Dl "ipfw table IN add vlan30 13000"
+.Dl "ipfw table OUT create type iface"
+.Dl "ipfw table OUT add vlan20 22000"
+.Dl "ipfw table OUT add vlan30 23000"
+.Dl ".."
+.Dl "ipfw add 100 ipfw skipto tablearg ip from any to any recv 'table(IN)' in"
+.Dl "ipfw add 200 ipfw skipto tablearg ip from any to any xmit 'table(OUT)' out"
+.Pp
+The following example illustrate usage of flow tables:
+.Pp
+.Dl "ipfw table fl create type flow:flow:src-ip,proto,dst-ip,dst-port"
+.Dl "ipfw table fl add 2a02:6b8:77::88,tcp,2a02:6b8:77::99,80 11"
+.Dl "ipfw table fl add 10.0.0.1,udp,10.0.0.2,53 12"
.Dl ".."
-.Dl "ipfw add 100 ipfw skipto tablearg ip from any to any recv 'table(10)' in"
-.Dl "ipfw add 200 ipfw skipto tablearg ip from any to any xmit 'table(10)' out"
+.Dl "ipfw add 100 allow ip from any to any flow 'table(fl,11)' recv ix0"
.Ss SETS OF RULES
To add a set of rules atomically, e.g.\& set 18:
.Pp
More information about the svn-src-projects
mailing list