pfSense Software XMLRPC Config Sync Overview

To make the job of maintaining practically identical nodes running pfSense® software easier, configuration synchronization is possible using XMLRPC. When XMLRPC Synchronization is enabled, settings from supported areas are copied from the primary node to the secondary node and activated after each configuration change. XMLRPC Synchronization is optional, but maintaining a cluster is a lot more work without it.

Some areas cannot be synchronized, such as the Interface configuration, but many other areas can: Firewall rules, aliases, users, certificates, VPNs, DHCP, routes, gateways, and more. See Options to Synchronize for a full list. As a general rule, items specific to hardware or a particular installation, such as Interfaces or values under System > General or System > Advanced do not synchronize. The list of supported areas can vary depending on the version of pfSense software in use. For a list of areas that will synchronize, see the checkbox items on System > High Avail Sync in the XMLRPC section. Most packages will not synchronize but some contain their own synchronization settings. Consult package documentation for more details.

Configuration synchronization should use the Sync interface, or if there is no dedicated Sync interface, use the same interface configured for firewall state synchronization.

In a two-node cluster the XMLRPC settings must only be enabled on the primary node, the secondary node must have these settings disabled.

For XMLRPC to function, both nodes must meet the following requirements:

  • The GUI must be running on the same port and protocol, for example: HTTPS on port 443, which is the default setting.

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

    Warning

    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.

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

    Note

    If XMLRPC will 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.