2.2. Managing Entries from the Command-Line

The command-line utilities allow you to manipulate the contents of your directory. They can be useful to write scripts to perform bulk management of the directory or to test the Directory Server. For example, you might want to ensure that it returns the expected information after you have made changes to access control information.

With command-line utilities, information can be provided directly from the command-line or through an LDIF input file.

NOTE

You cannot modify your directory unless the appropriate access control rules have been set. For information on creating access control rules for your directory, see Chapter 6, Managing Access Control.

2.2.1. Providing Input from the Command-Line

When you provide input to the ldapmodify and ldapdelete^[1] utilities directly from the command-line, you must use LDIF statements. For detailed information on LDIF statements, see Section 2.4, “LDIF Update Statements”.

The ldapmodify and ldapdelete utilities read the statements that you enter in exactly the same way as if they were read from a file. When all of the input has been entered, enter the character that the shell recognizes as the end of file (EOF) escape sequence. The utility then begins operations based on the supplied inputs.

While the EOF escape sequence depends on the type of machine, the EOF escape sequence almost always control-D (^D).

For example, to input some LDIF update statements to ldapmodify, you would do the following:

ldapmodify -D bindDN -w password -h hostname
  dn: cn=Barry Nixon, ou=people, dc=example,dc=com
  changetype: modify
  delete: telephonenumber
  -
  add: manager
  manager: cn=Harry Cruise, ou=people, dc=example,dc=com
  ^D

When adding an entry from the command line or from LDIF, make sure that an entry representing a subtree is created before new entries are created under that branch. For example, to place an entry in a People subtree, create an entry representing that subtree before creating entries within the subtree. For example:

dn: dc=example,dc=com
dn: ou=People, dc=example,dc=com
...People subtree entries. ...
dn: ou=Group, dc=example,dc=com
...Group subtree entries. ...

2.2.2. Creating a Root Entry from the Command-Line

The ldapmodify command-line utility can be used to create a new root entry in a database. For example:

ldapmodify -a -D bindDN -w password

The ldapmodify utility binds to the server and prepares it to add an entry. The new root object can then be added, as follows:

dn: Suffix_Name
objectclass: newobjectclass

The DN corresponds to the DN of the root or sub-suffix contained by the database. The newobjectclass value depends upon the type of object class you are adding to the database. You may need to specify additional required attributes depending on the type of root object being added.

NOTE

You can use ldapmodify to add root objects only if you have one database per suffix. If you create a suffix that is stored in several databases, you must use the ldif2db utility with the -noption parameter to specify the database that will hold the new entries. For information, see Section 4.1.3, “Importing from the Command-Line”.

2.2.3. Adding Entries Using LDIF

You can use an LDIF file to add multiple entries or to import an entire database. To add entries using an LDIF file and the Directory Server Console:

Define the entries in an LDIF file.
LDIF files are described in Appendix A, LDAP Data Interchange Format.
Import the LDIF file from the Directory Server Console.
See Section 4.1.1, “Importing a Database from the Console” for information about LDIF file formats. When you import the LDIF file, select Append to database in the Import dialog box so that the server will only import entries that do not currently exist in the directory.

You can also add entries described in an LDIF file from the command-line using the ldapmodify command with the -f option.

2.2.4. Adding and Modifying Entries Using ldapmodify

The ldapmodify^[1] command can add and modify entries in an existing Directory Server database. The ldapmodify command opens a connection to the specified server using the supplied distinguished name and password 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.

Consider the following when using ldapmodify:

If the server detects an attribute or object class in the entry that is not known to the server, then the modify operation will fail when it reaches the erroneous entry. All entries that were processed before the error was encountered will be successfully added or modified. If you run ldapmodify with the -c option (do not stop on errors), all correct entries processed after the erroneous entry will be successfully added or modified.
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.

NOTE

To create the root entry a database suffix (such as dc=example,dc=com) using ldapmodify, you must bind to the directory as the Directory Manager.

2.2.4.1. Adding Entries Using ldapmodify

Typically, to add the entries using ldapmodify, specify the DN and password to bind to the Directory Server, the port and host of the Directory Server, and the LDIF file to use. For example:

ldapmodify -a -D "cn=Directory Manager" -w King-Pin -h cyclops -p 845 -f new.ldif

This ldapmodify example has the following values:

The entries to be created are specified in the file new.ldif. (In this example, the LDIF statements in the new.ldif file do not specify a change type. They follow the format defined in Section A.1, “About the LDIF File Format”.)
The Directory Manager is a database administrator who has the authority to modify the entries, and its password is King-Pin.
The hostname is cyclops.
The server uses port number 845.

Table 2.2, “ldapmodify Parameters Used for Adding Entries” describes the ldapmodify parameters used in the example.

Parameter Name	Description
-a	Specifies that the modify operation will add new entries to the directory.
-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.
-w	Specifies the password associated with the distinguished name specified in the `-D` parameter.
-h	Specifies the name of the host on which the server is running.
-p	Specifies the port number that the server uses.
-f	Optional parameter that specifies the file containing the LDIF update statements used to define the modifications. 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 Section 2.2.1, “Providing Input from the Command-Line”.

Table 2.2. ldapmodify Parameters Used for Adding Entries

For full information on ldapmodify parameters, see the Directory Server Configuration, Command, and File Reference.

2.2.4.2. Modifying Entries Using ldapmodify

Typically, to edit entries using ldapmodify, specify the DN and password to bind to the Directory Server, the port and host of the Directory Server, and the LDIF file to use, as when adding entries with ldapmodify. For example:

ldapmodify -D "cn=Directory Manager" -w King-Pin -h cyclops -p 845 -f modify_statements

This ldapmodify example has the following values:

The entries to modify are specified in the file modify_statements. Before the entries can be modified, you must first create the modify_statements file with the appropriate LDIF update statements; LDIF update statements are described in Section 2.4, “LDIF Update Statements”.
The bind DN is cn=Directory Manager, which has permissions to edit any entry in the database, and the password is King-Pin.
The hostname is cyclops.
The server uses port number 845.

Table 2.3, “ldapmodify Parameters Used for Modifying Entries” describes the ldapmodify parameters used in the example.

Parameter Name	Description
-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.
-w	Specifies the password associated with the distinguished name specified in the `-D` parameter.
-h	Specifies the name of the host on which the server is running.
-p	Specifies the port number that the server uses.
-f	Optional parameter that specifies the file containing the LDIF update statements used to define the modifications. 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 Section 2.2.1, “Providing Input from the Command-Line”.

Table 2.3. ldapmodify Parameters Used for Modifying Entries

For full information on ldapmodify parameters, see the Directory Server Configuration, Command, and File Reference.

2.2.5. Deleting Entries Using ldapdelete

The ldapdelete command-line utility opens a connection to the specified server using the provided distinguished name and password and deletes the specified entry or entries.

NOTE

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, only the last two entries can be deleted.

ou=People,dc=example,dc=com
cn=Paula Simon,ou=People,dc=example,dc=com
cn=Jerry O'Connor,ou=People,dc=example,dc=com

The entry that identifies the People subtree can be deleted only if there are not any entries below it. To delete ou=People,dc=example,dc=com, you must first delete Paula Simon and Jerry O'Connor's entries and all other entries in that subtree.

Like ldapmodify, running ldapdelete requires the DN and password to bind to the Directory Server, the port and host of the Directory Server, and the DNs of the entries to delete. For example:

ldapdelete -D "cn=Directory Manager" -w King-Pin -h cyclops -p 845 "cn=Robert
    Jenkins,ou=People,dc=example,dc=com" "cn=Lisa
    Jangles,ou=People,dc=example,dc=com"

This ldapdelete example has the following values:

The entries tp delete have the DNs cn=Robert Jenkins,ou=People,dc=example,dc=com and cn=Lisa Jangles, ou=People,dc=example,dc=com.
The bind DN is the Directory Manager, which has permission to delete every entry in the database, and a password of King-Pin.
The hostname is cyclops.
The server uses port number 845.

Table 2.4, “ldapdelete Parameters Used for Deleting Entries” describes the ldapdelete parameters used in the example:

Parameter Name	Description
-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.
-w	Specifies the password associated with the distinguished name specified in the `-D` parameter.
-h	Specifies the name of the host on which the server is running.
-p	Specifies the port number that the server uses.

Table 2.4. ldapdelete Parameters Used for Deleting Entries

For full information on ldapdelete parameters, see the Directory Server Configuration, Command, and File Reference.

2.2.6. 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 (*), or backslash (\). When this situation occurs, enclose the value in quotation marks (""). For example:

-D "cn=Barbara Jensen,ou=Product Development,dc=example,dc=com"

Depending on the command-line utility, use either single or double quotation marks; see your operating system documentation for more information.

Additionally, if a DN contains commas, you must escape the commas with a backslash (\). For example:

-D "cn=Patricia Fuentes,ou=people,o=example.com Bolivia\,S.A."

To delete user Patricia Fuentes from the example.com Bolivia, S.A. tree, use the following command:

ldapdelete -D "cn=Directory Manager" -w King-Pin -h cyclops -p 845 "cn=Patricia
   Fuentes,ou=People,o=example.com Bolivia\,S.A."

^[1] The LDAP tools referenced in this guide are Mozilla LDAP, installed with Directory Server in the /usr/lib/mozldap directory on Red Hat Enterprise Linux 5 (32-bit); directories for other platforms are listed in Section 1.2, “LDAP Tool Locations”. However, Red Hat Enterprise Linux systems also include LDAP tools from OpenLDAP. It is possible to use the OpenLDAP commands as shown in the examples, but you must use the -x argument to disable SASL and allow simple authentication.