Sort references.
[dragonfly.git] / share / man / man4 / pfsync.4
CommitLineData
f1e85027 1.\" $OpenBSD: pfsync.4,v 1.14 2004/03/21 19:47:59 miod Exp $
9bf37d9d 2.\" $DragonFly: src/share/man/man4/pfsync.4,v 1.6 2007/11/03 18:37:42 swildner Exp $
f1e85027
SS
3.\"
4.\" Copyright (c) 2002 Michael Shalayeff
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.\"
0d16ba1d 27.Dd April 9, 2007
f1e85027
SS
28.Dt PFSYNC 4
29.Os
30.Sh NAME
31.Nm pfsync
32.Nd packet filter states table logging interface
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
72to ifconfig.
73(see
74.Xr ifconfig 8
75and the example below for more details)
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,
81action taken on the following states and the number of state
82table entries attached in this packet.
83This structure, defined in
44cb301e 84.In net/pf/if_pfsync.h
f1e85027
SS
85looks like:
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
99interface.
100.Bd -literal -offset indent
101# ifconfig pfsync0 syncif fxp0
102.Ed
103.Pp
104State change messages are sent out on the synchronisation
105interface using IP multicast packets.
106The protocol is IP protocol 240, PFSYNC, and the multicast group
107used is 224.0.0.240.
108.Pp
109It is important that the synchronisation interface be on a trusted
110network as there is no authentication on the protocol and it would
111be trivial to spoof packets which create states, bypassing the pf ruleset.
112Ideally, this is a network dedicated to pfsync messages,
113i.e. a crossover cable between two firewalls.
114.Pp
115There is a one-to-one correspondence between packets seen by
116.Xr bpf 4
117on the
118.Nm
119interface, and packets sent out on the synchronisation interface, i.e.\&
120a packet with 4 state deletion messages on
121.Nm
122means that the same 4 deletions were sent out on the synchronisation
123interface.
124However, the actual packet contents may differ as the messages
125sent over the network are "compressed" where possible, containing
126only the necessary information.
127.Sh EXAMPLES
128.Bd -literal -offset indent
129# ifconfig pfsync0 up syncif fxp0 maxupd 64
130# tcpdump -s1500 -evtni pfsync0
131.Ed
0d16ba1d
MD
132.Sh USING PFSYNC WITH CARP
133.Nm
134and
135.Xr carp 4
136can be used together to provide automatic failover of a pair of firewalls
137configured in parallel.
138One firewall handles all traffic \- if it dies or
139is shut down, the second firewall takes over automatically.
140.Pp
141Both firewalls in this example have three
142.Xr sis 4
143interfaces.
144sis0 is the external interface, on the 10.0.0.0/24 subnet; sis1 is the
145internal interface, on the 192.168.0.0/24 subnet; and sis2 is the
146.Nm
147interface, using the 192.168.254.0/24 subnet.
148A crossover cable connects the two firewalls via their sis2 interfaces.
149On all three interfaces, firewall A uses the .254 address, while firewall B
150uses .253.
151The interfaces are configured as follows (firewall A unless otherwise
152indicated):
153.Pp
154Interfaces configuration in
155.Pa /etc/rc.conf :
156.Bd -literal -offset indent
157network_interfaces="lo0 sis0 sis1 sis2"
158cloned_interfaces="carp0 carp1"
159ifconfig_sis0="10.0.0.254/24"
160ifconfig_sis1="192.168.0.254/24"
161ifconfig_sis2="192.168.254.254/24"
162ifconfig_carp0="vhid 1 pass foo 10.0.0.1/24"
163ifconfig_carp1="vhid 2 pass bar 192.168.0.1/24"
164pfsync_enable="YES"
165pfsync_syncdev="sis2"
166.Ed
167.Pp
168.Xr pf 4
169must also be configured to allow
170.Nm
171and
172.Xr carp 4
173traffic through.
174The following should be added to the top of
175.Pa /etc/pf.conf :
176.Bd -literal -offset indent
177pass quick on { sis2 } proto pfsync
178pass quick on { sis0 sis1 } proto carp keep state
179.Ed
180.Pp
181If it is preferable that one firewall handle the traffic,
182the
183.Ar advskew
184on the backup firewall's
185.Xr carp 4
186interfaces should be set to something higher than
187the primary's.
188For example, if firewall B is the backup, its
189carp1 configuration would look like this:
190.Bd -literal -offset indent
191ifconfig_carp1="vhid 2 pass bar advskew 100 192.168.0.1/24"
192.Ed
193.Pp
194The following must also be added to
195.Pa /etc/sysctl.conf :
196.Bd -literal -offset indent
197net.inet.carp.preempt=1
198.Ed
f1e85027 199.Sh SEE ALSO
3867d280 200.Xr tcpdump 1 ,
f1e85027 201.Xr bpf 4 ,
9bf37d9d 202.Xr carp 4 ,
f1e85027
SS
203.Xr inet 4 ,
204.Xr inet6 4 ,
205.Xr netintro 4 ,
206.Xr pf 4 ,
207.Xr pf.conf 5 ,
208.Xr protocols 5 ,
b958492b 209.Xr ifconfig 8
f1e85027
SS
210.Sh HISTORY
211The
212.Nm
213device first appeared in
214.Ox 3.3
215and was imported into
216.Dx 1.1
217by Devon H. O'Dell and Simon Schubert.