I’m here going to show you how I setup a small environment for the MQWEB REST API, mainly to try it out. It is actually not much to be done to get this up and running

First choose the security settings. For this IBM provide us with four sample configurations (/<installation path>/mqserver/web/mq/samp/configuration/):

basic_registry.xml  
ldap_registry.xml  
local_os_registry.xml
no_security.xml  

Out of these I’m going to choose local_os_registry.xml because it uses the groups and users already setup on the OS. This saves me from setting up new groups and users somewhere else

Copy desired configuration to MQWEB server settings

cp local_os_registry.xml /var/mqm/web/installations/<installation name>/servers/mqweb/mqwebuser.xml 

Start MQWEB server

strmqweb

That is pretty much it. Time to test

Put message on queue

curl -k -X POST -d 'helloworld' -u user:password -H "ibm-mq-rest-csrf-token: nothing" -H "Content-Type: text/plain"  https://localhost:9443/ibmmq/rest/v1/messaging/qmgr/MYQM01/queue/MYQUEUE/message

Here I feel we need some explaining:
-k: The default SSL certificate on the MQWEB server is self-signed. This option ignores that
-X POST: Use POST for putting messages onto MQ
-d: This is the data (string) that eventually will land on the queue
-u: The OS user and password (part of the mqm group in this example)
-H: The “ibm-mq-rest-csrf-token” needs to exist as a header but can contain anything, can even be completely blank
-H: We need to set a content type for the payload (from the -d option above). Valid content types include:

text/plain;charset=utf-8
text/html;charset=utf-8
text/xml;charset=utf-8
application/json;charset=utf-8
application/xml;charset=utf-8

NOTE: if omitting the charset, utf-8 is assumed
URL: Default URL and port: host:9443/ibmmq/rest/v1/. On top of this we add the default URL for handling messages on queues: /messaging/qmgr/<queue manager name>/queue/<queue name>/message

Get messages from queue

curl -k -X DELETE -u user:password -H "ibm-mq-rest-csrf-token: nothing" https://localhost:9443/ibmmq/rest/v1/messaging/qmgr/MYQM01/queue/MYQUEUE/message

Here I believe that I only need to explain one option:
-X DELETE: When fetching messages from MQ we use the REST DELETE operation

Done!

A couple of useful commands:

 
# Stop IBM MQ REST SERVER
endmqweb

# Show status of MQWEB (will also show the base URL for MQWEB REST API)
dspmqweb

Tested on IBM MQ 9.0.5.0 and Red Hat Linux 7.5 with curl 7.29.0

There is a lot of texts and pictures out there talking about topic trees but I have had a hard time finding any complete examples, so to better get a grip on what topic trees are and how I can use them I created this small example.

Goal: To be able to subscribe to multiple topics of similar entity types using only one subscription

Let’s get right into the tree building. I’m here going to use the runmqsc program but you can use MQExplorer if you like a GUI

DEFINE TOPIC(PRICES) TOPICSTR('/prices')
DEFINE TOPIC(FRUITS) TOPICSTR('/prices/fruits')
DEFINE TOPIC(APPLE)  TOPICSTR('/prices/fruit/apple')
DEFINE TOPIC(ORANGE) TOPICSTR('/prices/fruit/orange')
DEFINE TOPIC(TOYS)   TOPICSTR('/prices/toys')
DEFINE TOPIC(PUZZLE) TOPICSTR('/prices/toys/puzzle')
DEFINE TOPIC(CUBE)   TOPICSTR('/prices/toys/cube')

These commands will give you a tree looking like this

                     prices
                    /      \
               fruits       toys
              /     \      /    \
          orange  apple  cube  puzzle

And now I’m going to try to show the “magic” this brings

Tests
A. Subscribe to TOPICSTR(‘/prices/#’) will get you ALL messages published on ANY topic string in this tree
B. Subscribe to TOPICSTR(‘/prices/toys/#’) will get you messages published on ‘/prices/toys’, ‘/prices/toys/cube’ and ‘/prices/toys/puzzle’. No other
C. Subscribe to TOPICSTR(‘/prices/fruit/orange/#’) will get you messages published on ‘/prices/fruit/orange’ only. No other

Pure magic!

Tested on IBM MQ v9.0.5.0 on Red Hat Linux 7.5

In my line of work this is quite common task. I’ll place it here to be able to point new colleagues to it when I get tired of explaining 🙂
I’m here going to use the runmqsc and ikeycmd, both shipped with MQ from 8 and up, and the keytool program that can be found in most java distributions. MQExplorer and ikeyman could also be used if you like a GUI better

Add client to OS

useradd client43

Set a password and we are done with the OS part

Now create client channel in MQ (runmqsc MYQM01)

DEFINE CHANNEL(CLIENT43) CHLTYPE(SVRCONN) SSLCIPH(TLS_RSA_WITH_AES_128_CBC_SHA) MCAUSER('client43') 

Two things to note here:
* MCAUSER: this is the OS user that is going to use the channel. In this case ‘client43’ that we created in the beginning
* SSLCIPH: this cipher has to match the one used in the client. NOTE! Cipher names can differ between Java and MQ. Search IBM website for translation tables between cipher names

Set connection access to the new client

 
setmqaut -m MYQM01 -t qmgr -p client43 -all +connect +inq

Set object access to the new client (eg. PUT and GET rights for a local queue)

setmqaut -m MYQM01 -t queue -n QL.MY.CLIENTS.NEW.QUEUE -p client43 -all +put +get
...

Add client certificate to MQ certificate store

ikeycmd -cert -add -db "/var/mqm/qmgrs/MYQM01/ssl/key.kdb" -pw changeit -label ibmwebspheremqclient43 -file ibmwebspheremqclient43.crt -format ascii  

NOTE: The default naming convention for client certificates is: ibmwebspheremq + user name. In this example it turns out to: ibmwebspheremqclient43

NOTE 2: If you are using a self-signed certificate you only need to add that certificate to the MQ certificate store BUT if you are using a CA signed client certificate ALL certificates need to be put into the MQ certificate store in order from root to client certificate. The whole certificate chain needs to be present for the client certificate to be resolved correctly by MQ

Add server certificate to the client.jks

keytool -import -alias ibmwebspheremqmyqm01 -file ibmwebspheremqmyqm01.crt -keystore client.jks

NOTE: You can use whatever label you want here. I use the default MQ naming pattern for anything relating to IBM MQ

Done!

Troubleshooting tips

# Test auth records towards client user 
DISPLAY CHLAUTH(CLIENT43) MATCH(RUNCHECK) ALL ADDRESS('127.0.0.1') CLNTUSER('client43')

# Check clients authentication records on the queue manager
dmpmqaut -m MYQM01 -p client43

# View certificate labels in jks 
keytool -list -keystore client.jks -storepass changeit

# View certificate labels in kdb
ikeycmd -cert -list ca -db key.kdb -pw changeit

Tested on MQ 9.0.5.0, Java 1.8.0_121 and Red Hat Linux 7.5