Server utilities

Parameters of the db2pwden utility

options

The following table shows the options that you can use for the db2pwden utility.

Table 1. db2pwden options

Option	Description
-?	Print this text.
-b baseDN	Use baseDN as the starting point for the update instead of the default. If -b is not specified, this utility examines the LDAP_BASEDN environment variable for a baseDN definition. If you are running in TSO, set the LDAP_BASEDN environment variable using Language Environment® runtime environment variable _CEE_ENVFILE. See z/OS XL C/C++ Programming Guide for more information. If you are running in the z/OS shell, export the LDAP_BASEDN environment variable.
-d debugLevel	Specify the level of debug messages to be created. The debugLevel is specified in the same fashion as the debug level for the LDAP server. LDAP debug levels lists the specific debug levels. The default is no debug messages.
-D bindDN	Use bindDN to bind to the LDAP directory. The bindDN option is a string-represented DN. The default is a NULL string. If the -S or -m option is equal to DIGEST-MD5 or CRAM-MD5, this option is the authorization DN which is used for making access checks. This directive is optional when used in this manner.
-g realmName	Specify the realmName to use when doing a DIGEST-MD5 bind. This option is required when multiple realms are passed from an LDAP server to a client as part of a DIGEST-MD5 challenge; otherwise, it is optional.
-h ldapHost	Specify the host name or IP address on which the LDAP server is running. The default is the local host.
-K keyFile	Specify the name of the System SSL key database file, RACF® key ring, or PKCS #11 token. If this option is not specified, this utility looks for the presence of the SSL_key ring environment variable with an associated name. If keyFile is specified as *TOKEN*/NAME, then System SSL uses the specified PKCS #11 token. Otherwise, System SSL uses a key database file or a RACF key ring. In this case, System SSL first assumes that keyFile is a key database file name and tries to locate the file. If keyFile is not a fully qualified z/OS® UNIX System Services file name, the current directory is assumed to contain the key database file. The name cannot be a data set. If System SSL cannot locate the file, it then assumes that keyFile is a RACF key ring name. See SSL/TLS information for LDAP utilities for information about System SSL key databases, RACF key rings, and PKCS #11 tokens. This option is ignored if -Z is not specified.
-m mechanism or -S mechanism	Specify the bind method to use. You can use either -m or -S to indicate the bind method. Specify GSSAPI to indicate that a Kerberos Version 5 bind is requested, EXTERNAL to indicate that a certificate (SASL external) bind is requested, CRAM-MD5 to indicate that a SASL Challenge Response Authentication Mechanism bind is requested, or DIGEST-MD5 to indicate that a SASL digest bind is requested. The GSSAPI method requires a protocol level of 3 and the user must have a valid Kerberos Ticket Granting Ticket in their credentials cache by using the Kerberos kinit command-line utility. The EXTERNAL method requires a protocol level of 3. You must also specify -Z, -K, and -P to use certificate bind. Unless you want to use the default certificate in the key database file, RACF key ring, or PKCS #11 token, use the -N option to specify the label of the certificate. The CRAM-MD5 method requires protocol level 3. The -D or -U option must be specified. The DIGEST-MD5 method requires protocol level 3. The -U option must be specified. The -D option can optionally be used to specify the authorization DN. If -m or -S is specified, a simple bind is performed.
-N keyFileDN	Specify the label associated with the certificate in the key database file, RACF key ring, or PKCS #11 token. This option is ignored if -Z is not specified
-p ldapPort	Specify the TCP port where the LDAP server is listening. The default LDAP non-secure port is 389 and the default LDAP secure port is 636.
-P keyFilePW	Specify either the key database file password or the file specification for a System SSL password stash file. When the stash file is used, it must be in the form file:// followed immediately (no blanks) by the file system file specification (for example, file:///etc/ldap/sslstashfile). The stash file must be a file and cannot be a data set. This option is ignored if -Z is not specified.
-U userName	Specify the userName for CRAM-MD5 or DIGEST-MD5 binds. The userName is a short name (UID) that is used to perform bind authentication. This option is required if the -S or -m option is set to DIGEST-MD5.
-w passwd	Use passwd as the password for simple, CRAM-MD5, and DIGEST-MD5 authentication. The default is a NULL string.
-v	Use verbose mode, with many diagnostics written to standard output.
-x sslFipsMode	Specify FIPS mode for SSL/TLS protected connections. The supported FIPS modes are LEVEL1, LEVEL2, LEVEL3, and OFF. When FIPS mode is enabled, it is more restrictive regarding cryptographic algorithms, protocols, and key sizes that can be supported. If this option is not specified, the FIPS mode is set to OFF. This option is ignored if -Z is not specified.
-Z	Use a secure connection to communicate with the LDAP server. Secure connections expect the communication to begin with the SSL/TLS handshake. The -K keyFile option or equivalent environment variable is required when the -Z option is specified. The -P keyFilePW option is required when the -Z option is specified and the key file specifies a file system key database file. Unless you want to use the default certificate in the key database file, RACF key ring, or PKCS #11 token, use the -N option to specify the label of the certificate.

All other command-line inputs result in a syntax error message and the correct syntax is displayed. If the same option is specified multiple times or if both -m and -S are specified, the last value specified is used.

The db2pwden utility sends the PasswordPolicy control as a non-critical control when the user attempts to authenticate to the targeted LDAP server. If the bound user is subject to password policy on the LDAP server, the db2pwden utility parses and displays the warning and error messages from the PasswordPolicy control response.

Diagnosis notes for the db2pwden utility

Exit status is 0 if no errors occur. Errors result in a nonzero exit status and a diagnostic message being written to standard error.

Parameters of the ds2ldif utility

The following table shows the options that you can use for the ds2ldif utility:

All other command-line inputs result in a syntax error message and the correct syntax is displayed. Also, specifying the same option multiple times with different values results in a syntax error.

Usage notes for the ds2ldif utility

1. The output file name option (-o) is a required option for the ds2ldif utility. See Specifying a value for filename for information about specifying the output file name. If the output is to be written to a z/OS UNIX System Services file system, the file name must be fully qualified. If the output is to be written to a sequential or partitioned data set, the data set should be pre-allocated with a record format of variable blocked (VB), a record length of 1028, and a blocksize of 6144. The size of the output LDIF file is generally smaller than the space consumed in the database for both LDBM and TDBM, with the LDIF file often using less than half the space used in the database. However, unusual cases, such as a high amount of binary data or a high number of multi-valued attributes, can inflate the LDIF file size such that it might be slightly larger than the space used in the database. If you are unloading the entire backend, the size of the pertinent data can be estimated from the TDBM database by adding the SPACEF values (in kilobytes) of the DIR_ENTRY, DIR_LONGENTRY, and DIR_LONGATTR tables from a recent Db2® RUNSTATS report. For LDBM backends, the sum of the file sizes of all the LDBM-x.db files (where x is a number such as 1, 2, 3, and so on) provide a database size estimate. However, if the LDBM.ckpt file is large, this might include more data that has yet to be merged into the database files. In this case, you can either include the size of the LDBM.ckpt file in the sum or perform an LDBM commit to get a better estimate.
2. If the ds2ldif utility is invoked with the -s or the -n option and there is only one TDBM, LDBM, or CDBM backend in the LDAP server configuration file, all the directory entries (other than cn=localhost unless the -l option is specified) in that particular TDBM, LDBM, or CDBM backend are unloaded.
3. If a TDBM backend contains entries that have a suffix that is no longer configured in the TDBM section of the LDAP server configuration file, ds2ldif unloads those entries when it is invoked with the -n option. This is not true for an LDBM backend: only the entries that have a currently configured LDBM suffix are unloaded.
4. The ds2ldif utility only unloads owner and ACL information for entries that have a specific owner or ACL. Any entry data with an inherited owner or ACL does not have owner or ACL information unloaded.
5. The ibm-entryuuid attribute is included in each entry unloaded by the ds2ldif utility. The ldapadd utility can be used to add an entry containing an ibm-entryuuid attribute if the bound user is an LDAP root administrator and the server is running in maintenance mode or the -k option (Server Administration server control) is specified in the ldapadd utility. The ldif2ds utility supports loading entries containing the ibm-entryuuid attribute into a TDBM backend. If you do not need the ibm-entryuuid attribute in the loaded entry to have the same value as in the entry that was unloaded, then remove the attribute from each entry in the ds2ldif output file and a new ibm-entryuuid value is assigned when the entry is loaded using ldapadd or ldif2ds.
6. The replicateOperationalAttributes control is added to each unloaded entry when the -j option is not specified and the server compatibility level is 5 or greater. The replicateOperationalAttributes control value has the modifyTimestamp, createTimestamp, creatorsName, and modifiersName attribute types and values for the entry, base64 encoded. Both the ldapadd command and the ldif2ds utility support the specification of the replicateOperationalAttributes control in the input LDIF file. See the replicateOperationalAttributes control in replicateOperationalAttributes for more information about the control. See the serverCompatLevel configuration option serverCompatLevel {3 | 4 | 5 | 6 | 7| 8} for more information about the server compatibility level.
7. If there are password policy operational attribute values present in the entries that are being unloaded, they are included in the LDIF file created by the ds2ldif utility. The password policy operational attributes are pwdChangedTime, pwdAccountLockedTime, pwdExpirationWarned, pwdFailureTime, pwdGraceUseTime, pwdHistory, pwdReset, ibm-pwdAccountLocked, ibm-pwdIndividualPolicyDN, and ibm-pwdGroupPolicyDN.
8. If password policy is active in the LDAP server and there are plans to populate a new LDAP server with the same data, you might want the password policies in the cn=ibmpolicies suffix in the CDBM backend be unloaded along with the data you want in the LDBM or TDBM backends. These unloaded password policy entries must be added to the new server under the cn=ibmpolicies suffix in case there are user or group entries that have ibm-pwdgrouppolicydn or ibm-pwdindividualpolicydn attribute values. These user or group entries cannot be added to the server with the ldapadd or ldif2ds utilities until all referenced password policy entries are added to the CDBM backend.
9. The LDAP Version 3 protocol has a related set of internet drafts that document the introduction of a version mechanism for use in creating LDIF files. The ds2ldif utility always creates "tagged" LDIF files. The LDIF tag consists of a single line at the top of the LDIF file:

   version: 1

   All characters that are contained in the version one LDIF file are portable characters that are represented in the local code page that is specified in the LANG environment variable of the ds2ldif utility. If the unloadRequest extended operation is used, the LDIF file is in the local code page that is specified in the LANG environment variable of the LDAP server. If you reload the data in the LDIF file, ensure the utility that loads the data expects the data in the same code page you used to create the LDIF file. Strings containing nonportable characters (for example, textual values containing multi-byte UTF-8 characters) are base64 encoded.
10. To unload the LDAP server schema entry, specify:

    -s cn=schema

    The schema entry is unloaded in LDIF modify format. The current LDAP server schema entry is unloaded. No merging of TDBM schema into the LDAP server schema is performed when running ds2ldif.
11. If you want to unload the schema entry from a TDBM backend that is migrated from an Integrated Security Services LDAP server, specify the following:

    -s cn=schema,suffixDN

    where suffixDN is the DN of a suffix in the TDBM backend. The schema entry is unloaded in LDIF modify format. The current TDBM schema entry is unloaded. No merging of the LDAP server schema into the TDBM schema entry is performed when running ds2ldif.
12. When you edit the output file that is produced by ds2ldif, use an editor that does not delete blanks at the end of a line. If the output file contains a line that ends with blanks, using such an editor results in deleting the blanks, therefore, changing the value of the attribute. This is important when the line is continued, because the existing blanks no longer separate the last word in the line from the continuation on the next line. The maximum line length in a ds2ldif output file is 77; continued lines are always 77 long when the file is created by ds2ldif. The oedit editor is an example of an editor that deletes blanks and is not used.
13. The LDAP_DEBUG environment variable can also be used to set the debug level for ds2ldif. See debugLevel for more information about specifying the debug level.
14. If running ds2ldif in 64-bit mode, ensure that the user ID running the ds2ldif utility has a sufficient value specified for the MEMLIMIT and ASSIZEMAX values in the OMVS segment so that storage greater than 2 GB can be used. This enables the ds2ldif utility to work properly in 64-bit mode.
15. If you are using ds2ldif to unload many entries that you plan to later load using ldif2ds, specify the -g option on both ds2ldif and ldif2ds. This causes ds2ldif to unload the entries using a depth-first traversal of the directory: the root is unloaded, then each subtree directly below the root is traversed. This order results in improved ldif2ds load capacity, at the cost of some affect on ds2ldif performance. ldapadd performance does not benefit from the -g option for ds2ldif.

Diagnosis notes for the ds2ldif utility

Exit status is 0 if no errors occur. Errors result in a nonzero exit status and a diagnostic message being written to standard error.

Parameters

The following table shows the options that you can use for the ldif2ds utility:

All other command-line inputs result in a syntax error message and the correct syntax is displayed. Also, specifying the same option multiple times with different values results in a syntax error message. File names are case-sensitive unless the file name refers to a data set or DD statement. A data set is indicated by //'dsname' while a DD statement is indicated by //DD:ddname.

Preparing to run ldif2ds

Before invoking ldif2ds, you must:

• Allocate the output data sets used by ldif2ds.
• Create the SYSTEM file used by the prepare step of ldif2ds.
• Set up the user ID to run ldif2ds to ensure sufficient access to directories and files.

ADDUSER LDPADMIN DFLTGRP(LDAPGRP) OMVS(UID(2)
PROGRAM('/bin/sh'))

CONNECT LDAPADMIN GROUP(LDAPGRP)

See Requirements for a user ID that runs the LDAP server for similar commands to create the user ID and group for the LDAP server. Note that the commands also use LDAPGRP.

When you allocate data sets that are required by the ldif2ds utility, the various ldif2ds processing steps use six load data sets and a JCL data set. These data sets must be allocated before invoking ldif2ds and the high-level qualifiers in the data set names must be specified as the value of the -o outHlq option on the command. The ldif2ds utility writes the contents of these data sets, except for the SYSTEM member of the JCL data set which must be created before ldif2ds is run.

• Load record data sets

  The prepare step of ldif2ds writes the load data created from each LDIF entry into the load record data sets. Each data set contains the records for one database table and is used as input to the Db2 Load Utility when loading that table.

  • Data set names:
    • outHlq.BULKLOAD.INPUT.DESC - DIR_DESC load data set
    • outHlq.BULKLOAD.INPUT.ENTRY - DIR_ENTRY load data set
    • outHlq.BULKLOAD.INPUT.LATTR - DIR_LONGATTR load data set
    • outHlq.BULKLOAD.INPUT.LENTRY - DIR_LONGENTRY load data set
    • outHlq.BULKLOAD.INPUT.REPLICA - DIR_REPLICA load data set
    • outHlq.BULKLOAD.INPUT.SEARCH - DIR_SEARCH load data set
  • Data set format:
    • Sequential (non-PDS)
    • Record format = VB
  • Data set record length and block size:

    The record length depends on the page size of the corresponding table space. The actual record length might be reduced slightly by ldif2ds at run time.

    For a 32 K page size in Db2, use LRECL=32756, BLKSIZE=32760.

    This record length and block size can also be used for smaller page sizes. However, for smaller page sizes, a smaller LRECL and BLKSIZE can be used to reduce the required disk space. For example, on 3390 DASD, LRECL=27994, BLKSIZE=27998 enables two blocks for each track and, in general, more bytes for each track to be written. For the smaller page sizes, the LRECL and BLKSIZE must be at least pagesize + 6 and pagesize + 10, in that order.

  • Data set size:

    A rough estimate for the size (in bytes) of each data set is as follows:

    • outHLQ.BULKLOAD.INPUT.DESC:
      • 20 * (average depth) * (number of entries in the LDIF files)
      • where average depth = (average number of levels in a DN) - (average number of levels in each DNs suffix) + 1
    • outHLQ.BULKLOAD.INPUT.ENTRY, outHLQ.BULKLOAD.INPUT.LATTR, and outHLQ.BULKLOAD.INPUT.LENTRY:
      • The combined space required for these files is roughly
      • (number of bytes in the LDIF input files) * 3.0
      • If most directory entries are shorter than the DIR_ENTRY page size, and most attributes are shorter than the attrOverflowSize in the LDAP server configuration file, then most of the data is written in the outHLQ.BULKLOAD.INPUT.ENTRY data set. Otherwise, you might want to allocate each of these three data sets as this maximum size to ensure that you do not run out of space.
    • outHlq.BULKLOAD.INPUT.REPLICA:
      • (number of replicas defined in the LDIF input files) * 24
      • If there are no replica entries defined in the LDIF input files, use a minimum size to allocate the data set, such as one block.
    • outHLQ.BULKLOAD.INPUT.SEARCH:
      • (number of bytes in the LDIF input files) * 2.5
• JCL data set

  The JCL data set is a PDS whose members contain system information, status information, and the JCL to run Db2 Load Utility for each database table that must be loaded. The prepare and load steps of ldif2ds use the status information. The prepare step writes the contents of the JCL members of the JCL data set, using the information in the system member. The system member of the JCL data set must be created by the user before ldif2ds is invoked to run the prepare step.

  • Data set name:
    • outHlq.BULKLOAD.JCL
  • Members:
    • outHlq.BULKLOAD.JCL(JDESC) - DIR_DESC load JCL
    • outHlq.BULKLOAD.JCL(JENTR) - DIR_ENTRY load JCL
    • outHlq.BULKLOAD.JCL(JLATT) - DIR_LONGATTR load JCL
    • outHlq.BULKLOAD.JCL(JLENT) - DIR_LONGENTRY load JCL
    • outHlq.BULKLOAD.JCL(JREPL) - DIR_REPLICA load JCL
    • outHlq.BULKLOAD.JCL(JSRCH) - DIR_SEARCH load JCL
    • outHlq.BULKLOAD.JCL(STATUS) - Status information
    • outHlq.BULKLOAD.JCL(SYSTEM) - System information - see below
  • Data set format:
    • Partitioned (PDS)
    • Record format = FB
    • Record length = 80
  • Data set size:
    • 200 K bytes

When you create the SYSTEM member, the contents of the SYSTEM member, outHlq.BULKLOAD.JCL(SYSTEM), must be created before invoking the contents of the SYSTEM member, outHlq.BULKLOAD.JCL(SYSTEM), must be created before invoking ldif2ds to run the prepare step, which uses the information in the SYSTEM member to create the JCL to start the Db2 Load Utility to load each of the database tables. to run the prepare step, which uses the information in the SYSTEM member to create the JCL to start the Db2 Load Utility to load each of the database tables.

• Format of SYSTEM records

  HLQ db2hlq            High level qualifier for DB2 datasets 
  JOBCARD //jobname...  Job card record for JCL 
  #Comment record       Ignored if first non-blank character is #

• The SYSTEM member must contain one or more JOBCARD records. The first JOBCARD record must contain the job name. The JOB statement might span multiple JOBCARD records and must follow the JCL continuation rules. The maximum length of each JCL record is 72 characters. JES control statements might also be included in the JOBCARD specification. For example:

  JOBCARD //DB2TDBMn JOB (ACCOUNT),PGMR,CLASS=A,MSGCLASS=A,MSGLEVEL=1,
  JOBCARD // NOTIFY= &SYSUID
  JOBCARD /*JOBPARM SYSAFF=SYS1

  The HLQ record is optional. The Db2 high-level qualifier defaults to DSN if the HLQ record is not specified. If specified, the maximum length of the HLQ value is 35.

  Make sure that there are no sequence numbers at the end of each line of the SYSTEM member.

• To differentiate the load jobs in the 6 JCL members of the JCL PDS, the contents of the SYSTEM member, outHlq.BULKLOAD.JCL(SYSTEM), must be created before invoking ldif2ds to run the prepare step, which uses the information in the SYSTEM member to create the JCL to start the Db2 Load Utility to load each of the database tables. replaces the last character of the job name with the digits 1 through 6, as follows:
  • Jobname ends in 1 - JCL for loading DIR_DESC table, in outHlq.BULKLOAD.JCL(JDESC)
  • Jobname ends in 2 - JCL for loading DIR_ENTRY table, in outHlq.BULKLOAD.JCL(JENTRY)
  • Jobname ends in 3 - JCL for loading DIR_LONGATTR table, in outHlq.BULKLOAD.JCL(JLATT)
  • Jobname ends in 4 - JCL for loading DIR_LONGENTRY table, in outHlq.BULKLOAD.JCL(JLENT)
  • Jobname ends in 6 - JCL for loading DIR_REPLICA table, in outHlq.BULKLOAD.JCL(JREPL)
  • Jobname ends in 5 - JCL for loading DIR_SEARCH table, in outHlq.BULKLOAD.JCL(JSRCH)

When to use ldif2ds

Both the ldif2ds and ldapadd utilities can be used to load entries into a TDBM database. There are advantages and disadvantages to each of these. Following is a list of considerations that can help determine which method to use when loading entries.

The ldif2ds utility usage is complex, but it is fast. The ldapadd utility usage is simpler, but it is slower.

For one-time additions of 100K or more entries, or for frequent additions of 10K or more entries, use ldif2ds. For infrequent additions of less than 10K entries, use ldapadd. For additions of between 10K and 100K entries, use either ldif2ds or ldapadd.

ldif2ds performance considerations

The ldif2ds utility performance considerations are:

1. ldif2ds uses much storage when adding many entries. Make sure that you have sufficient memory available.
2. If the entries to load are in genealogical order, ldif2ds can take certain shortcuts to greatly reduce the storage used during the check and prepare steps. This allows ldif2ds to process more entries at one time. Genealogical order is the order that results from doing a depth-first traversal of a directory: the root is visited, then each subtree directly below the root is traversed. Specify the -g option to indicate that the LDIF input is in this order. The -g option of the ds2ldif utility can be used to unload entries in genealogical order. Do not specify the -g option on ldif2ds if the input is not in genealogical order.
3. If the parent of an entry being added is in the TDBM database, then ldif2ds must also check the database to ensure that the entry itself does not exist. Therefore, to minimize the database checks, include the parents of the entries being added in the ldif2ds input whenever possible. For example, do not use ldapadd to add a suffix and then use ldif2ds to add all the entries under the suffix. Instead, include the suffix in the ldif2ds input.
4. Do not specify the debug command-line option, -d. Usage of debug might affect performance even when there is little debug output. Only specify -d when an error occurs that you cannot fix.
5. By default, for better load performance ldif2ds sets the LOG NO option in the Db2 Load Utility JCL created during the prepare (-p) step. When the load (-l) step invokes the Db2 Load Utility, the Load Utility sets the copy pending restriction against the table space. The database can be read but cannot be updated until the restriction is removed, for example, by running the Db2 REORG or COPY utility. To avoid entering the copy pending state (for example, when the database already contains many entries), change LOG NO to LOG YES in the JCL. This is done by ldif2ds during the prepare step if the -j option is specified along with the -p option. It can also be performed manually in each of the outHLQ.BULKLOAD.JCL members after the prepare step if the load step is run separately from the prepare step.

ldif2ds normal usage

ldif2ds recovery

The ldif2ds utility can determine whether the submission of the Db2 Load Utility jobs is successful, but it cannot determine if the Db2 Load Utility jobs themselves succeed. In fact, ldif2ds typically terminates before the jobs are finished. Therefore, the final ldif2ds success message displays even if one or more of the jobs eventually fails.

If a Db2 Load Utility job fails, stop all the Db2 Load Utility invocations that failed, using

-TERM UTIL(BULKx)

where x is the last number in the job name of the failing job. Then, there are two alternatives for recovery.

Recovery process 1

The first recovery alternative is not selective in nature and might result in unnecessary reloading of data. This alternative must be used for recovery when:

• The ldif2ds utility is run with the load (-l) option immediately after creating the TDBM database (that is, without first starting the server or running ldif2ds with the check (-c) or prepare (-p) options).
• Loading the DIR_ENTRY, DIR_LONGENTRY, or DIR_LONGATTR table fails and a full image copy of these tables does not exist.

Following is the first recovery alternative process:

1. If full image copies exist for all six table spaces, use the Db2 Recover Utility to recover all six table spaces from those full image copies. Otherwise, drop and re-create the DIR_DESC, DIR_ENTRY, DIR_LONGATTR, DIR_LONGENTRY, DIR_REPLICA, and DIR_SEARCH tables.
2. See the Db2 Utility Guide and Reference in IMS in IBM Knowledge Center for information about correcting the problems logged in the failing jobs.
3. Run ldif2ds with only the load (-l) option again.

Recovery process 2

The second recovery alternative requires less processing, but requires a greater understanding of the problem. It cannot be used for recovery when:

• The ldif2ds utility is invoked with the load (-l) option immediately after creating the TDBM database.
• Loading the DIR_ENTRY, DIR_LONGATTR, or DIR_LONGENTRY table fails and a full image copy of these tables does not exist.

Following is the second recovery alternative process:

• If the load jobs that failed involve only the DIR_DESC or DIR_SEARCH tables, follow these steps:
  1. If a full image copy exists for the failing table spaces, use the Db2 Recover Utility to recover these table spaces from those full image copies. Otherwise, drop and re-create the failing tables.
  2. See IMS in IBM Knowledge Center for information about correcting problems logged in the failing jobs.
  3. Manually resubmit the Db2 Load Utility jobs that failed.
• If the load jobs that failed involve the DIR_ENTRY, DIR_LONGATTR, or DIR_LONGENTRY tables and a full image copy exists (you must use the first recovery alternative if a full image copy does not exist), follow these steps:
  1. If a full image copy exists for the affected table spaces, use the Db2 Recover Utility to recover these table spaces from those full image copies. Otherwise, you must use the first alternative.
  2. See IMS in IBM Knowledge Center for information about correcting problems logged in the failing jobs.
  3. Manually resubmit the Db2 Load Utility jobs for all the affected tables.

Usage of the ldif2ds utility

1. All input files specified with the -i and -e options can be z/OS UNIX file system files or data sets. To use data sets with ldif2ds, you must use a VB record format. Further, separator lines between directory entries in the LDIF file must contain no characters.
2. The ldif2ds utility can be invoked to run the check (-c) and prepare (-p) steps while an LDAP server using the same TDBM database is active. The LDAP server must be down when the load (-l) step is run.
3. The LDAP_DEBUG environment variable can also be used to set the debug level for ldif2ds. See debugLevel for more information about specifying the debug level.
4. Run the Db2 RUNSTATS utility when the data is loaded so that Db2 queries are optimized. See Performance tuning for detailed information about running the Db2 RUNSTATS utility.
5. No replication is performed for entries added by ldif2ds. Advanced and basic replication entries can be added using ldif2ds, but replication does not begin until the LDAP server is started.
6. Referral entries can be added by ldif2ds.
7. Only one TDBM database is loaded in an invocation of ldif2ds. All the LDIF entries in the LDIF input files and schema input file must contain DNs that belong to the same TDBM database. The parent of each LDIF entry must either be already in the database or must be a prior LDIF entry within these LDIF input files.
8. ldif2ds cannot be used to modify the LDAP server schema. The schema must already contain all the attributes and object classes used by the entries being added.
9. Do not specify the aclSource and ownerSource attributes in an LDIF entry because they are ignored. These attributes are set only by the system.
10. By default, the ldif2ds utility check processing is terminated after 100 syntax errors or schema errors are detected. This value can be changed with the option, -C. A value of 0 indicates no limit. The ldif2ds utility prepare and load processing is terminated after the first error, and these processing phases have no adjustable error limit.
11. Because typical ldif2ds usage can involve multiple invocations to check, prepare, and load the entries, ldif2ds maintains a status file to keep information about the last successful step processed. The status file is outHlq.BULKLOAD.JCL(STATUS), where outHlq is the value of the -o option on the command. Any invocation of ldif2ds with the same value for -o is considered a continuation of processing of an earlier invocation.

    The status file contains a STATUS record and a TIME record. When the prepare (-p) step is successful, the status is changed to STATUS P and the TIME record is set to the current time. The load step (-l) checks the STATUS record and exits if the status is not P. When the load step is successful, the status is changed to STATUS L and the TIME record is reset to the current time.

12. The prepare step uses the current LDAP server schema to create the load records for the entries to be added. Do not change the schema between the prepare step and the load step. This can result in loading entries that might not be valid for the new schema.
13. During the prepare (-p) step, the RDN of the new LDIF entry is checked to ensure that all the values specified in the RDN are also specified as attributes in the LDIF entry. Missing attributes are added to the entry before it is loaded into the directory. No messages are issued indicating this.
14. The ldif2ds utility encrypts or hashes clear text userPassword, secretKey, ibm-replicaKeyPwd, ibm-slapdAdminPw, ibm-slapdMasterPw and replicaCredentials attribute values for new entries loaded into the TDBM backend with the pwEncryption and secretEncryption methods specified in the LDAP server configuration file. The ldif2ds utility loads the LDIF format of an encrypted or hashed value unloaded by the ldif2ds utility with or without the -t option. When using the ldif2ds utility to load entries that have userPassword or ibm-slapdAdminPw attribute values hashed with crypt, the pwCryptCompat configuration option must be set in the same manner as when the values were originally hashed. The ldif2ds utility expects that textual data contained within the LDIF file is portable and of UTF-8 origin.
15. If you are maintaining multiple identical TDBM databases, you might want to run the prepare (-p) and load (-l) steps of ldif2ds against each TDBM database. Do not try to use the load data created by running the ldif2ds utility prepare step against one database to load entries on a different database. This can result in an unusable TDBM database.
16. Each loaded entry has a creatorsname, modifiersname, createtimestamp, modifytimestamp, and ibm-entryuuid attribute. The values for these attributes can be specified in the LDIF input for the entry. If not:
    • The creatorsname and modifiersname attributes are assigned the value of the -b command-line option if it is specified; otherwise, they are assigned the value of the adminDN option in the LDAP server configuration file.
    • The createtimestamp and modifytimestamp attributes are assigned a time set during utility initialization.
    • The ibm-entryuuid attribute is assigned a unique value generated by the utility.
17. When LDIF input contains a replicateOperationalAttributes control and the control has a creatorsname, modifiersname, createtimestamp, or modifytimestamp attribute value, that attribute value is assigned for the attribute in the entry being loaded. An attribute value assigned from the replicateOperationalAttributes control replaces any other assigned value for that attribute described in the previous usage note.
18. If there are user or group entries that have ibm-pwdgrouppolicydn or ibm-pwdindividualpolicydn attribute values specified, the password policy entries referenced in these values must exist in the CDBM backend under the cn=ibmpolicies suffix before using the check (-c) step of the ldif2ds utility. Before running ldif2ds, the server must be started with the CDBM backend configured and the server compatibility set to 6 and the necessary password policy entries must be added. When the password policy entries are added to the CDBM backend, shut down the server and then the ldif2ds utility can be run.

Diagnosis notes for the ldif2ds utility

Exit status is 0 if no errors occur. Errors result in a nonzero exit status and a diagnostic message being written to standard error.

Parameters for the ldapdiff utility

The following table shows the general options that you can use for the ldapdiff utility.

The following options apply to the supplier server and are denoted by an initial ’s’ in the option name:

safkeyring://userid/keyFile

safkeyring:///keyFile

safkeyring://userid/keyFile

safkeyring:///keyFile

The following options apply to the consumer server and are denoted by an initial ’c’ in the option name:

safkeyring://userid/keyFile

safkeyring:///keyFile

safkeyring://userid/keyFile

safkeyring:///keyFile

All other command-line inputs result in a syntax error message and the correct syntax is displayed. Also, specifying the same option multiple times results in the last specified option being used.

Usage notes for the ldapdiff utility

1. The ldapdiff utility is a Java-based utility and requires IBM® 31-bit SDK for z/OS, Java 2 Technology Edition, V7.1 (5655-W43) or later to be installed on the system.
2. The ldapdiff utility is used to bring a supplier and a consumer server in sync before starting advanced replication. The ldapdiff utility requires that the base DN, which is being compared, exist on at least one of the servers.
3. The ldapdiff utility is a diagnostic and corrective tool. It is not designed to be run as routine maintenance. If there are out of sync replication-related errors observed, an LDAP administrator with the appropriate administrative roles might decide to run the utility to correct the out of sync condition.
4. When the ldapdiff utility is run, do not make any updates to either of the targeted LDAP servers. If the ldapdiffldapdiff utility is run while updates are being made, it cannot be guaranteed that all discrepancies are accurately reported or fixed. An LDAP root, directory data, or replication administrator must manually quiesce or suspend all update activity to the two subtrees being compared on the two servers. The ldapdiff utility does not check at initialization time to determine if the servers are quiesced or not. The replication context subtree can be quiesced by using the Quiesce or unquiesce context extended operation on the ldapexop utility. See ldapexop utility for information about the Quiesce or unquiesce context extended operation.
5. Use the fix option (-F) with caution because it automatically synchronizes all the entries from the supplier server to the consumer server starting from the baseDn. This synchronization can result in unintentional results on the consumer server such as the deletion of replication topology entries, RACF users, groups, user-group connections, resource profiles, and other entries. Use the -L option first to write any differences between the supplier and consumer servers in LDIF file format. An LDAP administrator analyzes the output LDIF file to ensure that the updates are correct. If they are correct, the changes can be manually applied to the consumer server using the ldapmodify command or the ldapdiff utility can be rerun with the fix option (-F) specified.

   If the -F option is specified, use the Server Administration server control option (-a) to enable the ldapdiff utility to write to a read-only replica. The Server Administration server control also allows ldapdiff to modify operational attributes such as aclPropagate, aclSource, createTimeStamp, creatorsName, entryOwner, ibm-entryuuid, ibm-pwdGroupPolicyDN, modifiersName, modifyTimeStamp, ownerPropagate, ownerSource, pwdAccountLockedTime, pwdChangedTime, pwdExpirationWarned, pwdFailureTime, pwdGraceUseTime, pwdHistory, pwdReset, ibm-pwdAccountLocked, and ibm-pwdIndividualPolicyDN.

6. The ldapdiff utility performs two passes to get the supplier and consumer servers back in sync.
   In the first pass, the ldapdiff utility traverses the supplier server and does the following:

   • Checks for any extra entries on the supplier server that are not on the consumer server. The extra entries are added to the consumer server if the -F option is specified.
   • Compares the entries that exist on both the supplier and consumer servers. If there are mismatches, the consumer server entries are modified to match the supplier server entries if the -F option is specified.

   In the second pass, the ldapdiff utility traverses the consumer server to check for any extra entries on the consumer server. The extra entries are deleted from the consumer server if the -F option is specified. The second pass can be skipped by specifying the -x option.

7. The supplier and consumer bind DNs (-sD and -cD options) must be able to read the attributes in the entries being compared. In addition, if the fix option (-F) is specified, the consumer bind DN must also be able to update attributes and add and delete entries.
8. The ldapdiff utility traverses each entry in the directory subtree on the supplier server and compares its contents with the corresponding entry on the consumer server. Because each entry must be retrieved, running the ldapdiff utility can take a long time and can generate lots of read requests to the supplier and consumer servers. Depending on how many differences are found and whether the fix option (-F) is specified, the ldapdiff utility can also generate an equal amount of update (for example add, delete, modify) requests to the consumer server. Use the ldapdiff utility once between servers, when replication is initially setup. For example, if your replication topology has two peer masters and two replica servers, you might want to run the ldapdiff utility between peer 1 and peer 2. Then, if replication is suspended, run ldapdiff concurrently between peer 1 and replica 1 and between peer 2 and replica 2. If replica servers are out of sync with their master servers, the ldapdiff utility can be run to identify and correct out of sync conditions.
9. The following password policy operational attributes in user entries are only compared if both the supplier and consumer servers are participating in password policy:
   • pwdChangedTime
   • pwdReset
   • ibm-pwdAccountLocked
   • pwdExpirationWarned
   • pwdGraceUseTime
   • pwdFailureTime
   • pwdAccountLockedTime
   • pwdHistory
   Also, the following attributes for specifying individual and group policies in user and group entries are only compared if both the supplier and consumer servers are participating in password policy:
   • ibm-pwdIndividualPolicyDn
   • ibm-pwdGroupPolicyDn
10. If the supplier and consumer servers are participating in password policy, the ldapdiff utility needs to be run to synchronize the password policy entries in the cn=ibmpolicies subtrees on both servers, and then run to synchronize the entries in the LDBM and TDBM backends. There can be situations where the ldapdiff utility must be run for the entries in LDBM and TDBM subtrees first, and then run for the password policies entries. For example, if the consumer server has a password policy that no longer exists on the supplier server, but entries on the consumer server still reference that password policy, the password policy cannot be deleted until all references to it are removed. In this case, running ldapdiff for the LDBM and TDBM entries first removes those references, and then the ldapdiff utility can be run to synchronize the password policy entries.
11. The ldapdiff utility displays a message after it has finished comparing every 100th entry.

Diagnosis notes for the ldapdiff utility

Exit status is 0 if no errors occur. Errors result in a nonzero exit status and a diagnostic message being written to standard error.

Parameters for the ldapexop utility

Option names can normally be specified in a reduced manner with as few as one or two of the initial characters specified.

All other command-line inputs result in a syntax error message, after the correct syntax is displayed. Except for the –op option, if the same option is specified multiple times, the last value specified is used. The -op option must be specified only once.

Usage notes for the ldapexop utility

1. You must be bound as an LDAP administrator with the appropriate authority to successfully perform all extended operations (other than the User type extended operation) against the z/OS LDAP server. See Table 1 for information about which extended operations are allowed to be performed by administrative group members.
2. The ldapexop utility sends the PasswordPolicy control as a non-critical control when the user attempts to authenticate to the targeted LDAP server. If the bound user is subject to password policy on the LDAP server, the ldapexop utility parses and displays the warning and error messages from the PasswordPolicy control response.
3. The LDAP_DEBUG environment variable can be used to set the debug level. For more information about specifying the debug level using keywords, decimal, hexadecimal, and plus and minus syntax, see Table 1 for a list of specific debug levels.
4. You can specify an LDAP URL for host on the -h option. See ldap_init() in z/OS IBM Tivoli Directory Server Client Programming for z/OS for more information.
5. The password prompt (-w ?) is not supported when running from TSO or batch. In these environments, the password value must be specified on the -w option.

   The getpass() routine used to prompt for the password returns at most PASS_MAX number of characters, truncating any additional characters. See the description of getpass() in z/OS XL C/C++ Runtime Library Reference for more information. If the length of the specified password is greater than PASS_MAX, the password value must be specified on the -w option.

Diagnosis notes for the ldapexop utility

Exit status is 0 if no errors occur. Errors result in a nonzero exit status and a diagnostic message being written to standard error.

See Supported extended operations for additional diagnostic information about each of the extended operations.