REFRESH SECURITY

Use the MQSC command REFRESH SECURITY to perform a security refresh.

Using MQSC commands

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

IBM® i UNIX and Linux® Windows z/OS®
X X X See Using REFRESH SECURITY on z/OS

Synonym: REF SEC

REBUILD SECURITY is another synonym for REFRESH SECURITY.

REFRESH SECURITY

Read syntax diagramSkip visual syntax diagramREFRESH SECURITY(*)(MQADMIN1MQNLIST1MQPROC1MQQUEUE1MXADMIN1MXNLIST1MXPROC1MXQUEUE1MXTOPIC1)TYPE(CLASSES)1TYPE(AUTHSERV)2TYPE(SSL)TYPE(CONNAUTH)CMDSCOPE(' ')CMDSCOPE(qmgr-name)3CMDSCOPE(*)31
Notes:
  • 1 Valid only on z/OS.
  • 2 Not valid on z/OS.
  • 3 Valid only on IBM MQ for z/OS when the queue manager is a member of a queue-sharing group.
[z/OS]

Using REFRESH SECURITY on z/OS

REFRESH SECURITY can be used on z/OS. Depending on the parameters used on the command, it may be issued from various sources. For an explanation of the symbols in this table, see Using commands on z/OS.

Command Command Sources Notes
REFRESH SECURITY TYPE(CLASSES) CR  
REFRESH SECURITY TYPE(SSL) CR Not allowed from CSQINPT or CSQINP2. Channel initiator must be running.

Usage notes for REFRESH SECURITY

When you issue the REFRESH SECURITY TYPE(SSL) MQSC command, all running SSL channels are stopped and restarted. Sometimes SSL channels can take a long time to shut down and this means that the refresh operation takes some time to complete. There is a time limit of 10 minutes for an SSL refresh to complete[z/OS] (or 1 minute on z/OS ), so it can potentially take 10 minutes for the command to finish. This can give the appearance that the refresh operation has "frozen". The refresh operation will fail with an MQSC error message of AMQ9710 or PCF error MQRCCF_COMMAND_FAILED if the timeout is exceeded before all channels have stopped. This is likely to happen if the following conditions are true:
  • The queue manager has many SSL channels running simultaneously when the refresh command is invoked
  • The channels are handling large numbers of messages
If a refresh fails under these conditions, retry the command later when the queue manager is less busy. In the case where many channels are running, you can choose to stop some of the channels manually before invoking the REFRESH command.
When using TYPE(SSL):
  1. [z/OS]On z/OS, the command server and channel initiator must be running.
  2. [z/OS]On z/OS, IBM MQ determines whether a refresh is needed due to one, or more, of the following reasons:
    • The contents of the key repository have changed
    • The location of the LDAP server to be used for Certification Revocation Lists has changed
    • The location of the key repository has changed
    If no refresh is needed, the command completes successfully and the channels are unaffected.
  3. [z/OS](Platforms other than z/OS) The command updates all SSL channels regardless of whether a security refresh is needed.
  4. If a refresh is to be performed, the command updates all SSL channels currently running, as follows:
    • Sender, server and cluster-sender channels using SSL are allowed to complete the current batch. In general they then run the SSL handshake again with the refreshed view of the SSL key repository. However, you must manually restart a requester-server channel on which the server definition has no CONNAME parameter.
    • All other channel types using SSL are stopped with a STOP CHANNEL MODE(FORCE) STATUS(INACTIVE) command. If the partner end of the stopped message channel has retry values defined, the channel retries and the new SSL handshake uses the refreshed view of the contents of the SSL key repository, the location of the LDAP server to be used for Certification Revocation Lists, and the location of the key repository. In the case of a server-connection channel, the client application loses its connection to the queue manager and has to reconnect in order to continue.
[z/OS]When using TYPE(CLASSES):
  • Classes MQADMIN, MQNLIST, MQPROC, and MQQUEUE can only hold profiles defined in uppercase.
  • Classes MXADMIN, MXNLIST, MXPROC, and MQXUEUE can hold profiles defined in mixed case.
  • Class MXTOPIC can be refreshed whether using uppercase or mixed case classes. Although it is a mixed case class, it is the only mixed case class that can be active with either group of classes.
  • The MQCMD and MQCONN classes cannot be specified, and are not included by REFRESH SECURITY CLASS(*).

    Security information from the MQCMD and MQCONN classes is not cached in the queue manager. See Refreshing queue manager security on z/OS for further information.

Notes:
  1. Performing a REFRESH SECURITY(*) TYPE(CLASSES) operation is the only way to change the classes being used by your system from uppercase-only support to mixed case support.

    Do this by checking the queue manager attribute SCYCASE to see if it is set to UPPER or MIXED

  2. It is your responsibility to ensure that you have copied, or defined, all the profiles you need in the appropriate classes before you carry out a REFRESH SECURITY(*) TYPE(CLASSES) operation.
  3. A refresh of an individual class is allowed only if the classes currently being used are of the same type. For example, if MQPROC is in use, you can issue a refresh for MQPROC but not MXPROC.

Parameter descriptions for REFRESH SECURITY

The command qualifier allows you to indicate more precise behavior for a specific TYPE value. Select from:
*
A full refresh of the type specified is performed.[z/OS] This is the default value on z/OS systems.
[z/OS]MQADMIN
[z/OS] Valid only if TYPE is CLASSES. Specifies that Administration type resources are to be refreshed. Valid on z/OS only.
Note: If, when refreshing this class, it is determined that a security switch relating to one of the other classes has been changed, a refresh for that class also takes place.
[z/OS]MQNLIST
[z/OS] Valid only if TYPE is CLASSES. Specifies that Namelist resources are to be refreshed. Valid on z/OS only.
[z/OS]MQPROC
[z/OS] Valid only if TYPE is CLASSES. Specifies that Process resources are to be refreshed. Valid on z/OS only.
[z/OS]MQQUEUE
[z/OS] Valid only if TYPE is CLASSES. Specifies that Queue resources are to be refreshed. Valid on z/OS only.
[z/OS]MXADMIN
[z/OS] Valid only if TYPE is CLASSES. Specifies that administration type resources are to be refreshed. Valid on z/OS only.
Note: If, when refreshing this class, it is determined that a security switch relating to one of the other classes has been changed, a refresh for that class also takes place.
[z/OS]MXNLIST
[z/OS] Valid only if TYPE is CLASSES. Specifies that namelist resources are to be refreshed. Valid on z/OS only.
[z/OS]MXPROC
[z/OS] Valid only if TYPE is CLASSES. Specifies that process resources are to be refreshed. Valid on z/OS only.
[z/OS]MXQUEUE
[z/OS] Valid only if TYPE is CLASSES. Specifies that queue resources are to be refreshed. Valid on z/OS only.
[z/OS]MXTOPIC
[z/OS] Valid only if TYPE is CLASSES. Specifies that topic resources are to be refreshed. Valid on z/OS only.
[z/OS]CMDSCOPE
[z/OS] This parameter applies to z/OS only and specifies how the command is executed when the queue manager is a member of a queue-sharing group.
' '
The command is executed on the queue manager on which it was entered. This is the default value[z/OS] for non-z/OS systems.
qmgr-name
The command is executed 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 executed on the local queue manager and is also passed to every active queue manager in the queue-sharing group. The effect of this is the same as entering the command on every queue manager in the queue-sharing group.
TYPE
Specifies the type of refresh that is to be performed.
Distributed[IBMi]AUTHSERV
Distributed[IBMi]The list of authorizations held internally by the authorization services component is refreshed.

This is the default value.

[z/OS]CLASSES
[z/OS]

IBM MQ in-storage ESM (external security manager, for example RACF® ) profiles are refreshed. The in-storage profiles for the resources being requested are deleted. New entries are created when security checks for them are performed, and are validated when the user next requests access.

You can select specific resource classes for which to perform the security refresh.

This is valid only on z/OS where it is the default.

CONNAUTH

Refreshes the cached view of the configuration for connection authentication.

You must refresh the configuration before the queue manager recognizes the changes.

[IBMi][Windows][UNIX][Linux]On [IBMi]IBM i, UNIX, Linux, and Windows platforms, this is a synonym for AUTHSERV.

See Connection authentication for more information.
SSL
Refreshes the cached view of the Secure Sockets Layer, or Transport Layer Security, key repository and allows updates to become effective on successful completion of the command. Also refreshed are the locations of:
  • the LDAP servers to be used for Certified Revocation Lists
  • the key repository
as well as any cryptographic hardware parameters specified through IBM MQ.

To refresh CHLAUTH use the REFRESH QMGR command.