Configuring Message VPNs

To create a Message VPN, enter the following CONFIG command:

solace(configure)# create message-vpn <vpn-name>

To edit the properties of an existing Message VPN, enter the following CONFIG command:

solace(configure)# message-vpn <vpn-name>

Where:

<vpn-name> is the name of the Message VPN to be created or edited. The Message VPN name must be unique among all created Message VPNs on the event broker. Message VPN names can contain any characters, except the asterisk (*) or question mark (?).

The no version of this command, no message-vpn <vpn-name>, deletes the specified Message VPN from the event broker (the Message VPN named default, however, cannot be deleted). Before deleting a Message VPN:

  • It must be disabled through the shutdown VPN CONFIG command.
  • No other configured objects can refer to it.
  • When a Message VPN is created, it is not automatically enabled. For information, see Stopping/Starting Message VPNs.
  • The maximum number of Message VPNs that can be configured depends on the type of Solace PubSub+ event broker used. For example, the number of Message VPNs you can provision on a software event broker differs from the number that you can provision on an appliance. Additionally, a Solace PubSub+ 3560 with high-performance NABs and ADBs may support even more Message VPNs.

You can perform the following tasks for a configured Message VPN:

Configuring Accepted Client Authentication Schemes

See Configuring Client Authentication for details on how to configure client authentication schemes for the given Message VPN.

Configuring Bridging Server Certification Validation

See Configuring Server Certificate Validation Settings for details on configuring the actions to take on validating server certificates for Message VPN bridges when using Transport Layer Security (TLS)/ Secure Sockets Layer (SSL) authentication.

Designating Management Message VPNs

System-level syslog events (as opposed to Message VPN scope events) are always published in a Message VPN that has been designated as the Management Message VPN for the event broker. A Solace PubSub+ event broker can only have one of its enabled Message VPNs configured as the Management Message VPN. (If no Management Message VPN is configured, then system-level syslog events are not published on the event broker.)

To designate a Message VPN as the Management Message VPN to use for publishing message bus system-level syslog requests and events, enter the following CONFIG command:

solace(configure)# management-message-vpn <vpn-name>

Where:

<vpn-name> is the name of the Message VPN to be designated as the Management Message VPN.

The no version of this command, no management-message-vpn, deletes the management configuration for the Message VPN.

  • Message VPN-level events (including client and subscription events) are always published to the message bus in the Message VPN on which the events occurred.
  • The Config-Sync facility does not automatically propagate this setting across replication bridges. Therefore, if you are using the event broker in a replicated site, you must manually designate the Management Message VPN on each mate event broker.

Enabling Logging Events on Management Message VPNs

To turn system-level publishing of syslog events to the message bus on or off on the Management Message VPN, enter the following Global CONFIG level command:

solace(configure)# logging event

The CLI moves to a Logging Event CONFIG level, from which you can do the following:

  • To enable system-level publishing of syslog events to the message bus on the Management Message VPN, enter the following CONFIG command: 

    solace(configure/logging/event)# publish-system

  • To disable system-level publishing of syslog events to the message bus on the Management Message VPN, enter the following CONFIG command: 

    solace(configure/logging/event)# no publish-system

  • To configure a custom identification tag as a prefix for system-level syslog events, enter the system-tag Logging Event CONFIG command: 

    solace(configure/logging/event)# system-tag <tag-string>

    Where:

    <tag-string> is the custom identification tag with no spaces, asterisks (*), question marks (?), or single (') or double (") quotes. It can contain up to 32 alphanumeric characters, and must be unique among all system-level identification tags. The default is empty, that is, no custom identification tag.

    The no version of this command, no system-tag, deletes the custom identification tag from system-level syslog events, and sets the tag string back to default.

Showing Management Message VPN Logging Events

To view the current configuration of system-level publishing of syslog events to the message bus on the Management Message VPN, enter the following User EXEC command. 

solace> show logging event

Configuring Maximum Connections

To configure the maximum number of clients that are permitted to simultaneously connect to a given Message VPN through all supported services, enter the following CONFIG command:

solace(configure/message-vpn)# max-connections <value>

Where:

<value> is the integer value specifying the maximum total number of client connections permitted for the Message VPN. This maximum value includes client connections for all supported services. The valid range is from 0 to the maximum total number of clients that can be supported by the type of Solace PubSub+ event broker used.

The no version of this command, no max-connections, resets the maximum number of client connections that are permitted to simultaneously connect with the given Message VPN back to the default value which is the maximum total number of client connections for all services that the event broker can support.

  • To view the maximum total number of client connections that the Solace PubSub+ event broker can support, enter the show service User EXEC command.
  • The maximum number of client connections can also be limited on a client profile-basis, see Configuring Max Connections Per Username.
  • If you are using the replication facility, and the type of Solace PubSub+ event brokers used at each replication site do not match, you must ensure that the combined maximum number of client connections for all Message VPNs at one replication site does not exceed the combined maximum number of client connections for all Message VPNs at its mate replication site. Consider, for example, a scenario where a Solace PubSub+ 3560 is used at replication Site A and a Solace PubSub+3530 that supports a maximum of 6,000 clients is used as its mate at replication Site B. If the Solace PubSub+ 3560 at Site A uses more than 6,000 client connections, it is possible that the Solace PubSub+ 3530 at Site B will be sent more configuration updates than it can handle. Therefore, when Config‑Sync is enabled for replication sites that used mismatched event brokers, the configured max-connections value for Replicated Message VPNs and the max-connections-per-client-username values for the client profiles used by each event broker at the replication sites must not exceed the maximum value for the event broker with the lowest range.

Configuring Maximum Subscriptions

You can configure a limit for the maximum number of unique local subscriptions (across both primary and backup VRIDs) that clients can add to a Message VPN.

This limit only applies to unique subscriptions. For example, two clients subscribing to the topic "a/b" will only count as one against this limit. Also note that this limit is not affected by remote subscriptions. Therefore, the total number of unique subscriptions could exceed the maximum permitted number of subscriptions if some of them are remote subscriptions, as shown in the following example:

solace1> show message-vpn default
Message VPN:                         default
Configuration Status:                Enabled
Local Status:                        Up
Total Local Unique Subscriptions:    6
Total Remote Unique Subscriptions:   5
Total Unique Subscriptions:          11
Maximum Subscriptions:               10

To configure the maximum number of local client subscriptions (across both primary and backup VRIDs) that can be added to the specified Message VPN, enter the following VPN CONFIG command:

solace(configure/message-vpn)# max-subscriptions <value>

Where:

<value> is the integer value specifying the maximum number of local client subscriptions. The valid range is 0 to 4294967295. The default value is 5000000.

The no version of this command, no max-subscriptions, resets the maximum number of local client subscriptions that can be added to the specified Message VPN back to the default value.

Configuring Message VPN Event Generation

To configure the conditions that cause Message VPN-related events be generated, and control whether some types of events get published onto the message bus, enter the following CONFIG command:

solace(configure/message-vpn)# event

The CLI is now at the Message VPN Event CONFIG level, from which you can use the CLI to configure the high and low thresholds at which events are generated for the given Message VPN, and enable the publishing of events to the message bus for Message VPNs. For more information, see Configuring Events and Thresholds.

Configuring Replication

By default, the use of the replication feature is not enabled for a Message VPN. To use the replication feature, a replication mate and interface must first be set at the system level, and then replication settings can be configured at the Message VPN level.

For information on how to configure Solace PubSub+ for replication, see Configuring Replication. For information on the Message VPN-specific replication parameters, see Configuring VPN-Level Replication Settings.

Configuring SEMP Over Message Bus

The legacy Solace Element Management Protocol (SEMP) Request Over Message Bus feature can be enabled for a Message VPN so that clients have access to a limited subset of the event broker management commands for that Message VPN.

For information on using the event broker SEMP Request Over Message Bus service, see Configuring SEMP v1 Over Message Bus Services.

Configuring Services

You can configure the following the following types of service for a Message VPN:

Configuring SMF Service

To configure the Solace Message Format (SMF) service settings for the given Message VPN, enter the following CONFIG command:

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

The CLI is now at a configuration mode for SMF service from which you can configure the following SMF service parameters for the given Message VPN:

Configuring Max SMF Connections

To configure the maximum number of SMF clients that can be simultaneously connected to the given Message VPN on this event broker, enter the following CONFIG command:

solace(configure/message-vpn/service/smf)# max-connections <value>

Where:

<value> is the maximum number of simultaneous SMF client connections permitted. The valid range depends on the type of Solace PubSub+ event broker (for example, Solace PubSub+ 3530 or 3560) used.

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

To view the maximum total number of Web client connections that the given event broker can support, enter the show service User EXEC command.

Enabling Plain Text Over SMF Service

  • To enable plain-text over SMF service for the Message VPN, enter the following CONFIG command: 

    solace(configure/message-vpn/service/smf)# plain-text
solace(...re/message-vpn/service/smf/plaint-text)# no shutdown

    By default, plain-text over SMF service is enabled for a Message VPN.

  • To disable plain-text over SMF service for the Message VPN, enter the following CONFIG command: 

    solace(configure/message-vpn/service/smf)# plain-text
solace(...re/message-vpn/service/smf/plain-text)# shutdown

Enabling TLS/SSL Over SMF Service

  • To enable TLS/SSL over SMF service for the Message VPN, enter the following CONFIG command: 

    solace(configure/message-vpn/service/smf)# ssl
solace(configure/message-vpn/service/smf/ssl)# no shutdown

    By default, TLS/SSL over SMF service is enabled for a Message VPN.

  • To disable TLS/SSL over SMF service for the Message VPN, enter the following command: 

    solace(configure/message-vpn/service/smf)# ssl
solace(configure/message-vpn/service/smf/ssl)# shutdown

Configuring MQTT Service

To configure the Message Queuing Telemetry Transport (MQTT) service settings for the given Message VPN, enter the following CONFIG commands:

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

The CLI is now at a configuration mode at which you can configure MQTT service parameters. For information, see Managing the MQTT Service.

Configuring AMQP Service

To configure the Advanced Message Queuing Protocol (AMQP) service settings for the given Message VPN, enter the following CONFIG commands:

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

The CLI is now at a configuration mode at which you can configure AMQP service parameters. For more information, see Managing AMQP Service on VPNs.

Configuring REST Service

To configure the REST service settings for the given Message VPN, enter the following CONFIG command:

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

The CLI is now at a configuration mode for REST service for the given Message VPN, from which you can configure REST service parameters. For information, see Managing REST Service.

Configuring Web Transport Service

You can configure the following Web transport service parameters for a given Message VPN:

Configuring Max Web Client Connections

To configure the maximum number of Web clients that can be simultaneously connected to the given Message VPN, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service
solace(configure/message-vpn/service)# web-transport
solace(configure/message-vpn/service/web-transport)# max-connections <value>

Where:

<value> is the maximum number of simultaneous Web client connections permitted. The valid range depends on the type of Solace PubSub+ event broker used.

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

To view the maximum total number of Web client connections that the given event broker can support, enter the show service User EXEC command.

Enabling Plain Text Over Web Transport Service

  • To enable plain-text over Web transport service for the Message VPN, enter the following CONFIG commands: 
    solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service
solace(configure/message-vpn/service)# web-transport
solace(...ure/message-vpn/service/web-transport)# plain-text
solace(...-vpn/service/web-transport/plain-text)# no shutdown

    By default, plain-text over Web transport service is enabled for a Message VPN.

  • To disable plain-text over SMF service for the Message VPN, enter the following commands: 
    solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service
solace(configure/message-vpn/service)# web-transport
solace(...ure/message-vpn/service/web-transport# plain-text
solace(...-vpn/service/web-transport/plain-text)# shutdown

Enabling SSL Over Web Transport Service

  • To enable TLS/SSL over Web service for the Message VPN, enter the following CONFIG commands: 

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

    By default, TLS/SSL over SMF service is enabled for a Message VPN.

  • To disable TLS/SSL over SMF service for the Message VPN, enter the following commands: 

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

Configuring When to Request a Client Certificate from a Web Client

By default, PubSub+ event brokers request client certificates from web clients connecting via a TLS port if client certificate authentication is enabled in a given Message VPN. Because many popular web browsers handle the request for a client certificate poorly, this can result in clients running in web browsers being unable to connect over the WebSockets secure (WSS) protocol. If you have clients connecting from a web browser using WSS and other clients in the same Message VPN that need to authenticate using client certificates, you may want to prevent the broker from requesting a client certificate from incoming web clients.

To configure when the broker requests a client certificate from incoming Web clients connecting via a TLS port, enter the following CONFIG commands:

solace(configure)# message-vpn <vpn-name>
solace(configure/message-vpn)# service
solace(configure/message-vpn/service)# web-transport
solace(...ure/message-vpn/service/web-transport)# authentication
solace(.../service/web-transport/authentication)# client-certificate
solace(...ort/authentication/client-certificate)# request-client-certificate {always | never | when-enabled-in-message-vpn}

Where:

always configures the broker to always request a client certificate regardless of whether client certificate authentication is enabled in the Message VPN. For more information, see Enabling/Disabling Client Certificate Authentication For Clients .

never configures the broker to never request a client certificate regardless of whether client certificate authentication is enabled in the Message VPN. This setting is useful if you don't want the broker to request a client certificate from your WebSocket secure clients, but you still want to use client certificate authentication for other types of clients (such as bridges).

when-enabled-in-message-vpn configures the broker to request a client certificate only if client certificate authentication is enabled in the Message VPN. This is the default setting.

The no version of command, no request-client-certificate, resets the value to the default.

Configuring Message VPN Overrides

If you are using certificate revocation checking to authenticate clients attempting to connect to a Solace PubSub+ appliance, then you can set overrides for specific Message VPNs. To configure certificate revocation checking, see Configuring Certificate Authorities.

To configure the Message VPN overrides, enter the following commands:

solace(configure)# message-vpn <name>
solace(configure/message-vpn)# authentication user-class client
solace(...message-vpn/authentication/user-class)# client-certificate
solace(...ication/user-class/client-certificate)# revocation-check-mode [allow-all | allow-unknown | allow-valid]

Where:

allow-all (default)—Ignore client certificate revocation check results. The revocation checks are still done—all clients attempting to authenticate using certificates are revocation checked—and the results are ignored.

allow-unknown—Authenticate clients even if the revocation status of their certificates cannot be determined. Note that there are a number of possible conditions that may lead to the revocation status of a certificate to be unknown, see Certificate Revocation Checking.

allow-valid—Authenticate clients if the revocation checks return an explicit positive response. Only clients that present certificates that return a valid response to the revocation check will be authenticated.

Revocation checks are ignored if the default allow-all is not changed; even if all revocation check parameters are correctly configured. The default allow-all mode must be changed to successfully enable revocation checks.

Enabling Subscription Export

By default, the export policy in a Message VPN is set not to export subscriptions to other Solace PubSub+ event brokers in the network. For messages to be received from other event brokers, the subscription export policy in Message VPNs must be set to export subscriptions. This causes subscriptions added locally to the Message VPN to be exported to other physical event brokers in the network.

To enable the export of subscriptions in a Message VPN to other event brokers in the network, on a per-Message VPN basis, enter the following CONFIG command:

solace(configure/message-vpn)# export-policy export-subscriptions

The no version of this command, no export-subscriptions, disables export of subscriptions in the Message VPN to other event brokers in the network.

Set the subscription export policy for a given Message VPN the same for all event brokers in the network.

Configuring Message VPN Aliasing

You can configure a Message VPN to be an alias of another Message VPN. The intent of this is to help you to collapse multiple Message VPNs into a single Message VPN without needing to change your existing application code (or at least not requiring all application instances to change at the same time).

Message VPN Aliasing is a Controlled Availability (CA) feature and should only be used under the supervision of Solace support.

When a Message VPN is configured as an alias of another Message VPN, for example, Message VPN blue is configured as an alias of Message VPN red, the following rules apply:

  • Message VPN red has no effect on blue while blue is enabled.
  • When blue is disabled, and it is an alias of red:
    • all existing connections to blue are terminated.
    • all per-Message VPN ports of blue are closed.
    • all new client connections to blue are treated as if they were connected to red rather than blue, and obey all the configuration settings of red.
    • all new bridging and routing connections to blue are treated as if blue were shut down.
    • all statistics, events, and behaviors of connected clients occur within red rather than blue.

Message VPN Aliasing is supported only for SMF client connections.

Before setting a Message VPN to be an alias, you must ensure that the aliased Message VPN has all appropriate configuration added to it (client usernames, client profiles, authentication settings, bridges, etc.)

To configure a Message VPN to be an alias of another Message VPN, enter the following commands:

solace(configure)# message-vpn <name>
solace(configure/message-vpn)# alias <other-vpn-name>

Where:

<other-vpn-name> is the name of the other Message VPN that this Message VPN is an alias of.

Configuring a Forward Proxy

Depending on your deployment, you may require that communication between Solace event brokers and endpoint servers (such as external websites) goes through a forward proxy. This is often the case if the event broker sits behind a firewall and REST delivery point (RDP) egress traffic needs to connect to a proxy server to go outside the firewall.

In this scenario, you can create a forward proxy configuration object on the event broker to direct traffic to the proxy server before it is forwarded to the endpoint server.

To create a forward proxy for a Message VPN, enter the following commands:

solace(configure)# message-vpn <name>
solace(configure/message-vpn)# create proxy <proxy-name>

To enable a forward proxy once it has been configured, enter the following command:

solace(configure/message-vpn/proxy)# no shutdown

Where:

<proxy-name> specifies the name of the forward proxy configuration object. This name is used in the configuration of other broker objects (for example RDPs) to refer to the forward proxy.

Forward proxy configuration objects are only synchronized in high-availability (HA) deployments, and not disaster recover (DR) deployments as different sites may need different proxy configurations. The proxy reference (the reference in the RDP for example) is both HA and replication synchronized, so that once the appropriate proxies are set up on each site, each referencing object doesn’t need any special handling on replicated sites.

You can configure the following parameters for a forward proxy:

Configuring the Forward Proxy Authentication Scheme

To configure the authentication scheme that the event broker will use to establish a connection to the proxy server, enter the following commands:

solace(configure/message-vpn/proxy)# authentication
solace(configure/message-vpn/proxy/authentication)# auth-scheme {none | basic}

Where:

none specifies to login with no authentication. For more information, see None.

basic specifies to login with a username and password. For more information, see Basic Authentication.

None

If no authentication scheme is configured, the event broker will not use an authentication scheme when connecting to the proxy server. This may be useful for anonymous connections or when a proxy server does not require authentication.

Basic Authentication

If you configure a basic authentication scheme, the event broker authenticates to the proxy server with a username and password combination.

To configure settings for an basic authentication scheme, enter the following commands:

solace(configure/message-vpn/proxy)# authentication
solace(configure/message-vpn/proxy/authentication)# basic
solace(configure/message-vpn/proxy/authentication/basic)# username <value>
solace(configure/message-vpn/proxy/authentication/basic)# password <value>

Where:

username <value> is the client username to use for authentication to the proxy server.

password <value> is the password to use with the specified username.

Configuring the Forward Proxy IP Address or Hostname

To configure the IP address or hostname of the proxy server, enter the following commands:

solace(configure/message-vpn/proxy)# host <value>

Where:

<value> specifies the IP address or DNS name to which the event broker will connect. It can contain up to 253 characters.

The no version of this command, no host, removes any configured value.

Configuring the Forward Proxy Port

To configure the port to connect to on the proxy server, enter the following commands:

solace(configure/message-vpn/proxy)# port <value>

Where:

<value> specifies the port number. The valid range of values is 0 to 65535. The default is 0.

The no version of this command, no port, resets the value to the default.

Configuring the Forward Proxy Type

To configure the forward proxy type, enter the following commands:

solace(configure/message-vpn/proxy)# proxy-type {direct | http}

Where:

direct specifies a direct connection to the endpoint server, in other words no proxy is used. If you configure this proxy type, the only other configuration that has effect is whether the proxy is enabled or not. This is useful when one replication site might need a proxy and another might not, so for the second site you would set the proxy type to direct. This is the default.

http specifies that the connection from the event broker to the proxy server is HTTP. You can enable TLS/SSL for event broker objects using the forward proxy (for example RDPs) so that clients can exchange data with the event broker using TLS/SSL over single TCP connections instead of HTTP over TCP. For more information, see TLS / SSL Service Configuration.

The no version of this command, no proxy-type, resets the value to the default.

Stopping/Starting Message VPNs

Message VPNs are disabled by default (that is, not running) on Solace PubSub+ event brokers.

The shutdown VPN CONFIG command will disconnect all clients connected to the specified Message VPN, and any new connection requests to that Message VPN are rejected until it's enabled again through the no shutdown VPN CONFIG command.

  • To stop a given Message VPN, enter the following CONFIG command: 
    solace(configure/message-vpn)# shutdown
  • To start a given Message VPN, enter the following CONFIG command: 
    solace(configure/message-vpn)# no shutdown