Use the crtmqm command to create a queue manager and define the default and
system objects. The objects created by the crtmqm command are listed in System and default objects. When
you have created a queue manager, use the strmqm command to start it.
The queue manager is automatically associated with the installation from which the
crtmqm command was issued. To change the associated installation, use the
setmqm command.
From IBM MQ 9.2.0, you can use the environment variable MQLICENSE to
accept or view the license.
The options you can set the MQLICENSE environment variable to are
'accept' or 'view'. Other values are treated as if the environment
variable is not set.
You can also set the MQLICENSE environment variable on the
addmqinf and dspmqinf commands. However, you cannot set this
environment variable directly on the setmqprd command.
Note: You can use this
environment variable only when the licence has not already been accepted in the normal way (that is,
running mqlicense exe). If the license has already been accepted, this
environment variable is ignored regardless of the value.
Syntax
HA RDQM Options
DR RDQM Options
DR/HA RDQM Options
Notes:
1Windows only
2Specify one only of lc, ll, lla, lln, or lr
3AIX and Linux only
Required parameters
QMgrName
The name of the queue manager that you want to create. The name can contain up to 48 characters.
This parameter must be the last item in the command.
Note: The QMgrName is used by IBM MQ
applications, other IBM MQ queue managers, and IBM MQ control commands to identify this queue manager.
No other queue manager with the same name can exist on this machine. Where this queue manager is
going to connect to other queue managers you must ensure that queue manager names are unique within
that group of queue managers.
The QMgrName is also used to name the directories created on disk for the
queue manager. Due to filesystem limitations the name of the directories created might not be
identical to the QMgrName supplied on the crtmqm command.
In these cases the directories created will be based upon the supplied
QMgrName, but might be modified, or have a suffix such as .000
or .001, and so on, added to the queue manager name.
Optional parameters
-a[r] access_group
Use the access group parameter to specify a Windows
security group, members of which will be granted full access to all queue manager data files. The
group can either be a local or global group, depending on the syntax used.
Valid syntax for the group name is as follows:
LocalGroup
Domain name\GlobalGroup name
GlobalGroup name @ Domain name
You must define the additional access group before running the crtmqm command
with the -a [r] option.
If you specify the group using -ar instead of -a, the
local mqm group is not granted access to the queue manager data files. Use this
option if the file system hosting the queue manager data files does not support access control
entries for locally defined groups.
The group is typically a global security group, which is used to provide multi-instance
queue managers with access to a shared queue manager data and logs folder. Use the additional
security access group to set read and write permissions on the folder or to share containing queue
manager data and log files.
The additional security access group is an alternative to using the local group named
mqm to set permissions on the folder containing queue manager data and logs. Unlike
the local group mqm, you can make the additional security access group a local or a
global group. It must be a global group to set permissions on the shared folders that contain the
data and log files used by multi-instance queue managers.
The Windows operating system checks the
access permissions to read and write queue manager data and log files. It checks the permissions of
the user ID that is running queue manager processes. The user ID that is checked depends on whether
you started the queue manager as a service or you started it interactively. If you started the queue
manager as a service, the user ID checked by the Windows
system is the user ID you configured with the Prepare IBM MQ wizard. If you started the queue manager interactively, the
user ID checked by the Windows system is the user ID that
ran the strmqm command.
The user ID must be a member of the local mqm group to start the queue
manager. If the user ID is a member of the additional security access group, the queue manager can
read and write files that are given permissions by using the group.
Restriction: You can specify an additional security access group only on
Windows operating system. If you specify an additional
security access group on other operating systems, the crtmqm command returns an
error.
-c Text
Descriptive text for this queue manager. You can use up to 64 characters; the default is all
blanks.
If you include special characters, enclose the description in single quotation marks. The
maximum number of characters is reduced if the system is using a double-byte character set (DBCS).
-d DefaultTransmissionQueue
The name of the local transmission queue where remote messages are put if a transmission queue is not explicitly defined for their destination. There is no default.
-g ApplicationGroup
On AIX and Linux, the name of the group that
contains members that are allowed to perform the following actions:
Run MQI applications
Update all IPCC resources
Change the contents of some queue manager directories
The default value is -g all, which allows unrestricted access.
The -gApplicationGroup value is recorded in the queue manager configuration
file, qm.ini.
The mqm user ID and the user running the command must belong to the specified
Application Group. For further details of the operation of restricted mode, see Restricted mode.
-h MaximumHandleLimit
The maximum number of handles that an application can open at the same time.
Specify a value in the range 1 - 999999999. The default value is 256.
-ic FilePath
Automatic configuration of MQSC attributes.
Specify the location containing MQSC commands to be automatically applied to the queue manager
on every queue manager restart. This can be a filename, or a directory where each file
*.mqsc is automatically processed. See automatic configuration from an MQSC script
at startup for more details.
-ii FilePath
Automatic configuration of qm.ini file attributes.
Specify a configuration to be automatically applied to the qm.ini file on every queue manager
restart. This can be a filename containing INI format information, or a directory where
*.ini is automatically processed. See automatic configuration from an INI script
at startup for more details.
-iv VARIABLE=VALUE[;VARIABLE=VALUE]
Configuration variable for use with automatic uniform clusters.
Specify a name and associated value for use as an insert during MQSC definitions. This parameter
is only used for CONNAME fields in defining cluster receivers for automatic uniform clusters. For
example:
-iv CONNAME=QMA.host.name(1414)
The next set of parameter descriptions relate to logging, which is described in Using the log for recovery.
Note: Choose the logging arrangements with care, because some cannot be changed after they are
committed. The defaults for the logging options to crtmqm can be overridden by
attributes in the mqs.ini file.
If you specify the logging attributes in the mqs.ini file, those
attributes override the default values of the logging command line parameters to
crtmqm.
-lc
Use circular logging. This method is the default logging method.
-ld LogPath
The directory used to store log files. The default directory to store log paths is defined when
you install IBM MQ.
If the volume containing the log file directory supports file security, the log file directory
must have access permissions. The permissions allow the user IDs, under whose authority the queue
manager runs, read and write access to the directory and its subdirectories. When you install
IBM MQ, you grant permissions to the user IDs and to the
mqm group on the default log directory. If you set the LogPath
parameter to write the log file to a different directory, you must grant the user IDs permission to
read and write to the directory. The user ID and permissions for AIX and Linux are different from those for the Windows system:
AIX and Linux
The directory and its subdirectories must be owned by the user mqm in the group
mqm.
If the log file is shared between different instances of the queue manager, the security
identifiers (sid) that are used must be the same for the different instances. You must have set the
user mqm to the same sid on the different servers running
instances of the queue manager. Likewise for the group mqm.
Windows
If the directory is accessed by only one instance of the queue manager, you must give read and
write access permission to the directory for the following groups and users:
The local group mqm
The local group Administrators
The SYSTEM user ID
To give different instances of a queue manager access to the shared log directory, the queue
manager must access the log directory using a global user. Give the global group, which contains the
global user, read and write access permission to the log directory. The global group is the
additional security access group specified in the -a parameter.
In IBM MQ for Windows systems, the default
directory is C:\ProgramData\IBM\MQ\log (assuming that C: is your data drive). If the volume supports
file security, the SYSTEM ID, Administrators, and mqm group must be granted
read/write access to the directory.
In IBM MQ for AIX or Linux
systems, the default directory is /var/mqm/log. User ID mqm and
group mqm must have full authorities to the log files.
If you change the locations of these files, you must give these authorities yourself. If these
authorities are set automatically, then the log files are in their default locations.
-lf LogFilePages
The log data is held in a series of files called log files. The log file size is specified in
units of 4 KB pages.
In IBM MQ for AIX or Linux
systems, the default number of log file pages is 4096, giving a log file size of 16 MB. The minimum
number of log file pages is 64 and the maximum is 65535.
In IBM MQ for Windows systems, the default
number of log file pages is 4096, giving a log file size of 16 MB. The minimum number of log file
pages is 32 and the maximum is 65535.
Note: The size of the log files for a queue manager specified during creation of that queue manager
cannot be changed.
-ll LinearLogging
Use linear logging.
On Multiplatforms, if you create a
queue manager using the existing -ll option, you need to carry out manual
management of log extents as previously (LogManagement=Manual).
-lla
Use linear logging with automatic management of log extents
(LogManagement=Automatic).
-lln
Use linear logging with archive management of log extents
(LogManagement=Archive).
-lr InstanceName
Use log replication. Specify this option when configuring a Native HA group. The
InstanceName provided is used by Native HA to identify this copy of log data and
must be unique. The InstanceName can contain up to 48 characters. Valid
characters in an InstanceName are:
Uppercase or lowercase alphabetics (A-Z, a-z)
Numeric characters (0-9)
Dash (-), the leading character is not permitted to be a dash
Period (.)
Underscore (_)
Leading or embedded blanks are not permitted.
-lp LogPrimaryFiles
The log files allocated when the queue manager is created.
On a Windows system:
The minimum number of primary log files that you can have is 2 and the maximum is 254.
The total number of primary and secondary log files must not exceed 255 and must not be less
than 3.
On AIX and Linux
systems:
The minimum number of primary log files you can have is 2 and the maximum is 510. The default is
3.
The total number of primary and secondary log files must not exceed 511 and must not be less
than 3.
Operating system limits can reduce the maximum log size.
The value is examined when the queue manager is created or started. You can change it after the
queue manager has been created. However, a change in the value is not effective until the queue
manager is restarted, and the effect might not be immediate.
The log files allocated when the primary files are exhausted.
On a Windows system:
The minimum number of secondary log files that you can have is 1 and the maximum is 253.
The total number of primary and secondary log files must not exceed 255 and must not be less
than 3.
On AIX and Linux
systems:
The minimum number of secondary log files that you can have is 2 and the maximum is 509. The
default is 2.
The total number of primary and secondary log files must not exceed 511 and must not be less
than 3.
Operating system limits can reduce the maximum log size.
The value is examined when the queue manager is started. You can change this value, but changes
do not become effective until the queue manager is restarted, and even then the effect might not be
immediate.
For more information about the use of secondary log files, see What logs look like.
The directory used to hold the data files for a queue manager.
In IBM MQ for Windows systems, the default
is C:\ProgramData\IBM\MQ\qmgrs
(assuming that C: is your data drive). If the volume supports file security,
the SYSTEM ID, Administrators, and mqm group must be granted read/write access to
the directory.
In IBM MQ for AIX or Linux
systems, the default is /var/mqm/qmgrs. User ID mqm and group
mqm must have full authorities to the log files.
For RDQM on Linux systems, the
default is /var/mqm/vols/qmgrname/qmgr/.
The DataPath parameter is provided to assist in the configuration of
multi-instance queue managers. For example, on AIX and Linux systems: if the /var/mqm
directory is located on a local file system, use the DataPath parameter and the
LogPath parameter to point to the shared file systems accessible to multiple
queue managers.
Note: A queue manager created using DataPath parameter runs on versions of the
product earlier than IBM WebSphere® MQ 7.0.1, but the queue manager
must be reconfigured to remove the DataPath parameter. You have two options to
restore the queue manager to a pre-IBM WebSphere MQ 7.0.1
configuration and run without the DataPath parameter: If you are confident
about editing queue manager configurations, you can manually configure the queue manager using the
Prefix queue manager configuration parameter. Alternatively, complete the following
steps to edit the queue manager:
Stop the queue manager.
Save the queue manager data and log directories.
Delete the queue manager.
Backout IBM WebSphere MQ to the pre-IBM WebSphere MQ 7.0.1 fix level.
Create the queue manager with the same name.
Replace the new queue manager data and log directories with the ones you saved.
-oa group|user|UserExternal
On AIX and Linux
systems, you can specify whether group or user authorization is to be used. If you do not set this
parameter, group authorization is used. You can change the authorization model later by setting the
SecurityPolicy parameter in the Service stanza of the
qm.ini file (see Service stanza of the qm.ini file).
From IBM MQ 9.2.1, you can use the
additional option of UserExternal when creating new queue managers. If you select
this option, you can create a non-operating system user name, with a maximum of 12 characters, that:
Can be used both for checking and setting authorizations
If you create a non-operating system user name, that user is considered to
belong to no groups, except the nobody group. See Principals and groups on AIX, Linux, and Windows for more information.
Create a managed TCP listener on the specified port.
Specify a valid port value in the range
1-65535, to create a TCP listener object that uses the specified port. The new listener is called
SYSTEM.LISTENER.TCP.1. This listener is under queue manager control, and is started and stopped
along with the queue manager.
-q
Makes this queue manager the default queue manager. The new queue manager replaces any existing
default queue manager.
If you accidentally use this flag and you want to revert to an existing queue manager as the
default queue manager, change the default queue manager as described in Making an existing queue manager the
default.
-rr InstanceType
Create a disaster recovery replicated data queue manager (DR RDQM). Specify -rr
p to create the primary instance of the queue manager or specify -rr s
to create the secondary instance. You must be root or a user in the
mqm group with sudo privileges to use this command.
Use -rr with the -sx or the
-sxs parameter to create a DR/HA RDQM.
-rt ReplicationType
Optionally specify whether your DR RDQM configuration uses synchronous or asynchronous
replication. Specify -rt s for synchronous and -rt a for
asynchronous. Asynchronous is the default.
-rl LocalIP
Specify the local IP address used for replication of data between primary and secondary
instances of a DR RDQM.
Use -rlLocalIP,LocalIP,LocalIP with the -sx or the
-sxs parameter to create a DR/HA RDQM and specify the three IP addresses used
for DR replication on the local HA group.
-ri RemoteIP
Specify the remote IP address used for replication of data between primary and secondary
instances of a DR RDQM.
Use -riRemoteIP,RemoteIP,RemoteIP with the -sx or the
-sxs parameter to create a DR/HA RDQM and specify the three IP addresses used
for DR replication on the remote HA group. You must specify either the -ri or
the -rn parameter when creating a DR/HA RDQM.
-rn RemoteName
Specifies the name of the system that is hosting the other instance of the queue manager. The
name is the-+ value that is returned if you run uname -n on that server.
Use -rnGroupName with the -sx or the -sxs
parameter to create a DR/HA RDQM and specify name of the remote HA group. The
GroupName refers to the group defined in the DRGroup stanza in the
rdqm.ini file. You must specify either the -rn or the
-ri parameter when creating a DR/HA RDQM.
-rp DRPort
Specifies the port to use for DR replication.
-sa
Automatic queue manager startup. For Windows systems
only.
The queue manager is configured to start automatically when the IBM MQ Service starts.
This is the default option if you create a queue manager from IBM MQ Explorer.
Queue managers created in releases earlier than IBM WebSphere MQ 7 retain their existing startup type.
-sax
Automatic queue manager startup, permitting multiple instances. For Windows systems only.
The queue manager is configured to start automatically when the IBM MQ Service starts.
If an instance of the queue manager is not already running the queue manager starts, the
instance becomes active, and standby instances are permitted elsewhere. If a queue manager instance
that permits standbys is already active on a different server, the new instance becomes a standby
instance.
Only one instance of a queue manager can run on a server.
Queue managers created in versions of the product earlier than IBM WebSphere MQ 7.0.1 retain their existing startup type.
-si
Interactive (manual) queue manager startup.
The queue manager is configured to start only when you manually request startup by using the
strmqm command. The queue manager runs under the (interactive) user when that
user is logged-on. Queue managers configured with interactive startup end when the user who started
them logs off.
-ss
Service (manual) queue manager startup.
A queue manager configured to start only when manually requested by using the
strmqm command. The queue manager then runs as a child process of the service
when the IBM MQ Service starts. Queue managers
configured with service startup continue to run even after the interactive user has logged off.
This is the default option if you create a queue manager from the command line.
-sx [DR parameters][-fs
FilesystemSize]
Create a high availability replicated data queue manager (HA RDQM) on the primary node for that
queue manager (do not specify DR parameters). RDQM is a high availability solution that is available
on Linux only. See Creating an HA RDQM for more details
about creating an RDQM. You must be root or a user in the mqm
group with sudo privileges to use this command. The default size for file system
size is 3 GB. You can specify a different file system size using the -fs option.
The default unit is GB (so -fs 8 creates an 8 GB file system size). You can specify
a different unit, for example, specify -fs 1024M to create a 1024 MB file system
size. The queue manager is started automatically.
Specify DR parameters to create a DR/HA RDQM on the primary node for that queue manager. See
Creating DR/HA RDQMs for details. The DR
parameters are -rr, -ri, -rl,
-rn, -rp.
-sxs [DR parameters][-fs
FilesystemSize]
Create a replicated data queue manager (RDQM) on a secondary node (do not specify DR
parameters). RDQM is a high availability solution that is available on Linux only. See Creating an HA RDQM for more details
about creating an RDQM. You must be the root user to use this command. The default
size for file system size is 3 GB. The default size for file system size is 3 GB. You can specify a
different file system size using the -fs option. The default unit is GB (so
-fs 8 creates an 8 GB file system size). You can specify a different unit, for
example, specify -fs 1024M to create a 1024 MB file system size.
Specify DR parameters to create a DR/HA RDQM on a secondary node. See Creating DR/HA RDQMs for details. The DR
parameters are -rr, -ri, -rl,
-rn, -rp.
-t IntervalValue
The trigger time interval in milliseconds for all queues controlled by this queue manager. This
value specifies the length of time triggering is suspended, after the queue manager receives a
trigger-generating message. That is, if the arrival of a message on a queue causes a trigger message
to be put on the initiation queue, any message arriving on the same queue within the specified
interval does not generate another trigger message.
You can use the trigger time interval to ensure that your application is allowed sufficient time
to deal with a trigger condition before it is alerted to deal with another trigger condition on the
same queue. You might choose to see all trigger events that happen; if so, set a low or zero value
in this field.
Specify a value in the range 0 - 999999999. The default is 999999999 milliseconds; a time of
more than 11 days. Allowing the default to be used effectively means that triggering is disabled
after the first trigger message. However, an application can enable triggering again by servicing
the queue using a command to alter the queue to reset the trigger attribute.
-u DeadLetterQueue
The name of the local queue that is to be used as the dead-letter (undelivered-message) queue.
Messages are put on this queue if they cannot be routed to their correct destination.
The default is no dead-letter queue.
-x MaximumUncommittedMessages
The maximum number of uncommitted messages under any one sync point. The uncommitted messages
are the sum of:
The number of messages that can be retrieved from queues
The number of messages that can be put on queues
Any trigger messages generated within this unit of work
This limit does not apply to messages that are retrieved or put outside a sync point.
Specify a value in the range 1 - 999999999. The default value is 10000 uncommitted messages.
-z
Suppresses error messages.
This flag is used within IBM MQ to suppress unwanted error messages. Do not use this flag when using a command line. Using this flag can result in a loss of information.
Return codes
Table 1. Return code identifiers and descriptions
Return code
Description
0
Queue manager created
8
Queue manager exists
18
Invalid trigger interval
19
Invalid dead letter queue
20
Invalid default transmit queue
21
Invalid max handles value
22
Invalid max uncommitted messages value
25
Error creating the queue manager directory structure
37
Invalid queue manager description
38
The access group specified cannot be found
39
Invalid parameter specified
49
Queue manager stopping
58
Inconsistent use of installations detected
63
Invalid Native HA instance name
69
Storage unavailable
70
Queue space unavailable
71
Unexpected error
72
Queue manager name error
74
The IBM MQ service is not
started
93
Log replication is unavailable on this platform
95
Log replication is incompatible with RDQM
100
Log location invalid
105
The queue manager was created but could not be set as the default queue
manager
111
Queue manager created. However, there was a problem processing the default queue
manager definition in the product configuration file. The default queue manager specification might
be incorrect
115
Invalid log size
119
Permission denied ( Windows only)
155
The group ID specified is not valid
156
The owning group ID can only be changed on AIX and Linux systems
157
The group ID chosen is invalid
Examples
The following command creates a default queue manager called
Paint.queue.manager, with a description of Paint shop, and creates
the system and default objects. It also specifies that linear logging is to be used:
crtmqm -c "Paint shop" -ll -q Paint.queue.manager
The following command creates a default queue manager called
Paint.queue.manager, creates the system and default objects, and requests two
primary and three secondary log files:
The following command creates a queue manager called travel, creates the system
and default objects, sets the trigger interval to 5000 milliseconds (5 seconds), and specifies
SYSTEM.DEAD.LETTER.QUEUE as its dead-letter queue.
crtmqm -t 5000 -u SYSTEM.DEAD.LETTER.QUEUE travel
The following command creates a queue manager called QM1
on AIX and Linux systems, which has log and queue
manager data folders in a common parent directory. The parent directory is to be shared on highly
available networked storage to create a multi-instance queue manager. Before issuing the command,
create other parameters /MQHA, /MQHA/logs and
/MQHA/qmgrs owned by the user and group mqm, and with
permissions rwxrwxr-x.