An example

There are notes throughout the configuration files that are used in this example which guide you to tailor this set of properties to your particular needs. The one most likely to change is noderootrdn, you will probably have some domain other than PLEX2 as the grouping for your nodes - this value is input into the system at Step 4. “Build the legacyRoot node”.

Notice that the example assumes a principal of 'cn=admin' exists on the LDAP server, with password 'adminpwd' and that this principal is authorised to perform any operation on the LDAP server.

  1. Install the WebSphere naming schema.

    If the LDAP server to be configured already has the WebSphere naming schema, this step can be skipped. An LDAP name server configured for WebSphere will already have this schema.

    If it is any other LDAP server, install the WebSphere naming schema. The schema is shipped with CICS as /usr/lpp/cicsts/cicsts31/utils/namespace/WebSphereNamingSchema.ldif on HFS.
    Note: The WebSphereNamingSchema.ldif file requires that RFC2256.ldif and RFC2713.ldif be loaded first. This is because the definition of the ibm-wsnEntry object class refers to the javaClassName attribute type. When using the LDAP server on OS/390 or z/OS, these prerequisite LDAP files are not loaded by default when the LDAP server is set up.

    The LDAP server on OS/390 and z/OS needs to store the schema entries in the back-end store to which they apply. This is achieved by adding a suffix to the dn of each schema entry. The supplied WebSphereNamingSchema.ldif file does not specify a suffix on the schema entries, so you must add one. For example, if the suffix for the back-end store is “c=US”, you should change every instance of “dn:cn=schema” in the ldif file to “dn:cn=schema,c=US”.

    Apply the schema to the nameserver using the ldapmodify command :
    ldapmodify -h <hostname> 
               -p <portnumber> 
               -D <authorized_principal> 
               -w <authorized_principal_password> 
               -f WebSphereNamingSchema.ldif
    Where hostname and portnumber are those for the LDAP server and the authorised principal is the distinguished name of a user with sufficient authority on the nameserver to write entries.

    The ldapmodify command must be available for your chosen LDAP server. If it is not, consult your LDAP server documentation to determine how a new schema (in ldif form) should be installed.

    A specific example might be:
    ldapmodify -h wibble.ibm.com 
               -p 389 
               -D cn=admin 
               -w adminpwd 
               -f WebSphereNamingSchema.ldif  
  2. Add a new suffix.
    To build a new hierarchy in the namespace it is necessary to create a new base distinguished name suffix. In this example configuration the suffix is c=US, and the new hierarchy is to be ibm-wsnTree=t1,o=WASNaming,c=US. The procedure for adding a suffix varies between the different LDAP providers. Your LDAP documentation should indicate how to do this for your chosen provider. As an example, here is the procedure for adding a suffix to a Secureway installation on Windows 32:
    • Start the LDAP Administration interface on a Web browser by typing http://[hostname]/ldap, where hostname is the host name of the machine where the LDAP directory is installed. The Administration logon window displays.
    • Type the administrator user ID (for example, in the format cn=root) and password.
    • Make sure that the LDAP server is running.
    • In the left navigation pane, click the Settings folder, and then click Suffixes.
    • Type the name of the Base DN to be used as the suffix (in our example, "c=US"), and click Update.
    • After the Base DN suffix is added, stop and restart the LDAP server.
    The suffix now exists on your LDAP system
    On an OS/390® or z/OS® system, update the slapd.conf file to introduce your new suffix to the system, then restart the nameserver. The extra line to add to slapd.conf is:
    suffix “c=US”
  3. Build the system name space root node (containerdn)

    An ldif file to build the root of the system name space (a node called the containerdn) is supplied with CICS in utils/namespace/dfhsns.ldif. This file contains comments describing how to tailor it for your environment. If it is used without alteration, it creates a containerdn of ibm-wsnTree=t1,o=wasnaming,c=US and also two CICS users on the LDAP namespace. The first CICS user has a distinguished name of cn=CICSSystems,c=US and the second is cn=CICSUser,c=US.

    Two userids are defined. To understand how they are used, see Security considerations.

    The ldapmodify command must be available for your chosen LDAP server, if it is not, consult your LDAP server documentation to determine how the root of the system name space should be built..

    This LDIF file can be applied to the LDAP server as follows:
    ldapmodify-h <hostname> 
            -p <portnumber>
            -D <authorized_principal>  
            -w <authorized_principal_password> 
            -f dfhsns.ldif
    Where hostname and portnumber are those for the LDAP server and the authorised principal is the distinguished name of a user with sufficient authority on the nameserver to write entries.
    A specific example is:
    ldapmodify-h wibble.ibm.com 
            -p 389 
            -D cn=admin 
            -w adminpwd 
            -f dfhsns.ldif 
  4. Build the legacyRoot node below the namespace root node (noderootrdn)

    The legacyRoot node in the namespace is the point where CICS is usually configured to position itself when called to create a new InitialContext. For this step , the script DFHBuildSNS is shipped with CICS in the directory utils/namespace.

    The syntax is :
    DFHBuildSNS   -ldapserver  <server_url>  
                 [-node        <node within the domain>] 
                  -domain      <domain_name>
                  -containerdn <Root of the namespace>
                  -principal   <principal authorised to write to the namespace>
                  -credentials <password for that principal>
                 [-force]  
    For example:
    DFHBuildSNS    -ldapserver ldap://wibble.ibm.com:389
                   -domain PLEX2
                   -containerdn ibm-wsnTree=t1,o=WASNaming,c=US
                   -principal cn=admin
                   -credentials adminpwd 
    ( The -force option is only used with the -node flag, but neither are used in a CICS environment.
  5. Optionally apply the additional measures described in Security at the CICS region level.
After running this script, the values of the system properties required in your JVM properties files can be determined, and you can add them to all the relevant JVM properties files.