1.\" $OpenBSD: pfsync.4,v 1.27 2008/06/03 19:51:02 jmc Exp $ 2.\" 3.\" Copyright (c) 2002 Michael Shalayeff 4.\" Copyright (c) 2003-2004 Ryan McBride 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.\" 27.Dd January 2, 2011 28.Dt PFSYNC 4 29.Os 30.Sh NAME 31.Nm pfsync 32.Nd packet filter state 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 42.Xr tcpdump 1 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 72parameter to 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 is defined in 84.Aq Pa net/pf/if_pfsync.h 85as: 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 syncdev fxp0 102.Ed 103.Pp 104By default, state 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. 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 120.Pp 121It is important that the pfsync traffic be well secured 122as there is no authentication on the protocol and it would 123be trivial to spoof packets which create states, bypassing the pf ruleset. 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 . 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 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 keep state (no-sync) 192pass on { sis0 sis1 } proto carp keep state (no-sync) 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 213.Sh SEE ALSO 214.Xr tcpdump 1 , 215.Xr bpf 4 , 216.Xr carp 4 , 217.Xr inet 4 , 218.Xr inet6 4 , 219.Xr ipsec 4 , 220.Xr netintro 4 , 221.Xr pf 4 , 222.Xr pf.conf 5 , 223.Xr protocols 5 , 224.Xr ifconfig 8 225.\".Xr ifstated 8 , 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. 234