DEFINE CHANNEL (MQTT)

Using MQSC commands

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

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 Configuring a queue manager for telemetry on Linux or Configuring 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, you 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 IBM 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 IBM MQ, 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 SSL client. The initiating end of the channel acts as the SSL client, so this parameter applies to the end of the channel that receives the initiation flow, which acts as the SSL server.

NEVER

IBM MQ never requests a certificate from the SSL client.

REQUIRED

IBM MQ requires and validates a certificate from the SSL client.

OPTIONAL

IBM MQ lets the SSL 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 SSL Cipher Suite. The SSL 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 SSL 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 Secure Sockets Layer (SSL) key repository.

SSLKEYR ( string )

The full path name of the Secure Sockets Layer (SSL) key repository file, the store for digital certificates and their associated private keys. If you do not specify a key file, SSL is not used.

The maximum length of the string is 256 characters. On UNIX and Linux, the name is of the form pathname/keyfile and on Windows pathname\keyfile , where keyfile is specified without the suffix .jks, 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.