setmqweb properties (set mqweb server configuration properties)
Configure the mqweb server properties.
Purpose
You can use the setmqwebproperties command to configure the mqweb server. Changes to properties take
effect dynamically, within a few seconds, unless otherwise stated.
Using the command on z/OS
Before you issue either the setmqweb or dspmqweb commands
on z/OS®, you must set the WLP_USER_DIR environment
variable so that the variable points to your mqweb server configuration.
To set the WLP_USER_DIR environment variable, enter the following
command:
export WLP_USER_DIR=WLP_user_directory
where
WLP_user_directory is the name of the directory that is passed
to crtmqweb. For
example:
You must also set the JAVA_HOME environment variable to reference a 64-bit version of Java on your system.
The user ID running 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
When the setmqweb properties command is used to modify the mqweb server
configuration, the owner of the mqwebuser.xml file is changed to the user ID
that issued the command, and the file permissions are set to the permissions that are indicated by
the user's umask.
Using the command in a stand-alone IBM MQ Web Server
installation
Before you issue either the setmqweb or dspmqweb commands
in a stand-alone IBM® MQ Web Server installation, you must set the
MQ_OVERRIDE_DATA_PATH environment variable to the IBM MQ Web Server data directory.
The user ID running the command needs write access to the data directory and its
subdirectories.
Syntax
Parameters
-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. Some of the following properties
are not available in a stand-alone IBM MQ Web Server
installation.
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.
mqConsoleEnableDashboardBrowse
Some aspects of the MQ Console
dashboard contains information that is only available by browsing queues. This queue browsing
is enabled by default in the IBM MQ Console. If a
particular user does not have the correct authority to browse queues, many log entries can be
generated, recording the failed access. To reduce the load on the logs, you can disable this queue
browsing by setting this property to the string value "false".
mqConsoleEnableSystemTopicMonitoring
This configuration property is used to enable or disable system topic monitoring that is used to
display system information in the IBM MQ Console (see
Metrics published on the system
topics). If system topic monitoring is enabled, more information is available to display in
the queue manager Overview tab in the IBM MQ Console. See Quick tour of the MQ Console.
The value for this property is a string value and is set to "true" to enable
system topic monitoring or "false" to disable it.
mqConsoleMaxMsgCharsToDisplay
This configuration property is used to specify the maximum characters to retrieve from each
message when you browse a queue by using 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 you browse queues by using 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 you browse by using 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.
This property is not valid in a stand-alone IBM MQ Web Server installation. You cannot use the administrative REST API with the stand-alone IBM MQ Web Server.
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.
This property is not valid in a stand-alone IBM MQ Web Server installation. You cannot use the administrative REST API with the stand-alone IBM MQ Web Server.
mqRestMessagingAdoptWebUserContext
This configuration property is used to specify the user context that is used for authorization
when you send, publish, receive, or browse messages by using the messaging REST API. That is, it specifies which user ID is used for
authorization.
The value can be one of the following values:
true
The ID that is used for authorization is the user ID that is logged in to the REST API. MQMD.UserIdentifier is set to
the user ID that is logged in to the REST API, and the
MQMD.AppIdentityData is set to the user ID that is logged in to the REST API.
See MQMD for more information about the
message descriptor parts of the IBM MQ message.
false
The ID that is used for authorization is the user ID that is used to start the mqweb server. The
MQMD.UserIdentifier is left blank, and the
MQMD.AppIdentityData is set to the user ID that is logged in to the REST API.
The value for this property is a Boolean value. The default value is true.
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 nonpooled connection to use. This
connection is deleted 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.
This property is not valid in a stand-alone IBM MQ Web Server installation. You cannot use the REST API for MFT with the stand-alone IBM MQ Web Server.
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.
This property is not valid in a stand-alone IBM MQ Web Server installation. You cannot use the REST API for MFT with the stand-alone IBM MQ Web Server.
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.
This property is not valid in a stand-alone IBM MQ Web Server installation. You cannot use the REST API for MFT with the stand-alone IBM MQ Web Server.
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.
This property is not valid in a stand-alone IBM MQ Web Server installation as the REST API for MFT is not available in this environment.
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.
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. Some of the following
properties are not available in a stand-alone IBM MQ Web Server
installation.
httpHost
This configuration property is used to specify the HTTP hostname as an IP address, domain name
server (DNS) hostname with domain name suffix, or the DNS hostname 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 an 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 applies only to the IBM MQ Console.
The value for this property is an 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 that 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.
This property is not valid in a stand-alone IBM MQ Web Server installation. The IBM MQ Console can be used only with remote queue managers in a
stand-alone IBM MQ Web Server installation.
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.
This property is not valid in a stand-alone IBM MQ Web Server installation. The IBM MQ Console can be used only with remote queue managers in a
stand-alone IBM MQ Web Server installation.
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.
mqRestMessagingConnectionMode
This configuration property is used to specify whether the messaging REST API can send messages to queue managers that are not in
the same installation as the mqweb server.
The value can be one of the following values:
local
The messaging REST API can send messages only to queue
managers that are in the same installation as the mqweb server.
remote
The messaging REST API can send messages to any queue
manager that is configured for use by the messaging REST API.
If the queue manager is in the same installation as the mqweb server, no configuration is required.
For all other queue managers, a remote queue manager definition must exist. For more information
about creating a remote queue manager definition to use with the messaging REST API, see Setting up a remote queue
manager to use with the messaging REST API.
The value is a string value. The default value is local.
The mqweb server must be restarted after this value is set.
This property is not valid in a stand-alone IBM MQ Web Server installation. The messaging REST API can be used only with remote queue managers in a
stand-alone IBM MQ Web Server installation.
remoteKeyfile
This configuration property is used to specify 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 might
contain the following encryption key:
Th1sIs@n3Ncypt|onK$y
Ensure that your key file is adequately protected by 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 that is provided here must match the same key file that is used to encrypt the
password using the -sf parameter.
The mqweb server must be restarted after this value is set.
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 to 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 that is 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. 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 important when you provide 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.
Return codes
Table 1. Return code identifiers and descriptions
Return code
Description
0
Command successful.
>0
Command not successful.
For a full list of server command exit codes, see Liberty:server command options in the WebSphere® Application Server documentation.