NativeHALocalInstance stanza of the qm.ini file

The NativeHALocalInstance stanza controls operation of a Native HA configuration.

The NativeHALocalInstance stanza is added automatically to the qm.ini file on each of the nodes when you create a Native HA configuration. You can then edit the qm.ini file and customize the attributes in the NativeHALocalInstance stanza.

Name

The name of the NativeHALocalInstance stanza, taken from the log replica instance name specified when the Native HA queue manager is created.

You can optionally add the following attributes to the NativeHALocalInstance stanza:

KeyRepository

The full path and the file name of the key repository that holds the digital certificate that is used to protect log replication traffic. If the file extension is not specified, it is assumed to be .kdb.

If the KeyRepository stanza attribute is omitted, log replication data is exchanged between instances in plain text.

KeyRepositoryPassword

The key repository is secured with a password as it contains sensitive information. To be able to access the key repository contents, IBM® MQ must be able to retrieve the key repository password. If the password is not stored in a key repository stash file, you can supply the password in the KeyRepositoryPassword attribute. For example:

KeyRepositoryPassword=passw0rd

Attention: If you supply the password by using this attribute, encrypt the password with the IBM MQ password protection system. For more information, see Encrypting the key repository password.

InitialKeyFile

Specify this attribute if the key repository password that is specified with the KeyRepositoryPassword attribute is encrypted with a specific initial key. The name of the file that contains the initial key can be specified by using the -sf parameter when the runmqicred command is used to encrypt the key repository password.

Set the value of this attribute to the name of the file that contains the initial key used to encrypt the password. For example, if a file called mykey.key contains the initial key:

InitialKeyFile=/mykey.key

For more information, see Encrypting the key repository password.

CertificateLabel

The certificate label identifying the digital certificate to use for protection of log replication traffic. If KeyRepository is provided but CertificateLabel is omitted, a default value of ibmwebspheremqqueue_manager is used.

CipherSpec

The CipherSpec to use to protect log replication traffic. If this stanza attribute is provided, KeyRepository must also be provided. If KeyRepository is provided but CipherSpec is omitted, a default value of ANY is used.

LocalAddress

The local network interface address that accepts log replication traffic. If this stanza attribute is provided it identifies the local network interface and/or port using the format "[addr][(port)]". The network address can be specified as a hostname, IPv4 dotted decimal, or IPv6 hexadecimal format. If this attribute is omitted, the queue manager attempts to bind to all network interfaces, it uses the port specified in the ReplicationAddress in the NativeHAInstances stanza matching the local instance name.

HeartbeatInterval

The heartbeat interval defines how often in milliseconds an active instance of a Native HA queue manager sends a network heartbeat. The valid range of the heartbeat interval value is 500 (0.5 seconds) to 60000 (1 minute), a value outside of this range causes the queue manager to fail to start. If this attribute is omitted, a default value of 5000 (5 seconds) is used. Each instance must use the same heartbeat interval.

HeartbeatTimeout

The heartbeat timeout defines how long a replica instance of a Native HA queue manager waits before it decides that the active instance is unresponsive. The valid range of the heartbeat interval timeout value is 500 (0.5 seconds) to 120000 (2 minutes). The value of the heartbeat timeout must be greater than or equal to the heartbeat interval.

An invalid value causes the queue manager to fail to start. If this attribute is omitted a replica waits for 2 x HeartbeatInterval before starting the process to elect a new active instance. Each instance must use the same heartbeat timeout.

RetryInterval

The retry interval defines how often in milliseconds a Native HA queue manager should retry a failed replication link. The valid range of the retry interval is 500 (0.5 seconds) to 120000 (2 minutes). If this attribute is omitted a replica waits for 2 x HeartbeatInterval before retrying a failed replication link.

SSLFipsRequired

Specifies whether only FIPS certified algorithms are used if cryptography is used in sending log replication traffic. Set to Yes or No.

EncryptionPolicySuiteB

Specifies whether log replication traffic uses Suite-B compliant cryptography and what level of strength is used. Set to one of the following values:

NONE

Suite-B compliant cryptography is not used. This setting is the default setting.

128_BIT,192_BIT

Sets the security strength to both 128-bit and 192-bit levels.

128_BIT

Sets the security strength to 128-bit level.

192_BIT

Sets the security strength to 192-bit level.

CompressionThreshold

Sets a byte threshold that, when crossed, triggers compression of log data. Log data larger than the threshold value is compressed. A value of 0 (the assumed default) turns off all compression, a value of 1 compresses every log append. The maximum value is 268435456 (256 MB).

LZ4Acceleration

A tuning parameter that controls how the LZ4 algorithm looks for compressible sequences in the log data. Every time the acceleration value increases by 1, the algorithm does not look quite as carefully for a compressible sequence, exchanging compression ratio for a small performance gain. The minimum (and assumed default) value is 1, the maximum is 65537.

GroupName

Specifies the group name that this instance is a member of. This is required if:

• If a NativeHARecoveryGroup stanza is specified (regardless of whether it is enabled or not).
• If the GroupRole is set to Recovery.

GroupRole

Specifies the current role of the group that the instance belongs to. Set to Live or Recovery.

GroupLocalAddress

Specifies the replication network interface and port to advertise for the group. If not specified, defaults to all network interfaces and port 9415.

GroupCipherSpec

Optionally overrides the CipherSpec when establishing a TLS connection between groups. The group connection must be secured using TLS.

GroupCertificateLabel

Optionally overrides the certificate label to use for mutual authentication when establishing a TLS connection between groups.

GroupCompressionThreshold

Sets a byte threshold that, when crossed, triggers compression of log data when sent to a recovery group. Log data larger than the threshold value is compressed. A value of 1 (the assumed default) compresses every log append. A value of 0 turns off all compression of log data being sent to a recovery group. The maximum value is 268435456 (256 MB).

Encrypting the key repository password

The key repository password can be protected by using either the IBM MQ password protection system, or a key repository stash file. For more information about these two methods, see Encrypting key repository passwords.

If the repository password is specified by using the KeyRepositoryPassword attribute in the NativeHALocalInstance stanza, encrypt the password by using the password protection system. Use the IBM MQrunmqicred command to encrypt the password. The command returns the encrypted password that can be specified in the KeyRepositoryPassword attribute.

Use a unique initial key to encrypt the password securely. The name of the file that contains the initial key can be specified by using the -sf parameter to the runmqicred command. If you do not supply a unique key, the default key is used.

If you encrypt the key repository password with a unique initial key, you must also supply the same initial key by using the InitialKeyFile attribute in the NativeHALocalInstance stanza.

Example stanza

The following example shows the NativeHALocalInstance stanza used in the qm.ini file to specify the local name of a node.

NativeHALocalInstance:
  Name=node-1

The following example shows the NativeHALocalInstance stanza used in the qm.ini file to specify the local name of a node, and to specify the group details because the instance is part of a Native HA cross-region replication configuration

  Name=alpha-1
  GroupName=alpha
  KeyRepository=/var/mqm/qmgrs/MYQM/ssl/key
  CertificateLabel=MyCertificate
  CipherSpec=NULL
  GroupRole=Live
  GroupCipherSpec=ANY_TLS12
  GroupLocalAddress=(4445)