Managing REST Delivery Points

A REST delivery point (RDP) is a provisioned object on a Message VPN that facilitates message delivery to REST consumers. An RDP is associated with a client profile on the Message VPN that provides it with some configuration parameters. The RDP can be bound to message queues to deliver messages from those queues to REST consumers. The RDP maintains a list of REST consumers, which are identified by their remote connection information.

You can perform the following configuration tasks for RDPs:

Configuring REST Delivery Points

  • To create an RDP for the given Message VPN, enter the following CONFIG commands:

    solace(configure)# message-vpn <vpn-name>
    solace(configure/message-vpn)# rest
    solace(configure/message-vpn/rest)# create rest-delivery-point <name>

  • To edit the properties of an existing RDP, enter the following CONFIG commands:

    solace(configure)# message-vpn <vpn-name>
    solace(configure/message-vpn)# rest
    solace(configure/message-vpn/rest)# rest-delivery-point <name>

Where:

<name> is the name of the RDP. RDP names can be up to 100 characters and must be unique within the given Message VPN.

The no version of this command, no rest-delivery-point, deletes the specified RDP and all of its associated configuration.

Note:  You can create a maximum of 200 RDPs in total across all Message VPNs on the message broker.

Entering the rest-delivery-point REST VPN CONFIG command moves the CLI to an RDP configuration mode from which you can perform the following tasks:

Associating Client Profiles with REST Delivery Points

When an RDP is associated with an existing client profile, the RDP inherits that client profile’s TCP parameters and queue properties (max-depth and min-msg-burst). The TCP parameters inherited from the client profile will be used for all REST consumers on the delivery point.

To associate a client-profile with the given RDP, enter the following CONFIG command:

solace(.../message-vpn/rest/rest-delivery-point)# client-profile <name>

Where:

<name> is the name of a client-profile that already exists in the local Message VPN. By default, if no client profile is associated with an RDP, it will use the client profile named default for the current Message VPN.

The no version of this command, no client-profile, removes the client profile association from the RDP and assigns the default client profile for the current Message VPN.

Managing REST Delivery Point Queue Bindings

An RDP must be bound to one or more durable queues to attract messages from the queues and deliver them to REST consumers.

  • To bind the given RDP to a queue, enter the following CONFIG command:

    solace(.../message-vpn/rest/rest-delivery-point)# create queue-binding <queue-name>

  • To edit the properties of an existing queue binding, enter the following CONFIG command:

    solace(.../message-vpn/rest/rest-delivery-point)# queue-binding <queue‑name>

Where:

<queue-name> is the name of a queue in the given Message VPN to bind to the current RDP. Queue names can contain up to 200 characters (the only invalid characters are '<>*?&;).

The no version of this command, no queue-binding, deletes the specified queue binding for the current RDP. However, it does not delete the queue.

Note  
  • You can specify a binding to a queue that does not exist, but before the RDP can be brought into service, the referenced queue must be created. That is, a queue must exist with the same name as the queue binding in the same Message VPN as the RDP. The RDP must also have permission to consume messages from the queue—to achieve this, the queue’s owner must be set as the RDP username or the queue’s permissions for non-owner clients must be set to at least consume level access. For more information on configuring queues, refer to Configuring Queues.
  • The maximum number of queue bindings that can be created is the same as the maximum number of queues supported by a message broker.

The queue-binding REST VPN CONFIG command moves the CLI to the REST delivery point queue binding level:

solace(...est/rest-delivery-point/queue-binding)#

From this level, you can configure a POST request target for the given queue binding.

Configuring POST Request Targets

The POST request target that is associated with a queue binding is used in HTTP POST requests that are sent to REST consumers and identifies the target resource for message delivery on the remote REST consumer. Message delivery from a queue to a REST consumer cannot occur until a POST request target has been configured for the queue binding. For more information about request targets, see RFC 7230 §5.3.

To configure a POST request target for a queue binding, enter the following CONFIG command:

solace(...est/rest-delivery-point/queue-binding)# post-request-target <post-request-target>

Where:

<post-request-target> is a string containing the POST request target to associate with the current queue binding.

The no version of this command, no post-request-target, removes the POST request target from the current queue binding.

Note:  If the Message VPN containing the RDP is configured to act as a Microgateway, the POST request target is ignored.

Replacing the Authority Value in Outbound URIs

When a Message VPN is configured to act as a Microgateway, the message broker propagates HTTP requests in absolute form and retrieves the request-target's authority from the REST consumer's remote host and port configuration. You can optionally disable this functionality, and configure the message broker to use the authority configured in the original request.

To configure the message broker to use the authority value in the original request, enter the following CONFIG commands:

solace(...est/rest-delivery-point/queue-binding)# gateway
solace(...-delivery-point/queue-binding/gateway)# no replace-target-authority

To configure the message broker to replace the authority with the value configured for the REST consumer, enter the following CONFIG commands:

solace(...est/rest-delivery-point/queue-binding)# gateway
solace(...-delivery-point/queue-binding/gateway)# replace-target-authority

Note  Replacing the authority value in outbound URIs is available only when the corresponding Message VPN is configured to act as a Microgateway.

Configuring REST Consumers

A REST consumer is a virtual representation of a client or endpoint. An RDP maintains a list of REST consumers that messages can be delivered to. You can create a maximum of 600 REST consumers in total across all RDPs and Message VPNs on a message broker.

  • To create REST consumer within the current RDP, enter the following CONFIG command:

    solace(.../message-vpn/rest/rest-delivery-point)# create rest-consumer <name>

  • To edit an existing REST consumer, enter the following CONFIG command:

    solace(.../message-vpn/rest/rest-delivery-point)# rest-consumer <name>

Where:

<name> is the name of the specified REST consumer. The REST consumer name can contain up to 32 characters.

The no version of this command, no rest-consumer <name>, deletes the specified REST consumer and all of its configuration.

Entering the rest-consumer REST VPN CONFIG command moves the CLI to a configuration mode for REST consumers, from which you can perform the following tasks:

Configuring Remote Connection Info for REST Consumers

To configure remote connection information for the given REST consumer, enter the following REST VPN CONFIG command:

solace(...est/rest-delivery-point/rest-consumer)# remote

The CLI enters the Message VPN remote REST consumer level, from which you can configure the following remote connection properties for the current REST consumer:

Note:  Remote connection parameters for a REST consumer can only be configured while the REST consumer is shut down.

Host

To configure or reset either the IP address or DNS Name that the message broker will connect to so that it can deliver messages for the given REST consumer, enter the following CONFIG command:

solace(...t-delivery-point/rest-consumer/remote)# host <dest-ip-addr-or-host>

Where:

<dest-ip-addr-or-host> is the IP address or DNS name to which the message broker will connect to deliver messages for the current REST consumer, and it can contain up to 253 characters.

On PubSub+ software message brokers you can specify only an IPv4 address or DNS name.

On PubSub+ appliances, in addition to an IPv4 address or DNS name, you can specify an IPv6 address if the appliance's message-backbone is configured with an IPv6 global unicast or unique local address. For more information, refer to Configuring Appliance IP Interfaces. If you specify a DNS name and both an IPv4 and IPv6 address is returned during the lookup, the appliance chooses the IP address based on the preferred version configured for the Message VPN. For more information, refer to Configuring the Preferred IP Address Version for DNS Lookups.

The no version of this command, no host, resets the host setting to its default value (empty). If a REST consumer is enabled but has no host value configured, it will be in an operational Down state until a valid host value is set.

Note:  The host value can only be configured while the REST consumer is shutdown.

Port

To configure a port to be used with the host of the current REST consumer, enter the following CONFIG command:

solace(...t-delivery-point/rest-consumer/remote)# port <port>

Where:

<port> is the desired port number. Acceptable values are numerals from 1 to 65535.

The no version of this command, no port, resets the port value to a default value. Default values are 8080 for plain-text connections and 8443 for SSL connections.

SSL

To enable or disable SSL connections for the current REST consumer, enter the following CONFIG command:

solace(...t-delivery-point/rest-consumer/remote)# ssl

The no version of this command, no ssl, disables SSL connections for the current REST consumer.

Outgoing Connection Count

To set the total number of concurrent TCP connections initiated by the message broker that are open to the given REST consumer, enter the following CONFIG command:

solace(...t-delivery-point/rest-consumer/remote)# outgoing-connection-count <count>

Where:

<count> is the total number of outgoing connections (and thus HTTP POST operations) to this REST consumer that the appliance may initiate. Valid values are between 1 and 50 (inclusive).

The no version of this command, no outgoing-connection-count, resets the outgoing connection count parameter to the default value of 3.

Maximum POST Wait Time

There is a maximum amount of time that the message broker will wait for a POST response from the REST consumer.

If a POST operation has been outstanding for more than the configured maximum wait time, the TCP connection is reset. If the POST is for a non-persistent message, the message is discarded. If the POST is for a persistent message, message delivery is re-attempted through another available outgoing connection for the RDP, up to the max delivery count on the queue. If the max delivery count is exceeded, and the message is eligible for the Dead Message Queue (DMQ), then the message is moved to the DMQ, otherwise it is discarded.

To set the max POST wait time, enter the following CONFIG command:

solace(...t-delivery-point/rest-consumer/remote)# max‑post-wait-time <seconds>

Where:

<seconds> is the amount of time in seconds to wait for a response from an outstanding POST operation. The valid range is from 1 to 300.

The no version of this command, no max-post-wait-time, resets the maximum POST wait time parameter to the default value of 30.

Retry

To configure the retry delay (that is, the amount of time that should pass before a connection attempt is retried) enter the following CONFIG command:

solace(...t-delivery-point/rest-consumer/remote)# retry delay <seconds>

Where:

<seconds> is the amount of time (in seconds) that must pass before a connection attempt is retried. The valid range is from 1 to 300.

The no version of this command, no delay, resets the retry delay to the default value of 3.

Note:  If the Message VPN containing the RDP is configured to act as a Microgateway, the retry delay is ignored.

Configuring a Specific IP Interface for REST Consumers

By default, a message broker automatically chooses the IP interface through which outgoing connections from a REST consumer are made.

However, if your environment requires a fixed IP interface, it is also possible to configure a specific interface for the REST consumer. When a specific IP interface is configured, the source IP address specified in all outgoing packets will be the same for all connections associated with the REST consumer. A fixed IP interface may be required, for example, if a firewall is used between a client application and the message broker. In this case, the firewall must be configured to permit the message broker’s source IP address through, so an automatically-selected IP interface can be problematic.

Note:  If a local IP interface for a REST consumer is configured, that configuration will be propagated if the Config-Sync and/or Replication facilities are used. Therefore, you must either ensure that the specified interface is available on all Message VPNs that will be synchronized and/or replicated, or you should use the default behavior where the message brokers automatically select an IP interface.

To configure a specific local IP interface to use for all outgoing connections associated with the given REST consumer, enter the following CONFIG command:

solace(...est/rest-delivery-point/rest-consumer)# local
solace(...st-delivery-point/rest-consumer/local)# interface <phys-intf>

Where:

<phys-intf> is an ASCII string specifying the physical Ethernet interface port or LAG of the local appliance to use for all outgoing connections associated with the given REST consumer. Valid values are eth<port> (for example, eth1); chassis/lag1; <cartridge>/<slot>/<port> (for example, 1/1/8); <cartridge>/<slot>/lag<N> (for example, 1/1/lag1). Only a single LAG numbered 1 is supported.

The no version of this command, no interface, removes any configured local IP interface and resumes the default behavior where the message broker automatically chooses the IP interface through which the REST consumer is reachable.

Note:  A local IP interface for a REST consumer may be changed while the consumer is operationally up, but the new IP interface will only be used for new consumer connections—existing consumer connections will be unaffected.

Configuring REST Consumer Authentication Schemes

To configure authentication settings that the given REST consumer will use to establish a connection to the REST host, enter the following CONFIG command:

solace(...est/rest-delivery-point/rest-consumer)# authentication

The CLI enters a REST consumer authentication level, from which you can configure one of the following authentication schemes to be used for authenticating the REST consumer when it attempts to log in to the REST host:

The no version of the auth-scheme comman, no auth-scheme, resets the authentication scheme setting to its default value of none.

None

If no authentication scheme for a REST consumer is configured, the REST consumer will not use an authentication scheme. In this case, no authentication will be provided to the REST consumer. This may be useful for anonymous connections or when a REST consumer does not require authentication.

HTTP Basic Authentication

Using the HTTP basic authentication scheme, REST consumers can authenticate with a username and password combination carried over HTTP. Credentials can either be transmitted using plain-text or encrypted with SSL.

To configure an http-basic authentication scheme, enter the following CONFIG commands:

solace(...ry-point/rest-consumer/authentication)# http‑basic
solace(...st-consumer/authentication/http-basic)# username <name> [password <password>]

Where:

<name> is the client username to use for authentication with the REST host.

<password> is the optional password to be used with the specified username.

The no version of the username command, no username, removes any configured REST consumer authentication username and associated password.

Client Certificate Authentication

When using client certificate authentication, a REST consumer provides a certificate file to validate its identity. Client certificate authentication is only available to connections that use TLS/SSL.

To configure a client certificate authentication scheme, enter the following CONFIG commands:

solace(...ry-point/rest-consumer/authentication)# client-certificate
solace(...mer/authentication/client-certificate)# certificate-file <filename>

Where:

<filename> is the filename of the certificate file. The certificate file must be located in the certs folder of the message broker.

The no version of this command, no certificate-file, removes the certificate association for the current REST consumer.

Note  
  • The REST consumer certificate file can be changed at any time, but if the REST consumer is connected using client certificate authentication, changing the certificate will cause an interruption in service.
  • If no certificate is specified for a REST consumer using a client certificate authentication scheme, then the server certificate of the message broker is used instead.

Configuring REST Consumer TLS/SSL Parameters

To configure TLS/SSL parameters for the current REST consumer, enter the following CONFIG command:

solace(...est/rest-delivery-point/rest-consumer)# ssl

The CLI enters the REST consumer SSL configuration level, from which you may configure the following parameters:

Cipher Suite

You can configure the list of cipher suites that are used to encrypt connections from the message broker to a host. By default, all cipher suites are included in the list, ordered from most to least secure.

To use the default list of cipher suites, enter the following CONFIG command:

solace(...rest-delivery-point/rest-consumer/ssl)# cipher‑suite default

To modify the cipher suite list, do the following:

  • To empty the cipher suite list, enter the following REST VPN CONFIG command:

    solace(...rest-delivery-point/rest-consumer/ssl)# cipher‑suite empty

  • To add a cipher suite to the list, enter the following REST VPN CONFIG command:

    solace(...rest-delivery-point/rest-consumer/ssl)# cipher‑suite name <suite-name>

  • To add a cipher suite at a specific point in the list, use the following REST VPN CONFIG command:

    solace(...rest-delivery-point/rest-consumer/ssl)# cipher‑suite name <suite-name> [before|after <existing‑suite‑name>]

Where:

<suite-name> is a string identifying the cipher suite to be added to the list. If no ‘before’ or ‘after’ keyword is specified, the cipher suite is added at the end of the list.

before specifies that the cipher suite should be added before the cipher suite indicated by <existing-suite-name>.

after specifies that the cipher suite should be added after the cipher suite indicated by <existing-suite-name>.

<existing-suite-name> is the name of a cipher suite that is already on the list. The cipher suite being entered will be positioned before or after the existing suite name, depending on whether the before or after keyword was specified.

The no version of this command, cipher-suite name <suite-name>, removes the specified cipher suite from the configured list.

Note:  The cipher suite list can only be configured while the REST consumer is shutdown.

Trusted Common Name

A REST consumer uses a list of trusted common names to determine which remote security certificates it accepts based on their common names. By default, the list of trusted common names is empty, meaning that the REST consumer does not trust any common names.

To add a common name to the list of trusted common names used, enter the following CONFIG command:

solace(...rest-delivery-point/rest-consumer/ssl)# trusted‑common-name name {empty | name <common-name>}

Where:

empty removes all trusted common names from the list

<common-name> is a trusted common name of a remote certificate

The no version of this command, no trusted-common-name name <common-name>, removes the given trusted common name from the list.

Note:  For information on configuring CA certificates, refer to Managing Server Certificates.

Enabling REST Consumers

  • To enable the given REST consumer, enter the following CONFIG command:

    solace(...est/rest-delivery-point/rest-consumer)# no shutdown

  • To disable the given REST consumer, enter the following CONFIG command:

    solace(...est/rest-delivery-point/rest-consumer)# shutdown

    When a REST consumer is disabled, no connections can be initiated and no messages can be delivered to it.

Enabling REST Delivery Points

  • To enable the given RDP, enter the following CONFIG command:

    solace(.../message-vpn/rest/rest-delivery-point)# no shutdown

  • To disable the given RDP, enter the following CONFIG command:

    solace(.../message-vpn/rest/rest-delivery-point)# shutdown

    When disabled, no connections will be initiated and the RDP will not deliver messages to any of the contained REST consumers.