High Availability Synchronization Settings

High Availability Synchronization settings for pfSense® software are located in the GUI at System > High Avail. Sync.

This document covers the settings on that page, but the general topics are covered in more detail throughout this chapter.

State Synchronization Settings (pfsync)

The settings in this section control the behavior of state synchronization and related functions. State synchronization allows firewalls acting as HA nodes to exchange state data so that all nodes in the cluster have knowledge about network connections, not just the active node.

The state synchronization settings should be enabled on all members of an HA cluster.

See also

For details on how state synchronization operates, see State Synchronization (pfsync) Overview.

Synchronize States

Controls whether or not this firewall will perform state synchronization with other HA nodes on a shared segment.

When checked, the firewall will perform state synchronization on the Synchronize Interface.

Synchronize Interface

Controls which interface the firewall uses to send and receive state synchronization data with other HA nodes. This interface must have an IP address.

The best practice is to use an interface directly linked between the HA nodes, or at least connected through a switch using an isolated VLAN.

Warning

pfsync does not support any method of authentication. If this option is set to anything other than an isolated segment it is possible for a user with access to the network on that interface to manipulate the state table. For example, they could insert states into the state table.

Filter Host ID

This option defines a custom pf host identifier carried in state data to uniquely identify which host created a firewall state.

Note

Each node participating in state synchronization must have a different filter host ID.

The host IDs from state data are shown on the CARP status page which allows administrators to check if an HA node is exchanging state data with other HA nodes.

Using a custom value is ideal but not required. On current versions of pfSense software the default is to use the last 8 characters of the host NDI. On previous versions the default behavior was to generate a randomized value on every filter reload.

The host ID value must be a non-zero hexadecimal string 8 characters or less (e.g. 1, 2, ff01, abcdef01).

pfsync Synchronize Peer IP

The IP address to which this firewall will send state synchronization data.

If left blank, the firewall will send state data using multicast to all hosts on the chosen Synchronize Interface.

In practice, state synchronization is more reliable when sent directly and not via multicast.

Configuration Synchronization Settings (XMLPRC Sync)

These settings control the behavior of XMLRPC configuration synchronization. XMLRPC configuration synchronization copies settings from supported sections of the configuration from a primary node to a secondary node.

Warning

XMLRPC configuration synchronization must only be enabled on the primary node! It is not possible to synchronize settings from a secondary node back to the primary node.

Warning

The interfaces on both nodes must be assigned identically, for example: wan=WAN, lan=LAN, opt1=Sync, opt2=DMZ. Check the config.xml contents directly to ensure a match.

If the interfaces do not match up exactly, firewall rules and other configuration items will appear to synchronize to the wrong interface on the secondary node. Additionally, this can also lead to failures in DHCP failover.

See also

For details on how XMLRPC configuration synchronization operates, see pfSense Software XMLRPC Config Sync Overview.

Synchronize Config to IP

The IP address of the firewall to which this node will synchronize its configuration via XMLRPC.

There are a few requirements for this to work properly:

  • The target firewall must be running the same version of pfSense software

  • The target firewall GUI must be running the same protocol (HTTPS or HTTP)

  • The target firewall GUI must be running on the same port (e.g. 443 or 80)

Remote System Username

The username to use for authenticating against the target firewall.

The sync user must either be admin or an account on the target firewall with the System - HA node sync privilege.

Note

If XMLRPC is configured to synchronize users, create the sync user on the secondary manually first, as well as on the primary. The redundant copy on the secondary will be removed during the first successful synchronization, but the initial synchronization cannot succeed without it.

Remote System Password

The password to use for authenticating against the target firewall.

Synchronize Admin

Controls whether or not the primary node will synchronize its admin account to the target node.

By default, the XMLRPC process does not synchronize the admin account, which allows each HA node to have a different password for its admin account.

Note

When set, this option automatically updates Remote System Password when the password changes on the Remote System Username account.

Options to Synchronize

This part of the options is a list of configuration sections which XMLRPC configuration synchronization can copy to the target node. These sections include:

User manager users and groups:

Synchronizes users and groups defined in the user manager.

If users have associations to certificates (e.g. for OpenVPN), then certificates should also be synchronized.

Authentication servers:

Synchronizes Authentication servers defined in the User Manager settings. For example, LDAP and RADIUS server entries and their settings.

If these entries require SSL/TLS and are set to use a certificate, then certificates should also be synchronized.

Certificate Authorities, Certificates, and Certificate Revocation Lists:

Synchronizes the contents of the Certificate Manager.

This replaces the entire contents of the certificate manager on the target node, which may also cause it to replace the GUI certificate. There are multiple methods to work around this, such as:

  • Use the same GUI certificate on both nodes after performing an initial synchronization.

  • Import the GUI cert for the secondary into the primary node, allow it to synchronize, and then re-select it on the secondary node.

  • Create a new certificate on the primary node and then select it for use on the secondary after it synchronizes.

Tip

Certificates are synchronized when changed, but services depending on those certificates are not automatically restarted. When renewing certificates, services on the secondary which are running must be manually restarted. For example, if the GUI certificate is renewed, then the GUI must manually be restarted on the secondary node.

Firewall rules:

Synchronizes the contents of all firewall rule tabs, including assigned interfaces, floating rules, interface groups, VPNs, etc.

If any firewall rules utilize aliases or schedules, those sections should also be set to synchronize.

Firewall schedules:

Synchronizes defined firewall schedules.

Firewall aliases:

Synchronizes the contents of aliases.

NAT configuration:

Synchronizes the contents of NAT rules, including outbound NAT, port forwards, 1:1 NAT, etc.

IPsec configuration:

Synchronizes the contents of IPsec tunnels.

If any IPsec tunnels use certificates for authentication, then certificates should also be synchronized.

OpenVPN configuration:

Synchronizes the contents of all OpenVPN instances (clients and servers).

When enabled this also synchronizes the contents of the certificate manager as OpenVPN configurations require the use of certificates.

DHCP Server settings:

Synchronizes the contents of the IPv4 DHCP server settings.

This synchronization process automatically adjusts the value of Failover Peer IP for each DHCP interface. See DHCPv4 Server for details.

DHCP Relay settings:

Synchronizes the contents of the IPv4 DHCP relay settings.

DHCPv6 Relay settings:

Synchronizes the contents of the IPv6 DHCP relay settings.

WoL Server settings:

Synchronizes the contents of Wake on LAN.

Static Route configuration:

Synchronizes the contents of gateways and static routes.

Virtual IPs:

Synchronizes the contents of Virtual IP addresses.

Different types of VIPs behave differently with regard to synchronization and some do not synchronize at all. See Virtual IP Addresses for details.

Traffic Shaper configuration:

Synchronizes the contents of the ALTQ traffic shaper.

If firewall rules reference ALTQ traffic shaper queues, this should be enabled.

Traffic Shaper Limiters configuration:

Synchronizes the contents of Limiters.

If firewall rules reference Limiters, this should be enabled.

DNS Forwarder and DNS Resolver configurations:

Synchronizes the contents of the DNS Resolver and DNS Forwarder.

Captive Portal:

Synchronizes the contents of Captive Portal, which includes additional exchanges of portal user and voucher usage data between HA nodes.