Config-Sync Configuration

The Config-Sync feature can be used for Solace Appliance Event Brokers or Solace Software Event Brokers to automatically synchronize:

• configuration properties between event brokers in high-availability (HA) pairs.
• replication‑enabled Message VPNs on one replication site with the corresponding Message VPNs on its mate replication site.

To begin using Config-Sync for HA, or replication deployments, you must do the following:

1. Enable Guaranteed Messaging on each event broker that will use Config-Sync. See System-Level Message Spool Configuration.
2. Enable Config-Sync on each event broker. See Enabling Config-Sync.
3. If you are configuring an HA pair, you must also assert one event broker’s system configuration over its mate. See Asserting Event Broker System Configurations.

Enabling Config-Sync

For HA deployments, Config-Sync must be enabled for both event brokers in the HA pair. For software event broker HA groups, do not enable Config-Sync for the monitoring nodes.

For replication deployments, Config-Sync must be enabled for each event broker in both replication sites (regardless of whether or not HA redundancy is also used).

• To enable Config-Sync for an event broker, enter the following commands:

  solace(configure)# config-sync
  solace(configure/config-sync)# no shutdown

• To disable Config-Sync for an event broker, enter the following commands:

  solace(configure)# config-sync
  solace(configure/config-sync)# shutdown

Asserting Event Broker System Configurations

When enabling Config-Sync for the first time on an HA pair, you must assert the system-level configuration of one event broker over its mate. This "leader" event broker is typically the primary event broker in the pair.

After Config-Sync is running, if the two configurations get out of sync, you can also assert one event broker's system-level configuration over its mate's.

To assert the system-level settings of the event broker that you are currently logged on to over its HA mate, enter the following commands:

solace1> enable
solace1# admin
solace1(admin)# config-sync
solace1(admin/config-sync)# assert-leader router

After asserting the system-level configuration of one event broker over its mate, the output for show config-sync command should show the "Oper Status" of Config-Sync as "Up" on both primary and backup event brokers.

Resynchronizing Leaders After Errors

If the Config-Sync facility receives an error code when executing a configuration command, the affected configuration table will enter a blocked state. In some situations, to clear this error it may be necessary to abandon the pending configuration changes and resynchronize a leader’s configuration with another leader using the following commands:

solace# admin
solace(admin)# config-sync
solace(admin/config-sync)# resync-leader {router | message-vpn <vpn‑name>}

Where:

router specifies to overwrite the system-level configuration parameters for the event broker that you are currently logged on to with the leader configuration parameters held by its redundant mate.

message-vpn <vpn-name> is the name of a Message VPN on the event broker that you are currently logged on to. The configuration information for this Message VPN will be overwritten by a leader Message VPN of the same name on the event broker’s redundant mate or, if it is applicable, its replication mate (standalone or HA pair). This value may contain wildcards.

Asserting Event Brokers VPN Configurations

If there is a need to manually synchronize a Message VPN configuration between two event brokers, you can assert the Message VPN configuration of one of the event brokers (it doesn’t have to be on the leader or primary event broker) over the configuration of the same Message VPN on its mate.

To assert the Message VPN-level settings of the event broker that you are currently logged on to over its HA mate, enter the following commands:

solace1> enable
solace1# admin
solace1(admin)# config-sync
solace1(admin/config-sync)# assert-leader message-vpn <vpn-name>

Where:

<vpn-name> is the Message VPN name, which may contain wildcards.

Then press Y when prompted to continue.

It is also possible to "pull" leader Message VPN configurations from one replication mate to the other. When logged in to the event broker that requires a leader VPN configuration, enter the following command:

solace2(admin/config-sync)# resync-follower message-vpn <vpn-name>

Properties That Are Not Synchronized

Config-Sync does not automatically synchronize all configuration properties because the values for some objects/properties are considered to be unique to an event broker, or related to licensing or security. These objects/properties must be manually configured for each event broker. Examples of objects/properties that are not synchronized are an event brokerʼs hostname and shutdown state.

To determine whether an object/property is automatically synchronized, you can look up the command used to define or set the configuration parameter in the Solace Event Broker CLI Command Reference. In the displayed help for the command, a CONFIG-SYNC: section lists whether the parameter is synchronized by the Config-Sync process.

When you are using the Solace Event Broker CLI, end a command with the "?" character to confirm whether the property affected by that command parameter is synchronized.

Or, you can click below to access the Config-Sync Reference for a list of all the current configuration settings that are automatically synchronized:

• Appliance Event Broker Config-Sync Reference
• Software Event Broker Config-Sync Reference

Checking Whether VPN Configurations Are the Same

To check if both mates in an HA pair have same Message VPN configurations, perform the following steps:

1. For each Message VPN on each event broker, display the CLI commands used to configure the Message VPNs, and redirect the output to a file.

   solace1> show current-config message-vpn <vpn-name> > configs/solace1.txt
   solace2> show current-config message-vpn <vpn-name> > configs/solace2.txt

2. Copy the configuration files and transfer them to a host machine where they can be compared.

   solace1> enable
   solace1# copy configs/solace1.txt sftp://<username>@<host>

    

   solace2> enable
   solace2# copy configs/solace2.txt sftp://<username>@<host>

3. Use a diff tool to compare the two Message VPN configuration files for each event broker.

   For example, on a Linux host, you could enter the following:

   diff configs_solace1.txt configs_solace2.txt

4. If Message VPN configurations don’t match, you can do either of the following:
   • Manually adjust the Message VPNs’ configurations (through Solace Event Broker CLI commands or SolAdmin). This is only recommended for minor changes. Also note that manual adjustments to Message VPN configurations must be done before Config-Sync is enabled.
   • Enable Config-Sync for the event brokers and assert the configuration of each Message VPN with the configuration that you want over that of the Message VPN of the same name on the redundant mate (see Asserting Event Brokers VPN Configurations).

Advanced Config-Sync Configurations

This section provides information for modifying some advanced Config-Sync configuration parameters.

Enabling Config-Sync for Management User Commands

By default, Config-Sync automatically synchronizes any CLI user and file transfer user configuration changes made through username CONFIG commands. However, you can optionally disable the synchronization of username CONFIG commands.

• To enable the Config-Sync facility for the event broker, enter the following commands:

  solace(configure)# config-sync
  solace(configure/config-sync)# synchronize
  solace(configure/config-sync/synchronize)# username

• To disable Config-Sync for the event broker, enter the following commands:

  solace(configure)# config-sync
  solace(configure/config-sync)# synchronize
  solace(configure/config-sync/synchronize)# no username

  If you change from not synchronizing username CONFIG commands to synchronizing them, the mate event brokers will fall out of sync. To bring the redundant pair back in sync, run the assert-leader router Admin EXEC command on the event broker with the correct configuration (see Asserting Event Broker System Configurations.)

Enabling Config-Sync for Client Certificates

In version 10.26.2 and later, event brokers support the ability to synchronize client certificates. When client certificate synchronization is enabled, these certificates are transmitted to peer event brokers over the encrypted Config-Sync channel. This eliminates the need to manually copy certificate files to backup nodes or replication sites.

Client certificate synchronization is available at two scopes:

• Global scope: Synchronizes client certificates for OAuth profiles, DMR cluster links, and replication bridges.
• Message VPN scope: Synchronizes client certificates for Message VPN bridges, REST consumers, and Kafka sender and receivers.

Global-Scope Client Certificate Synchronization

Global-scope synchronization applies to client certificates configured outside of a Message VPN, including OAuth profile, DMR cluster link, and replication bridge certificates. This setting requires global/read-write privilege.

• To enable global-scope client certificate synchronization, enter the following commands:

  solace(configure)# config-sync
  solace(configure/config-sync)# synchronize
  solace(configure/config-sync/synchronize)# client-certificate

• To disable global-scope client certificate synchronization, enter the following commands:

  solace(configure)# config-sync
  solace(configure/config-sync)# synchronize
  solace(configure/config-sync/synchronize)# no client-certificate

After enabling global-scope client certificate synchronization, the mate event brokers will fall out of sync. To bring them back in sync, and to synchronize any certificates that were configured before it was enabled, run assert-leader router on the active event broker. For details, see Asserting Event Broker System Configurations.

Message VPN-Scope Client Certificate Synchronization

Message VPN-scope synchronization applies to client certificates configured within a Message VPN, including Message VPN bridge, REST consumer, and Kafka sender and receiver certificates. Each Message VPN is configured independently. This setting requires global/mesh-manager privilege.

• To enable VPN-scope client certificate synchronization, enter the following commands:

  solace(configure)# message-vpn <vpn-name>
  solace(configure/message-vpn)# config-sync
  solace(configure/message-vpn/config-sync)# synchronize
  solace(configure/message-vpn/config-sync/synchronize)# client-certificate

• To disable VPN-scope client certificate synchronization, enter the following commands:

  solace(configure)# message-vpn <vpn-name>
  solace(configure/message-vpn)# config-sync
  solace(configure/message-vpn/config-sync)# synchronize
  solace(configure/message-vpn/config-sync/synchronize)# no client-certificate

After enabling VPN-scope client certificate synchronization, the mate event brokers will fall out of sync. To bring them back in sync, and to synchronize any certificates that were configured before it was enabled, run assert-leader message-vpn <vpn-name> on the active event broker. For details, see Asserting Event Brokers VPN Configurations.

Modifying Config-Sync Client Profiles’ TCP Connect Parameters

Config-Sync uses a system-created Config-Sync client (#config‑sync) to transmit configuration messages between event brokers. Although the default TCP connection parameters used by this client’s client profile should be suitable for most implementations, you can modify them as you would for any other client profile.

Config-Sync does not propagate any changes made to the TCP connection parameters for the #config‑sync client on one event broker to its redundant mate. Therefore, to ensure proper operation of the Config-Sync feature, if you make any changes to the TCP connection parameters for one event broker’s #config-sync client profile, you must manually make the same changes to the mate’s #config-sync client profile.

To modify the TCP connection parameters for the #config-sync client profile, enter the following commands:

solace(configure)# config-sync
solace(configure/config-sync)# client-profile
solace(configure/config-sync/client-profile)# tcp

The CLI is now at a command level from which you can modify the TCP connection parameters for the #config-sync client. For information, see TCP Settings.

Modifying Config-Sync Secure Authentication Parameters

If you are using client certificate authentication for Config-Sync, you can specify the maximum allowed depth of certificate chains and whether the dates listed in certificates will be strictly validated.

For more detail on configuring certificate validation settings, refer to Configuring Server Certificate Validation Settings.

Maximum Certificate Chain Depth

To set the maximum depth allowed for a certificate chain, enter the following commands:

solace(configure)# config-sync
solace(configure/config-sync)# authentication client-certificate
solace(...ync/authentication/client-certificate)# max‑certificate‑chain-depth <max-depth>

Where:

<max-depth> is a number from 0 to 8 specifying the maximum number of signing CA certificates that may be present in the certificate chain. The default value is 3.

The no version of this command (no max-certificate-chain-depth) resets this parameter to its default value.

Validate Certificate Date

Certificates may specify a time range for which they are valid. This setting will enable or disable the validation of these dates. If disabled, a certificate will be accepted even if the valid date range provided in the certificate is not fulfilled.

To enable validation of certificate dates for Config-Sync, enter the following commands:

solace(configure)# config-sync
solace(configure/config-sync)# authentication client-certificate
solace(...ync/authentication/client-certificate)# validate‑certificate-date

By default, validate-certificate-date is enabled.

The no version of this command (no validate-certificate-date) disables validation of the “not before” and “not after” dates in certificates.

Viewing Config-Sync Info

To view the Config-Sync information for event brokers, enter the following command:

solace> show config-sync [database [router | message-vpn <vpn-name>] [detail | remote]]

Where:

database router asks to display system-level Config-Sync information for the given event broker.

database message-vpn <vpn-name> asks to display only the Message VPN‑level Config-Sync information for the given Message VPN name. <vpn-name> is the Message VPN name, which may contain wildcards.

detail asks to display details for the given system- or Message VPN-level Config-Sync information.

remote asks to display the latest information known about the configuration of other event brokers using Config-Sync. For example, it may display an event broker’s HA mate and all of its known Message VPN configuration. It may also show replicated Message VPNs.

To view the client certificate synchronization status for a specific Message VPN, use show message-vpn <vpn-name>. The output includes a Config-Sync section showing whether client certificate synchronization is enabled for that Message VPN.

In HA deployments, the role of the event broker and Message VPNs in the Config-Sync database of both HA mates is always Leader. Only replication-enabled Message VPNs on standby replication mates can have Follower roles.

Troubleshooting Client Certificate Synchronization

This section describes common conditions that prevent client certificate synchronization and the steps to resolve them.

Event Brokers Report Out-of-Sync

If show config-sync shows an out-of-sync state for event brokers that include client certificates, check the following:

• Synchronization is not enabled: Verify that client certificate synchronization is enabled for the correct scope. See Enabling Config-Sync for Client Certificates.
• Mixed-version deployment: If a peer event broker does not support client certificate synchronization, the affected event brokers remain out-of-sync until all peers are upgraded. Upgrade all peers, then run assert-leader.
• assert-leader not run after enabling synchronization: Certificates that were configured before synchronization was enabled are not automatically synchronized when the it is enabled. Run assert-leader router or assert-leader message-vpn <vpn-name> on the active event broker. For details, see Asserting Event Broker System Configurations.

Out-of-Sync Persists After Running assert-leader

If event brokers remain out-of-sync after running assert-leader, check the event logs for a specific error condition. Common causes include the peer event broker not supporting encrypted Config-Sync, or the peer running a version that predates this feature. If the issue cannot be resolved, contact Solace.