Config-Sync Configuration

The Config-Sync feature can be used for Solace PubSub+ appliances or Solace PubSub+ 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

Solace HA pairs that use Config‑Sync can fall out of synchronization when a client adds or removes endpoints or topic subscriptions on the HA active event broker, while CLI or SEMP configuration changes are made simultaneously on the same endpoints or topic subscriptions on the HA standby event broker.

To avoid this situation, it is recommended that you do one of the following:

Enabling Config-Sync

For HA deployments, Config-Sync must be enabled for both event brokers in the HA pair. For Solace PubSub+ 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

Note:  To use Config-Sync with a standalone event broker at a replication site, you must assign a routing interface for the event broker (see Assigning Routing Interfaces). This step is not required when configuring replication for an HA pair because a routing interface is assigned for the event brokers when configuring HA redundancy.

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 “master” 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.

The assert-master, resync-master, and resync-slave Config-Sync Admin EXEC commands force one event broker’s configuration onto one or more other event brokers. If there is a configuration mismatch between the mate replication sites, this could result in the loss of Guaranteed messages.

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-master 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 Masters 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 master’s configuration with another master using the following commands:

solace# admin
solace(admin)# config-sync
solace(admin/config-sync)# resync-master {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 master 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 master 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.

To avoid message and data loss, the resync-master command should not be run on an active event broker or Message VPN with connected clients. This command is intended for use on backup event brokers and Message VPNs.

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 master 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-master message-vpn <vpn-name>

Where:

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

Then press “Y” when prompted to continue.

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

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

When you assert the configuration information for a Message VPN on one event broker over the Message VPN of the same name on its HA and/or Replication mates, the clients of those Message VPNs on the mate event brokers can be temporarily disconnected. In addition, any in-flight messages to those endpoints on the Message VPNs that are receiving the asserted configuration changes will not be delivered if those endpoints are not configured the same as the endpoints on the Message VPN that is asserted.

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 CLI Command Reference. In the displayed help for the command, a “CONFIG-SYNC:” section will list whether the parameter is Config-Syncʼed.

Tip:  When you are using the Solace 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:

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 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

    Tip:   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-master router Admin EXEC command on the event broker with the correct configuration (see Asserting Event Broker System 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.

Note:  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.

Note:  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.

Note:  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.

Note:  In HA deployments, the ownership of the event broker and Message VPNs in the Config-Sync database of both HA mates is always Master. Only replication-enabled Message VPNs on standby replication mates can have Slave ownership.