Config-Sync Configuration

The Config-Sync feature can be used for Solace PubSub+ appliances or Solace PubSub+ software message brokers to automatically synchronize:

  • configuration properties between message 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 message broker that will use Config-Sync. See System-Level Message Spool Configuration.
  2. Enable Config-Sync on each message broker. See Enabling Config-Sync
  3. If you are configuring an HA pair, you must also assert one message broker’s system configuration over its mate. See Asserting Message 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 message broker, while CLI or SEMP configuration changes are made simultaneously on the same endpoints or topic subscriptions on the HA standby message 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 message brokers in the HA pair. For Solace PubSub+ software message broker HA groups, do not enable Config-Sync for the monitoring nodes.

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

  • To enable Config-Sync for a message broker, enter the following commands:

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

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

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

Note:  To use Config-Sync with a standalone message broker at a replication site, you must assign a routing interface for the message 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 message brokers when configuring HA redundancy.

Asserting Message Broker System Configurations

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

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

The assert-master, resync-master, and resync-slave Config-Sync Admin EXEC commands force one message broker’s configuration onto one or more other message 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 message 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 message 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 message 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 message 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 message 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 message 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 message broker or Message VPN with connected clients. This command is intended for use on backup message brokers and Message VPNs.

Asserting Message Brokers VPN Configurations

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

To assert the Message VPN-level settings of the message 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 message 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 message 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 message 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 a message broker, or related to licensing or security. These objects/properties must be manually configured for each message broker. Examples of objects/properties that are not synchronized are a message 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 message 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 message 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 message 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 Message 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 message 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 message 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 message brokers will fall out of sync. To bring the redundant pair back in sync, run the assert-master router Admin EXEC command on the message broker with the correct configuration (see Asserting Message 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 message 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 message 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 message 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 message 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 message 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 message brokers using Config-Sync. For example, it may display a message 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 message 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.