DEFINE CHANNEL (MQTT)
Syntax diagram for a telemetry channel when using the DEFINE CHANNEL command.
Using MQSC commands
For information on how you use MQSC commands, see Performing local administration tasks using MQSC commands.
IBM® i | AIX® and Linux® | Windows | z/OS® |
---|---|---|---|
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.
- 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.
- CHLTYPE
-
Channel type. MQTT (telemetry) channel.
- JAASCFG
( string )
-
The name of a stanza in the JAAS configuration file.
- 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.
- MCAUSER
( string )
-
Message channel agent user identifier.
- 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. - 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.