Configuring VPN Bridges

To create a Message VPN bridge, enter the following Global CONFIG command on the local message 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 name of each bridge provisioned on a message broker must be unique. That is, a bridge name cannot match another bridge name in any of the Message VPNs on the message broker.

<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 attaches the bridge to the active message broker; the active message broker may be primary or backup. If a virtual router is not specified, auto option is selected by default.

primary specifies that this bridge is for the primary virtual router, and is the default if no parameter is entered. It is only active when both the primary virtual router is locally active, and the IP interface on the VRF is running (through the no shutdown VRF IP Interface command).

backup specifies that this bridge is for the backup virtual router. It is only active when both the backup virtual router is locally active, and the IP interface on the VRF is running (through the no shutdown VRF IP Interface command.

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.

Note:  With the release of Solace PubSub+ software message broker version 8.9 and Solace PubSub+ appliance version 8.5, the Message VPN Bridge selects the auto option by default, while for versions prior to Solace PubSub+ software message broker version 8.9 and appliance version 8.5, the primary message broker was selected by default. To avoid mixed version problems between message brokers with automatic bridges and message brokers without, you must explicitly configure any new bridges to either primary or backup message broker.

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 message 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.

Note:   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 a message 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 a message 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 into 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 Client Profile Configuration 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.

Tip  

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 message 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 message 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.

Note:   If client certificate authentication is in use but no certificate file is specified, then the server certificate of the message 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 Load Balancing Messages with 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 remote Message VPN is the Message VPN that the bridge is to connect to. The location of the remote Message VPN can be specified by either of the following methods:

  • virtual router name—This is the virtual router that the bridge belongs to. The virtual router name can only be used with a bi-directional bridge (it cannot be used with a uni-directional bridges); and it can only be used at one end of the bi‑directional bridge.

    When a bi-directional bridge is configured, one end of the bi‑directional bridge can be configured using the virtual router name. However, if a bi‑directional bridge is configured at one end using an IP address, and the other end using the connect-via IP address and TCP, the bridge using the IP address connects first, then the bridge that uses the virtual router name discovers the existing connection to the remote message broker.

  • connect-via IP address—This specifies the message broker’s primary IP address and an optional physical interface. When this connect-via method is used for a bi‑directional bridge, the end of the bridge using that method establishes 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 message broker. When creating a loopback bridge, you should 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 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>]}

Tip:  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 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. Router names must be unique among all configured message brokers..

<addr> is the IP address or DNS name of the router where the given Message VPN is located in the form “IP address[:port]” or “DNS name[:port]”, where the IP address is specified in the dotted decimal notation form nnn.nnn.nnn.nnn, and the optional port is specified as a decimal value from 0 to 65,535 (for example, 192.168.100.1:55555). If no port is specified, the default is 55555 for non‑compressed data, and 55003 for compressed data. If you want to establish a bridge link to a remote Message VPN that is also on the local message broker, use an IP address of 127.0.0.1 and do not specify a physical interface—this establishes a loopback Message VPN bridge. Note that for SSL connections, the port specified in this command must be set to the SSL port of the message broker of the remote Message VPN.

<phys-intf> is an optional ASCII string specifying the physical Ethernet interface port or LAG of the local message 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.

Note  
  • 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 message broker, so that the bridge can automatically be rerouted to the standby message broker if the primary message 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.
  • Bridging to another Message VPN on the same local message broker is only allowed in a host list of size 1.

Remote Message VPN Bridges Configuration Tasks

The CLI is now at the configuration mode for the remote Message VPN bridge connection to the message 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>

Tip:  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 message 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 message broker.

Note:   The remote Message VPN bridge attempts to bind to the durable queue once the link has been established to the message 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 emote Message VPN bridge connection to the message 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 Client Profile Configuration for details.

To configure the message spool window size for use by Guaranteed Messaging when the bridge connects to the message 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 message broker. The valid range is 1 to 65535. The default value is 255 if this parameter is not provided.

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

The bridge connection to the remote Message VPN must first be disabled before configuring the data connections to use compression.

To use data compression for the connections used for the remote Message VPN bridge, enter the following CONFIG command:

solace(configure/bridge/remote/message-vpn)# compressed-data

The no version of this command, no compressed-data, configures the connections used for the remote Message VPN bridge to not use data compression for the specified remote Message VPN bridge. No data compression is the default.

Note:   Ensure the port that you have configured on the remote message broker for the remote Message VPN is the compression port. Otherwise, the connection cannot be successfully established. The default compression port is 55003.

Enabling TLS/SSL Encryption for Bridge Connections

By default, plain text over TCP is used for bridge connections. However, you can choose to use Transport Layer Security (TLS)/ Secure Sockets Layer (SSL) encryption over TCP for bridge connections.

To use TLS/SSL encryption for Bridge connections, an SSL server certificate must be configured on the message broker of the remote Message VPN, and the matching trusted CA must be configured on the message broker of the remote Message VPN.

To configure a TLS/SS-encrypted bridge connection to the current remote Message VPN, enter the following CONFIG command:

solace(configure/bridge/remote/message-vpn)# ssl

The no version of this command, no ssl, specifies that TLS/SSL encryption should not be used on the bridge connection to the current remote Message VPN.

Note:  Ensure the port that you have configured on the remote message broker for the remote Message VPN is the SSL port. Otherwise, the connection cannot be successfully established. The default SSL port is 55443. Refer to Configuring Remote Message VPNs for more information.

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.

Note:  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

Note:   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 message 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 message 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 message 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 message broker.

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 message 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 message 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+ message 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.

Configuring Lists of Trusted Common Names

The Message VPN Bridge uses a list of trusted common names to determine which security certificates it will accept based on their common names. By default, the list of trusted common names is empty, meaning that the bridge will not trust any common names.

To configure a list of trusted common names for the Message VPN Bridge, enter the following CONFIG command:

solace(configure/bridge/ssl)# trusted-common-name {empty | name <common-name>}

Where:

empty removes all previously specified common names from the list.

name <common-name> specifies the name of a certificate to add to the list of trusted common names.

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

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

Note:  By default, Message VPN bridges are not enabled.