8.4. Examples of Common ldapsearches

The next set of examples assumes the following:
  • The search is for all entries in the directory.
  • The directory is configured to support anonymous access for search and read. This means that no bind information has to be supplied in order to perform the search. For more information on anonymous access, see Section 12.4.2, “Defining User Access - userdn Keyword”.
  • The server is located on a host named server.example.com.
  • The server uses port number 389. Since this is the default port, the port number does not have to be sent in the search request.
  • SSL is enabled for the server on port 636 (the default SSL port number).
  • The suffix under which all data are stored is dc=example,dc=com.

8.4.1. Returning All Entries

Given the previous information, the following call will return all entries in the directory (subject to the configured size and time resource limits):
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "dc=example,dc=com" -s sub "(objectclass=*)"
"objectclass=*" is a search filter that matches any entry in the directory. Since every entry must have an object class, and the objectclass attribute is always indexed, this is a useful search filter to return every entry.

8.4.2. Specifying Search Filters on the Command Line

A search filter can be specified directly on the command line as long as the filter is enclosed in quotation marks ("filter"). If the filter is supplied with the command, do not specify the -f option. For example:
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "dc=example,dc=com" -s sub "cn=babs jensen"

8.4.3. Searching the Root DSE Entry

The root DSE is a special entry that contains a list of all the suffixes supported by the local Directory Server. This entry can be searched by supplying a search base of "", a search scope of base, and a filter of "objectclass=*". For example:
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "" -s base "objectclass=*"

8.4.4. Searching the Schema Entry

Directory Server stores all directory server schema in the special cn=schema entry. This entry contains information on every object class and attribute defined for the Directory Server. The following command searches the contents of the cn=schema entry:
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "cn=schema" -s base "objectclass=*"

8.4.5. Using LDAP_BASEDN

To make searching easier, it is possible to set the search base using the LDAP_BASEDN environment variable. Doing this means that the search base does not have to be set with the -b option. For information on how to set environment variables, see the documentation for the operating system.
Typically, set LDAP_BASEDN to the directory's suffix value. Since the directory suffix is equal to the root, or topmost, entry in the directory, this causes all searches to begin from the directory's root entry.
For example, set LDAP_BASEDN to dc=example,dc=com and search for cn=babs jensen in the directory, use the following command-line call:
export LDAP_BASEDN="dc=example,dc=com"

/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com "cn=babs jensen"
In this example, the default scope of sub is used because the -s option was not used to specify the scope.

8.4.6. Displaying Subsets of Attributes

The ldapsearch command returns all search results in LDIF format. By default, ldapsearch returns the entry's distinguished name and all of the attributes that a user is allowed to read. The directory access control can be set such that users are allowed to read only a subset of the attributes on any given directory entry. Only operational attributes are not returned. For operational attributes to be returned as a result of a search operation, explicitly specify them in the search command.
It may not be necessary to have all of the attributes for an entry returned in the search results. The returned attributes can be limited to just a few specific attributes by specifying the desired ones on the command line immediately after the search filter. For example, to show the cn and sn attributes for every entry in the directory, use the following command-line call:
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "dc=example,dc=com" -s sub "(objectclass=*)" sn cn

8.4.7. Searching for Operational Attributes

Operational attributes are special attributes set by the Directory Server itself that are used by the server to perform maintenance tasks, like processing access control instructions. They also show specific information about the entry, like the time it was initially created and the name of the user who created it. Operational attributes are available for use on every entry in the directory, regardless of whether the attribute is specifically defined for the object class of the entry.
Operational attributes are not returned in regular ldapsearches, so to return operational attributes, they have to be explicitly specified in the ldapsearch request.
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "dc=example,dc=com" -s sub "(objectclass=*)" creatorsName createTimestamp modifiersName modifyTimestamp
The complete list of operational attributes is in the "Operational Attributes and Object Classes" chapter in the Schema Reference

8.4.8. Specifying Search Filters Using a File

Search filters can be entered into a file instead of entering them on the command line. In this case, specify each search filter on a separate line in the file. The ldapsearch command runs each search in the order in which it appears in the file.
For example:
sn=Francis
givenname=Richard
ldapsearch first finds all the entries with the surname Francis, then all the entries with the givenname Richard. If an entry is found that matches both search criteria, then the entry is returned twice.
For example, in this search, the filters are specified in a file named searchdb:
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -f searchdb
The set of attributes returned here can be limited by specifying the attribute names at the end of the search line. For example, the following ldapsearch command performs both searches but returns only the DN and the givenname and sn attributes of each entry:
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -f searchdb sn givenname

8.4.9. Specifying DNs That Contain Commas in Search Filters

When a DN within a search filter contains a comma as part of its value, the comma must be escaped with a backslash (\). For example, to find everyone in the example.com Bolivia, S.A. subtree, use the following command:
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -s base -b "l=Bolivia\,S.A.,dc=example,dc=com" "objectclass=*"

8.4.10. Using Client Authentication When Searching

Client authentication uses a stored certificate to bind to the directory rather than simple username-password. This example shows user bjensen searching the directory using client authentication:
/usr/lib64/mozldap/ldapsearch -h server.example.com -p 636 -b "dc=example,dc=com" -N "bjensenscertname" -Z -W certdbpassword -P /home/bjensen/certdb/cert8.db "givenname=Richard"

8.4.11. Searching with Specified Controls

The Directory Server has defined controls in its supportedControls attribute in its DSE. Some of these define server operations like replication; other are allowed extended operations like get effective rights or dereferencing controls which clients can pass through LDAP operations to the server. These controls can be specified using the -J option by giving the control OID, its criticality for the ldapsearch, and any information required for the control operation.
-J control_OID:boolean criticality:control_information
This option is used, for example, for Get effective rights searches:
/usr/lib64/mozldap/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "dc=example,dc=com" -s sub -J 1.3.6.1.4.1.42.2.27.9.5.2:true:dn:uid=jsmith,ou=people,dc=example,dc=com "(objectclass=*)"
Get effective rights searches are covered in much more detail in the access control chapter, Section 12.7, “Checking Access Rights on Entries (Get Effective Rights)”.

8.4.12. Searching with Language Matching Rules

To explicitly submit a matching rule in a search filter, insert the matching rule after the attribute:
attr:matchingRule:=value
Matching rules are frequently used for searching internationalized directories. For example, this seearches for the department numbers after N4709 in the Swedish (2.16.840.1.113730.3.3.2.46.1) matching rule.
departmentNumber:2.16.840.1.113730.3.3.2.46.1:=>= N4709
More examples of performing internaionalized searches are given in Section C.4, “Searching an Internationalized Directory”.

8.4.13. Searching for Attributes with Bit Field Values

Bitwise searches use the bitwise AND or bitwise OR matching rules to perform bitwise search operaions on attributes with values that are bit fields.

NOTE

Attributes with values for bit fields aren't common in LDAP. (No default Directory Server schema use bit fields as attribute syntax.) However, several LDAP syntaxes support interger-style values. Custom attributes can be defined which use bit field values, and applications can use those custom attributes to perform bitwise operations against bit field values.
The bitwise AND matching rule (1.2.840.113556.1.4.803) checks that the bit given in the assertion value is set in the bit field attribute value. (This is somewhat analogous to an equality search.) In this example, the userAccountControl value must be set to the bit representing 2.
"(UserAccountControl:1.2.840.113556.1.4.803:=2)"
In this example, the userAccountControl value must have all of the bits set that are set in the value 6 (bits 2 and 4).
"(UserAccountControl:1.2.840.113556.1.4.803:=6)”
The bitwise OR matching rule (1.2.840.113556.1.4.804) checks to see if any of the bits in the assertion string are represented in the attribute value. (This is somewhat analogous to a substring search.) In this example, the userAccountControl value must have any of the bits which are set in the bit field of 6, meaning that the attribute value can be 2, 4, or 6.
"(UserAccountControl:1.2.840.113556.1.4.804:=6)"
Bitwise searches can be used with Windows-Red Hat Enterprise Linux integration, such as using Samba file servers.

NOTE

Microsoft has good documentation on bitwise operators at http://msdn.microsoft.com/en-us/library/aa746475.