Performing the setup

It is recommended to divide the setup process into three parts. The first part consists of setting up the IBM Tivoli Directory Server for z/OS so that it is able to run with the HCD LDAP backend. The second part consists of setting up the HCD LDAP backend. The third part consists of integrating the HCD schema into the IBM Tivoli Directory Server for z/OS.

Setting up the IBM Tivoli Directory Server for z/OS

This section lists the prerequisites that the IBM Tivoli Directory Server for z/OS must comply with, so that it can run with the HCD LDAP backend.

Prerequisites for IBM Tivoli Directory Server for z/OS setup: 

• Set up the IBM Tivoli Directory Server for z/OS for running as a started task.
• Establish a separate user ID that runs the IBM Tivoli Directory Server for z/OS.
• Set up the IBM Tivoli Directory Server for z/OS for running in single-server mode without replication.
• Configure the IBM Tivoli Directory Server for z/OS with the SDBM backend. The HCD LDAP backend requires the IBM Tivoli Directory Server for z/OS to run with this RACF backend. Therefore, SDBM must be included in the configuration file and all prerequisites for SDBM must be fulfilled.

Additional Prerequisites for z/OS UNIX level security: 

Up to here, you have completed to set up the IBM Tivoli Directory Server for z/OS with UNIX level security. If you want to have z/OS UNIX level security, your environment must comply to the following prerequisites:

• Define the RACF FACILITY profile BPX.SERVER. Refer to z/OS IBM Tivoli Directory Server Administration and Use for z/OSz/OS IBM Tivoli Directory Server Administration and Use for z/OS and z/OS UNIX System Services Planningz/OS UNIX System Services Planning for details what this means for the setup of the IBM Tivoli Directory Server for z/OS.
  Note:

  Defining a profile named BPX.SERVER in the RACF class FACILITY switches system security from UNIX level security to z/OS UNIX level security. Other applications may be affected by this switch.

• Define libraries to program control. Under z/OS UNIX level security, every program that is loaded into a server address space must be marked as controlled (see section "Defining Modules to Program Control" of the z/OS UNIX System Services Planningz/OS UNIX System Services Planning book).
  Note:

  Changing profiles in RACF class PROGRAM can cause severe system problems if not done in a manner suitable for the system. If you are unsure ask your RACF administrator.

Setting up the HCD LDAP backend

This section describes how to set up the HCD LDAP backend. There is a sample REXX procedure CBDSLCUS in SYS1.SAMPLIB that contains the RACF commands listed in this section for the z/OS UNIX level security.

To set up the HCD LDAP backend, perform the following steps. Steps 1 through 3 are only required for z/OS UNIX level security. If you have chosen UNIX level security, continue with step 5.

1. Authorize the HCD LDAP backend to act on behalf of other user IDs. With UNIX level security, the IBM Tivoli Directory Server for z/OS runs under a superuser (with UID 0) who is permitted to act on behalf of any user ID. Under z/OS UNIX level security, the HCD LDAP backend (which receives no password from the IBM Tivoli Directory Server for z/OS) can only perform a service for a client user ID when it has been explicitly authorized to act on behalf of that user ID (see the section "Defining Servers to Process Users without Password" of z/OS UNIX System Services Planningz/OS UNIX System Services Planning).

   In order to authorize the user ID of the server to act on behalf of another user ID, you must do the following:

   1. Define a surrogate profile for the prospective client by issuing the following RACF commands (the second command updates the in-storage copy of the SURROGAT profiles):

      RDEFINE SURROGAT BPX.SRV.userID UACC(NONE)
      SETROPTS RACLIST(SURROGAT) REFRESH

   2. Authorize the user ID of the IBM Tivoli Directory Server for z/OS for this profile by the following commands (the second command updates the in-storage copy of the SURROGAT profiles):

      PERMIT BPX.SRV.userID CLASS(SURROGAT) ID(LDAPSRV) ACCESS(READ)
      SETROPTS RACLIST(SURROGAT) REFRESH

   These example commands are based on the following assumptions (which may not hold for your system!):

   1. The RACF class SURROGAT has been activated.
   2. There is no profile in that class with the name BPX.SRV.userID, where userID is the user ID of the prospective client.
   3. The user ID of the IBM Tivoli Directory Server for z/OS is LDAPSRV.
2. Define libraries to program control. Under z/OS UNIX level security, every program that is loaded into a server address space must be marked as controlled (see section "Defining Modules to Program Control" of the z/OS UNIX System Services Planningz/OS UNIX System Services Planning book).

   When using the HCD LDAP backend, the libraries containing the following load modules must be defined to program control:

   Table 9. Load Module Libraries to be defined to program control

   Load Modules	Typical Library
   HCD LDAP backend	SYS1.LINKLIB on SYSRES
   HCD	SYS1.LINKLIB on SYSRES
   UIMs	SYS1.NUCLEUS on SYSRES
   C++ RTL	CEE.SCEERUN on SYSRES
   IBM Tivoli Directory Server for z/OS and SDBM backend	SYS1.SIEALNKE and SYS1.LPALIB on SYSRES

   Note:

   If you use load modules from other libraries you have to define these libraries to program control as well.

   To define these libraries to program control, issue the following RACF commands:

   RDEFINE PROGRAM ** UACC(READ)
   RALTER PROGRAM ** UACC(READ) ADDMEM('SYS1.LINKLIB'/'******'/NOPADCHK)
   RALTER PROGRAM ** UACC(READ) ADDMEM('SYS1.NUCLEUS'/'******'/NOPADCHK)
   RALTER PROGRAM ** UACC(READ) ADDMEM('CEE.SCEERUN'/'******'/NOPADCHK)
   RALTER PROGRAM ** UACC(READ) ADDMEM('SYS1.SIEALNKE'/'******'/NOPADCHK)
   RALTER PROGRAM ** UACC(READ) ADDMEM('SYS1.LPALIB'/'******'/NOPADCHK)
   SETROPTS WHEN(PROGRAM) REFRESH

   The first command defines a profile named ** to the class PROGRAM. The other commands, except the last, define the libraries containing the load modules to program control. The last command refreshes the in-storage copy of the PROGRAM profiles.

   The example commands are based on the following assumptions (which may not hold for your system!):

   1. The RACF class PROGRAM has been activated.
   2. GENERIC is enabled for the RACF class PROGRAM.
   3. There is no profile in that class with the name **.
   4. The load modules needed reside in their typical libraries as listed above.
3. When using the HCD LDAP backend, the libraries containing the following load modules must be APF authorized:

   Table 10. APF authorized Load Module Libraries

   Load Modules	Typical Library
   HCD LDAP backend	SYS1.LINKLIB on SYSRES
   C++ RTL	CEE.SCEERUN on SYSRES
   IBM Tivoli Directory Server for z/OS and SDBM backend	SYS1.SIEALNKE and SYS1.LPALIB on SYSRES

4. The following steps apply to both security levels.
5. Tailor the started task procedure. This includes:
   • The HCD instances that have been started by the HCD LDAP backend have the same region size as the IBM Tivoli Directory Server for z/OS started task. So, you may need to adjust the region size of the IBM Tivoli Directory Server for z/OS started task according to the region size suitable for the HCD instances.
   • You have to ensure that the IBM Tivoli Directory Server for z/OS and the HCD LDAP backend are able to find the load modules in Table 9 by using the z/OS search order. If the libraries containing these load modules are not searched by z/OS on your system, you must insert a STEPLIB DD, which contains the missing libraries, into the started task procedure.
6. Tailor the IBM Tivoli Directory Server for z/OS configuration file. You must include the definition of the HCD LDAP backend in the configuration file ds.conf. A sample of how to define the HCD LDAP backend as IBM Tivoli Directory Server for z/OS plug-in in the server configuration file is delivered with HCD and is installed in /usr/lpp/hcd/examples/ds.conf. For this purpose you must do the following (the examples are taken from the sample file):

   A plug-in configuration statement must be added into the GLOBAL section of the configuration file ds.conf of the IBM Tivoli Directory Server for z/OS to define the HCD LDAP backend as a plug-in:

   plugin clientOperation CBDMLPLG hcd_plginit “<parameters>”

   Note:

   Note that the HCD LDAP backend plug-in CBDMLPLG works in 31-bit mode.

   The parameters that are recognized by the HCD LDAP backend are described in Configuration file parameters. Here is an example of how to replace the <parameters> by acceptable keyword/value pairs (enclosed in double quotes). Note that the HCD suffix cn=HCD must be passed as parameter of the plug-in statement.

    "suffix                   cn=HCD
     MinHcdInstances          1
     MaxHcdInstances          3
     AllowSwitchTime          30
     ForceSwitchTime          600
     TransactionRollbackTime  3600
     Trace                    off
     Profile                  off
     TraceDsnSuffix           HCD.TRACE
     ProfileDsnSuffix         HCD.PROFILE
     TransformAttributeValues off"

   Note:

   For the processing of the IBM Tivoli Directory Server for z/OS configuration file, the following general rules apply:

   • A blank in column 1 indicates that this line is a continuation line.
   • Trailing blanks are ignored.

   The following syntax rules apply for specifying the parameters:

   • A single parameter is defined by its keyword and its value, both separated by at least one blank.
   • Parameters are delimited by blanks; for example, you may specify each parameter in a separate line.
   • Extra imbedded blanks are ignored, but not allowed within values, for example, do not insert any blanks within cn=HCD.
   • Continuation lines for the plug-in statement must start in column 3 (not in column 1, as for other statements).
7. Run the HCD LDAP backend. To verify that your setup is working issue an LDAP request against the HCD LDAP backend. You can use the LDAP operation utilities to do this. For this purpose, enter a command according to the following template:

   ldapsearch -h ldaphost -p ldapport -D binddn -w passwd -s base
              -b "hcdIodfId=IodfName,suffix" "objectclass=*"

   This command performs a search on the specified IODF on behalf of the user ID specified by binddn. binddn must be a DN from within the SDBM name space representing a user ID, and passwd the appropriate password. IodfName must be the name of an existing IODF data set. suffix would be cn=HCD if you have kept the default value specified in the sample configuration file ds.conf.

   If the request returns a plausible result, the HCD LDAP backend is working correctly.

Integrating the LDAP schema for HCD

HCD is shipped with a predefined schema file representing schema definitions which the IBM Tivoli Directory Server for z/OS needs to evaluate incoming HCD requests issued via the LDAP interface. You must integrate this file into the IBM Tivoli Directory Server for z/OS after this server has been successfully installed and set up. It is recommended that this integration step is performed by the person who is responsible for the IBM Tivoli Directory Server for z/OS (usually the system administrator). The name of the HCD schema file is schema.hcd.ldif and is located in the /usr/lpp/hcd/etc directory.

Use the ldapmodify command to load the schema, for example:

ldapmodify -h ldaphost -p ldapport -D adminDN -w passwd
           -f /usr/lpp/hcd/etc/schema.hcd.ldif

See z/OS IBM Tivoli Directory Server Client Programming for z/OSz/OS IBM Tivoli Directory Server Client Programming for z/OS for more information about ldapmodify.