3.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 the directory, see Chapter 13, Managing Access Control.

3.2.1. Providing Input from the Command Line

When you provide input to the ldapmodify and ldapdelete utilities directly from the command line, you must use LDIF statements. For detailed information on LDIF statements, see Section 3.3, “Using LDIF Update Statements to Create or Modify Entries”.
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: 
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x
  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. ...

3.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 "cn=directory manager" -W -p 389 -h server.example.com -x

dn: Suffix_Name
changetype: add
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.6, “Importing from the Command Line”.

3.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:
  1. Define the entries in an LDIF file.
    LDIF files are described in Appendix B, LDAP Data Interchange Format.
  2. Import the LDIF file from the Directory Server Console.
    See Section 4.1.4, “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.

3.2.4. Adding and Modifying Entries Using ldapmodify

The ldapmodify 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.

3.2.4.1. Adding Entries Using ldapmodify

Typically, to add the entries using ldapmodify, pass the -a option to indicate an add operation and the LDIF file to use which contains the new entry information (and, optionally, the bind credentials and any connection information). For example: 
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x -f new.ldif
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 B.1, “About the LDIF File Format”.)
If the new entry is not passed in a given LDIF file, then the ldapmodify utility waits for the DN of the new entry and then each object class and attribute for the entry, each on a new line in LDIF format. When the last attribute is entered, hit enter twice to submit the new entry.
Table 3.2, “ldapmodify Parameters Used for Adding Entries” describes the ldapmodify parameters used in the example.

Table 3.2. ldapmodify Parameters Used for Adding Entries

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, see Section 3.2.1, “Providing Input from the Command Line”.

3.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 -p 389 -h server.example.com -x -f modify_statements
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 3.3, “Using LDIF Update Statements to Create or Modify Entries”.
Table 3.3, “ldapmodify Parameters Used for Modifying Entries” describes the ldapmodify parameters used in the example.

Table 3.3. ldapmodify Parameters Used for Modifying Entries

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, see Section 3.2.1, “Providing Input from the Command Line”.
-x Disables SASL to allow a simple bind to the server.

3.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 secret -p 389 -h server.example.com -x "cn=Robert Jenkins,ou=People,dc=example,dc=com" "cn=Lisa Jangles,ou=People,dc=example,dc=com"
The DNs of the entries to delete (cn=Robert Jenkins,ou=People,dc=example,dc=com and cn=Lisa Jangles,ou=People,dc=example,dc=com) are appended to the end of the delete command.
Table 3.4, “ldapdelete Parameters Used for Deleting Entries” describes the ldapdelete parameters used in the example:

Table 3.4. ldapdelete Parameters Used for Deleting Entries

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.
-x Disables SASL to allow a simple bind to the server.

3.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 secret -p 389 -h server.example.com -x "cn=Patricia Fuentes,ou=People,o=example.com Bolivia\,S.A."