DEFINE CHANNEL (MQTT)

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

UNIX and Linux®	Windows

Note: For the telemetry server, AIX® is the only supported UNIX platform.

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 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). On z/OS®, client-connection channel names can duplicate others.

The maximum length of the string is 20 characters, and the string must contain only valid characters; see Rules for naming IBM® WebSphere® 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.

LOCLADDR(string)

LOCLADDR is the local communications address for the channel. Use this parameter if you want a channel to use a particular IP address, port, or port range for outbound communications. LOCLADDR might be useful in recovery scenarios where a channel is restarted on a different TCP/IP stack. LOCLADDR is also useful to force a channel to use an IPv4 or IPv6 stack on a dual-stack system. You can also use LOCLADDR to force a channel to use a dual-mode stack on a single-stack system.

This parameter is valid only for channels with a transport type (TRPTYPE) of TCP. If TRPTYPE is not TCP, the data is ignored and no error message is issued.

The value is the optional IP address, and optional port or port range used for outbound TCP/IP communications. The format for this information is as follows:

LOCLADDR([ip-addr][(low-port[,high-port])][,[ip-addr][(low-port[,high-port])]])

The maximum length of LOCLADDR, including multiple addresses, is MQ_LOCAL_ADDRESS_LENGTH.

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

Note, that you can set LOCLADDR for a C client using the Client Channel Definition Table (CCDT).

All the parameters are optional. Omitting the ip-addr part of the address is useful to enable the configuration of a fixed port number for an IP firewall. Omitting the port number is useful to select a particular network adapter without having the identify a unique local port number. The TCP/IP stack generates a unique port number.

Specify [,[ip-addr][(low-port[,high-port])]] multiple times for each additional local address. Use multiple local addresses if you want to specify a specific subset of local network adapters. You can also use [,[ip-addr][(low-port[,high-port])]] to represent a particular local network address on different servers that are part of a multi-instance queue manager configuration.

ip-addr

ip-addr is 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

low-port and high-port

low-port and high-port are port numbers enclosed in parentheses.

Table 3 shows how the LOCLADDR parameter can be used:

Table 1. Examples of how the LOCLADDR parameter can be used
LOCLADDR	Meaning
9.20.4.98	Channel binds to this address locally
9.20.4.98, 9.20.4.99	Channel binds to either IP address. The address might be two network adapters on one server, or a different network adapter on two different servers in a multi-instance configuration.
9.20.4.98(1000)	Channel binds to this address and port 1000 locally
9.20.4.98(1000,2000)	Channel binds to this address and uses a port in the range 1000 - 2000 locally
(1000)	Channel binds to port 1000 locally
(1000,2000)	Channel binds to port in range 1000 - 2000 locally

This parameter is valid only for channels with a channel type (CHLTYPE) of SDR, SVR, RQSTR, CLNTCONN, CLUSSDR, CLUSRCVR, or MQTT.

On CLUSSDR channels, the IP address and port to which the outbound channel binds, is a combination of fields. It is a concatenation of the IP address, as defined in the LOCLADDR parameter, and the port range from the cluster cache. If there is no port range in the cache, the port range defined in the LOCLADDR parameter is used. This port range does not apply to z/OS.

Even though this parameter is similar in form to CONNAME, it must not be confused with it. The LOCLADDR parameter specifies the characteristics of the local communications, whereas the CONNAME parameter specifies how to reach a remote queue manager.

When a channel is started, the values specified for CONNAME and LOCLADDR determine the IP stack to be used for communication; see Table 3 and Local Address (LOCLADDR) .

If the TCP/IP stack for the local address is not installed or configured, the channel does not start and an exception message is generated. The message indicates that the connect() request specifies an interface address that is not known on the default IP stack. To direct the connect() request to the alternative stack, specify the LOCLADDR parameter in the channel definition as either an interface on the alternative stack, or a DNS host name. The same specification also works for listeners that might not use the default stack. To find the value to code for LOCLADDR, run the NETSTAT HOME command on the IP stacks that you want to use as alternatives.

For channels with a channel type (CHLTYPE) of MQTT the usage of this parameter is slightly different. Specifically, a telemetry channel (MQTT) LOCLADDR parameter expects only an IPv4 or IPv6 IP address, or a valid host name as a string. This string must not contain a port number or port range. If an IP address is entered, only the address format is validated. The IP address itself is not validated.

Table 2. How the IP stack to be used for communication is determined
Protocols supported	CONNAME	LOCLADDR	Action of channel
IPv4 only	IPv4 address¹		Channel binds to IPv4 stack
	IPv6 address²		Channel fails to resolve CONNAME
	IPv4 and 6 host name³		Channel binds to IPv4 stack
	IPv4 address	IPv4 address	Channel binds to IPv4 stack
	IPv6 address	IPv4 address	Channel fails to resolve CONNAME
	IPv4 and 6 host name	IPv4 address	Channel binds to IPv4 stack
	Any address⁴	IPv6 address	Channel fails to resolve LOCLADDR
	IPv4 address	IPv4 and 6 host name	Channel binds to IPv4 stack
	IPv6 address	IPv4 and 6 host name	Channel fails to resolve CONNAME
	IPv4 and 6 host name	IPv4 and 6 host name	Channel binds to IPv4 stack
IPv4 and IPv6	IPv4 address		Channel binds to IPv4 stack
	IPv6 address		Channel binds to IPv6 stack
	IPv4 and 6 host name		Channel binds to stack determined by IPADDRV
	IPv4 address	IPv4 address	Channel binds to IPv4 stack
	IPv6 address	IPv4 address	Channel fails to resolve CONNAME
	IPv4 and 6 host name	IPv4 address	Channel binds to IPv4 stack
	IPv4 address	IPv6 address	Channel maps CONNAME to IPv6⁵
	IPv6 address	IPv6 address	Channel binds IPv6 stack
	IPv4 and 6 host name	IPv6 address	Channel binds IPv6 stack
	IPv4 address	IPv4 and 6 host name	Channel binds to IPv4 stack
	IPv6 address	IPv4 and 6 host name	Channel binds to IPv6 stack
	IPv4 and 6 host name	IPv4 and 6 host name	Channel binds to stack determined by IPADDRV
IPv6 only	IPv4 address		Channel maps CONNAME to IPv6⁵
	IPv6 address		Channel binds to IPv6 stack
	IPv4 and 6 host name		Channel binds to IPv6 stack
	Any address	IPv4 address	Channel fails to resolve LOCLADDR
	IPv4 address	IPv6 address	Channel maps CONNAME to IPv6⁵
	IPv6 address	IPv6 address	Channel binds to IPv6 stack
	IPv4 and 6 host name	IPv6 address	Channel binds to IPv6 stack
	IPv4 address	IPv4 and 6 host name	Channel maps CONNAME to IPv6⁵
	IPv6 address	IPv4 and 6 host name	Channel binds to IPv6 stack
	IPv4 and 6 host name	IPv4 and 6 host name	Channel binds to IPv6 stack
Notes: IPv4 address. An IPv4 host name that resolves only to an IPv4 network address or a specific dotted notation IPv4 address, for example `1.2.3.4`. This note applies to all occurrences of 'IPv4 address' in this table. IPv6 address. An IPv6 host name that resolves only to an IPv6 network address or a specific hexadecimal notation IPv6 address, for example `4321:54bc`. This note applies to all occurrences of 'IPv6 address' in this table. IPv4 and 6 host name. A host name that resolves to both IPv4 and IPv6 network addresses. This note applies to all occurrences of 'IPv4 and 6 host name' in this table. Any address. IPv4 address, IPv6 address, or IPv4 and 6 host name. This note applies to all occurrences of 'Any address' in this table. Maps IPv4 CONNAME to IPv4 mapped IPv6 address. IPv6 stack implementations that do not support IPv4 mapped IPv6 addressing fail to resolve the CONNAME. Mapped addresses might require protocol translators in order to be used. The use of mapped addresses is not recommended.

MCAUSER(string )

Message channel agent user identifier.

This parameter interacts with PUTAUT , see the definition of that parameter for more information.

If it is nonblank, it is the user identifier that is to be used by the message channel agent for authorization to access WebSphere MQ resources, including (if PUTAUT is DEF) authorization to put the message to the destination queue for receiver or requester channels.

If it is blank, the message channel agent uses its default user identifier.

The default user identifier is derived from the user ID that started the receiving channel. The possible values are:

On z/OS, the user ID assigned to the channel-initiator started task by the z/OS started-procedures table.
For TCP/IP, other than z/OS , the user ID from the inetd.conf entry, or the user that started the listener.
For SNA, other than z/OS , the user ID from the SNA server entry or, in the absence of this user ID the incoming attach request, or the user that started the listener.
For NetBIOS or SPX, the user ID that started the listener.

The maximum length of the string is 64 characters on Windows and 12 characters on other platforms. On Windows, you can optionally qualify a user identifier with the domain name in the format user@domain.

This parameter is not valid for channels with a channel type ( CHLTYPE) of SDR, SVR, CLNTCONN, CLUSSDR.

PORT(integer )

The port number that the telemetry (MQXR) service accepts client connections on. 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.

SSLCAUTH

Defines whether WebSphere 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.

This parameter is valid only for channels with a channel type (CHLTYPE) of RCVR, SVRCONN, CLUSRCVR, SVR, RQSTR, or MQTT.

The parameter is used only for channels with SSLCIPH specified. If SSLCIPH is blank, the data is ignored and no error message is issued.

REQUIRED: IBM WebSphere MQ requires and validates a certificate from the SSL client.
OPTIONAL: The peer SSL client system might still send a certificate. If it does, 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.

Here is an alphabetic list of the SSL cipher suites that are currently supported:

SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA
SSL_DH_anon_EXPORT_WITH_RC4_40_MD5
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA
SSL_DH_anon_WITH_AES_128_CBC_SHA
SSL_DH_anon_WITH_DES_CBC_SHA
SSL_DH_anon_WITH_RC4_128_MD5
SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA
SSL_DHE_DSS_WITH_3DES_EDE_CBC_SHA
SSL_DHE_DSS_WITH_AES_128_CBC_SHA
SSL_DHE_DSS_WITH_DES_CBC_SHA
SSL_DHE_DSS_WITH_RC4_128_SHA
SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
SSL_DHE_RSA_WITH_AES_128_CBC_SHA
SSL_DHE_RSA_WITH_DES_CBC_SHA
SSL_KRB5_EXPORT_WITH_DES_CBC_40_MD5
SSL_KRB5_EXPORT_WITH_DES_CBC_40_SHA
SSL_KRB5_EXPORT_WITH_RC4_40_MD5
SSL_KRB5_EXPORT_WITH_RC4_40_SHA
SSL_KRB5_WITH_3DES_EDE_CBC_MD5
SSL_KRB5_WITH_3DES_EDE_CBC_SHA
SSL_KRB5_WITH_DES_CBC_MD5
SSL_KRB5_WITH_DES_CBC_SHA
SSL_KRB5_WITH_RC4_128_MD5
SSL_KRB5_WITH_RC4_128_SHA
SSL_RSA_EXPORT_WITH_DES40_CBC_SHA
SSL_RSA_EXPORT_WITH_RC4_40_MD5
SSL_RSA_FIPS_WITH_3DES_EDE_CBC_SHA
SSL_RSA_FIPS_WITH_AES_128_CBC_SHA256
SSL_RSA_FIPS_WITH_AES_256_CBC_SHA256
SSL_RSA_FIPS_WITH_DES_CBC_SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_AES_128_CBC_SHA
SSL_RSA_WITH_AES_128_CBC_SHA256
SSL_RSA_WITH_AES_256_CBC_SHA256
SSL_RSA_WITH_DES_CBC_SHA
SSL_RSA_WITH_NULL_MD5
SSL_RSA_WITH_NULL_SHA
SSL_RSA_WITH_NULL_SHA256
SSL_RSA_WITH_RC4_128_MD5
SSL_RSA_WITH_RC4_128_SHA

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

SSLKEYP(string )

The store for digital certificates and their associated private keys. If you do not specify a key file, SSL is not used.

SSLKEYR(string )

The password for the key repository. If no passphrase is entered, then unencrypted connections must be used.

USECLTID

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