runmqbcb (run IBM MQ Bridge to blockchain)

Configure and run the IBM MQ Bridge to blockchain.

Attention: The existing format of the runmqbcb command is obsolete. From IBM MQ Version 9.1.4, if you have a Hyperledger Fabric network, use the format of the command described in runmqbcb (run IBM MQ Bridge to blockchain).

Syntax

The diagram shows the syntax for the runmqbcb command usage as described in note 1.

Usage notes

We can run the runmqbcb command to start the IBM MQ Bridge to blockchain and connect to IBM Blockchain and IBM MQ. When the connections are made, the bridge is ready to receive and process request messages that are put on the queue manager input queue, send the correctly formatted queries and updates to the blockchain network, receive, process and put replies from the blockchain to the reply queue.
```
runmqbcb -f ConfigFile -r RuntimeLogFile -m QMgrName -d DebugLevel -k killFile -r RuntimeLogFile
```
When we use the command for runtime processing, the required parameters are -f, with the name of the previously created configuration file, and -r with the name of the log file. When the other command parameters are also given on the command line, they override the values in the configuration file. The same configuration file can be used by multiple bridges.
We can also use the runmqbcb command to generate a configuration file that is used to define the parameters that are needed for the bridge to connect to IBM Blockchain and IBM MQ. When we are creating the configuration file, the -f parameter is optional.
```
runmqbcb -f inputConfigFile -o outputConfigFile
```
When you run the command in this way, we are prompted to enter values for each of the configuration parameters. To keep an existing value press Enter. To remove an existing value press Space, then Enter. For more information, see Configuration parameters.

Command line parameters

-f ConfigFile

Configuration file. The -f parameter is required when we are running the runmqbcb command to start the IBM MQ Bridge to blockchain, as described in usage note 1. We can optionally use the -f parameter to reuse some of the values from an existing inputConfigFile, as described in usage note 2, and also enter some of the new values. If we do not specify the -f parameter when we are creating the configuration file, all the values for the parameters we are prompted for are empty.

-r RuntimeLogFile

Required. Location and name of the log file for trace information. We can specify the log file path and name in the configuration file or on the command line.

-o outputConfigFile

New configuration file. When you run the command with the -o parameter, runmmbcb command loads existing configuration values from the -f file and prompts for new values for each configuration parameter.

-q BridgeInputQueue

Name of the queue that the bridge waits for messages on.

-m QMgrName

Queue manager name.

-d debugLevel

Debug level, 1, or 2.

1: Terse debug information is displayed.
2: Verbose debug information is displayed.

-k killFile

A file to cause the bridge to exit. When you run the command with the -k parameter and specify a file, if the file exists, it causes the bridge program to exit. Using this file is an alternative way to stop the program when you don't want to use Ctrl+C or kill command. The file is deleted by the bridge on startup in case it exists. If the deletion fails, the bridge abends but monitors for the recreation of the file.

Configuration parameters

When you run the runmqbcb command to create the configuration file, the parameters are stepped through in six groups. Passwords are obfuscated and are not displayed as you type. The generated configuration file is in JSON format. We must use the runmqbcb command to create the configuration file. We cannot edit the passwords and security certificate information directly in the JSON file.

Connection to queue manager

Parameters relating to the IBM MQ queue manager.

IBM MQ Queue manager: Required. The IBM MQ Advanced queue manager that we are using with the IBM MQ Bridge to blockchain.
Bridge input queue: SYSTEM.BLOCKCHAIN.INPUT.QUEUE is the default queue where applications put request messages, this can be overridden in the configuration file or on the runmqbcb command line. User applications must have appropriate authorisation to put messages to this queue.
IBM MQ Channel: The bridge requires a svrcon channel to connect to the z/os queue manager remotely.
IBM MQ Conname: Uses standard connection name format of "host(port), host(port)" to enable multiple destinations such as for multi-instance queue managers.
IBM MQ CCDT URL: If a TLS connection is required to the queue manager, we must use a JNDI or CCDT definition.
JNDI implementation class name: The class name of our JNDI provider. The "queue manager name" parameter refers to the connection factory name when we are using JNDI.
JNDI provider URL: The endpoint of our JNDI service.
IBM MQ UserId: The UserId that is running the bridge must have permission to set identity context on the messages it sends as replies, these have the requester UserId set in the message. The bridge user must therefore have appropriate access to put to the reply queue.
IBM MQ Password: Password for the IBM MQ UserId that the bridge is using.

User identification

Parameters relating to user authentication details that the bridge uses to connect to the Hyperledger Composer REST server

Userid: The User Id provided by the bridge to Hyperledger Composer must be known and authorized to connect to the Hyperledger Composer endpoint, based on the user authentication configuration of the Hyperledger Composer REST server.
Password: The password for the User Id that the bridge is using to connect to Hyperledger Composer.
API path for login: The URL path to provide user credentials to the Hyperledger Composer REST server. Note that this URL differs, depending on the type of security provider configured.

REST server

Address for Hyperledger Composer REST server.

The location of the Hyperledger Composer REST server in “host:port” format. The protocol prefix of http:// or https:// should not be provided.

Location of PEM file for IBM Blockchain certificate

When using a TLS connection to the Hyperledger Composer REST server, a single PEM file is used to hold the Hyperledger certificates to authenticate the bridge with the Hyperledger Composer REST server. This PEM file must be copied to the system where the IBM MQ Bridge to blockchain is running, and specified in the configuration file.

Certificate stores for TLS connections

Parameters relating to certificate stores for TLS connections.

Personal keystore for TLS certificates: Keystore for security certificates that are used for IBM MQ.
Keystore password: Password for the keystore.
Trusted store for signer certificates: If we do not add the trusted store, the personal keystore for TLS certificates is used.
Trusted store password: If the personal keystore for TLS certificates is used, this is the password for the keystore for TLS certificates.
Use TLS for MQ connection: The bridge can use TLS when it connects to the queue manager.
Timeout for Blockchain operations

If you don't provide a truststore parameter, the keystore is used for both roles. The stores can be the same as the one configured for the IBM MQ connection in the CCDT or JNDI.

Behavior of bridge program

Parameters relating to the behavior of the IBM MQ Bridge to blockchain.

Required. Runtime logfile for copy of stdout/stderr: Path to and name of the log file for the tracing information.

The configuration is only read on startup of the bridge process. Changes to the configuration require a restart of the bridge.