NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | EXIT STATUS | ATTRIBUTES | SEE ALSO
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 contain one filter per line. Specified LDAP filters must comply with RFC 2254.
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:
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>.
Omit leading version: 1 indication in LDIF output, meaning the output is not RFC 2849 compliant.
Check host names in SSL certificates.
Display non-ASCII values when the -v option is used.
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:
Determines which modifications to an entry are detected and displayed in the output. Possible values include:
Determines when to display search results. Possible values include:
Display initial search results immediately, not waiting for changes. Then display new changes as they occur.
Display changes when they occur (default).
Determines whether to display entry change controls. Possible values include:
Do not display entry change controls.
Display entry change controls (default).
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 comparison results, according to the DN's search permissions.
Request that the directories expose (report) bind identities.
Print specified separator character instead of : between attribute types and values.
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:
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.
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:
The target is the entry at the specified index position, starting from 1, and relative to the entire list of sorted results.
The target is the first entry in the list of sorted results.
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.
Display usage information.
Use the specified SSL card password file (pin).
Use the specified control OID.
The criticality, a boolean, is false by default.
Use the certificate private key database located in the specified directory.
You may omit the -K option if the key database location is provided as an argument to the -P option.
Manage referrals, searching the entry containing the referral instead of the entry obtained by following the referral.
Use the specified certificate for certificate-based client authentication, for example: -N "Client-Cert", where Client-Cert is the subject name of the user's certificate.
Follow at maximum limit referral hops. Default is 5.
Use the certificate database located in filename, the full path to the certificate database file.
Use PKCS 11.
Do not follow referrals automatically.
Sort the results based on the specified attribute.
Do not break long lines within individual attribute values.
Default is to break long attribute values according to LDIF rules.
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.
Use LDAP protocol version n, where n is 2 or 3. Default is 3.
Specify the password for the client's key database specified using the -K or -P option.
The -W option is required for certificate-based client authentication.
When performing a search to get effective rights using the -c option, use the list of attributes provided.
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.
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.
Dereference aliases as specified during a search. Possible values for the deref argument include the following values:
Dereference aliases both when finding the base DN, and when searching below it.
Dereference aliases when finding the base DN.
Never dereference aliases (default).
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.
Use the specified authorization ID when to perform a get effective rights search. The following authorization IDs are supported:
Use the authorization ID already specified for the operation.
Use the specified bind DN, such as uid=bjensen,ou=People,dc=example,dc=com
Use anonymous as the authorization ID.
Set LDAP debug level to the specified value.
The following debug levels are supported:
Display verbose debugging messages; LDAP_DEBUG_TRACE.
Display messages about the content of network packets; LDAP_DEBUG_PACKETS.
Display messages about LDIF parsing; LDAP_DEBUG_PARSE.
Display informational messages; LDAP_DEBUG_ANY.
Use the sum of the levels to specify more than one debug level.
Minimize base64–encoding of resulting attribute values.
Read the search filters from the specified file.
File format is one search filter per line, where search filters conform to RFC 2254.
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.
The default is localhost.
Use the specified character set as opposed to the character set specified as the value of the LANG environment variable.
Use this option for example to perform the conversion from the specified character set to UTF8, thus overriding the LANG setting.
Read the bind password for simple authentication from the specified file.
Use the conversion routines located in the specified directory.
The default is to use the current directory. Use the -k option to specify a sorting language that is not supported by the directory server.
Interrupt the comparison if the specified time limit is exceeded.
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.
Show what would be done, but do not actually do it.
Use the specified attribute values when performing SASL authentication.
The following attrname arguments are supported:
Use the specified authentication identity.
Use the specified authorization identity.
Request the specified SASL mechanism for the bind.
Use the specified realm to complete the bind.
Use the specified security level.
Contact the LDAP server on the specified port.
The default is 389 (636 if SSL is used).
Use the specified search scope.
The following values are supported for scope:
Examine only the entry specified by the argument to the -b option.
Examine only to the entry specified by the argument to the -b option and its immediate children.
(Default) Examine the subtree whose base is the entry specified by the argument to the -b option.
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.
Include user friendly entry names (ufn: userfriendly) in the results returned.
Run in verbose mode, displaying diagnostics on standard output.
Prompt for the bind password for simple authentication.
Use the specified bind password for simple authentication.
Have the directory server sort results based on entry DNs before returning the results.
Interrupt the comparison if the specified maximum number of entries returned is exceeded.
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.
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=*)" |
The following command employs a more specific filter to narrow the search:
$ ./ldapsearch -h host -b "dc=example,dc=com" "(cn=Babs Jensen)" |
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 namingContexts: o=NetscapeRoot supportedLDAPVersion: 2 supportedLDAPVersion: 3 |
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 … |
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.
$ export LDAP_BASEDN="dc=example,dc=com" $ ./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 |
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 $ |
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)" |
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: |
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)" |
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:
Successful completion; LDAP_SUCCESS; 0x00.
Server encountered errors while processing the request; LDAP_OPERATIONS_ERROR; 0x01.
Server encountered errors, such as a BER-decoding error, while processing the request; LDAP_PROTOCOL_ERROR; 0x02.
Search exceeded the time limit for operations on the server; LDAP_TIMELIMIT_EXCEEDED; 0x03.
Search returned more results than the maximum number allowed by the server; LDAP_SIZELIMIT_EXCEEDED; 0x04.
Base DN belongs to an entry handled by neither server, and the referral URL identifies another server that handles the entry; LDAP_REFERRAL; 0x0a.
Search returned more results than the maximum number a client application is allowed by the server to retrieve; LDAP_ADMINLIMIT_EXCEEDED; 0x0b.
Base DN belongs to an entry handled by neither server, and no referral URL is available for the entry; LDAP_NO_SUCH_OBJECT; 0x20.
Base DN is not a valid DN; LDAP_INVALID_DN_SYNTAX; 0x22.
Bind DN user does not have permission to read the entry from the directory; LDAP_INSUFFICIENT_ACCESS; 0x32.
Directory is read-only; LDAP_UNWILLING_TO_PERFORM; 0x35.
One of the directories did not respond to the request, or the connection was lost; LDAP_SERVER_DOWN; 0x51.
An error occurred while receiving results; LDAP_LOCAL_ERROR; 0x52.
The request could not be BER-encoded; LDAP_ENCODING_ERROR; 0x53.
A result could not be decoded; LDAP_DECODING_ERROR; 0x54.
The search exceeded the time limit specified using the -l option; LDAP_TIMEOUT; 0x55.
An error occurred while parsing and BER-encoding the specified filter; LDAP_FILTER_ERROR; 0x57.
An option or argument is not valid; LDAP_PARAM_ERROR; 0x59.
Needed memory could not be allocated; LDAP_NO_MEMORY; 0x5a.
A specified host name or port is not valid; LDAP_CONNECT_ERROR; 0x5b.
At least one 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.
See attributes(5) for descriptions of the following attributes:
ATTRIBUTE TYPE | ATTRIBUTE VALUE |
---|---|
Availability | SUNWldk |
Stability Level | Evolving |
ldapcompare(1), ldapdelete(1), ldapmodify(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | EXIT STATUS | ATTRIBUTES | SEE ALSO