[Previous] [Next] [TOC] [Index]

Appendix D
LDAP Command-Line Utilities

he Directory SDK includes command-line utilities for searching and updating the directory. If you want to write shell scripts or simple programs for working with an LDAP server, you can use these utilities.

The command-line utilities provided with the Directory SDK allow you to do the following:

The utilities for adding and modifying entries rely on input in the LDAP Data Interchange Format (LDIF). In order to use these utilities, you need to be familiar with that format.

This appendix covers the command-line utilities and the LDIF format in the following sections:

Using LDIF Format

 In order to add or modify entries in the directory, you need to specify the new entries or changes to the entries in the LDAP Data Interchange Format (LDIF).

NOTE: If you are not adding or modifying entries, you can skip ahead to the next section "Using the Command-Line Utilities".
The LDAP Data Interchange Format (LDIF) is used to represent entries or information about entries in text form.

For example, if you wanted to add entries to the directory, one of the entries in an LDIF file might look like this:

dn: cn=June Rossi, ou=accounting, o=Ace Industry, c=US
cn: June Rossi
sn: Rossi
givenName: June
mail: rossi@aceindustry.com
userPassword: {sha}KDIE3AL9DK
telephoneNumber: 2616
roomNumber: 220
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson

Using LDIF to Add Entries

 To add an entry to the directory, write an LDIF entry in the following format:

   [<id>]
   dn: <distinguished name>
   objectClass: <object class>
   objectClass: <object class>
   ...
   <attribute type>:<attribute value>
   <attribute type>:<attribute value>
   ...t
Every new entry that you want to add must have the following information in LDIF:

All other attributes and object classes are optional. You can specify object classes and attributes in any order.

The following table describes the LDIF fields shown in the previous definition:
Field Definition
[<id>] Optional positive decimal number representing the entry ID. The database creation tools generate this ID for you. Never add or edit this value yourself.
dn: <distinguished name> Specifies the distinguished name for the entry. For a complete description of distinguished names, refer to Appendix A, "Distinguished Names."
objectClass: <object class> Specifies an object class to use with this entry. The object class identifies the types of attributes, or schema, allowed and required for the entry.
<attribute type> Specifies a descriptive attribute to use with the entry. See Appendix B, "Entries and Attributes." (The attribute should be defined in the configuration files of the LDAP server that you are connecting to. The attribute should either be in slapd.at.conf or with the attribute parameter in slapd.conf.)
<attribute value> Specifies the attribute value to be used with the attribute type.

When you specify lines in LDIF, you can break and continue a line by indenting the continued portion of the line by exactly one space. For example, the following two statements are identical:

   dn: cn=Jake Lupinski, ou=Accounting, o=Ace Industry, c=US
   dn: cn=Jake Lup
    inski, ou=Accoun
    ting, o=Ace Industr
    y, c=US

Specifying an Organizational Person

 The most common type of entry that you will include in your directory will describe a person within your organization. The LDIF you specify to define an organizational person should appear as follows:

   dn: distinguished name
   cn: common name
   sn: surname
   list of optional attributes
   ...
   objectClass: top
   objectClass: person
   objectClass: organizationalPerson
   objectClass: inetOrgPerson
The following defines each aspect of the LDIF-formatted entry:

dn: distinguished name

Specifies the DN for the entry. DNs are described in Appendix A, "Distinguished Names.". A DN is required.

cn: common name

Specifies the common name for the person. That is, the full name commonly used by the person. For example, cn: Bill Anderson. A common name is required.

sn: surname

Specifies the person's surname, or last name. For example,
sn: Anderson. A surname is required.

list of attributes

Specifies the list of optional attributes that you want to maintain for the entry. Refer to the online documentation that comes with the server for a list of the attributes you can use with this object class. See Appendix A, "Object classes and attributes".

objectClass: top

Specifies the top object class. This object class specification is optional. Some older LDAP clients will require the existence of object class top during search operations.

objectClass: person

Specifies the person object class. This object class specification should be included because many LDAP clients will require the existence of object class person during search operations for a person or an organizational person.

objectClass: organizationalPerson

Specifies the organizationalPerson object class. This object class specification should be included because some LDAP clients will require the existence of object class organizationalPerson during search operations for an organizational person.

objectClass: inetOrgPerson

Specifies the inetOrgPerson object class. The inetOrgPerson object class is recommended for the creation of an organizational person entry because this object class includes the widest range of attributes. Refer to the online documentation that comes with the server for a list of the attributes you can use with this object class. See Appendix A, "Object classes and attributes".

Example: Using an LDIF File to Add Entries

The following example shows an LDIF file that contains three organizational person entries:

dn: cn=June Rossi, ou=accounting, o=Ace Industry, c=US
cn: June Rossi
sn: Rossi
givenName: June
mail: rossi@aceindustry.com
userPassword: {sha}KDIE3AL9DK
telephoneNumber: 2616
roomNumber: 220
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
dn: cn=Marc Chambers, ou=manufacturing, o=Ace Industry, c=US
cn: Marc Chambers
sn: Chambers
givenName: Marc
mail: chambers@aceindustry.com
userPassword: {sha}jdl2alem87dlacz1
telephoneNumber: 2652
roomNumber: 167
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
 
dn: cn=Robert Wong, ou=manufacturing, o=Ace Industry, c=US
cn: Robert Wong
cn: Bob Wong
sn: Wong
givenName: Robert
givenName: Bob
mail: bwong@aceindustry.com
userPassword: {sha}nn2msx761
telephoneNumber: 2881
roomNumber: 211
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson

Using LDIF to Update Entries

 If you want to update an entry in the directory, you need to use LDIF update statements to specify the changes. In general, LDIF update statements are a series of statements that:

The general format of LDIF update statements is as follows: 

   dn: distinguished name
   changetype identifier
   change operation identifier
   list of attributes
   ...
 
   -
 
   change operation identifier
   list of attributes
   ...
 
   -
 
   ...
Note A dash (-) must be used to denote the end of a change operation if subsequent change operations are specified. For example, the following statement adds the telephone number and manager attributes to the entry: 
   dn: cn=Lisa Jangles, ou=Sales, o=Ace Industry, c=US 
   changetype: modify
   add: telephonenumber
   telephonenumber: (408) 555-2468
   -
   add: manager
   manager: cn=Harry Cruise, ou=Manufacturing, o=Ace Industry, c=US
 In addition, the line continuation operator is a space. Therefore, the following two statements are identical:

   dn: cn=Lisa Jangles, ou=Sales, o=Ace Industry, c=US 
   dn: cn=Lisa Jangles,
      ou=Sales,
      o=Ace Industry,
      c=US
 The following sections describe the change types in detail.

Specifying Different Types of Changes

There are four change types you can specify. Note that the modify change type can be used to add, replace, or remove attribute values.

changetype: add

Adds entire new entries. The format of this type of change is essentially the same as an LDIF-formatted entry (LDIF is described in "Using LDIF to Add Entries"). The format is:

dn: distinguished name 
changetype: add
objectClass: objectClass
objectClass: objectClass
...
attribute type: attribute value
attribute type: attribute value
...

changetype: delete

 Deletes the entire entry. The format is:

dn: distinguished name
changetype: delete

changetype: modrdn

Modifies the relative distinguished name (RDN) of an entry. In essence, this renames the entry. An entry's RDN is the leftmost element in its distinguished name.

The format is:

      dn: distinguished name
      changetype: modrdn
      newrdn: new rdn
      deleteoldrdn: 0|1

where deleteoldrdn indicates whether the old RDN is to be deleted (1). If 0 is specified, then the attribute values of the old RDN are included in the entry corresponding to the new RDN.

changetype: modify

Adds, replaces, or removes attributes and/or attribute values to the entry. When changetype: modify is specified, a change operation is required to indicate how the entry is to be modified. Change operations can be:

The format is:

   dn: distinguished name 
   changetype: modify
   add: attribute type
   attribute type: attribute value
   attribute type: attribute value
   -
   ...
   replace: attribute type
   attribute type: attribute value
   attribute type: attribute value
   -
   ...
   delete: attribute type
   attribute type: attribute value
   attribute type: attribute value
   -
   ...

Example: Using LDIF update statements

 The following LDIF update statement adds a new entry:

   dn: cn=Barry Nixon, ou=Manufacturing, o=Ace Industry, c=US 
   changetype: add
   objectClass: top
   objectClass: person
   objectClass: orgperson
   objectClass: inetorgperson
   cn: Barry
   cn: Barry Nixon
   sn: Nixon
The following example adds the attribute types telephonenumber and manager to the existing entry. Note that two telephone numbers are added to the entry:

   dn: cn=Barry Nixon, ou=Manufacturing, o=Ace Industry, c=US 
   changetype: modify
   add: telephonenumber
   telephonenumber: (408) 555-1357
   telephonenumber: (408) 555-9753
   -
   add: manager
   manager: cn=Harry Cruise, ou=Manufacturing, o=Ace Industry, c=US
The following example replaces the manager attribute for the existing entry:

   dn: cn=Barry Nixon, ou=Manufacturing, o=Ace Industry, c=US 
   changetype: modify
   replace: manager
   manager: cn=Carrie King, ou=Manufacturing, o=Ace Industry, c=US
The following example deletes a telephone number for the entry (you would use this method if multiple telephone numbers are specified for the entry, and you want to delete just one of them):

   dn: cn=Barry Nixon, ou=Manufacturing, o=Ace Industry, c=US 
   changetype: modify
   delete: telephonenumber
   telephonenumber: (408) 555-9753
The following example deletes all instances of the telephone number attribute from the entry:

   dn: cn=Barry Nixon, ou=Manufacturing, o=Ace Industry, c=US 
   changetype: modify
   delete: telephonenumber
The following example modifies the RDN for the entry: 

   dn: cn=Barry Nixon, ou=Manufacturing, o=Ace Industry, c=US 
   changetype: modrdn
   newrdn: cn=Barney Nixon
   deleteoldrdn: 0
Because deleteoldrdn is 0, this example retains the existing RDN in the new entry. The resulting entry would therefore have a common name attribute set to both Barry Nixon and Barney Nixon in addition to all the other attributes included in the original entry.

Using the Command-Line Utilities

The Directory SDK includes five command-line utilities that you can use to search and update an LDAP server:

This section documents these utilities and provides general instructions for using the utilities.

General Instructions

When using the command-line utilities, you should keep the following usage guidelines in mind.

Using Quotation Marks

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=Ace Industry, c=US"
Note Depending on the command-line interpreter you are using, you should use either single or double quotation marks for this purpose. Refer to your operating system documentation for more information.

Providing Input from the Command Line

 The ldapadd, ldapmodify, and ldapmodrdn command-line utilities let you provide input both from an input file (using the -f option), as well as from the command line. If you want to provide input from the command line, do not specify the -f option when you call these commands.

Each of these utilities collects statements that you enter to the shell in exactly the same way as if they were reading from a file (see the description of the various command-line utilities for information on what kind of statements each requires). When you are done providing input to the utility, 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 have supplied.

Although configurable, the EOF escape sequence is almost always control-D (^D).

For example, suppose you wanted to specify some LDIF update statements to ldapmodify. Then you would do the following:

prompt> ldapmodify -D binddn -w password -h hostname 
> dn: cn=Barry Nixon, ou=Manufacturing, o=Ace Industry, c=US
> changetype: modify
> delete: telephonenumber
> -
> add: manager
> manager: cn=Harry Cruise, ou=Manufacturing, o=Ace Industry, c=US
> ^D
prompt>
Note that the ldapsearch utility works somewhat differently from the other command-line utilities in that it requires you to either specify the -f option or supply a single search filter directly to the command-line call. For more information on using filters, refer to "ldapsearch" on page 348.

ldapadd

ldapadd adds one or more entries to the directory.

Syntax
ldapadd [-h <host>] [-p <port>] [-D <binddn>] [-w <password>] 
   [-f <ldiffile>] [-e <rejectedfile>] [-O <maxhops>] 
   [-Z -P <certdbpath>] [-bcFHnRv]
 The options for this command are described below. For convenience, commonly used options are listed first. The rest of the options are listed in alphabetical order. 
-h <host>
 Specifies the name of the host on which the LDAP server is running. If you do not specify this option, localhost is used. 
-p <port>
 Specifies the port on which the LDAP server is running. If you do not specify this option, either 389 (if the LDAP server not using SSL) or 636 (if the LDAP server is using SSL and if you specify the Z option) are used. 
-D <binddn>
 Specifies the distinguished name that you want to authenticate as. This DN must have access privileges to add entries to the directory. If you do not specify this option, anonymous authentication is used. 
-w <password>
 Specifies the password for the DN that you want to authenticate as. If you do not specify this option, no password is used. 
-f <ldiffile>
 Specifies the file containing the new entries to be added. The entries should be in LDIF format (see "Using LDIF to Add Entries" for details). If you do not specify this option, you will need to use standard input to enter the new entries. (In other words, you will need to enter the LDIF statements on the command line.) 
-b
Specifies that if an attribute value starts with a slash ("/"), that value is a pathname to a file that contains the actual value. For example, suppose you specify the following attribute and value: 
jpegPhoto: /tmp/photo.jpeg
 

This utility interprets this line to mean "the value of the jpegPhoto attribute is found in the file /tmp/photo.jpeg".
If you do not specify this option in the example above, the utility assumes that the value you've specified is the actual value to be assigned to the attribute. 



-c 

Runs this utility in continuous operation mode. If errors occur, the utility will report the errors and continue running.
If you do not specify this option, this utility will exit when encountering an error.



-e <rejectfile>

Specifies a file in which to log any entries that could not be added. If this utility is not able to add the entry to the directory, the utility writes the error message and the entry to this file.



-F

Legacy option. Not currently supported.



-H

Displays help on this utility.



-n

Lets you preview what would happen if you added the entries, but does not actually add the entries. 



-O <maxhops>

Specifies the maximum number of referrals in a sequence that this utility should follow. For example, suppose you set this maximum to 1 referral. If LDAP server A refers the utility to LDAP server B, and LDAP server B refers the utility to LDAP server C, the utility will not follow the referral to server C. (This is the second referral in a sequence, which exceeds to maximum of 1 referral.)
By default, the utility stops following referrals after 5 referrals in a row. 



-P <certdbfile>

Specifies the path to the certificate database for this utility (for example, ~/.netscape/cert5.db). Use this option if you are connecting to an LDAP server over SSL and if you have specified the -Z option.



-R

Prevents this utility from automatically following referrals. 



-v

Runs this utility in verbose mode. 



-Z

Specifies that this utility connects to the LDAP server using SSL. Use this option if you are connecting to a secure LDAP server. 



 




 Description




The ldapadd utility opens a connection to the LDAP server specified by the -h and -p options, authenticates as the user specified by the -D and -w options, and adds the entries that are either specified on the command line or in the file identified by the -f option. 


Note the following:





 Examples




The following command adds the entries specified in an LDIF file to the directory. The command does the following:






 ldapdelete




ldapdelete deletes one or more entries from the directory. 




 Syntax





ldapdelete [-h <host>] [-p <port>] [-D <binddn>] [-w <password>
   [-f <file_with_DNs>][-O <maxhops>] 
   [-Z -P <certdbpath>] [-cHnRv] [<dn_to_delete>]

The options for this command are described below. For convenience, commonly used options are listed first. The rest of the options are listed in alphabetical order. 





-h <host>

Specifies the name of the host on which the LDAP server is running. 
If you do not specify this option, localhost is used. 



-p <port>

Specifies the port on which the LDAP server is running.
If you do not specify this option, either 389 (if the LDAP server not using SSL) or 636 (if the LDAP server is using SSL and if you specify the Z option) are used. 



-D <binddn>

Specifies the distinguished name that you want to authenticate as. This DN must have access privileges to delete entries from the directory. 
If you do not specify this option, anonymous authentication is used. 



-w <password>

Specifies the password for the DN that you want to authenticate as.
If you do not specify this option, no password is used. 



-f <file_with_DNs>

Specifies the file containing the DNs of the entries to delete.
If you do not specify this option, you will need to use standard input to enter the DNs. (In other words, you will need to enter the DNs on the command line.)



[<dn_to_delete>]

Specifies the DN identifying the entry to be deleted. If you want to specify more than one entry, you can list the DNs in a file and use the -f option. 



-c 

Runs this utility in continuous operation mode. If errors occur, the utility will report the errors and continue running.
If you do not specify this option, this utility will exit when encountering an error.



-F

Legacy option. Not currently supported.



-H

Displays help on this utility.



-n

Displays the effect of what would happen if you deleted the entries, but does not actually delete the entries. 



-O <maxhops>

Specifies the maximum number of referrals in a sequence that this utility should follow. 
For example, suppose you set this maximum to 1 referral. If LDAP server A refers the utility to LDAP server B, and LDAP server B refers the utility to LDAP server C, the utility will not follow the referral to server C. (This is the second referral in a sequence, which exceeds to maximum of 1 referral.)
By default, the utility stops following referrals after 5 referrals in a row. 



-P <certdbfile>

Specifies the path to the certificate database for this utility (for example, ~/.netscape/cert5.db). Use this option if you are connecting to an LDAP server over SSL and if you have specified the -Z option.



-R

Prevents this utility from automatically following referrals. 



-v

Runs this utility in verbose mode. 



-Z

Specifies that this utility connects to the LDAP server using SSL. Use this option if you are connecting to a secure LDAP server. 








 Description




The ldapdelete utility opens a connection to the LDAP server specified by the -h and -p options, authenticates as the user specified by the -D and -w options, and deletes the entries for the specified DNs. The DNs are either specified on the command line or in the file identified by the -f option. 


Note the following:





 Examples




The following command deletes the entries specified in an LDIF file to the directory. The command does the following:



The following command deletes the single entry specified on the command line. The command does the following:






 ldapmodify




ldapmodify modifies one or more entries in the directory. 




 Syntax





ldapmodify [-h <host>] [-p <port>] [-D <binddn>] [-w <password>] 
   [-f <ldiffile>] [-e <rejectedfile>] [-O <maxhops>] 
   [-Z -P <certdbpath>] [-bcFHnRv]

The options for this command are described below. For convenience, commonly used options are listed first. The rest of the options are listed in alphabetical order. 





-h <host>

Specifies the name of the host on which the LDAP server is running. 
If you do not specify this option, localhost is used. 



-p <port>

Specifies the port on which the LDAP server is running.
If you do not specify this option, either 389 (if the LDAP server not using SSL) or 636 (if the LDAP server is using SSL and if you specify the Z option) are used. 



-D <binddn>

Specifies the distinguished name that you want to authenticate as. This DN must have access privileges to add entries to the directory. 
If you do not specify this option, anonymous authentication is used. 



-w <password>

Specifies the password for the DN that you want to authenticate as.
If you do not specify this option, no password is used. 



-f <ldiffile>

Specifies the file containing the changes to be made to the directory. These changes must be specified as LDIF update statements (see "Using LDIF to Update Entries" for details). 
If you do not specify this option, you will need to use standard input to specify the changes to make. (In other words, you will need to enter the LDIF update statements on the command line.)



-b 

Specifies that if an attribute value starts with a slash ("/"), that value is a pathname to a file that contains the actual value. For example, suppose you specify the following attribute and value:

jpegPhoto: /tmp/photo.jpeg



This utility interprets this line to mean "the value of the jpegPhoto attribute is found in the file /tmp/photo.jpeg".
If you do not specify this option in the example above, the utility assumes that the value you've specified is the actual value to be assigned to the attribute. 



-c 

Runs this utility in continuous operation mode. If errors occur, the utility will report the errors and continue running.
If you do not specify this option, this utility will exit when encountering an error.



-e <rejectfile>

Specifies a file in which to log any entries that could not be modified. If this utility is not able to add the entry to the directory, the utility writes the error message and the entry to this file.



-F

Legacy option. Not currently supported.



-H

Displays help on this utility.



-n

Lets you preview what would happen if you modified the entries, but does not actually modify the entries. 



-O <maxhops>

Specifies the maximum number of referrals in a sequence that this utility should follow. 
For example, suppose you set this maximum to 1 referral. If LDAP server A refers the utility to LDAP server B, and LDAP server B refers the utility to LDAP server C, the utility will not follow the referral to server C. (This is the second referral in a sequence, which exceeds to maximum of 1 referral.)
By default, the utility stops following referrals after 5 referrals in a row. 



-P <certdbfile>

Specifies the path to the certificate database for this utility (for example, ~/.netscape/cert5.db). Use this option if you are connecting to an LDAP server over SSL and if you have specified the -Z option.



-R

Prevents this utility from automatically following referrals. 



-v

Runs this utility in verbose mode. 



-Z

Specifies that this utility connects to the LDAP server using SSL. Use this option if you are connecting to a secure LDAP server. 



 




 Description




The ldapmodify utility opens a connection to the LDAP server specified by the -h and -p options, authenticates as the user specified by the -D and -w options, and makes the changes that are either specified by the LDIF update statements on the command line or in the file identified by the -f option. 


Note the following:





 Examples




The following command modifies the entries specified by LDIF update statements in an LDIF file. The command does the following:






 ldapmodrdn




ldapmodrdn modifies the relative distinguished name (RDN) of one or more entries in the directory. 




 Syntax





ldapmodrdn [-h <host>] [-p <port>] [-D <binddn>] [-w <password>] 
   [-f <ldiffile>] [-e <rejectedfile>] [-O <maxhops>] 
   [-Z -P <certdbpath>] [-cFHnrRv]

The options for this command are described below. For convenience, commonly used options are listed first. The rest of the options are listed in alphabetical order. 





-h <host>

Specifies the name of the host on which the LDAP server is running. 
If you do not specify this option, localhost is used. 



-p <port>

Specifies the port on which the LDAP server is running.
If you do not specify this option, either 389 (if the LDAP server not using SSL) or 636 (if the LDAP server is using SSL and if you specify the Z option) are used. 



-D <binddn>

Specifies the distinguished name that you want to authenticate as. This DN must have access privileges to add entries to the directory. 
If you do not specify this option, anonymous authentication is used. 



-w <password>

Specifies the password for the DN that you want to authenticate as.
If you do not specify this option, no password is used. 



-f <ldiffile>

Specifies the file containing the changes to be made to the RDNs of entries in the directory. These changes must be specified as LDIF update statements (see "Using LDIF to Update Entries" for details). For example: 

   dn: cn=Barry Nixon, o=Ace Industry, c=US 
   changetype: modrdn
   newrdn: cn=Barney Nixon
   deleteoldrdn: 0


If you do not specify this option, you will need to use standard input to specify the changes to make. (In other words, you will need to enter the LDIF update statements on the command line.)



-r

Specifies that the old RDN should be removed from the entry. 
If you do not specify this option, the old RDN is kept as an attribute of the entry. 



-c 

Runs this utility in continuous operation mode. If errors occur, the utility will report the errors and continue running.
If you do not specify this option, this utility will exit when encountering an error.



-F

Legacy option. Not currently supported.



-H

Displays help on this utility.



-n

Lets you preview what would happen if you modified the RDNs of the entries, but does not actually modify the RDNs. 



-O <maxhops>

Specifies the maximum number of referrals in a sequence that this utility should follow. 
For example, suppose you set this maximum to 1 referral. If LDAP server A refers the utility to LDAP server B, and LDAP server B refers the utility to LDAP server C, the utility will not follow the referral to server C. (This is the second referral in a sequence, which exceeds to maximum of 1 referral.)
By default, the utility stops following referrals after 5 referrals in a row. 



-P <certdbfile>

Specifies the path to the certificate database for this utility (for example, ~/.netscape/cert5.db). Use this option if you are connecting to an LDAP server over SSL and if you have specified the -Z option.



-R

Prevents this utility from automatically following referrals. 



-v

Runs this utility in verbose mode. 



-Z

Specifies that this utility connects to the LDAP server using SSL. Use this option if you are connecting to a secure LDAP server. 



 




 Description




The ldapmodrdn utility opens a connection to the LDAP server specified by the -h and -p options, authenticates as the user specified by the -D and -w options, and changes the RDNs of entries specified either on the command line or in the file identified by the -f option. 


Note the following:





 Examples




The following command modifies the RDNs of entries specified by LDIF update statements in an LDIF file. The command does the following:






 ldapsearch




ldapsearch searches for entries in the directory that match some specified search criteria.




 Syntax





ldapsearch [-h <host>] [-p <port>] [-D <binddn>] [-w <password>]
   -b <basedn> [-s <scope>] [-f <filterfile> | <filter ] [<attributes>] [-S <sortby>] [-a <deref>] [-F <sep>] [-O <maxhops>] [-Z -P <certdbpath>] [-ABHnoRtuv]

The options for this command are described below. For convenience, commonly used options are listed first. The rest of the options are listed in alphabetical order. 





-h <host>

Specifies the name of the host on which the LDAP server is running. 
If you do not specify this option, localhost is used. 



-p <port>

Specifies the port on which the LDAP server is running.
If you do not specify this option, either 389 (if the LDAP server not using SSL) or 636 (if the LDAP server is using SSL and if you specify the Z option) are used. 



-D <binddn>

Specifies the distinguished name that you want to authenticate as. This DN must have access privileges to add entries to the directory. 
If you do not specify this option, anonymous authentication is used. 



-w <password>

Specifies the password for the DN that you want to authenticate as.
If you do not specify this option, no password is used. 



-b <basedn>

Specifies the base location in the directory from which the search will start.
The value specified here must be a distinguished name that currently exists in the database. This parameter is optional if the LDAP_BASEDN environment variable has been set to a base DN. The value specified in this parameter should be provided in double quotation marks. For example:

-b "cn=Barbara Jensen, ou=Product Development, o=Ace Industry, c=US"




-s <scope> 

Specifies the scope of the search. The scope can be one of the following:



-f <filterfile>

Specifies the file containing the search filters to use. For details on search filters, see Chapter 5, "Using Filter Configuration Files."



<filter>

Specifies the search filter. For details on search filters, see Chapter 5, "Using Filter Configuration Files."



<attributes>

Specifies the attributes that you want returned in the search results.



-S <sortby> 

Sorts the search results by the specified attribute <sortby>. The default is not to sort the returned entries. If the attribute is the zero-length string (""), the entries will be sorted by their distinguished name.



-a <deref> 

Specifies the method used for dereferencing aliases. Value can be "never," "always," "search," or "find." Default value is "never."



-A

Retrieves attribute names only (rather than the values of attributes) in the search.



-B

Prints non-ASCII values in search results, even if the old format (-o) is used.



-F <sep> 

Uses <sep> as the separator between attribute name and value when printing the search results. For example, if you specify -F :, the results are printed in the form name:value.
If you do not specify this option, an equals sign (=) is used.



-H

Displays help on this utility.



-l

Specifies the maximum number of seconds to wait for the search to complete.



-n

Lets you preview what would happen if you performed the search, but does not actually perform the search. 



-o

Prints search results in old format.
If you do not specify this option, the utility prints the results in LDIF format.



-O <maxhops>

Specifies the maximum number of referrals in a sequence that this utility should follow. 
For example, suppose you set this maximum to 1 referral. If LDAP server A refers the utility to LDAP server B, and LDAP server B refers the utility to LDAP server C, the utility will not follow the referral to server C. (This is the second referral in a sequence, which exceeds to maximum of 1 referral.)
By default, the utility stops following referrals after 5 referrals in a row. 



-P <certdbfile>

Specifies the path to the certificate database for this utility (for example, ~/.netscape/cert5.db). Use this option if you are connecting to an LDAP server over SSL and if you have specified the -Z option.



-R

Prevents this utility from automatically following referrals. 



-t

Writes values to files in the temporary directory (/tmp or C:\temp). 



-u

Includes user-friendly entry names in the output.



-v

Runs this utility in verbose mode. 



-z

Specifies the maximum number of entries to return. 



-Z

Specifies that this utility connects to the LDAP server using SSL. Use this option if you are connecting to a secure LDAP server. 



 




 Description




The ldapsearch utility opens a connection to the LDAP server specified by the -h and -p options, authenticates as the user specified by the -D and -w options, and searches for the entries under the base entry (specified by the -b option) within a given scope (specified by the -s option) that match the filter.


Note the following:





 Examples




The following command searches for entries under the "o=Netscape Communications Corporation,c=US" subtree that match the filter "(sn=Jensen)". The command does the following:








[Previous] [Next] [TOC] [Index]

Last modified: March 31, 1997

Copyright © 1997 Netscape
Communications Corporation