New features added to the runmqsc command in IBM MQ Version 8.0. IBM Techdoc:

Transcription

1 Page 1 of 28 New features added to the runmqsc command in IBM MQ Version 8.0 IBM Techdoc: Date last updated: 17-Jun-2016 Angel Rivera [email protected] IBM MQ Support +++ Objective The purpose of this techdoc is to provide examples of the new features added to the "runmqsc" command in IBM MQ 8.0. You use runmqsc to issue MQSC commands to a queue manager. New runmqsc features in MQ V8.0 support: "quit", access by non-administrators, client connection, CCDT, authentication The chapters are: Chapter 1: Quick summary of commands, including crtmqm, runmqsc and setmqaut Chapter 2: Usability: using 'quit' or 'exit' as synonym for 'end' Chapter 3: Non-administrators (not in the group 'mqm') can now use runmqsc Chapter 4: Flag -u to allow authentication Chapter 5: Flag -c to allow remote access through a client connection Chapter 6: Flag -n to allow the modification of a local CCDT file ++ Updates on 17-Jun-2016 Addition of: - MQPROMPT environment variable (Reference 3 in page 2) - MQ V9 provides support for keys in runmqsc in Unix to recall commands (Reference 4 in page 3) - New scenario in Chapter 3 to provide (in page 13): Scenario 4: Detailed scenario of remote user who is not an MQ administrator

2 Page 2 of References 1) For more information on the new flags, see the following web page: 01.ibm.com/support/knowledgecenter/SSFKSJ_8.0.0/com.ibm.mq.ref.adm.doc/q083460_. htm?lang=en WebSphere MQ > IBM MQ > Reference > Administration reference > IBM MQ Control commands > The control commands > runmqsc (run MQSC commands) 2) Some portions of the following free IBM Redbook is referenced in this techdoc: IBM MQ V8 Features and Enhancements (published 02-Oct-2014) 3) MQPROMPT environment variable introduced in MQ 8: Why does runmqsc have no prompt? (by Justin Fries) + begin excerpt MQ V8.0 adds the ability to set a prompt of your choice using the MQPROMPT environment variable. In additional to plain text, the MQPROMPT variable also allows environment variables to be inserted (using +VARNAME+ notation), in the same manner as MQ service object definitions. For example: sh> export +MQ_HOST_NAME+> " sh> runmqsc MY.QMGR 5724-H72 (C) Copyright IBM Corp. 1994, Starting MQSC for queue manager MY.QMGR. aix1> DISPLAY QMSTATUS + end excerpt

3 Page 3 of 28 4) New in MQ 9: runmqsc command line editor for UNIX platforms _.htm WebSphere MQ > WebSphere MQ > IBM MQ > Product overview > What's new in IBM MQ Version 9.0 > New for distributed platforms + begin excerpt runmqsc command line editor for UNIX platforms IBM MQ Version 9.0 adds the ability to use the up and down arrow keys, and tab key commands to control runmqsc commands on UNIX platforms. You can use the following keys: - Use the up arrow key to recall the previous runmqsc command - Use the down arrow key to recall the next runmqsc command - Use the tab key to offer completion options for the next keyword in the command + end excerpt ++ Configuration: Linux x86-64 bit, SLES 11 MQ Queue manager: TEST_80 (port 1419) (See Chapter 1 for steps) Directory for error logs of the queue manager: /var/mqm/qmgrs/test_80/errors

4 Page 4 of Chapter 1: Quick summary of commands, including crtmqm, runmqsc and setmqaut Summary of new flags for runmqsc + Connects in client mode, but prompts for password and authenticates provided credentials export MQSERVER='SYSTEM.ADMIN.SVRCONN/TCP/hostname(1414)' runmqsc -c -u user1 MYQMGR + Connects in local mode to define channels/authinfo objects into the local client channel definition (CCDT) file Unix: export MQCHLLIB=...(directory of CCDT) export MQCHLTAB=...(name of CCDT file) runmqsc -n Windows set MQCHLLIB=...(directory of CCDT) set MQCHLTAB=...(name of CCDT file) runmqsc -n Clarification Notes: - If you add new entries into the local channel definition file, or alter existing entries, these changes will NOT be reflected inside the queue manager. The queue manager does NOT read the contents of the local channel definition file. - The CCDT file is a write-only file from the perspective of the queue manager. The queue manager does NOT read the contents of the CCDT file. ++ Example of dmpmqcfg using remote connection An example of dmqmcfg en 8.0, from host-1 (Windows) talking to a queue manager in host- 2 (Linux) exploiting the remote connection: set MQSERVER='SYSTEM.ADMIN.SVRCONN/TCP/hostname(1414)' Notice that the keyword "-c default" is specified: dmpmqcfg -m QM_80 -u mqm -c default Enter password: (I entered the password) output of dmpmqcfg

5 Page 5 of Creating a queue manager for testing and initial customization to overcome typical security situations (not recommended for production) $ crtmqm -u DLQ TEST_80 Caveat: You must define the queue DLQ later. The above parameter does NOT actually create the queue, it just tells the queue manager which is the name of the dlq. Note: Many MQ Explorer users hide the SYSTEM* queues and thus, if you use as the dlq the SYSTEM.DEAD.LETTER.QUEUE, then it will be hidden and you may not notice if there are messages in the dlq. $ strmqm TEST_80 $ runmqsc TEST_80 ## Define a listener. The default is port (The default is 1414, but here another port is used, just to illustrate that it is possible to use another port other than 1414) define listener(listener) trptype(tcp) control(qmgr) port(1419) start listener(listener) ## Define a channel to be used by a remote MQ Explorer define channel(system.admin.svrconn) chltype(svrconn) ## Define the DLQ define qlocal(dlq) like(system.dead.letter.queue) ## Define test queue: define qlocal (Q1) ## For MQ 7.1 and if desiring to allow remote connections by an MQ Administrator: set CHLAUTH(*) TYPE(BLOCKUSER) USERLIST('nobody','*MQADMIN') set CHLAUTH(SYSTEM.ADMIN.*) TYPE(BLOCKUSER) USERLIST('nobody') ## For using MQSERVER for SYSTEM.DEF.SVRCONN SET CHLAUTH(SYSTEM.DEF.SVRCONN) TYPE(ADDRESSMAP) ADDRESS(*) USERSRC(CHANNEL) SET CHLAUTH(SYSTEM.DEF.*) TYPE(BLOCKUSER) USERLIST('nobody') ## For MQ 8.0 to disable userid/password for remote users ALTER AUTHINFO(SYSTEM.DEFAULT.AUTHINFO.IDPWOS) AUTHTYPE(IDPWOS) CHCKCLNT(OPTIONAL) REFRESH SECURITY TYPE(CONNAUTH) end

6 Page 6 of Providing remote access to non MQ Administrators To provide access to a non MQ administrator to the queue manager via command line or the MQ Explorer issue the 4 setmqaut commands shown below.. + Using -p flag (for a person). These setmqaut commands grant minimal authority to the userid myuser (using the PrincipalName, or person, flag: -p) The queue manager name is MYQMGR. The flag-value pair "t qmgr" refers to the object type of QueueManager. The flag-value pair "t q" refers to the object type of Queue.. 1. GENERAL (MQ EXPLORER and COMMAND LINE): Grant authority to access the queue manager. setmqaut -m MYQMGR -t qmgr -p myuser +connect +inq +dsp 2. MQ EXPLORER: Grant authority to the client channel to get the command server reply messages. setmqaut -m MYQMGR -t q -n SYSTEM.DEFAULT.MODEL.QUEUE -p myuser +inq +browse +get 3. MQ EXPLORER: Grant authority to put messages onto the command server input queue. setmqaut -m MYQMGR -t q -n SYSTEM.ADMIN.COMMAND.QUEUE -p myuser +inq +put 4. MQ EXPLORER: Grant authority to get the reply messages. setmqaut -m MYQMGR -t q -n SYSTEM.MQEXPLORER.REPLY.MODEL -p myuser +inq +browse +get +dsp. + Using -g flag (for a group):. Issue these setmqaut commands to grant minimal authority to the Unix group (using the GroupName flag: -g) 1. GENERAL (MQ EXPLORER and COMMAND LINE): Grant authority to access the queue manager. setmqaut -m MYQMGR -t qmgr -g mygroup +connect +inq +dsp 2. MQ EXPLORER: Grant authority to the client channel to get the command server reply messages. setmqaut -m MYQMGR -t q -n SYSTEM.DEFAULT.MODEL.QUEUE -g mygroup +inq +browse +get 3. MQ EXPLORER: Grant authority to put messages onto the command server input queue. setmqaut -m MYQMGR -t q -n SYSTEM.ADMIN.COMMAND.QUEUE -g mygroup +inq +put 4. MQ EXPLORER: Grant authority to get the reply messages. setmqaut -m MYQMGR -t q -n SYSTEM.MQEXPLORER.REPLY.MODEL -g mygroup +inq +browse +get +dsp.

7 Page 7 of 28 ADDITIONAL authorities are needed: The above 4 commands, just allow for the connection to happen. Once the user is connected, then it is necessary to provide additional authorities in order to do useful work, such as putting messages into a queue. The following command gives additional put/get authority for queue Q1. setmqaut -m MYQMGR -t q -n Q1 -p myuser +inq +browse +get +put +dsp The following command gives only the authority to display the names of the SYSTEM.* queues (otherwise, the user cannot view the system queues, via MQ Explorer, and errors are logged in the error log, one for each of the SYSTEM queues). Note: When using wildcard characters on UNIX and Linux systems, you must enclose the profile name in quotation marks. Windows: setmqaut -m MYQMGR -t q -n SYSTEM.** -p myuser +dsp Unix: setmqaut -m MYQMGR -t q -n 'SYSTEM.**' -p myuser +dsp. The following command gives to the user "myuser" only the authority to display the names of the queues (otherwise, the user cannot view the queues, such as Q1, via MQ Explorer, and errors are logged in the error log, one for each queue). Note: When using wildcard characters on UNIX and Linux systems, you must enclose the profile name in quotation marks. Windows: setmqaut -m MYQMGR -t q -n ** -p myuser +dsp Unix: setmqaut -m MYQMGR -t q -n '**' -p myuser +dsp. Similarly for other objects, such as channels: Windows: setmqaut -m MYQMGR -t channel -n ** -p myuser +dsp Unix: setmqaut -m MYQMGR -t channel -n '**' -p myuser +dsp

8 Page 8 of Chapter 2: Usability: using 'quit' or 'exit' as synonym for 'end' New "exit" and "quit" synonyms for "end" There are some synonyms added to complete a runmqsc session: END, QUIT and EXIT can all be used. Different tools and scripting environments typically use one of these commands, and it was very common to enter the wrong exiting command in runmqsc.

9 Page 9 of Chapter 3: Non-administrators (not in the group 'mqm') can now use runmqsc The following quote from the MQ 8.0 Redbook provides a good introduction to this enhancement: Chapter 1. Introduction Section Usability Pages Administration with runmqsc program + begin quote A common requirement has been to permit users of MQ to at least look at the resources they are using, for example to see queue depths. This is especially useful for application developers who want to test their code without having full MQ admin rights. Rather than require the use of a program such as the MQ Explorer, the runmqsc program is now installed to be runnable by any user instead of being restricted to only the default MQ administrator groups. The operations executed by runmqsc are of course still checked for authorizations, so not everyone can define or delete queues, but this removes the need to do something like invoke the runmqsc program in a sudo command wrapper. + end quote In MQ 8.0, notice that the file permissions were changed: $ cd /opt/mqm/bin $ ls l runmqsc -r-xr-xr-x 1 mqm mqm Mar 04:46 runmqsc In contrast, a previous version of MQ had the following file permissions (the following is for MQ 7.5): $ cd /opt/mqm/bin $ ls -l runmqsc -r-sr-s--- 1 mqm mqm May 18 14:03 runmqsc

10 Page 10 of Scenarios: The user "fulano" exists in the host of the queue manager, but it is not a member of the group "mqm": id fulano uid=1006(fulano) gid=1005(mqusers) groups=1005(mqusers) + Scenario 1: user is local but not authorized yet At this moment, the user "fulano" and the group "mqusers" do NOT have any authorities with MQ, thus, any attempts to connect to the queue manager regardless of the method will fail with an authorization error: fulano@mosquito:~> runmqsc TEST_ H72 (C) Copyright IBM Corp. 1994, Starting MQSC for queue manager TEST_80. AMQ8135: Not authorized. No MQSC commands read. No commands have a syntax error. All valid MQSC commands were processed. The following entry is added to the error log of the queue manager: 06/11/ :41:27 AM - Process( ) User(rivera) Program(amqzlaa0) Host(mosquito) Installation(Installation3) VRMF( ) QMgr(TEST_80) AMQ8077: Entity 'fulano' has insufficient authority to access object 'TEST_80'. EXPLANATION: The specified entity is not authorized to access the required object. The following requested permissions are unauthorized: connect ACTION: Ensure that the correct level of authority has been set for this entity against the required object, or ensure that the entity is a member of a privileged group. Solution: The MQ Administrator can use the one of the following commands to allow the user to connect to the queue manager. Note: The flag-value pair "-t qmgr" refers to the object type of QueueManager. * Using -p flag (for a userid or principal) setmqaut -m TEST_80 -t qmgr -p fulano +connect +inq +dsp

11 Page 11 of 28 * Using -g flag (for a group): setmqaut -m TEST_80 -t qmgr -g mqusers +connect +inq +dsp Result: The start of runmqsc was successful and does not terminate with an error. Instead is just waiting for the user to enter a command. fulano@mosquito:~> runmqsc TEST_ H72 (C) Copyright IBM Corp. 1994, Starting MQSC for queue manager TEST_80. + Scenario 2: user can connect, needs to see current depth in queue Q1 This is a continuation of Scenario 1. Now that the user "fulano" is allowed to connect to the queue manager, the user wants to see the current depth for queue Q1, that is, how many messages are in the queue. fulano@mosquito:~> runmqsc TEST_ H72 (C) Copyright IBM Corp. 1994, Starting MQSC for queue manager TEST_80. display queue(q1) 1 : display queue(q1) curdepth AMQ8135: Not authorized. AMQ8147: WebSphere MQ object Q1 not found. The following entry is added to the error log of the queue manager: AMQ8077: Entity 'fulano' has insufficient authority to access object 'Q1'. EXPLANATION: The specified entity is not authorized to access the required object. The following requested permissions are unauthorized: dsp Solution: The MQ Administrator can use the one of the following commands to allow the user to display and inquire the attributes of a queue, and to browse messages: Note: The flag-value pair "t q" refers to the object type of Queue. * Using -p flag (for a userid or principal) setmqaut -m TEST_80 -t q -n Q1 -p fulano +dsp +inq +browse

12 Page 12 of 28 * Using -g flag (for a group): setmqaut -m TEST_80 -t q -n Q1 -g mqusers +dsp +inq +browse Result: There is no need to exit runmqsc and restart it. Continuing from the current session with runmqsc, just retype the command: runmqsc TEST_80 : display queue(q1) curdepth 3 : display queue(q1) curdepth AMQ8409: Display Queue details. QUEUE(Q1) TYPE(QLOCAL) CURDEPTH(0) Notice that this time the attempt was successful! + Scenario 3: User is not local See Chapter 5: Scenario 2: User 'fulano' from host1 tries to access queue manager in host2, using -u flag to provide password Setup the MQSERVER or the variables that have the CCDT file. Specify the -u flag and then enter the password: $ runmqsc -c -u fulano TEST_ H72 (C) Copyright IBM Corp. 1994, Enter password: ********

13 Page 13 of 28 + Scenario 4: Detailed scenario of remote user who is not an MQ administrator In MQ 8, the tool runmqsc is shipped in the common 'runtime' fileset, that is, it is available in both the Server and the Client installation images. To download the MQ V8 Client code, which is a free download and includes already both the base code plus the latest fix pack, visit: MQC8: WebSphere MQ V8 Clients You will see a table at the lower part of the web page, which will have the links for the desired version to download. I used an MQ 8.0 runmqsc that was installed in host-1, and it worked remotely with an MQ 7.5 queue manager (name QM75RHEL1 ) and an MQ 8.0 queue manager (name QM80RHEL1) in host-2. I used an MQ Administrator, and a non-mq administrator, as the users of runmqsc in remote access mode. Here are the conditions that I found were needed for a non-mq administrator to use remote runmqsc to either of these queue managers. I am using the specific example for the MQ 7.5 queue manager in the following comments: - The userid from both the client host and the server host must exist with the same name. In my case, it was userid "fulano" in both hosts (not a member of the group "mqm") $ id fulano uid=1021(fulano) gid=1005(mqusers) groups=1005(mqusers) - With an MQ administrator login, I gave the user fulano the following standard authorities in order for this user to use MQ Explorer (these are nothing new, they come all the way from MQ 6.0): setmqaut -m QM75RHEL1 -t qmgr -p fulano +connect +inq +dsp setmqaut -m QM75RHEL1 -t q -n SYSTEM.DEFAULT.MODEL.QUEUE -p fulano +inq +browse +get +dsp setmqaut -m QM75RHEL1 -t q -n SYSTEM.ADMIN.COMMAND.QUEUE -p fulano +inq +put +dsp setmqaut -m QM75RHEL1 -t q -n SYSTEM.MQEXPLORER.REPLY.MODEL -p fulano +inq +browse +get +dsp - For illustration purposes, the userid was given access ONLY to this non-system queue: Q1 (that is no access to Q2) setmqaut -m QM75RHEL1 -t q -n Q1 -p fulano +inq +browse +get +put +dsp

14 Page 14 of 28 - Thru trial and error, I found that the userid needed authority to another system queue (This queue is mentioned in the runmqsc article in he MQ 8.0 Knowledge Center - although there is no example of using setmqaut to give authority to other users): setmqaut -m QM75RHEL1 -t q -n SYSTEM.MQSC.REPLY.QUEUE -p fulano +inq +get +browse +dsp This is what I did to test it: - I logged in as user "fulano" in host-1 - Specified the environment: setmqenv for MQ Setup MQSERVER for the MQ 7.5 in host-2 $ export MQSERVER="SYSTEM.ADMIN.SVRCONN/TCP/ (1421)" - Issued runmqsc as follows. I provided the password for the user when prompted. NOTES: a) The password is for the userid fulano in host-2, which is where the target queue manager is located. b) Notice It is MQ 8.0 runmqsc accessing an MQ 7.5 queue manager: $ runmqsc -c -u fulano QM75RHEL H72 (C) Copyright IBM Corp. 1994, Enter password: # Editorial note: User fulano has access to Q1 - result is OK display QL(Q1) curdepth 2 : display QL(Q1) curdepth AMQ8409: Display Queue details. QUEUE(Q1) TYPE(QLOCAL) CURDEPTH(0) # Editorial note: User fulano does NOT have access to Q2 - result is failure with 2035 display QL(Q2) curdepth 5 : display QL(Q2) curdepth AMQ8135: Not authorized.. # Editorial note: User fulano does NOT have access to create queues - result is failure with 2035 define QL(Q3) 6 : define QL(Q3) AMQ8135: Not authorized.

15 Page 15 of Chapter 4: Flag -u to allow authentication The following quote from the MQ 8.0 Redbook provides a good introduction to this enhancement: Chapter 3. User authentication Section: 3.11 Using authentication in programs provided by MQ Page 43 + begin quote Administration programs Essential administration programs were also updated to work with user IDs and passwords. This is needed because of the possibility of setting CHCKLOCL to REQUIRED or REQDADM; without a user ID option, even runmqsc fails to connect. Commands that were modified include runmqsc, runmqdlq, dspmqrte, dmpmqcfg, and runmqtrm. These all can take a -u user ID option on the command line, and they expect to read a password as the first line of input. The various authority control commands such as setmqaut were not extended, because the same operations can be done directly from runmqsc, for example by using the SET AUTHREC commands. + end quote The following is from the MQ Knowledge Center: -u UserID Primarily expected to be used for client connections (with -c), but also applicable to authentication in local queue manager mode. If you use the -u parameter to supply a user ID, you are prompted for a matching password. If you have configured the CONNAUTH AUTHINFO record with CHCKLOCL(REQUIRED) or CHCKLOCL(REQDADM), you must use the -u parameter otherwise you will not be able to administer your queue manager with runmqsc.. runmqsc -c -u [email protected] MYQMGR Connects in client mode, but prompts for password and authenticates provided credentials Note: Chapter 5 in this techdoc explores in depth the scenario with the -c flag.

16 Page 16 of Example of dmpmqcfg using remote connection An example of dmqmcfg en 8.0, from host-1 (Windows) talking to a queue manager in host- 2 (Linux) exploitint the remote connection: set MQSERVER=channel/tcp/hostname(1414) Notice that the keyword "-c default" is specified: dmpmqcfg -m QM_80 -u mqm -c default Enter password: (I entered the password) output of dmpmqcfg ++ Scenarios + Scenario 1: user is authorized, but enters wrong password The -u flag is specified and therefore, runmqsc asks for a password. The MQ Administrator is in a hurry and makes a mistake in typing the password. $ runmqsc -u mqm TEST_ H72 (C) Copyright IBM Corp. 1994, Enter password: *********** Starting MQSC for queue manager TEST_80. AMQ8135: Not authorized. No MQSC commands read. No commands have a syntax error. All valid MQSC commands were processed. The following entries are made in the error log: 06/11/ :27:36 PM - Process( ) User(rivera) Program(amqzlaa0) Host(mosquito) Installation(Installation3) VRMF( ) QMgr(TEST_80) AMQ5534: User ID 'mqm' authentication failed EXPLANATION: The user ID and password supplied by 'runmqsc' could not be authenticated. ACTION: Ensure that the correct user ID and password are provided by the application. Ensure that the authentication repository is correctly configured. Look at previous error messages for any additional information.

17 Page 17 of amqzfuca.c : /11/ :27:36 PM - Process( ) User(rivera) Program(amqzlaa0) Host(mosquito) Installation(Installation3) VRMF( ) QMgr(TEST_80) AMQ5542: The failed authentication check was caused by the queue manager CONNAUTH CHCKLOCL(OPTIONAL) configuration. EXPLANATION: The user ID 'mqm' and its password were checked because the queue manager connection authority (CONNAUTH) configuration refers to an authentication information (AUTHINFO) object named 'SYSTEM.DEFAULT.AUTHINFO.IDPWOS' with CHCKLOCL(OPTIONAL). This message accompanies a previous error to clarify the reason for the user ID and password check. ACTION: Refer to the previous error for more information. + Scenario 2: user is authorized and enters correct password This is a continuation of Scenario 1 from this Chapter. $ runmqsc -u mqm TEST_ H72 (C) Copyright IBM Corp. 1994, Enter password: ******** Starting MQSC for queue manager TEST_80. Notice that no errors were generated. + Scenario 3: user is not authorized The userid 'mengano' is local but is not authorized. The -u flag is specified and therefore, runmqsc asks for a password: $ runmqsc -u mengano TEST_ H72 (C) Copyright IBM Corp. 1994, Enter password: ******** Starting MQSC for queue manager TEST_80. AMQ8135: Not authorized. No MQSC commands read. No commands have a syntax error.

18 All valid MQSC commands were processed. Page 18 of 28 Result: If the user is not authorized, the following message will be shown inside runmqsc: AMQ8135: Not authorized.... and the following 2 entries are added to the queue manage error log: 06/11/ :19:41 PM - Process( ) User(rivera) Program(amqzlaa0) Host(mosquito) Installation(Installation3) VRMF( ) QMgr(TEST_80) AMQ5534: User ID 'mengano' authentication failed EXPLANATION: The user ID and password supplied by 'runmqsc' could not be authenticated. AMQ5542: The failed authentication check was caused by the queue manager CONNAUTH CHCKLOCL(OPTIONAL) configuration. EXPLANATION: The user ID 'mengano' and its password were checked because the queue manager connection authority (CONNAUTH) configuration refers to an authentication information (AUTHINFO) object named 'SYSTEM.DEFAULT.AUTHINFO.IDPWOS' with CHCKLOCL(OPTIONAL). ++ Scenario 4: Piping password from a file If the u flag is given, then a password is requested by runmqsc Note that the password is read from standard input (stdin) so that it can be redirected from a file if necessary. If you also use scripts piped into runmqsc, then you can group commands to avoid having to put the password in the same script as the MQSC commands. An insecure example for UNIX is as follows: (echo passw0rd; cat commands.mqsc) runmqsc -u mqadmin QM1 To avoid typing the password directly into the console, you could have the password in a file and then use 'cat' in Unix or "type' in Windows to concatenate / pipe the files: Unix: (cat password.stash ; cat script.mqsc) runmqsc u userid QM1 Windows: (type password.stash & type script.mqsc) runmqsc u userid QM1 Example in Windows:

19 Page 19 of 28 C:\temp\mq> type password.stash passw0rd C:\temp\mq> type script.mqsc display qmgr C:\temp\mq> (type password.stash & type script.mqsc) passw0rd display qmgr C:\temp\mq> (type password.stash & type script.mqsc) runmqsc -u user1 QM H72 (C) Copyright IBM Corp. 1994, Enter password: Starting MQSC for queue manager QM1 1 : display qmgr AMQ8408: Display Queue Manager details. QMNAME(QM1) ACCTCONO(DISABLED)...

20 Page 20 of Chapter 5: Flag -c to allow remote access through a client connection MQ V8 has new optional parameters for runmqsc to allow remote access through a client connection, and it is also known as "Client MQSC". The "Client MQSC" is a modification of the existing runmqsc executable to provide clientside MQ administration tooling. It is essentially a replacement for the popular MO72 SupportPac: MO72: MQSC Client for WebSphere MQ It has a wider platform coverage (Full set of MQ 8.0 distributed platforms IBM i, HP-NSS). It is part of the product, instead of being just a SupportPac, so it is less problematic for users to install and maintain. It is shipped in the common 'runtime' fileset. For example, in Linux, the following command shows which is the fileset that provides a particular file installed in the system: $ rpm -qf /opt/mqm/bin/runmqsc MQSeriesRuntime This option requires the client to be installed. If it is not installed an error message reporting the missing client libraries is issued. The client channel definitions used to connect to the queue manager are located using the following environment variables in this order of precedence: MQSERVER MQCHLLIB and MQCHLTAB. The tool waits by default for 30 seconds for the command server of the remote queue manager to put response messages. It is similar to queued mode (-w) but via a direct client connection to the queue manager rather than over channels between queue managers. Generic examples: runmqsc -c MYQMGR Connects to a remote queue manager MYQMGR using client connection sequence Waits by default for 30 seconds for command server to put response messages runmqsc -c -w 60 MYQMGR

21 Page 21 of 28 Connects in client mode, but waits 60 seconds for command server responses ++ Scenarios + Scenario 1: User 'mqm' from host1 tries to access queue manager in host2 Server channel to use: SYSTEM.ADMIN.SVRCONN $ export MQSERVER='SYSTEM.ADMIN.SVRCONN/TCP/mosquito.x(1419)' mqm@host1:~> runmqsc -c TEST_ H72 (C) Copyright IBM Corp. 1994, Starting MQSC for queue manager TEST_80. AMQ8135: Not authorized. 0 command responses received. The following entries are added to the error log of the queue manager: 06/11/ :02:53 PM - Process( ) User(rivera) Program(amqzlaa0) Host(mosquito) Installation(Installation3) VRMF( ) QMgr(TEST_80) AMQ5540: Application 'runmqsc' did not supply a user ID and password EXPLANATION: The queue manager is configured to require a user ID and password, but none was supplied. ACTION: Ensure that the application provides a valid user ID and password, or change the queue manager configuration to OPTIONAL to allow applications to connect which have not supplied a user ID and password amqzfuca.c : /11/ :02:53 PM - Process( ) User(rivera) Program(amqzlaa0) Host(mosquito) Installation(Installation3) VRMF( ) QMgr(TEST_80) AMQ5541: The failed authentication check was caused by the queue manager CONNAUTH CHCKCLNT(REQDADM) configuration. EXPLANATION: The user ID 'mqm' and its password were checked because the user ID is privileged and the queue manager connection authority (CONNAUTH) configuration refers to an authentication information (AUTHINFO) object named 'SYSTEM.DEFAULT.AUTHINFO.IDPWOS' with CHCKCLNT(REQDADM).

22 Page 22 of 28 + Scenario 2: User 'mqm' from host1 tries to access queue manager in host2, using -u flag to provide password Solution: In this case it is necessary to specify the -u flag and then enter the password: $ runmqsc -c -u mqm TEST_ H72 (C) Copyright IBM Corp. 1994, Enter password: ******** Starting MQSC for queue manager TEST_80. AMQ8135: Not authorized. 0 command responses received. Result: Hum! This time another security error was issued: 06/11/ :36:50 PM - Process( ) User(rivera) Program(amqrmppa) Host(mosquito) Installation(Installation3) VRMF( ) QMgr(TEST_80) AMQ9776: Channel was blocked by userid EXPLANATION: The inbound channel 'SYSTEM.ADMIN.SVRCONN' was blocked from address ' ' because the active values of the channel were mapped to a userid which should be blocked. The active values of the channel were 'MCAUSER(mqm) CLNTUSER(mqm) ADDRESS(localhost)'. ACTION: Contact the systems administrator, who should examine the channel authentication records to ensure that the correct settings have been configured. The ALTER QMGR CHLAUTH switch is used to control whether channel authentication records are used. The command DISPLAY CHLAUTH can be used to query the channel authentication records. Solution: Starting with MQ 7.1, a new security feature was introduced: channel authentication records. The default behavior is that MQ administrators are blocked from doing a remote access. For more information on the errors and the workarounds see:

23 Page 23 of 28 WMQ 7.1, 7.5, 8.0 queue manager RC 2035 MQRC_NOT_AUTHORIZED or AMQ4036 when using client connection as an MQ Administrator Summary: The MQ administrator needs to locally access the queue manager and run the following 2 runmqsc commands to allow an MQ Administrator to remotely login to the queue manager: SET CHLAUTH(*) TYPE(BLOCKUSER) USERLIST('nobody','*MQADMIN') SET CHLAUTH(SYSTEM.ADMIN.*) TYPE(BLOCKUSER) USERLIST('nobody') Result: Now the MQ administrator is able to successfully connect to the queue manager mqm@mosquito:~> runmqsc -c -u mqm TEST_ H72 (C) Copyright IBM Corp. 1994, Enter password: ******** Starting MQSC for queue manager TEST_80.

24 Page 24 of Chapter 6: Flag -n to allow the modification of a local CCDT file MQ V8 has a new optional parameter for runmqsc to allow the modification of a local CCDT file. When the -n flag specified, it modifies the runmqsc command to not connect to a queue manager. If this parameter is specified, all other command parameters must be omitted, otherwise an error message is issued. This option requires the client libraries to be installed. If they are not installed an error message is issued. MQSC commands entered in this mode are limited to managing the local channel definition file (CCDT), which is located through the MQCHLLIB and MQCHLTAB environment variables, or the default values if not defined. Clarification Notes: - If you add new entries into the local channel definition file, or alter existing entries, these changes will NOT be reflected inside the queue manager. The queue manager does NOT read the contents of the local channel definition file. - The CCDT file is a write-only file from the perspective of the queue manager. The queue manager does NOT read the contents of the CCDT file. Only the following MQSC commands are recognized: ALTER, DEFINE, DELETE, DISPLAY AUTHINFO (Only of type CRLLDAP or OCSP) ALTER, DEFINE, DELETE, DISPLAY CHANNEL (Only of type CLNTCONN) END, EXIT, QUIT For the AUTHINFO management commands, the names of existing AUTHINFO definitions are mapped and addressed using the names CRLLDAPn or OCSPn (according to type), where n is the numeric order in which they appear in the channel definition file. New AUTHINFO definitions are appended to the client channel table in order. For example, if the following commands are issued: DEFINE AUTHINFO(XYZ) AUTHTYPE(CRLLDAP) CONNAME('xyz') DEFINE AUTHINFO(ABC) AUTHTYPE(CRLLDAP) CONNAME('abc') This results in the 'xyz' LDAP server being checked for a CRL first, if that CRL server is unavailable then the 'abc' server is checked. issuing the DISPLAY AUTHINFO(*) CONNAME command shows this: AMQ8566: Display authentication information details.

25 Page 25 of 28 AUTHINFO(CRLLDAP1) AUTHTYPE(CRLLDAP) CONNAME(xyz) AMQ8566: Display authentication information details. AUTHINFO(CRLLDAP2) AUTHTYPE(CRLLDAP) CONNAME(abc). Note: The client mode only supports inserting new entries at the end of the client channel table. If you want to change the order of precedence of the CRL LDAP servers, you must remove the existing objects from the list and reinsert them in the correct order at the end. + Generic example: Connects in local mode to define channels/authinfo objects in the CCDT Unix: export MQCHLLIB=...(directory of CCDT) export MQCHLTAB=...(name of CCDT file) runmqsc -n Windows set MQCHLLIB=...(directory of CCDT) set MQCHLTAB=...(name of CCDT file) runmqsc -n + Specific example: Assuming that the CCDT file is located at: C:\temp\mq\CCDT1.TAB We need to setup both variables for the CCDT directory and file name. The MQCHLTAB is needed if the file name is not "AMQCLCHL.TAB" Windows: set MQCHLLIB=C:\temp\mq\ set MQCHLTAB=CCDT1.TAB Issue the runmqsc command with the flag -n as follows: runmqsc -n # Let's see how many channels are inside the file. Answer: 2 display channel(*) 1 : display channel(*) AMQ8414: Display Channel details. CHANNEL(SSL.SVRCONN) CHLTYPE(CLNTCONN)

26 Page 26 of 28 AMQ8414: Display Channel details. CHANNEL(SYSTEM.DEF.CLNTCONN). CHLTYPE(CLNTCONN) # A CCDT file always have at least one channel: SYSTEM.DEF.CLNTCONN # It is the default, but causes confusion. Do not use.. # Let's get all the details for the non-default one: display CHANNEL(SSL.SVRCONN) all 2 : display CHANNEL(SSL.SVRCONN) all AMQ8414: Display Channel details. CHANNEL(SSL.SVRCONN) CHLTYPE(CLNTCONN) AFFINITY(PREFERRED) CERTLABL( ) CLNTWGHT(0) COMPHDR(NONE) COMPMSG(NONE) CONNAME(host2.xxx.com(1414)) DEFRECON(NO) DESCR( ) HBINT(300) KAINT(AUTO) LOCLADDR( ) MAXMSGL( ) MODENAME( ) PASSWORD( ) QMNAME(QM1) RCVDATA( ) RCVEXIT( ) SCYDATA( ) SCYEXIT( ) SENDDATA( ) SENDEXIT( ) SHARECNV(10) SSLCIPH(TLS_RSA_WITH_AES_128_CBC_SHA) SSLPEER( ) TPNAME( ) TRPTYPE(TCP) USERID( ) # Let's try the AUTHINFO: There are none in this example. DISPLAY AUTHINFO(*) 3 : DISPLAY AUTHINFO(*) AMQ8147: WebSphere MQ object not found. Summary: The channel SSL.SVRCONN is described in this CCDT file.

27 Page 27 of Clarification that "runmqsc -n" does not work with the objects stored within the queue manager + runmqsc in normal mode (via queue manager) When you use runmqsc in normal mode or MQ Explorer to define a client-connection channel, there are 2 actions that take place: 1: Client-connection channel is added to the list of channels known to the queue manager Thus, these channels will be displayed when doing: display channel(*) 2: A new entry is added to the Client Channel Definition Table (CCDT) of the queue manager. runmqsc => queue manager internal objects => CCDT + runmqsc -n (bypassing the queue manager, using the CCDT directly) 1: (No action within the queue manager) Because the queue manager is NOT involved, there is NO new entry into the objects that are known to the queue manager. Thus, the queue manager does NOT know about the new objects (or changed objects) 2: A new entry is added to the Client Channel Definition Table (CCDT) pointed by the environment variables. runmqsc -n => CCDT + WARNING: It might be possible for the CCDT file and the list of client-connection channels within the queue manager to be out of sync. The following steps show such scenario: a: Queue manager is created. Client-connection channels in queue manager: 1 (SYSTEM.DEF.CLNTCONN ) CCDT file: 1 (SYSTEM.DEF.CLCNT) b: MQ Explorer or normal runmqsc is used to create a new client-connection channel: CLIENT1. This is added in both places. Client-connection channels in queue manager: 2 (SYSTEM.DEF.CLNTCONN, CLIENT1) CCDT file: 2 (SYSTEM.DEF.CLNTCONN, CLIENT1) Note: Up to now, both are in sync. c: runmqsc -n is used to add a new client-connection channel: CLIENT2 This is added ONLY into the CCDT file. The queue manager is NOT affected.

28 Page 28 of 28 Client-connection channels in queue manager: 2 (SYSTEM.DEF.CLNTCONN, CLIENT1) CCDT file: 3 (SYSTEM.DEF.CLNTCONN, CLIENT1, CLIENT2) Note: Now, both are out of sync. d: MQ Explorer or normal runmqsc is used to create a new client-connection channel: CLIENT3. This is added in both places. Client-connection channels in queue manager: 3 (SYSTEM.DEF.CLNTCONN, CLIENT1, CLIENT3) CCDT file: 4 (SYSTEM.DEF.CLNTCONN, CLIENT1, CLIENT2, CLIENT3) As you can see, the contents of the queue manager with respect to client-connection channels and the contents of the CCDT are out of sync. +++ end