|
| 1 | +# HA Sync |
| 2 | + |
| 3 | +The REST API package supports High Availability (HA) synchronization, allowing you to automatically replicate your |
| 4 | +REST API settings from one pfSense host to one or more remote peers. This is especially useful in HA deployments where |
| 5 | +you want all nodes to share the same REST API configuration without having to configure each host manually. |
| 6 | + |
| 7 | +!!! Important |
| 8 | + HA sync only synchronizes the **REST API package settings** (such as authentication methods, allowed interfaces, |
| 9 | + JWT expiration, and other options found under the REST API settings). It does not synchronize the rest of the |
| 10 | + pfSense configuration. Use pfSense's built-in HA/XMLRPC configuration sync for the base system configuration. |
| 11 | + |
| 12 | +## How It Works |
| 13 | + |
| 14 | +When HA sync is enabled and one or more sync hosts are defined, the source host will push its REST API settings to each |
| 15 | +configured peer whenever those settings change. Each peer receives the sync request and applies the incoming settings |
| 16 | +to its own REST API configuration. |
| 17 | + |
| 18 | +## Requirements |
| 19 | + |
| 20 | +Before enabling HA sync, ensure the following: |
| 21 | + |
| 22 | +- The REST API package is installed on every host that will participate in synchronization. |
| 23 | +- A dedicated user exists on **every** peer defined in the sync hosts list. This user must hold the `page-all` |
| 24 | + privilege and must use the same username and password across all hosts. |
| 25 | +- Each peer is reachable from the source host over HTTPS (the webConfigurator port). |
| 26 | +- If certificate validation is enabled, each peer's webConfigurator must present a certificate trusted by the source |
| 27 | + host. |
| 28 | + |
| 29 | +!!! Warning |
| 30 | + It is expected that the source host and each of its peers are as identical as possible. Changes between REST API |
| 31 | + versions or pfSense versions may make the synced configurations incompatible with the remote peers. Additionally, |
| 32 | + some settings (such as the allowed interfaces) are configuration-specific, and it is expected that those interfaces |
| 33 | + also exist on each remote peer. |
| 34 | + |
| 35 | +## Configuring HA Sync on the Source Host |
| 36 | + |
| 37 | +Follow these steps on the host that will send its REST API settings to peers: |
| 38 | + |
| 39 | +1. In the webConfigurator, navigate to **System > REST API > Settings**. |
| 40 | +2. Enable the **HA Sync** toggle. This allows the host to both send sync requests to peers and accept incoming sync |
| 41 | + requests from peers. |
| 42 | +3. In the **HA Sync Hosts** field, enter the IP address or hostname of each remote peer that should receive this host's |
| 43 | + REST API settings. You may define up to 10 hosts. |
| 44 | +4. Set the **HA Sync Username** to the username of the account used to authenticate sync requests. This user must exist on |
| 45 | + every peer and hold the `page-all` privilege. |
| 46 | +5. Set the **HA Sync Password** to the password for the HA username. This must match on all peers. |
| 47 | +6. (Recommended) Leave **HA Sync Validate Certs** enabled to validate each peer's webConfigurator certificate. This |
| 48 | + helps mitigate Man-in-the-Middle attacks. If you disable it, certificate validation will be skipped. |
| 49 | +7. Save your changes. |
| 50 | + |
| 51 | +## Configuring HA Sync on Remote Peers |
| 52 | + |
| 53 | +Repeat the following on **every** remote peer listed in the source host's **HA Sync Hosts** field: |
| 54 | + |
| 55 | +1. In the webConfigurator, navigate to **System > REST API > Settings**. |
| 56 | +2. Enable the **HA Sync** toggle. A peer will reject incoming sync requests by default unless the HA Sync toggle is enabled on that |
| 57 | + peer. |
| 58 | +3. Ensure the HA sync user (with the `page-all` privilege) exists on the peer and uses the same username and password |
| 59 | + as configured on the source host. |
| 60 | +4. Save your changes. |
| 61 | + |
| 62 | +Once HA Sync is enabled on both the source host and all peers, any change to the source host's REST API settings will |
| 63 | +automatically be synchronized to each configured peer. |
| 64 | + |
| 65 | +## Configuring HA Sync via the REST API |
| 66 | + |
| 67 | +All HA sync options are also available through the REST API settings endpoint, so you can automate HA sync configuration |
| 68 | +as part of your provisioning workflow. The relevant settings include: |
| 69 | + |
| 70 | +- `ha_sync` — Enables or disables HA sync on the host. Must be enabled on both the sending and receiving hosts. |
| 71 | +- `ha_sync_validate_certs` — Enables or disables certificate validation when syncing to peers. |
| 72 | +- `ha_sync_hosts` — A list of IP addresses or hostnames to sync REST API settings to. |
| 73 | +- `ha_sync_username` — The username used to authenticate sync requests. Must hold the `page-all` privilege on all peers. |
| 74 | +- `ha_sync_password` — The password for the HA sync user. Must match across all peers. |
0 commit comments