Configuring Topic Endpoints

To provision a durable topic endpoint in a given Message VPN, enter the following CONFIG commands:

solace(configure)# message-spool message-vpn <vpn-name>
solace(configure/message-spool)# create topic-endpoint <name>

To edit the properties of an existing, durable topic endpoint on a given Message VPN, enter the following CONFIG command:

solace(configure)# message-spool message-vpn <vpn-name>
solace(configure/message-spool)# topic-endpoint <name>

Where:

<name> is a topic endpoint name of up to 200 characters (the only invalid characters are '<>*?&;). Each topic endpoint name in a Message VPN must be unique.

The no version of this command, no topic-endpoint <name>, deletes the specified durable topic endpoint from the Message VPN. However, the topic endpoint cannot be deleted until it is shut down, which disables client access to the topic endpoint. Refer to Enabling/Disabling Clients from Publishing to/Consuming from Topic Endpoints for more information.

The name for a temporary topic endpoint can be a maximum of 250 characters. A temporary topic endpoint differs from a durable topic endpoint provisioned through the Solace CLI or SolAdmin in that it is dynamically provisioned by a client application and can only exist as long as the client is connected.

The topic subscription that a topic endpoint will spool messages for is not specified when a topic endpoint is provisioned; it is specified by a client when that client requests to bind a consumer flow to the topic endpoint (for information, refer to Creating Flows).

Configuring Access Types

To configure the client access type for durable topic endpoints on the Solace PubSub+ event broker on a per-topic-endpoint basis, enter the following CONFIG command.

solace(configure/message-spool/topic-endpoint)# access-type {exclusive | non-exclusive}

Where:

exclusive specifies that only one client can bind to and be serviced by the topic endpoint; if other consumers attempt to bind, they will be rejected.

non-exclusive specifies that all bound flows are able to receive messages, and when multiple flows are bound to a non-exclusive topic endpoint, they receive messages in a round-robin fashion.

The no version of this command, no access-type, reverts the setting back to the default (exclusive).

The client access type cannot be changed until client access to the durable topic endpoint is shut down (refer to Enabling/Disabling Clients from Publishing to/Consuming from Topic Endpoints).

Configuring Max Number of Flows That May Bind

To configure the maximum number of flows that can bind to a non-exclusive durable topic endpoint on the Solace PubSub+ event broker on a per-topic-endpoint basis, enter the following CONFIG command.

solace(configure/message-spool/topic-endpoint)# max-bind-count <value>

Where:

<value> is an integer value specifying the maximum number of flows that can bind to a non-exclusive durable topic endpoint. If the topic endpoint's access type has been set to exclusive, the value of max-bind-count is considered to be 1 regardless of the set value. The valid range is 0 to 10,000. The default value is 1.

The no version of this command, no max-bind-count, resets the maximum number of flows that can bind to a durable topic endpoint back to the default.

A single client can create multiple flows, and flows may originate from one or more clients.

Configuring Max Number of Delivered Unacked Messages

For a given topic endpoint you can configure the maximum number of Guaranteed messages that can be delivered to a consuming client through a flow but remain unacknowledged by that client. That is, how many outstanding unreturned message acknowledgments are acceptable per flow bound to the topic endpoint.

After this maximum number of delivered but unacknowledged messages is exceeded, the Solace PubSub+ event broker stops delivering messages to the client on the flow until the client acknowledges messages that are already delivered.

To configure a limit for maximum outstanding number of delivered but unacknowledged messages per flow, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# max-delivered-unacked-msgs-per-flow <max>

Where:

<max> is an integer value specifying the maximum number of messages that can be delivered to a client on a subscriber flow but remain unacknowledged by the client. The valid range is 1 to the maximum value supported by the event broker. The maximum value depends on the type of event broker used (for example, Solace PubSub+ 3530 or 3560). The default value is 10000. If the maximum number of delivered but unacknowledged messages amongst all clients is reached, the Solace PubSub+ event broker will stop delivering messages to all clients until some clients return acknowledgments back to the event broker.

The no version of this command, no max-delivered-unacked-msgs-per-flow, resets the maximum number unacknowledged messages back to the default value.

Configuring Max Permitted Message Sizes

To configure the maximum message size allowed for the given topic endpoint, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# max-message-size <size>

Where:

<size> is an integer value specifying the maximum message size (in bytes) permitted for the topic endpoint. The valid range is 0 to 30000000. The default value is 10000000.

The no version of this command, no max-message-size, resets the permitted message size available for use by the topic endpoint back to its default value.

Configuring Max Permitted Redelivery Attempts

You can use the max-redelivery option to configure the maximum number of times the topic endpoint can attempt to redeliver a message to a client. If the number of redelivery attempts for a given message exceeds the max-redelivery value, the message is either discarded, or, if a Dead Message Queue (DMQ) has been created and is ready to accept messages, the message is removed and placed in the DMQ.

To configure the maximum number of times a topic endpoint can attempt to redeliver a message to a client, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# max-redelivery <count>

Where:

<count> is the maximum message redelivery attempts possible. The valid range is 0 to 255. 0 means try forever. The default is 0.

The no version of this command, no max-redelivery, resets the max-redelivery value back to the default value.

Configuring a Message Redelivery Delay

When client applications are consuming messages from an event broker, they may occasionally encounter conditions where they are temporarily unable to process a message. In this scenario, the application may rollback the transaction to force a redelivery of a message.

Redelivering the message immediately often does not help, as it does not allow sufficient time for the transient condition to be resolved. Configuring a message redelivery delay can help in this scenario, by suspending message delivery to the client following a transaction rollback, until a configured redelivery delay time has passed. You can also configure a multiplier to allow for exponential back-off of redelivery attempts.

When you configure a message redelivery delay, it applies only when the broker attempts to redeliver a message to a client following an application-initiated local transaction rollback. Other types of redelivery will occur without a delay.

To configure a message redelivery delay, enter the following command:

solace(configure/message-spool/topic-endpoint)# redelivery-delay

The CLI is now at a level where you can configure the initial interval, maximum interval, and delay interval multiplier the topic endpoint uses when it attempts to redeliver a message to a client following an application-initiated local transaction rollback.

• To configure the initial interval, enter the following command:

  solace(.../message-spool/topic-endpoint/redelivery-delay)# initial-interval <value>

  Where:

  <value> is an integer value specifying the delay between the first two delivery attempts, in milliseconds. The valid range of values is 1 to 3600000. The default is 1000.

  The no form of this command, no inital-interval, resets the value to the default.

• To configure the maximum interval, enter the following command:

  solace(.../message-spool/topic-endpoint/redelivery-delay)# max-interval <value>

  Where:

  <value> is an integer value specifying the maximum delay to be used between any two redelivery attempts, in milliseconds. The valid range of values is 1 to 10800000. The default is 64000.

  The no form of this command, no max-interval, resets the value to the default.

• To configure the delay interval multiplier, enter the following command:

  solace(.../message-spool/topic-endpoint/redelivery-delay)# multiplier <value>

  Where:

  <value> is a floating point value specifying the amount that each delay interval is multiplied by after each failed delivery attempt. The valid range of values is 1.00 to 5.00. The default is 2.00.

  The no form of this command, no multiplier, resets the value to the default.

To enable the message redelivery delay configuration, enter the following command:

solace(.../message-spool/topic-endpoint/redelivery-delay)# no shutdown

To disable the message redelivery delay configuration, enter the following command:

solace(.../message-spool/topic-endpoint/redelivery-delay)# shutdown

Configuring Message Redelivery

By default, the maximum number of times a topic endpoint can attempt to redeliver a message to a client is controlled by the max-redelivery command. For more information, refer to Configuring Max Permitted Redelivery Attempts.

You can instead disable this functionality. When message redelivery is disabled, a given message will only be attempted to be delivered from the topic endpoint once.

To disable message redelivery attempts, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# no redelivery

To enable message redelivery attempts, enter the following CONFIG command.

solace(configure/message-spool/topic-endpoint)# redelivery

Configuring Message Delivery Count

You can use the delivery-count option to enable or disable the delivery count property for messages. When enabled, each message sent from the topic endpoint to a consumer contains a property indicating whether this is the 1^st, 2^nd, … or n^th attempt to deliver the message to a consumer. By default, the delivery count is disabled.

In the case of a redundancy (HA) failover, message counts greater than 1 are reset to 2.

To enable the delivery count for messages on the topic endpoint, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# delivery-count

To disable the delivery count for messages, enter the following CONFIG command.

solace(configure/message-spool/topic-endpoint)# no delivery-count

Configuring Delayed Delivery

By default, messages published to topic endpoints are immediately published to connected consumers. There are many use cases in which published messages must not be delivered to consumers immediately, but delivered only after a fixed delay. One example is a retry mechanism within a payment processing system. After receiving a customer order, you may want to implement a delivery delay to retry credit card transactions when the processing of the transaction fails for any reason. For more information, refer to Delayed Delivery.

You can use the delivery-delay option to configure a delivery delay for a topic endpoint, such that all messages destined to a topic endpoint are not eligible to be delivered for a fixed period of time.

If you are currently using DMQs to implement a delivery delay, contact Solace Professional Services for guidance on migrating your implementation to use the delivery-delay option instead.

To configure a delivery delay on the topic endpoint, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# delivery-delay <delay>

Where:

<delay> is the delay, in seconds, to apply to messages arriving on the topic endpoint before the messages are eligible for delivery. The valid range is 0 to 4294967295. The default is 0.

The no version of this command, no delivery-delay, resets the delivery-delay value back to the default.

Configuring Max Spool Usage Values

To configure the maximum message spool usage for durable topic endpoints on the Solace PubSub+ event broker on a per-topic endpoint basis, enter the following CONFIG command:

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

Where:

<size> is an integer value specifying the maximum amount of message spool disk space permitted for the topic endpoint in MB. Setting the value to 0 is not recommended for topic endpoints.

The no version of this command, no max-spool-usage, resets the default.

For information about the default values for this setting, see Maximum Spool Usage.

Configuring Permissions for Non-Owner Clients

To configure the permission levels for all clients other than the owner of the given durable topic endpoint, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# permission all {read-only | consume | modify-topic | delete}

Where:

read-only provides clients with read-only access permission to messages spooled to the topic endpoint

consume provides clients with read-only permission and the ability to delete messages from the topic endpoint

modify-topic provides clients with consume permission and the ability to modify the topic or selector assigned to the topic endpoint

delete provides clients with modify-topic permission and the ability to either delete messages from the topic endpoint, or delete the topic endpoint altogether. Note that clients cannot delete a topic endpoint if it was created using the CLI or SEMP by a management user.

The no version of this command, no permission, resets the permission levels for all clients other than the owner of the topic endpoint to none; that is, no access. A client access level of none is the default permission level.

Configuring Reject Low‑Priority Message Limits

To configure a reject-low-priority-msg-limit for a topic endpoint, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# reject-low-priority-msg-limit <limit>

Where:

<limit> is the total number of low- and high‑priority messages spooled. When this value is exceed, the topic endpoint discards any further published low-priority messages, but spools published high-priority messages. Valid values are from 0 through 4294967295. If value of 0 is set, the topic endpoint only spools high-priority messages are spooled. The default value is 0.

Configuring Topic Endpoint Event Thresholds

To configure the thresholds that control when message spool-related events are generated for the given topic endpoint, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# event

The CLI is now at a configuration level from which you can configure the set and clear thresholds for various message spool events for the topic endpoint.

For specific information on the available Message VPN-level message spool events that are generated for a topic endpoint and how to set the set and clear thresholds for generating those events, refer to Topic Endpoint Event Thresholds.

Configuring Topic Endpoint Owners

The ownership of a topic endpoint is established in the following manner:

• If a client application dynamically provisions a topic endpoint through a Solace messaging API, the client username associated with the client is automatically given ownership of that topic endpoint.
• If a CLI user manually provisions a topic endpoint through the Solace CLI, no client username is automatically given ownership of that topic endpoint.
• Any CLI user with Read-Write or Admin access to the Message VPN that the topic endpoint belongs to has full permissions on the topic endpoint (that is, management has ownership).

To give ownership of the given topic endpoint to any clients associated with a particular client username, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# owner <owner>

Where:

<owner> is an existing client username account name.

The no version of this command, no owner, resets the ownership of the topic endpoint back to the default of none.

Configuring Message Discard Handling

The reject-msg-to-sender-on-discard option configures how a durable topic endpoint should handle ingress messages discards that occur due to one or more of the following conditions:

• adding the published message will exceed the configured message quota for the topic endpoint
• the published message exceeds the maximum message size allowed for the topic endpoint
• the client published the message to a topic it has also subscribed to and has an active flow with "No Local Delivery"

If published message is not spooled because of any of the conditions above, the following will occur:

• If the reject-msg-to-sender-on-discard option is enabled for the topic endpoint, the message is discarded, and a NACK is returned to the sender. In this case, the message cannot be spooled to any other queue or topic endpoint (regardless of whether those endpoints have the reject-msg-to-sender-on-discard option enabled or disabled).
• A NACK is only sent to the client if the message was originally published with a non-persistent or persistent delivery mode. If the message was published with a Direct delivery mode, but was changed to non-persistent because of a topic match, and was then discarded, a NACK is not returned to the sender.
• How to handle the NACK is the responsibility of the publishing application—not Solace APIs. Solace APIs do not retransmit nacked messages.
• If the reject-msg-to-sender-on-discard option is not enabled for the topic endpoint, the ingress message is "silently" discarded (that is, it discards the message but returns an acknowledgment to the sender). In this case, other endpoints can spool the message—if they do not encounter any of the conditions listed above.

To enable the reject-msg-to-sender-on-discard option for a durable topic endpoint, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# reject-msg-to-sender-on-discard 

The no version of this command, no reject-msg-to-sender-on-discard, disables the reject-msg-to-sender-on-discard option on a durable topic endpoint.

Enabling/Disabling Clients from Publishing to/Consuming from Topic Endpoints

• To prevent client access to the specified durable topic endpoint, enter the following CONFIG command:

  solace(configure/message-spool/topic-endpoint)# shutdown [ingress | egress | full]

• To enable client access to the specified durable topic endpoint, enter the following CONFIG command:

  solace(configure/message-spool/topic-endpoint)# no shutdown [ingress | egress | full]

Where:

ingress specifies disable messages from being added to the durable topic endpoint.

egress specifies disable clients from binding to the durable topic endpoint to consume messages from it.

full specifies disable messages from being added to the durable topic endpoint and disable clients from binding to the durable topic endpoint. This is the default value.

Enabling/Disabling Propagating Consumer Acks to Replicated VPNs

By default, endpoints on an active Replication Message VPN propagate consumer acks that they received to the standby Replication Message VPN.

• To prevent the topic endpoint from propagating consumer acks to the standby Replication Message VPN, enter the following CONFIG command:

  solace(configure/message-spool/topic-endpoint)# no consumer-ack-propagation

• To allow the topic endpoint to propagate consumer acks to the standby Replication Message VPN, enter the following CONFIG command to allow it to do so:

  solace(configure/message-spool/topic-endpoint)# consumer-ack-propagation

Enabling Rejection of Low‑Priority Messages

To protect against message congestion scenarios where such a large number of published messages are delivered to a topic endpoint that system performance decreases, you can enable the topic endpoint to discard low‑priority messages but continue to spool high‑priority published messages. The topic endpoint selectively discards low-priority messages only after the total number of low- and high‑priority messages spooled exceeds the value set for the reject low‑priority message limit (refer toConfiguring Reject Low‑Priority Message Limits). By default, the reject low‑priority message feature is not enabled for endpoints.

To avoid inadvertently discarding all low-priority messages, it is recommended that you change the default value of 0 for the reject low‑priority message limit before enabling the reject low‑priority message feature to something more appropriate for your network.

To enable the reject low‑priority message feature for a topic endpoint, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# reject-low-priority-msg

The no version of this command, no reject-low-priority-msg, configures the durable topic endpoint to not perform reject low‑priority message limit checking on published messages (the default configuration).

Configuring Max Message TTLs

You can configure a Max Time to Live (TTL) value for a durable topic endpoint so that received messages are provided with expiration value to limit how long they can remain on that durable topic endpoint when a Max TTL is used. If a message is not consumed and its expiration time is reached, the message is discarded or is moved to a DMQ (if the publisher has flagged the message as DMQ-eligible).

A Max TTL value is only applied to messages when the Respect TTL option is enabled for the endpoint. It is also possible for a message to have a publisher-supplied TTL, which indicates how long the publisher considers a message to be valid. This differs from Max TTL in that the publisher TTL expiration starts when a message is published and counts down as the message passes through the network. The Max TTL only applies when a message is on the endpoint. If a message has both a publisher-assigned TTL and an endpoint-assigned Max TTL, the Solace PubSub+ event broker will use the minimum of the two TTL values when the message is on the endpoint.

To define a maximum TTL for the topic endpoint to apply to messages to be spooled, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# max-ttl <ttl>

Where:

<ttl> is maximum number of seconds that messages can stay on the topic endpoint when it has respect-ttl enabled.

The no version of this command, no max-ttl, sets the default Max TTL value 0 (disabled), which means that no expiry time is applied to any received messages spooled to that endpoint.

Enforcing Whether to Respect Message TTLs

You can configure a topic endpoint to either respect or ignore messages' Time‑to-Live (TTL) expiration values. This includes both the TTL value that can be set by publishing clients and the TTL value set on an endpoint through its configured Max TTL property.

When a topic endpoint is configured to respect message TTLs, messages' TTL values are checked. If a message’s TTL is expired, it is either removed from the message spool and discarded, or, if the message is eligible for a DMQ, it is moved to a DMQ provisioned on the event broker. If a message does not have an assigned TTL, then it will never expire. Note that by default, the DMQ is set to ignore message TTL expiry times and cannot be changed.

When a topic endpoint is configured to ignore message TTLs, spooled messages are not removed, even if they have been spooled for an amount of time that exceeds their set TTL value.

To configure a topic endpoint to respect message TTLs, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# respect-ttl

The no version of this command, no respect-ttl, configures a durable topic endpoint to ignore message TTL expiry times (the default configuration).

If the topic endpoint’s respect-ttl option is enabled after messages with a TTL value have been spooled, those existing spooled messages are not removed—even if their TTL expiration value has been exceeded. Only ingress messages with TTL values that are received after the respect-ttl option is enabled can be removed because TTL violations.

Enforcing Whether to Respect Message Priority Values

You can configure an endpoint to either respect or ignore messages' priority values.

When an endpoint is configured to respect message priority, the priority field in all received messages is used to deliver the message in the appropriate order, in other words messages with a higher priority are sent before messages with a lower priority.

The event broker recognizes ten levels of priority from 0 (lowest) to 9 (highest). If the priority field in the message is greater than 9, then the event broker treats it as priority 9. Received messages that do not have a priority field are treated as priority 4.

When transitioning from priority respected to ignored, all messages remain at their existing priorities. Although the queue does not respect priority values in new messages, priority values in existing messages are respected. Since new messages are treated as priority 9, when the queue is configured to ignore message priority, new messages may bypass messages that were received before the transition.

You must fully shutdown an endpoint before you can change whether it respects or ignores priority values.

To configure a topic endpoint to respect message priority values, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint)# respect-message-priority

The no version of this command, no respect-message-priority, configures a durable topic endpoint to ignore message priority values (the default configuration).