Services

Clients and management users access the services available on the Solace PubSub+ through TCP service ports on an event broker.

Solace PubSub+ event brokers support the following services:

• Solace Message Format (SMF)—This service allows clients to communicate with an event broker on the Message Backbone interface.
• Solace Element Management Protocol (SEMP)—This service allows management applications to communicate with an event broker on the Management interface.
• Web transport—This service allows Web clients to communicate with an event broker.
• Solace Representational State Transfer (REST)—This service allows REST clients to communicate with an event broker using standard HTTP requests.
• Message Queuing Telemetry Transport (MQTT)—This service allows clients to communicate with an event broker using the MQTT messaging protocol.
• Advanced Message Queuing Protocol (AMQP)—This service allows AMQP clients to communicate with an event broker using the AMQP open standard application layer protocol.

SMF Service Management

At the system-level, you can configure a listen port for SMF service and enable/disable SMF service on all Message VPNs on the event broker. You can also configure SMF events and event thresholds.

Setting SMF Listen Ports

You must shutdown SMF services on the event broker before setting the SMF listen ports, otherwise an error message is received.

To configure the TCP port number that SMF clients use when connecting to the event broker, enter the following commands:

solace(configure)# service smf
solace(configure/service/smf)# listen-port <port> {[compressed] [routing-control] [ssl]}

Where:

<port> specifies the TCP port number that SMF clients use when connecting to the event broker. The default value is 55555.

compressed specifies the port to connect to for exchanging Non-SSL compressed messages.

routing-control specifies the port to connect to for exchanging inter-node routing control messages. Note that Inter-node routing control messages cannot run over the compressed port. Therefore, you cannot specify compressed along with routing-control.

ssl specifies the port to connect to for exchanging Transport Layer Security (TLS)/ Secure Sockets Layer (SSL) traffic (with or without compression).

The no versions of this command do the following:

• no listen-port resets the port to the default value of 55555
• no listen-port compressed resets the port to the default value of 55003
• no listen-port routing-control resets the port to the default value of 55556
• no listen-port ssl resets the port to the default value of 55443

Enabling System-Level SMF Service

By default, SMF services are enabled on both Solace PubSub+ appliances and Solace PubSub+ software event brokers.

• To enable SMF service on the event broker, enter the following commands:

  solace(configure)# service smf
  solace(configure/service/smf)# no shutdown

• To disable SMF services on the event broker, enter the following commands:

  solace(configure)# service smf
  solace(configure/service/smf)# shutdown

Configuring SMF Events

You can optionally configure the set and clear thresholds at which system-level events are generated for a number or percentage of simultaneous SMF client connections. For information on how system-level service events can be generated and how to set the event thresholds for them, see Configuring System Event Thresholds.

SEMP Service Management

At the system-level, you can do the following:

• configure a listen port for SEMP service
• enable/disable extended timeouts for paged GETs
• enable/disable SEMP service on an event broker
• set the timeout values for client user sessions
• enable or disable Cross-Origin Resource Sharing (CORS) for the SEMP service

Setting a SEMP Listen Port

You must first shutdown SEMP service on the event broker before you can set a SEMP listen port.

To configure the TCP port number for SEMP clients to use when connecting to an event broker, enter the following commands:

solace(configure)# service semp
solace(configure/service/semp)# listen-port <port> [ssl]

Where:

<port> specifies the TCP port number to use for a SEMP connection to the event broker. The default value for plain text connections is 80.

ssl specifies the port number is for TLS/SSL-encrypted connections. The default value TLS/SSL connections is 55443.

The no versions of this command do the following:

• no listen-port resets the port to the default value for plain text connections
• no listen-port ssl resets the port to the default value for TLS/SSL connections

Enabling Extended SEMP Timeouts for Paged GETs

Wildcarded show commands may return paged data even if paging was not requested, especially if the command takes more than a few seconds to execute. In addition, when paged data is returned, the number of entries returned may be fewer than the number of entries requested. In some cases, paged responses may be completely empty (including only a more-cookie). Clients must be written to accept paged data of any size less than or equal to the requested page size.

You can enable or disable extended SEMP timeouts to assist in keeping your system running while you update your clients to use paging. When enabled, the amount of time available for the system to produce a response before paging is forced on a client is increased to 60 seconds. When disabled, the timeout is 5 seconds.

By default, extended SEMP timeouts for paged GETs are disabled.

• To enable extended SEMP timeouts for paged GETs on the event broker, enter the following commands:

  solace(configure)# service semp
  solace(configure/service/semp)# legacy-timeout

• To disable extended SEMP timeouts for paged GETs, enter the following commands:

  solace(configure)# service semp
  solace(configure/service/semp)# no legacy-timeout

Enabling System-Level SEMP Service

• To enable SEMP services on the event broker, enter the following command:

  solace(configure/service/semp)# no shutdown

• To disable SEMP services on the event broker, enter the following command:

  solace(configure/service/semp)# shutdown

Managing SEMP Sessions

When a client makes its first SEMPv2 request, it must supply a username and password using basic authentication.

If authentication is successful, the event broker returns a cookie containing a session token. The client can omit the username and password from subsequent requests, because the event broker now uses the session cookie for authentication instead. When the session expires or is deleted, the client must provide the username and password again, and the event broker creates a new session.

To see how sessions are used with the SEMP v2 API, see SEMP API Architecture.

You can configure two types of timeouts for sessions:

session-idle-timeout

The session idle timeout, in minutes. Sessions are invalidated if there is no activity in this period of time. The default value is 15 minutes.

session-max-lifetime

The maximum lifetime of a session, in minutes. Sessions are invalidated after this period of time, regardless of activity. The default value is 43200 minutes (equivalent to 30 days).

To set the session-idle-timeout value, enter the following commands in the CLI:

solace-1> enable
solace-1# configure
solace-1(configure)# service
solace-1(configure/service)# semp
solace-1(configure/service/semp)# session-idle-timeout 30

To set the session-max-lifetime value, enter the following commands in the CLI:

solace-1> enable
solace-1# configure
solace-1(configure)# service
solace-1(configure/service)# semp
solace-1(configure/service/semp)# session-max-lifetime 43260

To show the settings:

solace-1> show service semp

Service:                  SEMP
Config Status:            Enabled
Oper Status (Plain-text): Up
Oper Status (SSL):        No Cert
VRF:                      management
Port (Plain-text):        8080
Port (SSL):               1943
Legacy Timeout:           No
Session Idle Timeout:     15 minutes
Session Maximum Lifetime: 43200 minutes
CORS Allow Any Host:      No

To delete a session:

solace-1> enable
solace-1# admin
solace-1(admin)# semp-session <username-pattern> [session-id <session-id-value>]
solace-1(admin/semp-session)# delete

Sessions are also used by Broker Manager. For details, see Broker Manager Sessions.

Managing Cross-Origin Resource Sharing

You can enable or disable Cross-Origin Resource Sharing (CORS) for the SEMP service. By default, CORS is disabled for enhanced security.

Enabling CORS generates CORS-compliant headers that permit JavaScript loaded from any host to access the SEMPv2 endpoints on the event broker. This is helpful in case you have JavaScript tools or browser-based clients that involve management actions and where there's a low risk of security vulnerabilities.

To enable CORS, run the following commands:

solace-1> enable
solace-1# configure
solace-1(configure)# service
solace-1(configure/service)# semp
solace-1(configure/service/semp)# cors
solace-1(configure/service/semp/cors)# allow-any-host

REST Service Management

Solace PubSub+ event brokers can support REST clients. At the system-level, you can enable or disable REST incoming and/or outgoing connections to the event broker. You can also configure REST events and event thresholds.

Enabling Incoming REST Connections

By default, service for incoming REST service connections is not running on an event broker.

• To enable incoming REST service connections on the event broker, enter the following commands:

  solace(configure)# service rest
  solace(configure/service/rest)# incoming
  solace(configure/service/rest/incoming)# no shutdown

• To disable incoming REST service connections on the event broker, enter the following commands:

  solace(configure)# service rest
  solace(configure/service/rest)# incoming
  solace(configure/service/rest/incoming)# shutdown

Enabling Outgoing REST Connections

By default, service for outgoing REST service connections is not running on an event broker.

• To enable outgoing REST service connections on the event broker, enter the following commands:

  solace(configure)# service rest
  solace(configure/service/rest)# outgoing
  solace(configure/service/rest/outgoing)# no shutdown

• To disable outgoing REST service connections on the event broker, enter the following commands:

  solace(configure)# service rest
  solace(configure/service/rest)# outgoing
  solace(configure/service/rest/outgoing)# shutdown

Configuring REST Events

For information on configuring REST client event thresholds, see Configuring REST Outgoing Service Event Thresholds.

Web Transport Service Management

At the system-level, you can configure a listen port for Web Transport service, specify the Web URL suffixes, and enable/disable Web Transport service on all Message VPNs on an event broker.

Setting Web Transport Listen Ports

You must first shutdown Web Transport services on the event broker before setting the Web Transport listen ports.

To configure the TCP port number for Web clients to use when connecting to the event broker, enter the following commands:

solace(configure)# service web-transport
solace(configure/service/web-transport)# listen-port <port> [ssl]

Where:

<port> specifies the TCP port number that Web clients use when connecting to the event broker. The default value is 80.

ssl specifies the port to connect to for exchanging TLS/SSL traffic. The default value is 443.

The no versions of this command do the following:

• no listen-port resets the port to the default value of 80
• no listen-port ssl resets the port to the default value of 443

Enabling System-Level Web Transport Service

By default, Web Transport service is not running on an event broker.

• To start Web transport service on the event broker, enter the following commands:

  solace(configure)# service web-transport
  solace(configure/service/web-transport)# no shutdown

• To stop Web transport service on the event broker, enter the following commands:

  solace(configure)# service web-transport
  solace(configure/service/web-transport)# shutdown

Specifying Web URL Suffixes

You can set the Web URL suffix that Web clients will receive from the event broker when they login, and then use when communicating with the event broker (for example, for the purpose of load balancing client sessions).

To specify a Web URL suffix, you must shutdown Web Transport services on the event broker, and then enter the following commands:

solace(configure)# service web-transport
solace(configure/service/web-transport)# web-url-suffix <suffix> 

Where:

<suffix> specifies the text for a Solace Messaging Application Programming Interface (API) to append to the Web URL when communicating with the event broker. This text can contain up to 127 alphanumeric characters and should be unique among all created Web URL suffixes.

The no version of this command, no web-url-suffix, resets the Web URL suffix to the default value of empty string (that is, “ ”).

For more information on session load balancing and use of URLs, see Web Messaging Overview.

MQTT Service Management

You can enable or disable MQTT service at the system-level on event brokers.

Enabling System-Level MQTT Service

You can globally enable/disable MQTT service for an event broker. By default, MQTT service is not enabled.

• To enable MQTT service on the event broker, enter the following commands:

  solace(configure)# service mqtt
  solace(configure/service/mqtt)# no shutdown

• To disable MQTT service on the event broker, enter the following commands:

  solace(configure)# service mqtt
  solace(configure/service/mqtt)# shutdown

AMQP Service Management

Solace PubSub+ event brokers can support AMQP clients. At the system-level, you can enable/disable the AMQP service. Clients can connect via a global and/or per-Message VPN listen ports.

To provide connecting AMQP clients service from an event broker, you must perform the following system-level configurations:

• Setting AMQP Listen Ports
• Configuring the Virtual Hostname(Not required when using per-Message VPN ports)
• Enabling System-Level AMQP Service

Setting AMQP Listen Ports

The AMQP service supports both plain-text and encrypted data transport. If you want to transport plain-text and TLS/SSL data, a separate port must be configured for each transport type. To connect AMQP plain-text clients to an event broker, per-Message VPN AMQP plain-text ports must be configured.

For AMQP TLS/SSL clients to connect to an event broker, you can configure the following listen-ports:

• A global AMQP TLS/SSL port that is shared between all Message VPNs. This configuration is not required when using only per-Message VPN ports.
• per-Message VPN ports that are private to a particular Message VPN.

AMQP Global Port vs per-Message VPN Port

Before the release of version 9.6.0 of the PubSub+ event broker, AMQP clients could only connect to unique ports dedicated to each Message VPN. While this setup works when you have only a few Message VPNs, the port configuration can be challenging to manage when there are many Message VPNs.

Starting with version 9.6.0 of the event broker, a global AMQP TLS/SSL port can be configured. All AMQP TLS/SSL clients can connect to the global port. As a result, per-Message VPN ports are not required and the configuration is much simpler. This consumes fewer ports (one global vs one per-Message VPN), irrespective of the number of Message VPNs. It also potentially reduces firewall configuration.

If you have both the global port and per-Message VPN port configured, the client can connect to either one. For global port connections, virtual hostnames must be configured to map the client-provided hostname to the corresponding Message VPN. Note that clients connecting to the global port must connect via TLS with the hostname set in the Server Name Indication (SNI). For more information about virtual hostnames, see Configuring the Virtual Hostname.

Also, when connecting to the global port, clients must be able to validate the event broker’s server certificate based on the virtual hostname that they are connecting to. The standard way to ensure this is to add the virtual hostname to the subject alternate name (or wild card that covers the virtual hostname) of the event broker’s server certificate.

Setting Global AMQP Listen Ports

To set a global listen port for AMQP connections, enter the following commands:

solace(configure)# service amqp
solace(configure/service/amqp)# listen-port <port> ssl

The no version of this command, no listen-port ssl, removes the currently configured port number.

Where:

<port> is the port number from 1 to 65535.

ssl specifies that the given port will use a TLS transport.

To change the global listen port, the AMQP service must be shutdown globally. Refer to Enabling System-Level AMQP Service

Setting per-Message VPN AMQP Listen Ports

To set per-Message VPN listen ports for AMQP connections , see Set Message VPN AMQP Listen Ports.

Configuring the Virtual Hostname

A virtual hostname is configured on the event broker to map the client provided hostname to the corresponding Message VPN. This mapping is used only for connections arriving through the global AMQP port. If a client connects through the per-Message VPN port, the virtual hostname (if provided) is ignored. Refer to Setting AMQP Listen Ports for information on global and per-Message VPN listen ports.

Clients that connect to a global port and provide a hostname, through the Server Name Indication (SNI), will be directed to its corresponding Message VPN. An exact case-insensitive match is performed on the client-provided hostname against the configured virtual hostnames. This mechanism is supported only for AMQP and only for hostnames provided through the SNI extension of TLS. If a mapping for a hostname does not exist or points to a nonexistent Message VPN, the client login will fail.

Note that the virtual-hostname is restricted to contain only ASCII characters. To represent an internationalized domain name by a virtual-hostname on the event broker, you must first convert the non-ASCII characters to the punycode-encoded A-label form. For example, if an application were to use "éxample.com" as a virtual-hostname, it must be configured as the virtual-hostname "xn--xample-9ua.com" on the event broker.

To configure a virtual hostname, enter the following commands:

solace(configure)# service 
solace(configure/service)# create virtual-hostname <name>

The no version of this command, no virtual-hostname <name>, removes the virtual hostname. It must be disabled to be removed.

Where:

<name> is the virtual hostname. It must be an FQDN (1..253 characters) or an IP address (nnn.nnn.nnn.nnn).

Mapping the Virtual Hostname to a Message VPN

To map the virtual hostname to the corresponding Message VPN, enter the following command:

solace(configure/service/virtual-hostname)# message-vpn <vpn-name>

The no version of this command, no message-vpn, removes the Message VPN mapping.

Where:

<vpn-name> is the name of the Message VPN to connect to.

Enabling the Virtual Hostname

The virtual hostname to Message VPN mapping is disabled by default. You can enable it by executing the following command:

solace(configure/service/virtual-hostname)# no shutdown

To disable the virtual hostname to Message VPN mapping, enter the following command:

solace(configure/service/virtual-hostname)# shutdown

Enabling System-Level AMQP Service

You can enable or disable the AMQP service at the system-level on the event broker.

• To enable the AMQP service for the event broker, enter the following commands:

  solace(configure)# service amqp
  solace(configure/service/amqp)# no shutdown

• To disable the AMQP service for the event broker, enter the following commands:

  solace(configure)# service amqp
  solace(configure/service/amqp)#  shutdown

Enabling All Messaging Services

The Solace event broker Message Backbone is a Virtual Routing and Forwarding (VRF) object that contains all Solace event broker interfaces (physical, LAG, and IP), and transports message and topic subscription traffic between client applications and the virtual routers on the event broker.

The message backbone acts as a global switch that enables or disables all messaging services at the global level. Disabling the message backbone disables all messaging services until the message backbone is re-enabled.

Services that are disabled using the message backbone switch will retain their individually configured states when the message backbone is re-enabled. For example, if Web transport service is in a disabled state when the message backbone is disabled, Web transport service will remain disabled when the message backbone is re-enabled.

To shut down the message backbone to disable all messaging services at a global level, enter the following commands:

solace(configure)# service msg-backbone shutdown
All clients will be disconnected.
Do you want to continue (y/n)? y

The no version of this command, no msg-backbone shutdown, globally enables messaging service. Services that were disabled before the message backbone was shutdown will remain disabled when this command is run.

Managing Service Event Thresholds

To configure the thresholds that define when system‑level events are generated for the number of simultaneous client connections to the event broker, enter the following command:

solace(configure)# service event

The CLI is now at a level at which you can configure the set and clear event thresholds at which system-level events are generated for the number of simultaneous client connections. These thresholds are set according to the service type used (for example, SMF, Web Transport, REST). For more information, see Configuring System Event Thresholds.