Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition

Chapter 4 Directory Server LDIF and Search Filters

Directory Server uses the LDAP Data Interchange Format (LDIF) to describe a directory and its entries in text format. LDIF can be used to build the initial directory database or to add large numbers of entries to a directory. LDIF can also be used to describe changes to directory entries. Most command-line utilities rely on LDIF for input or output.

All directory data is stored by using the UTF-8 encoding of Unicode, and, therefore, LDIF files must also be UTF-8 encoded.

This chapter also provides information about searching the directory, and LDAP search filters.

For information about LDIF and searching the directory, see the following sections:

LDIF File Format

LDIF files consist of one or more directory entries separated by a blank line. Each LDIF entry consists of the following parts:

The LDIF format is defined in RFC 2849.

The following example shows a basic directory entry in LDIF.


Example 4–1 A Directory Entry in LDIF

dn: distinguished_name
objectClass: object_class
objectClass: object_class
...
attribute_type[;subtype]: attribute_value
attribute_type[;subtype]: attribute_value
...

All other attributes and object classes are optional. Object classes and attributes can be specified in any order. The space after the colon is optional.

The following table describes the fields in a LDIF file.

Table 4–1 LDIF Fields

Field  

Definition  

[id]

Optional. A 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

The distinguished name for the entry. 

objectClass: object_class

An object class to use with this entry. The object class identifies the types of attributes or schema that are allowed and required for the entry.  

attribute_type

A descriptive attribute to use with the entry. The attribute should be defined in the schema. 

[subtype]

Optional. A subtype of one of the following types: 

  • Language (attribute;lang-subtype) identifies the language in which the corresponding attribute value is expressed

  • Binary (attribute;binary) identifies whether the attribute value is binary

  • Pronunciation (attribute;phonetic) identifies whether the attribute value is a pronunciation of an attribute value

attribute_value

The attribute value to be used with the attribute type. 

The LDIF syntax for representing a change to an entry in the directory is different from the syntax described above.

Continuing Lines in LDIF

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

dn: cn=Babs Jensen,dc=example,dc=com

dn: cn=Babs J
 ensen,dc=exam
 ple,dc=com

You are not required to break and continue LDIF lines. However, doing so can improve the readability of an LDIF file.

Binary Data in LDIF

You can represent binary data in LDIF by using one of the following methods:

Representing Binary Data by Using Standard LDIF Notation

The following example gives the standard LDIF notation of binary data:

jpegphoto:< file:/path/to/photo

In the example, the path is relative to the client, not to the server. To use standard notation, you do not need to specify the ldapmodify -b parameter. However, you must add the following line to the beginning of your LDIF file or to your LDIF update statements:

version:1

For example, you could use the ldapmodify command, as follows:


$ ldapmodify -D userDN -w passwd
version: 1
dn: cn=Barbara Jensen,ou=People,dc=example,dc=com
changetype: modify
add: userCertificate
userCertificate;binary:< file:BabsCert

Representing Binary Data by Using the ldapmodify -b Command

For backward compatibility with earlier versions of Directory Server, binary data can be represented by using the ldapmodify -b command. However, when possible, use the standard LDIF notation to represent binary data.

Directory Server accepts the ldapmodify command with the -b parameter and the following LDIF notation:

jpegphoto: /path/to/photo

This notation indicates that the ldapmodify command should read the referenced file for binary values if the attribute value begins with a slash.

Representing Binary Data by Using Base 64 Encoding

Base 64 encoded data is represented by the :: symbol, as shown in this example:

jpegPhoto:: encoded_data

In addition to binary data, the following values must be base 64 encoded:

Use the ldif command with the -b parameter to convert binary data to LDIF format, as follows.


$ ldif -b attributeName

For more information about how to use the ldif command, see the ldif(1) man page.

In the above example, attributeName is the name of the attribute to which you are supplying the binary data. The binary data is read from standard input and the results are written to standard output. Use redirection operators to select input and output files.

The command takes any input and formats it with the correct line continuation and appropriate attribute information. The command also assesses whether the input requires base–64 encoding. The following example takes a binary file containing a JPEG image and converts it into LDIF format for the attribute named jpegPhoto. The output is saved to out.ldif:


$ ldif -b jpegPhoto < aphoto.jpg > out.ldif

The -b option specifies that the utility should interpret the entire input as a single binary value. If the -b option is not present, each line is considered as a separate input value.

You can edit the output file to add the LDIF statements required to create or modify the directory entry that will contain the binary value. For example, you can open the file out.ldif in a text editor and add the following lines at the top of the file.

dn: cn=Barbara Jensen,ou=People,dc=example,dc=com
changetype: modify
add: jpegPhoto
jpegPhoto:: encoded_data

In this example, encoded_data represents the contents of the out.ldif file produced by the command.

Directory Entries in LDIF

This section covers the following topics:

Organization Entries in LDIF

Directories often have at least one organization entry. Typically the organization entry is the first, or topmost entry in the directory. The organization entry often corresponds to the suffix set for the directory. For example, a directory defined to use a suffix of o=example.com will probably have an organization entry named o=example.com.

The LDIF that defines an organization entry should appear as follows:

dn: distinguished_name
objectClass: top 
objectClass: organization
o: organization_namelist_of_optional_attributes...

The following is an example organization entry in LDIF format:

dn: o=example.com
objectclass: top
objectclass: organization
o: example.com Corporation
description: Fictional company for example purposes
telephonenumber: 555-5555

The organization name in the following example uses a comma:

dn: o=example.com Chile\, S.A.
objectclass: top
objectclass: organization
o: example.com Chile\, S.A.
description: Fictional company for example purposes
telephonenumber: 555-5556

The following table describes each element of the organization entry.

Table 4–2 Organization Entries in LDIF

LDIF Element  

Description  

dn: distinguished_name

Required. Specifies the distinguished name for the entry.  

objectClass: top

Required. Specifies the top object class. 

objectClass: organization

Specifies the organization object class. This line defines the entry as an organization.  

o: organization_name

Specifies the organization’s name. If the organization name includes a comma, you must escape the comma by a single backslash or the entire organization argument must be enclosed in quotation marks. However, if you are working with a UNIX shell, you must also escape the backslash. Therefore, you must use two back slashes. For example, to set the suffix to example.com Bolivia, S.A. you would enter o: example.com Bolivia\, S.A..

list_of_attributes

Specifies the list of optional attributes that you want to maintain for the entry.  

Organizational Unit Entries in LDIF

In a directory tree, an organizational unit represents a major subdirectory. A directory tree usually contains more than one organizational unit. An LDIF file that defines an organizational unit entry must appear as follows:

dn: distinguished_name
objectClass: top
objectClass: organizationalUnit
ou: organizational_unit_namelist_of_optional_attributes...

The following example shows an organizational unit entry in LDIF format:

dn: ou=people, o=example.com
objectclass: top
objectclass: organizationalUnit
ou: people
description: Fictional organizational unit for example purposes

The following table defines each element of the organizational unit entry.

Table 4–3 Organizational Unit Entries in LDIF

LDIF Element  

Description  

dn: distinguished_name

Required. Specifies the distinguished name for the entry.  

If there is a comma in the DN, the comma must be escaped with a backslash (\). For example: 

dn: ou=people,o=example.com Bolivia\,S.A.

objectClass: top

Required. Specifies the top object class.

objectClass: organizationalUnit

Specifies the organizationalUnit object class. This line defines the entry as an organizationalUnit.

ou: organizational_unit_name

Specifies an attribute containing the name of the organizational unit. 

list_of_attributes

Specifies the list of optional attributes that maintain for the entry.  

Organizational Person Entries in LDIF

The majority of the entries in a directory represent organizational people. In LDIF, the definition of an organizational person is as follows:

dn: distinguished_name
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: common_name 
sn: surname
list_of_optional_attributes

The following example shows an organizational person entry in LDIF format:

dn: uid=bjensen,ou=people,o=example.com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: Babs Jensen
sn: Jensen
givenname: Babs
uid: bjensen
ou: Marketing
ou: people
description: Fictional person for example purposes
telephonenumber: 555-5557
userpassword: {sha}dkfljlk34r2kljdsfk9

The following table defines each element of the LDIF person entry.

Table 4–4 Organizational Person Entries in LDIF

LDIF Element  

Description  

dn: distinguished_name

Required. Specifies the distinguished name for the entry. 

If there is a comma in the DN, the comma must be escaped with a backslash (\). For example, dn:uid=bjensen,ou=people,o=example.com Bolivia\,S.A.

objectClass: top

Required. Specifies the top object class.

objectClass: person

Specifies the person object class. This object class specification should be included because many LDAP clients require it 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 require it 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. The uid attribute is required by this object class, and entries that contain this object class are named based on the value of the uid attribute.

cn: common_name

Required. Specifies the person’s common name which is the full name commonly used by the person. For example, cn: Bill Anderson.

sn: surname

Required. Specifies the person’s surname, or last name. For example, sn: Anderson.

list_of_attributes

Specifies the list of optional attributes that you maintain for the entry.  

Guidelines for Defining Directories by Using LDIF

Follow these guidelines to create a directory by using LDIF.

The following example shows an LDIF file with one organization entry, two organizational unit entries, and three organizational person entries.


Example 4–2 Example LDIF File With Entries for Organization, Organizational Units, and Organizational Person

dn: o=example.com Corp
objectclass: top
objectclass: organization
o: example.com Corp
description: Fictional organization for example purposes
dn: ou=People,o=example.com Corp
objectclass: top
objectclass: organizationalUnit
ou: People
description: Fictional organizational unit for example purposes
tel: 555-5559

dn: cn=June Rossi,ou=People,o=example.com Corp
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: June Rossi
sn: Rossi
givenName: June
mail: rossi@example.com
userPassword: {sha}KDIE3AL9DK
ou: Accounting
ou: people
telephoneNumber: 2616
roomNumber: 220

dn: cn=Marc Chambers,ou=People,o=example.com Corp
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: Marc Chambers
sn: Chambers
givenName: Marc
mail: chambers@example.com
userPassword: {sha}jdl2alem87dlacz1
telephoneNumber: 2652
ou: Manufacturing
ou: People
roomNumber: 167

dn: cn=Robert Wong,ou=People,o=example.com Corp
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: Robert Wong
cn: Bob Wong
sn: Wong
givenName: Robert
givenName: Bob
mail: bwong@example.com
userPassword: {sha}nn2msx761
telephoneNumber: 2881
roomNumber: 211
ou: Manufacturing
ou: people

dn: ou=Groups,o=example.com Corp
objectclass: top
objectclass: organizationalUnit
ou: groups
description: Fictional organizational unit for example purposes

Storing Information in Multiple Languages

For directories that contains a single language, it is not necessary to do anything special to add a new entry to the directory. However, for multinational organizations, it can be necessary to store information in multiple languages so that users in different locales can view directory information in their own language.

When information is represented in multiple languages, the server associates language tags with attribute values. When a new entry is added, attribute values used in the RDN (Relative Distinguished Name) must be added without any language codes.

Multiple languages can be stored within a single attribute. The attribute type is the same, but each attribute value has a different language code. The language tag has no effect on how the string is stored within the directory. All object class and attribute strings are stored using UTF-8.

For a list of the languages supported by Directory Server and their associated language tags, refer to Identifying Supported Locales.

For example, the example.com Corporation has offices in the United States and France. The company wants employees to be able to view directory information in their native language. When a directory entry is added for a new employee, Babs Jensen, the administrator creates the entry in LDIF. The administrator creates values for the personalTitle attribute in English and French, as follows:

dn: uid=bjensen,ou=people, o=example.com Corp
objectclass: top
objectclass: person
objectclass: organizationalPerson
name: Babs Jensen
cn: Babs Jensen
sn: Jensen
uid: bjensen
personalTitle: Miss
personalTitle;lang-en: Miss
personalTitle;lang-fr: Mlle
preferredLanguage: fr

Users accessing this directory entry with an LDAP client with the preferred language set to English will see the personal title Miss. Users accessing the directory with an LDAP client with the preferred language set to French will see the title Mlle.

Guidelines for Providing LDIF Input

All directory data is stored using the UTF-8 encoding of Unicode. Therefore, any LDIF input you provide must also be UTF-8 encoded. The LDIF format is described in detail in “LDAP Data Interchange Format Reference” in the Oracle Fusion Middleware Reference for Oracle Directory Server Enterprise Edition.

Consider the following points when you provide LDIF input:

Terminating LDIF Input on the Command Line

The ldapmodify and ldapdelete utilities read the LDIF statements that you enter after the command in exactly the same way as if they were read from a file. When you finish providing input, enter the character that your shell recognizes as the end of file (EOF) escape sequence.

Typically, the EOF escape sequence is Control-D (^D).

The following example shows how to terminate input to the ldapmodify command:

prompt\> ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w -
 dn: cn=Barry Nixon,ou=People,dc=example,dc=com
changetype: modify
delete: telephonenumber
^D
prompt\>

For simplicity and portability, examples in this document do not show prompts or EOF sequences.

Using Special Characters

When entering command options on the command line, you may need to escape characters that have special meaning to the command-line interpreter, such as space ( ), asterisk (*), backslash (\\), and so forth. For example, many DNs contain spaces, and you must enclose the value in double quotation marks ("") for most UNIX shells:

Depending on your command-line interpreter, you should use either single or double quotation marks for this purpose. Refer to your operating system documentation for more information.

Note that LDIF statements after the ldapmodify command are being interpreted by the command, not by the shell, and therefore do not need special consideration.

Using Attribute OIDs

Attribute OIDs are by default not supported in attribute names. This was not the case in some previous versions of Directory Server. If you used attribute OIDs as attribute names in a previous version of Directory Server, you must set the attribute nsslapd-attribute-name-exceptions to on for the attribute OIDs to be accepted.

Schema Checking

When adding or modifying an entry, the attributes you use must be required or allowed by the object classes in your entry, and your attributes must contain values that match their defined syntax.

When modifying an entry, Directory Server performs schema checking on the entire entry, not only the attributes being modified. Therefore, the operation may fail if any object class or attribute in the entry does not conform to the schema.

Ordering of LDIF Entries

In any sequence of LDIF text for adding entries, either on the command line or in a file, parent entries must be listed before their children. This way, when the server process the LDIF text, it will create the parent entries before the children entries.

For example, if you want to create entries in a People subtree that does not exist in your directory, then list an entry representing the People container before the entries within the subtree:

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

You can use the ldapmodify command-line utility to create any entry in the directory, however, the root of a suffix or subsuffix is a special entry that must be associated with the necessary configuration entries.

Managing Large Entries

Before adding or modifying entries with very large attribute values, you may need to configure the server to accept them. To protect against overloading the server, clients are limited to sending data no larger than 2 MB by default.

If you add an entry larger than this, or modify an attribute to a value which is larger, the server will refuse to perform the operation and immediately close the connection. For example, binary data such as multimedia contents in one or more attributes of an entry may exceed this limit.

Also, the entry defining a large static group may contain so many members that their representation exceeds the limit. However, such groups are not recommended for performance reasons, and you should consider redesigning your directory structure.

Error Handling

The command-line tools process all entries or modifications in the LDIF input sequentially. The default behavior is to stop processing when the first error occurs. Use the -c option to continue processing all input regardless of any errors. You will see the error condition in the output of the tool.

In addition to the considerations listed above, common errors are:

Searching the Directory

You can locate entries in a directory using any LDAP client. Most clients provide some form of search interface that enables you to search the directory and retrieve entry information.

The access control that has been set in your directory determines the results of your searches. Common users typically do not “see” much of the directory, and directory administrators have full access to all data, including configuration.

Searching the Directory With ldapsearch

You can use the ldapsearch command-line utility to locate and retrieve directory entries. Note that the ldapsearch utility described in this section is not the utility provided with the Solaris platform, but is part of the Directory Server Resource Kit.

This utility opens a connection to the server with a specified a user identity (usually a distinguished name) and password, and locates entries based on a 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.

ldapsearch Command-Line Format

When you use ldapsearch, you must enter the command using the following format:

ldapsearch [optional_options] [search_filter] [optional_list_of_attributes]

where


Note –

If you want operational attributes returned as a result of a search operation, you must explicitly specify them in the search command. To retrieve regular attributes in addition to explicitly specified operational attributes, use an asterisk (*) in the list of attributes in the ldapsearch command.


Using Special Characters

When using the ldapsearch command-line utility, 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 you specify special characters, enclose the value in quotation marks (“”). For example:

-D "cn=Charlene Daniels,ou=People,dc=example,dc=com"

Depending on your command-line interpreter, use either single or double quotation marks for this purpose. Refer to your shell documentation for more information.

ldapsearch Examples

In the next set of examples, the following assumptions are made:

Returning All Entries

Given the previous information, the following call will return all entries in the directory:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config
 -b "dc=example,dc=com" -s sub "(objectclass=*)"

"(objectclass=*)" is a search filter that matches any entry in the directory.

Specifying Search Filters on the Command Line

You can specify a search filter directly on the command line. If you do this, be sure to enclose your filter in quotation marks (“filter”). Also, do not specify the -f option.

For example:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -b "dc=example,dc=com" "(cn=Charlene Daniels)"

Searching the Root DSE Entry

The root DSE is a special entry that contains information related to the current server instance, such as a list of supported suffixes, available authentication mechanisms, and so forth. You can search this entry by supplying a search base of “”. You must also specify a search scope of base and a filter of "(objectclass=*)".

For example:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -b "" -s base "(objectclass=*)"

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 your directory server.

You can examine the contents of this entry as follows:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config
 -b "cn=schema" -s base "(objectclass=*)"

Note –

For strict compliance, the location of the schema subentry for a given entry is specified by the subschemaSubentry operational attribute. In this version of Directory Server, the value of this attribute is always cn=schema.


Using LDAP_BASEDN

To make searching easier, you can set your search base using the LDAP_BASEDN environment variable. Doing this allows you to skip specifying the search base with the -b option (for information on how to set environment variables, see the documentation for your operating system).

Typically, you set LDAP_BASEDN to your directory’s suffix value. Since your directory suffix is equal to the root, or topmost, entry in your directory, this causes all searches to begin from your directory’s root entry.

For example, if you have set LDAP_BASEDN to dc=example,dc=com, you can search for (cn=Charlene Daniels) in your directory using the following command-line call:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 "(cn=Charlene Daniels)"

In this example, the default scope of sub is used because the -s option was not used to specify the scope.

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 you are allowed to read. You can set up the directory access control such that you are allowed to read only a subset of the attributes on any given directory entry.) Only operational attributes are not returned. If you want operational attributes returned as a result of a search operation, you must explicitly specify them in the search command. For more information on operational attributes, refer to the TODO: No more AdminServerAdminGuide.

Suppose you do not want to see all of the attributes returned in the search results. You can limit the returned attributes to just a few specific attributes by specifying the ones you want 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:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 "(objectclass=*)" sn cn

This example assumes you set your search base with LDAP_BASEDN.

Searching Multi-Valued Attributes

During a search, Directory Server does not necessarily return multi-valued attributes in sorted order. For example, suppose you want to search for configuration attributes on cn=config requiring that the server be restarted before changes take effect.

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -b cn=config "(objectclass=*)" nsslapd-requiresrestart

The following result is returned:

dn: cn=config
nsslapd-requiresrestart: cn=config:nsslapd-port
nsslapd-requiresrestart: cn=config:nsslapd-secureport
nsslapd-requiresrestart: cn=config:nsslapd-plugin
nsslapd-requiresrestart: cn=config:nsslapd-changelogdir
nsslapd-requiresrestart: cn=config:nsslapd-changelogsuffix
nsslapd-requiresrestart: cn=config:nsslapd-changelogmaxentries
nsslapd-requiresrestart: cn=config:nsslapd-changelogmaxage
nsslapd-requiresrestart: cn=config:nsslapd-db-locks
nsslapd-requiresrestart: cn=config:nsslapd-return-exact-case
nsslapd-requiresrestart: cn=config,cn=ldbm database,cn=plugins,
  cn=config:nsslapd-allidsthreshold
nsslapd-requiresrestart: cn=config,cn=ldbm database,cn=plugins,
  cn=config:nsslapd-dbcachesize
nsslapd-requiresrestart: cn=config,cn=ldbm database,cn=plugins,
  cn=config:nsslapd-dbncache
nsslapd-requiresrestart: cn=config,cn=ldbm database,cn=plugins,
  cn=config:nsslapd-directory
nsslapd-requiresrestart: cn=encryption,cn=config:nssslsessiontimeout
nsslapd-requiresrestart: cn=encryption,cn=config:nssslclientauth
nsslapd-requiresrestart: cn=encryption,cn=config:nssslserverauth
nsslapd-requiresrestart: cn=encryption,cn=config:nsssl2
nsslapd-requiresrestart: cn=encryption,cn=config:nsssl3
...

As shown here, the nsslapd-requiresrestart attribute takes multiple values. These values are not, however, in sorted order. If you develop an application that requires multi-valued attributes in sorted order, make sure that your application performs the sort.

Using Client Authentication When Searching

This example shows user cdaniels searching the directory using client authentication:

ldapsearch -h myServer -p 636 -b "dc=example,dc=com"
  -N  "cdanielsscertname" -Z -W certdbpassword
  -P /home/cdaniels/certdb/cert.db "(givenname=Richard)"

LDAP Search Filters

Search filters select the entries to be returned for a search operation. They are most commonly used with the ldapsearch command-line utility. When you use ldapsearch, you can place multiple search filters in a file, with each filter on a separate line in the file, or you can specify a search filter directly on the command line.

For example, the following filter specifies a search for the common name Lucie Du Bois:

(cn=Lucie Du Bois)

This search filter returns all entries that contain the common name Lucie Du Bois. Searches for common name values are not case sensitive.

When the common name attribute has values associated with a language tag, all of the values are returned. Thus, the following two attribute values both match this filter:

cn: Lucie Du Bois
cn;lang-fr: Lucie Du Bois

Search Filter Syntax

The basic syntax of a search filter is:

(attribute operator value)

For example:

(buildingname\>=alpha)

In this example, buildingname is the attribute, \>= is the operator, and alpha is the value. You can also define filters that use different attributes combined together with Boolean operators.

Using Attributes in Search Filters

When searching for an entry, you can specify attributes associated with that type of entry. For example, when you search for people entries, you can use the cn attribute to search for people with a specific common name.

Examples of attributes that people entries might include:

Using Operators in Search Filters

The operators that you can use in search filters are listed in Table 4–5:

Table 4–5 Search Filter Operators

Search Type

Operator  

Description  

Equality

Returns entries containing attribute values that exactly match the specified value. For example, cn=Bob Johnson

Substring

=string*string

Returns entries containing attributes containing the specified substring. For example, 

cn=Bob*cn=*Johnsoncn=*John*cn=B*John

(The asterisk (*) indicates zero (0) or more characters.) 

Greater than or equal to

\>= 

Returns entries containing attributes that are greater than or equal to the specified value. For example, 

buildingname \>= alpha

Less than or equal to

<= 

Returns entries containing attributes that are less than or equal to the specified value. For example, 

buildingname <= alpha

Presence

=* 

Returns entries containing one or more values for the specified attribute. For example, 

cn=*

telephonenumber=*

manager=*

Approximate

~= 

Returns entries containing the specified attribute with a value that is approximately equal to the value specified in the search filter. For example, 

cn~=suret

l~=san fransico

could return 

cn=sarette

l=san francisco

The Approximate operator is experimental and works only with English language strings. It does not work with non-ASCII based strings, such as Ja or Zn. 

Extended operators exist that extend searches to dn attributes (cn:dn:=John, for example) and provide support for internationalized searches.

Using OIDs in Search Filters

LDAPv3 enables you to build match operators and rules for a particular attribute. Matching rules define how to compare attribute values with a particular syntax. In other words, a matching rule defines how potentially matching attributes are compared. For example, a matching rule can define whether or not to take text case into account when comparing attributes.

When the rules are created, they can be referred to in a search filter.

For example, the following search filter compares entries containing the surname “Jensen” by using the matching rule designated by OID 2.5.13.5:

(sn:2.5.13.5:=Jensen)

The following example illustrates the use of the ":dn" notation to indicate that OID 2.5.13.5 should be used when making comparisons, and that the attributes of an entry\qs distinguished name should be considered part of the entry when evaluating the match:

(sn:dn:2.5.13.5:=Jensen)

Using Compound Search Filters

Multiple search filter components can be combined using Boolean operators expressed in prefix notation as follows:

(Boolean-operator(filter)(filter)(filter)...)

where Boolean-operator is any one of the Boolean operators listed in Table 4–6.

Boolean operators can be combined and nested together to form complex expressions, such as:

(Boolean-operator(filter)(Boolean-operator(filter)(filter)))

The Boolean operators available for use with search filters include the following:

Table 4–6 Search Filter Boolean Operators

Operator  

Symbol  

Description  

AND 

All specified filters must be true for the statement to be true. For example, 

(&(filter)(filter)(filter)...)

OR 

At least one specified filter must be true for the statement to be true. For example, 

(|(filter)(filter)(filter)...)

NOT 

The specified statement must not be true for the statement to be true. Only one filter is affected by the NOT operator. For example, 

(!(filter))

The use of the NOT operator results in an unindexed search. 

Boolean expressions are evaluated in the following order:

Specifying Search Filters Using a File

You can enter search filters into a file instead of entering them on the command line. When you do this, 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, if the file contains:

(sn=Daniels)
(givenname=Charlene)

then ldapsearch first finds all the entries with the surname Daniels, and then all the entries with the given name Charlene. If an entry is found that matches both search criteria, the entry is returned twice.

For example, suppose you specified the previous search filters in a file named searchdb, and you set your search base using LDAP_BASEDN. The following returns all the entries that match either search filter:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -f searchdb

You can limit the set of attributes returned here by specifying the attribute names that you want 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:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -f searchdb sn givenname

Specifying Non 7-Bit ASCII Characters in Search Filters

Non 7-bit ASCII characters in search filters must be replaced with a representation of the character, where each byte of the UTF-8 encoding is preceded by a backslash. In UTF-8, characters are represented by a hexadecimal code for each byte.

For example, the character é has UTF-8 representation c3a9. Thus, in a search filter, you represent é as \\c3\\a9. So, to search for cn=Véronique Martin:

ldapsearch -h myServer -b "dc=example,dc=com" "(cn=V\\c3\\a9ronique Martin)"

The special characters listed in Table 4–7 must also be represented in this fashion when used in search filters.

Table 4–7 Special Characters in Search Filters

Special character  

Value With Special Character  

Example Filter  

Five*Star

(cn=Five\\2aStar)

\\ 

c:\\File

(cn=\\5cFile)

() 

John (2nd)

(cn=John \\282nd\\29)

null 

0004

(bin=\\00\\00\\00\\04)

Escaped Characters in Distinguished Names within Search Filters

When using a DN in any part of Directory Server, you must escape commas and certain other special characters with a backslash (\\). If you are using a DN in a search filter, the backslash used for escaping special characters in DNs must be represented by \\5c. For example:

DN: cn=Julie Fulmer,ou=Marketing\\,Bolivia,dc=example,dc=com

DN in a search filter: ldapsearch -h myServer -b "dc=example,dc=com" "(manager=cn=Julie Fulmer,ou=Marketing\\5c,Bolivia,dc=example,dc=com)"

Search Filter Examples

The following filter searches for entries containing one or more values for the manager attribute. This is also known as a presence search:

(manager=*)

The following filter searches for entries containing the common name Ray Kultgen. This is also known as an equality search:

(cn=Ray Kultgen)

The following filter returns all entries that contain a description attribute that contains the substring X.500:

(description=*X.500*)

The following filter returns all entries whose organizational unit is Marketing and whose description field does not contain the substring X.500:

(&(ou=Marketing)(!(description=*X.500*)))

The following filter returns all entries whose organizational unit is Marketing and that have Julie Fulmer or Cindy Zwaska as a manager:

(&(ou=Marketing)(|(manager=cn=Julie Fulmer,ou=Marketing,
 dc=example,dc=com)(manager=cn=Cindy Zwaska,ou=Marketing,
 dc=example,dc=com)))

The following filter returns all entries that do not represent a person:

(!(objectClass=person))

Note that the previous filter will have a negative performance impact and should be used as part of a complex search. The following filter returns all entries that do not represent a person and whose common name is similar to printer3b:

(&(cn~=printer3b)(!(objectClass=person)))

Searching for Operational Attributes

If you want operational attributes returned as a result of a search operation, you must explicitly specify them in the search command.

$ ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 "(objectclass=*)" aci

To retrieve regular attributes in addition to explicitly specified operational attributes, specify “*” in addition to the operational attributes. For example:

$ ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 "(objectclass=*)" aci *