DEFINE CHANNEL (MQTT)

Syntax diagram for a telemetry channel when using the DEFINE CHANNEL command.


Use MQSC commands

For information on how we use MQSC commands, see Performing local administration tasks using MQSC commands.

DEFINE CHANNEL (MQTT)

DEFINE CHANNEL ( channel-name ) CHLTYPE ( MQTT ) BACKLOG(4096)BACKLOG(integer)
  • JAASCFG(' ')JAASCFG(string)
  • LOCLADDR(' ')LOCLADDR(string)
  • MCAUSER (' ')MCAUSER(string)
  • PORT(1883)PORT(integer)
  • PROTOCOL(MQTTV311,MQTTV3,HTTP)PROTOCOL(MQTTV311)PROTOCOL(MQTTV3)PROTOCOL(HTTP)
  • SSLCAUTH(NEVER)SSLCAUTH(OPTIONAL)SSLCAUTH(REQUIRED)
  • SSLCIPH(' ')SSLCIPH(string)
  • SSLKEYP(' ')SSLKEYP(string)
  • SSLKEYR(' ')SSLKEYR(string)
  • TRPTYPE(TCP)
  • USECLTID(NO)USECLTID(YES)


  • Usage notes

    The telemetry (MQXR) service must be running when you issue this command. For instructions on how to start the telemetry (MQXR) service, see Configure a queue manager for telemetry on Linux or Configure a queue manager for telemetry on Windows .


    Parameter descriptions for DEFINE CHANNEL (MQTT)

      (channel-name)

      The name of the new channel definition.

      The name must not be the same as any existing channel defined on this queue manager (unless REPLACE or ALTER is specified).

      The maximum length of the string is 20 characters, and the string must contain only valid characters; see Rules for naming IBM MQ objects.

      BACKLOG(integer)

      The number of outstanding connection requests that the telemetry channel can support at any one time. When the backlog limit is reached, any further clients trying to connect will be refused connection until the current backlog is processed.

      The value is in the range 0 - 999999999.

      The default value is 4096.

      CHLTYPE

      Channel type. MQTT (telemetry) channel.

      JAASCFG (string)

      The name of a stanza in the JAAS configuration file.

      See Authenticating an MQTT client Java app with JAAS

      LOCLADDR (ip-addr)

      LOCLADDR is the local communications address for the channel. Use this parameter if you want to force the client to use a particular IP address. LOCLADDR is also useful to force a channel to use an IPv4 or IPv6 address if a choice is available, or to use a particular network adapter on a system with multiple network adapters.

      The maximum length of LOCLADDR is MQ_LOCAL_ADDRESS_LENGTH.

      If you omit LOCLADDR, a local address is automatically allocated.

        ip-addr
        ip-addr is a single network address, specified in one of three forms:

          IPv4 dotted decimal
          For example 192.0.2.1

          IPv6 hexadecimal notation
          For example 2001:DB8:0:0:0:0:0:0

          Alphanumeric host name form
          For example WWW.EXAMPLE.COM

      If an IP address is entered, only the address format is validated. The IP address itself is not validated.

      MCAUSER(string)

      Message channel agent user identifier.

      The maximum length of the string is 12 characters. On Windows, we can optionally qualify a user identifier with the domain name in the format user@domain.

      If this parameter is nonblank, and USECLNTID is set to NO, then this user identifier is used by the telemetry service for authorization to access IBM MQ resources.

      If this parameter is blank, and USECLNTID is set to NO, then the user name flowed in the MQTT CONNECT Packet is used. See MQTT client identity and authorization.

      PORT(integer)

      The port number on which the telemetry (MQXR) service accepts client connections. The default port number for a telemetry channel is 1883; and the default port number for a telemetry channel secured using SSL is 8883. Specifying a port value of 0 causes MQTT to dynamically allocate an available port number.

      PROTOCOL
      The following communication protocols are supported by the channel:

        MQTTV311
        The channel accepts connections from clients using the protocol defined by the MQTT Version 3.1.1 Oasis standard. The functionality provided by this protocol is almost identical to that provided by the pre-existing MQTTV3 protocol.

        MQTTV3
        The channel accepts connections from clients using the MQTT V3.1 Protocol Specification from mqtt.org.

        HTTP
        The channel accepts HTTP requests for pages, or WebSockets connections to MQ Telemetry.

      To accept connections from clients using different protocols, specify the acceptable values as a comma-delimited list. For example if you specify MQTTV3,HTTP the channel accepts connections from clients using either MQTTV3 or HTTP. If you specify no client protocols, the channel accepts connections from clients using any of the supported protocols.

      If you are using IBM MQ Version 8.0.0, Fix Pack 3 or later, and your configuration includes an MQTT channel that was last modified in an earlier version of the product, you must explicitly change the protocol setting to prompt the channel to use the MQTTV311 option. This is so even if the channel does not specify any client protocols, because the specific protocols to use with the channel are stored at the time the channel is configured, and previous versions of the product have no awareness of the MQTTV311 option. To prompt a channel in this state to use the MQTTV311 option, explicitly add the option then save your changes. The channel definition is now aware of the option. If you subsequently change the settings again, and specify no client protocols, the MQTTV311 option is still included in the stored list of supported protocols.

      SSLCAUTH
      Defines whether IBM MQ requires a certificate from the TLS client. The initiating end of the channel acts as the TLS client, so this parameter applies to the end of the channel that receives the initiation flow, which acts as the TLS server.

        NEVER
        IBM MQ never requests a certificate from the TLS client.

        REQUIRED
        IBM MQ requires and validates a certificate from the TLS client.

        OPTIONAL
        IBM MQ lets the TLS client decide whether to provide a certificate. If the client sends a certificate, the contents of this certificate are validated as normal.

      SSLCIPH(string)

      When SSLCIPH is used with a telemetry channel, it means TLS Cipher Suite. The TLS cipher suite is the one supported by the JVM that is running the telemetry (MQXR) service. If the SSLCIPH parameter is blank, no attempt is made to use TLS on the channel.

      If you plan to use SHA-2 cipher suites, see System requirements for using SHA-2 cipher suites with MQTT channels.

      SSLKEYP(string)

      The passphrase for the TLS key repository.

      SSLKEYR(string)

      The full path name of the TLS key repository file, the store for digital certificates and their associated private keys. If we do not specify a key file, TLS is not used.

      The maximum length of the string is 256 characters;

      • On AIX and Linux, the name is of the form pathname/keyfile.
      • On Windows, the name is of the form pathname\keyfile.
      where keyfile is specified without the suffix .kdb, and identifies a Java keystore file.

      TRPTYPE (string)
      The transmission protocol to be used:

        TCP
        TCP/IP.

      USECLTID

      Decide whether you want to use the MQTT client ID for the new connection as the IBM MQ user ID for that connection. If this property is specified, the user name supplied by the client is ignored.

      If you set this parameter to YES, then MCAUSER must be blank.

      If USECLNTID is set to NO, and MCAUSER is blank, then the user name flowed in the MQTT CONNECT Packet is used. See MQTT client identity and authorization.