Managing integration with TrueSight Middleware Administrator with the CLI

The mqtool utility is used to manage integration with TrueSight Middleware Administrator (TSMA). It can be used to perform the following activities:

Installing a new TSMA license key

Use this option if an invalid key or TSMA mode was chosen during installation. See TrueSight Middleware Administrator integration options for information on the various modes of integration.

If you wish TSMA to use the same security service as TrueSight Middleware and Transaction Monitor (TMTM) choose “y”. Otherwise, choose “n”.

mqtool --install-key license_key –configure-ldap y|n   user

Configuring the TSMA integration

Use the --configure option if you chose to configure TSMA later during installation.

When using the following variation of the command the user used to configure with TSMA  is the same user used to execute the mqtool utility.  Refer to TrueSight Middleware Administrator integration options, Users and Security for more information on the users specified with this command option.

mqtool --configure --admin-url url --admin-ldap-user user

    --admin-ldap-password password|console --admin-project project

    --admin-ts-path filepath --admin-ts-password password user

When using the following variation, the user specified by –admin-user specifies the user used to configure TSMA.

mqtool --configure --admin-url url --admin-user user --admin-password

    password|console --admin-ldap-user user --admin-ldap-password

    password|console --admin-project project --admin-ts-path filepath

    --admin-ts-password password user

The –configure command preserves the above values including the user for use with other commands and synchronization of WMQ Connections.

If for some reason you must re-install TSMA, you can reconfigure it again without specifying all the values again using --reconfigure.

mqtool --reconfigure user

When using --configure or --reconfigure and TSMA has previously been configured as determined by its security mode being LDAP_LDAP then most of the security settings are left untouched in case they have been manually altered and in a good working state. The exception is the LDAP Manager DN credentials which are always updated if they differ. You may alter this default behavior by using the -u option which indicates to update the TSMA values that differ with the TMTM values as defined in services.cfg. If the TSMA values are working and you do not wish to update them, you may specify the -g option to save them to services.cfg in case TSMA needs to be re-installed and you wish those values to be used. Note that -g does not update the LDAP Manager DN credentials in services.cfg. The -u and -g options can not be specified at the same time. Basic user authentication must be working in order for TMTM to log into TSMA and -u to succeed.

At any time, you can check the configuration using –check-config.

mqtool --check-config user 

Updating configuration values

Use –update-admin-password if you need to change the user or the user’s password that configures TSMA.

You should use this command before altering the user’s password. During this time TSMA will be unavailable. If you alter the password first you will be unable to log into TSMA with this user nor will TMTM be able to change the configuration with this user. It is recommended you have more than one TSMA administrator in case such a situation occurs. 

When using the following variation of the command the user used to configure with TSMA is the same user used to execute the mqtool utility. This user is preserved for use with other commands and synchronization of WMQ Connections. 

These options use the user running mqtool.

mqtool --update-admin-password user

When using the following variation, the user specified by –admin-user specifies the user used to configure TSMA. 

mqtool --update-admin-password --admin-user user --admin-password

    password|console user

Use the following option if you need to change the user or the user’s password that is used to authenticate users and retrieve user and group information with the security service.

You should use this command before actually altering the user’s password. During this time TSMA will be unavailable. If you alter the password first you will be unable to log into TSMA nor will TMTM be able to change the configuration.

mqtool --update-ldap-password --admin-ldap-user user --admin-ldap-password

    password|console user

Use the following option if the hostname or port where TSMA is installed changed.

mqtool --update-admin-url url user

Use the following option to update the license key. For example, you may need to update your key if you have purchased a licensed version of TSMA.

mqtool --update-admin-key license_key user

Use the following option to change the name of the TSMA project to which TMTM creates WMQ_Connections. When using the Monitor Edition of TSMA the previous project will be removed and existing WMQ_Connections moved to the new project.

mqtool --update-admin-project project user

Use the following option to change whether the TSMA security configuration should use the same security service as TMTM. For example, if you decide your licensed edition of TSMA should now use the same security service as TMTM. Note that the Monitor Edition of TSMA must use the same security service.

If your licensed edition of TSMA should use the same security service as TMTM, specify “y” to indicate the TSMA ldap security settings will be configured. Otherwise, always specify “n” to indicate only the security settings will not be configured.

mqtool --update-configure-ldap y|n user

Use the following option to add all groups with the “TSMA User” permission to the TSMA project. This only applies to the Monitor Edition of TSMA and the licensed edition of TSMA when you have chosen to use the same security service as TMTM. It also only applies if synchronization of the project’s WMQ_Connections is enabled. This feature is on by default.

mqtool --update-sync-groups y|n user

Use the following option to control how often synchronization of the project’s WMQ Connections occurs. A value of 0 disables synchronization but can be one manually using this utility. The minimum value is 300 seconds (5 minutes) and is the default.

mqtool --update-sync-interval seconds user

Use the following option to update trust store certificates for connecting to TSMA. If you install your certificates in TSMA, you may need to update the certificate that you used to configure TSMA.

mqtool --update-cert user 

Creating a queue manager list file to work with other commands

There are several ways to specify the queue managers to which a mqtool command is applied. This command creates a file containing a list of queue managers that match the agent and queue manager regular expressions.

mqtool --create-qm-list filename --filter-agent regex --filter-qm regex  user 

Creating a channel definition inputs file

A channel definition input file contains all user defined input for creating the MQ server conn channel and supporting objects like listeners, authority records, etc., and a corresponding TSMA WMQ Connection.

The format of the file is JSON, but you should not manually alter the file; use the mqtool utility to avoid mistakes in formatting the file. The file is intended to be re-usable for sets of queue managers for the fastest way to configure large numbers of queue managers. For example, you would not use a channel name of CHANNEL_MYQUEUE_MANAGER as that would only apply to that queue manager. Instead, use something generic like TSMA_SERVER_CONN that easily identifies the server conn as one used by the TSMA product.   

Not all options are required. Refer to the Option Details section for a description of each parameter. You may also use alternative ways of specifying a single or multiple queue manager(s). 

mqtool --create-json filename --chl-name channel name 

(--chl-port port | --chl-port-min port --chl-port-max port) user

mqtool --create-json filename --chl-name channel name 

(--chl-port port | --chl-port-min port --chl-port-max port)

--chl-ip ip --chl-user user --chl-password password --chl-mqsc mqsc

--chl-replace  user 

Preserving a channel definition file

You can preserve a channel definition for a queue manager using –-save-chl-inputs. You can specify the channel definition inputs at the same time or import form a channel definition inputs file. 

You can also use alternative ways of specifying a single or multiple queue manager(s). 

mqtool --qm-list filename --chl-name channel name 

(--chl-port port | --chl-port-min port --chl-port-max port)

    --save-chl-inputs user

mqtool --qm-list filename --chl-json-file filename --save-chl-inputs user 

Showing a preserved channel definition file

You can display the currently saved channel definition inputs. You can also use alternative ways of specifying a single or multiple queue manager(s). 

mqtool --qm-list filename --show-chl-inputs user 

Applying the mq changes

You can apply the mq changes that would be made for defining a client connection to queue managers using --apply-mq-changes

You can also use alternative ways of specifying a single or multiple queue manager(s). 

mqtool --qm-list filename --apply-mq-changes user 

When applying the mq changes PCF is used. If required, you can specify -m and mqsc scripts are used when possible. Agentless configurations do not support mq changes using mqsc scripts. When using mqsc scripts all the commands are issued once and continue regardless of whether they fail. For example, if you stop the listener it often takes some time for it to actually stop and if you attempt to delete it right away you will get an object in use error. It is advised to use PCF where possible as operations are retried as necessary for temporary errors like this. If you wish to manually use mqsc scripts you can use --zip-mqsc to obtain the scripts that would have been executed and --run-mqsc to execute a script.

Note that when issuing mq changes against a version 7.x agent, either an IP address or a user can be specified to restrict access to the queue manager via the server connection channel, but not both. If both are required, you must alter the channel authority records manually. You can define your own mqsc script and use --runmqsc to execute it if the queue manager is not using an agentless configuration.

Reporting the result of applying the mq changes

You can report the result of the last application of the mq changes against queue managers using --report. This is the same output displayed at the time the last --apply-mq-changes was used. 

You can also use alternative ways of specifying a single or multiple queue manager(s). 

mqtool --qm-list filename --report user 

Checking the status of the MQ configuration of the queue managers

You can check the status of the server conn channel, listener and WMQ Connection for the specified queue manager(s) using --check-status

You can also use alternative ways of specifying a single or multiple queue manager(s). 

mqtool --qm-list filename --check-status user 

Creating the mqsc file

A mqsc file is a command file using the mqsc syntax that the MQ runmqsc command understands. TMTM uses this to create the server conn channel and other required objects.

You can create the mqsc file that would be used for defining a client connection to queue managers using --create-mqsc. You can also use alternative ways of specifying a single or multiple queue manager(s). 

mqtool --qm-list filename --create-mqsc user 

Manually applying the mqsc files 

If your company policies prohibit TMTM from creating the server conn channel, you can create and zip up the mqsc files for defining the client connection to a queue manager for manual application. 

You can also use alternative ways of specifying a single or multiple queue manager(s). 

mqtool --qm-list filename --zip-mqsc filename user 

Note that the mqsc script can contain commands to stop and remove listeners, channels and channel authority records. You should execute those commands separately and verify they have been removed prior to executing the remaining script that creates (or recreates) those objects. Otherwise, object in-use or object already exist error codes may occur.

Applying your own mqsc file

You can run your own mqsc file against queue managers. This is useful with the --zip-mqsc command if you need to alter the script to suit your environment. 

You can also use alternative ways of specifying a single or multiple queue manager(s). 

mqtool --qm-list filename --runmqsc filename user 

Converting Configuration Manager message files to TSMA format

If you have upgraded TMTM from an earlier version that used the Configuration Manager, you can use the --msg-file-convert option to convert any preserved messages to the TSMA file format for use with TSMA. 

mqtool --msg-file-convert filename user 

Checking the input queue managers list

Use the --check-qm-list option to verify the contents of the file.  It displays the list for verification. 

You can also use alternative ways of specifying a single or multiple queue manager(s). 

mqtool --check-qm-list filename user

Updating TSMA WMQ Connections

Use the --update-connections option to update the WMQ Connection with the current channel definitions. If necessary, the WMQ Connection will be created. 

You can also use alternative ways of specifying a single or multiple queue manager(s). 

mqtool --qm-list filename --update-connections user

Removing TSMA WMQ Connections

Use the --remove-connections option to remove a WMQ Connection. Only use this option if the queue manager no longer exists in the TMTM object repository. 

You can also use alternative ways of specifying a single or multiple queue manager(s). 

mqtool --qm-list filename --remove-connections user 

Manually synchronizing the TSMA WMQ Connections

Use --sync-integration to manually remove, create or update WMQ Connections to match the queue mangers in the TMTM object repository. 

mqtool --sync-integration user

Testing TSMA WMQ Connections

Use --test-connections to test that TSMA can connect over the defined server conn channel. 

You can also use alternative ways of specifying a single or multiple queue manager(s). 

mqtool --qm-list filename --test-connections user 

Getting information about a queue manager

Use the following commands to display MQ information about the queue manager(s). 

You can also use alternative ways of specifying a single or multiple queue manager(s).

mqtool --qm-list filename --list-qm-authrec user

mqtool --qm-list filename --list-listeners user

mqtool --qm-list filename --list-srvrconn-channels user

mqtool --qm-list filename --list-chlauth user

Alternative ways of specifying a single or multiple queue manager(s)

Rather than a list using --qm-list you can specify a single queue manager using the following alternatives: 

--agent agent_name --qm queue_manager_name

--qm-oid hi_lo_typeid

--agent-oid hi_lo_typeid --qm queue_manager_name

You can also use regular expressions to specify multiple queue managers. 

--filter-agent regex --filter-qm regex 

Defining password entry for specific operations 

You can specify 'console' for passwords for which you would rather be prompted. The agent connection options [--agent-port port] [--secured-agent-user and user --secured-agent-password password|console] are supported on the following operations:

--check-status

--create-mqsc

--apply-mq-changes

--zip-mqsc

--list-listeners

--list-srvrconn-channels

--list-chlauth

--list-qm-authrec

--runmqsc 

mqtool options

Option

Description

--admin-ldap-password password|console

Password used for LDAP access by TSMA for the user specified by --admin-ldap-user.

--admin-ldap-user userUser used for LDAP access by TSMA.
--admin-password password|console

Password used for administrative access to TSMA for the user specified by --admin-user.

--admin-project projectProject to use in TSMA.
--admin-ts-password passwordPassword for trust store with the certificate to access TSMA.
--admin-ts-path filepathFile path for trust store with the certificate to access TSMA.
--admin-url urlURL to TSMA.
--admin-user user

User used for administrative access to TSMA rather than the mqtool user.

--agent agent_nameAgent name.
--agent-oid hi_lo_typeidAgent OID.
--agent-port port

Port of pre-8.0 agent. Applies to ALL pre-8.0 agents in --qm-list not using the default port of 2612. If not specified you will be prompted for each pre-8.0 agent not using the default port. You only need to specify a port once, and it will be preserved for future operations.

--apply-mq-changes

Apply mq changes for queue managers, --qm-list. When channel input has been specified, --save-chl-inputs is implied. Otherwise only previously saved inputs are used.

--as-host host_nameApplication Service host.
--as-port port_numberApplication Service port.
--check-configCheck the configuration for integration with TSMA.
--check-qm-list filenameCheck queue manager list, --qm-list.
--check-status 

Check the status of MQ configuration for queue managers, --qm-list.

--chl-ip ipIP address of TSMA used to restrict channel access.
--chl-json-file filenameJSON file containing input parameters.
--chl-mqsc mqscAdditional mqsc keywords.
--chl-name channel nameName of server conn channel(s) used by TSMA.
--chl-password passwordPassword for user used to restrict channel access.
--chl-port port

Listener port of queue manager of server conn channel(s) used by TSMA.

--chl-port-maxMaximum listener port range of queue manager of server conn channel(s) used by TSMA.
--chl-port-minMinimum listener port range of queue manager of server conn channel(s) used by TSMA.
--chl-replaceReplace an existing channel.
--chl-user userUser used to restrict channel access.
--configure

Save configuration information and configure integration with TSMA.

--configure-ldap y|n

Specifies whether TSMA and TMTM have a common LDAP access. Must be yes for Monitor Edition.

--create-json filenameCreate a JSON file containing input parameters.
--create-mqsc

Create and show mqsc scripts for queue managers, --qm-list. When channel input has been specified, save-chl-inputs is implied. Otherwise only previously saved inputs are used.

--create-qm-list filenameCreate a list of queue managers, --qm-list.
--list-qm-authrec

List queue manager authority records (authrec) definitions for queue managers, --qm-list.

--filter-agent regex

Restricts --create-qm-list to agents matching regular expression.

--filter-qm regex

Restricts --create-qm-list to queue managers matching regular expression.

--install-key license_key

Install TSMA key used to configure TSMA. Requires --admin-edition-configured. Use this option when an invalid key was specified during installation.

--list-chlauth

Lists server conn channel authentication (chlauth) definitions for queue managers, --qm-list.

--list-listenersLists listeners for queue managers, --qm-list.
--list-srvrconn-channelsLists server conn channels for queue managers, --qm-list.
--msg-file-convert filename

Convert message file to TSMA format. Output has the same filename with .json appended for use with TSMA.

--qm queue_manager_nameQueue manager name.
--qm-list filenameList of queue managers.
--qm-oid hi_lo_typeidQueue manager OID.
--reconfigure

Reconfigure using preserved configuration information from --configure for integration with TSMA.

--remove-connectionsRemove TSMA WMQ connections.
--report 

Report on the last result of running mqsc scripts for queue managers, --qm-list.

--runmqsc filenameRun a MQSC script.
--save-chl-inputsSave channel inputs for queue managers, --qm-list.
--secured-agent-password password|console

Pre-8.1 secured agent password for user specified by --secured-agent-user.

--secured-agent-user user

Pre-8.1 secured agent user used for authentication with MQ. Applies to ALL secured agents in --qm-list. If not specified you will be prompted for each secured agent. You must always specify a user and password for any operation applied to a secured agent.

--show-chl-inputsShow saved channel inputs for queue managers, --qm-list.
--sync-groups y|n

Synchronize by adding groups to or removing groups from the TSMA project based on whether they have the 'Run Configuration Manager' permission.

--sync-integration

Immediately adds or removes WMQ Connections to TSMA to keep in sync with queue managers in the object repository rather than waiting for the next periodic synchronization.

--sync-interval seconds

How often to periodically synchronize WMQ_Connections and groups to the TSMA project. Value must be >= 300 or 0 to disable.

--test-connectionsTest TSMA WMQ connections for queue managers.
--update-admin-key license_keyUpdate TSMA key.
--update-admin-passwordUpdate password for connecting to TSMA.
--update-admin-project projectUpdate TSMA project name.
--update-admin-url urlUpdate TSMA URL.
--update-certUpdate security certificate for integration with TSMA.
--update-configure-ldap y|n

Updates whether TSMA and TMTM have a common LDAP access. Must be yes for Monitor Edition.

--update-connections

Update channel definitions in TSMA WMQ connections for queue managers, --qm-list.

--update-ldap-passwordUpdate password used for LDAP access by TSMA.
--update-sync-groups y|nUpdate --sync-groups setting.
--update-sync-interval seconds

Update --sync-interval setting. Value must be >= 300 or 0 to disable.

--zip-mqsc filename

Zip mqsc scripts for queue managers, --qm-list for manual execution. When channel input has been specified, --save-chl-inputs is implied. Otherwise only previously saved inputs are used.

-c

Continue with other queue managers when errors are encountered.

-h|-?Give this help summary.
-i

Ignore agents or queue managers that are not connected or active.

-m

Use mqsc to apply MQ changes. The default is to use APIs that use PCF.

-p passwordPassword.
-r

Replace channel definition in media if it exists. The default is to use the one previously saved.

-s|--stdin 

Specify password via stdin. This is mutually exclusive with -p.

-vRun in verbose mode.
-y

Do not prompt, create trust store file and add cert if necessary from TSMA connection. This option is not recommended. 

-gGet any TSMA security settings manually altered in TSMA.
-uUpdate TSMA security settings even if previously configured.


Was this page helpful? Yes No Submitting... Thank you

Comments