Some cleanup in the pf manual pages.
[dragonfly.git] / share / man / man4 / pfsync.4
CommitLineData
b31f0f40 1.\" $OpenBSD: pfsync.4,v 1.24 2006/10/23 07:05:49 jmc Exp $
f1e85027
SS
2.\"
3.\" Copyright (c) 2002 Michael Shalayeff
70224baa 4.\" Copyright (c) 2003-2004 Ryan McBride
f1e85027
SS
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF MIND,
22.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26.\"
70224baa 27.Dd August 5, 2010
f1e85027
SS
28.Dt PFSYNC 4
29.Os
30.Sh NAME
31.Nm pfsync
70224baa 32.Nd packet filter state table logging interface
f1e85027
SS
33.Sh SYNOPSIS
34.Cd "device pfsync"
35.Sh DESCRIPTION
36The
37.Nm
38interface is a pseudo-device which exposes certain changes to the state
39table used by
40.Xr pf 4 .
41State changes can be viewed by invoking
b958492b 42.Xr tcpdump 1
f1e85027
SS
43on the
44.Nm
45interface.
46If configured with a physical synchronisation interface,
47.Nm
48will also send state changes out on that interface using IP multicast,
49and insert state changes received on that interface from other systems
50into the state table.
51.Pp
52By default, all local changes to the state table are exposed via
53.Nm .
54However, state changes from packets received by
55.Nm
56over the network are not rebroadcast.
57States created by a rule marked with the
58.Ar no-sync
59keyword are omitted from the
60.Nm
61interface (see
62.Xr pf.conf 5
63for details).
64.Pp
65The
66.Nm
67interface will attempt to collapse multiple updates of the same
68state into one message where possible.
69The maximum number of times this can be done before the update is sent out
70is controlled by the
71.Ar maxupd
70224baa 72parameter to ifconfig
f1e85027
SS
73(see
74.Xr ifconfig 8
70224baa 75and the example below for more details).
f1e85027
SS
76.Pp
77Each packet retrieved on this interface has a header associated
78with it of length
79.Dv PFSYNC_HDRLEN .
80The header indicates the version of the protocol, address family,
70224baa 81action taken on the following states, and the number of state
f1e85027 82table entries attached in this packet.
70224baa
JL
83This structure is defined in
84.Aq Pa net/pf/if_pfsync.h
85as:
f1e85027
SS
86.Bd -literal -offset indent
87struct pfsync_header {
88 u_int8_t version;
89 u_int8_t af;
90 u_int8_t action;
91 u_int8_t count;
92};
93.Ed
94.Sh NETWORK SYNCHRONISATION
95States can be synchronised between two or more firewalls using this
96interface, by specifying a synchronisation interface using
97.Xr ifconfig 8 .
98For example, the following command sets fxp0 as the synchronisation
70224baa 99interface:
f1e85027 100.Bd -literal -offset indent
70224baa 101# ifconfig pfsync0 syncdev fxp0
f1e85027
SS
102.Ed
103.Pp
70224baa 104By default, state change messages are sent out on the synchronisation
f1e85027
SS
105interface using IP multicast packets.
106The protocol is IP protocol 240, PFSYNC, and the multicast group
107used is 224.0.0.240.
70224baa
JL
108When a peer address is specified using the
109.Ic syncpeer
110keyword, the peer address is used as a destination for the pfsync traffic,
111and the traffic can then be protected using
112.Xr ipsec 4 .
113In such a configuration, the syncdev should be set to the
114.Xr enc 4
115interface, as this is where the traffic arrives when it is decapsulated,
116e.g.:
117.Bd -literal -offset indent
118# ifconfig pfsync0 syncpeer 10.0.0.2 syncdev enc0
119.Ed
f1e85027 120.Pp
70224baa
JL
121It is important that the pfsync traffic be well secured
122as there is no authentication on the protocol and it would
f1e85027 123be trivial to spoof packets which create states, bypassing the pf ruleset.
70224baa
JL
124Either run the pfsync protocol on a trusted network \- ideally a network
125dedicated to pfsync messages such as a crossover cable between two firewalls,
126or specify a peer address and protect the traffic with
127.Xr ipsec 4 .
f1e85027
SS
128.Pp
129There is a one-to-one correspondence between packets seen by
130.Xr bpf 4
131on the
132.Nm
133interface, and packets sent out on the synchronisation interface, i.e.\&
134a packet with 4 state deletion messages on
135.Nm
136means that the same 4 deletions were sent out on the synchronisation
137interface.
138However, the actual packet contents may differ as the messages
139sent over the network are "compressed" where possible, containing
140only the necessary information.
141.Sh EXAMPLES
142.Bd -literal -offset indent
143# ifconfig pfsync0 up syncif fxp0 maxupd 64
144# tcpdump -s1500 -evtni pfsync0
145.Ed
0d16ba1d
MD
146.Sh USING PFSYNC WITH CARP
147.Nm
148and
149.Xr carp 4
150can be used together to provide automatic failover of a pair of firewalls
151configured in parallel.
152One firewall handles all traffic \- if it dies or
153is shut down, the second firewall takes over automatically.
154.Pp
155Both firewalls in this example have three
156.Xr sis 4
157interfaces.
158sis0 is the external interface, on the 10.0.0.0/24 subnet; sis1 is the
159internal interface, on the 192.168.0.0/24 subnet; and sis2 is the
160.Nm
161interface, using the 192.168.254.0/24 subnet.
162A crossover cable connects the two firewalls via their sis2 interfaces.
163On all three interfaces, firewall A uses the .254 address, while firewall B
164uses .253.
165The interfaces are configured as follows (firewall A unless otherwise
166indicated):
167.Pp
168Interfaces configuration in
169.Pa /etc/rc.conf :
170.Bd -literal -offset indent
171network_interfaces="lo0 sis0 sis1 sis2"
172cloned_interfaces="carp0 carp1"
173ifconfig_sis0="10.0.0.254/24"
174ifconfig_sis1="192.168.0.254/24"
175ifconfig_sis2="192.168.254.254/24"
176ifconfig_carp0="vhid 1 pass foo 10.0.0.1/24"
177ifconfig_carp1="vhid 2 pass bar 192.168.0.1/24"
178pfsync_enable="YES"
179pfsync_syncdev="sis2"
180.Ed
181.Pp
182.Xr pf 4
183must also be configured to allow
184.Nm
185and
186.Xr carp 4
187traffic through.
188The following should be added to the top of
189.Pa /etc/pf.conf :
190.Bd -literal -offset indent
191pass quick on { sis2 } proto pfsync
70224baa 192pass on { sis0 sis1 } proto carp
0d16ba1d
MD
193.Ed
194.Pp
195If it is preferable that one firewall handle the traffic,
196the
197.Ar advskew
198on the backup firewall's
199.Xr carp 4
200interfaces should be set to something higher than
201the primary's.
202For example, if firewall B is the backup, its
203carp1 configuration would look like this:
204.Bd -literal -offset indent
205ifconfig_carp1="vhid 2 pass bar advskew 100 192.168.0.1/24"
206.Ed
207.Pp
208The following must also be added to
209.Pa /etc/sysctl.conf :
210.Bd -literal -offset indent
211net.inet.carp.preempt=1
212.Ed
f1e85027 213.Sh SEE ALSO
b31f0f40 214.Xr tcpdump 1 ,
f1e85027 215.Xr bpf 4 ,
9bf37d9d 216.Xr carp 4 ,
f1e85027
SS
217.Xr inet 4 ,
218.Xr inet6 4 ,
70224baa 219.Xr ipsec 4 ,
f1e85027
SS
220.Xr netintro 4 ,
221.Xr pf 4 ,
222.Xr pf.conf 5 ,
223.Xr protocols 5 ,
b31f0f40
SW
224.Xr ifconfig 8
225.\".Xr ifstated 8 ,
f1e85027
SS
226.Sh HISTORY
227The
228.Nm
229device first appeared in
230.Ox 3.3
231and was imported into
232.Dx 1.1
233by Devon H. O'Dell and Simon Schubert.