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 are useful to define a set of client behaviors and capabilities that you can apply to multiple client usernames or LDAP authorizations 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 for client applications to authenticate and are associated with a client profile and ACL profile to control the permissions of the connecting client application. Client usernames are specific to a Message VPN. They are used by client applications to authenticate with the event broker service, and may be used to make multiple client connections. This lets applications horizontally scale without additional configuration on the event broker. Each client username is associated with a client profile and an ACL profile. These profiles control properties and permissions of the connected client application.
Client profiles are objects provisioned on Message VPNs that are used to assign a common set of configuration properties to clients that have been successfully authorized.
Client profiles control many client behaviors and capabilities. For example, client profiles control the allocation of resources, such as the maximum number of subscriptions permitted for a single client and the per-client transport queues. Other characteristics controlled by client profiles include tuning TCP connection parameters, enabling persistent messaging capabilities, and adjusting the point at which certain events are triggered.
Client profiles can be applied to multiple client usernames or LDAP authorization groups in a Message VPN. This enables administrators to manage large groups of clients by making a configuration change once and having it apply to many clients rather than having to make individual changes to each client.
If you do not assign specific client profiles to a client username account, then the system assigns a default client profile automatically to each client username account. You can customize the configuration of the default client profile, but you cannot delete it from 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 Configuring Client Profile Settings.
Creating an event broker service also creates and enables a default client profile. The default client profile has common settings that let you bring up an event broker service and start using it quickly. You can edit and manage all client profiles and also assign them to client usernames after you've created a client profile in Cluster Manager or using the REST API for PubSub+ Cloud.
For more information about configuring client profiles in the PubSub+ Cloud Console, see the following sections:
- Creating a Client Profile
- Modifying a Client Profile
- Deleting a Client Profile
- Creating Client Usernames
- Assigning a Client Profile to a Client Username
- Configuring Client Profile Settings
- Managing Client Profiles with the PubSub+ Cloud REST API
Client Egress Structure Overview
For a published message to be delivered to a client, it passes through the queuing structure shown in the Egress Client Queue Hierarchy figure below.
The message first passes through one of the five per-client priority data queues. A scheduler then selects it and places it into a single, per-client Transmission Control Protocol (TCP) transmit queue.
For Direct messages, the Class of Service (COS) value the publishing client application sets for the message determines which per-client priority queue each message is enqueued to:
- COS 1 (C-1)—the message goes to the Direct 1 (D-1) queue (the lowest priority)
- COS 2 (C-2)—the message goes to the Direct 2 (D-2) queue (medium priority)
- COS 3 (C-3)—the message goes to the Direct 3 (D-3) queue (the high priority)
All Guaranteed messages are enqueued to the Guaranteed 1 (G-1) queue. A Guaranteed message also has an assigned COS value, however, this value determines the message’s discard eligibility when its destination endpoint is congested. COS 1 indicates that the message is low priority; COS 3 indicates that the message is high priority. (COS 2 is a reserved Solace value; currently a message with a COS of 2 is treated as low priority.)
The act of enqueuing the message triggers the TCP stack to evaluate if the connection can send more data from that queue. If the TCP stack determines that it is acceptable to send data on the TCP connection, then data from the message is copied to a per-port transmit queue. After the message is delivered, the data remains on the TCP transmit queue until it is acknowledged by the client through a TCP ACK message.
The per-client priority queues have a configurable maximum depth that is measured in work units of 2,048 bytes. When these queues become full, the older messages currently queued are discarded (oldest first), replaced by the newer incoming messages.
Once a message discard occurs due to the queue being full, the receiving client is notified of it through a discard indication published with the message immediately following the discarded messages. The data plane statistic for Egress Congestion Discards is also incremented.
The per-client TCP transmit queues hold messages that are either waiting for delivery out of the event broker, or that have already been sent, but are waiting for TCP acknowledgment.
Creating a Client Profile
You can create a client profile if your user profile has been assigned the Administrator role for that account.
- 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
- On the navigation bar, select Cluster Manager
, and then click the event broker service for which you want to add a client profile. - Select the Manage tab and then click Client Profiles.
- In the Client Profiles pane, click Add New.
- In the Profile Name field, type a unique name for the client profile.
- In the Basic Settings section, you can set the options as required.
- (Optional) Click the Advanced Settings drop-down list and set the options as required. For example, depending on the size of your service, you might want to set the maximum client connections per client username because the default is 100. If your service class is large, you might want to set this higher.
For more information about the settings, see Configuring Client Profile Settings.
Modifying a Client Profile
You can modify the settings for an existing client profile. Your user profile must be the assigned the Administrator role for the account to modify an existing client profile.
- 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
-
Select Cluster Manager from the navigation bar.
- On the Services page, the event broker service for which you want to modify a client profile. If the event broker service is not listed, make sure you have the right environment selected. For more information, see Selecting and Changing Environments.
- Select the Manage tab and then click Client Profiles.
- In the Client Profiles pane, click the name or the Edit
button beside the name of the client profile you want to modify. - In the Basic Settings section, you can set the options as required.
- (Optional) Click the Advanced Settings drop-down list and set the options as required.
For more information about the settings, see Configuring Client Profile Settings.
Deleting a Client Profile
You can delete existing client profile that you create, but you cannot delete the default client profile. Your user profile must be the assigned the Administrator role for the account to modify an existing client profile.
- 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
- Select Cluster Manager from the navigation bar.
- On the Services page, the event broker service for which you want to delete a client profile. If the event broker service is not listed, make sure you have the right environment selected. For more information, see Selecting and Changing Environments.
- Select the Manage tab and then click Client Profiles.
- In the Client Profiles pane, click the name or the Delete
button beside the name of the client profile that you want to remove.
Creating Client Usernames
Prior to creating a client username, you can create a client profile. 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 provided client profile is called "default".
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, you use must use Access Controls in PubSub+ Broker Manager.
- 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
- Select Cluster Manager from the navigation bar.
- On the Services page, the event broker service for which you want to add a client profile. If the event broker service is not listed, make sure you have the right environment selected. For more information, see Selecting and Changing Environments.
- Select the Manage tab and then click Access Control, which opens the Access Control page in Broker Manager.
- In Broker Manager, on the Access Control page, select the Client Usernames tab.
- In the top-right corner, click the +Client Username button.
- In the Create Username dialog, enter a name for your client username and then click Create.
- On the Edit Client Username Settings page.
- toggle on Enable
- click Change Password and enter a new password in the New Password and Confirm Password fields
- In the Client Profile list, select the profile to use with the client username.
- Click Apply.
You can use the client username to access the event broker service after you have assigned a client profile to it.
Assigning a Client Profile to a Client Username
By default, all client usernames use the default client profile. Client usernames are configured in Broker Manager. Broker Manager is a separate web-based application that connects you to the event broker service that you may be pre-authenticated to connect. For more information about connecting to Broker Manager, see Pre-Authentication for Broker Manager.
- 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
- Select Cluster Manager from the navigation bar.
- On the Services page, the event broker service for which you want to assign a client profile. If the event broker service is not listed, make sure you have the right environment selected. For more information, see Selecting and Changing Environments.
- Select the Manage tab and then click Access Control, which opens the Access Control page in Broker Manager. You are now directly connected to the event broker service.
- In Broker Manager, select the Client Usernames tab and click the client username you want to change.
- On the page for the client username you selected, click Edit located on the top-right of corner of the page.
- In the Client Profile drop-down list, select the name of the client profile you want the client username to use, and then click Apply.
Configuring Client Profile Settings
There are a number of basic settings and advanced settings that you can modify for a client profile.
For information about creating or editing client profiles, see Creating a Client Profile and Modifying a Client Profile.
PubSub+ Cloud provides a subset of the configuration options applicable to event broker services. Contact Solace if there's a setting that you require that is not available.
The following are the options that you can configure:
Basic Settings
These settings are commonly modified when creating a client profile.
- Profile Name
-
The name of the client profile. The name can be up to 32 alphanumeric characters (case-sensitive) and can also include underscores and dashes.
- Send guaranteed messages
-
Allow clients assigned to the client profile to publish Guaranteed Messages (that is non-persistent or persistent messages). This option is enabled by default.
- Receive guaranteed messages
-
Allow clients assigned to the client profile to bind to topic endpoints or queues. This option is enabled by default.
- Use transacted sessions
-
Transacted sessions (that is, local transacted sessions and/or XA 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. This option is enabled by default.
- Connect as a bridge
-
Allow for inter-connection between the Message VPN in the HA group to another HA group using DMR links. This option is enabled by default.
- Use Compression
-
Allow client applications to transfer data using compression. This option is disabled by default.
- Connect When Replication Standby
-
Allow 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. This option is disabled by default.
- Allow client to create endpoints
-
Allow client applications assigned to the client profile to create queues or topic endpoints. This option is enabled by default.
-
Optionally, you can specify to copy settings from an existing queue or topic endpoint:
- Copy settings from queue name: The name of the queue to copy the settings from
- Copy settings from queue template: The name of the queue template to copy the settings from
- Copy settings from topic endpoint name: The name of the topic endpoint to copy the settings from
- Copy settings from topic endpoint template: The name of the topic endpoint template to copy the settings from
-
When a client using Solace messaging APIs dynamically creates an endpoint, its configuration is determined first by those endpoint properties and provision flags that the client can provide with the API to create a queue or topic endpoint. Any remaining endpoint parameters to be configured are then filled by the values specified in the copy settings from the specified queue or topic endpoint. To receive published Guaranteed messages (that is, messages that have a delivery mode of Persistent or Non‑Persistent), a client must create a consumer Flow to bind to a Queue endpoint or a Topic Endpoint provisioned on the event broker. Once the client is bound to the endpoint, it can receive published Guaranteed messages that are delivered and spooled to that endpoint.When a consuming client successfully receives a Guaranteed message over a Flow, a corresponding application acknowledgment is required to indicate to the event broker that the client application received the message, and then the message can be removed from the endpoint.
Advanced Settings
These are settings to further configure messaging settings for client applications.
- Add Shared Subscriptions
-
Because allowing indiscriminate access to MQTT and SMF shared subscriptions is a potential security issue (where a client could join a shared subscription and siphon off a portion of the traffic), you can configure whether specific clients can use shared subscriptions. This option is enabled by default.
-
Allowing shared subscriptions is an all or nothing setting. This means that 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 to configure a list of share names that are permitted (or denied) and then associate it with a client profile.
- Enable Message Eliding
-
Eliding allows you to define a custom per-topic rate for client applications so they can effectively consume relevant messages, rather than queuing up outdated messages. For example, when eliding is configured, clients could receive direct messages for their topic subscriptions at a rate of at most five per second, per topic – even though the source is publishing updates at a much higher rate. This option is disabled by default.
- Eliding Delay (ms)
-
The amount of time to delay the delivery of messages to a client after the initial message has been delivered. You can specify a value from 0-6000 milliseconds. The default is 0.
- Maximum Eliding Topics Per Client Connection
-
The maximum number of topics the event broker service that can track for performing the eliding function on each client connection. You can specify a value from 1-320000. The default is 256.
- Maximum client connections per client username
-
For a given client profile, you can configure the maximum, permitted 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. That is, this limit applies to all client connections regardless of whether they use Solace Message Format (SMF), Web transport, REST, MQTT, or AMQP protocols. The default is 100.
- SMF client connections per client username
-
PubSub+ Cloud uses the Solace Message Format (SMF) as its underlying messaging transport protocol.
-
For the client profile, you can configure the maximum permitted number of simultaneous SMF client connections to the event broker that can be made using the same client username account. The default is 1000.
- Client Keepalive
-
The keepalive value for MQTT and SMF (Solace Message Format) connections. The keepalive timeout value is calculated based on the client provided timeout interval (3 x the keepalive interval for SMF connections, 1.5 x the keepalive interval for MQTT connections). For the given client profile, you can choose to impose a minimum timeout value in seconds using the Minimum Keepalive. You can also choose whether to enforce that minimum timeout value on SMF clients.
-
- Enable Minimum Keepalive Timeout for SMF
-
Toggle this option to have the event broker service enforce the minimum keepalive timeout on SMF connections. This option is disabled by default. Toogle this option to enable it.
- Minimum Keepalive
-
The minimum period of time (in seconds) that the event broker service will tolerate inactivity on the client connection. The minimum keepalive value is enforced on MQTT and SMF connections. The minimum keepalive is not enforced on SMF connections if the Enable Minimum Keepalive Timeout for SMF is disabled. The default is 30 and valid ranges are 3–3600.
- Web transport client connections per client username
-
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. The default is 1000.
- Web Transport - Inactive Timeout (sec)
-
The number of seconds a Web client has to send a request before its session times out and be terminated for being inactive.
- Web Transport - Maximum Web Transport Payload Size (B)
-
Allows you to set the maximum transport payload size.
-
Solace Message Format (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 that is sent 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 range is 300 to 10000000, in bytes. The default is 1000000 bytes.
-
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 that is sent 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.
Large SMF messages can be fragmented across Web transport messages to respect the value set for the maximum possible Web payload.
- Maximum queues and topic endpoints created per client username
-
The maximum number of durable and non-durable queues and topic endpoints that can be owned by the clients using the same client username within a client profile. The default is 100.
- Maximum outgoing flows per client
-
The maximum number of egress flows (that is, Guaranteed Message client receive flows or consumer flows) that can be created by a single client associated with this client profile. The default is 100.
- Maximum incoming flows per client
-
The maximum number of ingress flows (that is, Guaranteed Message client publish flows) that can be created by a single client associated with this client profile.
- Maximum subscriptions per client
-
The maximum number of subscriptions for a single client in the client profile. 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 that is used. That is, 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. The default is 1000.
- Maximum transacted sessions per client
-
The maximum number of simultaneous transacted sessions and/or XA Sessions allowed for a single client associated with the client profile. The default is 100.
- Maximum transactions per client
-
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. The default is 500.
- Initial TCP congestion window size
-
The TCP initial congestion window size is used when starting up 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.
-
Changing the TCP initial congestion window size from its default of 2 results in non-compliance with RFC 2581. Further, if this setting is set to a value too high, it may cause congestion in the network. Contact Solace before you attempt to change this TCP parameter.
- TCP keep alive retry count
-
The maximum number of
keepaliveprobes (from 2 to 5 ) that TCP should send before dropping the connection. The default is 5. - TCP keep alive idle time
-
The time (from 3 to 120 seconds) a connection must remain idle before TCP begins sending
keepaliveprobes. The default is 3. - TCP keep alive interval
-
The time (from 1 to 30 seconds) to set as the interval between individual keepalive probes. The default is 1.
- Maximum TCP segment size
-
The TCP maximum segment size (MSS) used for client to the event broker service. The default is 1460.
- Maximum TCP window size
-
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. The default is 256.
-
Alternatively, if the TCP maximum window size is set 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.
- Reject Messages to Sender On No Subscription Match Discard
-
Set that NACKs should be returned for published Guaranteed messages that do not have Guaranteed message subscription matches. This option is disabled by default.
- TLS Port: allow downgrading connection to plain-text
-
Allow TLS/SSL encryption to protect the clients' credentials but don't encrypt the data that is transmitted after the clients are authenticated and authorized. This setting allows connecting client applications to request to downgrade of their TLS/SSL connections to the Message VPN to a plain-text connection, and if that Message VPN allows TLS/SSL connection downgrades, after the client's login handshake is finished, their connections are downgraded. This means that the client's authentication data is still encrypted, but the subsequent application data that is transmitted is sent as non-encrypted plain-text. This option is enabled by default.
- Provisioned Endpoint Spool Usage Alert Thresholds (%)
-
Set 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 clients for the given client profile.
- Clear Percent
-
The clear threshold value for the message spool usage (as a percentage). The default is 60.
- Raise Percent
-
The raise threshold value for the message spool usage (as a percentage). The default is 80.
- Priority Queues - G-1 Maximum Depth
-
Set 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. The default is 20000.
- Priority Queues - G-1 Minimum Burst
-
Set the minimum number of messages that must be on the Guaranteed Message 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 with the default of 255. 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 Structure Overview.
- Priority Queues - D-1 Maximum Depth
-
Set 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. The default is 20000. For information about egress queues, see Client Egress Structure Overview.
- Priority Queues - D-1 Minimum Burst Depth
-
Set 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 with the default of 4. For information about egress queues, see Client Egress Structure Overview.
- Priority Queues - D-2 Maximum Depth
-
Set 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. The default is 20000. For information about egress queues, see Client Egress Structure Overview.
- Priority Queues - D-2 Minimum Burst Depth
-
Set 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 with the default of 4. For information about egress queues, see Client Egress Structure Overview.
- Priority Queues - D-3 Maximum Depth
- Set 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. The default is 20000.
- Priority Queues - D-3 Minimum Burst Depth
-
Set 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 with the default of 4.
- Priority Queues - C-1 Maximum Depth
-
Set 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. The default is 20000. For information about egress queues, see Client Egress Structure Overview.
- Priority Queues - C-1 Minimum Burst Depth
-
Set 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 with the default of 4. For information about egress queues, see Client Egress Structure Overview.