mqsicreatebroker command

Supported platforms

Purpose

The mqsicreatebroker command:
  • Creates a WebSphere MQ queue manager, except on z/OS, if one does not already exist.
    Note:
    1. If a WebSphere MQ queue manager is created as a result of using the mqsicreatebroker command, the default DLQ provided by WebSphere MQ (SYSTEM.DEAD.LETTER.QUEUE) is automatically enabled. The security settings are the same as those of other broker-specific WebSphere MQ queues.

      If you choose to create the queue manager separately, you must set up a dead letter queue (DLQ). The DLQ is referenced by WebSphere Event Broker when errors occur processing messages in message flows.

      If a message in either a user-defined message flow or in the publish/subscribe model cannot be processed, it is routed to this DLQ as a last resort. If you prefer to back out the message onto the input queue, effectively halting the message flow until the problem is resolved, disable the DLQ.

      The mqsideletebroker command does not delete this queue (unless the queue manager is deleted).

    2. If you are using a WebSphere MQ queue manager that has been created independently of the mqsicreatebroker command, you can define clusters if you choose. This simplifies your configuration in most cases.

  • Starts the WebSphere MQ queue manager, except on z/OS, if it is not already running.

    If the queue manager is created by this command, it is not started as a Windows service; it will therefore stop if you log off. To avoid this happening, you must either remain logged on, or change the startup status of the queue manager service. (If you lock your workstation, the WebSphere MQ queue manager does not stop.)

  • Creates the broker-specific WebSphere MQ queues, if these do not already exist.
  • Creates database tables for the broker, if they do not already exist, or adds rows specific to this broker to existing tables.
  • On Windows platforms, installs a service under which the broker will run.
  • Creates a record for the component in the broker registry.

Syntax

Windows platforms, Linux, and UNIX systems

z/OS console command

Parameters

brokername
(Required) The name of the broker that you want to create. This must be the first parameter, and it is case sensitive on Linux and UNIX systems.

On z/OS, if you create an uppercase broker name, you must use this name in uppercase also for your broker in the workbench.

For restrictions on the character set that can be used, see Characters allowed in commands.
-i ServiceUserID
(Required - Windows platforms, Linux, and UNIX systems) The user ID under which the broker will run.

This can be specified in any valid username syntax. On Windows platforms these are:

  • domain\username
  • \\server\username
  • .\username
  • username

On Linux and UNIX systems, only the last format, username, is valid.

If you use the unqualified form for this user ID (username) on Windows platforms, the operating system searches for the user ID throughout its domain, starting with the local system. This search might take some time to complete.

The ServiceUserID specified must be a member of the local group mqbrkrs. On Windows platforms, it can be a direct or indirect member of the group. The ServiceUserID must also be authorized to access the home directory (where WebSphere Event Broker has been installed), and the working directory (if specified by the -w flag).

If you specify, on Windows platforms, that the broker is to run as a WebSphere MQ trusted application (flag -t), you must also add this user ID to the group mqm. On Linux and UNIX systems, specify the ServiceUserID as mqm if you set the -t flag.

The security requirements for the ServiceUserID are detailed in Security requirements for Windows platforms.

If you use this user ID for database access (that is, you do not specify a different user ID with the -u flag) and you are using SQL Server for your database, you must create this user ID as an SQL Server login ID and give it the correct access before you create the broker (see Considering security for a broker for further details). If your broker database exists in DB2, and this user ID is not known to DB2, DB2 automatically creates if for you.

-a ServicePassword
(Required - Windows platforms, Linux, and UNIX systems) The password for the ServiceUserID.

For compatibility with existing systems, you can still specify <password>. However, if you do not specify a password with this parameter when you run the command you are prompted to enter a password during its invocation, and to enter the password a second time to verify that you have entered it correctly.

On Linux andUNIX systems -a is required for Windows platforms compatibility, but is not used in relation to ServiceUserID; it is used as a default only if -p is not specified. (See notes about the -p parameter for further details.)

-q QueueManagerName
(Required) The name of the queue manager associated with this broker. Use the same name for your broker and the queue manager to simplify the organization and administration of your network. Queue manager names are limited to 48 characters in length and are case sensitive.

Start of changeEach broker must have its own unique queue manager. A broker cannot share a queue manager with another broker. End of change

If the queue manager does not already exist, it is created by this command. It is not created as the default queue manager; if you want this queue manager to be the default queue manager on this system, you must either create the queue manager before you issue this command, or change the settings of this queue manager to make it the default. Use either the WebSphere MQ Explorer or the WebSphere MQ Services snap-in, depending which version of WebSphere MQ you are using.

The queue manager attribute MAXMSGLN (maximum length of messages that can be put to queues) is updated to 100 MB. This is done whether or not the queue manager is created by this command.

For restrictions on the character set that can be used, see Characters allowed in commands.

-n DataSourceName
(Required - Windows platforms, Linux, and UNIX systems) The ODBC data source name (DSN) of the database in which the broker tables are created. This must be the DSN, not the name of the database, if you have not used the same name for both.

This database must already exist. You must create a System DSN ODBC connection for this DSN, if you have not already done so.

If you have a DB2 database on Linux, enter the appropriate DB database alias name; an ODBC DSN is not required.

-u DataSourceUserID
(Optional - Windows platforms, Linux, and UNIX systems) The user ID with which databases containing broker tables and user data are to be accessed. If this is not specified, it defaults to the value specified by -i.

This user ID must have the authority to create tables within this database, and read from and write to those tables.

On Windows platforms, if your broker database exists in DB2, and this user ID is not known to DB2, it is created for you within DB2. On Linux and UNIX systems, the service user must have previously been granted the correct privilege. If your database is SQL Server, you must create this user ID as an SQL Server login ID and give it the correct access before you create the broker (see Security requirements for Windows platforms for further details).

If you have an application database in DB2 that was created by this user ID, or to which this user ID has appropriate read, write, or create authority, message flows executing in this broker can access and manipulate the application data held within it without having to specify explicit schema names.

Start of change-n DB2LocationEnd of change
Start of change(Required - z/OS) The location of the database in which the broker tables are created. End of change
Start of change-u DB2TableOwnerEnd of change
Start of change(Required - z/OS) The user ID with which databases containing broker tables and user data are to be accessed.

This user ID must have the authority to create tables within this database, and read from and write to those tables.

If you have an application database in DB2 that was created by this user ID, or to which this user ID has appropriate read, write, or create authority, message flows executing in this broker can access and manipulate the application data held within it without having to specify explicit schema names.

End of change
-p DataSourcePassword
(Optional - Windows platforms, Linux and UNIX systems) The password of the user ID with which databases containing broker tables and user data are to be accessed. If not specified, this defaults to the ServicePassword specified by -a.

For compatibility with existing systems, you can still specify <password>. However, if you do not specify a password with this parameter when you run the command you are prompted to enter a password during its invocation, and to enter the password a second time to verify that you have entered it correctly.

For DB2 on Linux and UNIX systems, -u and -p can be specified as empty strings (two double quotation marks "") . In this case, DB2 grants WebSphere Event Broker the privileges of the ServiceUserID, which results in a database connection as "already verified". If you specify -a as an empty string as well as -u and -p, no passwords are stored by WebSphere Event Broker, creating the most secure configuration.

-s UserNameServerQueueManagerName
(Optional) The name of the WebSphere MQ queue manager that is associated with the User Name Server. You must specify this parameter if you require either authentication services or publish/subscribe access control. If this is not specified, the broker assumes that there is no User Name Server defined.
-j
(Optional) You must specify this flag in conjunction with the -s UserNameServerQueueManagerName parameter to enable publish/subscribe access control.
-w Workpath
(Optional - Windows platforms, Linux, and UNIX systems) The directory in which working files for this broker are stored. If this is not specified, files are stored in the default workpath, specified when the product was installed. If specified, you must create this directory before you start the broker. On Windows platforms, this cannot be on a networked drive.

This directory is also used for trace records created when tracing is active. These are written to a subdirectory log, which you must create before you start the broker.

Error logs written by the broker when a process terminates abnormally are stored in this directory. On Windows platforms, use this option, to specify a directory on a drive other than the one on which the product is installed.

The error log is unbounded and continues to grow. Check this directory periodically and clear out old error information.

You cannot change this option using the mqsichangebroker command. If you want to specify, or change, the workpath, delete and recreate the broker.

-t
(Optional - Windows platforms, Linux, and UNIX systems) The broker is configured to run as a WebSphere MQ trusted application.

If you specify this option on Windows platforms, add the ServiceUserID (identified by flag -i) to the group mqm. If you specify this option on HP-UX and Solaris, specify the ServiceUserID as mqm. For more details about using WebSphere MQ trusted applications, see WebSphere MQ Intercommunication.

-m
(Optional -Windows platforms, Linux, and UNIX systems) Migrate an existing WebSphere MQ Publish/Subscribe broker. If you specify this option, the queue manager identified by -q must be the queue manager being used by the WebSphere MQ Publish/Subscribe broker.
-l UserLilPath
(Optional - Windows platforms, Linux, and UNIX systems) A list of paths (directories) from which the broker loads LILs (loadable implementation libraries) for user-defined message processing nodes.

You must create your own directory for storing your .lil or .jar files. Do not save them in the WebSphere Event Broker install directory.

If you specify more than one additional directory, they must be separated by the default platform-specific path separator (semicolon (;) on Windows platforms, colon (:) on Linux and UNIX systems).

You cannot include environment variables in this path: if you do so, they are ignored.

-g ConfigurationTimeout
(Optional) The length of time (in seconds) that an execution group in the broker is allowed to take to apply a change in configuration (for example, an update that you have deployed from the workbench).

When a message flow is processing an application message, it cannot respond to a configuration change. If any one of the message flows within the execution group that has been requested to change its configuration does not finish processing an application message and apply the configuration change within this timeout, the execution group returns a negative response to the deployed configuration message.

The value that you set for this timeout depends on the system load (including CPU utilization) and on each execution group's load. You can make an initial estimate by deploying the broker's entire configuration. The time taken for this to complete successfully gives you an indication of the minimum value to set.

The value is specified in seconds and can range from 10 to 3600. The default value is 300.

The sum of the ConfigurationTimeout and the ConfigurationDelayTimeout (described below) represents the maximum length of time that a broker is allowed to process a deployed configuration message before it generates a negative response.

-k ConfigurationDelayTimeout
(Optional) The length of time (in seconds) that a broker is allowed to take to process a minimal change in configuration (for example, an update that you have deployed from the workbench).

This represents the time it takes for a minimal deployed configuration message to be processed by the broker and its execution groups, and depends on queue manager network delays, the load on the broker's queue manager, and system load.

You can estimate this value by issuing a command to request a simple configuration change, for example:
  • On Windows platforms, Linux, and UNIX systems
    mqsireporttrace brokerName -e "Execution Group Name" -u
  • On z/OS
    F MQP1BRK,reporttrace u=yes,e='exgrp1'

The response time of each execution group differs according to system load and the load of its own processes. The value that you set must reflect the longest response time that any execution group takes to respond. If the value that you set is too low, the broker returns a negative response, and might issue error messages to the local error log.

The value is specified in seconds and can range from 10 to 3600. The default value is 60.

If the broker is on a production system, increase the values for both ConfigurationTimeout and ConfigurationDelayTimeout to allow for application messages currently being processed by message flows to be completed before the configuration change is applied.

If the broker is on a development or test system, you might want to reduce time-outs (in particular, the ConfigurationTimeout) to improve perceived response times, and to force a response from a broker that is not showing expected behavior. However, reducing the time-out values decreases the probability of successfully deploying a configuration change.

-P HTTPListenerPort
(Optional - Windows platforms, Linux, and UNIX systems) Enter the number of the port on which the Web services support is listening.

This listener is started by the broker when a message flow that includes Web services support is started, and has a default value of 7080.

Ensure that the port that you specify has not been specified for any other purpose.

-v statisticsMajorInterval
(Optional) The timer interval in minutes at which WebSphere Event Broker statistics and accounting is told to output archive records. For internal accounting, the valid range is from 10 to 14400 minutes.

An interval of zero minutes indicates that the platform has an external method of notification and is not using an internal timer within WebSphere Event Broker.

Start of change-1 End of change
Start of change(Optional - z/OS only) The registry pass, which creates only the broker registry.End of change
Start of change-2 End of change
Start of change(Optional - z/OS only) The WebSphere MQ pass, which creates only the broker WebSphere MQ queues.End of change
Start of change-3 End of change
Start of change(Optional - z/OS only) The DB2 pass, which creates only the broker DB2 tables and indexes.End of change
-y LdapPrincipal
(Optional - all platforms, but mandatory when LdapCredentials is provided.) The user principal for access to an optional LDAP directory that holds the JNDI administered Initial Context for the JMS provider.
-z LdapCredentials
(Optional - all platforms, but mandatory when LdapPrincipal is provided.) The user password for access to LDAP.
-c ICUConverterPath
(Optional) A delimited set of directories to search for additional code page converters. On Windows systems the delimiter is ";". On UNIX and Linux systems, the delimiter is ":". The code page converters must be either of the form icudt32_codepagename.cnv or in an ICU data package called icudt32.dat.

Authorization

On Windows systems, the user ID used to invoke this command must have Administrator authority on the local system.

On UNIX systems, the user ID used to invoke this command must be a member of the mqbrkrs group.

On z/OS systems, the user ID used to invoke this command must be a member of a group that has READ and WRITE access to the component directory.

Using LDAP: Ensure that the registry is appropriately secured to prevent unauthorized access. The setting of LdapPrincipal and LdapCredentials options on mqsicreatebroker is not required for correct operation of the broker. The password is not stored in clear text in the file system.

Websphere MQ queues created

  • SYSTEM.BROKER.ADMIN.QUEUE
  • SYSTEM.BROKER.CONTROL.QUEUE
  • SYSTEM.BROKER.EXECUTIONGROUP.QUEUE
  • SYSTEM.BROKER.EXECUTIONGROUP.REPLY
  • SYSTEM.BROKER.INTERBROKER.QUEUE
  • SYSTEM.BROKER.INTERBROKER.MODEL.QUEUE
  • SYSTEM.BROKER.MODEL.QUEUE
  • SYSTEM.BROKER.WS.INPUT
  • SYSTEM.BROKER.WS.REPLY
  • SYSTEM.BROKER.WS.ACK

Access authority is granted for the WebSphere Event Broker group mqbrkrs to all these queues. If the DLQ is enabled, it also has the same authority.

Database tables created

The database tables that this command creates, or adds to, are described in Database contents.

Responses

This command returns the following responses:

  • BIP8011 Unable to create configuration data
  • BIP8012 Unable to connect to system components
  • BIP8014 Component cannot be created
  • BIP8022 Invalid user ID/password
  • BIP8030 Unable to modify user ID privileges
  • BIP8040 Unable to connect to database
  • BIP8048 Unable to start queue manager
  • BIP8050 Unable to create queue manager
  • BIP8051 Unable to create queue
  • BIP8053 Unable to set security for queue manager
  • BIP8054 Unable to set security for queue
  • BIP8056 Unknown queue manager
  • BIP8070 Database exception
  • BIP8072 Database exception
  • BIP8073 Invalid broker name
  • BIP8084 Unable to create directory
  • BIP8086 Queue manager in use
  • BIP8087 Component already exists
  • BIP8093 Queue manager being created
  • BIP8094 Queue manager stopping
In some circumstances, you might see the following error message issued by DB2:
    (51002)[IBM][CLI Driver][DB2/NT]SQL0805N
    Package "NULLID.SQLLF000" was not found.  SQLSTATE=51002.

This error occurs when the bind to the database is not successful.

On Windows platforms, binding is not needed for broker databases, but is required for user databases. If you have created the database using the DB2 Control Center, the bind is completed for you. If you use the command interface, it is not. For the database MYDB, for example, you can create or re-create a bind by entering the following commands at the command prompt:

db2 connect to MYDB user db2admin using db2admin
db2 bind X:\sqllib\bnd\@db2cli.lst grant public
db2 connect reset

where X: is the drive on which DB2 is installed.

On UNIX platforms, binding is necessary for all databases. For the database WBRKBKDB, for example, you can effect this by entering the following commands at the command prompt (where <user_name> is the user ID under which the database instance was created):

db2 connect to WBRKBKDB user db2admin using db2admin
db2 bind ~<user_name>/sqllib/bnd/@db2cli.lst grant public CLIPKG 5
db2 connect reset

If you are not using the default DB2 user ID and password (db2admin), you must replace these values in the db2 connect command with the correct values.

If you run the mqsicreatebroker command for a second time because of a failure the first time, you receive a series of messages. These indicate any items that cannot be created. There should not be any detrimental effects as a result of this. For example, as long as the reason for the first failure has been resolved, attempting to create a broker which failed the first time should result in a properly created broker.

Examples

mqsicreatebroker WBRK_BROKER -i wbrkuid -a wbrkpw -q WBRK_QM -s WBRK_UNS_QM -n WBRKBKDB
mqsicreatebroker WBRK_BROKER -i wbrkuid -a wbrkpw -q WBRK_QM -n WBRKBKDB -t
Start of change
To create an entire broker on z/OS:
mqsicreatebroker CSQ1BRK -q CSQ1 -u BRKUSER -n DBA0
End of change
Start of change
To create only the DB2 tables and indexes on z/OS:
mqsicreatebroker CSQ1BRK -q CSQ1 -u BRKUSER -n DBA0 -2
End of change
Related concepts
Broker domains