Server utilities
This section describes the db2pwden, ds2ldif, ldif2ds, ldapdiff, and ldapexop server utilities.
db2pwden utility
The db2pwden utility is provided to encrypt or hash all unencrypted, AES encrypted, and DES encrypted user passwords in an already loaded TDBM, LDBM, or CDBM backend. The utility runs as a client operation while the server is active, and causes the server to encrypt or hash all the userPassword attribute values that are unencrypted, AES encrypted, or DES encrypted with the pwEncryption method configured on the LDAP server. The utility must be run by an LDAP administrator with the appropriate authority or a user with the authority to update password values. See Administrative roles for more information about administrative role authority.
Format of the db2pwden utility
db2pwden [options]
Parameters of the db2pwden utility
- options
- The following table shows the options that you can use for the db2pwden
utility.
Table 1. Options for the db2pwden utility 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.
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
orCRAM-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 aDIGEST-MD5
challenge; otherwise, it is optional.-h ldapHost Specify the hostname 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 mechanismSpecify 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, orDIGEST-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 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
-pldapPort 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
orDIGEST-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
, andDIGEST-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,
andOFF
. 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 toOFF
.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.
Examples of the db2pwden utility
Following are examples using the db2pwden utility:
- The following command:
encrypts or hashes all unencrypted, AES encrypted, or DES encrypted passwords in the TDBM, LDBM, or CDBM backend at the LDAP server on the local host. The base is defined in the LDAP_BASEDN environment variable. The encryption or hashing method used is the pwEncryption method configured on the LDAP server.db2pwden -D "cn=admin" -w secret
- The following command:
encrypts or hashes all unencrypted, AES encrypted, or DES encrypted passwords starting at the basedb2pwden -h ushost -p 391 -D "cn=admin" -w secret -b "o=university, c=US"
"o=university,c=US"
in the TDBM or LDBM backend on hostushost
at port391
. The encryption or hashing method used is the pwEncryption method configured on the LDAP server.
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.
ds2ldif utility
The ds2ldif utility is used to unload entries from a directory that is stored in a TDBM, LDBM, or CDBM backend into a file in LDAP Data Interchange Format (LDIF). The utility is also used to obtain the LDAP server schema entry. ds2ldif cannot be used to unload a GDBM or SDBM backend.
- ds2ldif31 (runs in a 31-bit environment)
- ds2ldif64 (runs in a 64-bit environment)
If using the ds2ldif utility in an interoperability environment, see Guidelines for interoperability between non-z/OS TDS and z/OS TDS for more information.
Format of the ds2ldif utility
ds2ldif31 | ds2ldif64 -o outputFile [-d debugLevel] [-f confFile] [-g]
[-j] [-k keyFile] [-r [-q filterDN]]
[[-s subtreeDN] | [-n beName] [-l]] [-t]
[-w adminPW] [-Z] [-?]
Parameters of the ds2ldif utility
The following table shows the options that you can use for the ds2ldif utility:
Option | Description |
---|---|
-? | Display the usage. |
-d debugLevel | Specify the level of the 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. |
-F confFile | Specify the name of the LDAP server configuration file to use. This configuration file only needs to contain information for the backend to be unloaded. The configuration data set specified by the CONFIG DD statement is used if the -F option is not specified. The /etc/ldap/ds.conf configuration file is used if the -F option is not specified and the CONFIG DD statement is not defined. |
-g | Specify to unload entries in genealogical order. This unloads entries in each subtree together, doing a depth-first traversal of the directory. Specify this option when you are unloading many entries that you are loaded later, using the ldif2ds utility with the -g option, because this order of entries improves the capacity of ldif2ds to process large numbers of entries. Unloading in this order requires more processing and impacts unload performance. |
-j | Indicate that the replicateOperationalAttributes control value is not written to the output LDIF file. The replicateOperationalAttributes control value has the modifyTimestamp, createTimestamp, creatorsName, and modifiersName attribute types and values for the entry base64 encoded. |
-k keyFile | Specify the name of the file containing the LDAP server encryption keys. If
running ds2ldif in batch, the data set specified by the LDAPKEYS
DD statement is used if the -k option is not specified. The key file must
be specified if any entries unloaded have userPassword,
secretKey, replicaCredentials,
ibm-replicaKeyPwd, ibm-slapdAdmimPw, or
ibm-slapdMasterPw attribute values that are encrypted using the DES or AES
algorithm and not using ICSF. These attribute values are decrypted and base64 encoded as the entry
is written to the output LDIF file. |
-l | Specify that entries under the cn=localhost suffix are unloaded
from the LDBM or TDBM backend. When an entire LDBM or TDBM backend is unloaded, the entries under
cn=localhost are not unloaded unless the -l option is specified.
The -l option cannot be used when the -s option is
specified. |
-n beName | Specify the name of the LDBM, TDBM, or CDBM backend to unload. This is the name that is assigned to the backend on its database record in the LDAP server configuration file or the name that is automatically generated when the LDAP server is started. This can be used to indicate which LDBM, TDBM, or CDBM backend to process when there are multiple LDBM, TDBM, or CDBM backends in the configuration file. The -n option cannot be used when the -s option is specified. |
-o outputFile | Specify the name of an output file to contain the unloaded directory entries. See Specifying a value for filename for information about how to specify the file name. |
-q filterDN | Specify a distinguished name (DN) of a replication filter entry which contains
ibm-replicationFilterAttr attribute values. These values are filters that are
used to skip entire entries or attributes within entries while unloading the directory. See Partial replication for more information about replication filter entries. The targeted LDAP server must be running and the -r option must be specified when the -q option is specified. Also, the CDBM backend must be configured and useAdvancedReplication on specified in the CDBM backend section of the server configuration file to perform unload filtering. |
-r | Perform an unloadRequest extended operation (1.3.18.0.2.12.62) to unload the subtree or backend. If the LDAP server that contains the backend that is to be unloaded is running, an unloadRequest extended operation can be sent to the LDAP server to unload the entries. |
-s subtreeDN | Identify the DN of the top entry of the subtree whose entries are to be unloaded.
This entry, plus all below it in the directory hierarchy, are written to the output file. The
-s option must be used to unload the LDAP server schema entry,
cn=schema . The -s option cannot be used when the
-n option is specified. |
-t | Specify that hashed userPassword and ibm-slapdAdminPw attribute values are unloaded with their encryption tag in clear text. See Using the -t (tagging) option for more information about this option. |
-w adminPW | When using the unloadRequest extended operation, specify the password of the LDAP root administrator defined in the configuration file. Do not specify the -w option if the adminPW option is specified in the LDAP server configuration file. In this case, the value from the server configuration file is used to perform the LDAP bind before sending the unloadRequest extended operation to the LDAP server. If the adminPW configuration option is not present and the -w option is not specified or a ? is specified on the -w option, a prompt is displayed for the LDAP root administrator password. |
-Z | When using the unloadRequest extended operation, use SSL to
encrypt the communication between the ds2ldif utility and the LDAP server. By
default, the ds2ldif utility attempts to use SSL to communicate with the LDAP
server assuming that the LDAP server configuration file has the necessary SSL options (for example,
sslKeyRingFile, sslKeyRingFilePW,
sslCertficiate, sslKeyRingStashFile,
sslFipsState) specified along with a secure listen option (for
example, listen ldaps:// ). If SSL cannot be used, the ds2ldif
utility fails. |
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.
Examples of the ds2ldif utility
- This example starts the 31-bit version of ds2ldif to unload all the entries
from the TDBM backend named
tdbm1
in the LDAP server configuration file/etc/ldap/ds.conf
. The replicateOperationalAttributes control is not included in the unloaded entries. The two entries that are in the TDBM backend namedtdbm1
are written to data setADMIN3.LDIF.DATA
.
Theds2ldif31 -j -o "//'ADMIN3.LDIF.DATA'" -n tdbm1 -f /etc/ldap/ds.conf
ADMIN3.LDIF.DATA
output data set contains the following:version: 1 dn: o=tdbm objectclass: organization objectclass: top o: tdbm ibm-entryuuid: 3A67E000-2E5C-1876-99D0-402064040959 aclentry: cn=Anybody:normal:rsc:system:rsc aclpropagate: TRUE entryowner: CN=ADMIN ownerpropagate: TRUE dn: cn=entry1,o=tdbm objectclass: newPilotPerson objectclass: person objectclass: top cn: entry1 sn: 1 uid: entry1 userpassword:: c2VjcmV0 ibm-entryuuid: 0C3DE000-F85D-1884-94B3-402084027431
- This example starts the 64-bit version of ds2ldif to unload all
the data at and underneath the
o=ldbm
subtreeDN entry by performing an unloadRequest extended operation over SSL with an LDAP root administrator password ofsecret
. By default, the replicateOperationalAttributes control is included in the unloaded entries. The entries are written to file /ldbmdata/ldif.data on the system where the LDAP server is running.
The /ldbmdata/ldif.data output file contains the following unloaded entries:ds2ldif64 -o /ldbmdata/ldif.data -s o=ldbm -r -w secret -Z -f /etc/ldap/ds.conf
version: 1 dn: o=ldbm control: 1.3.18.0.2.10.19 false:: MIGnMB8KAQAwGgQMY3JlYXRvcnNOYW1lMQoECGNuPWF kbWluMDAKAQAwKwQPY3JlYXRlVGltZXN0YW1wMRgEFjIwMDgxMDI0MTY0MDUwLjYzMDg5NFowIAo BADAbBA1tb2RpZmllcnNOYW1lMQoECGNuPWFkbWluMDAKAQAwKwQPbW9kaWZ5VGltZXN0YW1wMRg EFjIwMDgxMDI0MTY0MDUwLjYzMDg5NFo= o: ldbm objectclass: organization objectclass: top ibm-entryuuid: 9A063000-FA92-1901-9FBA-402084027431 aclentry: cn=Anybody:normal:rsc:system:rsc aclpropagate: TRUE entryowner: CN=ADMIN ownerpropagate: TRUE dn: cn=replfilter,o=ldbm control: 1.3.18.0.2.10.19 false:: MIGnMB8KAQAwGgQMY3JlYXRvcnNOYW1lMQoECGNuPWF kbWluMDAKAQAwKwQPY3JlYXRlVGltZXN0YW1wMRgEFjIwMDkwMTE2MTYxMzI5LjA2NTg4NlowIAo BADAbBA1tb2RpZmllcnNOYW1lMQoECGNuPWFkbWluMDAKAQAwKwQPbW9kaWZ5VGltZXN0YW1wMRg EFjIwMDkwMTE2MTYxMzI5LjA2NTg4Nlo= objectclass: ibm-replicationFilter objectclass: top cn: replfilter ibm-replicationfilterattr: (objectclass=person):(cn,sn) ibm-entryuuid: 1014C000-B229-1970-817D-402084027431 dn: ou=rochester,o=ldbm control: 1.3.18.0.2.10.19 false:: MIGnMB8KAQAwGgQMY3JlYXRvcnNOYW1lMQoECGNuPWF kbWluMDAKAQAwKwQPY3JlYXRlVGltZXN0YW1wMRgEFjIwMDkwMTE2MTYwODU5LjM5NjkwOVowIAo BADAbBA1tb2RpZmllcnNOYW1lMQoECGNuPWFkbWluMDAKAQAwKwQPbW9kaWZ5VGltZXN0YW1wMRg EFjIwMDkwMTE2MTYwODU5LjM5NjkwOVo= objectclass: organizationalUnit objectclass: top ou: rochester ibm-entryuuid: 60E5C000-B11B-1970-817D-402084027431 dn: cn=entry1,ou=rochester,o=ldbm control: 1.3.18.0.2.10.19 false:: MIGnMB8KAQAwGgQMY3JlYXRvcnNOYW1lMQoECGNuPWF kbWluMDAKAQAwKwQPY3JlYXRlVGltZXN0YW1wMRgEFjIwMDkwMTE2MTYwOTUxLjMxNjM3MVowIAo BADAbBA1tb2RpZmllcnNOYW1lMQoECGNuPWFkbWluMDAKAQAwKwQPbW9kaWZ5VGltZXN0YW1wMRg EFjIwMDkwMTE2MTYwOTUxLjMxNjM3MVo= objectclass: newPilotPerson objectclass: person objectclass: top cn: entry1 sn: entry1sn userpassword:: c2VjcmV0 description: A very nice person ibm-entryuuid: 4D3BE000-B14F-1970-817D-402084027431
- This example builds on the previous example, however, uses a replication filter entry to filter
the unload data. The
cn=replfilter,o=ldbm
replication filter entry from 2 has an ibm-replicationFilterAttr attribute value that only allows entries that have an objectclass value of person to be unloaded and only unloads the cn and sn attributes (if any) from these entries. See Partial replication for more information about replication filtering.
The /ldbmdata/filtered.ldif.data output file contains the following unloaded entry:ds2ldif31 -o /ldbmdata/filtered.ldif.data –s o=ldbm -r -w secret –q cn=replfilter,o=ldbm -f /etc/ldap/ds.conf
version: 1 dn: cn=entry1,ou=rochester,o=ldbm control: 1.3.18.0.2.10.19 false:: MIGnMB8KAQAwGgQMY3JlYXRvcnNOYW1lMQoECGNuPWF kbWluMDAKAQAwKwQPY3JlYXRlVGltZXN0YW1wMRgEFjIwMDkwMTE2MTYwOTUxLjMxNjM3MVowIAo BADAbBA1tb2RpZmllcnNOYW1lMQoECGNuPWFkbWluMDAKAQAwKwQPbW9kaWZ5VGltZXN0YW1wMRg EFjIwMDkwMTE2MTYwOTUxLjMxNjM3MVo= objectclass: newPilotPerson objectclass: person objectclass: top cn: entry1 sn: entry1sn ibm-entryuuid: 4D3BE000-B14F-1970-817D-402084027431
- The
o=ldbm, cn=replfilter,o=ldbm
andou=rochester,o=ldbm
entries are not unloaded because they do not have an objectclass attribute value of person. - The
cn=entry1,ou=rochester,o=ibm
entry is allowed to be unloaded because it has an objectclass attribute value of person. However, the userpassword and description attribute values are filtered out because they are not specified in the replication filter. - The objectclass and ibm-entryuuid attribute values are always unloaded by the ds2ldif utility although they are not specified in the replication filter.
- The
Using the -t (tagging) option:
- If the value is hashed using crypt, MD5, SHA, SHA224, SHA256, SHA384, or SHA512 one-way hashing
algorithms, then the tag is visible and the hashed userPassword or ibm-slapdAdminPw
value is base64 encoded in the unloaded value. The format of the unloaded value is:
where, attrtype isattrtype: {tag}base64encoded_and_hashedvalue
userpassword
oribm-slapdadminpw
. tag iscrypt, MD5, SHA, SHA224, SHA256, SHA384
, orSHA512
. For example:userpassword: {crypt}0fCik9fUqZnixuKkYQ== userpassword: {MD5}34d121/hie8s userpassword: {SHA}24309gf[jgt userpassword: {SHA224}lcf7ypKsUIOv2mKlZKPQFPw7cskUDjy5nqa/Eg== userpassword: {SHA256}K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols= userpassword: {SHA384}WKd1ukESvjAFrkQHznV9iP2nHUBJe7gCbsrFTU4//HIyzo3jq1rLMK4 5dg/ufFPt userpassword: {SHA512}vSsar3708Jvp9Szi2NWZZ02Bqp1qRCFpbcTZPdBhnWgs5WtNZKnvCXd hztmeD2cmW192CF5bDufKRpayrW/isg==
- If the value is hashed using SSHA (Salted SHA), SSHA224, SSHA256, SSHA384, or SSHA512 hashing
algorithms, then the tag is visible and the hashed userPassword or ibm-slapdAdminPw
value and salt values are base64 encoded in the unloaded value. The format of the unloaded value
is:
where, attrtype isattrtype: {tag}base64encoded_hashed_and_salt_values
userpassword
oribm-slapdadminpw
. tag isSSHA, SSHA224, SSHA256, SSHA384
, orSHA512
. For example:userpassword: {SSHA}yEmjV/P1OsnkDbFMpXARCpUzA0evrN4xquMjGW5bMKlhaAkb5Zt6VQ== userpassword: {SSHA224}sEHZjTzABWiPMDSFmnuYDUUMzGF1C+XOcryro0otC3X3smmwNlAbs+ 222PJRElE7GJUZ4adtbpo= userpassword: {SSHA256} qFzEm0vg2BtJL0cK6baEv6VrRJ4MI+wqQtvoknWjEA5lAL3ePW2u0l Ur6q+Ye/UYJG+eOyaAuHEehFN3OkGJwA== userpassword: {SSHA384}mbP0pQkuXYlDswEDq6JYWp2Y95jgysAX0wohTmbKP74tQvnkRl9G5e u46qth1jOKfvm7HItIuCzcdSRMTe80vynEsv+l0eSfge6Ou3yrXs0cNeN/yw5yMp+FUX0HIg4f userpassword: {SSHA512}rR/ls84oX0qz/GuxGsdtKaRwhdBXDVEP3Uj/WIRB+KB7zON8DX48gA L1k1QCRnrLv0jvyBEB45Dmyj71Awt3M2T5PeagtoTIxbDs1XgVH7zDqAHosWJEI0ZnOviQFP3Cx6 lR3OMOtd5XEAJKC3RBTnhYkOXmdqqwe6KkorUdaMQ=
- If the value is encrypted using a two-way encryption algorithm (DES or AES) or is not encrypted,
then the unencrypted value is base64 encoded in the unloaded value and there is no tag. The format
of the unloaded value
is:
where, attrtype isattrtype:: base64encoded_and_unencryptedvalue
userpassword
oribm-slapdadminpw
. For example:userpassword:: kfa6903axs
This is also the format used when unloading secretKey, replicaCredentials, ibm-replicaKeyPwd, and ibm-slapdMasterPw attribute values because these values can only be encrypted using two-way encryption algorithms.
- The LDAP server loads and uses tagged userPassword or ibm-slapdAdmimPw values that are hashed in crypt, SHA, SSHA (Salted SHA), or MD5 and were unloaded using the ds2ldif utility with the -t option. Also, these tagged values might be acceptable for other LDAP providers to load into their directory. If it is not directly loadable, this format is easily modifiable for loading by another provider into its LDAP directory.
- The values returned by the crypt algorithm are portable only to other X/Open-conformant systems when the pwCryptCompat configuration option is set to off. When the pwCryptCompat configuration option is set to off, the crypt() algorithm uses ASCII, which is a subset of UTF-8, when generating the hashed userPassword or ibm-slapdAdminPw attribute values. Therefore, you might want to set the pwCryptCompat configuration option to off when it is necessary to share userPassword or ibm-slapdAdminPw attribute values hashed in crypt() between the z/OS LDAP server and other ASCII-based LDAP servers.
- If the value is hashed using crypt, SHA, or MD5 one-way hashing algorithms, then the tag and the
hashed userPassword or ibm-slapdAdminPw values are base64 encoded in the unloaded
value. The format of the unloaded value is:
where, attrtype isattrtype:: base64encodedValue
userpassword
oribm-slapdadminpw
. base64encodedValue is a base64 encoding of {tag}hashedvalue
.where, tag iscrypt
,MD5
, orSHA
. For example:userpassword:: e2NyeXB0fdHwopPX1KmZ4sbipGE=
- If the value is hashed using SHA224, SHA256, SHA384, or SHA512 one-way hashing algorithms, then
the tag is visible and the hashed userPassword or ibm-slapdAdminPw value is base64
encoded in the unloaded value. The format of the unloaded value is:
where, attrtype isattrtype: {tag}base64encoded_and_hashedvalue
userpassword
oribm-slapdadminpw
. tag isSHA224
,SSHA256
,SSHA384
, orSHA512
. For example:userpassword: {SSHA224}sEHZjTzABWiPMDSFmnuYDUUMzGF1C+XOcryro0otC3X3smmwNlAbs+ 222PJRElE7GJUZ4adtbpo= userpassword: {SSHA256}qFzEm0vg2BtJL0cK6baEv6VrRJ4MI+wqQtvoknWjEA5lAL3ePW2u0l Ur6q+Ye/UYJG+eOyaAuHEehFN3OkGJwA== userpassword: {SSHA384}mbP0pQkuXYlDswEDq6JYWp2Y95jgysAX0wohTmbKP74tQvnkRl9G5e u46qth1jOKfvm7HItIuCzcdSRMTe80vynEsv+l0eSfge6Ou3yrXs0cNeN/yw5yMp+FUX0HIg4f userpassword: {SSHA512}rR/ls84oX0qz/GuxGsdtKaRwhdBXDVEP3Uj/WIRB+KB7zON8DX48gA L1k1QCRnrLv0jvyBEB45Dmyj71Awt3M2T5PeagtoTIxbDs1XgVH7zDqAHosWJEI0ZnOviQFP3Cx6 lR3OMOtd5XEAJKC3RBTnhYkOXmdqqwe6KkorUdaMQ=
- If the value is hashed using SSHA (Salted SHA), SSHA224, SSHA256,
SSHA384, or SSHA512 one-way hashing algorithms, then the tag is visible
and the hashed userPassword or ibm-slapdAdminPw value
and salt values are base64 encoded in the unloaded value. The format
of the unloaded value is:
where, attrtype isattrtype: {tag}base64encoded_hashed_and_salt_values
userpassword
oribm-slapdadminpw
. tag isSSHA, SSHA224, SSHA256, SSHA384
, orSSHA512
. For example:userpassword: {SSHA}yEmjV/P1OsnkDbFMpXARCpUzA0evrN4xquMjGW5bMKlhaAkb5Zt6VQ== userpassword: {SSHA224}sEHZjTzABWiPMDSFmnuYDUUMzGF1C+XOcryro0otC3X3smmwNlAbs+ 222PJRElE7GJUZ4adtbpo= userpassword: {SSHA256}qFzEm0vg2BtJL0cK6baEv6VrRJ4MI+wqQtvoknWjEA5lAL3ePW2u0l Ur6q+Ye/UYJG+eOyaAuHEehFN3OkGJwA== userpassword: {SSHA384}mbP0pQkuXYlDswEDq6JYWp2Y95jgysAX0wohTmbKP74tQvnkRl9G5e u46qth1jOKfvm7HItIuCzcdSRMTe80vynEsv+l0eSfge6Ou3yrXs0cNeN/yw5yMp+FUX0HIg4f userpassword: {SSHA512}rR/ls84oX0qz/GuxGsdtKaRwhdBXDVEP3Uj/WIRB+KB7zON8DX48gA L1k1QCRnrLv0jvyBEB45Dmyj71Awt3M2T5PeagtoTIxbDs1XgVH7zDqAHosWJEI0ZnOviQFP3Cx6 lR3OMOtd5XEAJKC3RBTnhYkOXmdqqwe6KkorUdaMQ=
- If the value is encrypted using a two-way encryption algorithm (DES or AES) or is not encrypted,
then the unencrypted value is base64 encoded in the unloaded value and there is no tag present. The
format of the unloaded value
is:
where, attrtype isattrtype:: base64encoded_and_unencryptedvalue
userpassword
oribm-slapdadminpw
. For example:userpassword:: e01ENXkfa6903axs
This is also the format used when unloading secretKey, replicaCredentials, ibm-replicaKeyPwd, and ibm-slapdMasterPw attribute values, because these values can only be encrypted using two-way encryption algorithms.
Using the unloadRequest extended operation
The unloadRequest extended operation is used to remotely unload directory data from a currently running z/OS LDAP server. The unloadRequest extended operation is required when attempting to unload data from an LDBM or CDBM backend that is already running with an active z/OS LDAP server. The unloadRequest extended operation is also required when using the -q filterDN option to filter entries as they are being unloaded from an LDBM, TDBM, or CDBM backend. The -r option can be used to force the unloadRequest extended operation to be sent to the z/OS LDAP server for any unload operation. If running ds2ldif from JCL, a DD card is not allowed to be specified on the -o option when using the unloadRequest extended operation.
- An LDAP root administrator simple bind is attempted using each secure listen
option in the LDAP server configuration file until a successful secure connection is established
with the LDAP server. The sslKeyRingFile option in the LDAP server configuration file
indicates the key database file, RACF key ring, or PKCS #11
token that ds2ldif uses to communicate securely with the LDAP server. If the
sslKeyRingFile option is a key database file, the sslKeyRingFilePW or
sslKeyRingPWStashFile options in the LDAP server configuration file are used by
ds2ldif to gain access to the key database file. The sslCertificate option
in the LDAP server configuration file is used as the SSL certificate when ds2ldif
establishes the secure connection with the LDAP server. The adminDN that is specified in the
LDAP server configuration file is used as the bind DN. If there is an adminPW configuration
option present, it is used as the password. If there is no adminPW configuration option,
ds2ldif uses the value of the ds2ldif
-w option or issues a prompt for the password if the -w option is
not specified. Note:
- The ds2ldif utility sends the PasswordPolicy control as a non-critical control when the LDAP root administrator in the configuration file (adminDN configuration option) attempts to authenticate to the LDAP server. If the LDAP root administrator's entry is subject to password policy on the targeted LDAP server, the ds2ldif utility parses and displays the warning and error messages from the PasswordPolicy control response.
- If you are running ds2ldif from TSO or batch, the password prompt does not execute. In these environments, you must either have an adminPW configuration option or specify the -w option.
- The getpass() routine used to prompt for the password returns at most PASS_MAX number of characters, truncating any additional characters. For more information about the getpass() function, see getpass() — Read a string of characters without echo in z/OS XL C/C++ Runtime Library Reference. If the length of the root administrator (adminDN) password is greater than PASS_MAX, you must either have an adminPW configuration option or specify the -w option.
- Ensure that the user ID running the ds2ldif utility has access to the key database file, RACF key ring, or PKCS #11 token that is specified on the sslKeyRingFile option.
- If a secure connection is not established with the LDAP server or there are no secure
listen options in the LDAP server configuration file, an LDAP root administrator
simple bind is attempted using each nonsecure listen option until a successful
nonsecure connection is established. If a connection is not established with the LDAP server,
ds2ldif ends.
- To perform the unloadRequest extended operation with the ds2ldif utility, the bound user is the LDAP root administrator (adminDN).
- If the -Z option is specified, the ds2ldif utility communicates over a secure port if a connection is established. If a secure connection is not established, the ds2ldif utility fails.
- Entries are unloaded into an output file on the LDAP servers system. The name of the file is
specified in the ds2ldif -o option.
If the ds2ldif utility unloads entries when using the unloadRequest extended operation, the output file is produced in the code page that is specified in the LANG environment variable of the LDAP server. Otherwise, the output file is produced in the code page that is specified in the LANG environment variable of the ds2ldif utility.
- An unloadResponse extended operation is sent back to the ds2ldif utility indicating how many entries are unloaded and whether the extended operation is successful.
Additional set up when unloading LDBM or CDBM directory data
If the ds2ldif utility is being used to unload LDBM or CDBM directory data and an unloadRequest extended operation is not being performed (the LDAP server is not running), the user ID that is running the ds2ldif utility must have read and execute access to the directory that is specified on the databaseDirectory configuration option of the LDBM or CDBM backend that is being unloaded and must also have read access to the LDBM or CDBM database and checkpoint files in that directory to successfully perform an unload. Also, the user ID must be in the owning GID group or be the owning UID for the directory and files in that directory to successfully perform an unload.
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.If the ds2ldif utility is being used to unload directory data and an unloadRequest extended operation is not being performed (the LDAP server is not running), the user ID that is running the ds2ldif utility must have read and execute access to the directory specified by the schemaPath configuration option or its default value and it must also have read access to the schema.db file in the directory. Also, the user ID must be in the owning GID group or be the owning UID for the directory and schema.db file in that directory to successfully perform an unload.
Usage notes for the ds2ldif utility
- 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 preallocated 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.
- 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. - 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.
- 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.
- 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.
- 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.
- 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.
- 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 thecn=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. - 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:
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 that contain nonportable characters (for example, textual values containing multi-byte UTF-8 characters) are base64-encoded.version: 1
- To unload the LDAP server schema entry, specify:
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.-s cn=schema
- 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:
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.-s cn=schema,suffixDN
- 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.
- 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.
- 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.
- 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 under the root is traversed. This order results in improved ldif2ds load capacity, at the cost of some effect 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.
ldif2ds utility
The ldif2ds utility is used to load entries that are specified in LDAP Data Interchange Format (LDIF) into a TDBM directory that is stored in a relational database. It cannot be used to load entries into a GDBM, LDBM, CDBM, or SDBM directory. The TDBM directory must exist. The ldif2ds utility is intended for loading many entries. The utility creates load records from the entries in the LDIF input files, then runs the Db2 Load Utility to load the records into the TDBM directory.
The ldapadd utility can also be used to add entries to a TDBM directory. See When to use ldif2ds for more information about when to use ldif2ds or ldapadd. For more information about ldapadd, see ldapmodify and ldapadd utilities in z/OS IBM Tivoli Directory Server Client Programming for z/OS.
The ldif2ds utility might be used to add entries to an empty directory or to a directory that already contains entries. The utility cannot be used to modify the LDAP server schema. The schema must already be appropriate for the entries being added.
- ldif2ds31 (runs in a 31-bit environment)
- ldif2ds64 (runs in a 64-bit environment)
See Preparing to run ldif2ds before using ldif2ds.
Format
ldif2ds | ldif2ds31 | ldif2ds64 { [ { [-c] [-g]
[-p [-o outHlq] [-j] [-b creator] [-k keyFile]] }
{ [-i ldifFile[,ldifFile]...] [-e ldifListFile] }
[-f confFile] [-q summaryFrequency] [-C maxCheckErrs] ]
[ -l [-o outHlq] ] }
[-d debugLevel] [-?]
Parameters
The following table shows the options that you can use for the ldif2ds utility:
Option | Description |
---|---|
-? | Display the usage. |
-b creatorDN | The DN to be associated as creator with each loaded entry that does not already include a creatorsname attribute. If -b is not specified, the value of the adminDN option in the LDAP server configuration file is used. If neither option is specified, ldif2ds fails. The same processing is also applied for the modifier for each loaded entry that does not already include a modifiersname attribute. This option is ignored if ldif2ds is not invoked for the prepare step. |
-c | Check that the entries in the LDIF input file or files are complete and acceptable according to the LDAP server schema. The Db2 database is not modified during the check phase. |
-C maxCheckErrs | Specify the maximum number of errors that are allowed in the check processing phase, such as syntax or schema errors. When this limit is reached, the utility terminates. The default value is 100 errors. Specify a value of 0 to indicate no limit. |
-d debugLevel | Specify the level of the 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. |
-e ldifListFile | Specify the name of a file which contains a list of LDIF input files to be used as input. This is equivalent to using the -i option to specify a list of LDIF files, but is more convenient for a large list. Each record in the list file must contain the name of one LDIF input file. Blank lines and lines beginning with a # (comment lines) are ignored. See the ldifFile option for more information about using a list of LDIF files. This option is ignored if ldif2ds is not invoked for the check or prepare step. |
-f confFile | Specify the name of the LDAP server configuration file to use. This
configuration file only needs to contain information for the TDBM backend into which the entries are
to be loaded. The configuration data set specified by the CONFIG DD statement is used if the
-f option is not specified. The /etc/ldap/ds.conf
configuration file is used if the -f option is not specified and the CONFIG DD
statement is not defined. This option is ignored if ldif2ds is not invoked for
the check or prepare step. See Specifying a value for filename for information about how to specify the file name. |
-g | Specify that the entries to be loaded are in genealogical order in the input LDIF files. This is the order that results from doing a depth-first traversal of a directory. This order greatly reduces the storage usage of ldif2ds during the check and prepare steps, enabling more entries to be loaded at one time. Do not specify this option if the entries to load are not in genealogical order. This order is produced when entries are unloaded using ldif2ds with the -g option. |
-i ldifFile | Specify the name of an LDIF file to use as input. If a list of file names is
specified, each file in the list is processed in turn. If ldif2ds is invoked
separately to run the check and prepare steps, make sure to specify the same set of LDIF files each
time you run ldif2ds.
See Specifying a value for filename for information about how to specify the file name. For more information about the ldapmodify utility, see ldapmodify and ldapadd utilities in z/OS IBM Tivoli Directory Server Client Programming for z/OS. This option is ignored if ldif2ds is not invoked for the check or prepare step. |
-j | Specify that Db2
logging is used when loading the directory entries. The load operation is faster if Db2 logging is not used but the Db2 database is placed into copy-pending state after
the data has been loaded. You then must run either the Db2 COPY or REORG utility to reset the copy-pending
state. Note: This option can only be specified during the prepare step, when the JCL for the load
jobs is created. It is ignored if ldif2ds is not invoked for the prepare
step.
|
-k keyFile | Specify the name of the file containing the LDAP server encryption keys. If running ldif2ds in batch, the data set specified by the LDAPKEYS DD statement is used if the -k option is not specified. The key file must be specified if any entries loaded have userPassword, secretKey, ibm-replicaKeyPwd, ibm-slapdMasterPw, or replicaCredentials attribute values that are encrypted using the DES or AES algorithm and not using ICSF. These attribute values are encrypted as the entry is prepared for loading into the directory. |
-l | Start the Db2 Load Utility to load the TDBM database. |
-p | Prepare Db2 table load files and JCL from the entries in the LDIF input file or files. The load and JCL files are generated as data sets, whose high-level qualifier is specified with the -o option. The prepare step deletes the existing contents of the data sets before writing new contents to the data sets. The Db2 database is modified during the prepare phase as entry identifiers and attribute identifiers are assigned for the new directory entries. The check phase is always performed when the -p option is specified, even if the -c option is not specified. |
-o outHlq | Specify the high-level qualifier of the data sets that contains the Db2 load and JCL output, the status information, and the system information. These data sets must be allocated before invoking ldif2ds. The value cannot be more than 22 characters long. See Preparing to run ldif2ds for more information. This option is ignored if ldif2ds is not invoked for the prepare or load step. |
-q summaryFrequency | Specify the number of LDIF entries the check or prepare step processes between issuing summary messages. The default value is 1000, resulting in issuing a summary message after every 1000 entries are checked or prepared. If you have many LDIF entries, increase this value to reduce the frequency of summary messages. Specify a value of 0 to suppress issuing any intermediate summary messages. A final summary message is always issued. This option is ignored if ldif2ds is not invoked for the check or prepare step. |
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.
Examples
ldif2ds31 -cpl -i /data2/ldif.data -o admin3.prv -d ERROR
This ldif2ds utility invocation checks, prepares, and loads the LDIF data from
/data2/ldif.data, uses the output data sets
ADMIN3.PRV.BULKLOAD.INPUT.xxx
and ADMIN3.PRV.BULKLOAD.JCL
, and
specifies a debug level of ERROR. By default, the server configuration file that is used is
/etc/ldap/ds.conf. Also, the value of the adminDN option in
the LDAP server configuration file is used as the default creator of each loaded entry, no Db2 logging is done when loading the entries, and a
progress message is issued after every 1000 entries processed during the check and prepare steps.
ldif2ds64 -cpl -i "//'ADMIN3.LDIF.DATA'" -o admin3.prv -d ERROR
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.
- The user ID must have read and execute access to the directory specified by the schemaPath Directory server configuration option or its default value and read access to the schema.db file in that directory.
- The user ID must be in the owning GID group or be the owning UID for the directory and schema.db file in that directory.
- The user ID must have read access to the CDBM backend directory as specified by the databaseDirectory server configuration option or its default value and the files within that directory.
- The user ID must be in the owning GID group or be the owning UID for the CDBM backend directory and files within that directory.
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
- outHlq.
- 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
- outHLQ.BULKLOAD.INPUT.DESC:
- Data set names:
- 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
- outHlq.
- 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
- outHlq.
- Data set format:
- Partitioned (PDS)
- Record format = FB
- Record length = 80
- Data set size:
- 200 K bytes
- Data set name:
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)
- Jobname ends in 1 - JCL for loading DIR_DESC table, in
outHlq.
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.
Considerations | ldif2ds | ldapadd |
---|---|---|
Speed of load | Faster | Slower, especially if the database is already large. |
Operational attributes | Accepts input containing operational attributes such as creatorsname, modifiersname, createtimestamp, modifytimestamp, and ibm-entryuuid. | Input can contain these operational attributes however the -k option (Server Administration server control) must be specified to allow operational attributes to be added. |
Complexity | High, takes time to learn. Typical usage requires multiple invocations, with review of JCL and preparation for recovery before load. | Low. |
Set up | User must allocate data sets and create the SYSTEM information file before running ldif2ds. | No setup. |
LDAP server downtime | LDAP server must be down during load step. Server can be up during check and prepare steps. | Server must be operational during adds. |
Db2 logging | Logging is optional. Additional Db2 work is needed to make database fully usable after the load if logging is not performed. | Requires logging. |
Recovery | Recovery from load failure is complex, involving knowledge of Db2 Utilities. | Simple recovery. |
Invocation | Must be run from z/OS system containing the database, or any image in a Parallel Sysplex® running a Db2 subsystem which is a member of the Db2 data sharing group containing the database, using a user ID with Db2 privileges. | Can be run from any LDAP client with appropriate LDAP access. |
Re-usability | Prepared entries are saved so that they can be re-used to reload this system. | No saved output. |
Replication | New entries are not replicated. | New entries can be replicated. |
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 100 K 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:
- ldif2ds uses much storage when adding many entries. Make sure that you have sufficient memory available.
- 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.
- 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.
- 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.
- 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
- Perform the necessary setup for running ldif2ds, as described in Preparing to run ldif2ds. This consists of:
- allocating data sets required by ldif2ds
- creating the SYSTEM member in the outHLQ.BULKLOAD.JCL data set
Note that the same data sets can be used for loading different entries, but the contents of the data sets are overwritten each time.
- Repeatedly invoke ldif2ds with only the prepare (-p) option until all problems in the LDIF input files have been resolved. The check step and the prepare step are performed. You can use the check option (-c) instead if you only want to check the entries at this time, then later invoke ldif2ds again with the -p option.
- Run ldif2ds with the prepare (-p) option to prepare the load data.
- Bring the LDAP server down.
- Even if loading an empty database, make a full image copy of the table spaces for the DIR_DESC, DIR_ENTRY, DIR_LONGATTR, DIR_LONGENTRY, DIR_REPLICA, and the DIR_SEARCH tables. A full image copy is required to help recover from any potential Db2 Load Utility failures. It is performed after the ldif2ds invocation with the prepare (-p) option specified because the prepare (-p) option might update some database tables. Therefore, these updates must be captured for a successful recovery from a Db2 Load Utility failure. If the prepare (-p) and load (-l) options are specified together, the full image copy is performed before the ldif2ds invocation.
- Review the JCL created by the prepare step in the JCL data set, outHLQ.BULKLOAD.JCL. Ensure that the Db2 Load Utility data sets are large enough and that the Db2 Load Utility options, especially the LOG value, are acceptable. See note 5 in the ldif2ds performance considerations section for more information about the LOG value.
- Run ldif2ds once more, with the load (-l) option to load the data into the database, and six batch jobs are submitted to load the database.
- Review the output from the load jobs when they end. If the loaded table spaces are in the copy pending state, see Db2 Utility Guide and Reference in Db2 for z/OS in IBM Knowledge Center for instructions on removing that restriction on table spaces. This typically involves running a Db2 utility to create an image copy of the database or reorganize the database (or both).
- Run the Db2 RUNSTATS utility to reset the statistics used by Db2 to access the database. See Performance tuning for detailed information about running the Db2 RUNSTATS utility.
- Run the Db2 COPY utility to make a backup image copy of the database.
- If running the ldif2ds utility in 64-bit mode, ensure that the user ID running the ldif2ds utility has a sufficient value specified for the MEMLIMIT and ASSIZEMAX values in the OMVS segment so that storage greater than 2 gigabytes can be used. This enables the ldif2ds utility to work properly in 64-bit mode.
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:
- 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.
- See Db2 Utility Guide and Reference in Db2 for z/OS in IBM Knowledge Center for information about correcting the problems that were logged in the failing jobs.
- 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:
- 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.
- For information about correcting problems that were logged in the failing jobs, see in Db2 for z/OS in IBM Knowledge Center.
- 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:
- 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.
- For information about correcting problems logged in the failing jobs, see Db2 for z/OS in IBM Knowledge Center.
- Manually resubmit the Db2 Load Utility jobs for all the affected tables.
Usage of the ldif2ds utility
- 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.
- 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.
- 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.
- 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.
- 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.
- Referral entries can be added by ldif2ds.
- 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.
- 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.
- Do not specify the aclSource and ownerSource attributes in an LDIF entry because they are ignored. These attributes are set only by the system.
- 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.
- 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 notP
. When the load step is successful, the status is changed toSTATUS L
and the TIME record is reset to the current time. - 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
ldapdiff utility
The ldapdiff utility compares two directory subtrees or two schemas on two different directory servers to determine if their contents match. The utility runs as a client operation when both servers are active and determines the differences between the servers. The utility can optionally attempt to synchronize one directory subtree to match the contents of the other.
Format of the ldapdiff utility
ldapdiff { [-S] [-b baseDn] } [-a] [-C countNumber] [-d debugLevel] [-F] [-j] [-L fileName]
[-n] [-O] [-v] [-x]
-sh host [-sp port] [-sD bindDn -sw bindPwd]
[-sT truststore -st truststoreType [-sY truststorePwd]
[-sZ] [-sK keystore -sN keystoreType [-sP keystorePwd]]]
-ch host [-cp port] [-cD bindDn -cw bindPwd]
[-cT truststore -ct truststoreType [-cY truststorePwd]
[-cZ] [-cK keystore -cN keystoreType [-cP keystorePwd]]]
Parameters for the ldapdiff utility
The following table shows the general options that you can use for the ldapdiff utility.
Option | Description |
---|---|
-? | Display the usage. |
-a | Specify that the Server Administration
control is to be sent to the consumer server or written to the output
LDIF file. This control enables a server that normally refuses updates,
such as a quiesced or replica server, to allow updates. If the -F option is specified, the control is sent to the consumer server. If the -L option is specified, the control is written to the output LDIF file. |
-b baseDn | Indicate the starting point for the subtree comparison. The ldapdiff utility requires either the -b or -S option, or both. |
-C countNumber | Specify the maximum number of non-matching subtree entries that can be found between the two LDAP servers. If the number of non-matching subtree entries exceeds the specified number, the ldapdiff utility exits. |
-d debugLevel | Specify the level of debug messages to be created. The default is no debug messages. Currently, only the ALL level is supported by the ldapdiff utility. This results in a large amount of debug output being created. |
-F | Specify that the content on the consumer replica
server is modified to match the content of the supplier server. The -F option has no effect when doing schema comparisons as requested by the -S option. |
-j | Indicate that the four operational attributes creatorsName, createTimeStamp, modifiersName, and modifyTimeStamp are to be ignored when comparing subtrees. |
-L fileName | Specify the name of the output LDIF file to contain the differences between the supplier and consumer servers. The output LDIF file can be used to update the consumer server to eliminate the differences between the supplier and consumer. The name cannot be a data set. |
-n | Specify that the Do Not Replicate control
is to be sent to the consumer server or written to the output LDIF
file. This control prevents the consumer server from sending replicated
entries to the next tier of advanced replication servers. If the -F option is specified, the control is sent to the consumer server. If the -L option is specified, the control is written to the output LDIF file. |
-O | Indicate that directory subtrees are compared using
checksum only. This option can be used to quickly detect differences
between servers without the need to retrieve all attribute types and
values. DNs for non-matching entries between the supplier and consumer
servers are displayed, but not the non-matching attributes. Both servers
must support entry checksum. Otherwise, the ldapdiff utility
does not start. The -O option overrides the -F, -j, and -L options. |
-S | Specify that the schema is to be compared between
the supplier and consumer servers. The ldapdiff utility requires either the -b or -S option, or both. |
-v | Use verbose mode, with many diagnostics written to standard output. |
-x | Specify that extra entries on the consumer server are to be ignored. |
The following options apply to the supplier server and are denoted by an initial ’s’ in the option name:
Option | Description |
---|---|
-sD bindDn | Specify the DN to use to bind to the supplier server. This option should be a string-represented DN. The default is an empty string. |
-sh host | Specify the host name or IP address on which the supplier server is running. There is no default host, therefore, this option is required. |
-sK keystore | Specify the file name of the Java™ keystore
or RACF key ring that contains the client certificate. If the
supplier server is configured to perform server authentication only, a client certificate is not
required. If the supplier server is configured to perform client and server authentication, a client
certificate might be required. The file name cannot be a data set. If specifying a RACF key ring, use the following
format:
where,
userid is the RACF user ID that owns
the RACF key ring and keyFile is the
name of the RACF key ring.If the user ID running
ldapdiff is the owner of the RACF key
ring, then a simplified format might be used:
where, keyFile is the
name of the RACF key ring. |
-sN keystoreType | Specify the type of the keystore being used by
the -sK option. The supported keystore types are:
This is a required option if the -sK option is specified. This option cannot be specified by itself. |
-sp port | Specify the TCP port where the supplier server is listening. The default LDAP non-secure port is 389 and the default LDAP secure port is 636. |
-sP keystorePwd | Specify the keystore password. This password is
required to access the encrypted information in the keystore file,
which might include one or more private keys. If the keystore specified by -sK is a RACF key ring, then this option should not be specified. This option is not allowed if the -sK option is not specified. |
-st truststoreType | Specify the type of the truststore used by the -sT option. The supported truststore types are:
This is a required option if the -sT option is specified. This option cannot be specified by itself. |
-sT truststore | Specify the file name of the Java keystore or RACF keying that contains the CA (certificate authority) certificate
that signed the supplier server's certificate. The file name cannot be a data set. If specifying a RACF key ring, use the following name format:
where, userid is the RACF user ID that
owns the RACF key ring and keyFile is the name of the RACF key ring.If you have ownership of
the RACF key ring, then a simplified
format might be used:
where, keyFile is the name of the RACF key ring.This option is required when using SSL. This option enables a secure connection even if the -sZ option is not specified. |
-sw bindPwd | Specify the bind password for simple authentication. The default is an empty string. |
-sY truststorePwd | Specify the truststore password. This password
is required to access the encrypted information in the truststore
file, which might include one or more private keys. If the truststore
specified by -sT is a RACF key ring, then this option should not be specified. This option is not allowed if the -sT option is not specified. |
-sZ | Use a secure connection to communicate with the supplier server. Secure connections expect the communication to begin with the SSL/TLS handshake. |
The following options apply to the consumer server and are denoted by an initial ’c’ in the option name:
Option | Description |
---|---|
-cD bindDn | Specify the DN to use to bind to the consumer server. This option should be a string-represented DN. The default is an empty string. |
-ch host | Specify the host on which the consumer server is running. There is no default host, therefore, this option is required. |
-cK keystore | Specify the file name of the Java keystore or RACF key ring that contains the client certificate. If the consumer
server is configured to perform server authentication only, a client
certificate is not required. If the consumer server is configured
to perform client and server authentication, a client certificate
might be required. The file name cannot be a data set. If specifying
a RACF key ring, use the following
name format:
where, userid is the RACF user ID that owns the RACF key ring and keyFile is the name of the RACF key ring.If you have ownership of the RACF key ring, then a simplified format might
be used:
where, keyFile is the name of the RACF key ring. |
-cN keystoreType | Specify the type of the keystore being used by
the -cK option. The supported keystore types are:
This is a required option if the -cK option is specified. This option cannot be specified by itself. |
-cp port | Specify the TCP port where the consumer server is listening. The default LDAP non-secure port is 389 and the default LDAP secure port is 636. |
-cP keystorePwd | Specify the keystore password. This password is
required to access the encrypted information in the keystore file,
which might include one or more private keys. If the keystore specified by -cK is a RACF key ring, then this option should not be specified. This option is not allowed if the -cK option is not specified. |
-ct truststoreType | Specify the type of the truststore used by the -cT option. The supported truststore types are:
This is a required option if the -cT option is specified. This option cannot be specified by itself. |
-cT truststore | Specify the file name of the Java keystore or RACF keying that contains the CA (certificate authority) certificate
that signed the consumer server's certificate. The file name cannot be a data set. If specifying a RACF key ring, use the following name format:
where, userid is the RACF user ID that
owns the RACF key ring and keyFile is the name of the RACF key ring.If you have ownership of
the RACF key ring, then a simplified
format might be used:
where, keyFile is the name of the RACF key ring.This option is required when using SSL. This option enables the -cZ option. |
-cw bindPwd | Specify the bind password for simple authentication. The default is an empty string. |
-cY truststorePwd | Specify the truststore password. This password
is required to access the encrypted information in the truststore
file, which might include one or more private keys. If the truststore
specified by -cT is a RACF key ring, then this option should not be specified. This option is not allowed if the -cT option is not specified. |
-cZ | Use a secure connection to communicate with the consumer server. Secure connections expect the communication to begin with the SSL/TLS handshake. |
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.
Examples of the ldapdiff utility
1.2.3.4
and other as a consumer server on IP address 1.2.3.5
, and
that the suffix o=sample
is present on both servers. Assume the entries in the
supplier.ldif file are in the supplier server and the entries in the
consumer.ldif file are in the consumer server.- Contents of the supplier.ldif
file:
dn: cn=Entry1,o=sample objectclass: inetOrgPerson objectclass: organizationalPerson objectclass: person objectclass: top objectclass: ePerson sn: entry1 cn: Entry1 dn: cn=Entry2,o=sample objectclass: inetOrgPerson objectclass: organizationalPerson objectclass: person objectclass: top objectclass: ePerson sn: entry2 cn: Entry2
- Contents of the consumer.ldif
file:
dn: cn=Entry2,o=sample objectclass: inetOrgPerson objectclass: organizationalPerson objectclass: person objectclass: top objectclass: ePerson sn: abcd cn: Entry2 dn: cn=Entry3,o=sample objectclass: inetOrgPerson objectclass: organizationalPerson objectclass: person objectclass: top objectclass: ePerson sn: entry3 cn: Entry3
o=sample
subtree on the consumer server (even if it is quiesced) to match the
supplier server, binding to the supplier server on IP address 1.2.3.4
with a bind
DN of cn=admin
and a password of supplier
and binding to the
consumer server on IP address 1.2.3.5
with a bind DN of cn=admin
and a password of
consumer
:ldapdiff -b o=sample -sh 1.2.3.4 -sD cn=admin -sw supplier -ch 1.2.3.5 -cD cn=admin
-cw consumer -F -a
- The
cn=Entry1,o=sample
is added to the consumer server. This entry is already present on the supplier server but was not on the consumer server. - The
cn=Entry2,o=sample
is modified on the consumer server. The sn attribute value on thecn=Entry2,o=sample
entry on the consumer server gets modified to match the value on the supplier server. - The
cn=Entry3,o=sample
is deleted from the consumer server. This entry does not exist on the supplier server, and is deleted from the consumer server so that the same set of entries are present on both the supplier and consumer servers.
Usage notes for the ldapdiff utility
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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
- ibm-pwdIndividualPolicyDn
- ibm-pwdGroupPolicyDn
- 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.
- 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.
ldapexop utility
- acctstatus - Account status extended operation
- cascrepl - Cascading control replication extended operation
- controlqueue - Control replication queue extended operation
- controlrepl - Control replication extended operation
- controlreplerr - Control replication error log extended operation
- effectpwdpolicy - Effective password policy extended operation
- geteffectiveacl - GetEffectiveACL extended operation
- getusertype - User type extended operation.
- quiesce - Quiesce or unquiesce context extended operation
- repltopology - Replication topology extended operation
Format of the ldapexop utility
ldapexop [-d debugLevel] [-h host] [-p port] [-?] [-help] [-v]
{ [-m EXTERNAL -Z [-x sslFipsMode] [-K keyFile] [-P keyFilePwd]
[-N certificateLabel]]
[ [ { [-D dn -w password] |
[-m CRAM-MD5 -w password { [-D dn] | [-U userName [-D dn]] }] |
[-m DIGEST-MD5 -U userName -w password [-D dn] [-G realmName]] |
[-m GSSAPI]
}
]
[-Z [-x sslFipsMode] [-K keyFile] [-P keyFilePwd] [-N certificateLabel]]
]
} -op extendedOperation extOptions
Parameters for the ldapexop utility
- There are general options that specify how to connect to the LDAP server. These options must be specified before the -op option. See Table 6 for an explanation about the general options.
- There are extended operation options that identify the extended operation to be performed. These options are specified after the general options and must begin with the -op option. See Extended operations options for an explanation about these options.
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.
Option | Description |
---|---|
-? | Display the usage. |
-d debugLevel | Specify the level of the 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 dn | Specify the DN to use to bind to the LDAP directory. This option is a
string-represented DN. The default is a NULL string. If the -m option is equal to
|
-G realmName
|
Specify the realm name 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 host | Specify the host name or IP address on which the LDAP server is running. The default is the local host. |
-help | Display the usage. |
-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_KEYRING environment variable with an
associated name.If keyFile is specified as
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
|
Specify the bind method to use. Specify The The The The If -m is not specified, a simple bind is performed. |
-N certificateLabel | 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 port | 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 keyFilePwd | 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 user name 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 -m option is
set to |
-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. |
-w password | Specify the bind password for simple, CRAM-MD5 ,
and DIGEST-MD5 authentication. The default is a NULL
string.Specify |
-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 keyFilePwd 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. |
- acctstatus -d userDn
- Perform the Account status extended operation. This extended operation returns the status
of a user entry with a userPassword attribute value. The status returned is either opened,
locked, or expired. See Account status extended operation example for more information about the Account
status extended operation.
- -d userDn
- Specifies the DN of the entry to be queried.This example performs the Account status extended operation to query the status of the
cn=jon,o=acme,c=us
entry.ldapexop -D adminDn -w adminPw -op acctstatus -d cn=jon,o=acme,c=us
- cascrepl -action { quiesce | unquiesce | replnow | wait } -rc contextDn [-timeout secs]
- Perform the Cascading control replication extended operation. The requested action is
applied to the specified server and also passed along to all replicas of the given context
(subtree). If any of these are forwarding replicas or gateway servers, they pass the extended
operation along to their replicas. The operation cascades over the entire advanced replication
topology. See Cascading control replication for more information about the Cascading control
replication extended operation.
- -action { quiesce | unquiesce | replnow | wait }
- Specifies the Cascading control replication extended operation action to be performed.
- quiesce
- Halts further updates, except by replication. Client updates under the specified context are restricted to LDAP administrators, if using the Server Administration control (OID 1.3.18.0.2.10.15), and any replication master DNs with authority under this context.
- unquiesce
- Resumes normal operation, client updates are accepted.
- replnow
- Replicates all queued changes to all replica servers as soon as possible, regardless of schedule. This operation is propagated to the consumer server of each replication agreement without waiting for all queued updates to be applied.
- wait
- Replicates all queued changes to all replica servers as soon as possible, regardless of schedule. This operation is propagated to the consumer server of each replication agreement after all queued updates for that agreement are applied.
- -rc contextDn
- Specifies the DN of the advanced replication context (subtree).
- -timeout secs
- Specifies the number of seconds that the extended operation must successfully complete. If not present, or 0, the operation has an indefinite amount of time to complete.
This example performs the Cascading control replication extended operation to wait for all updates to be replicated to each consumer server in theo=acme,c=us
replication context. If the extended operation does not successfully complete in 60 seconds, the operation ends with a return code of LDAP_TIMEOUT.ldapexop –D adminDn –w adminPw -op cascrepl -action wait -rc "o=acme,c=us" -timeout 60
- controlqueue -skip { all | changeId } -ra agreementDn
- Perform the Control replication queue extended operation. This extended operation
indicates which pending changes in the advanced replication queue are skipped and not replicated to
the consumer server. See Control replication queue for more information about the Control
replication queue extended operation.
- -skip {all | changeId}
-
- all
- Deletes (skips) all changes currently queued for replication for the specified replication agreement DN.
- changeId
- Deletes (skips) the change queued for replication with the change ID matching the specified number. The number must be in the range 1 - 4294967295. Change IDs can be determined by searching the agreementDn entry for the ibm-replicationPendingChanges operational attribute. Only the next change to be replicated can be skipped in this manner.
- -ra agreementDn
- Specifies the DN of the advanced replication agreement.
This example performs the Control replication queue extended operation to delete (skip) all pending updates in the advanced replication queue for the replication agreement,cn=server3,ibm-replicaSubentry=master1-id,ibm-replicaGroup=default,o=acme,c=us
. This extended operation prevents all changes in the replication queue from being replicated to all consumer servers.ldapexop –D adminDn –w adminPw -op controlqueue -skip all -ra "cn=server3,ibm-replicaSubentry=master1-id,ibm-replicaGroup=default,o=acme,c=us"
- controlrepl –action { suspend | resume | replnow } { -rc contextDn | -ra agreementDn }
- Perform the Control replication extended operation. This extended operation indicates
whether to suspend, resume, or immediately replicate entries in the advanced replication context
(subtree) or agreement. See Control replication for more information about the Control
replication extended operation.
- -action { suspend | resume | replnow }
- Specifies the Control replication extended operation action to be performed.
- suspend
- Suspends advanced replication for the replication agreement or context (subtree). Any updates under the replication agreement or context are queued until the Control replication extended operation is performed to resume updates to consumer servers.
- resume
- Resumes advanced replication for the replication agreement or context (subtree).
- replnow
- Replicates immediately any outstanding updates for the replication agreement or context (subtree), regardless of schedule. replnow has no effect on a suspended replication agreement or context.
- -rc contextDn | -ra agreementDn
- Specifies the DN of the advanced replication context (subtree) or agreement the action is to be performed against. To perform the action against all agreements under a replication context, use -rc contextDn with the DN of the replication context. Alternatively, to perform this action against a single agreement, use -ra agreementDn with the DN of the replication agreement. A contextDn and an agreementDn cannot both be specified.
This example performs the Control replication extended operation to suspend advanced replication on the replication agreement,cn=server3,ibm-replicaSubentry=master1-id,ibm-replicaGroup=default,o=acme,c=us
.ldapexop –D adminDn –w adminPw -op controlrepl -action suspend -ra "cn=server3,ibm-replicaSubentry=master1-id,ibm-replicaGroup=default,o=acme,c=us"
- controlreplerr -ra agreementDn { [ -delete { failureId | all } ] | [ -retry { failureId | all } ] | [ -show failureId ] }
- Perform the Control replication error log extended operation. This extended operation
indicates whether to delete, retry, or show a failed advanced replication update. Failing operations
can be determined by searching the agreementDn entry for the
ibm-replicationFailedChanges operational attribute which contains the failing change ID. See
Control replication error log for more information about the Control replication error log
extended operation.
- -ra agreementDn
- Specifies the DN of the advanced replication agreement.
- -delete { failureId | all }
- Removes one or all failed replication updates.
- failureId
- Deletes only the failed update specified by the failureId for this agreement. The failureId must be in the range 1 - 4294967295.
- all
- Deletes all the failed updates for this agreement.
- -retry { failureId | all }
- Reprocesses one or all failed replication updates.
- failureId
- Tries again only the failed update specified by the failureId for this agreement. The failureId must be in the range 1 - 4294967295.
- all
- Tries again all the failed updates for this agreement.
- -show failureId
- Shows the failed update specified by the failureId for this agreement. The failureId must be in the range 1 - 4294967295.
This example performs the Control replication error log extended operation to remove all failures from the replication error log for the replication agreement,cn=server3,ibm-replicaSubentry=master1-id,ibm-replicaGroup=default,o=acme,c=us
.ldapexop –D adminDn –w adminPw -op controlreplerr -delete all -ra "cn=server3,ibm-replicaSubentry=master1-id,ibm-replicaGroup=default,o=acme,c=us"
- effectpwdpolicy -d entryDn
- Perform the Effective password policy extended operation. This extended operation returns
the effective password policy entries and the attribute values of the effective password policy that
the specified entry is subject to. See Effective password policy for more information about the
Effective password policy extended operation.
- -d entryDn
- Specifies the DN of the entry to be queried to obtain its effective password policy.This example performs the Effective password policy extended operation to query the effective password policy of the
cn=jon,o=acme,c=us
entry.ldapexop -D adminDn -w adminPw -op effectpwdpolicy -d cn=jon,o=acme,c=us
- geteffectiveacl
- getusertype
- Perform the User type extended operation. This extended operation provides the
authenticated user with their user type and administrative roles. See User type for
more information about the User Type extended operation.This example performs the User type extended operation to determine the user type and roles for user
cn=jon,o=ibm,c=us
:ldapexop -D cn=jon,o=ibm,c=us -w secret -op getusertype
- quiesce -rc contextDn [-end]
- Perform the Quiesce or unquiesce context extended operation. When an advanced replication
context is quiesced, update operations are only accepted from certain users. See Quiesce or unquiesce context for more information about the Quiesce or unquiesce context extended
operation.
- -rc contextDN
- Specifies the DN of the advanced replication context (subtree) to be quiesced or unquiesced.
- -end
- Unquiesces the advanced replication context (subtree). If not specified, the default is to quiesce the replication context.
This example performs the Quiesce or unquiesce context extended operation to quiesce the replication contexto=acme,c=us
. After this extended operation is performed, updates to entries within the replication context are only allowed from certain users.ldapexop –D adminDn –w adminPw -op quiesce -rc "o=acme,c=us"
- repltopology -rc contextDn [-timeout secs] [-ra agreementDn]
- Perform the Replication topology extended operation. This extended operation synchronizes
all replication topology related entries under the specified context DN. See Replication topology for more information about the Replication topology extended operation.
- -rc contextDN
- Specifies the DN of the advanced replication context (subtree) on the supplier server for which advanced replication topology related entries are synchronized. The extended operation is cascaded through all forwarding and gateway servers.
- -timeout secs
- Specifies the number of seconds that the extended operation must successfully complete. If not present, or 0, the operation has an indefinite amount of time to complete.
- -ra agreementDn
- Specifies the DN of the advanced replication agreement and allows the operation to be restricted to only one server and its consumer.
This example performs the Replication topology extended operation to synchronize replication topology entries within theo=acme,c=us
replication context with the consumer defined in the replication agreementcn=server3,ibm-replicaSubentry=master1-id,ibm-replicaGroup=default,o=acme,c=us
. This extended operation does not cascade, it only modifies the consumer defined in the replication agreement before returning.ldapexop –D adminDn –w adminPw -op repltopology -rc "o=acme,c=us" -ra "cn=server3,ibm-replicaSubentry=master1-id,ibm-replicaGroup=default,o=acme,c=us"
Usage notes for the ldapexop utility
- 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.
- 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.
- 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.
- You can specify an LDAP URL for host on the -h option. For more information, see ldap_init() in z/OS IBM Tivoli Directory Server Client Programming for z/OS.
- 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. For more information about getpass(), see getpass() — Read a string of characters without echo in z/OS XL C/C++ Runtime Library Reference. 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.