Configure the JMS administration tool

The IBM MQ JMS administration tool uses a configuration file to set the values of certain properties. A sample configuration file is supplied, which we can edit to suit the system.

About this task

#Set the service provider
INITIAL_CONTEXT_FACTORY=com.sun.jndi.ldap.LdapCtxFactory
#Set the initial context
PROVIDER_URL=ldap://polaris/o=ibm_us,c=us
#Set the authentication type
SECURITY_AUTHENTICATION=none

A sample configuration file, which is used as the default configuration file, is supplied with IBM MQ. The sample file is called JMSAdmin.config, and is found in the MQ_JAVA_INSTALL_PATH/bin directory. We can either edit this sample file to define the settings needed for the system, or create your own configuration file.

When you start the administration tool, we can specify the configuration file that we want to use by using the -cfg command-line parameter, as described in Starting the administration tool. If we do not specify a configuration file name when you invoke the tool, the tool attempts to load the default configuration file ( JMSAdmin.config). It searches for this file first in the current directory, and then in the MQ_JAVA_INSTALL_PATH/bin directory, where MQ_JAVA_INSTALL_PATH is the path to the IBM MQ classes for JMS installation.

The names of JMS objects that are stored in an LDAP environment must comply with LDAP naming conventions. One of these conventions is that object and context names must include a prefix, such as cn= (common name), or ou= (organizational unit). The administration tool simplifies the use of LDAP service providers by allowing you to refer to object and context names without a prefix. If we do not supply a prefix, the tool automatically adds a default prefix to the name you supply. For LDAP, this is cn=. If required, we can change the default prefix by setting the NAME_PREFIX property in the configuration file.

Procedure

1. Define the service provider that the tool uses by configuring the INITIAL_CONTEXT_FACTORY property. The supported values for this property are as follows:
   • com.sun.jndi.ldap.LdapCtxFactory (for LDAP)
   • com.sun.jndi.fscontext.RefFSContextFactory (for file system context)
   • com.ibm.jndi.LDAPCtxFactory is supported on z/OS only, and provides access to an LDAP server. However, this class is incompatible with com.sun.jndi.ldap.LdapCtxFactory, in that objects created using one InitialContextFactory cannot be read or modified using the other.

   We can also use the administration tool to connect to other JNDI contexts by using three parameters defined in the JMSAdmin configuration file. To use a different InitialContextFactory:

   1. Set the INITIAL_CONTEXT_FACTORY property to the required class name.
   2. Define the behavior of the InitialContextFactory using the USE_INITIAL_DIR_CONTEXT, NAME_PREFIX and NAME_READABILITY_MARKER properties. The settings for these properties are described in the sample configuration file comments.

   You do not need to define the USE_INITIAL_DIR_CONTEXT, NAME_PREFIX and NAME_READABILITY_MARKER properties if we use one of the supported INITIAL_CONTEXT_FACTORY values. However, we can give values to these properties if we want to override the system defaults. For example, if your objects are stored in an LDAP environment, we can change the default prefix that the tool adds to object and context names by setting the NAME_PREFIX property to the required prefix.

   If we omit one or more of the three InitialContextFactory properties, the administration tool provides suitable defaults based on the values of the other properties.

2. Define the URL of the initial context of the session by configuring the PROVIDER_URL property. This URL is the root of all JNDI operations carried out by the tool. Two forms of this property are supported:
   • ldap://hostname/contextname
   • file:[drive:]/pathname

   The format of the LDAP URL can vary, depending on your LDAP provider. See your LDAP documentation for more information.

3. Define whether JNDI passes security credentials to your service provider by configuring the SECURITY_AUTHENTICATION property. This property is used only when an LDAP service provider is used and can take one of three values:

   none (anonymous authentication)

   If you set this parameter to none, JNDI does not pass any security credentials to the service provider, and anonymous authentication is performed.

   simple (simple authentication)

   If you set the parameter to simple, security credentials are passed through JNDI to the underlying service provider. These security credentials are in the form of a user distinguished name (User DN) and password.

   CRAM-MD5 (CRAM-MD5 authentication mechanism)

   If you set the parameter to CRAM-MD5, security credentials are passed through JNDI to the underlying service provider. These security credentials are in the form of a user distinguished name (User DN) and password.

   If we do not supply a valid value for the SECURITY_AUTHENTICATION property, the property defaults to none.

   If security credentials are required, we are prompted for them when the tool initializes. We can avoid this by setting the PROVIDER_USERDN and PROVIDER_PASSWORD properties in the JMSAdmin configuration file.

   Note: If we do not use these properties, the text typed, including the password, is echoed to the screen. This might have security implications.

   The tool does no authentication itself; the authentication task is delegated to the LDAP server. The LDAP server administrator must set up and maintain access privileges to different parts of the directory. See your LDAP documentation for more information. If authentication fails, the tool displays an appropriate error message and terminates.

   More detailed information about security and JNDI is in the documentation at Oracle's Java website ( Oracle Technology Network for Java Developers ).

Parent topic: Configure JMS objects using the administration tool