ldapmodrdn utility

Purpose

The ldapmodrdn utility provides an interface to the ldap_rename() API.

The ldapmodrdn utility opens a connection to an LDAP server, binds, and modifies the DN of entries. The input consists of a distinguished name (DN) and a new relative distinguished name (RDN). The new RDN replaces the existing RDN in the entry that is specified by the DN. If no dn and newRDN arguments are provided, the input is read from standard input or from file if the -f option is used, and two lines are read for each rename. The first line contains the DN and the second line contains the new RDN. One or more blank lines must separate each DN and RDN pair.

The entries being renamed can be either leaf entries or non-leaf entries, and entire subtrees can be relocated in the directory with the -s option.

The ldapmodrdn utility is not supported by z/OS® LDAP support for RACF® access.

Format

ldapmodrdn [options] [dn newRDN]

Parameters

options
Table 1 shows the options you can use for the ldapmodrdn utility:
Table 1. ldapmodrdn options
Option Description
-? Print this text.
-a Sends an IBMModifyDNRealignDNAttributesControl control with the operation request. The control criticality is set to TRUE. There is no control value. See z/OS IBM Tivoli Directory Server Administration and Use for z/OS for a description of this control.
-c Continuous operation mode. Errors are reported, but ldapmodrdn continues with DN modifications. The return code from the utility is determined by the last DN modification. The default is to exit after reporting an error.
-d debugLevel Specify the level of debug messages to be created. The debug level is specified in the same fashion as the debug level for the LDAP server. See Table 1 for the possible values for debugLevel. The default is no debug messages.
-D bindDN Use bindDN to bind to the LDAP directory. This option should be a string-represented DN. The default is a NULL string.

If the -S or -m option is equal to DIGEST-MD5 or CRAM-MD5, this option is the authorization DN that is used for making access checks. This directive is optional when used in this manner.
-f file Read the entry rename information from file instead of from standard input or the command-line (by specifying dn and newRDN). Multiple pairs of dn and newRDN can be specified in the input file or standard input. The pairs must be separated by one or more blank lines. Do not put quotation marks around the dn or newRDN values in the file. The newSup option cannot be included in file; this option is only accepted as a command-line option. If the newSup option (-s) is specified, each entry specified in the file has its RDN updated and be moved under the new superior entry's DN. If the IBMModifyDNRealignDNAttributesControl option (-a) is specified, it is sent on each rename operation that is specified in the file.

You can specify a partitioned or sequential data set for file on the -f option. See Specifying a value for a file name for more information.
-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 ldapHost Specify the host name or IP address on which the LDAP server is running. The default is the local host.
-k Send the Server Administration control with the operation request. The control requires a protocol level of 3 and its criticality is set to TRUE. There is no control value. This control enables a server that would normally refuse updates, such as a quiesced or replica server, to allow updates. See z/OS IBM Tivoli Directory Server Administration and Use for z/OS for additional information about this control.
-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 *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 partitioned or sequential 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 client utilities for information about System SSL key databases, RACF key rings, and PKCS #11 tokens.

This option is ignored if -Z is not specified.
-l timeLimit Send an IBMModifyDNTimelimitControl control with the operation request, substituting timeLimit as the control value. The control criticality is set to TRUE. See z/OS IBM Tivoli Directory Server Administration and Use for z/OS for a description of this control.
-L Send the Do Not Replicate control with the operation request. The control requires a protocol level of 3 and its criticality is set to TRUE. There is no control value. This control prevents the targeted server from sending replicated entries to the next tier of advanced replication servers. See z/OS IBM Tivoli Directory Server Administration and Use for z/OS for additional information about this control.
-m mechanism See the description of the -S option.
-M Manage referral objects as normal entries. This requires a protocol level of 3.
-n Show what would be done, but do not actually change entries. Useful for debugging with -v.
-N keyFileDN Specify the label associated with the certificate in the System SSL key database, RACF key ring, or PKCS #11 token.

This option is ignored if -Z is not specified.

-p ldapPort Specify the TCP port where the LDAP server is listening. The default LDAP non-secure port is 389 and the default LDAP secure port is 636.
-P keyFilePW Specify either the key database file password or the file specification for a System SSL password stash file. When the stash file is used, it must be in the form file:// followed immediately (no blanks) by the file system file specification (for example, file:///etc/ldap/sslstashfile). The stash file must be a z/OS UNIX System Services file and cannot be a partitioned or sequential data set.

This option is ignored if -Z is not specified.
-r Remove old RDN values from the entry. Default is to keep old values.
-R Do not automatically follow referrals.
-s newSup Specify the DN of the new superior entry under which the renamed entry is relocated. The newSup argument can be the zero-length string (-s ""), if the destination server accepts zero-length string newSup arguments on an LDAP Modify DN operation.
-S mechanism
or
-m mechanism

Specify the bind method to use. You can use either -m or -S to indicate the bind method.

Specify GSSAPI to indicate that a Kerberos Version 5 bind is requested, EXTERNAL to indicate that a certificate (SASL external) bind is requested, CRAM-MD5 to indicate that a SASL Challenge Response Authentication Mechanism bind is requested, or DIGEST-MD5 to indicate that a SASL digest hash 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. If there is no default certificate in the key database file, RACF key ring, or PKCS #11 token or a certificate other than the default must be used, use the -N option to specify the label of the certificate.

The CRAM-MD5 method requires a protocol level of 3. The -D or -U option must be specified.

The DIGEST-MD5 method requires a protocol level of 3. The -U option must be specified. Optionally, the -D option can be used to specify the authorization DN.

If -m or -S is not specified, a simple bind is performed.
-U userName Specify the user name for CRAM-MD5 or DIGEST-MD5 binds. The userName is a short name (for example, the uid attribute value) that is used to perform bind authentication.

This option is required if the -S or -m option is set to DIGEST-MD5.
-v Use verbose mode, with many diagnostics written to standard output.
-V version Specify the LDAP protocol level the client should use. The value for version can be 2 or 3. The default is 3.
-w passwd Use passwd as the password for simple, CRAM-MD5, and DIGEST-MD5 authentication. The default is a NULL string.
-x Specify FIPS mode for SSL/TLS protected connections. The supported FIPS modes are LEVEL1, LEVEL2, LEVEL3, and OFF. When FIPS mode is enabled, it is more restrictive regarding cryptographic algorithms, protocols, and key sizes that can be supported. If this option is not specified, the FIPS mode is set to OFF.

This option is ignored if -Z is not specified.
-Z Use a secure connection to communicate with the LDAP server. Secure connections expect the communication to begin with the SSL/TLS handshake.

The -K keyFile option or equivalent environment variable is required when the -Z option is specified. The -P keyFilePW option is required when the -Z option is specified and the key file specifies a file system key database file. Unless you want to use the default certificate in the key database file, RACF key ring, or PKCS #11 token, use the -N option to specify the label of the certificate.
dn
Specify the DN of the entry to change.
newRDN
Specify the new RDN for the entry.

All other command-line inputs result in a syntax error message, after which 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.

Examples

The following are ldapmodrdn examples.
  1. Assume that the /tmp/entrymods file exists and has the following contents: 
    cn=Modify Me, o=My Company, c=US
cn=The New Me
    The following command changes the RDN from cn=Modify Me to cn=The New Me and removes the old RDN cn=Modify Me from the entry. The DN of the entry is cn=The New Me, o=My Company, c=US.
    ldapmodrdn -r -f /tmp/entrymods
  2. The following command is another way to accomplish the same change as Example 1. An IBMModifyDNTimelimitControl control accompanies the operation request, specifying a time limit of 30 seconds.
    ldapmodrdn -r -l 30 "cn=Modify Me, o=My Company, c=US" "cn=The New Me"
  3. The following command changes the RDN from cn=Modify Me to cn=The New Me and removes the old RDN cn=Modify Me from the entry. The renamed entry is relocated beneath the new superior entry o=Some Other Company, c=US. The DN of the entry is changed to cn=The New Me, o=Some Other Company, c=US. If the renamed entry is a non-leaf node, its subordinate entries are also moved and renamed to reflect their new locations in the directory hierarchy. An IBMModifyDNTimelimitControl control accompanies the operation request, specifying a time limit of 30 seconds, and an IBMModifyDNRealignDNAttributesControl control accompanies the operation request.
    ldapmodrdn -l 30 -a -s "o=Some Other Company, c=US" "cn=Modify Me, o=My Company, c=US" "cn=The New Me"

Notes

The LDAP_DEBUG environment variable can be used to set the debug level. For more information about specifying the debug level by using keywords, decimal, hexadecimal, and plus and minus syntax, see Enabling tracing.

You can specify an LDAP URL for ldapHost on the -h option. See ldap_init() for more information.

For clients using authenticated binds, the DNs in their identity mappings might change as a result of a Modify DN operation which is performed concurrently with their session to the server, and this might affect ACL processing which results in permission to access, or denial of access to, directory entries for which they previously were permitted or denied access. The resolution for this situation is to unbind and rebind, so that identity processing uses the latest DNs.

For information about SSL/TLS, see SSL/TLS information for LDAP client utilities.

Diagnostics

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