xref: /freebsd/share/man/man4/pfsync.4 (revision 18be782c4e5fcbe4d37a951a6c77c13b3c11b8be)
13b3a8eb9SGleb Smirnoff.\"	$OpenBSD: pfsync.4,v 1.28 2009/02/17 10:05:18 dlg Exp $
23b3a8eb9SGleb Smirnoff.\"
33b3a8eb9SGleb Smirnoff.\" Copyright (c) 2002 Michael Shalayeff
43b3a8eb9SGleb Smirnoff.\" Copyright (c) 2003-2004 Ryan McBride
53b3a8eb9SGleb Smirnoff.\" All rights reserved.
63b3a8eb9SGleb Smirnoff.\"
73b3a8eb9SGleb Smirnoff.\" Redistribution and use in source and binary forms, with or without
83b3a8eb9SGleb Smirnoff.\" modification, are permitted provided that the following conditions
93b3a8eb9SGleb Smirnoff.\" are met:
103b3a8eb9SGleb Smirnoff.\" 1. Redistributions of source code must retain the above copyright
113b3a8eb9SGleb Smirnoff.\"    notice, this list of conditions and the following disclaimer.
123b3a8eb9SGleb Smirnoff.\" 2. Redistributions in binary form must reproduce the above copyright
133b3a8eb9SGleb Smirnoff.\"    notice, this list of conditions and the following disclaimer in the
143b3a8eb9SGleb Smirnoff.\"    documentation and/or other materials provided with the distribution.
153b3a8eb9SGleb Smirnoff.\"
163b3a8eb9SGleb Smirnoff.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
173b3a8eb9SGleb Smirnoff.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
183b3a8eb9SGleb Smirnoff.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
193b3a8eb9SGleb Smirnoff.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
203b3a8eb9SGleb Smirnoff.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
213b3a8eb9SGleb Smirnoff.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF MIND,
223b3a8eb9SGleb Smirnoff.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
233b3a8eb9SGleb Smirnoff.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
243b3a8eb9SGleb Smirnoff.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
253b3a8eb9SGleb Smirnoff.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
263b3a8eb9SGleb Smirnoff.\"
27*18be782cSKajetan Staszkiewicz.Dd October 17, 2023
283b3a8eb9SGleb Smirnoff.Dt PFSYNC 4
293b3a8eb9SGleb Smirnoff.Os
303b3a8eb9SGleb Smirnoff.Sh NAME
313b3a8eb9SGleb Smirnoff.Nm pfsync
323b3a8eb9SGleb Smirnoff.Nd packet filter state table sychronisation interface
333b3a8eb9SGleb Smirnoff.Sh SYNOPSIS
343b3a8eb9SGleb Smirnoff.Cd "device pfsync"
353b3a8eb9SGleb Smirnoff.Sh DESCRIPTION
363b3a8eb9SGleb SmirnoffThe
373b3a8eb9SGleb Smirnoff.Nm
383b3a8eb9SGleb Smirnoffinterface is a pseudo-device which exposes certain changes to the state
393b3a8eb9SGleb Smirnofftable used by
403b3a8eb9SGleb Smirnoff.Xr pf 4 .
413b3a8eb9SGleb SmirnoffState changes can be viewed by invoking
423b3a8eb9SGleb Smirnoff.Xr tcpdump 1
433b3a8eb9SGleb Smirnoffon the
443b3a8eb9SGleb Smirnoff.Nm
453b3a8eb9SGleb Smirnoffinterface.
463b3a8eb9SGleb SmirnoffIf configured with a physical synchronisation interface,
473b3a8eb9SGleb Smirnoff.Nm
483b3a8eb9SGleb Smirnoffwill also send state changes out on that interface,
493b3a8eb9SGleb Smirnoffand insert state changes received on that interface from other systems
503b3a8eb9SGleb Smirnoffinto the state table.
513b3a8eb9SGleb Smirnoff.Pp
523b3a8eb9SGleb SmirnoffBy default, all local changes to the state table are exposed via
533b3a8eb9SGleb Smirnoff.Nm .
543b3a8eb9SGleb SmirnoffState changes from packets received by
553b3a8eb9SGleb Smirnoff.Nm
563b3a8eb9SGleb Smirnoffover the network are not rebroadcast.
573b3a8eb9SGleb SmirnoffUpdates to states created by a rule marked with the
583b3a8eb9SGleb Smirnoff.Ar no-sync
593b3a8eb9SGleb Smirnoffkeyword are ignored by the
603b3a8eb9SGleb Smirnoff.Nm
613b3a8eb9SGleb Smirnoffinterface (see
623b3a8eb9SGleb Smirnoff.Xr pf.conf 5
633b3a8eb9SGleb Smirnofffor details).
643b3a8eb9SGleb Smirnoff.Pp
653b3a8eb9SGleb SmirnoffThe
663b3a8eb9SGleb Smirnoff.Nm
673b3a8eb9SGleb Smirnoffinterface will attempt to collapse multiple state updates into a single
683b3a8eb9SGleb Smirnoffpacket where possible.
693b3a8eb9SGleb SmirnoffThe maximum number of times a single state can be updated before a
703b3a8eb9SGleb Smirnoff.Nm
713b3a8eb9SGleb Smirnoffpacket will be sent out is controlled by the
723b3a8eb9SGleb Smirnoff.Ar maxupd
733b3a8eb9SGleb Smirnoffparameter to ifconfig
743b3a8eb9SGleb Smirnoff(see
753b3a8eb9SGleb Smirnoff.Xr ifconfig 8
763b3a8eb9SGleb Smirnoffand the example below for more details).
773b3a8eb9SGleb SmirnoffThe sending out of a
783b3a8eb9SGleb Smirnoff.Nm
793b3a8eb9SGleb Smirnoffpacket will be delayed by a maximum of one second.
803b3a8eb9SGleb Smirnoff.Sh NETWORK SYNCHRONISATION
813b3a8eb9SGleb SmirnoffStates can be synchronised between two or more firewalls using this
823b3a8eb9SGleb Smirnoffinterface, by specifying a synchronisation interface using
833b3a8eb9SGleb Smirnoff.Xr ifconfig 8 .
843b3a8eb9SGleb SmirnoffFor example, the following command sets fxp0 as the synchronisation
853b3a8eb9SGleb Smirnoffinterface:
863b3a8eb9SGleb Smirnoff.Bd -literal -offset indent
873b3a8eb9SGleb Smirnoff# ifconfig pfsync0 syncdev fxp0
883b3a8eb9SGleb Smirnoff.Ed
893b3a8eb9SGleb Smirnoff.Pp
903b3a8eb9SGleb SmirnoffBy default, state change messages are sent out on the synchronisation
91cc20157dSSevan Janiyaninterface using IP multicast packets to the 224.0.0.240 group address.
923b3a8eb9SGleb SmirnoffAn alternative destination address for
933b3a8eb9SGleb Smirnoff.Nm
943b3a8eb9SGleb Smirnoffpackets can be specified using the
953b3a8eb9SGleb Smirnoff.Ic syncpeer
963b3a8eb9SGleb Smirnoffkeyword.
973b3a8eb9SGleb SmirnoffThis can be used in combination with
983b3a8eb9SGleb Smirnoff.Xr ipsec 4
993b3a8eb9SGleb Smirnoffto protect the synchronisation traffic.
1003b3a8eb9SGleb SmirnoffIn such a configuration, the syncdev should be set to the
1013b3a8eb9SGleb Smirnoff.Xr enc 4
1023b3a8eb9SGleb Smirnoffinterface, as this is where the traffic arrives when it is decapsulated,
1033b3a8eb9SGleb Smirnoffe.g.:
1043b3a8eb9SGleb Smirnoff.Bd -literal -offset indent
1053b3a8eb9SGleb Smirnoff# ifconfig pfsync0 syncpeer 10.0.0.2 syncdev enc0
1063b3a8eb9SGleb Smirnoff.Ed
1073b3a8eb9SGleb Smirnoff.Pp
1083b3a8eb9SGleb SmirnoffIt is important that the pfsync traffic be well secured
1093b3a8eb9SGleb Smirnoffas there is no authentication on the protocol and it would
1103b3a8eb9SGleb Smirnoffbe trivial to spoof packets which create states, bypassing the pf ruleset.
1113b3a8eb9SGleb SmirnoffEither run the pfsync protocol on a trusted network \- ideally a network
1123b3a8eb9SGleb Smirnoffdedicated to pfsync messages such as a crossover cable between two firewalls,
1133b3a8eb9SGleb Smirnoffor specify a peer address and protect the traffic with
1143b3a8eb9SGleb Smirnoff.Xr ipsec 4 .
1153b3a8eb9SGleb Smirnoff.Pp
116*18be782cSKajetan StaszkiewiczWhen new features are introduced to
117*18be782cSKajetan Staszkiewicz.Xr pf 4
118*18be782cSKajetan Staszkiewiczthe format of messages used by
119*18be782cSKajetan Staszkiewicz.Nm
120*18be782cSKajetan Staszkiewiczmight change.
121*18be782cSKajetan Staszkiewicz.Nm
122*18be782cSKajetan Staszkiewiczwill by default use the latest format.
123*18be782cSKajetan StaszkiewiczIf synchronization with a peer running an older version of FreeBSD is needed the
124*18be782cSKajetan Staszkiewicz.Ar version
125*18be782cSKajetan Staszkiewiczparameter can be used.
126*18be782cSKajetan StaszkiewiczE.g.:
127*18be782cSKajetan Staszkiewicz.Bd -literal -offset indent
128*18be782cSKajetan Staszkiewicz# ifconfig pfsync0 version 1301
129*18be782cSKajetan Staszkiewicz.Ed
130*18be782cSKajetan Staszkiewicz.Pp
131*18be782cSKajetan Staszkiewicz.Bd
132*18be782cSKajetan StaszkiewiczCurrently the following versions are supported:
133*18be782cSKajetan Staszkiewicz.Bl -tag -width indent
134*18be782cSKajetan Staszkiewicz.It Cm 1301
135*18be782cSKajetan StaszkiewiczFreeBSD releases 13.2 and older.
136*18be782cSKajetan StaszkiewiczCompatibility with FreeBSD 13.1 has been verified.
137*18be782cSKajetan Staszkiewicz.It Cm 1400
138*18be782cSKajetan StaszkiewiczFreeBSD release 14.0.
139*18be782cSKajetan Staszkiewicz.El
140*18be782cSKajetan Staszkiewicz.Ed
141*18be782cSKajetan Staszkiewicz.Pp
1423b3a8eb9SGleb Smirnoff.Nm
1433b3a8eb9SGleb Smirnoffhas the following
1443b3a8eb9SGleb Smirnoff.Xr sysctl 8
1453b3a8eb9SGleb Smirnofftunables:
1463b3a8eb9SGleb Smirnoff.Bl -tag -width ".Va net.pfsync"
1473b3a8eb9SGleb Smirnoff.It Va net.pfsync.carp_demotion_factor
1483b3a8eb9SGleb SmirnoffValue added to
1493b3a8eb9SGleb Smirnoff.Va net.inet.carp.demotion
1503b3a8eb9SGleb Smirnoffwhile
1513b3a8eb9SGleb Smirnoff.Nm
1523b3a8eb9SGleb Smirnofftries to perform its bulk update.
1533b3a8eb9SGleb SmirnoffSee
1543b3a8eb9SGleb Smirnoff.Xr carp 4
1553b3a8eb9SGleb Smirnofffor more information.
1563b3a8eb9SGleb SmirnoffDefault value is 240.
1574fc65bcbSKristof Provost.It Va net.pfsync.pfsync_buckets
1584fc65bcbSKristof ProvostThe number of
1594fc65bcbSKristof Provost.Nm
1604fc65bcbSKristof Provostbuckets.
1614fc65bcbSKristof ProvostThis affects the performance and memory tradeoff.
1624fc65bcbSKristof ProvostDefaults to twice the number of CPUs.
1634fc65bcbSKristof ProvostChange only if benchmarks show this helps on your workload.
1643b3a8eb9SGleb Smirnoff.El
1653b3a8eb9SGleb Smirnoff.Sh EXAMPLES
1663b3a8eb9SGleb Smirnoff.Nm
1673b3a8eb9SGleb Smirnoffand
1683b3a8eb9SGleb Smirnoff.Xr carp 4
1693b3a8eb9SGleb Smirnoffcan be used together to provide automatic failover of a pair of firewalls
1703b3a8eb9SGleb Smirnoffconfigured in parallel.
1713b3a8eb9SGleb SmirnoffOne firewall will handle all traffic until it dies, is shut down, or is
1723b3a8eb9SGleb Smirnoffmanually demoted, at which point the second firewall will take over
1733b3a8eb9SGleb Smirnoffautomatically.
1743b3a8eb9SGleb Smirnoff.Pp
1753b3a8eb9SGleb SmirnoffBoth firewalls in this example have three
1763b3a8eb9SGleb Smirnoff.Xr sis 4
1773b3a8eb9SGleb Smirnoffinterfaces.
1783b3a8eb9SGleb Smirnoffsis0 is the external interface, on the 10.0.0.0/24 subnet; sis1 is the
1793b3a8eb9SGleb Smirnoffinternal interface, on the 192.168.0.0/24 subnet; and sis2 is the
1803b3a8eb9SGleb Smirnoff.Nm
1813b3a8eb9SGleb Smirnoffinterface, using the 192.168.254.0/24 subnet.
1823b3a8eb9SGleb SmirnoffA crossover cable connects the two firewalls via their sis2 interfaces.
1833b3a8eb9SGleb SmirnoffOn all three interfaces, firewall A uses the .254 address, while firewall B
1843b3a8eb9SGleb Smirnoffuses .253.
1853b3a8eb9SGleb SmirnoffThe interfaces are configured as follows (firewall A unless otherwise
1863b3a8eb9SGleb Smirnoffindicated):
1873b3a8eb9SGleb Smirnoff.Pp
1883b3a8eb9SGleb SmirnoffInterfaces configuration in
1893b3a8eb9SGleb Smirnoff.Pa /etc/rc.conf :
1903b3a8eb9SGleb Smirnoff.Bd -literal -offset indent
1913b3a8eb9SGleb Smirnoffnetwork_interfaces="lo0 sis0 sis1 sis2"
1923b3a8eb9SGleb Smirnoffifconfig_sis0="10.0.0.254/24"
1933b3a8eb9SGleb Smirnoffifconfig_sis0_alias0="inet 10.0.0.1/24 vhid 1 pass foo"
1943b3a8eb9SGleb Smirnoffifconfig_sis1="192.168.0.254/24"
1953b3a8eb9SGleb Smirnoffifconfig_sis1_alias0="inet 192.168.0.1/24 vhid 2 pass bar"
1963b3a8eb9SGleb Smirnoffifconfig_sis2="192.168.254.254/24"
1973b3a8eb9SGleb Smirnoffpfsync_enable="YES"
1983b3a8eb9SGleb Smirnoffpfsync_syncdev="sis2"
1993b3a8eb9SGleb Smirnoff.Ed
2003b3a8eb9SGleb Smirnoff.Pp
2013b3a8eb9SGleb Smirnoff.Xr pf 4
2023b3a8eb9SGleb Smirnoffmust also be configured to allow
2033b3a8eb9SGleb Smirnoff.Nm
2043b3a8eb9SGleb Smirnoffand
2053b3a8eb9SGleb Smirnoff.Xr carp 4
2063b3a8eb9SGleb Smirnofftraffic through.
2073b3a8eb9SGleb SmirnoffThe following should be added to the top of
2083b3a8eb9SGleb Smirnoff.Pa /etc/pf.conf :
2093b3a8eb9SGleb Smirnoff.Bd -literal -offset indent
2103b3a8eb9SGleb Smirnoffpass quick on { sis2 } proto pfsync keep state (no-sync)
2113b3a8eb9SGleb Smirnoffpass on { sis0 sis1 } proto carp keep state (no-sync)
2123b3a8eb9SGleb Smirnoff.Ed
2133b3a8eb9SGleb Smirnoff.Pp
2143b3a8eb9SGleb SmirnoffIt is preferable that one firewall handle the forwarding of all the traffic,
2153b3a8eb9SGleb Smirnofftherefore the
2163b3a8eb9SGleb Smirnoff.Ar advskew
2173b3a8eb9SGleb Smirnoffon the backup firewall's
2183b3a8eb9SGleb Smirnoff.Xr carp 4
2193b3a8eb9SGleb Smirnoffvhids should be set to something higher than
2203b3a8eb9SGleb Smirnoffthe primary's.
2213b3a8eb9SGleb SmirnoffFor example, if firewall B is the backup, its
2223b3a8eb9SGleb Smirnoffcarp1 configuration would look like this:
2233b3a8eb9SGleb Smirnoff.Bd -literal -offset indent
2243b3a8eb9SGleb Smirnoffifconfig_sis1_alias0="inet 192.168.0.1/24 vhid 2 pass bar advskew 100"
2253b3a8eb9SGleb Smirnoff.Ed
2263b3a8eb9SGleb Smirnoff.Pp
2273b3a8eb9SGleb SmirnoffThe following must also be added to
2283b3a8eb9SGleb Smirnoff.Pa /etc/sysctl.conf :
2293b3a8eb9SGleb Smirnoff.Bd -literal -offset indent
2303b3a8eb9SGleb Smirnoffnet.inet.carp.preempt=1
2313b3a8eb9SGleb Smirnoff.Ed
2323b3a8eb9SGleb Smirnoff.Sh SEE ALSO
233923544aaSBaptiste Daroussin.Xr tcpdump 1 ,
2343b3a8eb9SGleb Smirnoff.Xr bpf 4 ,
2353b3a8eb9SGleb Smirnoff.Xr carp 4 ,
2363b3a8eb9SGleb Smirnoff.Xr enc 4 ,
2373b3a8eb9SGleb Smirnoff.Xr inet 4 ,
2383b3a8eb9SGleb Smirnoff.Xr inet6 4 ,
2393b3a8eb9SGleb Smirnoff.Xr ipsec 4 ,
2403b3a8eb9SGleb Smirnoff.Xr netintro 4 ,
2413b3a8eb9SGleb Smirnoff.Xr pf 4 ,
2423b3a8eb9SGleb Smirnoff.Xr pf.conf 5 ,
2433b3a8eb9SGleb Smirnoff.Xr protocols 5 ,
2443b3a8eb9SGleb Smirnoff.Xr rc.conf 5 ,
245923544aaSBaptiste Daroussin.Xr ifconfig 8
2463b3a8eb9SGleb Smirnoff.Sh HISTORY
2473b3a8eb9SGleb SmirnoffThe
2483b3a8eb9SGleb Smirnoff.Nm
2493b3a8eb9SGleb Smirnoffdevice first appeared in
2503b3a8eb9SGleb Smirnoff.Ox 3.3 .
2513b3a8eb9SGleb SmirnoffIt was first imported to
2523b3a8eb9SGleb Smirnoff.Fx 5.3 .
2533b3a8eb9SGleb Smirnoff.Pp
2543b3a8eb9SGleb SmirnoffThe
2553b3a8eb9SGleb Smirnoff.Nm
2563b3a8eb9SGleb Smirnoffprotocol and kernel implementation were significantly modified in
2573b3a8eb9SGleb Smirnoff.Fx 9.0 .
2583b3a8eb9SGleb SmirnoffThe newer protocol is not compatible with older one and will not interoperate
2593b3a8eb9SGleb Smirnoffwith it.
260