mqsicreatebroker command - Windows, Linux and UNIX systems

Syntax

Parameters

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

For restrictions on the character set that you can use, see Characters allowed in commands.

-a ServicePassword
(Required) 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 and UNIX systems -a is required for compatibility with Windows systems, but is not used in relation to ServiceUserID; -a is used as a default only if -p is not specified. (See notes about the -p parameter for further details.)

-i ServiceUserID

You can specify the ServiceUserID in any valid user name syntax. On Windows systems, valid formats 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 systems, 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 that you specify must be a member of the mqbrkrs local group. On Windows systems, the ID 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 parameter).

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

The security requirements for the ServiceUserID are described in Security requirements for Windows platforms for Windows systems, and in Security requirements for Linux and UNIX platforms for Linux and UNIX systems.

-q QueueManagerName
(Required) The name of the queue manager that is 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 they are case sensitive.

Each broker must have its own unique queue manager. A broker cannot share a queue manager with another broker.

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, 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 on which version of WebSphere MQ you are using.

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

For restrictions on the character set that you can use, see Characters allowed in commands.

-n DataSourceName
(Required) 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.

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

-u DataSourceUserID
(Optional) The user ID with which databases that contain broker tables and user data are to be accessed. If this ID is not specified, it defaults to the value that is specified by the -i parameter.

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

On Windows systems, 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 been granted the correct privilege previously. 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.

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 that run in this broker can access and manipulate the application data that is held within it, without having to specify explicit schema names (see Security requirements for Linux and UNIX platforms and Security requirements for Windows platforms for further details).

-p DataSourcePassword
(Optional) The password of the user ID with which databases that contain broker tables and user data are to be accessed. If not specified, this parameter defaults to the ServicePassword that is specified by the -a parameter.

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, you can specify -u and -p 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 parameter is not specified, the broker assumes that there is no User Name Server defined.

-j
(Optional) You must specify this parameter in conjunction with the -s UserNameServerQueueManagerName parameter to enable publish/subscribe access control.
-w Workpath
(Optional) The directory in which working files for this broker are stored. If you do not specify this parameter, files are stored in the default work path, specified when the product was installed. If you specify this parameter, you must create this directory before you start the broker. On Windows systems, this directory cannot be on a networked drive.

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

Error logs that are written by the broker when a process terminates abnormally are stored in this directory. On Windows systems, use this parameter 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 parameter using the mqsichangebroker command. To specify or change the work path, delete and re-create the broker.

-t
(Optional) This parameter requests that the broker is configured to run as a WebSphere MQ trusted application.

If you specify this parameter on Windows systems, add the ServiceUserID (identified by -i parameter) to the mqm group.

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) Migrate an existing WebSphere MQ Publish/Subscribe broker. If you specify this option, the queue manager that is identified by the -q parameter must be the queue manager that is being used by the WebSphere MQ Publish/Subscribe broker.
-l UserLilPath
(Optional) A list of paths (directories) from which the broker loads LILs (loadable implementation libraries) for user-defined message processing nodes.

On Linux and UNIX systems, this name is case sensitive, and you must include the names in single quotes if they contain mixed case characters.

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

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, each directory must be separated by the default platform-specific path separator: semicolon (;) on Windows systems; colon (:) on Linux and UNIX systems.

-g ConfigurationTimeout
(Optional) This parameter defines the length of time (in seconds) that an execution group in the broker can 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 can 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:
mqsireporttrace brokerName -e "Execution Group Name" -u

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 that are 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 timeout values decreases the probability of deploying a configuration change successfully.

-P HTTPListenerPort
(Optional) 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) Specify the timer interval (in minutes) at which WebSphere Event Broker statistics and accounting is notified that archive records are to be output. For internal accounting, the valid range is from 10 to 14400 minutes.

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

-y LdapPrincipal
(Optional, 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, 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 a semicolon (;). On UNIX and Linux systems, the delimiter is a colon (:).
Start of changeDo not use this parameter to set the converter path if you are using a converter that matches one of the built-in converters that are provided with Version 6.0, and that converter is the local code page for the broker. Use the ICU_DATA environment variable instead.End of change

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