Managing REST Service

REST service can be configured on a per-Message VPN level for incoming and outgoing connections.

Configuring Incoming Connections

You can perform the following configuration tasks for incoming REST client connections to the given Message VPN:

Setting the Max Incoming Connections

To set the maximum number of incoming REST clients that can simultaneously connect to the given Message VPN, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service rest
solace(configure/message-vpn/service/rest)# incoming
solace(...ure/message-vpn/service/rest/incoming)# max-connections <value>

Where:

<value> is the maximum number of simultaneous incoming REST client connections to the given Message VPN that will be permitted. The valid range is from 0 to the maximum total number of REST clients that can be supported by the type of Solace PubSub+ event broker that the clients connect to.

The no version of this command, no max-connections, resets the value to the maximum limit supported by the event broker.

:  This parameter can be set to a value that is higher than the maximum number of simultaneous connections permitted by the event broker, but the connection limit for the event broker will be still be enforced.

Setting Listen Ports

You must configure a TCP port number for REST clients to use when connecting to the given Message VPN. Separate ports can be configured for plain text REST clients and SSL REST clients.

To set a listen port for REST connections, enter the following CONFIG command:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service rest
solace(configure/message-vpn/service/rest)# incoming
solace(...ure/message-vpn/service/rest/incoming)# listen-port <port> [ssl]

Where:

<port> is the port number from 1 to 65535. This port must not be used for any other service.

[ssl] specifies that the port is for TLS/SSL encrypted connections.

The no version of this command, no listen-port, resets the listen port to an unconfigured state.

The listen port can only be configured while the service using the port is shutdown. If the service is currently running, an error will occur.

Enabling REST Plain Text Service

To enable plain-text REST service for the given Message VPN, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service rest
solace(configure/message-vpn/service/rest)# incoming
solace(...ure/message-vpn/service/rest/incoming)# no plain-text shutdown

:  Before enabling plain-text service, you must configure the TCP port to be used (refer to Setting Listen Ports).

To disable plain-text REST service for the given Message VPN, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service rest
solace(configure/message-vpn/service/rest)# incoming
solace(...ure/message-vpn/service/rest/incoming)# plain-text shutdown

Enabling REST SSL Service

To enable SSL REST service for the given Message VPN, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service rest
solace(configure/message-vpn/service/rest)# incoming
solace(...ure/message-vpn/service/rest/incoming)# no ssl shutdown

:  Before enabling SSL service, you must configure the TCP port to be used (Setting Listen Ports).

To disable SSL REST service for the given Message VPN, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service rest
solace(configure/message-vpn/service/rest)# incoming
solace(...ure/message-vpn/service/rest/incoming)# ssl shutdown

Configuring Outgoing Connections

You can perform the following configuration tasks for outgoing REST client consumer connections from the given Message VPN:

Setting the Max Outgoing Connections

To set the maximum number of simultaneous REST consumer connections that the given Message VPN can establish, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service rest
solace(configure/message-vpn/service/rest)# outgoing
solace(...ure/message-vpn/service/rest/outgoing)# max-connections <value>

Where:

<value> is the maximum number of REST consumer connections that the current Message VPN can establish. The valid range is from 0 to the maximum total number of REST consumers that can be supported by the type of event broker that the clients connect to.

The no version of this command, no max-connections, resets this parameter to the default value of 6000.

Configuring SSL Cert Validation Settings for Outgoing Connections

For outgoing REST connections that use TLS/SSL encryption, you can perform the following configuration tasks:

Enforcing the Use of Trusted Common Names

A REST consumer may specify a list of trusted common names that it expects to be returned in the server certificate from the remote REST consumer. If you want REST consumers to only operate if a list of trusted common names has been configured, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# rest ssl server-certificate-validation
solace(...est/ssl/server-certificate-validation)# enforce-trusted-common-name

The no version of this command, no enforce-trusted-common-name, instructs the event broker not to enforce the use of trusted common names.

When validate-server-name is enabled, the enforce-trusted-common-name parameter is ignored.

Setting the Maximum Certificate Chain Depth

The max-certificate-chain-depth parameter determines the maximum permitted depth for the certificate chain. The depth of a certificate chain is defined as the number of signing CA certificates that are present in the certificate chain back to a trusted self-signed root CA certificate.

To set the max certificate chain depth, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# rest ssl server-certificate-validation
solace(...est/ssl/server-certificate-validation)# max-certificate-chain-depth <max-depth>

Where:

<max-depth> is the maximum permitted depth of the certificate chain.

The no version of this command, no max-certificate-chain-depth, resets this parameter to the default value of 3.

Enabling Validation of Certificate Dates

To enable the validation of "not before" and "not after" dates in the server certificate, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# rest ssl server-certificate-validation
solace(...est/ssl/server-certificate-validation)# validate-certificate-date

This parameter is enabled by default.

To disable the validation of the "not before" and "not after" dates in the server certificate, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# rest ssl server-certificate-validation
solace(...est/ssl/server-certificate-validation)# no validate-certificate-date

If this parameter is disabled, a certificate will be accepted even if it is not valid according to the "not before" or "not after" dates present in the certificate.

Enabling Sever Name Validation

You can enable or disable the TLS authentication mechanism to verify the requested hostname. If enabled, the Server Name Indication (SNI) extension is sent on outgoing TLS connections and the server name used for that connection is verified against the server names in the Subject Alternative Name (SAN) extension in the certificate returned from the remote server.

To enable the validation of server names, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# rest ssl server-certificate-validation
solace(...est/ssl/server-certificate-validation)# validate-server-name

This parameter is disabled for existing VPNs on brokers that have been upgraded from versions prior to 9.6; otherwise it is enabled by default.

To disable server name validation, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# rest ssl server-certificate-validation
solace(...est/ssl/server-certificate-validation)# no validate-server-name

When validate-server-name is enabled, the enforce-trusted-common-name parameter is ignored (the broker behaves as if enforce-trusted-common-name is false regardless of its actual value).