setmqweb (set mqweb server configuration)

• You can use the setmqweb properties command to configure the mqweb server. Changes to properties take effect dynamically, within a few seconds, unless otherwise stated.
  Attention: When you use the setmqweb properties command to change the property values in the mqwebuser.xml file, you need to ensure that the file is encoded in UTF-8. Using a different encoding corrupts the file during updates.
• You can use the setmqweb remote command to set up remote queue manager connections to use with the IBM® MQ Console.
• You can use the setmqweb pid command to change the product ID (PID) that the mqweb server runs under. By default, on z/OS®, the mqweb server runs under the PID that is chosen when using the crtmqweb command. Before using setmqweb pid you should ensure the mqweb server has been stopped by using the MVS STOP command on the mqweb server started task. See Product usage recording with IBM MQ for z/OS products for more information on PIDs and how they are used on z/OS.

To do this, issue the following command:

export WLP_USER_DIR=WLP_user_directory

where WLP_user_directory is the name of the directory passed to crtmqweb. For example:

export WLP_USER_DIR=/var/mqm/web/installation1

The user ID executing the command needs write access to the following directories:

• WLP_user_directory and its subdirectories.
• /tmp or to another directory that is referenced by the TMPDIR variable. If you do not have access to /tmp, the command fails with message FSUMF315 Cannot define temporary file. If you need to set the TMPDIR variable, issue the following command in the z/OS UNIX shell: export TMPDIR=user_directory

-r

Reset to default values. This parameter removes all user-modified configuration properties from the mqwebuser.xml file.

-k name

The name of the configuration property to add, update, or remove to or from the mqwebuser.xml file. The following values are the valid values for name on all platforms, including the IBM MQ Appliance:

ltpaExpiration

This configuration property is used to specify the time, in minutes, before the LTPA token expires.

The value for this property is an integer value. The default value is 120 minutes.

maxTraceFiles

This configuration property is used to specify the maximum number of mqweb server log files that are generated by the mqweb server.

The value for this property is an integer value. The default value is 2.

maxTraceFileSize

This configuration property is used to specify the maximum size, in MB, that each mqweb server log file can reach.

The value for this property is an integer value. The default value is 200.

mqConsoleMaxMsgCharsToDisplay

This configuration property is used to specify the maximum characters to retrieve from each message when browsing a queue via the IBM MQ Console.

The value for this property is an integer. The default value is 1024.

mqConsoleMaxMsgRequestSize

This configuration property is used to specify the maximum size, in MB, a browse request can be across all messages when browsing queues via the IBM MQ Console.

The value for this property is an integer. The default value is 1.

mqConsoleMaxMsgsPerRequest

This configuration property is used to specify the total number of messages to retrieve from a queue when browsing via the IBM MQ Console.

The value for this property is an integer. The default value is 1000.

mqRestCorsAllowedOrigins

This configuration property is used to specify the origins that are allowed to access the REST API. For more information about CORS, see Configuring CORS for the REST API.

The value for this property is a string value.

mqRestCorsMaxAgeInSeconds

This configuration property is used to specify the time, in seconds, that a web browser can cache the results of any CORS pre-flight checks.

The value for this property is an integer value. The default value is 0.

mqRestCsrfValidation

This configuration property is used to specify whether CSRF validation checks are performed. A value of false removes the CSRF token validation checks.

The value for this property is a boolean value. the default value is true.

mqRestGatewayEnabled

This configuration property is used to specify whether the administrative REST API gateway is enabled.

The value for this property is a boolean value. The default value is true.

mqRestGatewayQmgr

This configuration property is used to specify the name of the queue manager to use as the gateway queue manager. This queue manager must be in the same installation as the mqweb server. A blank value indicates that no queue manager is configured as the gateway queue manager.

The value for this property is a string value. If this value can be interpreted as number or a boolean value, it must be enclosed in double quotation marks.

mqRestMessagingEnabled

This configuration property is used to specify whether the messaging REST API is enabled.

The value for this property is a boolean value. The default value is true.

mqRestMessagingFullPoolBehavior

This configuration property is used to specify the behavior of the messaging REST API when all connections in the connection pool are in use.

The value can be one of the following values:

block

When all the connections in the pool are in use, wait for a connection to become available. When this option is used, the wait for a connection is indefinite.

Inactive connections are closed and removed from a queue manager pool automatically. The state of each queue manager pool is interrogated every 2 minutes, and any connections that have been inactive for the last 30 seconds are closed and removed from the associated pool.

error

When all the connections in the pool are in use, return an error.

overflow

When all the connections in the pool are in use, create a non-pooled connection to use. This connection is destroyed after it is used.

The value for this property is a string value. The default value is overflow.

mqRestMessagingMaxPoolSize

This configuration property is used to specify the maximum connection pool size for each queue manager connection pool.

The value for this property is an integer value. The default value is 20.

mqRestMftCommandQmgr

This configuration property is used to specify the name of the command queue manager to which create transfer and create, delete or update resource monitor requests are submitted by the REST API for MFT.

The value for this property is a string value. If this value can be interpreted as number or a boolean value, it must be enclosed in double quotation marks.

Changes to the value of this property take effect when the mqweb server is next started.

mqRestMftCoordinationQmgr

This configuration property is used to specify the name of the coordination queue manager from which transfer details are retrieved by the REST API for MFT.

The value for this property is a string value. If this value can be interpreted as number or a boolean value, it must be enclosed in double quotation marks.

Changes to the value of this property take effect when the mqweb server is next started.

mqRestMftEnabled

This configuration property is used to specify whether the REST API for MFT is enabled.

The value for this property is a boolean value. The default value is false.

Changes to the value of this property take effect when the mqweb server is next started.

mqRestMftReconnectTimeoutInMinutes

This configuration property is used to specify the length of time, in minutes, after which the REST API for MFT stops trying to connect to the coordination queue manager.

The value for this property is an integer value. The default value is 30.

Changes to the value of this property take effect when the mqweb server is next started.

mqRestRequestTimeout

This configuration property is used to specify the time, in seconds, before a REST request times out.

The value for this property is an integer value. The default value is 30.

mqConsoleEarName

This configuration property is used to switch between the New Web Console and the Dashboard Web Console.

The value for this property is a string value and is "com.ibm.mq.webconsole" to switch to the New Web Console, and "com.ibm.mq.console" to switch to the Dashboard Web Console.

The default value is com.ibm.mq.webconsole.

traceSpec

This configuration property is used to specify the level of trace that is generated by the mqweb server. For a list of possible values, see Configuring logging for the IBM MQ Console and REST API.

The value for this property is a string value. The default value is *=info.

The following values are the additional valid values for name on z/OS, UNIX, Linux®, and Windows:

httpHost

This configuration property is used to specify the HTTP host name as an IP address, domain name server (DNS) host name with domain name suffix, or the DNS host name of the server where IBM MQ is installed.

You can use an asterisk in double quotation marks to specify all available network interfaces.

You can use the value localhost to allow only local connections.

The value for this property is a string value. The default value is localhost.

httpPort

This configuration property is used to specify the HTTP port number that is used for HTTP connections.

You can use a value of -1 to disable the port.

The value for this property is an integer value. The default value is -1.

httpsPort

This configuration property is used to specify the HTTPS port number that is used for HTTPS connections.

You can use a value of -1 to disable the port.

The value for this property is an integer value. The default value is 9443.

ltpaCookieName

This configuration property is used to specify the name of the LTPA token cookie name.

By default, the value of this property is LtpaToken2_${env.MQWEB_LTPA_SUFFIX} on AIX®, Linux, and Windows , or LtpaToken2_${httpsPort} on z/OS. The variable after the LtpaToken2_ prefix is used by the mqweb server to generate a unique name for the cookie. You cannot set this variable, but you can change the ltpaCookieName to a value of your choosing.

The value for this property is a string value.

maxMsgTraceFiles

This configuration property is used to specify the maximum number of messaging trace files that are generated by the mqweb server for the IBM MQ Console.

The value for this property is a integer value. The default value is 5.

maxMsgTraceFileSize

This configuration property is used to specify the maximum size, in MB, that each messaging trace file can reach.

This property only applies to the IBM MQ Console.

The value for this property is a integer value. The default value is 20.

mqConsoleAutostart

This configuration property is used to specify whether the IBM MQ Console automatically starts when the mqweb server starts.

The value for this property is a boolean value. The default value is true.

mqConsoleFrameAncestors

This configuration property is used to specify the list of origins of web pages which can embed the IBM MQ Console in an IFrame. For more information about this property, see embedding the IBM MQ Console in an IFrame.

The value for this property is a string.

mqConsoleRemoteSupportEnabled

This configuration property is used to specify whether the IBM MQ Console allows remote queue manager connections. When this property is set to true, remote queue manager connections are allowed.

The value for this property is a boolean value. The default value is true.

mqConsoleRemoteAllowLocal

This configuration property is used to specify whether remote and local queue managers are visible in the IBM MQ Console when remote queue manager connections are allowed. When this property is set to true, both local and remote queue managers are displayed.

The value for this property is a boolean. The default value is true.

mqConsoleRemotePollTime

This configuration property is used to specify the time, in seconds, before the remote queue manager connections list is refreshed. On refresh, unsuccessful connections are retried.

The value for this property is an integer. The default value is 300.

mqConsoleRemoteUIAdmin

This configuration property is used to specify whether remote queue managers can be added to the IBM MQ Console by using the Console, or if remote queue managers can be added only by using the setmqweb remote command. When this property is set to true, remote queue managers can be added by using the IBM MQ Console.

The value for this property is a boolean. The default value is false.

mqRestAutostart

This configuration property is used to specify whether the REST API automatically starts when the mqweb server starts.

The value for this property is a boolean value. The default value is true.

remoteKeyfile

The location of the key file that contains the initial encryption key that is used to decrypt the passwords that are stored in the remote queue manager connection information.

The initial key is a file that must contain a single line of at least one character. However, you should use a key that is at least 16 characters. For example, your initial key file could contain the following encryption key:

Th1sIs@n3Ncypt|onK$y

Ensure that your key file is adequately protected using the operating system permissions, and that the encryption key is unique to the key file.

If you do not provide a key file, a default key is used.

You can also provide the path to the key file by using the MQS_WEBUI_REMOTE_KEYFILE environment variable.

The key file provided here must match the same key file used to encrypt the password via the -sf parameter below.

secureLtpa

This configuration property is used to specify whether the LTPA token is secured for all requests. An unsecured LTPA token is required in order send HTTP requests from a browser.

The value for this property is a boolean value. The default value is true.

The following values are the additional valid values for name on AIX, Linux, and Windows:

managementMode

This configuration property is used to specify whether queue managers and listeners are able to be created, deleted, started, and stopped by the IBM MQ Console.

The value for this property is a string value and can be one of the following values:

standard

Queue managers and listeners can be created and administered in the IBM MQ Console.

externallyprovisioned

Queue managers and listeners cannot be created in the IBM MQ Console. Only queue managers and listeners that are created outside of the IBM MQ Console can be administered.

The default value is standard.

-d

Deletes the specified configuration property from the mqwebuser.xml file.

-v value

The value of the configuration property to add to, or update in, the mqwebuser.xml file. Any existing configuration properties of the same name are overwritten. Duplicate configuration properties are removed.

The value is case-sensitive. To specify an asterisk, multiple tokens, or an empty value, enclose the value in double quotation marks.

The value that is specified is not validated. If incorrect values are specified a subsequent attempt to start the mqweb server might fail.

Note: The value provided for a configuration property is converted into a Java Object, and some heuristic parsing is applied:

Numbers

If the value is numeric, it is parsed as a Java Number object, such as Integer or Double. Note that a prefix of 0 indicates an octal value, 0x a hexadecimal one, and so on. For example, 0101 becomes an Integer with the decimal value 65.

Booleans

If the value matches true or false, it is parsed as a Boolean object.

Quoted values

If the value is enclosed in double quotation marks, it is parsed as a String object. If a single character is enclosed in single quotation marks, it is parsed as a Character object.

Other values

If none of the previous rules apply, then the value is parsed without change as a String object.

These rules are particularly important when providing string values. If such a value can be interpreted as a number or boolean then you must ensure that it is specified to the setmqweb command in double quotation marks. For example, if you give a queue manager a numeric name or call it TRUE, you must enclose the name in double quotation marks.

You must escape double quotation marks on the command line. For example, you might specify

setmqweb properties -k mqRestGatewayQmgr - v "\"0101\""

to set a gateway queue manager name that resembles a number.

-l

Enable verbose logging. Diagnostic information is written to an mqweb server log file.

add

Add a new entry to the remote queue manager connection information instead of editing an existing entry.

-uniqueName uniqueID

The unique name for the remote queue manager definition.

If this parameter is omitted, the queue manager name must be specified, and the queue manager name is used as the unique name.

The unique name must be specified in the following cases:

• to delete a remote queue manager connection.
• to add a new remote queue manager connection, when a queue manger with the same name already exists in the remote queue manager connection information.
• to modify a remote queue manager connection, when there is more than one queue manager with the same name in the remote queue manager connection information.

-qmgrName qmgrName

The name of the queue manager to add or update.

This parameter must be specified to add a new remote queue manager connection.

-sf keyfilePath

The location of the key file that contains the initial encryption key that is used to encrypt the passwords that are stored in the remote queue manager connection information.

The initial key is a file that must contain a single line of at least one character. However, you should use a key that is at least 16 characters. For example, your initial key file could contain the following encryption key:

Th1sIs@n3Ncypt|onK$y

Ensure that your key file is adequately protected using the operating system permissions, and that the encryption key is unique to the key file.

If you do not provide a key file, a default key is used.

You can also provide the path to the key file by using the MQS_REMOTE_KEYFILE environment variable.

-jsonkey value|-d|-i

jsonkey

The name of the property to add, update, or remove. To add or update a value, specify the value after the jsonkey property. To delete a value, specify the -d flag after the jsonkey property.

There are two types of properties that you can add, update, or remove. The first type are global properties that you can set with the setmqweb remote command without specifying a queue manager name or unique name. The second type are properties that are specific to a single remote queue manager connection. These properties can be set with the setmqweb remote command only if you also specify a queue manager name, a unique name, or both.

The following values are valid jsonkey values that do not require you to specify a queue manager name or unique name in the setmqweb remote command:

globalTrustStorePath

The path to the trust store JKS file. This trust store is used for all remote connections unless it is overridden by specific remote queue manager connection information in the trustStorePath entry..

This value is a string value.

globalTrustStorePassword

The password for the global trust store.

This value is a string value, and it is encrypted in the remote queue manager connection information.

globalKeyStorePath

The path to the key store JKS file. This key store is used for all remote connections unless it is overridden by a specific remote queue manager connection information in the keyStorePath entry.

globalKeyStorePassword

The password for the global key store.

This value is a string value, and it is encrypted in the remote queue manager connection information.

The following values are valid jsonkey values that require you to specify a queue manger name or unique name in the setmqweb remote command:

ccdtURL

The path to the CCDT file that is associated with the remote queue manager.

This value is a string value.

username

The username that is used for the remote queue manager connection.

This value is a string value.

password

The password that is associated with the username that is used for the remote queue manager connection.

This value is a string value, and it is encrypted in the remote queue manager connection information.

enableMutualTLS

Whether this remote queue manager connection should add a key store to enable mutual TLS.

This value is a boolean value.

trustStorePath

The path to the trust store JKS file.

This value is a string value, and it overrides the global trust store value.

trustStorePassword

The password for the trust store file.

This value is a string value, and it is encrypted in the remote queue manager connection information.

keyStorePath

The path to the key store JKS file.

This value is a string value, and it overrides the global key store value.

keyStorePassword

The password for the key store file.

This value is a string value, and it is encrypted in the remote queue manager connection information.

value

The value of the json key entry to add or update.

The values are case-sensitive and must be enclosed in double quotation marks

-d

Delete the specified property from the remote connection information.

-i

Enable interactive mode for the specified json key entry. You are then prompted for the json key value as the command runs.

-d

Delete the connection information for the queue manager with the specified unique name.

-r

Reset and remove all remote connection information.

-l

Enable verbose logging. Diagnostic information is written to an mqweb server log file.

-p pid_name

Specifies the PID that the mqweb server will run under. pid_name should be one of:

MQ

The mqweb server runs under IBM MQ for z/OS (5655-MQ9)

VUE

The mqweb server runs under IBM MQ for z/OS Value Unit Edition (5655-VU9)

ADVANCEDVUE

the mqweb server runs under IBM MQ Advanced for z/OS VUE (5655-AV1)

-l

Enable verbose logging. Diagnostic information is written to an mqweb server log file.

The following example sets the path to the global key store for remote queue manager connections:

setmqweb remote -globalTrustStorePath “c:\supersecure\keys.jks”

The following example creates a new entry for a queue manager, QM2, in the remote queue manager connection information. The example sets the CCDT URL, a username and password to use with the connection, and a key store path:

setmqweb remote add -qmgrName “QM2” -ccdtURL “c:\myccdts\cdt.json” -username “user” -password “password” -keyStorePath “c:\supersecure\keys.jks”

The following example creates a new entry for a different queue manager that is also named QM2, and specifies a unique name to differentiate between the two QM2 queue managers. The example sets the CCDT URL, a username, and a password. The example uses the -i option to interactively enter the password that is associated with the username when the command runs:

setmqweb remote add -uniqueName qm2remote -qmgrName “QM2” -ccdtURL “c:\myccdts\cdt.json” -username “mqadmin” -password -i