Configuring VPN Bridges

To create a Message VPN bridge, enter the following Global CONFIG command on the local event broker: 

solace(configure)# create bridge <bridge-name> message-vpn <vpn-name> [auto | primary | backup]

To edit properties for an existing Message VPN bridge, enter the following Global CONFIG command: 

solace(configure)# bridge <bridge-name> message-vpn <vpn-name> [auto | primary | backup]

Where:

<bridge-name> is the name of the Message VPN bridge. A name can contain up to 150 characters, composed of alphanumeric characters and the following punctuation character set: ~`!@$%|^()_+={}:,.#-;[]. The bridge's name must be unique within its Message VPN if the auto option is selected. However, if either primary or backup is selected, the same bridge name can be used for both a primary and backup bridge within the same Message VPN.

<vpn-name>is the full name of an existing local Message VPN. Partial names, or wildcard characters used to represent one or more characters of the name, are not supported.

auto associates the bridge automatically at time of creation with either the primary or backup virtual router, depending on the current setting of the redundancy active-standby-role. This is the default and recommended value.

primary associates the bridge at time of creation to the primary virtual router. This value should only be used if an active/active redundancy model is being used.

backupassociates the bridge at time of creation to the backup virtual router. This value should only be used if an active/active redundancy model is being used.

The no version of this command, no bridge <bridge-name> message-vpn <vpn-name>, deletes the specified bridge from the Message VPN. To delete a Message VPN, the bridge must be disabled through the shutdown Bridge CONFIG command, and no other configured objects can refer to it.

When configuring a bi-directional Message VPN bridge in a Message VPN where replication is also enabled, avoid subscribing both ends of that bridge to the same topics if those topics are also configured for replication. This restriction also applies to overlapping wildcard subscriptions. In other words, it applies to any subscription which would match a message received over the bridge. If such topics exist, then following a replication failover, they can cause messages originally received over the bridge to be sent back over that bridge to the originating event broker. This results in message duplication in the originating broker.

Prior to Solace PubSub+ software event broker version 8.9 and appliance version 8.5, the auto value was not available, and primary was the default virtual router for the bridge upon creation.

Message VPN Bridges Configuration Tasks

Entering the bridge message-vpn command moves the CLI to a level that allows you to configure the given bridge. At this level, you can perform the following configuration tasks for the given Message VPN bridge:

Configuring Max Bridge TTLs

Message VPN bridges use a bridge time-to-live (TTL) value for messages that are delivered from one Message VPN to another remote Message VPN. The bridge TTL value specifies the maximum number of hops that can occur before the message is discarded. This TTL value prevents bridges from creating a network message loop between different Message VPNs and multiple event brokers, whereby copies of the same message get delivered multiple times to the same clients.

When a Message VPN bridge delivers a message to the another Message VPN, the bridge TTL value messages is set to whichever is lower—the current bridge TTL value for the message, or the maximum TTL value that is set for the Message VPN bridge.

To configure the number of hops for the given Message VPN bridge, enter the following CONFIG command:

solace(configure/bridge)# max-ttl <value>

Where:

<value> is the integer value specifying the maximum number of hops that can occur before the message is discarded. The valid range is 1 to 255. The default value is 8.

The no version of this command (no max-ttl) resets the maximum TTL value for the bridge back to the default.

The maximum TTL value for a bridge only applies to the number of "hops" a message may take over Message VPN bridges. It is not related to the time-based publisher or endpoint set message TTLs, which determine how long a message may persist after it is published or spooled to a queue without being consumed or acknowledged.

Configuring Max Remote Retry Attempts

To configure the maximum number of retries to attempt a remote Message VPN bridge connection to an event broker before the next alternate source for the bridge is attempted (for example, if the retry count is set to 1, a total of two connection attempts is made for each alternate source—the initial attempt plus one retry), enter the following CONFIG command:

solace(configure/bridge)# remote retry count <count>

Where:

<count> is an integer from 0 to 255 for the number of times to retry a connection to an individual router name. The default value is 0.

The no version of this command (no remote retry count) resets the number of retries attempted for an event broker connection back to the default value.

Configuring Remote Authentication

Authentication can be set up on a Message VPN bridge to provide secure connections between Message VPNs. Basic and client certificate authentication modes are available. Note that a client username must be configured before a remote Message VPN bridge can be connected through the no shutdown command, see Configuring Client Certificate Authentication.

In an authentication scenario, a remote Message VPN acts as the server which authenticates a local Message VPN bridge.

To configure the authentication scheme to be used for Message VPN bridges, enter the following CONFIG command:

solace(configure/bridge)# remote authentication
solace(configure/bridge/remote/authentication)# auth-scheme {basic | client‑certificate}

Where:

basic specifies that basic username and password authentication should be used for bridge connections

client-certificate specifies that client certificate authentication should be used for bridge connections

After selecting an authentication scheme, you can then configure specific parameters for the chosen basic or client certificate authentication scheme.

Configuring Basic Authentication

To enter the basic authentication configuration mode, enter the following CONFIG command:

solace(configure/bridge/remote/authentication)# basic
solace(...re/bridge/remote/authentication/basic)#

The CLI is now at the configuration mode for configuring basic authentication for the given Message VPN bridge. From here, you can set the client username that the bridge will use to log in to the remote Message VPN.

Configuring Client Usernames for Authentication

To establish a bridge connection to a remote Message VPN, a local bridge client is automatically created, and this client requires a client username to login and authenticate itself. Before configuring a new client username for a remote Message VPN bridge, the bridge connection must be shutdown.

Also note that, by default, clients cannot create remote Message VPN bridge connections—you must configure permission settings in the client profile that is assigned to the client username. Permission to create bridge connections can be enabled with the allow-bridge-connections command. Refer to Configuring Client Profiles for details.

To configure the client username that the bridge will use to log in to the remote Message VPN, enter the following CONFIG command:

solace(...re/bridge/remote/authentication/basic)# client-username <name> [password <password>]

Where:

<name> is the full username of the client username account (partial names or wildcard characters used to represent one or more characters of the name are not supported). The client username may contain up to 189 characters.

<password> is the password assigned to the client username account, which will be required for authentication if set. The password may contain up to 128 characters.

The no version of this command (no client-username) deletes the client username and its associated password, if any, from the bridge.

If the TCP parameters used by the local bridge client are not suitable for your network, do the following:

Configuring Client Certificate Authentication

To configure client certificate authentication for the given Message VPN bridge, enter the following CONFIG command:

solace(configure/bridge/remote/authentication)# client-certificate
solace(...ote/authentication/client-certificate)#

The CLI is now in a configuration mode that allows you to set the certificate that the bridge will use for authentication on the remote Message VPN bridge.

Configuring Certificate Files to Use

To configure the certificate that the bridge will present to the remote event broker, enter the following CONFIG command:

solace(...ote/authentication/client-certificate)# certificate-file <filename>

Where:

<filename> is the file name of the certificate to be used for authentication. The certificate must be located in the event broker's /usr/sw/jail/certs directory.

The certificate file can only be configured while the bridge is shutdown.

After the certificate has been associated with the bridge, the certificate file can be removed from the /usr/sw/jail/certs directory.

For authentication to succeed, the common name provided in the certificate file must exist as a client username on the remote Message VPN. The client username must be enabled, and the client profile that is used by that client username must have allow-bridge-connections enabled. The provided client certificate must also be enabled on the remote Message VPN and adhere to the specified client certificate authentication settings on the remote Message VPN.

The no version of this command, no certificate file, disassociates the certificate file from the current Message VPN bridge.

If client certificate authentication is in use but no certificate file is specified, then the server certificate of the event broker will be used as the client certificate for bridge authentication sessions.

Configuring Remote Deliver-To-One Priorities

Through the use of Solace Messaging APIs, client applications can use the Deliver-To-One (DTO) feature to send a Direct message to a single client, rather than all, even though there may be a number of clients with appropriate subscriptions that are capable of receiving the message. For information, see Deliver-To-One.

A bridge to a remote Message VPN is assigned a DTO subscriber priority, which determines the priority that its topic subscriptions have for receiving published Deliver-To-One messages from that remote Message VPN. Note that the bridge must be first shut down before configuring the DTO priority for the topic subscriptions.

To configure the DTO priority for the bridge’s topic subscriptions, enter the following Bridge VPN CONFIG commands:

solace(configure/bridge)# remote
solace(configure/bridge/remote)# deliver-to-one priority <dto-priority>

Where:

<dto-priority> is the DTO priority for the bridge’s topic subscriptions. Valid values are P1, P2, P3, P4 (where P1 is the highest priority, and P4 is the lowest priority), or DA for Delivery Always. The default value is P1.

The no version of this command, no priority, resets the DTO priority for the topic subscriptions back to default:

solace(configure/bridge/remote/deliver-to-one)# no priority

Configuring Remote Message VPNs

The Message VPN the bridge connects to is the Remote Message VPN. You can specify the Remote Message VPN's location using either of the following methods:

  • By using the virtual router name: This is the virtual router to which the bridge belongs. The virtual router name can only be used with a bi-directional bridge and only at one end of the bridge.

    When a bi-directional bridge is configured, one end can be configured using the virtual router name. If a bi-directional bridge is configured at one end using a router-name, and at the other end using the connect-via IP address, the bridge using the IP address connects first, then the bridge using the virtual router name discovers the existing connection to the remote event broker.

  • By using connect-via IP address: This specifies the event broker's primary IP address and an optional physical interface. In the case of a bi-directional bridge, the end that is using the connect-via method establishes the connection first.

    This method can also be used with a loopback Message VPN bridge, that is, a bridge that connects a local Message VPN and a Remote Message VPN that are on the same event broker. When you create a loopback bridge, use an IP address of 127.0.0.1 and do not specify a physical interface.

A Message VPN bridge must first be disabled through the shutdown before configuring which Remote Message VPN it should connect to. To configure the Message VPN that the bridge is to connect to, enter the following commands:

solace(configure/bridge)# remote
solace(configure/bridge/remote)# create message-vpn <vpn-name> {router <virtual-router-name> | connect-via <addr> [interface <phys-intf>]}

To edit the properties for an existing Remote Message VPN that the bridge connects to, do not include create in the command.

Where:

<vpn-name> is the Message VPN name to connect the bridge to (partial names or wildcard characters used to represent one or more characters of the name are not supported).

<virtual-router-name> is the name of the remote virtual router where the given Message VPN is located. This name must begin with v:, as that indicates a virtual router. Router names can contain up to 66 characters, composed of alphanumeric characters 0 to 9, a to z, A to Z, underscore '_', dot '.', and hyphen '-'. Note that '_', '.' and '-' cannot be used at the beginning or end of a router name. Virtual router names must be unique among all configured event brokers.

<addr> is the IP address or FQDN of the remote broker where the given Message VPN is located in the form IP_address[:port] or FQDN[:port]. DNS Name Lookup is supported. For connecting to an appliance, the <addr> parameter must resolve to the remote appliance's msg-backbone VRF. IPv4 addresses must be specified in the dotted decimal notation form, nnn.nnn.nnn.nnn. In SolOS version 9.12.0 and later, IPv6 formatted strings (RFC 5952) are supported, however, these addresses must be enclosed in square brackets. The port is specified as a decimal value from 0 to 65535. For example, a correctly formatted IPv4 address is: 192.168.100.1:55555. The same address in IPv6 fromat is [::ffff:c0a8:6401]:55555.

If no port is specified, port 55555 will be used. For plain-text, non-compressed data traffic, the default port is 55555; for plain-text, compressed data traffic, the default port is 55003; for TLS/SSL encrypted data traffic, regardless of whether the data traffic is compressed or non-compressed, the default port is 55443. You should note that once a Remote Message VPN is created, you can't change the port unless you delete the Remote Message VPN, or create another Remote Message VPN that uses an alternative port.

If you want to establish a bridge link to a Remote Message VPN that is also on the local event broker (that is, a loopback Message VPN bridge), use an IP address of 127.0.0.1 and don't specify a physical interface.

<phys-intf> is an optional ASCII string specifying the physical Ethernet interface port or LAG of the local event broker that the bridge connection will originate from. Valid values are eth<port> (for example, eth1); <cartridge>/<slot>/<port> (for example, 1/1/8); <cartridge>/<slot>/lag<N> (for example, 1/1/lag1). If you are using multiple interfaces, and only one of them applies, you must assign the applicable interface. If no physical interface is specified, an appropriate physical interface is automatically assigned.

The no version of this command, no message-vpn <vpn-name>, removes the given Remote Message VPN bridge connection.

  • Bridges are configured against a specific virtual router. Therefore, if a local physical interface is specified, it must contain an IP interface configured against the same virtual router as the bridge.
  • This command can be repeated up to four times on the bridge so that up to four distinct Remote Message VPNs can be configured. This creates an internal host list, which provides potential redundant hosts for the bridge. Each combination of <vpn-name> and either <virtual‑router-name> or <addr> <phys-intf> must be unique, and a mixture of the two possible combinations is not allowed. When adding a new host source entry, it is appended to the end of the existing host list. Its position can be modified through the connect-order Remote Message VPN Bridge CONFIG command (see Configuring Connect Orders).

    However, when using Guaranteed Messaging over a Message VPN bridge:

    • Solace recommends that redundant host sources for the bridge not be used to provide redundancy. While redundant host sources allow a Message VPN bridge to successfully reroute in the event of a failure, Guaranteed messages and acknowledgments could be lost and stale messages delivered during the failover and failback operations.
    • Solace recommends instead that the Message VPN bridge connection be made to the virtual address of the event broker, so that the bridge can automatically be rerouted to the standby event broker if the primary event broker fails.
  • When more than one Remote Message VPN is provided, the connection is attempted in order for each enabled Remote Message VPN, from the start of the Host List to the end. Each address may be retried several times depending on the configured retry count.

Remote Message VPN Bridges Configuration Tasks

The CLI is now at the configuration mode for the remote Message VPN bridge connection to the event broker, which allows you to perform the following configuration tasks:

Configuring Connect Orders

The bridge connection to the remote Message VPN must first be disabled through the shutdownRemote Message VPN Bridge CONFIG command before configuring the order in which the bridge attempts to connect to redundant remote Message VPN hosts.

To configure the order in which the bridge attempts to connect to redundant remote Message VPN hosts, enter the following CONFIG command:

solace(configure/bridge/remote/message-vpn)# connect-order <number>

You can assign different remote Message VPNs to the same connect order, since their relative priority is not defined by this number.

Where:

<number> is an integer from 1 to 4, where 1 provides the highest connection attempt priority, and 4 provides the lowest. Different remote Message VPNs may be assigned the same connect-order, in which case their relative priority is not defined. The default value is 4.

The no version of this command, no connect-order, resets the connect order priority for the remote Message VPN to the default value.

Configuring Message Spool Queues

If you want to transfer Guaranteed messages over the Message VPN bridge, you must specify an existing durable queue (with an exclusive access type) on the remote event broker to which a Guaranteed Messaging flow connection will be established to. When a flow is established to a durable queue, Guaranteed messages (that is, messages with persistent and non-persistent delivery modes) can be sent over the bridge link without any changes to their delivery modes. Topic subscriptions must be added to the queue to attract messages published to specific topics of interest.

The bridge connection to the remote Message VPN must first be disabled through the shutdown Remote Message VPN Bridge CONFIG command before you can specify the durable message queue to use for the bridge connection. To specify an existing durable queue (with an exclusive access type) on the remote Message VPN to establish a Guaranteed Messaging Flow connection to, enter the following CONFIG command:

solace(configure/bridge/remote/message-vpn)# message-spool queue <name>

Where:

<name> is the name of an existing, durable queue. This queue must have an exclusive access type.

The no version of this command (no message-spool queue) removes the durable message queue from the remote Message VPN bridge. If the bridge is currently established then the binding is removed from the event broker.

The remote Message VPN bridge attempts to bind to the durable queue once the link has been established to the event broker (it binds to the queue immediately if the link is already established). If the bind fails, an event log is generated that includes the reason for the failure.

Configuring Message Spool Window Sizes

Configuring an excessively large message spool window size on low-latency VPN bridge links can negatively impact network performance. Contact Solace for technical support before changing this parameter, as they can assist you in choosing the appropriate value for your network conditions.

The message spool window size dictates how many outstanding Guaranteed messages may be sent over the remote Message VPN bridge connection before an acknowledgment to the remote queue must be returned.

You must first disable the remote Message VPN bridge connection to the event broker before configuring the message spool window size for use by Guaranteed Messaging. The client username to be used for the remote Message VPN bridge connection must first be configured before enabling access through the no shutdown Remote Message VPN Bridge CONFIG command. Refer to Enabling Data Compression.

By default, clients cannot create remote Message VPN bridge connections—permission must first be configured in the client profile that is assigned to the client username. Permission to create bridge connections can be enabled the allow-bridge-connections Client Profile CONFIG command. Refer to Configuring Client Profiles for details.

To configure the message spool window size for use by Guaranteed Messaging when the bridge connects to the event broker using the specified remote Message VPN, enter the following CONFIG command:

solace(configure/bridge/remote/message-vpn)# message-spool window-size <number>

Where:

<number> is the integer value representing the new message spool window size to the event broker. The valid range is 1 to 65535, and the default value is 255 if this parameter is not provided. To maintain performance, if you increase the window size above 255 you'll need to set the min-msg-burst for the G-1 queue in the client profile used by the bridge to the same value. For information on configuring min-msg-burst refer to Configuring Egress Queue Minimum Message Bursts.

The no version of this command, no message-spool window-size, resets the message spool window size value back to default.

solace(configure/bridge/remote/message-spool)# no window-size

Enabling Access to Remote VPN Bridge Connections

  • To enable access to remote Message VPN bridge connections on a per bridge basis, enter the following Remote Message VPN Bridge CONFIG command: 
    solace(configure/bridge/remote/message-vpn)# no shutdown
  • To disable access to remote Message VPN bridge connections on a per bridge basis, enter the following CONFIG command:
    solace(configure/bridge/remote/message-vpn)# shutdown

Enabling Data Compression

By default, bridge data traffic is uncompressed, but you can choose to compress it by following these steps:

  1. Disable the bridge connection to the remote Message VPN.
  2. You need to ensure you've configured the correct port on the remote Message VPN's event broker for your application. If you only want to compress data traffic, you should use the compression port (port 55003 is the default). If you plan to compress and TLS/SSL encrypt the data traffic, use the SSL port (port 55443 is the default). For instructions on how to configure data encryption refer to Enabling TLS/SSL Encryption for Bridge Connections.
  3. Use this command to enable data compression:
    solace(configure/bridge/remote/message-vpn)# compressed-data

    The no version, no compressed-data,specifies that no data compression be used.

Enabling TLS/SSL Encryption for Bridge Connections

Plain text over TCP is the default encoding for bridge connections; however, you can choose to use TLS/ SSL encryption over TCP.

To configure TLS/SSL encryption you'll need to follow these steps:

  1. An SSL server certificate, and the matching trusted CA, must be configured on the remote Message VPN's event broker.
  2. You need to ensure that the port you've configured on the remote Message VPN's event broker is the SSL port; otherwise, the connection won't be established. The default SSL port is 55443, and Configuring Remote Message VPNs has more configuration information.
  3. Use this command to enable SSL:
    solace(configure/bridge/remote/message-vpn)# ssl

    The no version, no ssl, specifies that TLS/SSL encryption should not be used.

Configuring Client Profiles for Uni-Directional Bridges

By default, when a uni-directional bridge establishes a connection to the given remote Message VPN, the TCP parameters from a non-editable, default client profile, #client-profile, are used (this default client profile has a TCP max window size of 2 MB). However, if the TCP parameters used by the #client‑profile client profile are not suitable for your network, can use those from another client profile on the local Message VPN.

When establishing a bi-directional bridge, the client profile associated with the client username is fully configurable (that is, no default client profile like that used for a uni-directional bridge is used).

To specify a client profile that will provide the TCP parameters to use for the uni‑directional bridge, enter the following CONFIG commands:

solace(configure/bridge/remote/message-vpn)# unidirectional
solace(...dge/remote/message-vpn/unidirectional)# client‑profile <name>

Where:

<name> is the name of a client profile that exists on the local Message VPN. A client profile name can contain up to 32 alphanumeric characters (case‑sensitive).

The no version of this command, no client-profile, removes the current client profile assignment, and reassigns the default client profile, #client-profile

If you make the bridge bi-directional (that is, if you later configure another bridge of the same name that uses the same Message VPNs but in the reverse order), the TCP parameters from another client profile associated with a client username specified by the opposite end of the bridge are used to transport messages in the opposite direction.

Configuring Remote Retry Delays

To configure the number of seconds that must pass before retrying a connection to a remote event broker, enter the following CONFIG command:

solace(configure/bridge)# remote retry delay <seconds>

Where:

<seconds> is an integer from 0 to 255 for the number of seconds to wait before retrying a connection to a remote event broker. The default value is 3.

The no version of this command, no remote retry delay, resets the number of seconds to wait back to the default value.

Configuring Remote Subscription Topics

To add a topic subscription to the Message VPN bridge used on the remote event broker, enter the following CONFIG command:

solace(configure/bridge)# remote subscription-topic <topic> [deliver-always]

Where:

<topic> is the name of the topic subscription to be added in the form a/b/c.

deliver-always configures the topic subscription as DA rather than with a configured remote DTO priority. A given topic may be DTO or DA, but not both.

The no version of this command, no remote subscription-topic <topic>, removes the specified topic subscription from the Message VPN bridge used on the remote event broker.

For Request-Reply messaging, it's necessary to add the return address as a topic subscription on the Message VPN Bridge for the reply message to be sent back to the Publisher publishing the request messages.

Configuring TLS/SSL

To enter the SSL configuration mode for the current Message VPN Bridge, enter the following CONFIG command:

solace(configure/bridge)# ssl

The CLI is now at the level to configure SSL connections on the current Message VPN Bridge. From here, you can configure the cipher suites that the bridge will use for negotiation with the event broker of the remote Message VPN as well as the common names that are trusted by the bridge that will be verified against the remote server certificate during the SSL handshake.

Configuring Cipher Suites

A list of cipher suites, in order of preference, can be specified to negotiate with the event broker of the remote Message VPN. By default, all supported cipher suites are used, ordered from the most secure to the least secure. An empty cipher suite list will prevent the bridge from initiating a connection.

For a full list of cipher suites supported by the Solace PubSub+ event brokers, see Supported Cipher Suites.

To configure which cipher suites should be use on the bridge connection, enter the following CONFIG command:

solace(configure/bridge/ssl)# cipher-suite {default | empty | name <suite-name> [{before | after} <suite-name>]}

Where:

default specifies that the default list of supported cipher suites, ordered from most secure to least secure, may be used.

empty removes all cipher suites from the list.

name <suite-name> adds the specified cipher suite to the list of suites to be used.

before <suite-name> specifies that the suite specified by the name parameter should be inserted into the list immediately before (that is, with a higher priority than) the suite specified by the before parameter.

after <suite-name> specifies that the suite specified by the name parameter should be inserted into the list immediately after (that is, with a lower priority than) the suite specified by the after parameter.

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

Enabling Server Name Validation

You can enable or disable the TLS authentication mechanism to verify the name used to connect to the remote broker. If enabled, 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 broker.

Server name validation is enabled by default and should remain enabled in all production scenarios.

To enable server name validation on the bridge connection, enter the following command:

solace(configure/message-vpn/bridging/ssl)# server-certificate-validation
solace(...ing/ssl/server-certificate-validation)# validate-server-name

To disable server name validation:

solace(...ing/ssl/server-certificate-validation)# no validate-server-name

Starting/Stopping Bridge Connections

The shutdown Bridge CONFIG command disconnects the bridge client from the remote Message VPN. No new connection is attempted to the remote Message VPN until the bridge is enabled again through the no shutdown Bridge CONFIG command.

  • To start a bridge connection, enter the following CONFIG command: 
    solace(configure/bridge)# no shutdown
  • To stop a bridge connection, enter the following CONFIG command: 
    solace(configure/bridge)# shutdown

By default, Message VPN bridges are not enabled.