1.\" $OpenBSD: pfsync.4,v 1.14 2004/03/21 19:47:59 miod Exp $ 2.\" $DragonFly: src/share/man/man4/pfsync.4,v 1.6 2007/11/03 18:37:42 swildner Exp $ 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.\" 27.Dd April 9, 2007 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 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 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 84.In net/pf/if_pfsync.h 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 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 199.Sh SEE ALSO 200.Xr tcpdump 1 , 201.Xr bpf 4 , 202.Xr carp 4 , 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 , 209.Xr ifconfig 8 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. 218