svn commit: r221091 - projects/pf/pf45/contrib/pf/man
Ermal Luçi
eri at FreeBSD.org
Tue Apr 26 22:13:58 UTC 2011
Author: eri
Date: Tue Apr 26 22:13:58 2011
New Revision: 221091
URL: http://svn.freebsd.org/changeset/base/221091
Log:
Update man pages also to match the OpenBSD 4.5 content.
Modified:
projects/pf/pf45/contrib/pf/man/pf.4
projects/pf/pf45/contrib/pf/man/pf.conf.5
projects/pf/pf45/contrib/pf/man/pf.os.5
projects/pf/pf45/contrib/pf/man/pflog.4
projects/pf/pf45/contrib/pf/man/pfsync.4
Modified: projects/pf/pf45/contrib/pf/man/pf.4
==============================================================================
--- projects/pf/pf45/contrib/pf/man/pf.4 Tue Apr 26 22:11:40 2011 (r221090)
+++ projects/pf/pf45/contrib/pf/man/pf.4 Tue Apr 26 22:13:58 2011 (r221091)
@@ -1,4 +1,4 @@
-.\" $OpenBSD: pf.4,v 1.58 2007/02/09 11:39:06 henning Exp $
+.\" $OpenBSD: pf.4,v 1.62 2008/09/10 14:57:37 jmc Exp $
.\"
.\" Copyright (C) 2001, Kjell Wooding. All rights reserved.
.\"
@@ -28,7 +28,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd February 7, 2005
+.Dd September 10 2008
.Dt PF 4
.Os
.Sh NAME
@@ -294,14 +294,17 @@ if another process is concurrently updat
Add a state entry.
.Bd -literal
struct pfioc_state {
- u_int32_t nr;
- struct pf_state state;
+ struct pfsync_state state;
};
.Ed
.It Dv DIOCGETSTATE Fa "struct pfioc_state *ps"
-Extract the entry with the specified number
-.Va nr
-from the state table.
+Extract the entry identified by the
+.Va id
+and
+.Va creatorid
+fields of the
+.Va state
+structure from the state table.
.It Dv DIOCKILLSTATES Fa "struct pfioc_state_kill *psk"
Remove matching entries from the state table.
This ioctl returns the number of killed states in
@@ -1049,12 +1052,14 @@ internal interface description.
The filtering process is the same as for
.Dv DIOCIGETIFACES .
.Bd -literal
-#define PFI_IFLAG_SKIP 0x0100 /* skip filtering on interface */
+#define PFI_IFLAG_SKIP 0x0100 /* skip filtering on interface */
.Ed
.It Dv DIOCCLRIFFLAG Fa "struct pfioc_iface *io"
Works as
.Dv DIOCSETIFFLAG
above but clears the flags.
+.It Dv DIOCKILLSRCNODES Fa "struct pfioc_iface *io"
+Explicitly remove source tracking nodes.
.El
.Sh FILES
.Bl -tag -width /dev/pf -compact
@@ -1133,6 +1138,7 @@ main(int argc, char *argv[])
.Xr altq 4 ,
.Xr if_bridge 4 ,
.Xr pflog 4 ,
+.Xr pflow 4 ,
.Xr pfsync 4 ,
.Xr pfctl 8 ,
.Xr altq 9
Modified: projects/pf/pf45/contrib/pf/man/pf.conf.5
==============================================================================
--- projects/pf/pf45/contrib/pf/man/pf.conf.5 Tue Apr 26 22:11:40 2011 (r221090)
+++ projects/pf/pf45/contrib/pf/man/pf.conf.5 Tue Apr 26 22:13:58 2011 (r221091)
@@ -1,5 +1,5 @@
-.\" $FreeBSD$
-.\" $OpenBSD: pf.conf.5,v 1.393 2008/02/11 07:46:32 jmc Exp $
+.\" $FreeBSD$
+.\" $OpenBSD: pf.conf.5,v 1.406 2009/01/31 19:37:12 sobrado Exp $
.\"
.\" Copyright (c) 2002, Daniel Hartmeier
.\" All rights reserved.
@@ -28,7 +28,7 @@
.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd June 10, 2008
+.Dd January 31 2009
.Dt PF.CONF 5
.Os
.Sh NAME
@@ -79,6 +79,17 @@ By default
enforces this order (see
.Ar set require-order
below).
+.Pp
+Comments can be put anywhere in the file using a hash mark
+.Pq Sq # ,
+and extend to the end of the current line.
+.Pp
+Additional configuration files can be included with the
+.Ic include
+keyword, for example:
+.Bd -literal -offset indent
+include "/etc/pf/sub.filter.conf"
+.Ed
.Sh MACROS
Macros can be defined that will later be expanded in context.
Macro names must start with a letter, and may contain letters, digits
@@ -154,7 +165,7 @@ A table initialized with the empty list,
will be cleared on load.
.El
.Pp
-Tables may be defined with the following two attributes:
+Tables may be defined with the following attributes:
.Bl -tag -width persist
.It Ar persist
The
@@ -173,6 +184,11 @@ can be used to add or remove addresses f
when running with
.Xr securelevel 7
= 2.
+.It Ar counters
+The
+.Ar counters
+flag enables per-address packet and byte counters which can be displayed with
+.Xr pfctl 8 .
.El
.Pp
For example,
@@ -328,7 +344,8 @@ With 9000 state table entries, the timeo
(tcp.first 60, tcp.established 43200).
.Pp
.It Ar set loginterface
-Enable collection of packet and byte count statistics for the given interface.
+Enable collection of packet and byte count statistics for the given
+interface or interface group.
These statistics can be viewed using
.Bd -literal -offset indent
# pfctl -s info
@@ -403,9 +420,10 @@ set limit { states 20000, frags 20000, s
.Bl -tag -width xxxxxxxx -compact
.It Ar none
Disable the ruleset optimizer.
-This is the default behaviour.
.It Ar basic
-Enable basic ruleset optimization, which does four things to improve the
+Enable basic ruleset optimization.
+This is the default behaviour.
+Basic ruleset optimization does four things to improve the
performance of ruleset evaluations:
.Pp
.Bl -enum -compact
@@ -500,6 +518,16 @@ For example:
.Bd -literal -offset indent
set state-policy if-bound
.Ed
+.It Ar set state-defaults
+The
+.Ar state-defaults
+option sets the state options for states created from rules
+without an explicit
+.Ar keep state .
+For example:
+.Bd -literal -offset indent
+set state-defaults pflow, no-sync
+.Ed
.It Ar set hostid
The 32-bit
.Ar hostid
@@ -617,6 +645,19 @@ modifier to ensure unique IP identifiers
Enforces a minimum TTL for matching IP packets.
.It Ar max-mss Aq Ar number
Enforces a maximum MSS for matching TCP packets.
+.It Xo Ar set-tos Aq Ar string
+.No \*(Ba Aq Ar number
+.Xc
+Enforces a
+.Em TOS
+for matching IP packets.
+.Em TOS
+may be
+given as one of
+.Ar lowdelay ,
+.Ar throughput ,
+.Ar reliability ,
+or as either hex or decimal.
.It Ar random-id
Replaces the IP identification field with random values to compensate
for predictable values generated by many hosts.
@@ -725,7 +766,7 @@ much in the same way as
works in the packet filter (see below).
This mechanism should be used when it is necessary to exclude specific packets
from broader scrub rules.
-.Sh QUEUEING/ALTQ
+.Sh QUEUEING
The ALTQ system is currently not available in the GENERIC kernel nor as
loadable modules.
In order to use the herein after called queueing options one has to use a
@@ -816,7 +857,7 @@ assigned.
.Ar Priority
mainly controls the time packets take to get sent out, while
.Ar bandwidth
-has primarily effects on throughput.
+primarily affects throughput.
.Ar hfsc
supports both link-sharing and guaranteed real-time services.
It employs a service curve based QoS model,
@@ -879,7 +920,7 @@ Defines a list of subqueues to create on
.El
.Pp
In the following example, the interface dc0
-should queue up to 5 Mbit/s in four second-level queues using
+should queue up to 5Mbps in four second-level queues using
Class Based Queueing.
Those four queues will be shown in a later example.
.Bd -literal -offset indent
@@ -1171,7 +1212,7 @@ or to the firewall itself.
Note that redirecting external incoming connections to the loopback
address, as in
.Bd -literal -offset indent
-rdr on ne3 inet proto tcp to port spamd -\*(Gt 127.0.0.1 port smtp
+rdr on ne3 inet proto tcp to port smtp -\*(Gt 127.0.0.1 port spamd
.Ed
.Pp
will effectively allow an external host to connect to daemons
@@ -1256,7 +1297,7 @@ block all
.Ed
.It Ar pass
The packet is passed;
-state is created state unless the
+state is created unless the
.Ar no state
option is specified.
.El
@@ -1432,7 +1473,8 @@ This rule applies only to packets with t
addresses and ports.
.Pp
Addresses can be specified in CIDR notation (matching netblocks), as
-symbolic host names or interface names, or as any of the following keywords:
+symbolic host names, interface names or interface group names, or as any
+of the following keywords:
.Pp
.Bl -tag -width xxxxxxxxxxxxxx -compact
.It Ar any
@@ -1454,7 +1496,15 @@ the route back to the packet's source ad
Any address that matches the given table.
.El
.Pp
-Interface names can have modifiers appended:
+Ranges of addresses are specified by using the
+.Sq -
+operator.
+For instance:
+.Dq 10.1.1.10 - 10.1.1.12
+means all addresses from 10.1.1.10 to 10.1.1.12,
+hence addresses 10.1.1.10, 10.1.1.11, and 10.1.1.12.
+.Pp
+Interface names and interface group names can have modifiers appended:
.Pp
.Bl -tag -width xxxxxxxxxxxx -compact
.It Ar :network
@@ -1462,7 +1512,7 @@ Translates to the network(s) attached to
.It Ar :broadcast
Translates to the interface's broadcast address(es).
.It Ar :peer
-Translates to the point to point interface's peer address(es).
+Translates to the point-to-point interface's peer address(es).
.It Ar :0
Do not include interface aliases.
.El
@@ -1552,17 +1602,6 @@ This is equivalent to "from any to any".
Similar to
.Ar user ,
this rule only applies to packets of sockets owned by the specified group.
-.Pp
-The use of
-.Ar group
-or
-.Ar user
-in
-.Va debug.mpsafenet Ns = Ns 1
-environments may result in a deadlock.
-Please see the
-.Sx BUGS
-section for details.
.It Ar user Aq Ar user
This rule only applies to packets of sockets owned by the specified user.
For outgoing connections initiated from the firewall, this is the user
@@ -1628,7 +1667,7 @@ Flags not specified in
are ignored.
For stateful connections, the default is
.Ar flags S/SA .
-To indicate that flags should not be checkd at all, specify
+To indicate that flags should not be checked at all, specify
.Ar flags any .
The flags are: (F)IN, (S)YN, (R)ST, (P)USH, (A)CK, (U)RG, (E)CE, and C(W)R.
.Bl -tag -width Fl
@@ -1780,7 +1819,7 @@ of
.Em lowdelay
and TCP ACKs with no data payload will be assigned to the second one.
See
-.Sx QUEUEING/ALTQ
+.Sx QUEUEING
for setup details.
.Pp
For example:
@@ -1811,7 +1850,8 @@ or
rules in addition to filter rules.
Tags take the same macros as labels (see above).
.It Ar tagged Aq Ar string
-Used with filter or translation rules to specify that packets must already
+Used with filter, translation or scrub rules
+to specify that packets must already
be tagged with the given tag in order to match the rule.
Inverse tag matching can also be done
by specifying the
@@ -1822,6 +1862,22 @@ keyword.
.It Ar rtable Aq Ar number
Used to select an alternate routing table for the routing lookup.
Only effective before the route lookup happened, i.e. when filtering inbound.
+.It Xo Ar divert-to Aq Ar host
+.Ar port Aq Ar port
+.Xc
+Used to redirect packets to a local socket bound to
+.Ar host
+and
+.Ar port .
+The packets will not be modified, so
+.Xr getsockname 2
+on the socket will return the original destination address of the packet.
+.It Ar divert-reply
+Used to receive replies for sockets that are bound to addresses
+which are not local to the machine.
+See
+.Xr setsockopt 2
+for information on how to bind these sockets.
.It Ar probability Aq Ar number
A probability attribute can be attached to a rule, with a value set between
0 and 1, bounds not included.
@@ -1940,7 +1996,7 @@ pool options.
Note that by default these associations are destroyed as soon as there are
no longer states which refer to them; in order to make the mappings last
beyond the lifetime of the states, increase the global options with
-.Ar set timeout source-track
+.Ar set timeout src.track .
See
.Sx STATEFUL TRACKING OPTIONS
for more ways to control the source tracking.
@@ -2026,7 +2082,7 @@ Rules with
will not work if
.Xr pf 4
operates on a
-.Xr if_bridge 4 .
+.Xr bridge 4 .
.Pp
Example:
.Bd -literal -offset indent
@@ -2046,8 +2102,8 @@ must be specified explicitly to apply op
.Bl -tag -width xxxx -compact
.It Ar max Aq Ar number
Limits the number of concurrent states the rule may create.
-When this limit is reached, further packets matching the rule that would
-create state are dropped, until existing states time out.
+When this limit is reached, further packets that would create
+state will not match this rule until existing states time out.
.It Ar no-sync
Prevent state changes for states created by this rule from appearing on the
.Xr pfsync 4
@@ -2064,8 +2120,12 @@ Uses a sloppy TCP connection tracker tha
numbers at all, which makes insertion and ICMP teardown attacks way
easier.
This is intended to be used in situations where one does not see all
-packets of a connection, i.e. in asymmetric routing situations.
+packets of a connection, e.g. in asymmetric routing situations.
Cannot be used with modulate or synproxy state.
+.It Ar pflow
+States created by this rule are exported on the
+.Xr pflow 4
+interface.
.El
.Pp
Multiple options can be specified, separated by commas:
@@ -2472,10 +2532,8 @@ into the anchor.
.Pp
Optionally,
.Ar anchor
-rules can specify the parameter's
-direction, interface, address family, protocol and source/destination
-address/port
-using the same syntax as filter rules.
+rules can specify packet filtering parameters using the same syntax as
+filter rules.
When parameters are used, the
.Ar anchor
rule is only evaluated for matching packets.
@@ -2779,10 +2837,11 @@ in BNF:
.Bd -literal
line = ( option | pf-rule | nat-rule | binat-rule | rdr-rule |
antispoof-rule | altq-rule | queue-rule | trans-anchors |
- anchor-rule | anchor-close | load-anchor | table-rule | )
+ anchor-rule | anchor-close | load-anchor | table-rule |
+ include )
option = "set" ( [ "timeout" ( timeout | "{" timeout-list "}" ) ] |
- [ "ruleset-optimization" [ "none" | "basic" | "profile" ]] |
+ [ "ruleset-optimization" [ "none" | "basic" | "profile" ]] |
[ "optimization" [ "default" | "normal" |
"high-latency" | "satellite" |
"aggressive" | "conservative" ] ]
@@ -2790,9 +2849,10 @@ option = "set" ( [ "timeout" ( t
[ "loginterface" ( interface-name | "none" ) ] |
[ "block-policy" ( "drop" | "return" ) ] |
[ "state-policy" ( "if-bound" | "floating" ) ]
+ [ "state-defaults" state-opts ]
[ "require-order" ( "yes" | "no" ) ]
[ "fingerprints" filename ] |
- [ "skip on" ( interface-name | "{" interface-list "}" ) ] |
+ [ "skip on" ifspec ] |
[ "debug" ( "none" | "urgent" | "misc" | "loud" ) ] )
pf-rule = action [ ( "in" | "out" ) ]
@@ -2804,10 +2864,10 @@ logopts = logopt [ "," logopts ]
logopt = "all" | "user" | "to" interface-name
filteropt-list = filteropt-list filteropt | filteropt
-filteropt = user | group | flags | icmp-type | icmp6-type | tos |
+filteropt = user | group | flags | icmp-type | icmp6-type | "tos" tos |
( "no" | "keep" | "modulate" | "synproxy" ) "state"
[ "(" state-opts ")" ] |
- "fragment" | "no-df" | "min-ttl" number |
+ "fragment" | "no-df" | "min-ttl" number | "set-tos" tos |
"max-mss" number | "random-id" | "reassemble tcp" |
fragmentation | "allow-opts" |
"label" string | "tag" string | [ ! ] "tagged" string |
@@ -2834,17 +2894,16 @@ rdr-rule = [ "no" ] "rdr" [ "pass"
[ portspec ] [ pooltype ] ]
antispoof-rule = "antispoof" [ "log" ] [ "quick" ]
- "for" ( interface-name | "{" interface-list "}" )
- [ af ] [ "label" string ]
+ "for" ifspec [ af ] [ "label" string ]
table-rule = "table" "\*(Lt" string "\*(Gt" [ tableopts-list ]
tableopts-list = tableopts-list tableopts | tableopts
-tableopts = "persist" | "const" | "file" string |
+tableopts = "persist" | "const" | "counters" | "file" string |
"{" [ tableaddr-list ] "}"
tableaddr-list = tableaddr-list [ "," ] tableaddr-spec | tableaddr-spec
tableaddr-spec = [ "!" ] tableaddr [ "/" mask-bits ]
-tableaddr = hostname | ipv4-dotted-quad | ipv6-coloned-hex |
- interface-name | "self"
+tableaddr = hostname | ifspec | "self" |
+ ipv4-dotted-quad | ipv6-coloned-hex
altq-rule = "altq on" interface-name queueopts-list
"queue" subqueue
@@ -2852,7 +2911,7 @@ queue-rule = "queue" string [ "on" i
subqueue
anchor-rule = "anchor" [ string ] [ ( "in" | "out" ) ] [ "on" ifspec ]
- [ af ] [ protospec ] [ hosts ] [ "{" ]
+ [ af ] [ protospec ] [ hosts ] [ filteropt-list ] [ "{" ]
anchor-close = "}"
@@ -2875,8 +2934,10 @@ return = "drop" | "return" | "re
icmpcode = ( icmp-code-name | icmp-code-number )
icmp6code = ( icmp6-code-name | icmp6-code-number )
-ifspec = ( [ "!" ] interface-name ) | "{" interface-list "}"
-interface-list = [ "!" ] interface-name [ [ "," ] interface-list ]
+ifspec = ( [ "!" ] ( interface-name | interface-group ) ) |
+ "{" interface-list "}"
+interface-list = [ "!" ] ( interface-name | interface-group )
+ [ [ "," ] interface-list ]
route = ( "route-to" | "reply-to" | "dup-to" )
( routehost | "{" routehost-list "}" )
[ pooltype ]
@@ -2896,8 +2957,9 @@ ipspec = "any" | host | "{" host
host = [ "!" ] ( address [ "/" mask-bits ] | "\*(Lt" string "\*(Gt" )
redirhost = address [ "/" mask-bits ]
routehost = "(" interface-name [ address [ "/" mask-bits ] ] ")"
-address = ( interface-name | "(" interface-name ")" | hostname |
- ipv4-dotted-quad | ipv6-coloned-hex )
+address = ( interface-name | interface-group |
+ "(" ( interface-name | interface-group ) ")" |
+ hostname | ipv4-dotted-quad | ipv6-coloned-hex )
host-list = host [ [ "," ] host-list ]
redirhost-list = redirhost [ [ "," ] redirhost-list ]
routehost-list = routehost [ [ "," ] routehost-list ]
@@ -2926,11 +2988,11 @@ icmp-type-code = ( icmp-type-name | icmp
[ "code" ( icmp-code-name | icmp-code-number ) ]
icmp-list = icmp-type-code [ [ "," ] icmp-list ]
-tos = "tos" ( "lowdelay" | "throughput" | "reliability" |
+tos = ( "lowdelay" | "throughput" | "reliability" |
[ "0x" ] number )
state-opts = state-opt [ [ "," ] state-opts ]
-state-opt = ( "max" number | "no-sync" | timeout | sloppy |
+state-opt = ( "max" number | "no-sync" | timeout | "sloppy" | "pflow" |
"source-track" [ ( "rule" | "global" ) ] |
"max-src-nodes" number | "max-src-states" number |
"max-src-conn" number |
@@ -2971,9 +3033,10 @@ realtime-sc = "realtime" sc-spec
upperlimit-sc = "upperlimit" sc-spec
sc-spec = ( bandwidth-spec |
"(" bandwidth-spec number bandwidth-spec ")" )
+include = "include" filename
.Ed
.Sh FILES
-.Bl -tag -width "/usr/share/examples/pf" -compact
+.Bl -tag -width "/etc/protocols" -compact
.It Pa /etc/hosts
Host name database.
.It Pa /etc/pf.conf
@@ -2984,8 +3047,6 @@ Default location of OS fingerprints.
Protocol name database.
.It Pa /etc/services
Service name database.
-.It Pa /usr/share/examples/pf
-Example rulesets.
.El
.Sh BUGS
Due to a lock order reversal (LOR) with the socket layer, the use of the
@@ -3017,6 +3078,7 @@ Rules with a route label do not match an
.Xr ip 4 ,
.Xr ip6 4 ,
.Xr pf 4 ,
+.Xr pflow 4 ,
.Xr pfsync 4 ,
.Xr route 4 ,
.Xr tcp 4 ,
Modified: projects/pf/pf45/contrib/pf/man/pf.os.5
==============================================================================
--- projects/pf/pf45/contrib/pf/man/pf.os.5 Tue Apr 26 22:11:40 2011 (r221090)
+++ projects/pf/pf45/contrib/pf/man/pf.os.5 Tue Apr 26 22:13:58 2011 (r221091)
@@ -1,4 +1,4 @@
-.\" $OpenBSD: pf.os.5,v 1.7 2005/11/16 20:07:18 stevesk Exp $
+.\" $OpenBSD: pf.os.5,v 1.8 2007/05/31 19:19:58 jmc Exp $
.\"
.\" Copyright (c) 2003 Mike Frantzen <frantzen at w4g.org>
.\"
@@ -13,10 +13,9 @@
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-.\"
.\" $FreeBSD$
.\"
-.Dd August 18, 2003
+.Dd May 31 2007
.Dt PF.OS 5
.Os
.Sh NAME
@@ -217,7 +216,7 @@ almost translates into the following fin
57344:64:1:44:M1460: exampleOS:1.0::exampleOS 1.0
.Ed
.Sh SEE ALSO
-.Xr tcpdump 1 ,
.Xr pf 4 ,
.Xr pf.conf 5 ,
-.Xr pfctl 8
+.Xr pfctl 8 ,
+.Xr tcpdump 1
Modified: projects/pf/pf45/contrib/pf/man/pflog.4
==============================================================================
--- projects/pf/pf45/contrib/pf/man/pflog.4 Tue Apr 26 22:11:40 2011 (r221090)
+++ projects/pf/pf45/contrib/pf/man/pflog.4 Tue Apr 26 22:13:58 2011 (r221091)
@@ -1,4 +1,4 @@
-.\" $OpenBSD: pflog.4,v 1.9 2006/10/25 12:51:31 jmc Exp $
+.\" $OpenBSD: pflog.4,v 1.10 2007/05/31 19:19:51 jmc Exp $
.\"
.\" Copyright (c) 2001 Tobias Weingartner
.\" All rights reserved.
@@ -25,7 +25,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd December 10, 2001
+.Dd May 31 2007
.Dt PFLOG 4
.Os
.Sh NAME
@@ -36,7 +36,7 @@
.Sh DESCRIPTION
The
.Nm pflog
-interface is a pseudo-device which makes visible all packets logged by
+interface is a device which makes visible all packets logged by
the packet filter,
.Xr pf 4 .
Logged packets can easily be monitored in real
@@ -91,13 +91,13 @@ and monitor all packets logged on it:
# tcpdump -n -e -ttt -i pflog1
.Ed
.Sh SEE ALSO
-.Xr tcpdump 1
.Xr inet 4 ,
.Xr inet6 4 ,
.Xr netintro 4 ,
.Xr pf 4 ,
.Xr ifconfig 8 ,
-.Xr pflogd 8
+.Xr pflogd 8 ,
+.Xr tcpdump 1
.Sh HISTORY
The
.Nm
Modified: projects/pf/pf45/contrib/pf/man/pfsync.4
==============================================================================
--- projects/pf/pf45/contrib/pf/man/pfsync.4 Tue Apr 26 22:11:40 2011 (r221090)
+++ projects/pf/pf45/contrib/pf/man/pfsync.4 Tue Apr 26 22:13:58 2011 (r221091)
@@ -1,4 +1,4 @@
-.\" $OpenBSD: pfsync.4,v 1.24 2006/10/23 07:05:49 jmc Exp $
+.\" $OpenBSD: pfsync.4,v 1.28 2009/02/17 10:05:18 dlg Exp $
.\"
.\" Copyright (c) 2002 Michael Shalayeff
.\" Copyright (c) 2003-2004 Ryan McBride
@@ -26,12 +26,12 @@
.\"
.\" $FreeBSD$
.\"
-.Dd June 6, 2006
+.Dd February 17 2009
.Dt PFSYNC 4
.Os
.Sh NAME
.Nm pfsync
-.Nd packet filter state table logging interface
+.Nd packet filter state table sychronisation interface
.Sh SYNOPSIS
.Cd "device pfsync"
.Sh DESCRIPTION
@@ -40,26 +40,25 @@ The
interface is a pseudo-device which exposes certain changes to the state
table used by
.Xr pf 4 .
-.\" XXX: not yet!
-.\" State changes can be viewed by invoking
-.\" .Xr tcpdump 1
-.\" on the
-.\" .Nm
-.\" interface.
+State changes can be viewed by invoking
+.Xr tcpdump 1
+on the
+.Nm
+interface.
If configured with a physical synchronisation interface,
.Nm
-will send state changes out on that interface using IP multicast,
+will also send state changes out on that interface,
and insert state changes received on that interface from other systems
into the state table.
.Pp
By default, all local changes to the state table are exposed via
.Nm .
-However, state changes from packets received by
+State changes from packets received by
.Nm
over the network are not rebroadcast.
-States created by a rule marked with the
+Updates to states created by a rule marked with the
.Ar no-sync
-keyword are omitted from the
+keyword are ignored by the
.Nm
interface (see
.Xr pf.conf 5
@@ -67,33 +66,19 @@ for details).
.Pp
The
.Nm
-interface will attempt to collapse multiple updates of the same
-state into one message where possible.
-The maximum number of times this can be done before the update is sent out
-is controlled by the
+interface will attempt to collapse multiple state updates into a single
+packet where possible.
+The maximum number of times a single state can be updated before a
+.Nm
+packet will be sent out is controlled by the
.Ar maxupd
parameter to ifconfig
(see
.Xr ifconfig 8
and the example below for more details).
-.Pp
-Each packet retrieved on this interface has a header associated
-with it of length
-.Dv PFSYNC_HDRLEN .
-The header indicates the version of the protocol, address family,
-action taken on the following states, and the number of state
-table entries attached in this packet.
-This structure is defined in
-.Aq Pa net/if_pfsync.h
-as:
-.Bd -literal -offset indent
-struct pfsync_header {
- u_int8_t version;
- u_int8_t af;
- u_int8_t action;
- u_int8_t count;
-};
-.Ed
+The sending out of a
+.Nm
+packet will be delayed by a maximum of one second.
.Sh NETWORK SYNCHRONISATION
States can be synchronised between two or more firewalls using this
interface, by specifying a synchronisation interface using
@@ -104,18 +89,16 @@ interface:
# ifconfig pfsync0 syncdev fxp0
.Ed
.Pp
-It is important that the underlying synchronisation interface is up
-and has an IP address assigned.
-.Pp
By default, state change messages are sent out on the synchronisation
-interface using IP multicast packets.
-The protocol is IP protocol 240, PFSYNC, and the multicast group
-used is 224.0.0.240.
-When a peer address is specified using the
+interface using IP multicast packets to the 244.0.0.240 group address.
+An alternative destination address for
+.Nm
+packets can be specified using the
.Ic syncpeer
-keyword, the peer address is used as a destination for the pfsync traffic,
-and the traffic can then be protected using
-.Xr ipsec 4 .
+keyword.
+This can be used in combination with
+.Xr ipsec 4
+to protect the synchronisation traffic.
In such a configuration, the syncdev should be set to the
.Xr enc 4
interface, as this is where the traffic arrives when it is decapsulated,
@@ -127,50 +110,19 @@ e.g.:
It is important that the pfsync traffic be well secured
as there is no authentication on the protocol and it would
be trivial to spoof packets which create states, bypassing the pf ruleset.
-Either run the pfsync protocol on a trusted network \- ideally a network
+Either run the pfsync protocol on a trusted network \- ideally a network
dedicated to pfsync messages such as a crossover cable between two firewalls,
or specify a peer address and protect the traffic with
.Xr ipsec 4 .
-.Pp
-For
-.Nm
-to start its operation automatically at the system boot time,
-.Va pfsync_enable
-and
-.Va pfsync_syncdev
-variables should be used in
-.Xr rc.conf 5 .
-It is not advisable to set up
-.Nm
-with common network interface configuration variables of
-.Xr rc.conf 5
-because
-.Nm
-must start after its
-.Cm syncdev ,
-which cannot be always ensured in the latter case.
-.\" XXX: not yet!
-.\" .Pp
-.\" There is a one-to-one correspondence between packets seen by
-.\" .Xr bpf 4
-.\" on the
-.\" .Nm
-.\" interface, and packets sent out on the synchronisation interface, i.e.\&
-.\" a packet with 4 state deletion messages on
-.\" .Nm
-.\" means that the same 4 deletions were sent out on the synchronisation
-.\" interface.
-.\" However, the actual packet contents may differ as the messages
-.\" sent over the network are "compressed" where possible, containing
-.\" only the necessary information.
.Sh EXAMPLES
.Nm
and
.Xr carp 4
can be used together to provide automatic failover of a pair of firewalls
configured in parallel.
-One firewall handles all traffic \- if it dies or
-is shut down, the second firewall takes over automatically.
+One firewall will handle all traffic until it dies, is shut down, or is
+manually demoted, at which point the second firewall will take over
+automatically.
.Pp
Both firewalls in this example have three
.Xr sis 4
@@ -208,12 +160,12 @@ traffic through.
The following should be added to the top of
.Pa /etc/pf.conf :
.Bd -literal -offset indent
-pass quick on { sis2 } proto pfsync
-pass on { sis0 sis1 } proto carp
+pass quick on { sis2 } proto pfsync keep state (no-sync)
+pass on { sis0 sis1 } proto carp keep state (no-sync)
.Ed
.Pp
-If it is preferable that one firewall handle the traffic,
-the
+It is preferable that one firewall handle the forwarding of all the traffic,
+therefore the
.Ar advskew
on the backup firewall's
.Xr carp 4
@@ -221,6 +173,7 @@ interfaces should be set to something hi
the primary's.
For example, if firewall B is the backup, its
carp1 configuration would look like this:
+would look like this:
.Bd -literal -offset indent
ifconfig_carp1="vhid 2 pass bar advskew 100 192.168.0.1/24"
.Ed
@@ -230,16 +183,10 @@ The following must also be added to
.Bd -literal -offset indent
net.inet.carp.preempt=1
.Ed
-.Sh BUGS
-Possibility to view state changes using
-.Xr tcpdump 1
-has not been ported from
-.Ox
-yet.
.Sh SEE ALSO
.Xr bpf 4 ,
.Xr carp 4 ,
-.Xr ifconfig 8 ,
+.Xr enc 4 ,
.Xr inet 4 ,
.Xr inet6 4 ,
.Xr ipsec 4 ,
@@ -247,16 +194,20 @@ yet.
.Xr pf 4 ,
.Xr pf.conf 5 ,
.Xr protocols 5 ,
-.Xr rc.conf 5
+.Xr rc.conf 5 ,
.Xr ifconfig 8 ,
.Xr ifstated 8 ,
-.Xr tcpdump 8
+.Xr tcpdump 1
.Sh HISTORY
The
.Nm
device first appeared in
.Ox 3.3 .
+.Pp
The
.Nm
-device was imported to
-.Fx 5.3 .
+protocol and kernel implementation were significantly modified between
+.Ox 4.4
+and
+.Ox 4.5 .
+The two protocols are incompatible and will not interoperate.
More information about the svn-src-projects
mailing list