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 files consist of one or more directory entries separated by a blank line. Each LDIF entry consists of the following parts:
Entry ID (optional)
Distinguished name (required)
One or more object classes
Multiple attribute definitions
The LDIF format is defined in RFC 2849.
The following example shows a basic directory entry in LDIF.
dn: distinguished_name objectClass: object_class objectClass: object_class ... attribute_type[;subtype]: attribute_value attribute_type[;subtype]: attribute_value ...
An LDIF file must contain the following parts:
A DN
At least one object class definition
Any attributes required by the object classes that you define for the entry
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 13–1 LDIF Fields
The LDIF syntax for representing a change to an entry in the directory is different from the syntax described above.
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.
You can represent binary data in LDIF by using one of the following methods:
Standard LDIF notation, the lesser than, <, symbol
Command-line utility, ldapmodify with the -b option
Base 64 encoding
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 |
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.
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:
Any value that begins with a semicolon, ;, or a space
Any value that contains non ASCII data, including new lines
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.
This section covers the following topics:
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 13–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. |
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 13–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. |
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 13–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. |
Follow these guidelines to create a directory by using LDIF.
Create an ASCII file that contains the entries you want to add in LDIF format.
Separate entries with a single empty line. Do not allow the first line of the file to be blank, otherwise the ldapmodify command will exit.
Begin each file with the topmost, or root, entry in the database. The root entry must represent the suffix or sub-suffix contained by the database. For example, if your database has the suffix dc=example,dc=com, the first entry in the directory must be
dn: dc=example,dc=com |
Create the branch point for a subtree before you create entries to go in the subtree.
Create the directory from the LDIF file by using one of the following methods:
By using the Directory Service Control Center
By using the dsadm command and dsconf command
By using theldapmodify command with the -a option or -B option
Create the directory by using ldapmodify command if you currently have a directory database but you are adding a new subtree to the database. Unlike the other methods for creating the directory from an LDIF file, Directory Server must be running before you can add a subtree by using the ldapmodify command.
The following example shows an LDIF file with one organization entry, two organizational unit entries, and three organizational person entries.
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
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.
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 Sun Java System Directory Server Enterprise Edition 6.0 Reference.
Consider the following points when you provide LDIF input:
An object is a blank line followed by a line that starts with dn:. This line is the distinguished name of the object. All other lines are the object’s attributes.
Comments start with # (and end with the EOL.)
Lines starting with a single space continue the previous line.
Binary values are base-64 encoded, and represented with a double colon (::) after the attribute name.
Carriage returns and line feeds unsafe in LDIF values, and should be base-64 encoded.
Do not unintentionally leave trailing spaces at the end of an attribute value when you change the attribute value by using the ldapmodify command.
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.
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:
-D "cn=Barbara Jensen,ou=Product Development,dc=example,dc=com"
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.
In addition, if you are using DNs that contain commas, you must escape the commas with a backslash (\\). For example:
-D "cn=Patricia Fuentes,ou=People,o=example.com Bolivia\\,S.A."
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.
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.
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.
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.
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 multi-media 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.
Set a new value for the nsslapd-maxbersize attribute of the cn=config entry.
To do this from the command line, use the following command:
ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w - dn: cn=config changetype: modify replace: nsslapd-maxbersize nsslapd-maxbersize: sizeLimitInBytes ^D |
For more information, see “nsslapd-maxbersize” in the Sun Java System Directory Server Enterprise Edition 6.0 Reference.
Restart the server.
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:
Not having the appropriate access permission for the operation.
Adding an entry with a DN that already exists in the directory.
Adding an entry below a parent that does not exist.
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.
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.
When you use ldapsearch, you must enter the command using the following format:
ldapsearch [optional_options] [search_filter] [optional_list_of_attributes]
where
optional_options represents a series of command-line options. These must be specified before the search filter, if any.
search_filter represents an LDAP search filter in a file using the -f option.
optional_list_of_attributes represents a list of attributes separated by a space. Specifying a 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 a 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 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.
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.
The following lists the most commonly used ldapsearch command-line options. If you specify a value that contains a space [ ], the value should be surrounded by double quotation marks, for example, -b "ou=groups, dc=example,dc=com".
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=Charlene Daniels, ou=People, dc=example,dc=com"
Specifies the distinguished name with which to authenticate to the server. This option is optional if anonymous access is supported by your server. If specified, this value must be a DN recognized by Directory Server, and it must also have the authority to search for the entries. For example:
-D "uid=cdaniels, dc=example,dc=com"
Specifies the hostname or IP address of the machine on which Directory Server is installed. If you do not specify a host, ldapsearch uses the localhost. For example, -h myServer.
Specifies the maximum number of seconds to wait for a search request to complete. Regardless of the value specified here, ldapsearch will never wait longer than is allowed by the server’s nsslapd-timelimit attribute (except in the case of a persistent search.)Sun Java System Directory Server Enterprise Edition 6.0 Reference.
For example, -l 300. The default value for the nsslapd-timelimit attribute is 3,600 seconds (1 hour.)
Specifies the TCP port number that Directory Server uses. For example, -p 5201. The default is 389, and 636 when the SSL options are used.
Specifies the scope of the search. The scope can be one of:
base—Search only the entry specified in the -b option or defined by the LDAP_BASEDN environment variable.
one—Search 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—Search 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.
Specifies the password associated with the distinguished name that is specified in the -D option. If you do not specify this option, anonymous access is used. For example, -w diner892.
Specifies that the search results are sorted on the server rather than on the client. This is useful if you want 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, although server-side sorting uses server resources.
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. However, you can override this limitation by binding as the root DN when using this command-line argument. When you bind as the root DN, this option defaults to zero (0). The default value for the nsslapd-sizelimit attribute is 2,000 entries.
For detailed information on all ldapsearch utility options, refer to ldapmodify(1).
In the next set of examples, the following assumptions are made:
You want to perform a search of all entries in the directory.
The server is located on hostname myServer.
The server uses port number 5201.
You are binding to the directory as cn=admin,cn=Administrators,cn=config. Using the symbol “-” means that you will be prompted for the password on the command line.
SSL is enabled for the server on port 636 (the default SSL port number).
The suffix under which all data is stored is dc=example,dc=com.
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.
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)"
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=*)"
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=*)"
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.
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.
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.
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.
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)"
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
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.
Search filters are described in detail in the following sections:
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:
cn (the person’s common name)
sn (the person’s surname, or last name, or family name)
telephoneNumber (the person’s telephone number)
buildingName (the name of the building in which the person resides)
l (the locality in which you can find the person)
The operators that you can use in search filters are listed in Table 13–5:
Table 13–5 Search Filter Operators
Operator |
Description |
|
---|---|---|
= |
Returns entries containing attribute values that exactly match the specified value. For example, cn=Bob Johnson |
|
=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.) |
|
\>= |
Returns entries containing attributes that are greater than or equal to the specified value. For example, buildingname \>= alpha |
|
<= |
Returns entries containing attributes that are less than or equal to the specified value. For example, buildingname <= alpha |
|
=* |
Returns entries containing one or more values for the specified attribute. For example, cn=* telephonenumber=* manager=* |
|
~= |
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.
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)
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 13–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 13–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)) |
Boolean expressions are evaluated in the following order:
Innermost to outermost parenthetical expressions first
All expressions from left to right
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
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 13–7 must also be represented in this fashion when used in search filters.
Table 13–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) |
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)"
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)))
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 *