runmqbcb (run IBM MQ Bridge to blockchain)

Configure and run the IBM MQ Bridge to blockchain on a Hyperledger Fabric network.


Syntax

The diagram shows the syntax for the runmqbcb command usage as described in note 1. runmqbcb  -f ConfigurationFile  -r RuntimeLogFile  -o outputConfigFile -q BridgeInputQueue -m QMgrName -d DebugLevel -k killFile -sf file -sp mode


Usage notes

There are two available authentication mechanisms for the bridge to connect to Hyperledger Fabric, both of which require that you configure a username. This username will be associated with any operations processed through the IBM MQ Bridge to blockchain.

The first approach allows a Wallet (file) to be supplied from the administrator. The Wallet is a container holding certificates and so on.

The second approach is based on an administrator just providing certificates to you and not a standalone wallet. The configuration then requires the location of the certificate (typically a PEM file), along with a password to access it, and an associated organization name.

  1. We can run the runmqbcb command to start the IBM MQ Bridge to blockchain and connect to Hyperledger Fabric 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 -q BridgeInputQueue -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 Hyperledger Fabric and IBM MQ. When we are creating the configuration file, the -f parameter is optional.
    runmqbcb -f inputConfigFile -o outputConfigFile [-b]
    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.
  3. From IBM MQ Version 9.2.0, the usage of the enhanced protection parameters is as follows:

      Configuration mode
      Newly entered passwords are written to the output configuration file protected with the new key. Note that preexisting passwords are not changed in format.
      A warning is issued when the default key is being used, that is, you have not provided a keyfile.
      Provision of passwords in the batch configuration mode, using environment variables, continues unchanged; that is, the value of the environment variables is given in plain text.

      Runtime mode
      When a password is decrypted, warning messages are issued if the password is found to be in the old format, and the name of the parameter causing the warning is given in the message to encourage you to migrate. However, the bridge continues processing commands.Note: The warning message is not issued if you have specified the -sp 0 parameter on the command line, as you explicitly wanted to use old formats.
      A warning is also issued when the default key is being used, that is, you have not provided a keyfile.
      Errors occur if a password cannot be decrypted, for example, if you have specified the wrong keyfile.


Command line parameters

    -f ConfigurationFile
    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.

    -b
    Use environment variables during configuration.

    -sf file
    File containing password protection key.

    -sp mode
    Password protection mode. The values can be:

      1
      Default, to use the new protection mode.

      0
      Use the existing protection mode.


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 Fabric REST server

      Userid
      The User Id provided by the bridge to Hyperledger Fabric must be known and authorized to connect to the Hyperledger Fabric endpoint, based on the user authentication configuration of the Hyperledger Fabric REST server.

      Password
      The password for the User Id that the bridge is using to connect to Hyperledger Fabric.

      API path for login
      The URL path to provide user credentials to the Hyperledger Fabric REST server. Note that this URL differs, depending on the type of security provider configured.

    Fabric server
    Attributes applicable to the Hyperledger Fabric server.

      Wallet
      A file containing credentials for the user, usually supplied by a Hyperledger Fabric administrator.

      User Name
      Mandatory parameter.

      User Certificate
      If no Wallet is provided, we must supply your certificate, private key and organization.

      User Private Key
      Your private key. We must supply this along with your certificate and organization if no Wallet has been provided.

      User Organization
      Your organization. We must supply this along with your certificate and private key if no Wallet has been provided.

      Network Configuration File
      A JSON-format file, usually supplied by the Hyperledger Fabric administrator or tooling that describes the various servers, addresses and so on. The file must exist.

      Commit Timeout
      Timeout for update operations in seconds.
      The default value is 15 seconds.

      Discovery
      Whether to enable discovery of unknown networks that are not listed in the network configuration file.
      The value can be Y or N.

      Updates sent to all peers
      Whether update responses are needed from all peers. or just one.
      The value can be Y or N. The default value is Y.

      Updates sent to all organizations in the network
      Should updates be sent to all of the organizations listed in the configuration, or just to the specific MSPID organization.
      The value can be Y for all organizations, or N for the specific organization. The default value is N.

    Location of PEM file for IBM Blockchain certificate
    When using a TLS connection to the Hyperledger Fabric REST server, a single PEM file is used to hold the Hyperledger certificates to authenticate the bridge with the Hyperledger Fabric 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.

    -sf file
    File containing password protection key.

    -sp mode
    Password protection mode. The values can be:

      1
      Default, to use the new protection mode.

      0
      Use the existing protection mode.

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