ldapsearch(1) (Sun Java System Directory Server Enterprise Edition 6.2 Man Page Reference)

Sun Java System Directory Server Enterprise Edition 6.2 Man Page Reference

ldapsearch(1)

NAME

ldapsearch – find LDAP entries

Synopsis

/opt/SUNWdsee/dsee6/bin/ldapsearch -b baseDN [options] filter
 [attribute]...

/opt/SUNWdsee/dsee6/bin/ldapsearch  -b baseDN [options] -f filename
 [attribute]...

install-path/dsrk6/bin/ldapsearch 
 -b baseDN [options] filter [attribute]...

install-path/dsrk6/bin/ldapsearch 
 -b baseDN [options] -f filename [attribute]...

Description

The ldapsearch command searches for entries stored by a directory server based on the specified LDAP filter.

The ldapsearch command displays results found in LDIF format, including the specified attributes, or all attributes returned if none are specified.

Filter files, which are specified using the -f filename option, contain one filter per line. Specified LDAP filters must comply with RFC 2254.

Options

Unless the LDAP_BASEDN environment variable is set, you must at minimum provide a baseDN argument to the -b option. The baseDN argument specifies the distinguished name (DN) of the LDAP entry at the base of the search scope.

The following options are supported:

-0

Ignore LDAP library version mismatches.

When this option is omitted, the default behavior is to assert that the revision number of the LDAP API be greater than or equal to that used to compile the tool. Also, if the library and the tool have the same vendor name, the tool will assert that the vendor version number of the API be greater than or equal to that used to compile the tool. Revision and version numbers are based on the contents of the LDAPAPIInfo structure defined in <ldap.h> or header files included by <ldap.h>.

-1

Omit leading version: 1 indication in LDIF output, meaning the output is not RFC 2849 compliant.

-3

Check host names in SSL certificates.

-A

Display non-ASCII values when the -v option is used.

-C ps:changetype[:changesonly[:entrychangecontrols]]

Perform a persistent search that stops when you type Control-C.

By default, when used with the -C option the ldapsearch command requests that the directory server return entry change controls with persistent search results. Adjust this behavior with the following arguments:

changetype

Determines which modifications to an entry are detected and displayed in the output. Possible values include:

add
any
delete
modify
moddn

changesonly

Determines when to display search results. Possible values include:

0 f false: Display initial search results immediately, not waiting for changes. Then display new changes as they occur.
1: Display changes when they occur (default).

entrychangecontrols

Determines whether to display entry change controls. Possible values include:

0 f false: Do not display entry change controls.
1: Display entry change controls (default).

-D bindDN

Use the specified bind DN to authenticate to the directory server.

If the bind DN and its password are omitted, the ldapsearch command binds anonymously. The bind DN determines what entries and attributes appear in the search results, according to the search permissions for the DN.

-E

Request that the directories expose (report) bind identities.

-F sep

Print specified separator character instead of = between attribute types and values.

-G pattern

Retrieve a virtual list view displaying a portion of the total search results. Use this option with the -S and -x options to sort entries returned.

The specified pattern may take one of two forms to specify the size of the virtual list view around a target entry:

entriesbefore:entriesafter:value

Return the target entry, which is the first entry in the sorted results whose sort attribute is greater than or equal to the specified value, as well as the specified number of entries before the target entry and the specified number of entries after the target entry.

For example, -S sn -x -G 5:10:johnson returns 16 entries in alphabetical order of the surname attribute: 5 less than johnson, the entry equal to or following johnson, and the 10 subsequent entries.

entriesbefore:entriesafter:index:count

Return the target entry, as well as the specified number of entries before the target entry and the specified number of entries after the target entry. The target entry depends on the index and estimated count arguments.

The count argument may take the following values, with the following results:

count == 0

The target is the entry at the specified index position, starting from 1, and relative to the entire list of sorted results.

count == 1

The target is the first entry in the list of sorted results.

count > 1

The target is the first entry in the slice of the list represented by the fraction index/count.

Use an index argument greater than the count argument to target the last result in the list.

For example, -G 5:10:2:4 specifies the index closest to the beginning of the second quarter of the entire list. If the search yielded 100 entries, the target index would be 26, and this pattern would return entries 21 through 36.

The number of entries displayed before and after the target entry may be limited by the beginning and end of the virtual list. The ldapsearch command displays the control response, giving the count of entries in the virtual list and the index of the target entry. Use these values to refine index and count arguments.

-H -help --help -?

Display usage information.

-I filename

Read SSL key password for the client key database specified using the -P option from filename.

The default is key3.db.

-J controloid[:criticality[:value|::base64value|:<fileurl]]

Use the specified control OID.

The criticality, a boolean, is false by default.

An LDAP control can be associated with a value. Proxy authorization takes a proxy authorization ID, for example, passed with the control OID, and criticality. If a value is necessary you specify it using value, base64value, or <fileurl.

-K pathname

Use the SSL key database located in pathname, the full path to the key database file.

The default is to search for the key database file, key3.db, in the directory specified by the -P option.

-M

Manage referrals, searching the entry containing the referral instead of the entry obtained by following the referral.

-N certificate

Use the specified certificate for certificate-based client authentication, for example: -N "Client-Cert", where Client-Cert is the subject name of the user certificate.

-O limit

Follow at maximum limit referral hops. Default is 5.

-P filename

Use the certificate database located in filename, the full path to the certificate database file.

The default is to search for the certificate database file, cert8.db, in the current directory.

-Q [token][:certificate-name]

Use PKCS 11.

-R

Do not follow referrals automatically.

-S attrtype

Sort the results based on the specified attribute.

-T

Do not break long lines within individual attribute values.

Default is to break long attribute values according to LDIF rules.

-U

When generating temporary file output using the -t option, include URLs as attribute types whose value is a file, such as a photo or certificate.

-V n

Use LDAP protocol version n, where n is 2 or 3. Default is 3.

-W -

Prompt for the password for the client key database specified using the -P option.

The -W option is required for certificate-based client authentication.

-W password

Specify the password for the client key database specified using the -P option.

The -W option is required for certificate-based client authentication.

-X attrlist

When performing a search to get effective rights using the -c option, use the list of attributes provided.

-Y proxydn

Use the rights of the entry having the specified DN for performing LDAP operations. When using this option, you must also specify how to bind before you assume the rights of the proxy. Thus, when using simple authentication, you would also use the -D and -w options with this option.

Before proxy authentication can work in Directory Server, you must set up the appropriate access control instructions.

-Z

Use SSL to provide certificate-based client authentication.

The -Z option requires the -N and -W options and any other SSL options needed to identify the certificate and the key database.

-ZZ

Use Start TLS to provide certificate-based client authentication.

The -ZZ option requires the -N and -W options and any other SSL options needed to identify the certificate and the key database.

-a deref

Dereference aliases as specified during a search. Possible values for the deref argument include the following values:

always: Dereference aliases both when finding the base DN, and when searching below it.
find: Dereference aliases when finding the base DN.
never: Never dereference aliases (default).
search: Dereference aliases when searching below the base DN, but not when finding the base DN.

This option has no effect when used with directories that do not support alias dereferencing.

-c authzid

Use the specified authorization ID when to perform a get effective rights search. The following authorization IDs are supported:

"": "" represents an empty string, meaning use the authorization ID already specified for the operation.
"bindDN": Use the specified bind DN, such as uid=bjensen,ou=People,dc=example,dc=com.
"dn:": Use anonymous as the authorization ID.

-d level

Set LDAP debug level to the specified value.

The following debug levels are supported:

1: Display verbose debugging messages; LDAP_DEBUG_TRACE.
2: Display messages about the content of network packets; LDAP_DEBUG_PACKETS.
320: Display messages about LDIF parsing; LDAP_DEBUG_PARSE.
16384: Display informational messages; LDAP_DEBUG_ANY.

Use the sum of the levels to specify more than one debug level. For example, to set the debug level to display both verbose debugging messages, and messages about the content of network packets, specify -d 3.

-e

Minimize base64–encoding of resulting attribute values.

-f filename

Read the search filters from the specified file.

File format is one search filter per line, where search filters conform to RFC 2254.

-h host

Contact the LDAP server on the specified host, which may be a host name or an IP address. Enclose IPv6 addresses in brackets ([]) as described in RFC 2732.

For example, when mapping the IPv4 address 192.168.0.99 to IPv6, pass the -h option with its argument as -h [::ffff:192.168.0.99]. Notice the brackets.

When using GSSAPI with Directory Server, specify the host as a fully-qualified host name which matches the value of the nsslapd-localhost attribute on the cn=config entry. The GSSAPI authentication process requires that the host name provided by the client match the one provided by the server.

The default is localhost.

-i charset

Use the specified character set to override the value of the LANG environment variable. This option is useful, as the command converts certain arguments you specify to UTF-8 before sending the request to the server. The following arguments are converted: base DN, bind DN, LDAP filter, and password.

You can prevent the command from converting passwords by using the -k option.

Examples of charset values include ISO8859-1, ISO8859-15, ibm-1275, and windows-1251.

-j filename

Read the bind password for simple authentication from the specified file.

-k

Do not convert the passwords to UTF-8.

-l timelimit

Interrupt the search if the specified time limit is exceeded.

-m pathname

Use the security module database located in the specified directory.

Use the -m option if the security module database is in a different directory from the certificate database itself.

-n

Show what would be done, but do not actually do it.

-o attrname=attrvalue

Use the specified attribute values when performing SASL authentication.

The following attrname arguments are supported:

authid: Use the specified authentication identity.
authzid: Use the specified authorization identity.
mech: Request the specified SASL mechanism for the bind.
realm: Use the specified realm to complete the bind.
secProp: Use the specified security level.

The attrvalue is a valid value corresponding to the attrname you specify.

-p port

Contact the LDAP server on the specified port.

The default is 389 (636 if SSL is used).

-s scope

Use the specified search scope.

The following values are supported for scope:

base: Examine only the entry specified by the argument to the -b option.
one: Examine only to the entry specified by the argument to the -b option and its immediate children.
sub: (Default) Examine the subtree whose base is the entry specified by the argument to the -b option.

-t

Write a temporary file as output for each attribute of each entry in the search results. Such files are written to the system temporary directory, typically /tmp. On standard output, write file names in place of attribute values.

When the -t option is used, no base64 encoding is performed on any attribute values, regardless of their content.

-u

Include user friendly entry names (ufn: userfriendly) in the results returned.

-v

Run in verbose mode, displaying diagnostics on standard output.

-w –

Prompt for the bind password for simple authentication.

-w password

Use the specified bind password for simple authentication.

-x

Have the directory server sort results based on entry DNs before returning the results.

-z sizelimit

Interrupt the search if the specified maximum number of entries returned is exceeded.

INTERNATIONAL SEARCHES

This section focuses on international searches, and in particular the matching rule filter portion of the ldapsearch command.

When you perform search operations, you can request that the directory sort the results based on any language for which the server has a supported collation order.

A matching rule provides special guidelines for how the directory compares strings during a search operation. In an international search, the matching rule tells the system what collation order and operator to use when performing the search operation. The syntax of the matching rule filter is as follows.

attr:matchingRule:=value

Here attr, matchingRule, and value mean the following.

attr is an attribute belonging to entries you're searching for, such as cn or mail.
matchingRule is a string that identifies either the collation order or the collation order and a relational operator, depending on the format you prefer.
value is either the attribute value for which you want to search or a relational operator plus the attribute value for which you want to search. The syntax of the value portion of the filter depends on the matching rule format you use.

The matching rule portion of a search filter can be represented in one of the following ways.

Use an OID for the matching rule.

Each locale supported by Directory Server has an associated collation order OID. Locales supported for Directory Server are listed in the reference documentation on Identifying Supported Locales in Sun Java System Directory Server Enterprise Edition 6.2 Reference. When you use this approach, the matching rule filter has the following form.
```
attr:OID:=relational-operator value
```
The relational operator is included in the value portion of the string, separated from the value by a single space. For example, to search for all departmentNumber attributes that are at or after N4709 in the Swedish collation order, use the following filter.
```
departmentNumber:2.16.840.1.113730.3.3.2.46.1:=>= N4709
```
Use a language tag for the matching rule.

Each locale supported by Directory Server has an associated language tag. When you use this approach, the matching rule filter has the following form.
```
attr:language-tag:=relational-operator value
```
The relational operator is included in the value portion of the string, separated from the value by a single space. For example, to search the directory for all description attributes with a value of estudiante using the Spanish collation order, use the following filter.
```
cn:es:== estudiante
```
Use an OID and suffix for the matching rule.

As an alternative to using a relational operator-value pair, you can append a suffix that represents a specific operator to the OID in the matching rule portion of the filter. Combine the OID and suffix.
```
attr:OID+suffix:=value
```
For example, to search for businessCategory attributes with the value Softwareprodukte in the German collation order, use the following filter.
```
businessCategory:2.16.840.1.113730.3.3.2.7.1.3:=Softwareprodukte
```
The .3 in the previous example is the equality suffix.
Use a language tag and suffix for the matching rule.

As an alternative to using a relational operator-value pair, you can append a suffix that represents a specific operator to the language tag in the matching rule portion of the filter. Combine the language tag and suffix.
```
attr:language-tag+suffix:=value
```
For example, to search for all surnames that come at or after La Salle in the French collation order, use the following filter.
```
sn:fr.4:=La Salle
```

Directory Server supports the following types of international searches, designated in your search filter by adding either the search operator, or the search suffix to the OID or language code specifying the appropriate, collation dependent, matching rule.

equality

Search operator: =

Suffix operator: .1

less than

Search operator: <

Suffix operator: .2

less than or equal to

Search operator: <=

Suffix operator: .3

greater than or equal to

Search operator: >=

Suffix operator: .4

greater than

Search operator: >

Suffix operator: .5

substring

Search operator: =*

Suffix operator: .6

Approximate, or phonetic, and presence searches are supported only in English.

Examples

Examples in this section use the following conventions:

The directory server is located on a system named host.
The directory server has been configured to support anonymous access for search and read. Therefore, you do not have to specify bind information.
The directory server listens on port number 389, the default for non-SSL traffic.
The directory server listens on port number 636, the default for SSL traffic. SSL is enabled.

Example 1 Returning All Entries

The following command returns all entries in the suffix under the base DN. Use this only when you need to retrieve all entries and attributes:

$ ldapsearch -h host -b "dc=example,dc=com" "(objectclass=*)"

Example 2 Narrowing a Search

The following command employs a more specific filter to narrow the search:

$ ldapsearch -h host -b "dc=example,dc=com" "(cn=Babs Jensen)"

Example 3 Searching the Root DSE Entry

The following command searches the root DSE entry, requesting supported naming contexts and supported LDAP versions. Notice you specify the scope as only the base entry:

$ ldapsearch -h host -b "" -s base "(objectclass=*)" \
 namingContexts supportedLDAPVersion
version: 1
dn:
namingContexts: dc=example,dc=com
supportedLDAPVersion: 2
supportedLDAPVersion: 3

Example 4 Searching the Schema Entry

The following command searches the schema entry, which contains the directory schema. Notice that you can request the operational attribute subSchemaSubEntry on any entry to determine which entry holds the schema attributes, in this case cn=schema. Then you specify the scope as only the base entry:

$ ldapsearch -h host -b "" -s base "(objectclass=*)" subSchemaSubEntry
version: 1
dn:
subSchemaSubEntry: cn=schema
$ ldapsearch -h host -b "cn=schema" -s base "(objectclass=*)"
version: 1
dn: cn=schema
…

Example 5 Setting the Base DN

The following commands set the LDAP_BASEDN environment variable, and then use it when searching the directory. The syntax of the first command may not work for your shell. Refer to the documentation about your shell for instructions on setting environment variables.

$ LDAP_BASEDN="dc=example,dc=com"; export LDAP_BASEDN
$ ldapsearch -h host "(givenname=Barbara)" cn uid
version: 1

dn: uid=bjablons, ou=People, dc=example,dc=com
cn: Barbara Jablonski
uid: bjablons

dn: uid=bhal2, ou=People, dc=example,dc=com
cn: Barbara Hall
uid: bhal2

dn: uid=bjensen, ou=People, dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen
uid: bjensen

dn: uid=bmaddox, ou=People, dc=example,dc=com
cn: Barbara Maddox
uid: bmaddox

dn: uid=bfrancis, ou=People, dc=example,dc=com
cn: Barbara Francis
uid: bfrancis
$

Example 6 Using a Filter File

The following commands demonstrate use of a filter file. The results show the directory server responds to separate searches for each filter.

$ cat filters
sn=Francis
givenname=Barbara
$ ldapsearch -b "dc=example,dc=com" -h host -f filters cn uid
version: 1

dn: uid=rfrancis, ou=People, dc=example,dc=com
cn: Richard Francis
uid: rfrancis

dn: uid=bfrancis, ou=People, dc=example,dc=com
cn: Barbara Francis
uid: bfrancis

dn: uid=bjablons, ou=People, dc=example,dc=com
cn: Barbara Jablonski
uid: bjablons

dn: uid=bhal2, ou=People, dc=example,dc=com
cn: Barbara Hall
uid: bhal2

dn: uid=bjensen, ou=People, dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen
uid: bjensen

dn: uid=bmaddox, ou=People, dc=example,dc=com
cn: Barbara Maddox
uid: bmaddox

dn: uid=bfrancis, ou=People, dc=example,dc=com
cn: Barbara Francis
uid: bfrancis
$

Example 7 Escaping Commas

The following command demonstrates use of the backslash (\) to escape a comma within a base DN.

$ ldapsearch -b "o=Example Company\, Inc.,dc=example,dc=com" \
 -h host "(givenname=Barbara)"

SSL Authentication Examples

The following examples demonstrate using SSL authentication for searches.

Example 8 Using Server Authentication

The following command uses server authentication during the bind, where the server only accepts binds by clients with trusted certificates. Notice only the -P option is used without other SSL-related options.

$ ldapsearch -h host -p 636 -b dc=example,dc=com \
 -P /home/bjensen/security -D uid=bjensen,ou=people,dc=example,dc=com \
 -w - "(givenname=Barbara)"
Enter bind password:

Example 9 Using Client Authentication

The following command uses client authentication during the bind, where the server only accepts binds by clients with trusted certificates, and the client must sign the certificate with a password-protected private key. Notice the options used in this example.

$ ldapsearch -h host -p 636 -b dc=example,dc=com \
 -P /home/bjensen/security -N "bjscert" -K /home/bjensen/security \
 -W keypassword "(givenname=Barbara)"

International Search Examples

The following examples show search filters used to perform international searches on directory data. Each example gives all the possible matching rule filter formats so that you can become familiar with the formats and select the one that works best for you.

Example 10 International Less Than Search

When you perform a locale-specific search using the less than operator (<) or suffix (.1), you search for all attribute values that come before the given attribute in a specific collation order.

Any of the following filters can be used to search for all surnames that come before the surname Marquez in the Spanish collation order.

sn:2.16.840.1.113730.3.3.2.15.1:=< Marquez
sn:es:=< Marquez
sn:2.16.840.1.113730.3.3.2.15.1.1:=Marquez
sn:es.1:=Marquez

Example 11 International Less Than or Equal To Search

When you perform a locale-specific search using the less than or equal to operator (<=) or suffix (.2), you search for all attribute values that come at or before the given attribute in a specific collation order.

Any of the following filters can be used to search for all room numbers that come at or before room number CZ422 in the Hungarian collation order.

roomNumber:2.16.840.1.113730.3.3.2.23.1:=<= CZ422
roomNumber:hu:=<= CZ422
roomNumber:2.16.840.1.113730.3.3.2.23.1.2:=CZ422
roomNumber:hu.2:=CZ422

Example 12 International Equality Search

When you perform a locale-specific search using the equal to operator (=) or suffix (.3), you search for all attribute values that match the given attribute in a specific collation order.

Any of the following filters can be used to search for all businessCategory attributes with the value Softwareprodukte in the German collation order.

businessCategory:2.16.840.1.113730.3.3.2.7.1:== Softwareprodukte
businessCategory:de:== Softwareprodukte
businessCategory:2.16.840.1.113730.3.3.2.7.1.3:=Softwareprodukte
businessCategory:de.3:=Softwareprodukte

Example 13 International Greater Than or Equal To Search

When you perform a locale-specific search using the greater than or equal to operator (>=) or suffix (.4), you search for all attribute values that come at or after the given attribute in a specific collation order.

Any of the following filters can be used to search for all localities that come at or after Québec in the French collation order.

locality:2.16.840.1.113730.3.3.2.18.1:=>= Québec
locality:fr:=>= Québec
locality:2.16.840.1.113730.3.3.2.18.1.4:=Québec
locality:fr.4:=Québec

Example 14 International Greater Than Search

When you perform a locale-specific search using the greater than operator (>) or suffix (.5), you search for all attribute values that come at or before the given attribute in a specific collation order.

Any of the following filters can be used to search for all mail hosts that come after host schranka4 in the Czech collation order.

mailHost:2.16.840.1.113730.3.3.2.5.1:=> schranka4
mailHost:cs:=> schranka4
mailHost:2.16.840.1.113730.3.3.2.5.1.5:=schranka4
mailHost:cs.5:=schranka4

Example 15 International Substring Search

When you perform an international substring search, you search for all values that match the given pattern in the specified collation order.

Any of the following filters can be used to search for all user IDs that end in ming in the Chinese collation order.

uid:2.16.840.1.113730.3.3.2.49.1:=* *ming
uid:zh:=* *ming
uid:2.16.840.1.113730.3.3.2.49.1.6*_:=*ming_*
uid:zh.6*_:=*ming_*

Exit Status

The exit status returned reflects the return values of the underlying functions used, which may depend on return values sent by the server. Common exit status codes follow:

0: Successful completion; LDAP_SUCCESS; 0x00.
1: Server encountered errors while processing the request; LDAP_OPERATIONS_ERROR; 0x01.
2: Server encountered errors, such as a BER-decoding error, while processing the request; LDAP_PROTOCOL_ERROR; 0x02.
3: Search exceeded the time limit for operations on the server; LDAP_TIMELIMIT_EXCEEDED; 0x03.
4: Search returned more results than the maximum number allowed by the server; LDAP_SIZELIMIT_EXCEEDED; 0x04.
10: Base DN belongs to an entry handled by neither server, and the referral URL identifies another server that handles the entry; LDAP_REFERRAL; 0x0a.
11: Search returned more results than the maximum number a client application is allowed by the server to retrieve; LDAP_ADMINLIMIT_EXCEEDED; 0x0b.
32: Base DN belongs to an entry handled by neither server, and no referral URL is available for the entry; LDAP_NO_SUCH_OBJECT; 0x20.
34: Base DN is not a valid DN; LDAP_INVALID_DN_SYNTAX; 0x22.
50: Bind DN user does not have permission to read the entry from the directory; LDAP_INSUFFICIENT_ACCESS; 0x32.
53: Directory is read-only; LDAP_UNWILLING_TO_PERFORM; 0x35.
81: The directory server did not respond to the request, or the connection was lost; LDAP_SERVER_DOWN; 0x51.
82: An error occurred while receiving results; LDAP_LOCAL_ERROR; 0x52.
83: The request could not be BER-encoded; LDAP_ENCODING_ERROR; 0x53.
84: A result could not be decoded; LDAP_DECODING_ERROR; 0x54.
85: The search exceeded the time limit specified using the -l option; LDAP_TIMEOUT; 0x55.
87: An error occurred while parsing and BER-encoding the specified filter; LDAP_FILTER_ERROR; 0x57.
89: An option or argument is not valid; LDAP_PARAM_ERROR; 0x59.
90: Needed memory could not be allocated; LDAP_NO_MEMORY; 0x5a.
91: A specified host name or port is not valid; LDAP_CONNECT_ERROR; 0x5b.
92: The directory server supports only LDAPv2, and the -V 2 option was not used, or the -V 2 option was used, but the server no longer supports LDAP v2; LDAP_NOT_SUPPORTED; 0x5c.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWldapcsdk-tools
Stability Level	Evolving