SET CHLAUTH

Use the MQSC command SET CHLAUTH to create or modify a channel authentication record.

UNIX and Linux® Windows
X X

SET CHLAUTH

Read syntax diagramSkip visual syntax diagramSET CHLAUTH( generic-channel-name)1CMDSCOPE(' ')CMDSCOPE(qmgr-name)2CMDSCOPE(*)23CUSTOM(custom-values)TYPE Blocking BlockMapping Block4 Blocking BlockMapping BlockACTION(ADD)ACTION(REPLACE)ACTION(REMOVE)ACTION(REMOVEALL)DESCR(' ')DESCR(string)
Blocking Block
Read syntax diagramSkip visual syntax diagram(BLOCKUSER)USERLIST(,user-name)(BLOCKADDR)ADDRLIST(,generic-ip-address)WARN(NO)WARN(YES)
Mapping Block
Read syntax diagramSkip visual syntax diagram(SSLPEERMAP)SSLPEER(generic-ssl-peer-name)(ADDRESSMAP)(USERMAP)CLNTUSER(client-user-name)(QMGRMAP)QMNAME(generic-partner-qmgr-name)USERSRC(MAP)MCAUSER(user )USERSRC(NOACCESS)WARN(NO)WARN(YES)USERSRC(CHANNEL)ADDRESS(generic-ip-address)5
Notes:
  • 1 The generic channel name must be '*' when TYPE is BLOCKADDR
  • 2 Valid only on z/OS® when the queue manager is a member of a queue-sharing group.
  • 3 Valid only on z/OS.
  • 4 Select the appropriate value for TYPE, depending upon the option that you select from the two types of block.
  • 5 Mandatory when TYPE is ADDRESSMAP

Usage notes

The following table shows which parameters are valid for each value of ACTION:
  Action
Parameter ADD or REPLACE REMOVE REMOVEALL
CHLAUTH X X X
TYPE X X X
CMDSCOPE X X X
ACTION X X X
ADDRESS X X  
ADDRLIST X X  
CLNTUSER X X  
MCAUSER X    
QMNAME X X  
SSLPEER X X  
USERLIST X X  
USERSRC X    
WARN X    
DESCR X    

Parameters

generic-channel-name
The name of the channel or set of channels for which you are setting channel authentication configuration. You can use one or more asterisks (*), in any position, as wildcards to specify a set of channels. If you set TYPE to BLOCKADDR, you must set the generic channel name to a single asterisk, which matches all channel names. On z/OS the generic-channel-name must be in quotes if it contains an asterisk.
TYPE
The TYPE parameter must follow the generic-channel-name parameter.

The type of channel authentication record for which to set allowed partner details or mappings to MCAUSER. This parameter is required. The following values can be used:

BLOCKUSER
This channel authentication record prevents a specified user or users from connecting. The BLOCKUSER parameter must be accompanied by a USERLIST.
BLOCKADDR
This channel authentication record prevents connections from a specified IP address or addresses. The BLOCKADDR parameter must be accompanied by an ADDRLIST. BLOCKADDR operates at the listener before the channel name is known.
SSLPEERMAP
This channel authentication record maps SSL or TLS Distinguished Names (DNs) to MCAUSER values. The SSLPEERMAP parameter must be accompanied by an SSLPEER.
ADDRESSMAP
This channel authentication record maps IP addresses to MCAUSER values. The ADDRESSMAP parameter must be accompanied by an ADDRESS. ADDRESSMAP operates at the channel.
USERMAP
This channel authentication record maps asserted user IDs to MCAUSER values. The USERMAP parameter must be accompanied by a CLNTUSER.
QMGRMAP
This channel authentication record maps remote queue manager names to MCAUSER values. The QMGRMAP parameter must be accompanied by a QMNAME.
ACTION
The action to perform on the channel authentication record. The following values are valid:
ADD
Add the specified configuration to a channel authentication record. This is the default value.

For types SSLPEERMAP, ADDRESSMAP, USERMAP and QMGRMAP, if the specified configuration exists, the command fails.

For types BLOCKUSER and BLOCKADDR, the configuration is added to the list.

REPLACE
Replace the current configuration of a channel authentication record.

For types SSLPEERMAP, ADDRESSMAP, USERMAP and QMGRMAP, if the specified configuration exists, it is replaced with the new configuration. If it does not exist it is added.

For types BLOCKUSER and BLOCKADDR, the configuration specified replaces the current list, even if the current list is empty. If you replace the current list with an empty list, this acts like REMOVEALL.

REMOVE
Remove the specified configuration from the channel authentication records. If the configuration does not exist the command fails. If you remove the last entry from a list, this acts like REMOVEALL.
REMOVEALL
Remove all members of the list and thus the whole record (for BLOCKADDR and BLOCKUSER) or all previously defined mappings (for ADDRESSMAP, SSLPEERMAP, QMGRMAP and USERMAP) from the channel authentication records. This option cannot be combined with specific values supplied in ADDRLIST, USERLIST, ADDRESS, SSLPEER, QMNAME or CLNTUSER. If the specified type has no current configuration the command still succeeds.
ADDRESS
The filter to be used to compare with the IP address of the partner queue manager or client at the other end of the channel.

This parameter is mandatory with TYPE(ADDRESSMAP)

This parameter is also valid when TYPE is SSLPEERMAP, USERMAP, or QMGRMAP and ACTION is ADD, REPLACE, or REMOVE. You can define more than one channel authentication object with the same main identity, for example the same SSL peer name, with different addresses. However, you cannot define channel authentication records with overlapping address ranges for the same main identity. See Generic IP addresses for more information about filtering IP addresses.

If the address is generic then it must be in quotes.

ADDRLIST
A list of up to 256 generic IP addresses which are banned from accessing this queue manager on any channel. This parameter is only valid with TYPE(BLOCKADDR). See Generic IP addresses for more information about filtering IP addresses.

If the address is generic then it must be in quotes.

CLNTUSER
The client asserted user ID to be mapped to a new user ID or blocked.

This parameter is valid only with TYPE(USERMAP).

CMDSCOPE
This parameter applies to z/OS only and specifies how the command is run when the queue manager is a member of a queue-sharing group.
' '
The command is run on the queue manager on which it was entered. This is the default value.
qmgr-name
The command is run on the queue manager you specify, providing the queue manager is active within the queue-sharing group.

You can specify a queue manager name, other than the queue manager on which the command was entered, only if you are using a queue-sharing group environment and if the command server is enabled.

*
The command is run on the local queue manager and is also passed to every active queue manager in the queue-sharing group. The effect is the same as entering the command on every queue manager in the queue-sharing group.
CUSTOM
Reserved for future use.
DESCR
Provides descriptive information about the channel authentication record, which is displayed when you issue the DISPLAY CHLAUTH command. It must contain only displayable characters. The maximum length is 64 characters. In a DBCS installation, it can contain DBCS characters (subject to a maximum length of 64 bytes).
Note: Use characters from the coded character set identifier (CCSID) for this queue manager. Other characters might be translated incorrectly if the information is sent to another queue manager.
MCAUSER
The user identifier to be used when the inbound connection matches the SSL or TLS DN, IP address, client asserted user ID or remote queue manager name supplied.

This parameter is mandatory with USERSRC(MAP) and is valid when TYPE is SSLPEERMAP, ADDRESSMAP, USERMAP, or QMGRMAP.

This parameter can only be used when ACTION is ADD or REPLACE.

QMNAME
The name of the remote partner queue manager, or pattern that matches a set of queue manager names, to be mapped to a user ID or blocked.

This parameter is valid only with TYPE(QMGRMAP).

If the queue manager name is generic then it must be in quotes.

SSLPEER

The filter to use to compare with the Subject Distinguished Name of the certificate from the peer queue manager or client at the other end of the channel.

The SSLPEER filter is specified in the standard form used to specify a Distinguished Name. See WebSphere® MQ rules for SSLPEER values for details.

The maximum length of the parameter is 1024 bytes.

USERLIST
A list of up to 100 user IDs which are banned from use of this channel or set of channels. Use the special value *MQADMIN to mean privileged or administrative users. The definition of this value depends on the operating system, as follows:
  • On Windows, all members of the mqm group, the Administrators group and SYSTEM.
  • On UNIX and Linux, all members of the mqm group.
  • On IBM® i, the profiles (users) qmqm and qmqmadm and all members of the qmqmadm group, and any user defined with the *ALLOBJ special setting.
  • On z/OS, the user ID that the channel initiator and queue manager address spaces are running under.
For more information about privileged users, see Privileged users .
This parameter is only valid with TYPE(BLOCKUSER).
USERSRC
The source of the user ID to be used for MCAUSER at run time. The following values are valid:
MAP
Inbound connections that match this mapping use the user ID specified in the MCAUSER attribute. This is the default value.
NOACCESS
Inbound connections that match this mapping have no access to the queue manager and the channel ends immediately.
CHANNEL
Inbound connections that match this mapping use the flowed user ID or any user defined on the channel object in the MCAUSER field.

Note that WARN and USERSRC(CHANNEL), or USERSRC(MAP) are incompatible. This is because channel access is never blocked in these cases, so there is never a reason to generate a warning.

WARN
Indicates whether this record operates in warning mode.
NO
This record does not operate in warning mode. Any inbound connection that matches this record is blocked. This is the default value.
YES
This record operates in warning mode. Any inbound connection that matches this record and would therefore be blocked is allowed access. An error message is written and, if channel events are configured, a channel event message is created showing the details of what would have been blocked, see Channel Blocked. The connection is allowed to continue. An attempt is made to find another record that is set to WARN(NO) to set the credentials for the inbound channel.