Services

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

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 (appliances) and as data traffic (software event brokers).
Solace Element Management Protocol (SEMP)—This service allows management applications to communicate with an event broker on the management (appliances) and as data traffic (software event brokers)..
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.

Config-Sync does not automatically synchronize services. Therefore, if the event broker is being used in a high-availability (HA) redundant deployment or in a replicated site, you must manually configure services on each mate event broker or replicated Message VPN.

To determine whether an object/property is synchronized by Config-Sync, look up the command used to configure the object/property in the CLI Command Reference or type the command in the Solace CLI, ending the command with "?". The Help will list whether the object or property is synchronized.

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

Disabling SMF service at the system-level will disconnect all client and event broker connections to the event broker. Therefore, it is recommended that if you need to stop SMF service on the event broker, you do so when the service disruption will have the least impact. Also, to avoid such a large service interruption, you can optionally disable SMF service only on specific Message VPNs (see Configuring SMF Service).

By default, SMF services are enabled on both PubSub+ appliances and 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.

ssl specifies the port number is for TLS/SSL-encrypted connections.

The default ports for port and ssl depend on whether it's a software event broker or appliance. For information about which port to use, see Default Port Numbers.

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.

Enabling extended timeouts is meant as a temporary solution and should be used only while SEMP clients are updated so that they can handle short pages.

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

Shutting down SEMP service at the system-level will cause a disruption in management service when run since it disconnects all SEMP and SolAdmin connections from the event broker. Therefore, it is recommended that if you need to stop SEMP service on the event broker, you do so when the service disruption will least impact to clients.

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, which is 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

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

Shutting down REST service at the system-level disconnects all REST clients from the event broker and new clients will not be able to connect. Therefore, Solace recommends that if you need to stop the REST service on the event broker that you do so when the service disruption will least impact client applications.

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.

ssl specifies the port to connect to for exchanging TLS/SSL traffic.

The default ports for port and ssl depend on whether it's a software event broker or appliance. For information about which port to use, see Default Port Numbers.

The no versions of this command do the following:

no listen-port resets the port to its default value.
no listen-port ssl resets the port to its default value.

Enabling System-Level Web Transport Service

Shutting down Web transport service at the system-level will disconnect all Web transport clients from the event broker and new clients will not be able to connect. Therefore, it is recommended that if you need to stop Web transport service on the event broker, you do so when the service disruption will least impact clients. Also, to avoid such a large service interruption, you can optionally disable Web transport service only on specific Message VPNs (see Configuring 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

Web Transport service is locked by default on PubSub+ appliances that are older than the SolOS version 8.4.0. To unlock Web Transport service on those appliances, you must have a valid product key supplied by Solace. For more information, see Product Keys .
To enable Web transport clients to connect to the event broker, you must start SMF services on the event broker because Web transport clients are also considered to be SMF clients. For more information, see Enabling System-Level SMF Service.

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 PubSub+ Messaging 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 or 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
```

If you disable the MQTT service at the system level, you will disconnect all clients currently connected to any MQTT service-enabled Message VPNs on the event broker, and new clients will not be able to connect. Therefore, it's recommended that if you need to stop the MQTT service, you should do so when the service disruption will have the least impact. Also, to avoid large service interruptions, you have the option of disabling the MQTT service on individual Message VPNs (see Enabling and Disabling MQTT Connections).

AMQP Service Management

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

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
```

If you disable the AMQP service at the system level, you will disconnect all clients currently connected to any AMQP service-enabled Message VPNs on the event broker. To avoid such a large service interruption, you can disable the AMQP service only on specific Message VPNs (see Enable/Disable AMQP Service for VPNs).

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, the Web transport service will remain disabled when the message backbone is re-enabled.

Config-Sync will not automatically synchronize this object or property. Therefore, if the event broker is being used in a high-availability (HA) redundant configuration or in a replicated site, you must manually configure this object/property on each mate event broker or replicated Message VPN.

To determine whether an object/property is synchronized by Config-Sync, look up the command used to configure the object/property in the CLI Command Reference or type the command in the Solace CLI, ending the command with "?". The Help lists whether the object/property is synchronized.

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.

Provide feedback