mirror of
https://github.com/freebsd/freebsd-src.git
synced 2024-12-01 21:33:04 +00:00
263 lines
7.5 KiB
Groff
263 lines
7.5 KiB
Groff
.\" $OpenBSD: pfsync.4,v 1.24 2006/10/23 07:05:49 jmc Exp $
|
|
.\"
|
|
.\" Copyright (c) 2002 Michael Shalayeff
|
|
.\" Copyright (c) 2003-2004 Ryan McBride
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF MIND,
|
|
.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd June 6, 2006
|
|
.Dt PFSYNC 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm pfsync
|
|
.Nd packet filter state table logging interface
|
|
.Sh SYNOPSIS
|
|
.Cd "device pfsync"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
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.
|
|
If configured with a physical synchronisation interface,
|
|
.Nm
|
|
will send state changes out on that interface using IP multicast,
|
|
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
|
|
.Nm
|
|
over the network are not rebroadcast.
|
|
States created by a rule marked with the
|
|
.Ar no-sync
|
|
keyword are omitted from the
|
|
.Nm
|
|
interface (see
|
|
.Xr pf.conf 5
|
|
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
|
|
.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
|
|
.Sh NETWORK SYNCHRONISATION
|
|
States can be synchronised between two or more firewalls using this
|
|
interface, by specifying a synchronisation interface using
|
|
.Xr ifconfig 8 .
|
|
For example, the following command sets fxp0 as the synchronisation
|
|
interface:
|
|
.Bd -literal -offset indent
|
|
# 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
|
|
.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 .
|
|
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,
|
|
e.g.:
|
|
.Bd -literal -offset indent
|
|
# ifconfig pfsync0 syncpeer 10.0.0.2 syncdev enc0
|
|
.Ed
|
|
.Pp
|
|
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
|
|
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.
|
|
.Pp
|
|
Both firewalls in this example have three
|
|
.Xr sis 4
|
|
interfaces.
|
|
sis0 is the external interface, on the 10.0.0.0/24 subnet; sis1 is the
|
|
internal interface, on the 192.168.0.0/24 subnet; and sis2 is the
|
|
.Nm
|
|
interface, using the 192.168.254.0/24 subnet.
|
|
A crossover cable connects the two firewalls via their sis2 interfaces.
|
|
On all three interfaces, firewall A uses the .254 address, while firewall B
|
|
uses .253.
|
|
The interfaces are configured as follows (firewall A unless otherwise
|
|
indicated):
|
|
.Pp
|
|
Interfaces configuration in
|
|
.Pa /etc/rc.conf :
|
|
.Bd -literal -offset indent
|
|
network_interfaces="lo0 sis0 sis1 sis2"
|
|
cloned_interfaces="carp0 carp1"
|
|
ifconfig_sis0="10.0.0.254/24"
|
|
ifconfig_sis1="192.168.0.254/24"
|
|
ifconfig_sis2="192.168.254.254/24"
|
|
ifconfig_carp0="vhid 1 pass foo 10.0.0.1/24"
|
|
ifconfig_carp1="vhid 2 pass bar 192.168.0.1/24"
|
|
pfsync_enable="YES"
|
|
pfsync_syncdev="sis2"
|
|
.Ed
|
|
.Pp
|
|
.Xr pf 4
|
|
must also be configured to allow
|
|
.Nm
|
|
and
|
|
.Xr carp 4
|
|
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
|
|
.Ed
|
|
.Pp
|
|
If it is preferable that one firewall handle the traffic,
|
|
the
|
|
.Ar advskew
|
|
on the backup firewall's
|
|
.Xr carp 4
|
|
interfaces should be set to something higher than
|
|
the primary's.
|
|
For example, if firewall B is the backup, its
|
|
carp1 configuration would look like this:
|
|
.Bd -literal -offset indent
|
|
ifconfig_carp1="vhid 2 pass bar advskew 100 192.168.0.1/24"
|
|
.Ed
|
|
.Pp
|
|
The following must also be added to
|
|
.Pa /etc/sysctl.conf :
|
|
.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 inet 4 ,
|
|
.Xr inet6 4 ,
|
|
.Xr ipsec 4 ,
|
|
.Xr netintro 4 ,
|
|
.Xr pf 4 ,
|
|
.Xr pf.conf 5 ,
|
|
.Xr protocols 5 ,
|
|
.Xr rc.conf 5
|
|
.Xr ifconfig 8 ,
|
|
.Xr ifstated 8 ,
|
|
.Xr tcpdump 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
device first appeared in
|
|
.Ox 3.3 .
|
|
The
|
|
.Nm
|
|
device was imported to
|
|
.Fx 5.3 .
|