Configuring Endpoint Templates

Endpoint templates are configurable objects that administrators can use to specify custom attributes and parameters for any new client created endpoints based upon the endpoint name. When the client created endpoints are created dynamically using an API, the endpoint name can be matched to the endpoint template. All custom attributes that are configured in the endpoint template will be copied to the client-created endpoint. For overview information, take a look at Endpoint Templates.

Also, Client Profiles have an optional copy-from-template-on-create command associated with them for both queues and topic endpoint templates. You can use the copy-from-template-on-create command to specify a CLI-provisioned endpoint template and those template values will be applied to any new client-created endpoints. For more information on this topic, refer to Configuring Initial Values for Client-Created Endpoints.

Endpoint templates can be configured using Solace CLI or Solace PubSub+ Manager. In the subsequent topics, we will show you how to use the Solace CLI to configure endpoint template values for both queue and topic endpoints.

:  This feature is available only on Solace PubSub+ event broker 9.4.0 release onwards.

Configuring Queue Templates

To configure a queue template in a given Message VPN, enter the following commands:

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

Where:

<name> is the queue template name of up to 255 characters.

The no version of the command, no queue-template <name>, deletes the specified queue template from the Message VPN.

From here, you can now assign custom attributes and parameters to the queue template that can be copied to any client created queues. You can start by setting up a name-filter that can be used to match a queue name with a queue template.

Setting Name Filters to Match Queue Names

Administrators can use name filters to match a queue name with a queue template. More precisely, name filter is a wildcard pattern that is used to determine which queues use settings from a given template. Following two types of wildcards are supported: * and >.

Rules governing the use of the wildcards:

  • * matches zero or more characters but never a slash (/). It can be present only at the end, after a / (as in, animals/domestic/*).

    Example: animals/domestic/* matches the queues animals/domestic/cats and animals/domestic/dogs, but it doesn't match the queue animals/domestic/dogs/beagles.

  • > matches anything with identical prefixes to the name-filter, but only when it's placed at the end (as in, animals/domestic/>). It is considered a wildcard only when placed at the end, after a /.

    Example: animals/domestic/> matches the queues animals/domestic/cats, animals/domestic/dogs and animals/domestic/dogs/beagles, but it doesn't match the queue animals/domestic.

To configure a name-filter that can be used to match a queue name with a queue template, enter the following command:

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

Where:

name is the value to be used for the name-filter.

The no version of the command, no name-filter <name>, returns its value to the default.

:  When configuring name filters, the best practice is to avoid overlapping name filters. If you do use overlaping filter, the event broker takes the longest non-wildcarded prefix when resolving multiple matches.

Setting Durability Override

The durability-override command allows to control the durability of client created well-known durable queues. When a client’s API-created queues are created, with durability-override non-durable specified in the queue template, the client created well-known durable queue is converted to a well-known non-durable queue. The created queue will be non-durable, regardless of what the client requested during queue creation.

To configure durability-override to controls the durability of a queue created from a given template, enter the following CONFIG command:

solace(configure/message-spool/queue-template)# durability-override {none | non-durable}

Where:

none is the durability of the queue as requested on create.

non-durable is the durability of the created queue, which will be non-durable, regardless of the specified durability.

The no version of the command, no durability-override {none | non-durable}, returns its value to the default (none).

:  Durability override is not support for MQTT queues.

To learn more about well-known queues, refer to Well-Known Queue.

Setting Access Types

To configure the client access type for durable message queues, enter the following CONFIG command:

solace(configure/message-spool/queue-template)# 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 providconses 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).

Refer to Configuring Access Types for additional information on client access type configuration for durable queues.

Setting Consumer Ack Propogation

Following configurations in the queue template will enable or disable the propagation of consumer acks received on the active Replication Message VPN 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-template)# no consumer-ack-propagation

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-template)# consumer-ack-propagation

For additional information on configuring consumer ack propogation for durable queues, refer to Enabling / Disabling Propagating Consumer Acks to Replicated VPNs.

Setting Queue Event Thresholds

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

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

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

For information on how to set and clear thresholds for generating those events for a queue using a queue template, refer to Queue Event Thresholds Using Templates.

Setting Max Number of Flows That May Bind

To configure the maximum number of flows that can bind to a queue, enter the following CONFIG command.

solace(configure/message-spool/queue-template)# 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 queue template back to the default.

For additional information, refer to Configuring Max Number of Flows That May Bind.

Setting Max Permitted Number of Delivered Unacked Messages

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

solace(configure/message-spool/queue-template)# 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 Solace PubSub+ 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 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.

Take a look at Configuring Max Permitted Number of Delivered Unacked Messages for additional information on max-delivered-unacked-msgs-per-flow or to review any performance impact that you may want to consider.

Setting 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-template)# 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.

Setting Max Redelivery Attempts

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-template)# 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.

For more information on max-message-size configuration, refer to Configuring Max Redelivery Attempts.

Setting 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-template)# 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 1500.

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.

For more information related to configuring max-spool-usage size, see Configuring Max Spool Usage Values.

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

:  Client access to the durable message queue must first be disabled before queue permissions can be configured, (refer to Configuring Endpoint Templates).

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

Where:

no-access disallows all access.

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.

Refer to Configuring Permissions for Non-Owner Clients for any additional information related to queue permissions.

Setting Rejection of Low-Priority Messages

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

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

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

For further information on this topic, refer to Enabling Rejection of Low-Priority Messages.

Setting 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-template)# 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.

Setting Message Discard Handling

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

solace(configure/message-spool/queue-template)# 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.

See Configuring Message Discard Handling to learn about that conditions that cause ingress messages discards as well as it's impact on transacted sessions.

Setting Max Message TTLs

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.

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.

For information regarding that conditions when Max TTL value is applied, TTL & Message-VPN Bridges, and it's impact on performance, refer to Configuring Max Message TTLs

Setting Respect TTLs

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

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

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

For additional information on this topic, refer to Enforcing Whether to Respect TTLs.

Setting Respect Message Priority Values

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

solace(configure/message-spool/queue-template)# 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).

Refer to Enforcing Whether to Respect Message Priority Values for additional information on this topic.

Configuring Topic Endpoint Templates

To configure a topic endpoint template in a given Message VPN, enter the following commands:

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

Where:

<name> is the topic endpoint template name of up to 255 characters.

The no version of the command, no topic-endpoint-template <name>, deletes the specified topic endpoint template from the Message VPN.

From here, you can now assign custom attributes and parameters to the topic endpoint template that will be copied to any client created topic endpoints. Lets start by setting up a name filter that can be used to match a topic endpoint name with a topic endpoint template.

Setting Name Filters to Match Topic Endpoint Names

Administrators can use name filters to match a topic endpoint name with a topic endpoint template. More precisely, name filter is a wildcard pattern that is used to determine which queues use settings from a given template. Following two types of wildcards are supported: * and >.

Rules governing the use of the wildcards:

  • * matches zero or more characters but never a slash (/). It can be present only at the end, after a / (as in, animals/domestic/*).

    Example: animals/domestic/* matches the topic endpoints animals/domestic/cats and animals/domestic/dogs, but it doesn't match the topic endpoint animals/domestic/dogs/beagles.

  • > matches anything with identical prefixes to the name-filter, but only when it's placed at the end (as in, animals/domestic/>). It is considered a wildcard only when placed at the end, after a /.

    Example: animals/domestic/> matches the topic endpoints animals/domestic/cats, animals/domestic/dogs and animals/domestic/dogs/beagles, but it doesn't match the topic endpoint animals/domestic.

To configure a name-filter that can be used to match a topic endpoint name with a topic endpoint template, enter the following command:

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

Where:

name is the value to be used for the name-filter.

The no version of the command, no name-filter <name>, returns its value to the default.

:  When configuring name filters, the best practice is to avoid overlapping name filters. If you do use overlaping filter, the event broker takes the longest non-wildcarded prefix when resolving multiple matches.

Setting Access Types

To configure the client access type for durable topic endpoints, enter the following CONFIG command.

solace(configure/message-spool/topic-endpoint-template)# 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).

See Configuring Access Types for additional information on client access type configuration for durable queues.

Setting Consumer Acknowledgment (ACKs)

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

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

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

To allow 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-template)# consumer-ack-propagation

Setting Topic Endpoint Event Thresholds

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

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

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

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

Setting Max Number of Flows That May Bind

To configure the maximum number of flows that can bind to a non-exclusive durable topic endpoint, enter the following CONFIG command:

solace(configure/message-spool/topic-endpoint-template)# 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.

For additional information, refer to Configuring Max Number of Flows That May Bind.

Setting Max Permitted Number of Delivered Unacked Messages

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-template)# 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.

Take a look at Configuring Max Number of Delivered Unacked Messages for additional information on max-delivered-unacked-msgs-per-flow or to review any performance impact that you may want to consider.

Setting Max Permitted Message Sizes

To configure the maximum message size for a given topic endpoint, enter the following CONFIG command.

solace(configure/message-spool/topic-endpoint-template)# 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. For Solace PubSub+ 3230, the maximum message size (in bytes) permitted for the topic endpoint is lower. The valid range for a Solace PubSub+ 3230 is 0 to 10000000. 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.

Setting Max Redelivery Attempts

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-template)# 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.

For more information on max-message-size configuration, refer to Configuring Max Permitted Redelivery Attempts.

Setting 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-template)# 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. The default value is 4000, and the valid range is 0 to 6000000. Setting the value to 0 is not recommended for topic endpoints.

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

Setting Permissions for Non-Owner Clients

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

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

Where:

no-access disallows all access.

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.

Refer to Configuring Permissions for Non-Owner Clients for any additional information related to queue permissions.

Setting 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-template)# 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.

Setting Rejection of Low-Priority Messages

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

solace(configure/message-spool/topic-endpoint-template)# 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).

For further information on this topic, refer to Enabling Rejection of Low‑Priority Messages.

Setting Max Message TTLs

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-template)# 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.

For information additional information on this topic, refer to Configuring Max Message TTLs

Setting Message Discard Handling

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-template)# 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.

Refer to Configuring Message Discard Handling to learn about that conditions that cause ingress messages discards as well as it's impact on transacted sessions.

Setting Respect TTLs

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

solace(configure/message-spool/topic-endpoint-template)# 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).

For additional information on this topic, refer to Enforcing Whether to Respect Message TTLs.

Setting Respect Message Priority Values

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

solace(configure/message-spool/topic-endpoint-template)# 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).

Refer to Enforcing Whether to Respect Message Priority Values for additional information on this topic.