Legacy SEMP

This section provides information on the older version of SEMP, SEMP v1, which uses an XML schema for monitoring and managing event brokers. For information on the current SEMP release, SEMP v2, which is a RESTful API, see SEMP. You should be aware that configuring the same event broker object concurrently with both SEMP v2 and Legacy SEMP/CLI is not supported, and may result in unexpected behavior.

Using SEMP v1 to Manage and Monitor Event Brokers

Solace Element Management Protocol (SEMP v1) is a request/reply protocol that uses an XML schema to identify all managed objects available in an event broker. Any object available through the event broker Command Line Interface (CLI) or SolAdmin is also available through SEMP v1.

Applications can use SEMP v1 to manage and monitor an event broker. It uses a simple request/reply paradigm to send XML-encoded requests to the event broker and receive corresponding XML-encoded replies. These requests and replies parallel the commands and replies offered through Solace CLI.

Running gather-diagnostics via legacy SEMP or from SolAdmin (which uses legacy SEMP) will stop all other SEMP requests from being serviced until gather-diagnostics completes. Running gather-diagnostics normally takes several minutes. If this is a problem, we recommend that you run gather-diagnostics via the Solace CLI.

SEMP v1 XML-encoded commands and replies are either wrapped in HTTP requests and responses and sent over a TCP connection (SEMP v1 Request over HTTP) to the management interface, or sent over the event broker message bus (SEMP v1 Request Over Message Bus) using one of the PubSub+ Messaging APIs or any messaging protocol that supports the request/reply message exchange pattern.

The following figure shows both the SEMP v1 Request over HTTP and SEMP v1 Request Over Message Bus access methods.

A diagram illustrating the access mechanisms described in the surrounding text.

SEMP v1 Request and Reply Schema Files

You can obtain the SEMP v1 schema files by doing one of the following:

  • To obtain the SEMP v1 Request schema file, perform a GET on the following URI:

    http://<HOST>/SEMP/v1/requestSchema.xsd

  • To obtain the SEMP v1 Reply schema file, perform a GET on the following URI:

    http://<HOST>/SEMP/v1/replySchema.xsd

SEMP v1 Polling Frequency Guidelines

The event broker supports a maximum SEMP v1 polling rate of ten requests per second.

When you are using SEMP v1 paging and a more-cookie is returned, the single page constitute a single request . For information on oversized responses and the more-cookie, see SEMP v1 Paging.

The following SEMP v1 requests should not be polled more than once every 30 seconds due to the large amount of data that could be returned.

  • show cache-instance <name> remote status
  • show cache-instance <name> remote topics
  • show queue <name> message-vpn <name> rates
  • show smrp subscriptions
  • show topic-endpoint <name> message-vpn <name> rates

The time the responses take to be returned may vary depending on the amount of information on the event broker. For large amounts of data, the poll responses may take more than 30 seconds.

The following SEMP v1 requests should not be polled.

  • show queue <name> message-vpn <name> messages
  • show topic-endpoint <name> message-vpn <name> messages
  • show replay-log <name> message-vpn <name> messages

Secure Connections

Applications can optionally create secure connections to an event broker to safeguard authentication information and the data that is transmitted. By default, the SEMP v1 data that is exchanged between a management application and an event broker through an established connection is transmitted as plain text. Secure connections use Transport Layer Security (TLS)/ Secure Sockets Layer (SSL) protocols to encrypt the SEMP v1 data that is exchanged so that SEMP v1 data is transported using TLS/SSL over TCP instead of plain text over TCP.

PubSub+ event brokers support TLSv1.0, TLSv1.1, and TLSv1.2 (SSLv1.0, v2.0, and v3.0 are not supported).

To create a TLS/SSL-encrypted connection, the event broker must be properly configured for TLS/ SSL service and the appropriate server certificate must be in place. For information on configuring an event broker to allow for secure connections, see TLS / SSL Service Configuration.

The following configurations are also required on the client-side:

  • When using SEMP v1 over HTTP, an HTTPs URI scheme and a secure port (by default, port 443 on an appliance and port 1943 on a software broker) must be specified to create a secure connection.
  • When using SEMP v1 over message bus service, a number of TLS/SSL-specific Session properties must be specified to create a secure Session.

    For information on these properties, see Creating Secure Sessions for the PubSub+ Messaging APIs and/or Secure Connections for the PubSub+ Messaging API for JMS.

SEMP v1 Request Over HTTP Service

A management application can use the SEMP v1 interface to communicate with the event broker over HTTP as follows:

  1. A management application opens a TCP connection.

    For information about which port to use, see Default Port Numbers (for appliances and software event brokers) and Client Application Connectivity and Security (for PubSub+ Cloud).

    For information on how to set the SSL listen port on an event broker, see Enabling System-Level SEMP Service.

  2. The management application then sends HTTP POST messages to issue SEMP v1 commands to the event broker.

    If a TLS/SSL connection is required, an HTTPs URL scheme must be used.

    The management application must wait for the reply to each command before issuing the next command.

  3. The event broker sends an HTTP response back for each HTTP POST request, containing the SEMP v1 reply.

    At this point, the management application can close the connection, or keep the connection open for future HTTP POST requests.

    The event broker supports a maximum of 500 concurrent SEMP v1 requests over HTTP sessions.

SEMP v1 Request Over Message Bus Service

The SEMP v1 Request Over Message Bus feature is provided as a light-weight alternative to the full administrative access that is supported by the SEMP v1 Request Over HTTP transport service. This feature allows network management and client applications that support request/reply convenience functions and methods to manage an event broker. For example, a client application using a messaging API can publish a request to a destination that uses a specific command topic, and the event broker returns a reply back to the client application.

MQTT and OpenMAMA clients do not support SEMP v1 Request Over Message Bus functionality.

The SEMP v1 Request Over Message Bus, when enabled for a Message VPN, can give a client application access to show User EXEC commands, client Admin EXEC commands, and distributed cache Admin EXEC commands within the Message VPN that the client application is connected to. Unless a Message VPN has been designated as the Management Message VPN, an application may only request data through show commands and run administration commands for the Message VPN to which it is connected. The event broker will reject any requests for information about any managed object not contained in that Message VPN.

By default, the SEMP v1 data that is sent between a client application and an event broker through a connected Session is transmitted as plain text. However, it is also possible to establish a secure Session that uses TLS/SSL protocols to encrypt the SEMP v1 data. For information on specific TLS/SSL Session properties and how to establish a secure Session, see Creating Secure Sessions for the PubSub+ Messaging APIs and/or Important Connection Properties for the PubSub+ Messaging API for JMS.

SEMP v1 on software event brokers does not support TLSv1.0.

SEMP v1 Formatting

To use the SEMP v1 Request transport service, the following formatting conventions are used:

HTTP Request Format

The following is an example of an HTTP POST request from a management application to issue a SEMP v1 command to an event broker:

POST /SEMP HTTP/1.1
Authorization: Basic <usernameAndPassword>
Content-Length:<length>
<SEMP command>

Where:

<usernameAndPassword> is the username and password for the user. The username and password must be encoded as described in RFC 2617: Section 2: Basic Authentication Scheme.

OAuth authentication is also supported using one or more OAuth tokens in the HTTP Authorization header as a bearer token. For more information see OAuth Authentication.

<length> indicates the length (in bytes) of the SEMP v1 command that follows the HTTP header.

<SEMP command> is the contents of the SEMP v1 command being sent (see SEMP v1 Command Format). The application can only send one SEMP v1 command for each HTTP POST request.

HTTP Response Format

The following is an example of an event broker HTTP response to a management application's SEMP v1 command:

HTTP/1.1 200 OK
Content-Length: <length>
<SEMP reply>

Where:

<length> indicates the length (in bytes) of the SEMP v1 reply that follows the HTTP header

<SEMP reply> is the contents of the SEMP v1 reply that is returned by the event broker (see SEMP v1 Reply Format)

An HTTP response of "200 OK" is returned if the command was accepted by the event broker (even if it was not successfully executed). If there is an authentication failure, the following response is returned:

401 Unauthorized
Basic Realm="CLI"

If the SEMP reply indicates a failure with reasonCode="549" and reason="SEMP response buffer allocation failed", the requested response is large and the event broker cannot allocate enough internal resources to buffer it. Use SEMP v1 Paging to avoid excessively large responses that can result in this error.

SEMP Schema Version

SEMP uses an XML schema to identify all managed objects available in an event broker.

The SEMP command contains an optional SEMP v1 schema version string that specifies which SEMP schema is to be used in the validation of the command by the event broker.

When received by an event broker in a command, the SEMP schema version string is processed in the following manner,

  • If a version string is provided:
    • and matches a SEMP schema installed on the event broker, then the command is validated with the specified schema.
    • and does not match any installed SEMP schema, then the command is validated with the latest installed schema.
  • If a version string is not provided, the event broker validates the command using the latest installed schema.

As of PubSub+ software event broker version 8.7+ and PubSub+ appliance version 8.3+, it is recommended not to include a SEMP version string in commands, and only include one if a known deprecated behavior is needed from a particular SEMP schema.

SEMP Schema Version Support Policy

Legacy SEMP schema versions continue to be supported by new event broker releases for six years after the legacy SEMP schema version was introduced. To identify the minimum supported legacy SEMP schema version for a given event broker release, see PubSub+ Event Broker - Release Compatibility.

If a legacy SEMP request is sent with no version specified, the event broker uses its latest supported schema version to validate and process the request. This is Solace’s recommended approach. One potential limitation of this approach is that the request may stop working if the latest schema has a non-backwards compatible change. However, Solace expects such changes to be rare.

If a legacy SEMP request includes a schema version and the request is sent to an event broker that:

  • supports that schema version, the event broker validates and processes the request using the specified schema version.

  • does not support that schema version, the event broker attempts to use its latest supported schema version to validate and process the request.

SEMP v1 Command Format

For both SEMP v1 Request over HTTP and SEMP v1 Request Over Message Bus access methods, the format of SEMP v1 commands within a request is modeled after the Solace CLI. Each SEMP v1 command is the equivalent of a single Solace CLI command.

SEMP v1 commands are formatted in XML, following the schema in the semp-rpc-soltr.xsd file provided with the Solace PubSub+ software release bundle. White space (including line-end characters) is optional in the SEMP v1 command. The top‑level element is <rpc>, and the next-level element corresponds to the command being issued. Inside the <rpc> element are the keywords and parameters of the command.

Example:

<rpc>
    <show>
        <client>
            <name>*</name>
        </client>
    </show>
</rpc>

SEMP v1 does not provide a concept of command modes. All commands are issued at the top level of the command mode hierarchy. In particular, the enable and configure commands are not required or supported in SEMP v1.

If a known deprecated behavior is needed from a particular SEMP v1 schema, a SEMP v1 version string is specified inside the <rpc> element. For example, to specify schema version 10.2.1, use <rpc semp-version="soltr/10_2_1"> (for the appliance) or <rpc semp-version="soltr/10_2_1VMR"> (for the software broker).

SEMP v1 Reply Format

For both SEMP v1 Request over HTTP and SEMP v1 Request Over Message Bus access methods, the SEMP v1 interface replies indicate the success or failure of a SEMP v1 command, in addition to the reason code for any failure. SEMP v1 replies are formatted in XML, following the schema in the semp-rpc-reply-soltr.xsd file.

The following is an example of a successful reply to the command described in SEMP v1 Command Format (white space, including line-end characters, is optional in a SEMP v1 reply):

<rpc-reply semp-version="soltr/10_3_0">
  <rpc>
    <show>
      <client>
        <primary-virtual-router>
          <client>
            <client-address>192.168.1.180:58305</client-address>
            <name>s0001</name>
            <profile>default</profile>
            <num-subscriptions>1</num-subscriptions>
            <message-vpn>default</message-vpn>
            <description></description>
          </client>
        </primary-virtual-router>
        <internal-virtual-router>
          <client>
            <client-address>127.55.55.55:56244</client-address>
            <name>#client</name>
            <profile>#client-profile</profile>
            <num-subscriptions>2</num-subscriptions>
            <message-vpn>default</message-vpn>
            <description>Internal Message Bus</description>
          </client>
        </internal-virtual-router>
      </client>
    </show>
   </rpc>
<execute-result code="ok"/>
</rpc-reply>

As shown in the example above, a successfully parsed SEMP v1 command always generates <rpc-reply> and <execute-result> element tags. Additionally, in the case of SEMP v1 show commands, a number of element tags detailing the command name (without parameters) and output are also generated.

The execute-result code has either a value of "ok", or "fail". For a failure, the reason (represented by a string) and reason code (represented by an integer) are also provided.

Publishing an HTTP SEMP v1 Request with cURL

The following simple example shows a simple HTTP SEMP v1 request published to the event broker with cURL (http://curl.haxx.se/).

Using the Solace CLI, you can view global event broker stats with the show stats client User EXEC command. The following snippet shows the XML for the equivalent SEMP v1 request:

<rpc>
  <show>
    <stats>
      <client/>
    </stats>
  </show>
</rpc>

If this XML code is put in a file called request.xml, you can use cURL to send it to the HTTP listen port of the event broker management interface.

PubSub+appliance example:

curl -d @request.xml -u username:password http://192.168.128.12:80/SEMP

PubSub+ software event broker example:

curl -d @request.xml -u username:password http://192.168.128.12:8080/SEMP

The response provides the same client statistics that would be provided through the Solace CLI output, but these statistics that the SEMP v1 provides are provided formatted in XML (see SEMP v1 Reply Format).

Configuring SEMP v1 Over Message Bus Services

The SEMP v1 Request Over Message Bus service is configured on a per Message VPN basis.

To configure SEMP v1 Request Over Message Bus service on a Message VPN through the Solace CLI, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# semp-over-msgbus
solace(configure/message-vpn/semp-msgbus)#

The Solace CLI is now in the configuration mode for the SEMP v1 Request Over Message Bus service on the specified Message VPN.

The example below shows the hierarchical structure of the SEMP v1 Request Over Message Bus service command tree. This shows how you can enable or disable all client access to SEMP v1 Request Over Message Bus service for the Message VPN or limit client access to specific Admin and Show commands for the SEMP v1 Request Over Message Bus service.

SEMP v1 Over Message Bus Service Command Hierarchy

SEMP v1 over Message Bus:              Enabled/Disabled
    Admin commands:                    Enabled/Disabled
      Client commands:                 Enabled/Disabled
      Distributed Cache commands:      Enabled/Disabled
    Show commands:                     Enabled/Disabled
    Legacy Show Clear commands:        Enabled/Disabled

To enable or disable client access to SEMP v1 Request Over Message Bus service for the Message VPN, see Allowing SEMP v1 Over Message Bus Service.

When SEMP v1 Request Over Message Bus service is enabled, you can further control client access to the following commands for the SEMP v1 Request Over Message Bus service:

By default, SEMP v1 Request Over Message Bus service is enabled for a Message VPN, but access to each group of admin and show commands is disabled.

Enabling SEMP v1 Service for Management VPNs

To allow system-wide access to SEMP v1 service over Message Bus, you can enable SEMP v1 service for the Message VPN that is designated as the Management Message VPN (see Designating Management Message VPNs).

A single Message VPN can be designated as the Management Message VPN for an event broker. SEMP v1 requests published by a client application connected to the Management Message VPN may request system-level information, as well as information for any of the Message VPNs configured on the event broker. Clients connected to the Management Message VPN have permission to clear events (at client or Distributed Cache level) and delete messages in Distributed Caches across all Message VPNs.

Allowing SEMP v1 Over Message Bus Service

  • To allow clients to run SEMP v1 commands over the message bus for the given Message VPN, enter the following CONFIG command: 
    solace(configure/message-vpn/semp-msgbus)# no shutdown

    By default, SEMP v1 Request Over Message Bus service is enabled for a Message VPN.

  • To not allow clients to run SEMP v1 commands over the message bus for the given Message VPN, enter the following CONFIG command: 
    solace(configure/message-vpn/semp-msgbus)# shutdown

Allowing Access to Admin Commands

The Admin EXEC commands contain the Client EXEC Admin commands and the Distributed Cache Admin EXEC commands. To stop clients from running Admin EXEC commands over the message bus denies them access to both the Client EXEC Admin commands and the Distributed Cache Admin EXEC commands.

  • To allow clients to run Admin EXEC commands over the message bus for the given Message VPN, enter the following CONFIG command: 
    solace(configure/message-vpn/semp-msgbus)# no admin-cmds shutdown
  • To stop clients from running Admin EXEC commands over the message bus for the given Message VPN, enter the following CONFIG command: 
    solace(configure/message-vpn/semp-msgbus)# admin-cmds shutdown

    By default, Admin EXEC SEMP Request over Message Bus commands are not allowed for a Message VPN.

Allowing Access to Client Admin Commands

The Client EXEC Admin commands can be used to clear events.

  • To allow clients to run Client Admin EXEC commands over the message bus for the given Message VPN, enter the following CONFIG command: 
    solace(configure/message-vpn/semp-msgbus)# no admin-cmds client-cmds shutdown
  • To stop clients from running Client Admin EXEC commands over the message bus for the given Message VPN, enter the following CONFIG command: 
    solace(configure/message-vpn/semp-msgbus)# admin-cmds client-cmds shutdown

    By default, Client Admin EXEC SEMP Request over Message Bus commands are not allowed for a Message VPN.

Allowing Access to Distributed Cache Admin Commands

The Distributed Cache Admin EXEC commands can be used to clear Distributed Cache events and delete messages from the given Distributed Cache.

  • To allow clients to run Distributed Cache Admin EXEC commands over the message bus for the given Message VPN, enter the following CONFIG command: 
    solace(configure/message-vpn/semp-msgbus)# no admin-cmds distributed-cache-cmds shutdown
  • To stop clients from running Distributed Cache Admin EXEC commands over the message bus for the given Message VPN, enter the following CONFIG command: 
    solace(configure/message-vpn/semp-msgbus)# admin-cmds distributed-cache-cmds shutdown

    By default, Distributed Cache Admin EXEC SEMP Request over Message Bus commands are not allowed for a Message VPN.

Allowing Access to Show Commands

The show User EXEC commands include show commands for data and statistics scoped within the Message VPN that the client is connected to.

  • To allow clients to run show User EXEC commands over the message bus for the given Message VPN, enter the following CONFIG command: 
    solace(configure/message-vpn/semp-msgbus)# no show-cmds shutdown
  • To stop clients from running show User EXEC commands over the message bus for the given Message VPN, enter the following CONFIG command: 
    solace(configure/message-vpn/semp-msgbus)# show-cmds shutdown

    By default, show User EXEC Request over Message Bus commands are not allowed for a Message VPN.

Allowing Access to Legacy Show Clear Commands

By default, legacy SEMP v1 access (that is, SEMP v1 show and administration requests published to topic "#P2P/[router name]/#client/SEMP") is enabled on each Message VPN for backwards compatibility. However, as of event broker version 5.4, legacy SEMP v1 access is deprecated, and it is recommended that you publish SEMP show and administration requests published to the current topic "#SEMP/<router name>/<cmd-topic>" (see Publishing SEMP v1 Requests Over the Message Bus) and avoid enabling legacy SEMP access.

  • To allow clients to run legacy SEMP v1 commands on the event broker SEMP Request Over Message Bus service for the given Message VPN, enter the following CONFIG command: 
    solace(configure/message-vpn/semp-msgbus)# no legacy-show-clear-cmds shutdown
  • To stop clients from running legacy SEMP v1 commands on the event broker SEMP Request Over Message Bus service for the given Message VPN, enter the following VPN CONFIG command: 
    solace(configure/message-vpn/semp-msgbus)# legacy-show-clear-cmds shutdown

SEMP v1 Paging

If you are retrieving multiple objects (for example, Queues, Message VPNs, or Subscriptions) via SEMP v1, you must use SEMP paging (also called "sequenced get"), and the number of objects you request must never exceed 100. When using the SEMP v1 Request Over Message Bus service, you must further limit your object count to ensure your response fits within the maximum response size of 89,000 bytes, and when using SEMP v1 over HTTP, your response must fit within the maximum response size of 33,554,432 bytes.

If a SEMP v1 show command requires paging, it supports "sequenced get" and also provide a more-cookie to receive the full response through multiple smaller responses.

When a SEMP v1 request would result in an oversized response, the event broker responds with a failure with reasonCode="431" and reason="response too big" (or for SEMP over the message bus, the limit-error element contains "response too big: use sequenced get"). When this occurs, refer to the SEMP v1 schema file to create your send request with the "sequenced get" parameters. The sequenced get parameters consist of the count and num-elements XML attributes.

If paging is supported for a command, the event broker might include a more-cookie in the response. This more-cookie can be retrieved from the SEMP v1 response with the following XML XPath: //more-cookie. The more-cookie can be sent back to the event broker in another SEMP v1 request to receive the next portion of the response. This is repeated to retrieve all portions of the response from the event broker. The responses from "sequenced get" and more-cookie can be used individually or reassembled into a single SEMP v1 response. Both the more-cookie, individual SEMP v1 responses, and the entire response (when reassembled) adhere to the SEMP v1 response schema.

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.

If this behavior prevents your client from functioning, you can use the configure service semp legacy-timeout command to assist in keeping your system running while you update your clients to use paging. When enabled, it increases the amount of time available for the system to produce a response before paging is forced on a client. Note that this is only intended to be used to keep a system running for a short period of time while clients are updated to use paging.

When using show commands with a sort parameter (for example, show client * sorted-stats total-client-messages-sent), using a "sequenced get" will return the top elements (up to the specified number of elements), and a more-cookie will not be present (although more elements may be present).

<rpc>
  <show>
    <client-username>
      <name>*</name>
      <vpn-name>*</vpn-name>
      <count/>
      <num-elements>4</num-elements>
   </client-username>
  </show>
</rpc>
<rpc-reply semp-version="soltr/8_3_0">
  <rpc>
    <show>
      <client-username>
        <client-usernames>
          <client-username>
            <client-username>user1</client-username>
            <message-vpn>exampleVpn</message-vpn>
            <enabled>true</enabled>
            <num-clients>2</num-clients>
          </client-username>
          <client-username>
            <client-username>testUser</client-username>
            <message-vpn>exampleVpn</message-vpn>
            <enabled>false</enabled>
            <num-clients>0</num-clients>
          </client-username>
          <client-username>
            <client-username>testCacheUser</client-username>
            <message-vpn>exampleVpn</message-vpn>
            <enabled>true</enabled>
            <num-clients>1</num-clients>
          </client-username>
          <client-username>
            <client-username>devUser</client-username>
            <message-vpn>devVPn</message-vpn>
            <enabled>true</enabled>
            <num-clients>15</num-clients>
         </client-username>
        </client-usernames>
      </client-username>
    </show>
  </rpc>
  <more-cookie>
    <rpc>
      <show>
        <client-username>
          <name>*</name>
          <vpn-name>*</vpn-name>
          <following-username/>
          <vpn-id-index-param>5</vpn-id-index-param>
          <username-index-param>devUser</username-index-param>
          <count/>
          <num-elements>4</num-elements>
        </client-username>
      </show>
    </rpc>
  </more-cookie>
 <execute-result code="ok"/>
</rpc-reply>

Available SEMP v1 Over Message Bus Commands

The following commands can be executed over the message bus:

  • Show User EXEC commands—These commands enable applications to display configuration and statistical information only for the Message VPN that the client is connected to. For example, the show client * command will display client configuration and status information only for those clients within the Message VPN that the client application is connected to.

    A client application cannot display information for a Message VPN that it is not connected to, and it cannot display system-level information.

    The only exception to this limitation is if the client application is connected to the event broker’s Management Message VPN. In this case, it can successfully run all show commands (whether they concern System-level information or Message VPN-scoped information).

    If a client executes system-level show commands, such as show hardware or show version, and it is not connected to the Management Message VPN, a permission error "invalid request: not authorized to run this command" is returned.

    To view all of the possible show commands, enter the following User EXEC command:

    solace> show ?
  • Client Admin EXEC commands—These commands enable applications to clear and reset the given client’s event notification for a specified one-shot event. The following client admin EXEC command can be executed over the message bus:
    • admin client <name> message-vpn <vpn-name> [primary][backup] [static] clear-event <event-name>
  • Distributed Cache Admin EXEC commands—These commands enable applications to clear event notifications for the given Distributed Cache or delete messages from the given Distributed Cache. These commands also enable applications to start a single PubSub+ Cache Instance or all PubSub+ Cache Instances in a Cache Cluster that do not have Auto Start Mode enabled. The following distributed cache admin EXEC commands can be executed over the message bus:
    • admin distributed-cache <name> message-vpn <vpn-name> clear-event <event-name> [cache-cluster <cluster-name>] [cache-instance <instance-name>]
    • admin distributed-cache <name> message-vpn <vpn-name> delete-messages <topic> [cache-cluster <cluster-name>] [cache-instance <instance-name>]

For more information on the Solace CLI equivalent of these commands and details for the parameters, see Performing PubSub+ Cache Administrative Tasks.

Publishing SEMP v1 Requests Over the Message Bus

Client applications can use the Java, C, and .NET messaging APIs to make SEMP v1 requests over the message bus. Client applications must publish any SEMP v1 requests over the message bus to the following topic destination:

#SEMP/<router name>/<cmd-topic>

Where:

router name is the hostname of the event broker to send the request to.

cmd-topic is a command specific topic destination to publish the SEMP v1 request to. The following command topics can be used:

  • #SEMP/<router name>/SHOW—The command topic destination for show User EXEC commands, which display Message VPN-scoped information such as configuration data, statistics, and client information.

    For more information on the Solace CLI equivalent of this command, see Monitoring VPN Configurations and Stats.

  • #SEMP/<router name>/ADMIN/CLIENT—The command topic destination for Client Admin EXEC commands, which enable applications to clear and reset the given client’s event notification for a specified one-shot event.
  • #SEMP/<router name>/ADMIN/DISTRIBUTED-CACHE—The command topic destination for Distributed Cache Admin EXEC commands, which enable applications to clear event notifications for the given Distributed Cache or delete messages from the given Distributed Cache.

The following are examples of full command topics that SEMP v1 requests could be published to:

  • #SEMP/SolaceNewYork/SHOW
  • #SEMP/SolaceLondon2/ADMIN/CLIENT
  • #SEMP/SolaceNewJersey/ADMIN/DISTRIBUTED-CACHE

When developing a client application that can publish a SEMP v1 request and handle its response, each SEMP v1 request and each SEMP v1 response must fit within a single message. Multi-part messages are not supported.

The event broker allows one Message VPN to be designated as the Management Message VPN. Clients connected to this Management Message VPN may then request both system-level information as well as information pertaining to any of the Message VPNs configured on the event broker. Likewise, clients connected to the Management Message VPN may run administration commands for any Message VPN configured on the event broker. For more information, see Designating Management Message VPNs.

Related Samples

For a complete example of how to publish SEMP v1 requests over the message bus, a sample file is provided for the PubSub+ Messaging APIs for JCSMP, C, and .NET. There is a readme file at the top of the example directory that describes how to build and run the example code.

API Path to SEMP v1 Sample File
JCSMP

samples/src/com/solacesystems/jcsmp/samples/introsamples/SempGetOverMB.java

samples/src/com/solacesystems/jcsmp/samples/introsamples/SempHttpSetRequest.java

samples/src/com/solacesystems/jcsmp/samples/introsamples/SempPagingRequests.java

C ex/sempGetOverMb.c
CCSMP (.NET)

ex/SolClientSamples/SempGetOverMB.cs

ex/SolClientSamples/SempHttpSetRequest.cs

ex/SolClientSamples/SempPagingRequests.cs

Publishing SEMP v1 Requests with the JCSMP

To publish a SEMP v1 request with the JCSMP, perform the following steps:

  1. Create a Session and Producer.
  2. Create a message topic to publish the SEMP v1 request to: 
    Topic topic = JCSMPFactory.onlyInstance().createTopic(String topicString);

    The topic must be constructed as follows: "#SEMP/<router name>/<cmd-topic>"

  3. Create a request message: 
    BytesXMLMessage requestMsg = _producer.createBytesXMLMessage();
  4. Set the SEMP v1 request string as the binary attachment: 
    requestMsg.writeAttachment(byte[] byteInputBuffer);
  5. Create a requestor on the session, and send the request.

    The SEMP v1 response is returned as a BytesXMLMessage:

    Requestor requestor = _session.createRequestor();
BytesXMLMessage replyMsg = requestor.request(
requestMsg,
long timeoutMillis,
topic
);
  6. Obtain the binary attachment data from the reply message. The binary attachment contains the SEMP v1 reply for the command topic in the publish request. 
    replyMsg.readAttachmentBytes(byte[] bytes);

For API specifications and more details, see the PubSub+ Messaging API JCSMP reference.

Publishing SEMP v1 Requests with the C API

To publish a SEMP v1 request with the C API, perform the following steps:

  1. Create a Session.
  2. Allocate a message for requests. 
    if ( ( rc = solClient_msg_alloc ( &msg_p ) ) != SOLCLIENT_OK ) {
        common_handleError ( rc, "solClient_msg_alloc()" );
        return;
    }
  3. Create a SEMP v1 request message and specify the topic destination to publish the SEMP v1 request to. The topic destination must be constructed as follows: 
    solClient_destination_t topic
topic.dest = topicString;
topic.destType = SOLCLIENT_TOPIC_DESTINATION;
  4. Create a request message and set its Destination to the topic created in Step 3: 
    solClient_msg_setDestination ( msg_p, &topic );

    Set the SEMP v1 request string as the binary attachment:

    solClient_msg_setBinaryAttachmentPtr
( msg_p, byteInputBuffer, strlen( byteInputBuffer ));
  5. Call the solClient_session_sendRequest method: 
    solClient_opaqueMsg_pt replyMsg_p;
solClient_returnCode rc;
rc = solClient_session_sendRequest
( session_p, msg_p, &replyMsg_p );

    The SEMP v1 response is returned in the Reply Message.

  6. Obtain the binary attachment data from the Reply Message: 
    solClient_msg_getBinaryAttachment
(reply Msg_p, byteOutputBuffer, sizeof ( byteOutput Buffer );

    The binary attachment contains the SEMP v1 response for the command topic in the publish request.

For API specifications and more details, see the PubSub+ Messaging API C reference.

Publishing SEMP v1 Requests with the .NET API

To publish a SEMP v1 request with the .Net Messaging API, perform the following steps:

  1. Create a Session.
  2. Create the message topic. 
    "#SEMP/<router name>/<cmd-topic>"
ITopic topic =
ContextFactory.Instance.CreateTopic(topicString);
  3. Create a request message and set its Destination to the topic in Step 2: 
    IMessage requestMsg = ContextFactory.Instance.CreateMessage();
requestMsg.Destination = topic;
  4. Set the SEMP v1 request string as the binary attachment: 
    requestMsg.BinaryAttachment = byteInputBuffer;
  5. Call the SendRequest() method on Session. 
    IMessage replyMsg;
ReturnCode rc = session.SendRequest(requestMsg, out replyMsg, timeout);

    The SEMP v1 response is returned in replyMsg.

  6. Obtain the binary attachment data from the reply message: 
    replyMsg.BinaryAttachment

    The binary attachment contains the SEMP v1 reply for the command topic in the publish request.

For API specifications and more details, see the PubSub+ Messaging API .NET reference.

Receiving SEMP v1 Replies Over the Message Bus

Client applications can handle SEMP v1 replies over the message bus as they would other Direct messages—through a message receive interface (XMLMessageConsumer for the JCSMP), a message receive callback (C API), or a delegate (.NET API) that are set when the Session is created.

For information on how to receive messages with the PubSub+ Messaging APIs, see Receiving Direct Messages.

Generating Java SEMP v1 APIs

If you want to integrate SEMP v1 into your Java applications, you can use tools from the Java Architecture for XML Binding (JAXB) project to generate a Java SEMP v1 API. Using the third-party tool, you can create a set of Java classes from the SEMP v1 XML schema that can be imported into Java applications. With those Java classes, your Java applications can create object-oriented SEMP v1 request commands and decompose SEMP v1 replies into Java objects.

To convert the SEMP v1 XML request and reply schemas to Java class files, the JAXB binding files for SEMP v1 requests (semp-rpc-soltr-jaxb-bindings.xsd) and SEMP v1 replies (semp-rpc-reply-soltr-jaxb-bindings.xsd) that are provided with the software release bundle must be specified when running the JAXB generation tool.

To generate a Java SEMP v1 API, perform the following:

  1. Go to https://jaxb.java.net/ and download the latest release of JAXB.
  2. Follow the instructions provided by the JAXB project to properly install the toolset.
  3. Convert the SEMP v1 command schema.

    In the JAXB conversion tool , enter the following command:

    xjc -p SolaceSempRequest semp-rpc-soltr.xsd -b semp-rpc-soltr-jaxb-bindings.xsd

    The tool will create a SolaceSempRequestdirectory in the current directory. The new directory contains Java class files that represent the SEMP v1 request commands.

  4. Convert the SEMP v1 reply schema.

    In the JAXB conversion tool, enter the following command:

    xjc -p SolaceSempReply semp-rpc-reply-soltr.xsd -b semp-rpc-reply-soltr-reply-jaxb-bindings.xsd

    The tool will create a SolaceSempReply directory in the current directory. The new directory will contain Java class files that represent the SEMP v1 reply commands.

For more information on how to import and use JAXB-generated APIs, go to https://jaxb.java.net.