runmqbcb (run IBM MQ Bridge to blockchain)

Configure and run the 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
  •  -l Re-enrollUser
  •  -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 query 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 -l Re-enrollUser
      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 you are creating the configuration file, the -f parameter is optional, the input configuration file bcbConfig.json is included in the IBM MQ Bridge to blockchain samp directory.
      runmqbcb -f inputConfigFile -o outputConfigFile
      When you run the command in this way, you 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 you 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 you are creating the configuration file, all the values for the parameters you 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.
      -l ReenrollUser
      The ReenrollUser flag is used to force re-enrolment or password checking and credential download for the user. This is useful if you want to move to a different blockchain network but still use the same user and organization names, new credentials are then required and the process forces a discard of the old stored values.
      -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 we 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. You 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 z/OS® queue manager that you 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.

        Bridge user identity queue
        SYSTEM.BLOCKCHAIN.IDENTITY.QUEUE is used only by the bridge program to store the security credentials for the configured userid.
        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, you must use a JNDI or CCDT definition.
        JNDI implementation class name
        The class name of your JNDI provider. The "queue manager name" parameter refers to the connection factory name when you are using JNDI.
        JNDI provider URL
        The endpoint of your 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.

      Blockchain - User identification
      Parameters relating to blockchain user credentials that the bridge uses to connect to the IBM Blockchain network.

        IBM Blockchain Userid
        enrollID value from the credentials file from your IBM Blockchain network.
        IBM Blockchain Enrollment Secret
        enrollSecret value from the credentials file from your IBM Blockchain network.

      Blockchain - Organisation identification
      Parameters relating to the membership service provider (MSPid) that governs membership and identity rules for your blockchain network.

        Organisation Name
        MSPid name value from the credentials file from your blockchain network.
        Organisation MSPId
        MSPid value from the credentials file from your blockchain network.

      Blockchain server locations
      Parameters relating to the blockchain network certificate authority, peer, orderer, and peer event server addresses from your credential file and the location for the .pem certificate file.

        Certificate Authority servers
        From your blockchain network credentials file, provide the name, server (IP address) and port details for the certificate authority. For example:
        ca.example.com Docker_container_host:7054 (for example ca.example.com localhost:7054)
        or 
        CA1 your_blockchain_network_public_ip_address:30000 (for example CA1 123.456.789.10:30000)
        Peer servers
        From your blockchain network credentials file, provide the name, server (IP address) and port details for the peer servers. For example:
        peer0 localhost:7051
        or
        blockchain-org1peer1 your_blockchain_network_public_ip_address:30110
        Orderer servers
        From your blockchain network credentials file, provide the name, server (IP address) and port details for the orderer servers. For example:
        orderer0 localhost:7050
        or
        blockchain-orderer your_blockchain_network_public_ip_address:31010
        Note: Include all the peer and orderer name-server:port values that appear in your credentials file.
        Peer event servers
        From your blockchain network credentials file, provide the name, server (IP address) and port details for the peer event servers. For example:
        peer0 localhost:7053
        or
        blockchain-org1peer1 your_blockchain_network_public_ip_address:30111
        Location of PEM file for IBM Blockchain certificate
        When using a TLS connection to the Hyperledger Fabric instance, a single PEM file is used to hold the Hyperledger certificates to authenticate the bridge with the Hyperledger Fabric instance. 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 we 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, such as through the IBM MQ Service definitions.