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 April 21, 2018 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. 108An alternative destination address for 109.Nm 110packets can be specified using the 111.Ic syncpeer 112keyword. 113.Pp 114It is important that the pfsync traffic be well secured 115as there is no authentication on the protocol and it would 116be trivial to spoof packets which create states, bypassing the pf ruleset. 117Either run the pfsync protocol on a trusted network \- ideally a network 118dedicated to pfsync messages such as a crossover cable between two firewalls. 119.Pp 120There is a one-to-one correspondence between packets seen by 121.Xr bpf 4 122on the 123.Nm 124interface, and packets sent out on the synchronisation interface, i.e.\& 125a packet with 4 state deletion messages on 126.Nm 127means that the same 4 deletions were sent out on the synchronisation 128interface. 129However, the actual packet contents may differ as the messages 130sent over the network are "compressed" where possible, containing 131only the necessary information. 132.Sh EXAMPLES 133.Bd -literal -offset indent 134# ifconfig pfsync0 up syncif fxp0 maxupd 64 135# tcpdump -s1500 -evtni pfsync0 136.Ed 137.Sh USING PFSYNC WITH CARP 138.Nm 139and 140.Xr carp 4 141can be used together to provide automatic failover of a pair of firewalls 142configured in parallel. 143One firewall handles all traffic \- if it dies or 144is shut down, the second firewall takes over automatically. 145.Pp 146Both firewalls in this example have three 147.Xr sis 4 148interfaces. 149sis0 is the external interface, on the 10.0.0.0/24 subnet; sis1 is the 150internal interface, on the 192.168.0.0/24 subnet; and sis2 is the 151.Nm 152interface, using the 192.168.254.0/24 subnet. 153A crossover cable connects the two firewalls via their sis2 interfaces. 154On all three interfaces, firewall A uses the .254 address, while firewall B 155uses .253. 156The interfaces are configured as follows (firewall A unless otherwise 157indicated): 158.Pp 159Interfaces configuration in 160.Pa /etc/rc.conf : 161.Bd -literal -offset indent 162network_interfaces="lo0 sis0 sis1 sis2" 163cloned_interfaces="carp0 carp1" 164ifconfig_sis0="10.0.0.254/24" 165ifconfig_sis1="192.168.0.254/24" 166ifconfig_sis2="192.168.254.254/24" 167ifconfig_carp0="vhid 1 pass foo 10.0.0.1/24" 168ifconfig_carp1="vhid 2 pass bar 192.168.0.1/24" 169pfsync_enable="YES" 170pfsync_syncdev="sis2" 171.Ed 172.Pp 173.Xr pf 4 174must also be configured to allow 175.Nm 176and 177.Xr carp 4 178traffic through. 179The following should be added to the top of 180.Pa /etc/pf.conf : 181.Bd -literal -offset indent 182pass quick on { sis2 } proto pfsync keep state (no-sync) 183pass on { sis0 sis1 } proto carp keep state (no-sync) 184.Ed 185.Pp 186If it is preferable that one firewall handle the traffic, 187the 188.Ar advskew 189on the backup firewall's 190.Xr carp 4 191interfaces should be set to something higher than 192the primary's. 193For example, if firewall B is the backup, its 194carp1 configuration would look like this: 195.Bd -literal -offset indent 196ifconfig_carp1="vhid 2 pass bar advskew 100 192.168.0.1/24" 197.Ed 198.Pp 199The following must also be added to 200.Pa /etc/sysctl.conf : 201.Bd -literal -offset indent 202net.inet.carp.preempt=1 203.Ed 204.Sh SEE ALSO 205.Xr tcpdump 1 , 206.Xr bpf 4 , 207.Xr carp 4 , 208.Xr inet 4 , 209.Xr inet6 4 , 210.Xr netintro 4 , 211.Xr pf 4 , 212.Xr pf.conf 5 , 213.Xr protocols 5 , 214.Xr ifconfig 8 215.\".Xr ifstated 8 , 216.Sh HISTORY 217The 218.Nm 219device first appeared in 220.Ox 3.3 221and was imported into 222.Dx 1.1 223by Devon H. O'Dell and Simon Schubert. 224