Configuring the IBM MQ server connection channel

To send messages between IBM® MQ and Eclipse Amlen, you must configure a server connection channel.

This task details the steps that are required to configure the IBM MQ server connection channel on distributed platforms. For more information about how to configure the server connection channel on z/OS®, see Configuring the IBM MQ server connection channel on z/OS.

You can use an existing server connection channel, but a new channel provides the following benefits:

Active Eclipse Amlen channels can be easily identified on the IBM MQ queue manager.
The connection between Eclipse Amlen and IBM MQ can be explicitly secured.
CHLAUTH records can be created to map the user ID of the Eclipse Amlen requests to an appropriate user ID on the IBM MQ system.

These steps take place on the IBM MQ system.

Create a server-connection channel for the queue manager, by using the DEFINE CHANNEL MQSC command:
- To create a server-connection channel for an unsecured Eclipse Amlen connection:
  runmqsc qmgrName
  DEFINE CHANNEL(channelName) CHLTYPE(SVRCONN) TRPTYPE(TCP)
- To create a server-connection channel for an SSL secured Eclipse Amlen connection:
  runmqsc qmgrName
  DEFINE CHANNEL(channelName) CHLTYPE(SVRCONN) TRPTYPE(TCP) SSLCIPH(SSLCipherSpec)
Note: When you create the server-connection channel, ensure that you specify a value of at least 1 for the SHARECNV parameter.
Eclipse Amlen uses the server-connection channel to connect to IBM MQ.
For more information about the DEFINE CHANNEL command and the options available, including the valid values of SSLCipherSpec, see DEFINE CHANNEL in the IBM MQ documentation.
Make a note of the server-connection channel name, and which queue manager the channel is associated with. If applicable, make a note of the SSLCipherSpec value used.

The name of the server-connection channel is used when you create a queue manager connection by using either the Amlen WebUI, or the Eclipse Amlen REST Administration APIs. The name is also used when you authorize Eclipse Amlen to connect to IBM MQ.
If you are not using an existing listener definition, then define and start a listener on the queue manager by using the DEFINE LISTENER MQSC command:
runmqsc qmgrName
DEFINE LISTENER (listenerName) TRPTYPE(TCP) CONTROL(QMGR) PORT(portNumber)
START LISTENER (listenerName)
The listener enables the server to detect incoming network requests from Eclipse Amlen. Each queue manager on the same system must listen on a different port number.
For more information about the DEFINE LISTENER MQSC command and the options available, see DEFINE LISTENER in the IBM MQ documentation.
Make a note of the port number of the listener, and which queue manager the listener is associated with.
If you are using an SSL connection, you must configure Eclipse Amlen security by creating key repositories and certificates:
- For a step-by-step guide to configuring Eclipse Amlen security by using self-signed certificates, see Configuring MQ Connectivity security by using self-signed certificates.
- For a step-by-step guide to configuring Eclipse Amlen security by using CA certificates, see Configuring MQ Connectivity security by using CA certificates.

By default, Eclipse Amlen attempts to connect to IBM MQ by using the user ID admin. You can make the connection more secure. The following steps use a CHLAUTH rule to secure the server connection channel. The steps also map the Eclipse Amlen user ID to a user ID on the IBM MQ system:

Authorize Eclipse Amlen to connect securely to the IBM MQ queue manager:
1. Obtain a user ID on the system your queue manager is running on. The user ID must not be a privileged administrative user. This user ID is the authority under which Eclipse Amlen runs on the queue manager.
2. Create a channel authentication record for each Eclipse Amlen IP address. Each channel authentication record must allow only the Eclipse Amlen server IP address to use the server-connection channel that was created to connect IBM MQ and Eclipse Amlen:
  runmqsc qmgrName
  SET CHLAUTH(ChannelName) TYPE(ADDRESSMAP) ADDRESS(IPAddress) MCAUSER('userIDcreatedInStepa')
  Where:
  
  ChannelName
  
  Specifies the server-connection channel name that was created to connect IBM MQ and Eclipse Amlen.
  
  IPAddress
  
  Specifies the IP address of Eclipse Amlen.
  
  userIDcreatedInStepa
  
  Specifies the user ID created in step a that is the authority under which Eclipse Amlen runs on the queue manager.
3. Grant general IBM MQ access to the Eclipse Amlen user ID created in step a:
  runmqsc qmgrName
  SET AUTHREC OBJTYPE(QMGR) PRINCIPAL('userIDcreatedInStepa') AUTHADD(CONNECT, INQ, DSP)
  Where:
  
  userIDcreatedInStepa
  
  Specifies the user ID created in step a that is the authority under which Eclipse Amlen runs on the queue manager.
4. Grant authority for the user ID created in step a to issue requests to IBM MQ:
  runmqsc qmgrName
  SET AUTHREC PROFILE('SYSTEM.DEFAULT.MODEL.QUEUE') OBJTYPE(QUEUE) PRINCIPAL('userIDcreatedInStepa') AUTHADD(DSP, GET)
  SET AUTHREC PROFILE('SYSTEM.ADMIN.COMMAND.QUEUE') OBJTYPE(QUEUE) PRINCIPAL('userIDcreatedInStepa') AUTHADD(DSP, PUT)
  Where:
  
  userIDcreatedInStepa
  
  Specifies the user ID created in step a that is the authority under which Eclipse Amlen runs on the queue manager.
5. Grant authority for the user ID created in step a to create a IBM MQ queue for Eclipse Amlen synchronization records.
  To synchronize the transfer of messages between Eclipse Amlen and IBM MQ, a queue is created with a name that starts SYSTEM.IMA. This queue is used to store messages as they are transferred between Eclipse Amlen and IBM MQ.
  runmqsc qmgrName
  SET AUTHREC PROFILE('SYSTEM.IMA.*') OBJTYPE(QUEUE) PRINCIPAL('userIDcreatedInStepa') AUTHADD(CRT, PUT, GET, BROWSE)
  SET AUTHREC PROFILE('SYSTEM.DEFAULT.LOCAL.QUEUE') OBJTYPE(QUEUE) PRINCIPAL('userIDcreatedInStepa') AUTHADD(DSP)
  Where:
  
  userIDcreatedInStepa
  
  Specifies the user ID created in step a that is the authority under which Eclipse Amlen runs on the queue manager.
6. For each mapping rule that maps to or from a IBM MQ topic, you must create a topic object and grant specific authorities to it. For each mapping rule that maps to or from a IBM MQ queue, you must create the queue and grant specific authorities to it.
  - For queues, use the IBM MQ MQSC commands DEFINE QLOCAL and SET AUTHREC:
    runmqsc qmgrName
    DEFINE QLOCAL(queueName)
    SET AUTHREC PROFILE(queueName) OBJTYPE(QUEUE) PRINCIPAL('userIDcreatedInStepa') AUTHADD(authorization)
    Where:
    queueName
    
    Specifies the name of the IBM MQ queue.
    
    userIDcreatedInStepa
    
    Specifies the user ID created in step a that is the authority under which Eclipse Amlen runs on the queue manager.
    
    authorization
    
    Specifies the put and get authorities to give to the queue. This value can be one of the following values:
    
    PUT
    
    Grants put authority.
    
    This authority is needed when the destination of a destination mapping rule is a IBM MQ queue.
    
    GET
    
    Grants get authority.
    
    This authority is needed when the source of a destination mapping rule is a IBM MQ queue.
  - For topics, use the IBM MQ MQSC commands DEFINE TOPIC and SET AUTHREC:
    runmqsc qmgrName
    DEFINE TOPIC(topicObjectName) TOPICSTR(topicString)
    SET AUTHREC PROFILE(topicObjectName) OBJTYPE(TOPIC) PRINCIPAL('userIDcreatedInStepa') AUTHADD(authorization)
    Where:
    topicObjectName
    
    Specifies the name of the IBM MQ topic object.
    
    topicString
    
    Specifies the topic string that you want to set authorization for.
    
    userIDcreatedInStepa
    
    Specifies the user ID created in step a that is the authority under which Eclipse Amlen runs on the queue manager.
    
    authorization
    
    Specifies the publish and subscribe authorities to give to the topic. This value can be one of the following values:
    
    PUB, DSP
    
    Grants publish authority.
    
    The display (DSP) authority allows Eclipse Amlen to inquire about the attributes of the topic object. This authority is necessary for Eclipse Amlen to publish messages.
    
    SUB, CTRL
    
    Grants subscribe and control authority.
    
    The control (CTRL) authority allows Eclipse Amlen to delete the Eclipse Amlen subscriptions on IBM MQ. The authority to delete subscriptions is required when the Eclipse Amlen server is restarted.
  For more information about DEFINE TOPIC, DEFINE QLOCAL, and SET AUTHREC, see the IBM MQ documentation topics DEFINE QLOCAL, DEFINE TOPIC, and SET AUTHREC.
  Note: It is possible to get an MQRC_NOT_AUTHORIZED error when you attempt to publish or subscribe to a IBM MQ topic at or below a topic node that has a retained message. This error occurs after the queue manager is restarted. To resolve this problem, contact your IBM service representative about the IBM MQ APAR IV45712.
7. For each IBM MQ topic object that you create, you must decide what happens when a message cannot be delivered to a subscriber. For persistent messages, you must set the PMSGDLV attribute of the topic object. For non-persistent messages, you must set the NPMSGDLV attribute of the topic object. There are four possible values for these attributes:
  - ALLAVAIL
    
    The message is delivered to all subscribers that are able to receive it. No error is reported for any subscribers that do not receive the message. Therefore, the Eclipse Amlen server does not know whether some subscribers do not receive the message, and does not try to send the message again. If there is only one subscriber, and that subscriber cannot receive the message, then the message is discarded, even if it is a persistent message.
  - ALL
    
    The message must be delivered to all subscribers. If a message is not delivered, the corresponding destination mapping rule is disabled and rolls back any messages that are in transit. The mapping rule does not operate, but all the messages are stored on the server.
    
    When the destination mapping rule is disabled, the Amlen WebUI reports the reason as MQRC_PUBLICATION_FAILURE. This error typically occurs when there is a problem with the subscriber queue. The queue might be full, or the message might be larger than the MAXMSGL attribute of the queue.
  - ALLDUR
    
    The message must be delivered to all durable subscribers. If a durable subscriber is not available to receive the message, the corresponding destination mapping rule is disabled.
    
    When the destination mapping rule is disabled, the Amlen WebUI reports the reason as MQRC_PUBLICATION_FAILURE. This error typically occurs when there is a problem with the subscriber queue. The queue might be full, or the message might be larger than the MAXMSGL attribute of the queue.
  - ASPARENT
    
    The behavior of the topic object is defined by the parent topic.
  You can use the ALTER TOPIC MQSC command to set the attribute values. For more information, see ALTER TOPIC, in the IBM MQ v7.5 documentation.

If you are configuring connection between Eclipse Amlen and IBM MQ version 8.0, avoid authentication of Eclipse Amlen in IBM MQ:

Either use an unprivileged user ID, or amend the authentication configuration of the queue manager. You can amend the CHCKCLNT attribute in the CHLAUTH record. However, it is not recommended to allow general unauthenticated access to IBM MQ.

This example demonstrates the IBM MQ setup to allow messages to be forwarded from Eclipse Amlen to a IBM MQ topic MQROOT/LEVEL1. This example does not use a secure SSL connection.

Create a server-connection channel that is called SYSTEM.MSG.SVRCONN for QM1, by using the DEFINE CHANNEL MQSC command:
runmqsc QM1
DEFINE CHANNEL(SYSTEM.MSG.SVRCONN) CHLTYPE(SVRCONN) TRPTYPE(TCP)
The server-connection channel name is SYSTEM.MSG.SVRCONN, and it is associated with QM1.
Start a listener MSGLISTENER on port 1414 for queue manager QM1:
runmqsc QM1
DEFINE LISTENER (MSGLISTENER) TRPTYPE(TCP) CONTROL(QMGR) PORT(1414)
START LISTENER (MSGLISTENER)
The port number is 1414, and it is associated with QM1.
Authorize Eclipse Amlen to connect securely to the IBM MQ queue manager:
1. Obtain a user ID on the system QM1 is running on. In this example, the user ID MSG is used.
2. Create a channel authentication record that allows only the Eclipse Amlen IP address 192.0.2.1 to use the server-connection channel SYSTEM.MSG.SVRCONN:
  runmqsc QM1
  SET CHLAUTH(SYSTEM.MSG.SVRCONN) TYPE(ADDRESSMAP) ADDRESS(192.0.2.1) MCAUSER('MSG')
3. Grant general IBM MQ access to the user ID MSG:
  runmqsc QM1
  SET AUTHREC OBJTYPE(QMGR) PRINCIPAL('MSG') AUTHADD(CONNECT, INQ, DSP)
4. Grant authority for the user ID MSG to issue requests to IBM MQ:
  runmqsc QM1
  SET AUTHREC PROFILE('SYSTEM.DEFAULT.MODEL.QUEUE') OBJTYPE(QUEUE) PRINCIPAL('MSG') AUTHADD(DSP, GET)
  SET AUTHREC PROFILE('SYSTEM.ADMIN.COMMAND.QUEUE') OBJTYPE(QUEUE) PRINCIPAL('MSG') AUTHADD(DSP, PUT)
5. Grant authority for the user ID MSG to create a IBM MQ queue for Eclipse Amlen synchronization records:
  runmqsc QM1
  SET AUTHREC PROFILE('SYSTEM.IMA.*') OBJTYPE(QUEUE) PRINCIPAL('MSG') AUTHADD(CRT, PUT, GET, BROWSE)
  SET AUTHREC PROFILE('SYSTEM.DEFAULT.LOCAL.QUEUE') OBJTYPE(QUEUE) PRINCIPAL('MSG') AUTHADD(DSP)
6. Grant publish authority to MQROOT/LEVEL1:
  runmqsc QM1
  DEFINE TOPIC(MSGTOPIC.QM1) TOPICSTR(MQROOT/LEVEL1)
  SET AUTHREC PROFILE(MSGTOPIC.QM1) OBJTYPE(TOPIC) PRINCIPAL('MSG') AUTHADD(PUB, DSP)

After you configure the IBM MQ server connection channel, you must configure the Eclipse Amlen queue manager connections and destination mapping rules.

If you are creating a secured connection, you must enter the same SSLCipherSpec value for the SSLCipherSpec variable as you specified when you created the server-connection channel.

For more information about configuring queue manager connections, see Configuring queue manager connections.

For more information about configuring destination mapping rules, see Configuring destination mapping rules.