System-Level Message Spool Configuration

This section provides information on the system-level message spool parameters that you can configure for the Solace PubSub+ event broker. These parameters are critical to the operation of Guaranteed Messaging. This section also provides information on how to enable or disable message spooling for an event broker.

In addition to configuring the message spool parameters when using Guaranteed Messaging, it is important to consider the maximum number of messages that the event broker can store in the message spool. You can increase the number of queue messages supported by the event broker using the max-queue-messages system scaling parameter. For more information, see Maximum Number of Queue Messages.

Config-Sync will not automatically synchronize the hardware properties. Therefore, if the event broker is being used in a high-availability (HA) pair or in a replicated site, you must manually configure the hardware message-spool properties on each mate event broker or replicated Message VPN.

To determine whether an object or property is synchronized, look up the command used to configure the object or property in the CLI Command Reference, or, in the Solace CLI, end the command with "?". The Help will list whether the object/property is synchronized.

When high-availability (HA) redundant event brokers are used, enable Config-Sync for each event broker in the redundant pair. Enabling Config-Sync can reduce possible configuration and input errors and increase the speed at which Guaranteed Messaging information is handled if a redundancy switchover occurs. For more, see Config-Sync.

Configuring External Disk Arrays

When using Guaranteed Messaging for either a standalone appliance or a redundant pair of appliances, an external disk storage array can be used for spooling messages.

To configure the Worldwide Name (WWN) used when accessing a LUN on an external disk storage array, enter the following CONFIG commands:

solace# configure
solace(configure)# hardware message-spool
solace(configure/hardware/message-spool)# disk-array wwn <wwn>

Where:

wwn <wwn> is the Worldwide Name. If in Network Address Authority (NAA) format, it is a unique 8-byte or 16-byte number represented as a string of hex characters separated by colons starting with 1, 2, 5, or 6 (for example: 50:00:2a:c0:00:f1:33:74 or 60:06:01:60:bf:51:12:00:9a:fb:40:97:83:3f:dc:11). If not in NAA format, it can be any string without colons. The default is Null.

  • Before configuring the WWN for an external disk storage array through the disk-array Message Spool CONFIG command, you must first (in the order given):
    • delete all the messages spooled on the appliance for clients using the delete-messages Message Spool Admin EXEC command
    • enter the shutdown Message Spool CONFIG command to stop message spooling on the appliance (if started)
    • disable the internal disk drive on the appliance for message spooling through the no internal-disk Message Spool CONFIG command
  • The no version of this command (no disk-array) resets the WWN to its default value of Null.
  • For information on how to configure the partitions and file system on the event broker once there is access to the LUN on the external disk storage array, see Configuring an External Disk Array for Guaranteed Messaging.

The file system of an external disk storage array can be corrupted if two or more non-redundant event brokers assert ownership for the same external disk storage array and successfully modify the same file system.

To avoid this, the mounting of the external disk storage array is stopped if a disk ownership conflict is detected, and declares the disk storage array unusable by the display of "Disk Contents Invalid" in the detailed status and usage item summary screen output by the show message-spool detail User EXEC command.

The system administrator can then make one of the event brokers take ownership of the conflicted disk storage array by using the assert-disk-ownership Message Spool Admin EXEC command.

Configuring Event Thresholds for the System Message Spool

To configure the thresholds that control when system-level message spool events are generated for the event broker, enter the following CONFIG commands:

solace# configure
solace(configure)# hardware message-spool
solace(configure/hardware/message-spool)# event

From this level of the CLI, you can now configure the thresholds at which the broker generates system-level events pertaining to the message spool.

For information on the available system-level message-spool events and how to set the thresholds for them, see Configuring System Message Spool Event Thresholds.

Configuring Max Spool Usage

To configure the maximum amount of disk space that can be used to spool messages, enter the following CONFIG commands:

solace# configure
solace(configure)# hardware message-spool
solace(configure/hardware/message-spool)# max-spool-usage <size>

Where:

<size> is an integer that specifies the maximum amount of message spool disk space (in MB) the broker as a whole can use. The valid range is from 0 (in which case spooling is effectively disabled) to the maximum amount of message spool disk space supported for the entire system. For details about the default values for this setting, see Maximum Spool Usage.

The no version of this command, no max-spool-usage, resets the size of the Local Spool Quota for the event broker back to the default value.

When using an external disk storage array for Guaranteed Messaging with a redundant appliance pair, two partitions need to be created on the array—one partition for each appliance. The partition sizes required depend on the maximum size configured for the message spool disk space using this command. A general rule of thumb is to create two partitions that are 1.1 times the maximum size configured for the message spool disk space. For example, if you configure the maximum spool usage for appliances to be 600,000 MB using this command (that is, 600 GB), then Solace recommends you create two partitions on the array sized 600 x 1.1. This equals 660 GB for each partition, for a total of 1,320 GB Logical Unit Number (LUN). For further information, see SAN Behavior for Guaranteed Messaging Through Active/Standby Redundancy. For information on how to configure the partitions and file system on the Solace PubSub+ appliance once there is access to the LUN on the external disk storage array, see Configuring an External Disk Array for Guaranteed Messaging.

Configuring Max Cache Usage

When an event broker is processing Guaranteed messages, its Guaranteed Message Cache can use some of the data buffer resources that are also used for its NAB egress queues (see Message Delivery Resources).

To configure the maximum percentage of the NAB data buffer resources that the Guaranteed Message Cache can use, enter the following CONFIG commands:

solace# configure
solace(configure)# hardware message-spool
solace(configure/hardware/message-spool)# max-cache-usage <percent-usage>

Where:

<percent-usage> is the maximum amount of the NAB data buffers (as a percentage) that the Guaranteed Message Cache is allowed to use. The valid values are 0 (disables the Guaranteed Message Cache feature), or 1 through 50. The default is 10.

The no version of this command, no max-cache-usage, resets the maximum percentage of the NAB data buffers that the Guaranteed message cache can use back to the default value.

When the Guaranteed Message Cache's utilization reaches the maximum limit, the Guaranteed Message Cache is not used to process subsequent Guaranteed messages.

Configuring the Active/Active HA Role for Guaranteed Messaging

If the HA configuration is set to active/active, you must configure the HA role an appliance will take for Guaranteed Messaging.

If the HA configuration is not set to active/active (in other words if the active/standby role is set to something other than none), this setting is ignored by the appliance and has no impact on the Guaranteed Messaging configuration. For more information about the active/standby role, refer to Configuring Redundancy Parameters.

To configure the HA role an appliance will take for Guaranteed Messaging if the HA configuration is set to active/active, enter the following CONFIG commands:

solace# configure
solace(configure)# hardware message-spool
solace(configure/hardware/message-spool)# virtual-router-when-active-active {primary | backup}

Where:

primary sets the HA role to primary. In other words, this enables the message spool for the primary virtual router.

backup sets the HA role to backup. In other words, this enables the message spool for the backup virtual router.

The no version of this command, no virtual-router-when-active-active, resets the HA role back to the default value (primary).

Enabling the Internal Disk for Message Spooling

By default, the internal physical disk drive of a appliance is disabled for message spooling with Guaranteed Messaging, and a customer-supplied external disk storage array must be used for message spooling with Guaranteed Messaging.

Solace recommends using a customer-supplied external disk storage array to support Guaranteed Messaging. Using the internal appliance disk drive for message spooling is not recommended. For more information, contact Solace.

To enable an appliance's internal disk drive for message spooling, enter the following CONFIG commands:

solace# configure
solace(configure)# hardware message-spool
solace(configure/hardware/message-spool)# internal-disk

The no version of this command, no internal-disk, disables the internal disk drive for message spooling.

  • Before changing between internal and external disks through the internal-disk Message Spool CONFIG command, you must first do the following (in the order given):
    1. Reset the message spool. See Resetting the Guaranteed Message Spool for instructions.
    2. Stop message spooling on the event broker (if started) using the shutdown Message Spool CONFIG command.
  • The internal disk drive cannot be enabled for message spooling through the internal-disk Message Spool CONFIG command if event broker redundancy is enabled. In this case, you must first stop the event broker redundancy facility on the event broker (if running) through the shutdown Redundancy CONFIG command:
    • solace(configure)# redundancy
    solace(configure/redundancy)# shutdown

Enabling Guaranteed Message Spooling

  • Always perform message spool state changes within a maintenance window to prevent service interruption.
  • Always disconnect all client connections before changing the message spool state on an event broker. To disconnect a client connection, either close the client Session through the Solace messaging API, or terminate the client application.
  • After message spool state changes are completed on the event broker, clients may reconnect to it.
  • When setting up a network of event brokers for Guaranteed Messaging service, always perform the message spool state changes before configuring neighbor links between the event brokers. Otherwise, they may not advertise their Guaranteed Messaging capabilities correctly to each other.

By default, Guaranteed Message spooling is not enabled for Solace PubSub+ appliances, but it is enabled for Solace PubSub+ software event brokers.

  • To start Guaranteed Message spooling, enter the CONFIG commands: 
    solace# configure
    solace(configure)# hardware message-spool
    solace(configure/hardware/message-spool)# no shutdown
  • To stop Guaranteed Message spooling on the event broker, enter the following CONFIG command: 
    solace(configure/hardware/message-spool)# shutdown
  • The no shutdown primary Message Spool CONFIG command is not allowed if:
    • The no shutdown backup Message Spool CONFIG command has been entered beforehand. In this case, you must enter the shutdown Message Spool CONFIG command first to disable the backup event broker configuration.
    • There are already messages spooled for the backup event broker (that is, backup VRID). In this case, you must first delete all spooled messages for all clients using the delete-messages Message Spool Admin EXEC command.
    • An appliance's internal disk is disabled for message spooling, and the worldwide name (WWN) used when accessing a LUN on an external disk storage array has not been configured beforehand through the disk-array Message Spool CONFIG command. In this case, you must first configure the WWN for the external disk storage array.
  • The no shutdown backup Message Spool CONFIG command is not allowed if:
    • The no shutdown primary Message Spool CONFIG command has been entered beforehand. In this case, you must enter the shutdown Message Spool CONFIG command first to disable the primary event broker configuration.
    • There are already messages spooled for the primary event broker (that is, primary VRID). In this case, you must first delete all spooled messages for all clients using the delete-messages Message Spool Admin EXEC command.
    • The event broker's internal disk drive is enabled for message spooling through the internal-disk Message Spool CONFIG command. In this case, you must first enter the no internal-disk Message Spool CONFIG command to disable the internal disk drive for message spooling.
    • The event broker's internal disk drive is disabled for message spooling through the no internal-disk Message Spool CONFIG command, and the worldwide name (WWN) used when accessing a LUN on an external disk storage array has not been configured beforehand through the disk-array Message Spool CONFIG command. In this case, you must first configure the WWN for the external disk storage array.
  • Running the no shutdown primary or no shutdown backup Message Spool CONFIG commands automatically clear all current statistics for spooled messages.