Configuring 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 you can edit to suit your system.

About this task

The configuration file is a plain-text file that consists of a set of key-value pairs, separated by the equal sign (=). You configure the administration tool by setting values for the three properties defined in the configuration file. The following example shows these three properties: 

#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
(In this example, a hash sign (#) in the first column of the line indicates a comment, or a line that is not used.)

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. You can either edit this sample file to define the settings needed for your system, or create your own configuration file.

When you start the administration tool, you can specify the configuration file that you want to use by using the -cfg command-line parameter, as described in Starting the administration tool. If you 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 your 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 you do not supply a prefix, the tool automatically adds a default prefix to the name you supply. For LDAP, this is cn=. If required, you can change the default prefix by setting the NAME_PREFIX property in the configuration file.

Note: You might need to configure your LDAP server to store Java objects. For more information, see the documentation for your LDAP server.

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)
    • [z/OS]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.

    You 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 you use one of the supported INITIAL_CONTEXT_FACTORY values. However, you can give values to these properties if you want to override the system defaults. For example, if your objects are stored in an LDAP environment, you 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 you 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 you do not supply a valid value for the SECURITY_AUTHENTICATION property, the property defaults to none.

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

    Note: If you 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 ).