Sun Java System Message Queue 3.7 UR1 Administration Guide

Chapter 7 Managing Security

You manage security by configuring a user repository to authenticate users, to define access control, to configure a Secure Socket Layer (SSL) connection service that encrypts client-broker communication, and to set up a password file for use in broker startup.

The chapter includes the following sections:

User Authentication

When a user attempts to connect to the broker, the broker authenticates the user by inspecting the name and password provided. The broker grants the connection if the name and password match those in a broker-specific user repository that each broker is configured to consult.

You are responsible for maintaining a list of users, their groups, and their passwords in a user repository. You can use a different user repository for each broker instance. This section explains how you create, populate, and manage that repository.

The repository can be one of the following types:

Using a Flat-File User Repository

Message Queue provides a flat-file user repository and a command line tool, the User Manager utility (imqusermgr), that you can use to populate and manage the flat-file user repository. The following sections describe the flat-file user repository and how you use the User Manager utility to populate and manage that repository.

Creating a User Repository

The flat-file user repository is instance-specific. A default user repository (named passwd) is automatically created for each broker instance that you start. This user repository is placed in a directory identified by the name of the broker instance with which the repository is associated (see Appendix A, Platform-Specific Locations of Message QueueTM Data):


The repository is created with two entries. Each row of Table 7–1 shows an entry.

Table 7–1 Initial Entries in User Repository

User Name 












These initial entries allow the Message Queue broker to be used immediately after installation without intervention by the administrator:

The following sections explain how you populate and manage a flat-file user repository.

User Manager Utility

The Message Queue User Manager utility (imqusermgr) lets you edit or populate a flat-file user repository. This section introduces the User Manager utility. Subsequent sections explain how you use the imqusermgr subcommands to accomplish specific tasks.

For full reference information about the imqusermgr command, see Chapter 13, Command Line Reference

Before using the User Manager, keep the following things in mind:

Note –

Examples in the following sections assume the default broker instance.


The imqusermgr command has the subcommands add, delete, list, and update.

Command Options

Table 7–2 lists the options to the imqusermgr command.

Table 7–2 imqusermgr Options



-a activeState

Specifies (true/false) whether the user’s state should be active. A value of true means that the state is active. This is the default.


Performs action without user confirmation. 


Displays usage help. Nothing else on the command line is executed. 

-i instanceName

Specifies the broker instance name to which the command applies. If not specified, the default instance name, imqbroker, is assumed.

-p passwd

Specifies the user’s password. 

-g group

Specifies the user group. Valid values are admin, user, anonymous.


Sets silent mode. 

-u userName

Specifies the user name. 


Displays version information. Nothing else on the command line is executed. 


When adding a user entry to the user repository for a broker instance, you can specify one of three predefined groups: admin, user, or anonymous. If no group is specified, the default group user is assigned. Groups should be assigned as follows:

To change a user’s group, you must delete the user entry and then add another entry for the user, specifying the new group.

You cannot rename or delete these system-created groups, or create new groups. However, you can specify access rules that define the operations that the members of that group can perform. For more information, see User Authorization: The Access Control Properties File.

User States

When you add a user to a repository, the user’s state is active by default. To make the user inactive, you must use the update command. For example, the following command makes the user JoeD inactive:

imqusermgr update -u JoeD -a false

Entries for users that have been rendered inactive are retained in the repository; however, inactive users cannot open new connections. If a user is inactive and you add another user who has the same name, the operation will fail. You must delete the inactive user entry or change the new user’s name or use a different name for the new user. This prevents you from adding duplicate user names.

Format of User Names and Passwords

User names and passwords must follow these guidelines:

Populating and Managing a User Repository

Use the add subcommand to add a user to a repository. For example, the following command adds the user Katharine with the password sesame to the default broker instance user repository.

imqusermgr add -u Katharine -p sesame -g user

Use the delete subcommand to delete a user from a repository. For example, the following command deletes the user, Bob:

imqusermgr delete -u Bob

Use the update subcommand to change a user’s password or state. For example, the following command changes Katharine’s password to aladdin:

imqusermgr update -u Katharine -p aladdin

To list information about one user or all users, use the list command. The following command shows information about the user named isa:

imqusermgr list -u isa

% imqusermgr list -u isa

User repository for broker instance: imqbroker
User Name    Group    Active State
isa          admin    true

The following command lists information about all users:

imqusermgr list

% imqusermgr list

User repository for broker instance: imqbroker
User Name    Group        Active State
admin        admin        true
guest        anonymous    true
isa          admin        true
testuser1    user         true
testuser2    user         true
testuser3    user         true
testuser4    user         false
testuser5    user         false

Changing the Default Administrator Password

For the sake of security, you should change the default password of admin to one that is known only to you. The following command changes the default administrator password for the mybroker broker instance from admin to grandpoobah.

imqusermgr update mybroker -u admin -p grandpoobah

You can quickly confirm that this change is in effect by running any of the command line tools when the broker instance is running. For example, the following command will prompt you for a password:

imqcmd list svc mybroker -u admin

Entering the new password (grandpoobah) should work; the old password should fail.

After changing the password, you should supply the new password any time you use any of the Message Queue administration tools, including the Administration Console.

Using an LDAP Server for a User Repository

To use an LDAP server for a user repository, you perform the following tasks:

Editing the Instance Configuration File

To have a broker use a directory server, you set the values for certain properties in the broker instance configuration file, These properties enable the broker instance to query the LDAP server for information about users and groups whenever a user attempts to connect to the broker instance or perform messaging operations.

The instance configuration file is located in a directory under the broker instance directory. The path has the following format:



For information about the operating system-specific location of instance directories, see Appendix A, Platform-Specific Locations of Message QueueTM Data

ProcedureTo Edit the Configuration File to Use an LDAP Server

  1. Specify that you are using an LDAP user repository by setting the following property:

  2. Set the imq.authentication.type property to determine whether a password should be passed from client to broker in base-64 (basic ) or MD5 (digest) encoding. When using an LDAP directory server for a user repository, you must set the authentication type to basic . For example,

  3. You must also set the broker properties that control LDAP access. These properties are stored in a broker’s instance configuration file. The properties are discussed under Security Services and summarized under Security Properties.

    Message Queue uses JNDI APIs to communicate with the LDAP directory server. Consult JNDI documentation for more information on syntax and on terms referenced in these properties. Message Queue uses a Sun JNDI LDAP provider and uses simple authentication.

    Message Queue supports LDAP authentication failover: you can specify a list of LDAP directory servers for which authentication will be attempted (see the reference information for the imq.user.repos.ldap.server property).

    See the broker’s file for a sample of how to set properties related to LDAP user-repository.

  4. If necessary, you need to edit the users/groups and rules in the access control properties file. For more information about the use of access control property files, see User Authorization: The Access Control Properties File.

  5. If you want the broker to communicate with the LDAP directory server over SSL during connection authentication and group searches, you need to activate SSL in the LDAP server and then set the following properties in the broker configuration file:

    • Specify the port used by the LDAP server for SSL communications. For example:

    • Set the broker property imq.user_repository.ldap.ssl.enabled to true.

      When employing multiple LDAP directory servers, use ldap:// to specify each additional directory server. For example:

      imq.user_repository.ldap.server= myHost:7878 ldap:// otherHost:7878

      Separate each additional directory server with a space. All directory servers in the list must use the same values for other LDAP-related properties.

Setting Up Access Control for Administrators

To create administrative users, you use the access control properties file to specify users and groups that can create ADMIN connections. These users and groups must be predefined in the LDAP directory.

Any user or group who can create an ADMIN connection can issue administrative commands.

ProcedureTo Set Up an Administrative User

  1. Enable the use of the access control file by setting the broker property imq.accesscontrol.enabled to true, which is the default value.

    The imq.accesscontrol.enabled property enables use of the access control file.

  2. Open the access control file, The location for the file is listed in Appendix A, Platform-Specific Locations of Message QueueTM Data

    The file contains an entry such as the following:

    service connection access control##################################connection.NORMAL.allow.user=*

    The entries listed are examples. Note that the admin group exists in the file-based user repository but does not exist by default in the LDAP directory. You must substitute the name of a group that is defined in the LDAP directory, to which you want to grant Message Queue administrator privileges.

  3. To grant Message Queue administrator privileges to users, enter the user names as follows:

    connection.ADMIN.allow.user= userName[[,userName2] ]

  4. To grant Message Queue administrator privileges to groups, enter the group names as follows: groupName[[,groupName2] ]

User Authorization: The Access Control Properties File

An access control properties file (ACL file) contains rules that specify the operations that users and groups of users can perform. You edit the ACL file to restrict operations to certain users and groups. You can use a different ACL file for each broker instance.

The ACL file is used whether user information is placed in a flat-file user repository or in an LDAP user repository. A broker checks its ACL file when a client application performs one of the following operations:

The broker checks the ACL file to determine whether the user that generated the request, or a group to which the user belongs, is authorized to perform the operation.

If you edit an ACL file, the new settings take effect the next time the broker checks the file to verify authorization. You need not restart the broker after editing the file.

Creating an Access Control Properties File

The ACL file is instance specific. Each time you start a broker instance, a default file named is created in the instance directory. The path to the file has the following format (see Appendix A, Platform-Specific Locations of Message QueueTM Data):


The ACL file is formatted like a Java properties file. It starts by defining the version of the file and then specifies access control rules in three sections:

The version property defines the version of the ACL properties file; you may not change this entry.


The three sections of the ACL file that specify access control are described below, following a description of the basic syntax of access rules and an explanation of how permissions are calculated.

Syntax of Access Rules

In the ACL properties file, access control defines what access specific users or groups have to protected resources like physical destinations and connection services. Access control is expressed by a rule or set of rules, with each rule presented as a Java property:

The basic syntax of these rules is as follows:



Table 7–3 describes the elements of syntax rules.

Table 7–3 Syntactic Elements of Access Rules




One of the following: connection, queue or topic.


An instance of the type specified by resourceType. For example, myQueue. The wild card character (*) may be used to mean all connection service types or all physical destinations.


Value depends on the kind of access rule being formulated. 


One of the following: allow or deny.


One of the following: user or group. For more information, see Groups.


Who may have the access specified on the left-hand side of the rule. This may be an individual user or a list of users (comma delimited) if the principalType is user; it may be a single group or a list of groups (comma delimited list) if the principalType is group. The wild card character (*) may be used to represent all users or all groups.

Here are some examples of access rules:

Note –

To specify non-ASCII user, group, or destination names, use Unicode escape (\\uXXXX) notation. If you have edited and saved the ACL file with these names in a non-ASCII encoding, you can convert the file to ASCII with the Java native2ascii tool. For more detailed information, see

How Permissions are Computed

When there are multiple access rules in the file, permissions are computed as follows:

Access Control for Connection Services

The connection access control section in the ACL properties file contains access control rules for the broker’s connection services. The syntax of connection access control rules is as follows:


Two values are defined for resourceVariant: NORMAL and ADMIN. These predefined values are the only types of connection services to which you can grant access.

The default ACL properties file gives all users access to NORMAL connection services and gives users in the group admin access to ADMIN connection services:


If you are using a file-based user repository, the default group admin is created by the User Manager utility. If you are using an LDAP user repository, you can do one of the following to use the default ACL properties file:

You can restrict connection access privileges. For example, the following rules deny Bob access to NORMAL but allow everyone else:


You can use the asterisk (*) character to specify all authenticated users or groups.

The way that you use the ACL properties file to grant access to ADMIN connections differs for file-based user repositories and LDAP user repositories, as follows:

Access Control for Physical Destinations

The destination access control section of the access control properties file contains physical destination-based access control rules. These rules determine who (users/groups) may do what (operations) where (physical destinations). The types of access that are regulated by these rules include sending messages to a queue, publishing messages to a topic, receiving messages from a queue, subscribing to a topic, and browsing messages in a queue.

By default, any user or group can have all types of access to any physical destination. You can add more specific destination access rules or edit the default rules. The rest of this section explains the syntax of physical destination access rules, which you must understand to write your own rules.

The syntax of destination rules is as follows:


Table 7–4 describes these elements:

Table 7–4 Elements of Physical Destination Access Control Rules




Can be queue or topic.


A physical destination name or all physical destinations (*), meaning all queues or all topics. 


Can be produce, consume, or browse.


Can be allow or deny.


Can be user or group.

Access can be given to one or more users and/or one or more groups.

The following examples illustrate different kinds of physical destination access control rules:

Access Control for Auto-Created Physical Destinations

The final section of the ACL properties file, includes access rules that specify for which users and groups the broker will auto-create a physical destination.

When a user creates a producer or consumer at a physical destination that does not already exist, the broker will create the destination if the broker’s auto-create property has been enabled.

By default, any user or group has the privilege of having a physical destination auto-created by the broker. This privilege is specified by the following rules:


You can edit the ACL file to restrict this type of access.

The general syntax for physical destination auto-create access rules is as follows:


Where resourceType is either queue or topic.

For example, the following rules allow the broker to auto-create topic destinations for everyone except Snoopy.


Note that the effect of physical destination auto-create rules must be congruent with that of physical destination access rules. For example, if you 1) change the destination access rule to forbid any user from sending a message to a destination but 2) enable the auto-creation of the destination, the broker will create the physical destination if it does not exist but it will not deliver a message to it.

Message Encryption

This section explains how to set up a connection service based on the Secure Socket Layer (SSL) standard, which sends encrypted messages between clients and broker. Message Queue supports the following SSL-based connection services:

The remainder of this section describes how to set up secure connections over TCP/IP, using the ssljms, ssladmin, and cluster connection services.For information on setting up secure connections over HTTP with the httpsjms service, see Appendix C, HTTP/HTTPS Support.

Using Self-Signed Certificates

To use an SSL-based connection service over TCP/IP, you generate a public/private key pair using the Key Tool utility (imqkeytool). This utility embeds the public key in a self-signed certificate that is passed to any client requesting a connection to the broker, and the client uses the certificate to set up an encrypted connection. This section describes how to set up an SSL-based service using such self-signed certificates.

For a stronger level of authentication, you can use signed certificates verified by a certification authority. The use of signed certificates involves some additional steps beyond those needed for self-signed certificates: you must first perform the steps described in this section and then follow them with the additional ones in Using Signed Certificates.

Message Queue's support for SSL with self-signed certificates is oriented toward securing on-the-wire data, on the assumption that the client is communicating with a known and trusted server. The following procedure shows the steps needed to set up an SSL-based connection service to use self-signed certificates. The subsections that follow describe each of these steps in greater detail.

ProcedureTo Set Up an SSL-Based Connection Service Using Self-Signed Certificates

  1. Generate a self-signed certificate.

  2. Enable the ssljms, ssladmin, or cluster connection service in the broker.

  3. Start the broker.

  4. Configure and run the client.

    This step applies only to the ssljms connection service and not to ssladmin or cluster.

Generating a Self-Signed Certificate

Run the Key Tool utility (imqkeytool) to generate a self-signed certificate for the broker. (On UNIX® systems, you may need to run the utility as the superuser (root) in order to have permission to create the key store.) The same certificate can be used for the ssljms, ssladmin, or cluster connection service.

Enter the following at the command prompt:

imqkeytool -broker

The Key Tool utility prompts you for a key store password:

   Generating keystore for the broker ...
   Enter keystore password:

Next, the utility prompts you for information identifying the broker to which this certificate belongs. The information you supply will make up an X.500 distinguished name. Table 7–5 shows the prompts and the values to be provided for each. Values are case-insensitive and can include spaces.

Table 7–5 Distinguished Name Information Required for a Self-Signed Certificate


X.500 Attribute 



What is your first and last name?

commonName (CN)

Fully qualified name of server running the broker

What is the name of your organizational unit?

organizationalUnit (OU)

Name of department or division 


What is the name of your organization?

organizationName (ON)

Name of larger organization, such as a company or government entity 

My Company, Inc.

What is the name of your city or locality?

localityName (L)

Name of city or locality 

San Francisco

What is the name of your state or province?

stateName (ST)

Full (unabbreviated) name of state or province 


What is the two-letter country code for this unit?

country (C)

Standard two-letter country code 


When you have entered the information, the Key Tool utility displays it for confirmation. For example:

   Is, OU=purchasing, ON=My Company, Inc.,
   L=San Francisco, ST=California, C=US correct?

To accept the current values and proceed, enter yes; to reenter values, accept the default or enter no. After you confirm, the utility pauses while it generates a key pair.

Next, the utility asks for a password to lock the key pair (key password). Press Return in response to this prompt to use the same password as the key password and key store password.

Note –

Remember the password you specify. You must provide this password when you start the broker, to allow the broker to open the key store. You can store the key store password in a password file (see Password Files).

The Key Tool utility generates a self-signed certificate and places it in Message Queue’s key store. The key store is located in a directory that depends upon the operating system, as shown in Appendix A, Platform-Specific Locations of Message QueueTM Data.

The following are the configurable properties for the Message Queue key store for SSL-based connection services:

In some circumstances, you may need to regenerate a key pair in order to solve certain problems: for example, if you forget the key store password or if the SSL-based service fails to initialize when you start a broker and you get the exception Cannot recover key

(This exception may result if you provided a key password different from the key store password when you generated the self-signed certificate.)

ProcedureTo Regenerate a Key Pair

  1. Remove the broker’s key store, located as shown in Appendix A, Platform-Specific Locations of Message QueueTM Data.

  2. Run imqkeytool again to generate a new key pair, as described above.

Enabling an SSL-Based Connection Service

To enable an SSL-based connection service in the broker, you need to add ssljms (or ssladmin) to the imq.service.activelist property.

ProcedureTo Enable an SSL-Based Service in the Broker

  1. Open the broker’s instance configuration file.

    The instance configuration file is located in a directory identified by the name of the broker instance (instanceName) with which the configuration file is associated (see Appendix A, Platform-Specific Locations of Message QueueTM Data):

  2. Add an entry (if one does not already exist) for the imq.service.activelist property and include the desired SSL-based service(s) in the list.

    By default, the property includes the jms and admin connection services. Add the SSL-based service or services you wish to activate (ssljms, ssladmin, or both):


    Note –

    The SSL-based cluster connection service is enabled using the imq.cluster.transport property rather than the imq.service.activelist property; see Connecting Brokers.

  3. Save and close the instance configuration file.

Starting the Broker

Start the broker, providing the key store password. You can provide the password in either of two ways:

Note –

When you start a broker or client with SSL, you may notice a sharp increase in CPU usage for a few seconds. This is because the JSSE (Java Secure Socket Extension) method, which Message Queue uses to generate random numbers, takes a significant amount of time to create the initial random number seed. Once the seed is created, the CPU usage level will drop to normal.

Configuring and Running an SSL-Based Client

The procedure for configuring a client to use an SSL-based connection service differs depending on whether it is an application client (using the ssljms connection service) or a Message Queue administrative client such as imqcmd (using the ssladmin connection service.)

Application Clients

For application clients, you must make sure the client has the following .jar files specified in its CLASSPATH variable:

If you are using a version of the Java 2 Software Development Kit (J2SDK) earlier than 1.4, you must also include the following Java Secure Socket Extension (JSSE) and Java Naming and Directory Interface (JNDI) .jar files:

(It is not necessary to include these files if you are using J2SDK 1.4 or later, which has JSSE and JNDI support built in.)

Once the CLASSPATH files are properly specified, one way to start the client and connect to the broker’s ssljms connection service is by entering a command like the following:

java -DimqConnectionType=TLS clientAppName

This tells the connection to use an SSL-based connection service.

Administrative Clients

For administrative clients, you can establish a secure connection by including the -secure option when you invoke the imqcmd command: for example,

imqcmd list svc -b hostName:portNumber -u adminName -secure

where adminName is a valid entry in the Message Queue user repository. The command will prompt you for the password. (If you are using a flat-file repository, see Changing the Default Administrator Password).

Listing the connection services is a way to verify that the ssladmin service is running and that you can successfully make a secure administrative connection, as shown in the following output:

Listing all the services on the broker specified by:

Host                 Primary Port
localhost            7676

Service Name     Port Number       Service State
admin            33984 (dynamic)   RUNNING
httpjms          -                 UNKNOWN
httpsjms         -                 UNKNOWN
jms              33983 (dynamic)   RUNNING
ssladmin         35988 (dynamic)   RUNNING
ssljms           dynamic           UNKNOWN

Successfully listed services.

Using Signed Certificates

Signed certificates provide a stronger level of server authentication than self-signed certificates. You can implement signed certificates only between a client and broker, and not between multiple brokers in a cluster. This requires the following extra steps in addition to the ones described above for configuring self-signed certificates. These steps are described in greater detail in the subsections that follow.

ProcedureTo Use a Signed Certificate

  1. Install the certificate in the key store.

  2. Configure the Message Queue client to require signed certificates when establishing an SSL-based connection to the broker.

Obtaining and Installing a Signed Certificate

The following procedures explain how to obtain and install a signed certificate.

ProcedureTo Obtain a Signed Certificate

  1. Use the J2SE keytool command to generate a certificate signing request (CSR) for the self-signed certificate you generated in the preceding section.

    Information about the keytool command can be found at

    Here is an example:

    keytool -certreq -keyalg RSA -alias imq -file certreq.csr
            -keystore /etc/imq/keystore -storepass myStorePassword

    This generates a CSR encapsulating the certificate in the specified file (certreq.csr in the example).

  2. Use the CSRto generate or request a signed certificate.

    You can do this by either of the following methods:

    • Have the certificate signed by a well known certification authority (CA), such as Thawte or Verisign. See your CA’s documentation for more information on how to do this.

    • Sign the certificate yourself, using an SSL signing software package.

      The resulting signed certificate is a sequence of ASCII characters. If you receive the signed certificate from a CA, it may arrive as an e-mail attachment or in the text of a message.

  3. Save the signed certificate in a file.

    The instructions below use the example name broker.cer to represent the broker certificate.

ProcedureTo Install a Signed Certificate

  1. Check whether J2SE supports your certification authority by default.

    The following command lists the root CAs in the system key store:

    keytool -v -list -keystore $JAVA_HOME/lib/security/cacerts

    If your CA is listed, skip the next step.

  2. If your certification authority is not supported in J2SE, import the CA’s root certificate into the Message Queue key store.

    Here is an example:

    keytool -import -alias ca -file ca.cer -noprompt -trustcacerts
            -keystore /etc/imq/keystore -storepass myStorePassword

    where ca.cer is the file containing the root certificate obtained from the CA.

    If you are using a CA test certificate, you probably need to import the test CA root certificate. Your CA should have instructions on how to obtain a copy.

  3. Import the signed certificate into the key store to replace the original self-signed certificate.

    Here is an example:

    keytool -import -alias imq -file broker.cer -noprompt -trustcacerts
            -keystore /etc/imq/keystore -storepass myStorePassword

    where broker.cer is the file containing the signed certificate that you received from the CA.

    The Message Queue key store now contains a signed certificate to use for SSL connections.

Configuring the Message Queue Client Runtime to Require Signed Certificates

You must now configure the Message Queue client runtime to require signed certificates, and ensure that it trusts the certification authority that signed the certificate.

ProcedureTo Configure the Client Runtime to Require Signed Certificates

  1. Set the connection factory's imqSSLIsHostTrusted attribute to false.

    By default, the imqSSLIsHostTrusted attribute of the connection factory object that the client will be using to establish broker connections is set to true, meaning that the client runtime will accept any certificate presented to it. You must change this value to false so that the client runtime will attempt to validate all certificates presented to it. Validation will fail if the signer of the certificate is not in the client's trust store.

  2. Verify whether the signing authority is registered in the client's trust store.

    To test whether the client will accept certificates signed by your certification authority, try to establish an SSL connection, as described above under Configuring and Running an SSL-Based Client.If the CA is in the client's trust store, the connection will succeed and you can skip the next step. If the connection fails with a certificate validation error, go on to the next step.

  3. Install the signing CA’s root certificate in the client’s trust store.

    The client searches the key store files cacerts and jssecacerts by default, so no further configuration is necessary if you install the certificate in either of those files. The following example installs a test root certificate from the Verisign certification authority from a file named testrootca.cer into the default system certificate file, cacerts.The example assumes that J2SE is installed in the directory $JAVA_HOME/usr/j2se:

    keytool -import -keystore /usr/j2se/jre/lib/security/cacerts
            -alias VerisignTestCA -file testrootca.cer -noprompt
            -trustcacerts -storepass myStorePassword

    An alternative (and recommended) option is to install the root certificate into the alternative system certificate file, jssecacerts :

    keytool -import -keystore /usr/j2se/jre/lib/security/jssecacerts
            -alias VerisignTestCA -file testrootca.cer -noprompt
            -trustcacerts -storepass myStorePassword

    A third possibility is to install the root certificate into some other key store file and configure the client to use that as its trust store.The following example installs into the file /home/smith/.keystore:

    keytool -import -keystore /home/smith/.keystore
            -alias VerisignTestCA -file testrootca.cer -noprompt
            -trustcacerts -storepass myStorePassword

    Since the client does not search this key store by default, you must explicitly provide its location to the client to use as a trust store. You do this by setting the Java system property once the client is running:

Password Files

Several types of commands require passwords. In Table 7–6, the first column lists the commands that require passwords and the second column lists the reason that passwords are needed.

Table 7–6 Commands That Use Passwords



Purpose of Password 


Start the broker 

Access a JDBC-based persistent data store, an SSL certificate key store, or an LDAP user repository 


Manage the broker 

Authenticate an administrative user who is authorized to use the command 


Manage a JDBC-based data store 

Access the data store 

You can specify these passwords in a password file and use the -passfile option to specify the name of the file. This is the format for the -passfile option:

imqbrokerd -passfile myPassfile

Note –

In previous releases, you could use the -p, -password, -dbpassword, and -ldappassword options to specify passwords on a command line. These options are deprecated and will be removed in a future release. In the current release, a value on the command line for one of these options supersedes the associated value in a password file.

Security Concerns

Specifying a password interactively, in response to a prompt, is the most secure method of specifying a password, unless your monitor is visible to other people. You can also specify a password file on the command line. For non-interactive use of commands, however, you must use a password file.

A password file is unencrypted, so you must set its permissions to protect it from unauthorized access. Set permissions such that they limit the users who can view the file, but provide read access to the user who starts the broker.

Password File Contents

A password file is a simple text file that contains a set of properties and values. Each value is a password used by a command.

A password file can contain the passwords shown in Table 7–7:

Table 7–7 Passwords in a Password File


Affected Commands 




Specifies the administrator password for an imqcmd command line. The password is authenticated for each command.



Specifies the key store password for SSL-based services. 



Specifies the password used to open a database connection, if required. 



Specifies the password associated with the distinguished name assigned to a broker for binding to a configured LDAP user repository. 

A sample password file is part of the Message Queue product. For the location of the sample file, see Appendix A, Platform-Specific Locations of Message QueueTM Data

Connecting Through a Firewall

When a client application is separated from the broker by a firewall, special measures are needed in order to establish a connection. One approach is to use the httpjms or httpsjms connection service, which can “tunnel” through the firewall; see Appendix C, HTTP/HTTPS Support for details. HTTP connections are slower than other connection services, however; a faster alternative is to bypass the Message Queue Port Mapper and explicitly assign a static port address to the desired connection service, and then open that specific port in the firewall. This approach can be used to connect through a firewall using the jms or ssljms connection service (or, in unusual cases, admin or ssladmin).

Table 7–8 Broker Configuration Properties for Static Port Addresses

Connection Service 

Configuration Property 









ProcedureTo Enable Broker Connections Through a Firewall

  1. Assign a static port address to the connection service you wish to use.

    To bypass the Port Mapper and assign a static port number directly to a connection service, set the broker configuration property imq.serviceName.protocolType.port, where serviceName is the name of the connection service and protocolType is its protocol type (see Table 7–8). As with all broker configuration properties, you can specify this property either in the broker's instance configuration file or from the command line when starting the broker. For example, to assign port number 10234 to the jms connection service, either include the line


    in the configuration file or start the broker with the command

    imqbrokerd  -name myBroker  -Dimq.jms.tcp.port=10234
  2. Configure the firewall to allow connections to the port number you assigned to the connection service.

    You must also allow connections through the firewall to Message Queue's Port Mapper port (normally 7676, unless you have reassigned the Port Mapper to some other port). In the example above, for instance, you would need to open the firewall for ports 10234 and 7676.

Audit Logging

Message Queue supports audit logging in Enterprise Edition only. When audit logging is enabled, Message Queue generates a record for the following types of events:

To log audit records to the Message Queue broker log file, set the imq.audit.enabled broker property to true . All audit records in the log contain the keyword AUDIT.