Adding connections

This section describes how to define an IBM MQ connection in MainView Middleware Administrator (MVMA).

To add a new IBM MQ connection

1. Select the WMQ Connections option (click the words WMQ Connections, not the horizontal navigational arrow to its right) from the Navigation Panel. The IBM MQ Connections summary view is displayed (see the IBM MQ connections summary section below for details on the operations available in the summary view).
2. Select the Add Item  icon, and the Properties for New Connection dialog is displayed.
3. Define the appropriate connection properties. All fields in the General category with the exception of Disable Connection are required. See the section below for details on each of the available connection properties.
4. Save your work. The IBM MQ Connections summary view returns to the workspace, with the newly created connection displayed in the list.

IBM MQ connection properties

This section describes the properties that can be applied to a IBM MQ connection via the IBM MQ Properties for the Connection screen.

General

This category contains general settings for making a connection to the queue manager.

• Connection Name: The connection name to be used in MVMA.
• QMgr Name: The name of the queue manager.
• Host: The hostname where the target queue manager is located, or if Proxy Enabled is selected (see the Proxy section below) where the proxy queue manager is located.
• Port: The port number where the target queue manager, or if Proxy Enabled is selected (see the Proxy section below) where the proxy queue manager will be listening.
• Channel: The server connection channel.
• z/OS Queue Manager: Enable to indicate the connection targets a mainframe queue manager and that messages of type MQSTR should be created in the queue manager's CCSID if message conversion is turned on in the MVMA configuration. This will result in new string messages to be converted to EBCDIC on a z/OS queue manager automatically when creating them from within MVMA.

• Connection Disabled: The check box to temporarily suspend or disable the connection. When selected, MVMA does not establish new connections to the destination queue manager to process user requests or perform background tasks such as archiving or collecting data for monitoring or indexing, until this flag is unselected again.

  Warning

  Important

  As of MVMA 9.1.00.B product administrators can configure automatic conversion of MQ string messages for connections flagged as z/OS Queue Manager adding an entry msg.string.data.conversion=true to the configuration file com.bmc.mmpa.wmq.qm.connection.cfg.

Monitoring

Monitoring Enabled: This field determines whether the connection's object metrics will be evaluated by applicable event triggers.

Indexing

These fields configure indexing behavior for this connection.

• Indexing Enabled: Default is off, turn on to have the connection indexed.
  A connection needs to be indexed for its objects to be included in search results.

• Indexing Type: Choose whether you want the connection indexed at a regular hourly interval, or once per day.
• Indexing Hour/Interval: Depending on the selected 'Indexing Type', this field can represent 1) the hourly interval, or 2) time of day for daily indexing (0-23, 0 == midnight, 12 == noon.)

Security

These fields are for configuring SSL channels and security exits. See the Using an SSL configured IBM MQ connection section below.

• SSL Enabled: Default is off. Turning this on indicates you want the client channel to communicate securely, and requires that you enter a value in the Cipher Suite field (below).
• Cipher Suite: See above. The value entered in this field should be compatible with the SSL Cipher Spec value for the client channel.
• Security Exit Enabled: Default is off. Enable this to specify security exit information for connection.
• Security Exit Library Name: Library name value for specifying security exit to be used by connection.
• Security Exit Entry Point: Entry point value for specifying security exit to be used by connection.
• Security Exit Data: Data for specifying security exit to be used by connection.
• Username / Password: Setting these values will pass credentials with each connection request. These are required for IBM MQ 8.0 queue managers with 'Connection Authentication' enabled.
• Override Credentials: This option enables administrators to further secure their middleware environment with individual authentication, which provides a means of overriding the credentials used to connect to IBM MQ queue managers. When selected, certain functionality (as listed below) will require the user to enter credentials to be authenticated by the queue manager. Once valid credentials are supplied, they will be re-used for actions on that connection for the remainder of the MVMA session. 
  • All Messaging Operations
  • Refresh Queue Manager
  • Reset Queue Manager
  • Start Channel
  • Stop Channel
  • Ping Channel
  • Reset Channel
  • Resolve Channel

Proxy

These fields are for configuring a proxy queue manager to be used for making an indirect connection.

• Proxy Enabled: Default is off. Turn this on to use a proxy queue manager.

• QMgr Proxy: Name of the queue manager used as the proxy to the target queue manager in the connection.

  Warning

  Important

  Using a proxy connection with 

  MVMA

   requires the proper set up of IBM MQ for the underlying proxy and destination queue managers and their connections to each other. The following steps are required by IBM (for more details see the IBM MQ product documentation) for setting up the proxy queue manager (QMPROXY) and the target queue manager (QMTRGT):

  1. Create a transmission queue on the proxy queue manager (QMPROXY) to the target queue manager as, for example, the default transmission queue being named after the target queue manager QMTRGT.
  2. Create a transmission queue on the target queue manager (QMTRGT) to the proxy queue manager as, for example, the default transmission queue being named after the proxy queue manager QMPROXY.

  Default transmission queues must be available on both of the queue managers involved linking the proxy queue manager to the destination queue manager, and vice-versa.

Advanced

These fields are for specifying objects or settings that, while unnecessary in most configurations, provide flexibility when necessary.

• Command Input Queue: Queue name that MVMA will use to send command requests to MQ. Generally, this can be left blank; if left blank, a SYSTEM queue will be determined and used, depending on the queue manager platform. This is mainly used as part of setting up a proxy connection (see the above section) for routing commands to the command queue on the target queue manager.
• Command Reply Model Queue: Model Queue name that MVMA will use to create a temporary dynamic queue for reading response data from MQ. If left blank, BMM.RESPONSE.MODEL.QUEUE will be used.

• Max Connections: Maximum number of connections MVMA can have to a single unique queue manager configuration (hostname!qmgr!channel!port). The default is 10 unique connections.

  Warning

  Important

  If multiple connections are configured with the same hostname!qmgr!channel!port values, each connection maintains its own max connection limit. This is important to keep in mind, as the number of channel instances on the queue manager can increase with every connection defined for those unique hostname!qmgr!channel!port values.

• Max Idle Time: Maximum seconds MVMA will wait before expiring an idle queue manager connection. The default is 600 seconds or 10 minutes (note that a value of 0 (zero) enforces the default).

• Connection Properties: Name/value pairs for custom java properties relevant to a queue manager connection. MVMA sets most necessary properties based on the connection definition – hostname, channel, port, userID, password, etc. For more details, refer to the MQEnvironment in IBM documentation.

  Warning

  Important

  For using a long password to connect to a queue manager having CONNAUTH enabled, set the 'Use MQCSP authentication' property to true in the MVMA connection definition when using MVMA with an MQ client prior to MQ 9.2.1 to switch to MQCSP connection mode. Not using that property defaults to the previous compatibility mode connection only supporting short passwords.

Remote File Access

These fields are for defining remote file access to various configuration and log files.

• File Access Scheme: Select from Auto-Detect, smb or ssh.
  When using SMB (in particular on Linux) use a resolved share path that maps to the physical path on that system. For example, for WMQ queue managers use a share named var that has a path of /var so the relevant WMQ files can be located at /var/mqm/qmgrs, and so on.
  In addition, it is possible that ssh remote connections will not work if the user specified in Access User has shell initialization scripts that produce output (like echo statements) for non-interactive sessions. Modifying the appropriate shell scripts should resolve this.
• File Access Port: The port used to access the remote system, which will depend on the File Access Scheme. ssh defaults to port 22 and smb defaults to port 445.
• File Access User: The username required to access the computer which hosts the queue manager.
• File Access Password: The password required to access the computer which hosts the queue manager.

• Discover Remote Files: Click the Discover button to fill in the relevant fields above (File Access username and password must be entered, as described above, for this functionality to work correctly).

• Global Error Directory: The directory path to a global IBM MQ error directory.
• MQS.INI File: The path to the IBM MQinstallation's mqs.ini configuration file.
• Queue Manager Log Directory: The log directory on the queue manager computer.
• Queue Manager Error Directory: The error directory on the queue manager computer.
• Queue Manager Root Directory: The directory root on the queue manager computer.
• QM.INI File: The path to the queue manager configuration file.
• Custom Directories: A list of directories identified by their individual symbolic name and their path that should be accessible for that connection additional to the default IBM MQ directories and files listed in this section.
  
  To configure a new directory click Add and enter a symbolic Name and a Path. Click OK to confirm the new entry. The symbolic name must be non-empty, must be a combination of the characters A-Z (upper or lowercase), the digits 0-9 and the underscore ('_') character, and must be a maximum of 20 characters in length.
  
  To modify an existing entry, identify the entry in the list and click in the corresponding Value field to adjust the path accordingly. The change takes effect when pressing Enter or switching to another field.
  
  To delete one or multiple custom directory entries, select them in the list and click Remove.
• Command Execution Type: Select from Set Executable Path, Use Default Path, or User Environment (the user environment that you provided the user credentials for).
• Command Platform: Select the relevant platform to define the default path that should be followed.

• Execution Path: Enter the relevant path (note that if you selected Set Executable Path as the Command Execution Type, you can add the path to the bin folder of your installation; this ensures support for multiple installation configurations where you might have, for example, different queue manager versions using different configurations).

  Warning

  Important

  The Command Execution Type, Command Platform, and Execution Path fields relate to operations (such as starting/stopping a queue manager, switching cluster channels or retrieving WMQ information) that are processed executing a command remotely on the queue manager’s host. These options require the setting up of the connection with the proper ‘Remote Access’ parameters, especially when SSH is selected as the File Access Scheme, together with the proper port and credentials. However, the ability to execute these remote commands does not require ‘Remote File Access’ on the project level to be enabled; it only requires the parameters mentioned to be correctly set up with the connection definition.

IBM MQ Connections Summary View

The WMQ Connections Summary View displays a list of the current IBM MQ connections in MVMA.

Operations available (from the Operations drop-down menu to the left of each connection):

• Test Connection: Click to ensure the values you defined are valid. This will take the current connection parameters and attempt to make a valid connection. Results of the attempt are displayed, and, if necessary, details can be adjusted for a successful connection.
• Copy: Copy this connection's details for a new connection. When clicking Copy, define the relevant connection settings in the displayed Properties for New Connection dialog.
• Delete: Delete this connection. When clicking Delete, you will be prompted to confirm the connection's deletion.

To edit the properties for the connection, click on the Connection Name. Then define the connection settings as required, as described above. 

Using an SSL configured WMQ connection

MVMA is able to connect to remote queue managers over a channel configured for SSL communication. In the WMQ Connection Properties Editor, select SSL Enabled, and enter a valid Cypher Suite value that is compatible with the SSL Cipher Spec value of the client channel. The SSL certificates that are required depend on the type of authentication required.

The following types of authentication are supported:

• Server Authentication: For Server (one way) authentication,  add the queue manager certificate or CA's root certificate to the truststore file, depending on the security infrastructure. With this setup, it is required to change the SSL Client Authentication attribute for the channel used by MVMA to Optional.
• Client Authentication: For Client (two way) authentication, add the queue manager certificate or CA's root certificate to the truststore file, depending on the security infrastructure. Also, a client certificate is required to be present in the keystore. With this setup, it is required to change the SSL Client Authentication attribute for the channel used by MVMA to Required.
   

Truststore and keystore files

For storing the certificates to be used for SSL configuration, MVMA uses the truststore and keystore files that are specified in the configuration/wrapper.conf entries below:

Securing keystore / truststore passwords used for WMQ SSL connections

To secure the keystores and truststores used for WMQ certificates when making SSL connections to queue managers, add the following properties to configuration/services/com.bmc.mmpa.wmq.qm.connection.cfg (note that the keystore/truststore names and passwords are for example purposes only):

ssl.keyStore=security/wmqkeys.jks
ssl.keyStorePassword=des:
{6Gu+V5O9Hic/GzQf8CRK1g==}
ssl.trustStore=security/wmqtrusts.jks
ssl.trustStorePassword=des:{6Gu+V5O9Hic/GzQf8CRK1g==}
ssl.protocol=TLS

Passwords can be encoded using the bin/encodeBmmPassword.sh or encodeBmmPassword.bat utility. Do not use bin/encodePassword.sh as that is used to encode Jetty passwords.

Note that using javax.net.ssl.* JVM system properties with encoded passwords for WMQ will not work. Ensure that you have configured your Admin service to handle the WMQ keystores and truststores using the above configuration. You can still use the same keystores and truststores, but you cannot configure access using system properties with encoded passwords for IBM MQ.