Using Client Profiles and Client Usernames

You can use client profiles to assign a common set of configuration properties to client applications that have been successfully authenticated with your event broker service. Client profiles define a set of client behaviors and capabilities that you can apply to multiple client usernames or LDAP authorization groups in the Message VPN for your event broker service. From an administrative perspective, this enables you to manage authorization settings for groups of client applications and make configuration changes in one place that apply to multiple applications that share the same client profile, and tune performance for the applications.

Client usernames are used by client applications to authenticate with the event broker service. They are associated with a client profile and an ACL profile to control the properties and permissions of the connecting client application. Client usernames are specific to a Message VPN and may be used to make multiple client connections, which lets applications horizontally scale without additional configuration on the event broker.

To configure client profiles, you must have one of the following permissions:

  • Mission Control Manager
  • Mission Control Viewer with Manager access
  • Mission Control User with Manager access.

The behaviors and capabilities that you can configure for a client profile include:

  • the allocation of resources (e.g., maximum number of subscriptions for a single client, per-client transport queues)
  • TCP connection parameters
  • enablement of event services capabilities
  • adjusting the point at which certain events are triggered.

For information about the options available, see Client Profile Settings.

All event broker service have a default client profile. The default client profile has common settings that let you start using an event broker servicequickly. If you don't assign a client profile to a client username, the event broker service automatically assigns the default client profile. You can edit and manage all client profiles and assign them to client usernames in the PubSub+ Cloud Console or using the REST API for PubSub+ Cloud. For more information about using the REST API, see Managing Client Profiles with the PubSub+ Cloud REST API.

For more information about configuring client profiles in the Cloud Console, see the following sections:

Creating a Client Profile

You must be a Mission Control Manager or Administrator to create client profiles.

  1. Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging In to the PubSub+ Cloud Console.
  2. On the navigation bar, select Cluster Manager .
  3. Select the event broker service that you want to configure. If the event broker service is not listed, make sure you have the right environment selected. For more information, see Selecting Environments.
  4. Select the Manage tab.
  5. Click Client Profiles and perform one of the following steps.
  6. If the event broker service is version 10.10 or later:
    1. In Broker Manager, click + Client Profile.
    2. Type a unique name for the client profile and click Create. The name can be up to 32 alphanumeric characters (case-sensitive) and can also include underscores and dashes.
    3. Configure the client profile as required. For more information about the settings, see Client Profile Settings.
    4. (Optional) Click Show Advanced Settings to display additional options.
    5. Click Apply.
    6. Return to Cluster Manager.
  7. If the event broker service is earlier than version 10.10:
    1. In the Client Profiles pane, click Add New.
    2. In the Profile Name field, type a unique name for the client profile. The name can be up to 32 alphanumeric characters (case-sensitive) and can also include underscores and dashes.
    3. Set the options as required. For more information about the settings, see Client Profile Settings.
    4. (Optional) Click Advanced Settings to display and set additional options
    5. Click Save.

Modifying a Client Profile

You can modify the settings for an existing client profile. You must be a Mission Control Manager or Administrator to modify an existing client profile.

  1. In Cluster Manager click the event broker service that you want to modify.
  2. Select the Manage tab.
  3. Click Client Profiles and perform one of the following steps.
  4. If the event broker service is version 10.10 or later:
    1. In Broker Manager, click the name of the client profile you want to modify.
    2. Click Edit .
    3. Update the client profile as required. For more information about the settings, see Client Profile Settings.
    4. Click Apply.
    5. To return to Cluster Manager, select the Service details | PubSub+ Cloud tab in your web browser.
  5. If the event broker service is earlier than version 10.10:
    1. In the Client Profiles pane, click the name of the client profile you want to modify.
    2. Update the client profile as required. For more information about the settings, see Client Profile Settings.
    3. Click Save.

Deleting a Client Profile

If you are a a Mission Control Manager or Administrator, you can delete any client profile except the default profile.

  1. In Cluster Manager click the event broker service that you want to delete a client profile from.
  2. Select the Manage tab.
  3. Click Client Profiles and perform one of the following steps.
  4. If the event broker service is version 10.10 or later:
    1. In Broker Manager, click the name of the client profile you want to modify.
    2. Select the check box next to the name of the client profile.
    3. Click Action > Delete.
    4. To return to Cluster Manager, select the Service details | PubSub+ Cloud tab in your web browser.
  5. If the event broker service is earlier than version 10.10:
    1. In the Client Profiles pane, click the Delete button beside the name of the client profile that you want to remove.
    2. Click Save.

Client Profile Settings

For event broker services earlier than version 10.10, Mission Control Managers and Administrators configure client profiles in Cluster Manager. Administrators and Mission Control Managers configure client profiles for event broker services version 10.10 in Broker Manager.

Setting Description

Send Guaranteed Messages

Allows client applications to publish Guaranteed messages.

 

Receive Guaranteed Messages

Allows client applications to bind to topic endpoints or queues to receive Guaranteed messages.

 

Connect as a Bridge

Allows client applications to establish connections between the event broker service in the high-availability (HA) group and another HA group using DMR links.

 

Use Transacted Sessions

Allows client applications to use transacted sessions (that is, local transacted sessions and/or XA Sessions). Transacted sessions are supported by the Solace messaging APIs (e.g., JMS, Java, Java RTO, JCSMP, C, and .NET APIs messaging APIs). XA Sessions are only supported by the Solace JMS messaging API.

 

Add Shared Subscriptions

Allows client applications to use shared subscriptions for Direct messaging.

Clients permitted to use shared subscriptions are allowed to subscribe to all shared subscriptions in the Message VPN. If you want to control access to specific shared subscriptions, you can use an ACL profile to configure a list of share names that are permitted (or denied), and then associate it with a client profile.

Use Compression

Allows client applications to use compression when transferring data.

Connect When Replication Standby

Allows client applications to remain connected to the Message VPN with a standby replication state when the Message VPN replication state changes from Active to Standby

Downgrade Connection To Plain Text

Allows connecting client applications to request to downgrade their TLS/SSL connections to plaintext after the client is authenticated and authorized. The client's authentication data is still encrypted, but the subsequent application data that is transmitted is sent as non-encrypted plaintext.

This setting is not available for client profiles configured in Cluster Manager for event broker services earlier than 10.10

Allow Client to Create Endpoints

Allows client applications to create queues or topic endpoints. This option is enabled by default.

Specify Endpoint Durability

Specifies the types of queues and topic endpoints that client applications can create. The options are:

  • All Endpoints—Client can create any type of endpoint.
  • Durable Endpoints—Client can create only durable endpoints.
  • Non-durable Endpoints—Client can create only non-durable endpoints.

The setting is available only when Allow Client to Create Endpoints is enabled in Broker Manager.

This setting is not available for client profiles configured in Cluster Manager for event broker services earlier than 10.10

Copy Settings From Queue Template

Specifies the name of the queue template to copy the settings from when the client application creates a queue.

When a client using Solace messaging APIs dynamically creates an endpoint, its configuration is determined first by the endpoint properties and provision flags that the client provides through the API. Any remaining parameters are then filled by the values in the specified queue template or topic endpoint template.

Copy Settings From Topic Endpoint Template

Specifies the name of the topic endpoint template to copy the settings from when the client application creates a topic endpoint.

Reject Messages to Sender On No Subscription Match Discard

Enables the sending of a negative acknowledgments (NACKs) to a client application when discarding a Guaranteed message because no matching subscription was found.

This setting is not available for client profiles configured in Cluster Manager for event broker services earlier than 10.10.

TCP Maximum Segment Size (B)

Specifies the TCP maximum segment size (MSS) in bytes used for the client application.

TCP Initial Congestion Window Size (MSS)

Specifies the TCP initial congestion window size used when starting a TCP connection or on recovery from idle (that is, no traffic). This setting is the number of segments that TCP sends before waiting for an acknowledgment from the peer. Larger values of the initial window allows a connection to come up to speed more quickly. For further details, refer to RFC 2581.

TCP Maximum Window Size (KB)

Specifies the TCP window size between the event broker service and the client.

If the maximum window size is set to less than the bandwidth-delay product, then the TCP connection operates below its maximum potential throughput. If the maximum window is set to less than about twice the bandwidth-delay product, then occasional packet loss causes the TCP connection to operate below its maximum potential throughput as it handles the missing acknowledgments and retransmissions.

Alternatively, if the TCP maximum window size is too large, in the presence of a high offered load, TCP gradually increases its congestion window size until either:

  • the congestion window size reaches the maximum window size
  • packet loss occurs in the network

Initially, when the TCP congestion window size is small, the physical bandwidth-delay of the network acts as a memory buffer for packets in flight. But as the congestion window crosses the bandwidth-delay product, the buffering of in-flight packets moves to queues in event broker services and other equipment throughout the network. As the TCP congestion window continues to increase in size, these various equipment queues overflow, causing packet loss and TCP backoff.

TCP Keepalive Retry

Specifies the maximum number of keepalive probes that TCP sends before dropping the connection. The value must be between 2 and 5.

TCP Keepalive Time (sec)

Specifies the time period that a connection remains idle before TCP begins sending keepalive probes. The value must be between 3 and 120 seconds

TCP Keepalive Interval (sec)

Specifies the time interval between individual keepaliveprobes. The value must be between 1 and 30 seconds,

Message Eliding Enabled

Allows client applications to use message eliding for Direct messaging.

Message eliding allows client applications to receive Direct messages published to topics that they subscribe to, at a rate they can manage, rather than queue outdated messages. Message eliding can be useful in situations where messages are consumed at a slower rate then they are published due to slow consumers or human interaction.

Maximum Eliding Topics Per Client Connection

Specifies the maximum number of topics the event broker service can track for performing the eliding function on each client connection. The value must be between 1 and 320000,

Eliding Delay (ms)

 Specifies the amount of time to delay the delivery of messages to a client application after the initial message has been delivered. The value must be between 0 and 6000 milliseconds.

Minimum Application Keepalive Timeout (sec)

Specifies the minimum period of time in seconds that the event broker service tolerates inactivity on the client connection. The keepalive timeout value is calculated based on the client provided timeout interval (3 x the keepalive interval for Solace Message Format (SMF) connections, 1.5 x the keepalive interval for MQTT connections).

The minimum keepalive value is enforced for MQTT connections by default. The value must be between 3 and 3600 seconds,

Minimum Keepalive Timeout Enabled for SMF

Specifies whether the Minimum Application Keepalive Timeout value is enforced for SMF connections in addition to MQTT connections.

Web Transport Inactive Timeout (sec)

Specifies the number of seconds a web client has to send a request before its session times out and is terminated for being inactive.

Maximum Web Transport Payload Size (B)

Specifies the maximum transport payload size.

SMF messages that are sent to a consuming web client are contained within a web transport message that the event broker sends in its HTTP response to that client. Each web transport message can contain multiple SMF messages or partial SMF messages.

The maximum web payload value sets the maximum number of bytes allowed in a single web transport message (not including the header). This value determines the number of SMF messages that can be sent in a single HTTP response and the size of the web transport message sent in the HTTP response. The value must be between 0 and 1000000 bytes.

Maximum Endpoints Created Per Client Username

Specifies the maximum number of queues and topic endpoints that can be owned by client applications using the same client username.

Alert Thresholds—Specifies the thresholds that control when an alert is generated.

Maximum Outgoing Flows Per Client

Specifies the maximum number of egress flows that can be created by a single client application associated with this client profile.

Alert Thresholds—Specifies the thresholds that control when an alert is generated.
Maximum Incoming Flows Per Client

Specifies the maximum number of ingress flows \that can be created by a single client application associated with this client profile.

Alert Thresholds—Specifies the thresholds that control when alert is generated.
Provisioned Endpoint Spool Usage Alert Thresholds (%)

Specifies the clear and raise threshold values that determine when to generate events for the percentage amount of the message spool used by all endpoints provisioned by client applications for the given client profile.

  • Clear —The clear threshold value for the message spool usage (as a percentage).
  • Raise— The raise threshold value for the message spool usage (as a percentage).
Maximum Transacted Sessions Per Client

Specifies the maximum number of simultaneous transacted sessions and/or XA Sessions allowed for a single client application associated with the client profile. The default is 100.

Alert Thresholds—Specifies the thresholds that control when alert is generated.

Maximum Messages Per Transaction

Specifies the maximum number of publisher and consumer messages combined that is allowed within a transaction for each client application associated with this client-profile. Exceeding this limits results in a transaction prepare or commit failure.

This setting is not available for client profiles configured in Cluster Manager for event broker services earlier than 10.10

Maximum Transactions Per Client

Specifies the total maximum number of simultaneous transactions (both local transactions and transactions within the XA transaction branches) allowed for a single client associated with the client profile.

Alert Thresholds—Specifies the thresholds that control when alert is generated.

Maximum Client Connections Per Client Username

Specifies the maximum number of simultaneous client connections to the event broker service that can be made using the same client username. This limit applies to client connections using any supported service type. If your service class is large, you might want to raise this limit.

Alert Thresholds—Specifies the thresholds that control when alert is generated.

SMF Client Connections Per Client Username

Specifies the maximum permitted number of simultaneous SMF client connections to the event broker service that can be made using the same client username account.

Alert Thresholds—Specifies the thresholds that control when alert is generated.

 

Web Transport Client Connections Per Client Username

Specifies the maximum permitted number of simultaneous web transport client connections to the event broker service that can be made using the same client username account.

Alert Thresholds—Specifies the thresholds that control when alert is generated.
Maximum Subscriptions Per Client

Specifies the maximum number of subscriptions for a single client application. When you set this option, consider the total maximum number of permitted topic subscriptions and the total maximum number of client connections for the type of event broker service that is used. To ensure reliable system performance, you must find the right balance for your network, while staying within the system limits mentioned. The balance is generally between allowing the creation of many client applications and allowing each client to add a large number of topic subscriptions.

Alert Thresholds—Specifies the thresholds that control when alert is generated.

Priority Queues - G-1 Maximum Depth (work units)

Specifies the egress queue maximum depth for Guaranteed messages that represents the number of work units for the client priority queues. The valid range is 2 to 262144. For more information, see Configuring Max Egress Queue Depths.

Priority Queues - G-1 Minimum Burst (msgs)

Specifies the minimum number of messages that must be on the Guaranteed hessage queue before the queue’s depth is checked against the maximum depth setting (thereby allowing the queue to absorb a burst of large messages that exceeds the number of allowed work units). The valid range is 0 to 262144 . The value of 255 is recommended for memory usage optimized configurations, such as message applications; a value of 66000 is for WAN optimized configurations. For more information about egress queues, see Client Egress Queue Structure Overview.

Priority Queues - D-1 Maximum Depth (work units)

Specifies the egress queue maximum depth for Direct Messages 1 [Class of Service (COS) 1] that represents the number of work units for the client priority queues. The valid range is 2 to 262144. For more information, see Configuring Max Egress Queue Depths.

Priority Queues - D-1 Minimum Burst (msgs)

Specifies the minimum number of messages that must be on the Direct 1 (COS 1) queue before the queue’s depth is checked against the maximum depth setting (thereby allowing the queue to absorb a burst of large messages that exceeds the number of allowed work units). A valid range is 0 to 262144. For more information, see Configuring Egress Queue Minimum Message Bursts.

Priority Queues - D-2 Maximum Depth (work units)

Specifies the egress queue maximum depth for Direct Messages 2 (COS 2) that represents the number of work units for the client priority queues. The valid range is 2 to 262144. For more information, see Configuring Max Egress Queue Depths.

Priority Queues - D-2 Minimum Burst (msgs)

Specifies the minimum number of messages that must be on the Direct 2 (COS 2) queue before the queue’s depth is checked against the maximum depth setting (thereby allowing the queue to absorb a burst of large messages that exceeds the number of allowed work units). A valid range is 0 to 262144. For more information, see Configuring Egress Queue Minimum Message Bursts.

Priority Queues - D-3 Maximum Depth (work units)

Specifies the egress queue maximum depth for Direct Messages 3 [Class of Service (COS) 3] that represents the number of work units for the client priority queues. The valid range is 2 to 262144. For more information, see Configuring Max Egress Queue Depths.

Priority Queues - D-3 Minimum Burst (msgs)

Specifies the minimum number of messages that must be on the Direct 3 (COS 3) queue before the queue’s depth is checked against the maximum depth setting (thereby allowing the queue to absorb a burst of large messages that exceeds the number of allowed work units). A valid range is 0 to 262144. For more information, see Configuring Egress Queue Minimum Message Bursts

Priority Queues - C-1 Maximum Depth (work units)

Specifies the egress queue maximum depth for Control 1 that represents the number of work units for the client priority queues. The valid range is 2 to 262144. For information about egress queues, see Using Client Profiles and Client Usernames.

Priority Queues - C-1 Minimum Burst (msgs)

Specifies the minimum number of messages that must be on the Direct 1 (COS 1) queue before the queue’s depth is checked against the maximum depth setting (thereby allowing the queue to absorb a burst of large messages that exceeds the number of allowed work units). A valid range is 0 to 262144.For more information, see Configuring Egress Queue Minimum Message Bursts.

Creating and Managing Client Usernames

A client is only authorized to connect to a Message VPN that is associated with a client username that client has been assigned.

Client access to the resources and messaging capabilities on an event broker is facilitated through the client username accounts that are provisioned. When clients are authenticated, they are provided with the predefined configurations  (client profiles) that are associated with those client usernames.

The username must be unique among all created client usernames within its Message VPN. A client username :

  • can contain up to 189 printable ASCII characters (that is, characters in the range 0x20 – 0x7e) are permitted - though the question mark (?) and asterisk (*) are not permitted.
  • are case-sensitive

To create a client username, perform these steps:.

  1. Log in to the PubSub+ Cloud Console if you have not done so yet. The URL to access the Cloud Console differs based on your authentication scheme. For more information, see Logging In to the PubSub+ Cloud Console.
  2. On the navigation bar, select Cluster Manager .
  3. Select the event broker service that you want to configure. If the event broker service is not listed, make sure you have the right environment selected. For more information, see Selecting Environments.
  4. Select the Manage tab and then click Access Control.
  5. In Broker Manager, on the Access Control page, select the Client Usernames tab.
  6. In the top-right corner, click +Client Username.
  7. Type a unique client username and click Create.
  8. Configure the client username as required:
    • Click Enable to allow applications to connect using the client username.
    • Click Change Password to update the password for the username.
    • In the Client Profile list, select a client profile to use with the client username. If you don't select a profile, the client username uses the default profile.
    • In the ACL Profile list, select the ACL profile to use with the client username.
    • Enable Guaranteed Endpoint Permission Override to allow the application to access, modify, and delete all Guaranteed messaging endpoints with the same permissions as the owner.
    • Enable Subscription Manager to allow the application to manage subscriptions on behalf of other client usernames.
  9. Click Apply.