6.4. ldapsearch

6.4. ldapsearch

ldapsearch is a configurable utility that locates and retrieves directory entries via LDAP. This utility opens a connection to the specified server using the specified distinguished name and password and locates entries based on a specified search filter. Search scopes can include a single entry, an entry's immediate subentries, or an entire tree or subtree. Search results are returned in LDIF format.

Syntax

ldapsearch [ -b basedn ] [ optional_options ] [ filter ] [ optional_list_of_attributes ]

For any value that contains a space ( ), the value should be enclosed in double quotation marks. For example: 

-b "ou=groups, dc=example,dc=com"
Option Description
optional_options A series of command-line options. These must be specified before the search filter, if used.
filter An LDAP search filter as described in Directory Server Administration Guide. Do not specify a search filter if search filters are supplied in a file using the -f option.
optional_list_of_attributes A list of space-separated attributes that reduce the scope of the attributes returned in the search results. This list of attributes must appear after the search filter. For a usage example, see the Directory Server Administration Guide. If a list of attributes is not specified, the search returns values for all attributes permitted by the access control set in the directory with the exception of operational attributes.
Table 6.2. ldapsearch Syntax

To return operational attributes as a result of a search operation, they must be explicitly specified in the search command. To retrieve regular attributes along with explicitly-specified operational attributes, specify an asterisk (*) in addition to the operational attributes.

Commonly-Used ldapsearch Options

The following table lists the most commonly used ldapsearch command-line options.

Option Description
-b

Specifies the starting point for the search. The value specified here must be a distinguished name that currently exists in the database. This option is optional if the LDAP_BASEDN environment variable has been set to a base DN.

The value specified in this option should be provided in double quotation marks. For example: 

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

The root DSE entry is a special entry that contains a list of all the suffixes supported by the local directory. To search this entry, supply a search base of "", a search scope of base, and a filter of "objectclass=*". For example: 

-b "" -s base "objectclass=*"
-D Specifies the distinguished name with which to authenticate to the server. This option is optional if anonymous access is supported by the server. If specified, this value must be a DN recognized by the Directory Server, and it must also have the authority to search for the entries. For example: 
-D "uid=bjensen, dc=example,dc=com"
-g

Specifies that the password policy request control not be sent with the bind request. By default, the new LDAP password policy request control is sent with bind requests.

The ldapsearch tool can parse and display information from the response control if it is returned by a server; that is, the tool will print an appropriate error or warning message when a server sends the password policy response control with the appropriate value.

The criticality of the request control is set to false to ensure that all LDAPv3 servers that do not understand the control can ignore it. To suppress sending of the request control with the bind request, include -g on the command-line.

-h Specifies the hostname or IP address of the machine on which the Directory Server is installed. If a host is not specified, ldapsearch uses the local host. For example: 
-h mozilla
-l

Specifies the maximum number of seconds to wait for a search request to complete. For example: 

-l 300

Regardless of the value specified here, ldapsearch will never wait longer than is allowed by the server's nsslapd-timelimit attribute, unless the authenticated user is the Directory Manager. The default value for the nsslapd-timelimit attribute is 3600 seconds. See Section 2.3.1.95, “nsslapd-timelimit (Time Limit)” for more information.

-p Specifies the TCP port number that the Directory Server uses. For example: 
-p 1049
The default is 389. If -Z is used, the default is 636.
-s

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

  • base searches only the entry specified in the -b option or defined by the LDAP_BASEDN environment variable.

  • one searches only the immediate children of the entry specified in the -b option. Only the children are searched; the actual entry specified in the -b option is not searched.

  • sub searches the entry specified in the -b option and all of its descendants. That is, perform a subtree search starting at the point identified in the -b option. This is the default.

-w

Specifies the password associated with the distinguished name that is specified in the -D option. For example: 

-w diner892

If this option is not specified, anonymous access is used.

If a dash (-) is used as the password value, the utility prompts for the password after the command is entered. This avoids having the password on the command line.

-x Specifies that the search results are sorted on the server rather than on the client. This is useful to sort according to a matching rule, as with an international search. In general, it is faster to sort on the server rather than on the client.
-z

Specifies the maximum number of entries to return in response to a search request. For example: 

-z 1000

Normally, regardless of the value specified here, ldapsearch never returns more entries than the number allowed by the server's nsslapd-sizelimit attribute, unless the authenticated user is the Directory Manager. However, this limitation can be overridden by binding as the root DN when using this command-line argument. This is because binding as the root DN causes this option to default to zero (0). The default value for the nsslapd-sizelimit attribute is 2000 entries. See Section 2.3.1.92, “nsslapd-sizelimit (Size Limit)” for more information.

Table 6.3. Commonly-Used ldapsearch Options

SSL Options

The following command-line options can be used to specify that ldapsearch use LDAPS when communicating with an SSL-enabled Directory Server or used for certificate-based authentication. These options are valid only when LDAPS has been turned on and configured for the Directory Server. For information on certificate-based authentication and creating a certificate database for use with LDAP clients, see the "Managing SSL" chapter in the Directory Server Administration Guide.

In addition to the standard ldapsearch options, to run an ldapsearch command using SSL, specify the following:

ldapsearch { -Z, -ZZ, -ZZZ } [ -p secure_port ] [ -P certificate_database ] [ -N certificate_name ] [ -K key_database ] [ -W key database password ]

NOTE

To run ldapsearch over TLS/SSL, either the -Z option is required (for SSL) or the -ZZ or -ZZZ option is required (for Start TLS).

Option

Description

-3 Specifies that hostnames should be checked in SSL certificates.
-I Specifies the SSL key password file that contains the token:password pair.
-K

Specifies the absolute path, including the filename, of the private key database of the client.

The -K option must be specified when the key database has a different name than key3.db or when the key database is not under the same directory as the certificate database, the cert8.db file (the path which is specified with the -P option).

-m Specifies the path to the security module database, such as /etc/dirsrv/slapd-instance_name/secmod.db. This option only need to be given if the security module database is in a different directory than the certificate database itself.
-N Specifies the certificate name to use for certificate-based client authentication, such as -N "Server-Cert". If this option is specified, then the -Z, -P, and -W options are required. Also, if this option is specified, then the -D and -w options 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.
-P

Specifies the absolute path, including the option, of the certificate database of the client. This option is used only with the -Z option.

When used on a machine where an SSL-enabled web browser is configured, the path specified on this option can be that of the certificate database for the browser. For example: 

-P /security/cert.db

The client security files can also be stored on the Directory Server in the /etc/dirsrv/slapd-instance_name directory. In this case, the -P option would call out a path and filename similar to the following: 

-P /etc/dirsrv/slapd-instance_name/client-cert.db
-Q Specifies the token and certificate name, which is separated by a semi-colon (:) for PKCS11.
-W Specifies the password for the private key database identified in the -P option. For example: 
-W serverpassword
If a dash (-) is used as the password value, the utility promptes for the password after the command is entered. This avoids having the password on the command line.
-Z Specifies that SSL is to be used for the search request.
-ZZ Specifies the Start TLS request. Use this option to make a cleartext connection into a secure one. If the server does not support Start TLS, the command does not have to be aborted; it will continue in cleartext.
-ZZZ Enforces the Start TLS request. The server must respond that the request was successful. If the server does not support Start TLS, such as Start TLS is not enabled or the certificate information is incorrect, the command is aborted immediately.
Table 6.4. Additional SSL ldapsearch Options

SASL Options

SASL mechanisms can be used to authenticate a user, using the -o the required SASL information.

To learn which SASL mechanisms are supported, search the root DSE. See the -b option in Table 6.3, “Commonly-Used ldapsearch Options”.

Option Description
-o Specifies SASL options. The format is -o saslOption=value. saslOption can have one of six values:

  • mech

  • authid

  • authzid

  • secProp

  • realm

  • flags

The expected values depend on the supported mechanism. The -o can be used multiple times to pass all of the required SASL information for the mechanism. For example: 
-o "mech=DIGEST-MD5" -o "authzid=test_user" -o "authid=test_user"
Table 6.5. SASL Options

There are three SASL mechanisms supported in Red Hat Directory Server:

Required or Optional Option Description Example
Required mech=CRAM-MD5 Gives the SASL mechanism. -o “mech=CRAM-MD5”
Required authid=authid_value Gives the ID used to authenticate to the server. authid_value can be the following:

  • UID. For example, msmith.

  • u: uid. For example, u: msmith.

  • dn: dn_value. For example, dn: uid=msmith,ou=People,o=example.com.

-o “authid=dn:uid=msmith,ou=People,o=example.com"
Optional secprop=value The secprop attribute sets the security properties for the connection. The secprop value can be any of the following:

  • None

  • noplain — Do not permit mechanisms susceptible to simple passive attack.

  • noactive — Do not permit mechanisms susceptible to active attacks.

  • nodict — Do not permit mechanisms susceptible to passive dictionary attacks.

  • forwardsec — Require forward secrecy.

  • passcred — Attempt to pass client credentials.

  • noanonymous — Do not permit mechanisms that allow anonymous access.

  • minssf — Require a minimum security strength; this option needs a numeric value specifying bits of encryption. A value of - 1 means integrity is provided without privacy.

  • maxssf — Require a maximum security strength; this option needs a numeric value specifying bits of encryption. A value of - 1 means integrity is provided without privacy.

  • maxbufsize — Set the maximum receive buffer size the client will accept when using integrity or privacy settings.

-o "secprop=noplain,minssf=1,maxbufsize=512"
Table 6.6. Description of CRAM-MD5 Mechanism Options

Required or Optional Option Description Example
Required mech=DIGEST-MD5 Gives the SASL mechanism. -o “mech=DIGEST-MD5”
Required authid=authid_value Gives the ID used to authenticate to the server. authid_value can be the following:

  • UID. For example, msmith.

  • u: uid. For example, u: msmith.

  • dn: dn_value. For example, dn: uid=msmith,ou=People,o=example.com.

-o “authid=dn:uid=msmith,ou=People,o=example.com"
Optional secprop=value The secprop attribute sets the security properties for the connection. The secprop value can be any of the following:

  • None

  • noplain — Do not permit mechanisms susceptible to simple passive attack.

  • noanonymous — Do not permit mechanisms that allow anonymous access.

  • minssf — Require a minimum security strength; this option needs a numeric value specifying bits of encryption. A value of - 1 means integrity is provided without privacy.

  • maxssf — Require a maximum security strength; this option needs a numeric value specifying bits of encryption. A value of - 1 means integrity is provided without privacy. The maximum value is 128.

-o “secprop=noplain,noanonymous, maxssf=128,minssf=128”
Table 6.7. Description of DIGEST-MD5 SASL Mechanism Options

Required or Optional Option Description Example
Required mech=GSSAPI Gives the SASL mechanism.

NOTE

Have the Kerberos ticket before issuing a GSS-API request.

-o “mech=GSSAPI”
Optional secprop=value The secprop attribute sets the security properties for the connection. The secprop value can be any of the following:

  • None

  • noplain — Do not permit mechanisms susceptible to simple passive attack.

  • noanonymous — Do not permit mechanisms that allow anonymous access.

  • minssf — Require a minimum security strength; this option needs a numeric value specifying bits of encryption. A value of - 1 means integrity is provided without privacy.

  • maxssf — Require a maximum security strength; this option needs a numeric value specifying bits of encryption. A value of - 1 means integrity is provided without privacy. The maximum value is 56.

-o “secprop=noplain,noanonymous, maxssf=56,minssf=56”
Table 6.8. Description of GSSAPI SASL Mechanism Options

Additional ldapsearch Options

Option Description
-A Specifies that the search retrieve the attributes only, not the attribute values. This option is useful to determine if an attribute is present for an entry and the value is not important.
-a Specifies how alias dereferencing is completed. Values can be never, always, search, or find. The default value is never.
-B Print non-ASCII values using the old output format (attrName=attrValue).
-c Specifies the getEffectiveRights control authzid. For example: 
dn:uid=bjensen,dc=example,dc=com
A value of "" means the authorization ID for the operation. A value of dn: means anonymous
-F Specifies a different separator. This option allows a separator other than a colon (:) to separate an attribute name from the corresponding value. For example: 
-F +
-f

Specifies the file containing the search filters to be used in the search. For example: 

-f search_filters

option to supply a search filter directly to the command line.

For more information about search filters, see Appendix B, "Finding Directory Entries", in the Directory Server Administration Guide.

-G

Conducts a virtual list view search. This option can set the number of entries before or after the search target and the index or value of the first entry returned.

For example, a value operation that sorts by surname, -G 20:30:johnson, returns the first entry with a surname equal to or less than johnson, in addition to 20 entries that come before it and 30 entries that come after it. If there are fewer matching entries in the directory than the before or after number requested by the search, all available entries before/after the search target that match the search criteria are returned.

An index operation which sorts by surname, -G 20:30:100:0, returns from the 80th through 130th entries sorted by sn. Use 0 as the fourth value for the count number unless you know how many entries the VLV index has.

-i

Specifies the characterset to use for command-line input. The default is the characterset specified in the LANG environment variable. Use this option to perform the conversion from the specified characterset to UTF8, thus overriding the environment variable setting.

This argument can input the bind DN, base DN, and the search filter pattern in the specified characterset.

ldapsearch converts the input from these arguments before it processes the search request. For example, -i no indicates that the bind DN, base DN, and search filter are provided in Norwegian. This argument only affects the command-line input; that is, if a file containing a search filter (with the -f option) is specified, ldapsearch will not convert the data in the file.

-J Send an arbitrary control. This option can be used in the following format to retrieve access control information on a specific entry: 
-J control OID:boolean criticality:dn:AuthID

  • control OID is the OID for the get effective rights control, 1.3.6.1.4.1.42.2.27.9.5.2.

  • boolean criticality specifies whether the search operation should return an error if the server does not support this control (true) or if it should be ignored and let the search return as normal (false).

  • AuthId is the DN of the user whose rights to check.

-k

Bypasses converting the password to UTF8.

-M Manages smart referrals. This causes the server not to return the smart referral contained on the entry but, instead, to return the actual entry containing the referral. Use this option to search for entries that contain smart referrals. For more information about smart referrals, see the "Configuring Directory Databases" chapter in the Directory Server Administration Guide.
-n Specifies that the search is not actually to be performed, but that ldapsearch is to show what it would do with the specified input.
-O Specifies the maximum number of referral hops ldapsearch should automatically follow. For example: 
-O 2
-R Specifies that referrals are not to be followed automatically. By default, referrals are followed automatically.
-S Specifies the attribute to use as the sort criteria. For example: 
-S sn
Use multiple -S arguments to further define the sort order. In the following example, the search results will be sorted first by surname and then by given name: 
-S sn -S givenname
The default is not to sort the returned entries.
-T Specifies that no line breaks should be used within individual values in the search results.
-t Specifies that the results be written to a set of temporary files. With this option, each attribute value is placed in a separate file within the system temporary directory. No base-64 encoding is performed on the values, regardless of the content.
-u Specifies that the user-friendly form of the distinguished name be used in the output.
-v Specifies that the utility is to run in verbose mode.
-V Specifies the LDAP version number to be used on the search. For example: 
-V 2
LDAPv3 is the default. An LDAPv3 search cannot be performed against a Directory Server that only supports LDAPv2.
-Y Specifies the proxy DN to use for the search. This argument is provided for testing purposes. For more information about proxied authorization, see the "Managing Access Control" chapter in the Directory Server Administration Guide.
-X Specifies the getEffectiveRights control specific attribute list, where attributes are separated by spaces. For example: 
"nsroledn userPassword"
Table 6.9. Additional ldapsearch Options


Note: This documentation is provided {and copyrighted} by Red Hat®, Inc. and is released via the Open Publication License. The copyright holder has added the further requirement that Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. The CentOS project redistributes these original works (in their unmodified form) as a reference for CentOS-5 because CentOS-5 is built from publicly available, open source SRPMS. The documentation is unmodified to be compliant with upstream distribution policy. Neither CentOS-5 nor the CentOS Project are in any way affiliated with or sponsored by Red Hat®, Inc.