The command-line client utilities allow you to manipulate the contents of your directory. The command-line utilities are especially useful for writing scripts to perform bulk management of your directory, or for testing your Directory Server to ensure that it is working correctly (especially if you have changed your access control information) or written a custom client.
This section provides information about:
Using Special Characters
When using the Directory Server command-line client tools, you may need to specify values that contain characters that have special meaning to the command-line interpreter (such as space [ ], asterisk [*], backslash [\], and so forth). When this situation occurs, enclose the value in quotation marks (""). For example:
-D "cn=Barbara Jensen, ou=Product Development, o=airius.com"
Depending on the command-line utility you use, you should use either single
or double quotation marks for this purpose. Refer to your operating system
documentation for more information.
In addition, if you are using DNs that contain commas, you must escape the
commas with a backslash (\). For example:
-D "cn=Patricia Fuentes, ou=people, o=Airius Bolivia\, S.A."
Providing Input From the Command Line
ldapmodify and ldapdelete allow you to provide input both from an input file (using the -f parameter), as well as from the command line. If you want to provide input from the command line, do not specify the -f parameter when you use these commands.
The tool collects statements you enter in exactly the same way as if they were read from a file. When you finish providing input, enter the character that your shell recognizes as the end of file (EOF) marker. This causes the utility to begin operations based on the input you supplied.
Typically, the EOF escape sequence is one of the following, depending upon the type of machine you use:
For example, suppose you wanted to specify some LDIF update statements to ldapmodify. Then, on Unix, you would do the following:
prompt> ldapmodify -D <bindDN> -w <password> -h <hostname>
> dn: cn=Barry Nixon, ou=people, o=airius.com
> changetype: modify
> delete: telephonenumber
> -
> add: manager
> manager: cn=Harry Cruise, ou=people, o=airius.com
> ^D
prompt>
When you add an entry from the command-line or from LDIF, make sure that an entry representing a branch point is created before new entries are created under that branch. For example, if you want to place an entry in a Person and a Group subtree, then create the branch point for those subtrees before creating entries within the subtrees. For example:
dn: o=airius.com
dn: ou=People, o=airius.com
...
<People subtree entries.>
...
dn: ou=Group, o=airius.com
...
<Group subtree entries.>
...
Adding Entries Using LDIF
You can use an LDIF file to add multiple entries or to import an entire database. For details, refer to "Importing LDIF From the Server Console". You can also add or edit entries using the ldapmodify command along with the appropriate LDIF update statements. For details, refer to "Adding and Modifying Entries Using ldapmodify". For details on LDIF, see Chapter 2, "LDAP Data Interchange Format."
To add entries using an LDIF file and the Directory Server Console:
Define the entries in an LDIF file. LDIF is described in Chapter 2, "LDAP Data Interchange Format."
Import the LDIF file from the Directory Server Console. See "Importing Databases From LDIF" for information. When you import the LDIF file, select "Append to database" on the Import dialog box so that the server will only import entries that do not currently exist in the directory.
Adding and Modifying Entries Using ldapmodify
You use the ldapmodify command-line utility to modify entries in an existing
Directory Server database. ldapmodify opens a connection to the specified
server using the distinguished name and password you supply, and modifies
the entries based on LDIF update statements contained in a specified file.
Because ldapmodify uses LDIF update statements, ldapmodify can do
everything that ldapdelete can do.
For information on where you can find the command-line utilities in your Directory Server installation, see "Finding the Command-Line Utilities".
If schema checking is turned on when you use this utility, then the server
performs schema checking for the entire entry when it is modified. If the server
detects an attribute or object class in the entry that is not known to the server,
then the entire modify operation fails. Also, if a required attribute is not present,
the modify operation fails. This happens even if the offending object class or
attribute is not being modified.
This situation occurs if you ran the Directory Server with schema checking
turned off, added unknown object classes or attributes, and then turned schema
checking on.
Note.
You cannot create a root entry (such as o=airius.com) using ldapmodify unless you bind to the directory as the root DN, for example, cn=Directory Manager.
For more information, see "Turning Schema Checking On and Off".
This section provides information about:
Commonly Used ldapmodify Parameters
To modify an entry or entries in an existing directory, use the ldapmodify command-line utility with the following parameters:
-D. Specifies the distinguished name with which to authenticate to the server. The
value must be a DN recognized by the directory server, and it must also have
the authority to modify the entries. For example, -D uid=bjensen,
o=airius.com. You cannot use this parameter with the -N parameter.
-w. Specifies the password associated with the distinguished name specified in the
-D parameter. For example, -w mypassword.
-h. Specifies the name of the host on which the server is running. For example, -h
cyclops.
-p. Specifies the port number that the server uses. For example, -p 1049. The
default is 389. If -Z is used, the default is 636.
-f. Optional parameter that specifies the file containing the LDIF update statements
used to define the directory modifications. For example, -f modify_statements.
If you do not supply this parameter, the update statements are read from
stdin. For information on supplying LDIF update statements from the
command line, refer to "Providing Input From the Command Line".
-a. Allows you to add LDIF entries to the directory without requiring the
changetype:add LDIF update statement. This provides a simplified method
of adding entries to the directory. This option also allows you to directly add a
file created by ldapsearch.
SSL Parameters
You can use the following command-line parameters to specify that ldapmodify is to use LDAP over SSL (LDAPS) when communicating with your Directory Server. LDAPS encrypts data during transit. You also use these parameters if you want to use certificate-based authentication. These parameters are valid only when SSL has been turned on and configured for your Directory Server. For more information on certificate-based authentication, see See "Using Certificate-Based Authentication". For information on creating a certificate database for use with LDAP clients, see See "Creating Certificate Databases for LDAP Clients".
Make sure that you specify your Directory Server's encrypted port when you use these parameters:
-Z. Specifies that SSL is to be used for the directory request.
-P. Specifies the path and filename of the security files for the client. This
parameter is used only with the -Z parameter. When used on a machine where
a SSL-enabled web browser is configured, the path specified on this parameter
can be pointed to the security database for the web browser. For example, -P
c:\security\cert.db. You can also store the client security files on the
Directory Server in the <NSHOME>/alias directory. In this case, the -P
parameter calls out a path and filename similar to the following:
-P c:\Netscape\Suitespot\alias\client-cert.db
-N. Specifies the certificate name to use for certificate-based client authentication.
For example, -N Server-Cert. If this parameter is specified, then the -Z, -K,
and -W parameters are required. Also, if this parameter is specified, then the -D
and -w parameters must not be specified, or certificate-based authentication
will not occur and the bind operation will use the authentication credentials
specified on -D and -w.
-K. Specifies the name of the certificate key used for certificate-based client
authentication. For example, -K Server-Key.
-W. Specifies the password for the certificate database identified on the -P
parameter. For example, -W serverpassword.
Additional ldapmodify Parameters
The following parameters offer additional functionality:
-b. Causes the utility to check every attribute value to determine whether the value
is a valid file reference. If the value is a valid file reference, then the content of
the referenced file is used as the attribute value. This is often used for
specifying a path to a file containing binary data, such as JPEG. For example, if
you wanted to add a jpegPhoto attribute, then specify the -b parameter on
the ldapmodify call. In the LDIF you provide to ldapmodify, include
something like the following:
jpegPhoto: /tmp/photo.jpeg
ldapmodify reads the contents of the photo.jpeg file into the jpegPhoto
attribute that you are placing on the entry.
On Windows NT, the format of this parameter is exactly the same (including
the forward slashes, except that you can specify a drive letter. For example:
jpegPhoto: c:/tmp/photo.jpeg
-c. Specifies that the utility run in continuous operation mode. Errors are reported,
but the utility continues with modifications. The default is to quit after reporting
an error.
-H. Lists all available ldapmodify parameters.
-M. Manage smart referrals. Causes the server to not return the smart referral
contained on the entry, but to instead apply the modification request directly to
the entry. Use this parameter if you are attempting to add, change, or delete a
directory entry that contains a smart referral. For more information about smart
referrals, see "Creating and Changing Smart Referrals".
-n. Specifies that the entries are not to be actually modified, but that ldapmodify
is to show what it would do with the specified input.
-O. Specifies the maximum number of referral hops to follow. For example, -O 2.
-R. Specifies that referrals are not to be followed automatically.
-v. Specifies that the utility is to run in verbose mode.
-V. Specifies the LDAP version number to be used on the operation. For example,
-V 2. LDAP v3 is the default. Note that you can not perform an LDAP v3
operation against a Directory Server that only supports LDAP v2.
ldapmodify Example
Suppose:
Then to modify the entries, first specify the appropriate LDIF update statements in the modify_statements file, and then enter the following command:
ldapmodify -D "cn=Directory Manager, o=airius.com" -w King-Pin -h
cyclops -p 845 -f modify_statements
Deleting Entries Using ldapdelete
You use the ldapdelete command-line utility to delete entries from an existing Directory Server database. This utility opens a connection to the specified server using the distinguished name and password you provide, and deletes the entry or entries. (For information on where you can find the command-line utilities in your Directory Server installation, see "Finding the Command-Line Utilities".)
You can only delete entries at the end of a branch. You cannot delete entries that are branch points in the directory tree. For example, of the following three entries:
ou=People, o=airius.com
cn=Paula Simon, ou=People, o=airius.com
cn=Jerry O'Connor, ou=People, o=airius.com
you can delete only the last two entries. The entry that identifies the People subtree can be deleted only if no other entries exist below it. If you want to delete ou=People, o=airius.com, you must first delete cn=Paula Simon, ou=People, o=airius.com and cn=Jerry O'Connor, ou=People, o=airius.com.
This section provides information about:
Commonly Used ldapdelete Parameters
To delete an entry or entries from an existing database, use the ldapdelete command-line utility with the following parameters:
-D. Specifies the distinguished name with which to authenticate to the server. The
value must be a DN recognized by the Directory Server, and it must also have
the authority to delete the entries. For example, -D uid=bjensen,
o=airius.com. Access control is described in Chapter 5, "Managing Access
Control." If you use the -D parameter, you cannot use the -N parameter.
-w. Specifies the password associated with the distinguished name specified in the
-D parameter. For example, -w mypassword. The default is "", or anonymous.
-h. Specifies the name of the host on which the server is running. For example, -h
cyclops. The default is localhost.
-p. Specifies the port number that the server uses. Default is 389. If -Z is used, the
default is 636.
SSL Parameters
You can use the following parameters to specify that ldapdelete use LDAPS when communicating with your Directory Server. You also use these parameters if you want to use certificate-based authentication. These parameters are valid only when LDAPS has been turned on and configured for your Directory Server. For more information on certificate-based authentication, see See "Using Certificate-Based Authentication". For information on creating a certificate database for use with LDAP clients, see See "Creating Certificate Databases for LDAP Clients".
Make sure that you specify your Directory Server's encrypted port when you use these parameters:
-Z. Specifies that SSL is to be used for the delete request.
-P. Specifies the path and filename of the security files for the client. This
parameter is used only with the -Z parameter. When used on a machine where
an SSL-enabled web browser is configured, the path specified on this parameter
can point to the security database for the web browser. For example, -P
c:\security\cert.db. The client security files can also be stored on the
Directory Server in the <NSHOME>/alias directory (where NSHOME is the
directory where you installed the server). In this case, the -P parameter calls out
a path and filename similar to the following:
-P c:\Netscape\Suitespot\alias\client-cert.db.
-N. Specifies the certificate name to use for certificate-based client authentication.
For example, -N Server-Cert. If this parameter is specified, then the -Z, -K,
and -W parameters are required. Also, if this parameter is specified, then the -D
and -w parameters must not be specified, or certificate-based authentication
will not occur and the bind operation will use the authentication credentials
specified on -D and -w.
-K. Specifies the name of the certificate key used for certificate-based client
authentication. For example, -K Server-Key.
-W. Specifies the password for the certificate database identified on the -P
parameter. For example, -W serverpassword.
Additional ldapdelete Parameters
The following parameters offer additional functionality:
-c. Specifies that the utility run in continuous operation mode. Errors are reported,
but the utility continues with deletions. The default is to quit after reporting an
error.
-f. Specifies the file containing the distinguished names of entries to be deleted.
For example, -f modify_statements. Omit this parameter if you want to supply
the distinguished name of the entry to be deleted directly to the command line.
-H. Lists all available ldapdelete parameters.
-M. Manage smart referrals. Causes the server to not return the smart referral
contained on the entry, but to instead delete the actual entry containing the
smart referral. For more information about smart referrals, see "Creating and
Changing Smart Referrals".
-n. Specifies that the entries are not to be actually deleted, but that ldapdelete is
to show what it would do with the specified input.
-O. Specifies the maximum number of referral hops to follow. For example, -O 2.
-R. Specifies that referrals are not to be followed automatically. By default, the
server follows referrals.
-v. Specifies that the utility is to run in verbose mode.
-V. Specifies the LDAP version number to be used on the operation. For example,
-V 2. LDAP v3 is the default. Note that you cannot perform an LDAP v3
operation against a Directory Server that only supports LDAP v2.
ldapdelete Examples
Suppose:
Then to delete the entries for users Robert Jenkins and Lisa Jangles, enter the following command:
ldapdelete -D "cn=Directory Manager, o=airius.com" -w King~Pin -h
cyclops -p 845 "cn=Robert Jenkins, ou=People, o=airius.com" "cn=Lisa
Jangles, ou=People, o=airius.com"
To delete user Patricia Fuentes from the Airius Bolivia, S.A. tree, you would enter the following command:
ldapdelete -D "cn=Directory Manager, o=airius.com" -w King~Pin -h
cyclops -p 845 "cn=Patricia Fuentes, ou=People, o=Airius Bolivia\, S.A."
The DN of this entry contains a comma, so you must escape the comma with a backslash (\).