Search

Chapter 1. Finding entries using the command line (ldapsearch)

download PDF

You can use the ldapsearch command-line utility to search for directory entries. This utility opens a connection to a specified server using the specified identity and credentials and locates entries based on a specified search filter. The search scope can include:

  • a single entry (-s base)
  • an entry immediate subentries (-s one)
  • an entire tree or subtree (-s sub)
Note

The ldapsearch utility does not search for directory entries based on attributes in the distinguished name. The distinguished name is only a unique identifier for a directory entry and cannot be used as a search key. Instead, ldapsearch searches for entries based on the attribute value pairs stored in entries. If the distinguished name of an entry is, for example, uid=bjensen,ou=People,dc=example,dc=com, then a search for dc=example does not match that entry unless dc:example was explicitly added as an attribute value pair to this entry.

The ldapsearch utility returns results in the LDIF format that is defined in the RFC 2849 specification.

1.1. The ldapsearch command format

The ldapsearch command must use the following format:

# ldapsearch [-x | -Y mechanism] [options] [search_filter] [list_of_attributes]
  • -x or -Y

    Use -x (simple binds) or -Y (SASL mechanism) to configure the type of the connection.

  • options

    The ldapsearch command-line options. Specify the options before the search filter, if any are used.

  • search_filter

    An LDAP search filter. Do not specify a search filter if you configure search filters in a file using the -f option.

  • list_of_attributes

    A list of attributes separated by a space character. Specifying the list of attributes reduces the number of attributes returned in the search results. This list of attributes must appear after the search filter. If you do not specify the list of attributes, the search returns values for all attributes permitted by the access control set in the directory with the exception of operational attributes.

    If you want the search to return operational attributes, you must explicitly specify it in the ldapsearch search command. To return all operational attributes of an object use +. To retrieve regular attributes in addition to explicitly specified operational attributes, use an asterisk (*) in the list of attributes.

    Note that you might need to escape the asterisk character with a backslash (\*).

    To retrieve only a list of matching DNs, use the attribute 1.1. For example:

    # ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com \
        -b "dc=example,dc=com" -x "(objectclass=inetorgperson)" 1.1

1.2. Commonly used ldapsearch options

The following table lists the most commonly used ldapsearch utility options. If a specified value contains a space character, the value must be surrounded by single or double quotation marks, for example:

-b "cn=My Special Group,ou=groups,dc=example,dc=com"

Important

The ldapsearch utility from OpenLDAP uses SASL connections by default. To perform a simple bind or to use TLS, use the -x argument to disable SASL and allow other connection methods.

OptionDescription

-b

Specifies the starting point for the search - base Distinguished Name (DN). Note that distinguished name must exist in the database. If you set the LDAP_BASEDN environment variable as a base DN, you do not need to use this option.
You must specify the option value in single or double quotation marks if the value contains a space character. For example:
-b "cn=user,ou=Product Development,dc=example,dc=com".
To search the root DSE entry, specify an empty string here, such as -b "" .

-D

Specifies the DN used to authenticate to the server. Directory Server must recognize the DN value, and the DN must have the authority to search for the entries. For example:
-D "uid=user_name,dc=example,dc=com".
Do not specify this option if the server supports anonymous access.

-H

Specifies an LDAP URL to connect to the server. An LDAP URL has the following format:

ldap[s]://hostname:[port]

Specifying the port value is optional. The ldapsearch utility will then use the default LDAP port 389 or LDAPS port 636.

The utility can also use an LDAPI URL with each element separated by the HTML hex code %2F instead of a forward slash (/). For example:

ldapi://%2Ffull%2Fpath%2Fto%2Fslapd-example.socket

For LDAPI, specify the full path to the file which represents the LDAPI socket the server is listening to. If you did not specify the URL, ldapsearch uses the localhost or the setting specified in the /etc/openldap/ldap.conf file.

-h

Specifies the hostname or IP address of the machine with installed Directory Server. For example, -h server.example.com. If you did not specify a host, ldapsearch uses the localhost. Directory Server supports both IPv4 and IPv6 addresses.

Note

The -h option is deprecated and will be removed in a future release. Use the -H option instead.

-p

Specifies the TCP port number used by Directory Server. For example, -p 1049. The default port number is 389.

Note

The -p option is deprecated and will be removed in a future release.

-l

Specifies the maximum time limit in seconds for a search request to complete. For example, -l 300. The time limit should not exceed the value specified in the nsslapd-timelimit attribute, because ldapsearch utility compares these two values and uses the smallest one. The default nsslapd-timelimit attribute value is 3600 seconds.

-s scope

Specifies the scope of the search. You can choose one of the following scopes:

  • sub
    Searches through the entry specified in the -b option and all of its descendants entries. This is a default setting.
  • one
    Searches through the immediate children of the entry specified in the -b option. The ldapsearch utility considers only children, not the base DN itself.
  • base
    Searches only through the entry specified in the -b option or defined by the LDAP_BASEDN environment variable.

-W

Prompts for the password. if you did not specify the option, the ldapsearch utility uses anonymous access. Alternatively, use the -w option to pass the password to the utility.

Note

The password can be visible in the process list for other users and is saved in the shell’s history.

-x

Disables the default SASL connection to allow simple binds.

-Y SASL_mechanism

Sets the SASL mechanism to use for authentication. If you do not set any mechanism, ldapsearch selects the best mechanism supported by the server. If you do not use the -x option, you must specify the -Y option instead.

-z number

Sets the maximum number of entries to return in a response to a search request. This value overwrites the nsslapd-sizelimit attribute when binding using the root DN.

-f

Specifies a file with search filters.

1.3. Using special characters

When using the ldapsearch utility, you might need to specify values with characters that have special meaning to the command-line interpreter, such as space character, asterisk (*), or backslash (\). Depending on the command-line interpreter, enclose the value that has the special character either in single (' ') or double (" ") quotation marks. For example:

-D "cn=John Smith,ou=Product Development,dc=example,dc=com"

In general, use single quotation marks (' ') to enclose values. Use double quotation marks (" ") to allow variable interpolation if there are shell variables.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.