Configuring a DMR Cluster

A cluster is a provisioned object on an event broker that contains global DMR configuration parameters. There can be only one cluster for each node. Parameters configured at the cluster level apply to all links in the cluster, unless you override each setting by providing equivalent cluster link-level configuration.

To create a cluster, enter the following commands:

solace(configure)# routing
solace(configure/routing)# dynamic-message-routing
solace(...igure/routing/dynamic-message-routing)# create cluster <cluster-name>

To configure an existing cluster, enter the following command:

solace(...igure/routing/dynamic-message-routing)# cluster <cluster-name>

To enable the cluster, enter the following command:

solace(...uting/dynamic-message-routing/cluster)# no shutdown

Where:

<cluster-name> is the name of the cluster you want this node to belong to.

The configuration tasks that you can perform for an existing cluster include:

Configuring Authentication on a Cluster

When you configure cluster-level authentication, each setting applies for all links in the cluster. If you want to provide per-link authentication, refer to Configuring Authentication on the Link.

Configuring Basic Authentication

Basic authentication is the default client authentication scheme used by PubSub+ event brokers. This authentication scheme allows cluster links to connect to a remote node and authenticate with that node using a password.

Basic authentication is compatible with both plain-text and encrypted connections. For more information about configuring encrypted connections, see Enabling TLS/SSL Encryption.

To configure basic authentication for all links in the cluster, enter the following commands:

solace(...igure/routing/dynamic-message-routing)# cluster <cluster-name>
solace(...uting/dynamic-message-routing/cluster)# authentication
solace(...essage-routing/cluster/authentication)# basic

Configuring the Authentication Type

To configure the type of basic authentication to use for cluster link connections, enter the following command:

solace(...-routing/cluster/authentication/basic)# auth-type {internal | none}

Where:

internal specifies to authenticate cluster link connections against a locally-configured password.

none specifies that no authentication is required (in other words, an anonymous login is allowed).

Configuring a Password for Basic Internal Authentication

To configure a password for basic internal authentication of cluster link connections, enter the following command:

solace(...-routing/cluster/authentication/basic)# password <password>

Where:

<password> is the password you want to use to authenticate incoming cluster links (both control and data channels). This password is also used for all outgoing links if each link does not have a per-link password.

Configuring Authentication Using Client Certificates

Client-certificate authentication requires a cluster link to prove its identity to a remote node through an X509v3 client certificate from a recognized Certification Authority (CA).

To use client-certificate authentication, you must configure the client certificate that cluster links present to the remote node when initiating the connection. The node that initiates the link connection presents its client certificate to the remote node; the remote node presents its SSL server certificate to the initiating node for client certification. Each node can be configured with a per-cluster client certificate, which is used as the offered credentials for outgoing links. Only one client certificate can be configured per cluster; it can't be overridden on a per-link basis. In addition, you must configure at least one client certificate matching rule condition when using client certificate authentication for cluster links (see Configuring Client Certificate Matching Rules).

Client-certificate authentication is compatible with encrypted connections only. For more information about configuring encrypted connections, see Enabling TLS/SSL Encryption.

To configure client-certificate authentication for all links in the cluster, enter the following commands:

solace(...igure/routing/dynamic-message-routing)# cluster <cluster-name>
solace(...uting/dynamic-message-routing/cluster)# authentication
solace(...essage-routing/cluster/authentication)# client-certificate

Configuring the Client Certificate File to Present to Remote Nodes

To configure the certificate file to use, enter the following command:

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

Where:

<file> specifies the certificate file used to authenticate all cluster links (both control and data channels). This certificate is presented to the remote node by the node initiating the connection for authentication when the link is established. The certificate file must be in the certs directory in the jail directory (refer to Copying Files). Once installed, you may remove the file in the certs directory.

Configuring Client Certificate Matching Rules

When you configure client certificate matching, you create a set of matching rules per cluster. For a client certificate to be accepted as a valid credential, the certificate must match at least one rule. Each rule contains a set of one or more conditions, all of which must be satisfied for a certificate to match the rule. Each condition compares a certificate field with an attribute associated with the cluster link or a fixed glob expression.

You can also create attribute filters to ensure that the matching rule applies only to cluster links with certain attribute values. For example, you could mark certain cluster links with a span attribute and then create a rule that contains both an attribute filter which checks that the value of the span attribute is set to internal, and a simple condition that allows those links to authenticate with remote nodes.

You must configure at least one client certificate matching rule condition when using client certificate authentication for cluster links.

To configure a client certificate matching rule, enter the following commands:

solace(...ter/authentication/client-certificate)# matching rules
solace(...ion/client-certificate/matching-rules)# create rule <name>

To configure a client certificate matching rule condition, enter the following comands:

solace(...lient-certificate/matching-rules/rule)# create condition {certificate-thumbprint | common-name | common-name-last | subject-alternate-name-msupn | uid | uid-last | org-unit | org-unit-last | issuer | subject | serial-number | dns-name | ip-address} {{matches-attribute <attribute>} | {matches-expression <expression>}}

To configure a client certificate matching rule attribute filter, enter the following commands:

solace(...lient-certificate/matching-rules/rule)# create attribute-filter <name>
solace(.../matching-rules/rule/attribute-filter)# name <value>
solace(.../matching-rules/rule/attribute-filter)# value <value>

To enable a certificate matching rule, enter the following CONFIG commands:

solace(...lient-certificate/matching-rules/rule)# no shutdown

By default, client certificate matching is disabled and any otherwise valid certificate is accepted. To enable client certificate matching, enter the following CONFIG commands:

solace(...ion/client-certificate/matching-rules)# no shutdown
Where:

rule <name> specifies the name of the certificate matching rule.

certificate-thumbprint compares the certificate thumbprint with the specified attribute or glob expression. The certificate thumbprint is a SHA-1 hash of the entire DER-encoded certificate calculated by the broker after it receives the client certificate.

common-name compares the first instance of the CN in the client certificate with the specified attribute or glob expression.

common-name-last compares the last instance of the CN in the client certificate with the specified attribute or glob expression.

subject-alternative-name-msupn compares the msUPN (in the otherName field) in the SAN extension of the client certificate with the specified attribute or glob experssion.

uid compares the first instance of the user identifier (UID) attribute in the client certificate with the specified attribute or glob expression.

uid-last compares the last instance of the UID attribute in the client certificate with the specified attribute or glob expression.

org-unit compares the first instance of the Org Unit attribute in the client certificate with the specified attribute or glob expression.

org-unit-last compares the last instance of the Org Unit attribute in the client certificate with the specified attribute or glob expression.

issuer compares the Issuer attribute in the client certificate with the specified attribute or glob expression.

subject compares the Subject attribute in the client certificate with the specified attribute or glob expression.

serial-number compares the client certificate serial number with the specified attribute or glob expression.

dns-name compares the DNS name in the SAN extension of the client certificate with the specified attribute or glob expression.

ip-address compares IP address in the SAN extension of the client certificate with the specified attribute or glob expression.

matches-attribute <attribute> specifies the attribute used in the comparison.

matches-expression <expression> specifies the glob expression used in the comparison. The expression is compared directly to the field extracted from the certificate and may contain wildcards.

attribute-filter <name> specifies the name of the attribute filter.

attribute <value> specifies the name of the attribute to be tested.

value <value> specifies the expected value of the attribute in order to apply the certificate matching rule.

Certificate matching rules have no effect unless the links or cluster is restarted.

Examples

Internal Links

Internal links are likely to have a uniform set of rules, or most likely a single rule that extracts the node name from a client certificate and compares it to a link attribute carrying the node name. A typical rule for internal links might look like this:

solace(...ion/client-certificate/matching-rules)# create rule internal
solace(...lient-certificate/matching-rules/rule)# create condition common-name matches-attribute nodeName
solace(...lient-certificate/matching-rules/rule)# no shutdown

This requires that you also create the nodeName attribute on the cluster link, for more information, see Setting Cluster Link Attributes.

External Links

External links are likely to connect to a cluster managed by a different organization with different certificate styles, so more configuration is likely to be required, for example:

solace(...ion/client-certificate/matching-rules)# create rule external
solace(...lient-certificate/matching-rules/rule)# create condition issuer matches-attribute issuer
solace(...lient-certificate/matching-rules/rule)# create condition subject matches-attribute subject
solace(...lient-certificate/matching-rules/rule)# no shutdown

This requires that you also create the issuer and subject attributes on the cluster link, for more information, see Setting Cluster Link Attributes.

Differentiating the Rules for Internal and External Links

To apply different rules for internal and external links, you can create attribute filters that ensure the rule only applies to links with certain attribute values. This allows you to create a unique rule for each external link, that only applies when the nodeName attribute has a certain value.

solace(...ion/client-certificate/matching-rules)# create rule internal
solace(...lient-certificate/matching-rules/rule)# create attribute-filter spanInternal
solace(.../matching-rules/rule/attribute-filter)# attribute span
solace(...rules/rule/attribute-filter/attribute)# value internal
solace(...rules/rule/attribute-filter/attribute)# exit
solace(.../matching-rules/rule/attribute-filter)# exit
solace(...lient-certificate/matching-rules/rule)# create condition common-name matches-attribute nodeName
solace(...lient-certificate/matching-rules/rule)# no shutdown
solace(...lient-certificate/matching-rules/rule)# exit
solace(...ion/client-certificate/matching-rules)# create rule external1
solace(...lient-certificate/matching-rules/rule)# create attribute-filter nodeName
solace(.../matching-rules/rule/attribute-filter)# attribute nodeName
solace(...rules/rule/attribute-filter/attribute)# value external-node-1
solace(...rules/rule/attribute-filter/attribute)# exit
solace(.../matching-rules/rule/attribute-filter)# exit
solace(...lient-certificate/matching-rules/rule)# create condition issuer matches-expression "CN=CA1, O=org1, ..."
solace(...lient-certificate/matching-rules/rule)# create condition subject matches-expression "CN=external-node-1, O=org1, ..."
solace(...lient-certificate/matching-rules/rule)# no shutdown

This requires that you also create the span and nodeName attributes on the internal cluster links, and the nodeName attribute on external cluster links. For more information, see Setting Cluster Link Attributes.

Enabling TLS/SSL Encryption

The following is required before you can enable TLS/SSL encryption for links in the cluster:

  • TLS/SSL service must be configured and enabled on both nodes on each cluster link. This requires the TLS/SSL server-certificate to be configured on the node which receives the encrypted connection. See Managing Server Certificates.

  • With client-certificate authentication configured, the client-certificate file that identifies the node initiating the encrypted connection must be loaded onto the node. See Configuring the Client Certificate File to Present to Remote Nodes.

To configure TLS/SSL encryption, enter the following commands:

solace(...uting/dynamic-message-routing/cluster)# ssl
solace(...g/dynamic-message-routing/cluster/ssl)# server-certificate-validation

The TLS/SSL configuration tasks that you can perform include:

When you make a change to the server certificate validation settings for a DMR cluster, the PubSub+ broker automatically disconnects and then reconnects all TLS-enabled links in the cluster to enable the change.

Enabling the Validation of the Server Name

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 the validation of server names:

solace(...g/dynamic-message-routing/cluster/ssl)# server-certificate-validation
solace(...ter/ssl/server-certificate-validation)# validate-server-name

To disable server name validation:

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

Configuring the Maximum Certificate Chain Depth

You can configure the maximum allowed depth of a server-certificate chain. The depth of a chain is defined as the number of signing CA certificates that are present in the chain back to a trusted self-signed root CA certificate.

To configure the maximum allowed depth of a certificate chain, enter the following commands:

solace(...g/dynamic-message-routing/cluster/ssl)# server-certificate-validation
solace(...ter/ssl/server-certificate-validation)# max-certificate-chain-depth <max-depth>

Where:

<max-depth> specifies the maximum allowed depth of a certificate chain.

Enabling the Validation of the Certificate Date

You can enable or disable the validation of the Not Before and Not After validity dates in the server-certificate. When disabled, the certificate is accepted even if the certificate is not valid based on these dates.

To enable certificate date validation:

solace(...g/dynamic-message-routing/cluster/ssl)# server-certificate-validation
solace(...ter/ssl/server-certificate-validation)# validate-certificate-date

To disable certificate date validation:

solace(...ter/ssl/server-certificate-validation)# no validate-certificate-date