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. runmqbcb  -f ConfigFile  -r RuntimeLogFile  -o outputConfigFile -q BridgeInputQueue -m QMgrName -d DebugLevel -k killFile


Usage notes

  1. 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.
  2. 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.