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