Configuring Queues

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

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

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

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

Where:

<name> is a queue name of up to 200 characters (only reserved queue names can begin with # and invalid characters are '<>*?&;). If the name contains a hierarchy of levels (for example, "a/b") each level of the hierarchy must contain one or more valid characters, and the name can't begin or end with a slash. Each queue name in a Message VPN must be unique.

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

The no version of this command, no queue <name>, deletes the specified durable message queue from the Message VPN. However, the queue cannot be deleted until it's shutdown, which disables client access to it (refer to Enabling / Disabling Client Access to Queues).

In this topic we'll show you how to use the Solace CLI to configure the parameters and features associated with a durable queue .

Configuring Access Types

To configure the client access type for durable message queues on the Solace PubSub+ message broker on a per-queue basis, enter the following CONFIG command.

Note:  The client access type cannot be changed until client access to the durable message queue is disabled (refer to Enabling / Disabling Client Access to Queues).

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

Where:

exclusive specifies that multiple subscriber flows established by clients can be bound to the queue, but only one flow out of all the bound flows is able to receive messages at a time. (That is, only one flow can be active.) The first flow to bind to the queue can consume messages from it, and when that Flow disconnects, the next oldest Flow to bind becomes active and can begin receiving messages, and so on.

non-exclusive specifies that all bound Flows are able to receive messages, and when multiple Flows are bound to a non‑exclusive Queue, they receive messages in a round-robin fashion. This provides load-balancing; however, if a connection fails, then unacknowledged messages are delivered to another Flow with the re‑delivered indicator set. In this way, messages can be delivered to clients out of order.

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

Configuring Max Number of Flows That May Bind

To configure the maximum number of flows that can bind to a durable message queue on the Solace PubSub+ message broker on a per-queue basis, enter the following CONFIG command.

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

Where:

<value> is the integer value specifying the maximum number of flows that can bind to a durable message queue. The valid range is 0 to 10,000. The default value is 1,000.

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

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

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 queue from propagating consumer acks to the standby Replication Message VPN, enter the following CONFIG command:

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

Alternatively, if the queue was allowed 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/queue)# consumer-ack-propagation

Configuring Queue Event Thresholds

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

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

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

Note:  For specific information on the available Message VPN-level message spool events that are generated for a queue and how to set the set and clear thresholds for generating those events, refer to Queue Event Thresholds.

Configuring Max Permitted Number of Delivered Unacked Messages

For a given queue you can configure the maximum number of Guaranteed messages that can be delivered to a client through a subscriber flow (that is, an egress flow) but remain unacknowledged by that client. That is, how many outstanding non-returned message acknowledgments are acceptable per flow bound to the queue.

After this maximum number of delivered but unacknowledged messages is exceeded, the Solace PubSub+ message 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-queue)# 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 message broker. The maximum value depends on the type of Solace PubSub+ message 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 message broker will stop delivering messages to all clients until some clients return acknowledgments back to the message 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.

Possible performance impact

Modifying max-delivered-unacked-msgs-per-flow may negatively impact performance if it's set lower than the transport window size used by consuming clients.

Provided the application is using at least Version 10.0.2 of the Java or JMS APIs, or at least Version 7.2.5 of the C, .NET, or JavaRTO APIs, the API learns about the configured max-delivered-unacked-msgs-per-flow at bind time and adjusts its ACK threshold accordingly for best performance. If the max-delivered-unacked-msgs-per-flow is changed while clients are bound, the clients may need to be disconnected and allowed to reconnect to receive the new value.

Older versions of the APIs don't adjust their ACK threshold based on the max-delivered-unacked-msgs-per-flow setting. If applications using older versions of the API bind to the queue, its max-delivered-unacked-msgs-per-flow must be set to a value greater than or equal to the transport window size used by the applications to ensure performance.

Configuring Max Permitted Message Sizes

To configure the maximum message size for the given durable queue, enter the following CONFIG command.

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

Where:

<size> is an integer value specifying the maximum message size (in bytes) permitted for the queue.

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

Configuring Max Redelivery Attempts

You can use the max-redelivery option to configure the maximum number of times the queue 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 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 queue can attempt to redeliver a message to a client, enter the following CONFIG command:

solace(configure/message-spool/queue)# 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 Max Spool Usage Values

To configure the maximum amount of message spool that the given queue may use, enter the following CONFIG command:

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

Where:

<size> is an integer value specifying the maximum amount of message spool disk space permitted for the queue in MB. The valid range is 0 to 6000000. The default value is 4000.

The no version of this command, no max-spool-usage, resets the permitted message spool usage quota available for use by the queue back to the default.

Setting maximum message spool usage to 0

Setting maximum message spool usage to 0 enables the Last Value Queue feature and disables endpoint quota checking. However, global quota checking and Message VPN quota checking are unaffected. When set to 0, the message broker enforces a queue depth of one by deleting older messages from the endpoint upon receiving new messages. For more information, refer to Last Value Queues.

Configuring Queue Owners

The queue owner has full unlimited permissions for the queue. That is, the owner can consume, delete, or modify topics in the queue. The ownership of a queue is established in the following manner:

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

Note:  Client access to the durable message queue must first be disabled before assigning an owner (refer to Enabling / Disabling Client Access to Queues).

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

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

<owner> is the username of an existing client username account. Default owner is management.

The no version of this command, no owner, resets the owner of the queue back to the default.

Restrictions on client initiated deletions

  • Clients can't delete subscriptions on a queue if those subscriptions were added using CLI or SEMP by management users.
  • Clients can't delete a queue if the queue was created using CLI or SEMP by a management user.

Configuring Permissions for Non-Owner Clients

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

Note:  Client access to the durable message queue must first be disabled before queue permissions can be configured, (refer to Enabling / Disabling Client Access to Queues).

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

Where:

read-only provides clients with read-only access permission to messages spooled to the queue.

consume provides clients with read-only permission and the ability to delete messages from the queue.

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

delete provides clients with modify-topic permission and the ability to either delete messages from the queue, or delete the queue altogether. Note that clients cannot delete a queue 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 queue to none; that is, no access. A client access level of none is the default permission level.

Note:  Permission levels are ignored for client-usernames with Guaranteed Endpoint Permission Override enabled. (Refer to Enabling Endpoint Permission Overrides.)

Receiving messages on topics that would otherwise be denied by clients' subscribe-topic ACLs

If clients other than the owner are given access to a queue, those clients may receive messages on topics which would otherwise be denied by the clients' subscribe-topic ACLs. For example, client1 could connect to the queue, and add a subscription to the topic a/b, which is an allowed subscription according to client1’s ACL profile. If client2 subsequently connects to that queue, client2 will receive messages for topic a/b from that queue, even though client2’s ACL rules may not allow client2 to subscribe to a/b.

Restrictions on client initiated subscription changes

  • Clients must have modify-topic permission set to add or remove a subscription from a queue. (Refer to Adding Topic Subscriptions to Queues.)
  • Clients cannot delete subscriptions on a queue if management users added those subscriptions using CLI or SEMP.

Enabling Rejection of Low-Priority Messages

To protect against message congestion scenarios where such a large number of messages are published to a queue that system performance decreases, you can enable the queue to discard low‑priority messages but continue to spool high‑priority published messages. The queue can selectively discard low-priority messages only after the total number of low‑priority and high‑priority messages spooled exceeds the value set for the reject low‑priority message limit .

By default, the reject low‑priority message feature is not enabled for endpoints.

Note  
  • To avoid inadvertently discarding all low-priority messages, it's 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 (refer to Configuring Reject Low‑Priority Message Limits).
  • When this feature is enabled, the reject message to sender on discard option (refer to Configuring Message Discard Handling) must also be enabled for the queue so that session events are sent to the publishing clients whenever messages are not enqueued on the queue and are discarded.

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

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

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

Assigning message priorities

Client applications can use the Solace messaging APIs to assign message priorities through the Class of Service (COS) property.

Configuring Reject Low‑Priority Message Limits

To configure a reject low‑priority message limit for a queue, enter the following CONFIG command:

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

Where:

<limit> is the total number of low- and high‑priority messages spooled. When this value is exceeded, the queue 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 queue only spools high-priority messages are spooled.

Configuring Message Discard Handling

The reject-msg-to-sender-on-discard option configures how a durable queue 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 queue
  • the published message exceeds the maximum message size allowed for the queue
  • the client published the message to a topic it has also subscribed to and has an active flow with “No Local Delivery”

If a 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 queue (this is the default): 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 a queue: 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 queue, enter the following CONFIG command:

solace(configure/message-spool/queue)# reject-msg-to-sender-on-discard [including-when-shutdown]

Where:

including-when-shutdown specifies to return Nacks to clients publishing messages topics if the endpoint has a matching subscription but is shutdown. Note that this parameter specifically targets messages published to topics because messages published to a queue are always nacked when reject-msg-to-sender is enabled and the queue is shutdown.

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

Impact on transacted sessions

The reject-msg-to-sender-on-discard option also affects the behavior of transacted sessions. If “acks”’ are being returned to the sender, then the transacted session commit succeeds. If a nack is returned to the sender, then the commit fails. For more information, refer to Using Local Transactions for Solace enterprise APIs and Using Transacted Sessions for Solace JMS.

Configuring Max Message TTLs

You can configure a Max Time to Live (TTL) value for a durable endpoint so that received messages are provided with expiration value to limit how long they can remain on that durable 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 Dead Message Queue (DMQ) (if the publisher has flagged the message as DMQ-eligible).

It's 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. 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+ message broker will use the minimum of the two TTL values when the message is on the endpoint.

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

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

Where:

<ttl> is maximum number of seconds that messages can stay on a queue that has the Respect TTL option enabled.

Conditions:

  • A Max TTL value is only applied to messages when the Respect TTL option is enabled for the endpoint.
  • Any messages already on the queue endpoint when this parameter is configured or changed will not be impacted; those messages will continue to use the TTL assigned to them (if any) when they were spooled to the endpoint.
  • A Max TTL cannot be set on DMQs, queues associated with Replication bridges, or queues associated with Config-Sync bridges.

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

Max TTL & Message-VPN Bridges

Although Max TTL values can be configured on queues associated with Message VPN bridges, it's recommended that you configure Max TTLs on the endpoints that are the published messages' ultimate destinations. This will prevent messages from being discarded on the bridge queue when there are expectant downstream consumers.

Max TTL & Performance

Using Max TTL increases the amount of state that needs to be maintained for each message stored in the endpoint and will affect the Guaranteed messaging performance.

Enforcing Whether to Respect TTLs

You can configure a queue 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. By default, the DMQ is set to ignore message TTL expiry times.

When a queue 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 message broker. If a message does not have an assigned TTL, then it will never expire.

When a queue 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 durable queue to respect message TTLs, enter the following CONFIG command:

solace(configure/message-spool/queue)# respect-ttl

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

Note:  If a queue'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 a queue to either respect or ignore messages' priority values.

When a queue 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 message 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 message 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.

Note:  You must fully shutdown a queue before you can change whether it respects or ignores priority values.

To configure a durable queue to respect message priority values, enter the following CONFIG command:

solace(configure/message-spool/queue)# respect-message-priority

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

Enforcing message priority increases the chance that duplicate messages will be delivered to a consuming client after it recovers from a connection failure.

Adding Topic Subscriptions to Queues

To add a topic subscription to the given durable message queue so that Guaranteed messages published to those topics are also delivered to the queue, enter the following CONFIG command:

solace(configure/message-spool/queue)# subscription topic <topic>

Where:

<topic> is the name of the topic subscription to be added in the form a/b/c.

The no version of this command, no subscription topic, deletes the specified topic subscription from the durable queue.

Conditions:

  • Adding or deleting a topic subscription does not affect the messages that are already stored in the queue.
  • The subscription topic Queue CONFIG command and no subscription topic Queue CONFIG command can be entered multiple times to add or delete multiple topic subscriptions to the queue.
  • The queue subscriptions are constrained by the same limits put on per client subscriptions and the message broker-wide constraint of number of supported subscriptions.

Restrictions on subscription changes

  • Clients using Solace Messaging APIs can't remove topic subscriptions from a queue that an administrator has added through CLI or SEMP.
  • To permit clients to add or remove subscriptions from a queue that have not been added by an administrator, a permission level of modify-topic or delete must be configured for the queue (refer to Configuring Permissions for Non-Owner Clients), or the clients must be assigned a client profile that has the guaranteed endpoint permission override enabled (refer to Allowing Guaranteed Endpoint Creates).
  • Adding or removing a subscription from a queue is fully supported in a redundant message broker configuration. That is, topic subscriptions in queues can be managed on the active message broker and those subscriptions survive activity switches between message broker pairs.

Adding Topic Subscription Exceptions to Queues

To add a topic subscription exception to the given durable message queue so that Guaranteed messages published to those topics are not delivered to the queue, repeat the steps to add a subscription and add a leading "!" character to the topic name.

In other words, to add a topic subscription exception to the queue enter the following CONFIG command:

solace(configure/message-spool/queue)# subscription topic !<topic>

Where:

<topic> is the name of the topic subscription you want to exclude from the queue in the form a/b/c.

Subscription exceptions are enabled by default. If subscription exceptions are disabled, the leading "!" is treated as a literal character. For more information about enabling and disabling subscription exceptions, refer to System-Level Subscription Exception Configuration.

Enabling / Disabling Client Access to Queues

To enable client access to the specified durable queue, enter the following CONFIG command:

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

To disable client access to the specified durable queue, enter the following CONFIG command:

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

Where:

ingress specifies disable clients from publishing to the queue.

egress specifies disable clients from binding to the queue.

full specifies disable clients from publishing to the queue and disable clients from binding to the queue (default).