mqsicreatebroker command - Windows systems

Use the mqsicreatebroker command to create an integration node on a Windows system.

Syntax

Some parameters have alternative long names; for example, -i and --serviceUserID are alternative parameter names of the user ID under which the integration node runs. The long names available are listed in the Parameters section.

Parameters

integrationNodeName

(Required) The name of the integration node that you are creating. This parameter must be the first parameter. If you create an integration node with an uppercase name, you must also specify the name in uppercase in the IBM® App Connect Enterprise Toolkit.

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

-i | --general-default-user-id serviceUserId

(Optional) The user ID under which the integration node runs.

You can specify the serviceUserId in any valid username syntax:

As a local name:
username

.\username
As a User Principal Name (UPN):
username@domain
As a traditional style of logon name:
domain\username
As a request to a specific server:
\\server\username

If you use the unqualified form for this user ID (username), 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 direct or indirect member of the mqbrkrs local group. The serviceUserId must also be authorized to access the home directory (where IBM App Connect Enterprise is installed), and the working directory (if specified by the -w parameter).

If you specify that the integration node is to run as an IBM MQ trusted application (-t parameter), you must also add the service user ID to the mqm group.

The security requirements for the serviceUserId are described in Security requirements for Windows systems.

-i | --general-default-user-id LocalSystem

(Optional) You can specify LocalSystem instead of serviceUserId.

If you are using a system and you do not specify -i, then the default is LocalSystem.

If you specify LocalSystem, the servicePassword parameter is not required.

If you specify the -e parameter, LocalSystem must not be used. When you specify the -e parameter, you must use a real user ID for the -i option. For Windows, only the -i LocalSystem parameter is available. If you specify the -e parameter for a multi-instance integration node, the system issues an error (BIP8022E: Invalid service user ID and password combination supplied).

Note: Either the LocalSystem or serviceUserId option must be specified for the -i parameter.

-a | --general-default-password generalDefaultPassword

(Required) The password for the serviceUserId. If 'LocalSystem' was specified instead of serviceUserId, the password value is ignored.

For compatibility with existing systems, you can 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. You must enter the password a second time to verify that you entered it correctly.

-q | --queue-manager queueManagerName

(Optional) The name of the queue manager associated with the integration node. Use the same name for your integration node and 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. This queue manager is used by default for IBM MQ processing in the message flow if no queue manager is specified explicitly on the IBM MQ node.

The queue manager that is specified on the integration node is also required for message flow nodes that use system queues to store state information about messages. For example, the CD and WebSphere MQ File Transfer Edition nodes, and for event-driven processing nodes that are used for aggregation and timeout flows, message collections, and message sequences. These nodes require a queue manager to be specified on the integration node, and they also require a set of system queues to be created. You create the queues by running the script iib_createqueues.bat in the install_dir\server\sample\wmq directory. Alternatively, you can create the queues by running the IBM MQ define qlocal command. For more information about using the define qlocal command, see the IBM MQ product information. For more information about the IBM App Connect Enterprise features that require system queues, see mqsicreatebroker command.

If you specify a queue manager that does not exist, you must create it before the flow is deployed.

If the -q parameter is not specified, some features that require access to IBM MQ are not available. For more information about using IBM MQ with IBM App Connect Enterprise, see Enhanced flexibility in interactions with IBM MQ and Installing IBM MQ.

If you create a multi-instance integration node where the queue manager does not exist on the server, a multi-instance queue manager is created beneath the multi-instance integration node shared work path. The multi-instance queue manager is created by using the IBM MQ crtmqm command as follows:

  crtmqm -md \<integration node sharedWorkPath>\mqm\qmdata
         -ld \\<integration node sharedWorkPath>\mqm\qmlog queueManagerName

If this shared queue manager path is not appropriate, create the multi-instance queue manager on the server before you run this command. For more information, see Creating a multi-instance integration node.

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

-w | --workpath workPath

(Optional) The working directory within which work files for this integration node are stored.

If you specify this parameter, a subdirectory with the name of this integration node is created to store its work files. For example, if you specify C:\ACEwork when you create an integration node named MyNode, then the subdirectory that is created is C:\ACEwork\components\MyNode. (This working directory is a subset of the IBM App Connect Enterprise working directory structure; it contains fewer subdirectories and no common\profiles subdirectory.) If you specify a directory name that does not exist, it is created automatically. You must have permission to create this directory, or the command fails and returns an error.

If you do not specify this parameter, the files are stored in a subdirectory of the IBM App Connect Enterprise working directory, which was set when the product was installed. For example, for an integration node, node_name, the default path name for the working directory on Windows is C:\ProgramData\IBM\MQSI\components\node_name.

Note: To verify the IBM App Connect Enterprise working directory, enter the following command in a command console:

echo %MQSI_WORKPATH%

When you enable an integration node for multi-instance mode by using the -e flag, the integration node workPath is used to store data that is specific to this integration node. The integration node workPath is also used to store data that is shared between this integration node and its instances. The instances are created by using the mqsiaddbrokerinstance command. Data that is specific to the multi-instance enabled integration node is stored in the workPath directory on the local server. The shared data is held in a directory on network storage at the location that is specified by using the -e flag.

When you activate tracing, this directory is also used for trace records that are created. These records are written to a subdirectory, log, which you must create before you start the integration node.

Error logs that are written by the integration node when a process ends abnormally are stored in this directory.

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

To change the work path directory after the integration node is configured, you must delete and then re-create the integration node with the new work path directory.

--node-conf-yaml workfile

The configuration file, node.conf.yaml, to be used for the integration node.

When the integration node is created, the file is copied to workpath/components/integrationNodeName/node.conf.yaml. If the node-conf-yaml parameter is not provided, the default node.conf.yaml file is copied.

--vault-key vaultKey

(Optional) This parameter specifies the vault key to be used for creating the vault. If either the --vault-key or --vaultrc-location parameter is specified on the command, an App Connect Enterprise vault is created to hold the credentials that are used by the integration node when it accesses secured resources. For more information about vaults, see: mqsivault command.

--vaultrc-location

(Optional) This parameter specifies the location of the .mqsivaultrc file that is used to locate the vault key. If either the --vault-key or --vaultrc-location parameter is specified on the command, an App Connect Enterprise vault is created to hold the credentials that are used by the integration node when it accesses secured resources. For more information about vaults, see: mqsivault command.

-t | --trusted

(Optional) The integration node runs by using IBM MQ fastpath binding (known as a trusted application.)

For more information about using IBM MQ trusted applications, see the Intercommunication section of the IBM MQ product documentation online.

-m | --migration-required

Indicates that migration is required from an IBM publish/subscribe integration node.

-l --user-lil-path userLilPath

(Optional) A list of paths (directories) from which the integration node loads Loadable implementation libraries (LIL files) for user-defined message processing nodes.

Do not include environment variables in the path; the integration node ignores them.

Create your own directory for storing your .lil or .jar files. Do not save them in the IBM App Connect Enterprise installation directory.

If you specify more than one directory, separate directories by using a semicolon (;).

-P | --http-port httpListenerPort

(Optional) Enter the number of the port on which the web services support is listening.

The integration node starts this listener when a message flow that includes HTTP nodes or web services support is started. The default is 7080.

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

-v | --statistics-major-interval statisticsMajorInterval

(Optional) Specify the interval (in minutes) at which statistics and accounting archive records are to be written. The valid range is 1 - 43200 minutes; the default value is 60.

-y | --ldap-principal 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 | --icu-converter-path 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 (:).

Do not use this parameter to set the converter path if both of the following conditions apply:

You are using a converter that matches one of the built-in converters that are provided.
That converter is the local code page for the integration node.

Use the ICU_DATA environment variable instead.

-x | --user-exit-path userExitPath

(Optional) The path that contains the location of all user exits to be loaded for integration servers in this integration node. This path is added to the system library search path (PATH,LIBPATH,LD_LIBRARY_PATH,SHLIBPATH) for the integration server process only.

-s | --admin-security adminSecurity

(Optional) Preserved for compatibility. To set and view the administration security mode, use the mqsichangeauthmode command and mqsireportauthmode command instead of using this parameter.

Specify the administrative security status for the integration node. If you specify -s active, administration security is enabled. Only user IDs that you authorize have permission to complete actions on the integration node. Read, write, and execute authority is always granted on the integration node to all user IDs that belong to the security group mqbrkrs. When the integration node is created, you can add further user ID authorizations.

If you are using queue-based security, the queue SYSTEM.BROKER.AUTH.integration_server_name is created when you create an integration server on an integration node for which administrative security is enabled. Populate the queue with the appropriate user authorization.

If you specify -s inactive, or omit this parameter, integration node administration security is not enabled. All users are able to complete all actions against the integration node and all integration servers.

If integration node administration security is not enabled, web users can access the web user interface as the default user, with unrestricted access to data and integration node resources.

For more information about security, see Administration security overview and Authorizing users for administration.

-e | --shared-workpath sharedWorkPath

(Optional) Setting this value enables the integration node for the multi-instance mode of operation.

You must specify a queue manager (-q) for the integration node to use this parameter. You must ensure that the integration node has access to this network storage location before you start the integration node. You must also ensure that the queue manager for the integration node is configured as an IBM MQ multi-instance queue manager. The information that is stored in this shared directory includes:

The integration node registry
Component directories
Internal integration node tables and files for deployed message flows
Policy properties.

-d | --mq-managed-service MQService

Note: You must be a member of the mqm group to run the mqsicreatebroker command with the -d parameter.

(Optional) Specify whether you enable an integration node to be started and stopped as an IBM MQ service when the queue manager starts and stops. If you set this parameter, you cannot later change this setting. You must specify a queue manager (-q) for the integration node to use this parameter.

This option is an alternative to starting a multi-instance integration node in standby mode by using the mqsistart command.

If you specify -d defined, the MQ Service is defined to the queue manager, and the integration node starts and stops when the queue manager starts and stops.

Note: Ensure that the mqm user ID is a member of the mqbrkrs operating system group because the integration node is started by the mqm user ID.

If you specify -d undefined, the MQ Service is not defined to the queue manager, and the integration node does not start and stop when the queue manager starts and stops. This setting is the default setting.

For more information about running the integration node as an MQ Service, see Creating a multi-instance integration node.

-C | --ccsid CCSID

(Optional) The internal CCSID of the integration node. The default is set during installation and is based on the values that are set for the locale and language variables. If these variables are not set, a default value of 1208 is used.

-B | --broker-domain-group integrationNodeDomainGroup

(Optional) Use this parameter to set the Windows Domain Group that is used to secure files in the sharedWorkPath of a multi-instance integration node. Use only with -e.

-Q | --queue-manager-domain-group queueManagerDomainGroup

(Optional) Use this parameter to set the Windows Domain Group that is used to secureIBM MQ files in the sharedWorkPath of a multi-instance integration node. Use only with -e, and if the queue manager does not exist and must be created.

-S | --autostart autostart

(Optional) Use this parameter to activate automatic startup of the integration node on system startup. Valid values that you can set are 'yes' and 'no'. The default is 'no'.

--trace traceFileName

(Optional) Use this parameter to send verbose internal trace to the specified file.

Examples

For parameters that have alternative long names, the examples include the syntax for the short names and the alternative long names:

Create an integration node that runs under the serviceUserId wbrkuid with wbrkpw as the password for the serviceUserId:

mqsicreatebroker INODE -i wbrkuid -a wbrkpw

mqsicreatebroker INODE --general-default-user-id wbrkuid --general-default-password wbrkpw

Create an integration node and specify LocalSystem instead of serviceUserId. The servicePassword parameter is not required:

mqsicreatebroker INODE -i LocalSystem

mqsicreatebroker INODE --general-default-user-id LocalSystem

Create an integration node and specify the working directory within which work files for the integration node are stored:

mqsicreatebroker INODE -w C:\myWorkpath

mqsicreatebroker INODE --workpath C:\myWorkpath

Create an integration node and specify the configuration file, node.conf.yaml, to be used for the integration node:

mqsicreatebroker INODE --node.conf.yaml C:\myWorkpath\node.conf.yaml

Create an integration node and specify the vault key to be used for creating the vault:

mqsicreatebroker INODE --vault-key 12345678

Create an integration node with an associated queue manager called myQmgr:

mqsicreatebroker INODE -q myQmgr

mqsicreatebroker INODE --queue-manager myQmgr

Create an integration node to run as a trusted application:

mqsicreatebroker INODE -i wbrkuid -a wbrkpw -t

mqsicreatebroker INODE --general-default-user-id wbrkuid --general-default-password wbrkpw --trusted

Create an integration node. Specify that migration is required from an IBM publish/subscribe integration node:

mqsicreatebroker INODE -i wbrkuid -a wbrkpw -m

mqsicreatebroker INODE --general-default-user-id wbrkuid --general-default-password wbrkpw --migration-required

Create an integration node. Specify a list of directories from which the integration node loads Loadable implementation libraries for user-defined message processing:

mqsicreatebroker INODE -l C:\lildir1;C:\lildir2

mqsicreatebroker INODE --user-lil-path C:\lildir1;C:\lildir2

Create an integration node. Specify the number of the port on which the web services support is listening:

mqsicreatebroker INODE -P 7801

mqsicreatebroker INODE --http-port 7802

Create an integration node. Specify the interval (in minutes) at which statistics and accounting archive records are to be written:

mqsicreatebroker INODE -v 1

mqsicreatebroker INODE --statistics-major-interval 5

Create an integration node. Specify the user principal and the user password for access to LDAP:

mqsicreatebroker INODE -y myldapuser -z myldpapcredentials

mqsicreatebroker INODE –ldap-principal myldapuser -z myldpapcredentials

Create an integration node. Specify a set of directories to search for additional code page converters:

mqsicreatebroker INODE -c C:\icu1;C:\icu2

mqsicreatebroker INODE --icu-converter-path C:\icu1;C:\icu2

Create an integration node that references user exits:

mqsicreatebroker INODE -i wbrkuid -a wbrkpw -x /opt/3rdparty/wmbexits

mqsicreatebroker INODE --general-default-user-id wbrkuid --general-default-password wbrkpw --user-exit-path /opt/3rdparty/wmbexits

Create an integration node with administrative security enabled:

mqsicreatebroker INODE -s active

mqsicreatebroker INODE --admin-security active

Create an integration node. Set the shared workpath (-e) to enable multi-instance operation and specify the Windows Domain Group (-B) that is used to secure files in the shared workpath:

mqsicreatebroker INODE -i "WMB\mqsiuser" -a password -q QM1 -e \\MyServer\\mqsishare -B "WMB\Domain mqbrkrs"

mqsicreatebroker INODE --general-default-user-id "WMB\mqsiuser" --general-default-password password --queue-manager QM1 --shared-workpath \\MyServer\\mqsishare --broker-domain-group "WMB\Domain mqbrkrs"

Create an integration node. Set the shared workpath (-e) to enable multi-instance operation. Specify (-B) the Windows Domain Group that is used to secure files in the shared workpath. Specify (-Q), the Windows Domain Group that is used to secure IBM MQ files in the shared workpath:

mqsicreatebroker INODE -i "WMB\mqsiuser" -a password -q QM1 -e \\MyServer\\mqsishare -B "WMB\Domain mqbrkrs" -Q "WMB\Domain mqm"

mqsicreatebroker INODE --general-default-user-id "WMB\mqsiuser" --general-default-password password --queue-manager QM1 --shared-workpath \\MyServer\\mqsishare --broker-domain-group "WMB\Domain mqbrkrs" --queue-manager-domain-group "WMB\Domain mqm"

Create an integration node. Specify that the integration node is started and stopped as an IBM MQ service when the queue manager starts and stops:

mqsicreatebroker INODE -q myQmgr -d defined

mqsicreatebroker INODE --queue-manager myQmgr --mq-managed-service defined

Create an integration node. Specify the ccsid (Coded character set identifier) for the locale and language variables:

mqsicreatebroker INODE -C 1208

mqsicreatebroker INODE --ccsid 819

Create an integration node. Specify a file to which verbose internal trace for the integration node is sent:

mqsicreatebroker INODE --trace C:\traceDir\myTrace.txt