How to Use ldapsearch command and Test ldap connection

Posted on : April 30, 2011 , Last Updated on : January 18, 2017 By
| Reply More

The ldapsearch command opens a connection to an LDAP server, binds, and performs a search using specified parameters.

The ldapsearch tool has four types of options:

  • Common Options
  • Input And Output Options
  • LDAP Controls Options
  • SSL (Secure Socket Layer) Options

Common Options

The ldapsearch -H command and option, when run on the command line, will display brief descriptions of all the command-line options

Some common options for ldapsearch  are listed below:

-h ldaphost

Specify the hostname of the directory server. When this option is omitted, it takes the default which is localhost.

-p ldapport

Specify an alternate TCP port where the ldap server is listening. The default is 389 normally and 636 when the SSL options are used.

-D bindDN

Specify a bind DN for accessing your directory, usually in double quotes ("") for the shell. Use the Distinguished Name "binddn" to bind to the LDAP directory.  For SASL binds, the server is expected to ignore this
value. If the bind DN and its password are omitted, the tool will use anonymous binding.

-w passwd

Specify the password for the bind DN. It isn't advised to specify the password on the command-line, since it is a security breach. Use passwd as the password for simple authentication.

-W
Prompt for simple authentication. This is used instead of specifying the password on the command line.
Type the password for the bind DN when prompted. This is the most secure way of specifying the password.

-j filename

Specify a file containing the password for the bind DN. We can use this option in scripts and place the password in a secure file to protect it. You can't use it with -w option.

-b baseDN

Use search base as the starting point for the search instead of the default. Specify the base DN for the search operation, usually in double quotes ("") for the shell. You may omit this option if you specify the base DN in the LDAP_BASEDN environment variable.

-s {base|one|sub|children}
Specify the scope of the search to be one of base, one, sub, or children to specify a base object, one-level, subtree, or
children search. The default is sub. The scope parameter may have one of the following values:

base - For searching only the base entry.
one - For searching only the children of the base entry.
sub - For searching the base entry and all its descendants. This is the default if the -s option is omitted.

-f filterFile

Read a series of lines from a file, performing one LDAP search for each line. Specify the name of a file containing filter strings. This file contains one or more filters, each on a separate line; ldapsearch will perform a separate search with each filter, in the order found in the file. ldapsearch will exit when the first non-successful search result is returned unless -c is used

-l timelimit

It will wait at most timelimit seconds for a search to complete. A time limit of 0 (zero) or none means no limit. A time limit of max means the maximum integer allowable by the protocol. A server may impose a maximal time limit which only the root user may override. ldapsearch will never wait longer than is allowed by the server’s nsslapd-timelimit attribute, whose default is 3,600 seconds.

-V version

It will output version info. If -VV is given, only the version information is printed. LDAP v3 is the default; only specify LDAP v2 when connecting to servers that do not support v3.

-v

It will run in Verbose mode. The tool will display additional information about the search, such as the filter string and the number of results for each search.

-n

Show what would be done, but don't actually perform the search. Useful for debugging in conjunction with -v. No-op mode: It can be used with the -v option to show what tool would do with the given input without actually performing any search.

-H

List the usage help text that briefly describes all options.

Input And Output Options

Some of the useful Input/Output options are listed below:

-i locale

It is used to mention the character set to use for command-line input. The default is the character set specified in the LANG environment variable. This argument only affects the command-line input.
-k path

It is used to specify the path to a directory containing conversion routines. You can use these routines if you wish to specify a sorting language which isn't supported by your LDAP server.

-S [-]attribute

This specifies an attribute to sort entries returned by the search.

-z max

It specifies the maximum number of entries to return in response to a search request.

-u

By using this we can include User-Friendly Name form of the Distinguished Name (DN) in the output

-t

This is useful for dealing with values containing non-character data such as jpegPhoto or audio. A second -t writes all retrieved values to files. Temporary file output: each attribute of each entry in the search results will be written to a separate file in the system’s temporary directory (usually /tmp). The standard output of the tool will include the name of the file instead of the attribute’s value.

-o

It is used to specify the SASL security parameters. It can be used specify Simple Authentication and Security Layer (SASL) options (mech, realm, authid and authzid).

 

LDAP Controls Options

It provides advanced search controls for server-side sorting, virtual lists, and persistent searches. This functionality is available only if the server supports the corresponding LDAP controls.  Please see some of the useful LDAP control options below:

-x

Use simple authentication instead of SASL. It is used with the -S option (input/output options) to specify that search results be sorted on the server rather than by the ldapsearch command running on the client. It is usually faster to sort on the server, rather than on the client.

-C pattern

Used to perform a search that keeps the connection open and displays results whenever entries matching the scope and filter of the search are added, modified, or removed. The ldapsearch tool will run indefinitely for this persistent search. Control-C must be typed to stop it. These controls indicate the type of operation that caused the entry to be detected by the search. the pattern has the format:

ps:changeType[:changesOnly[:entryChangeControls]]

changeType determines which modifications to an entry are detected and displayed in the output; its possible values are added, delete, modify,  or any.

changesOnly is an optional boolean value. The default 1 displays changes when they occur. Specify 0, f, or false to display the results of the search before waiting for changes.

entryChangeControls is also an optional boolean value. Specify 0, f, or false if you do not want the server to return entry change controls. In this case, you must also specify a value for the changesOnly parameter.

-G pattern

This option always requires the -S and -x options to specify the sorting order on the server.  This virtual list view retrieves only a portion of all results, as determined by the index or value of the search target and the number of entries to be returned before and after the target. The pattern has two possible formats:

entriesBefore:entriesAfter:value - It is used to specify the search target as the first entry in the sorted results for which the sort attribute is “greater than” or equal to the given value. For example, -S sn -x -G 5:10:john will return 16 entries in alphabetical order of the surname attribute: 5 less than john, the entry equal to or following john, and the 10 subsequent entries.

entriesBefore:entriesAfter:index:count - It is used to specify the search target as the index position relative to the estimated count. If the count is 0 (zero), the index is taken as the absolute index of the target entry within the actual number of entries found. An index of 1 will always select the first entry in the sorted list of results.

In this example, -G 5:10:2:4  it 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. Give an index greater than the count to specify the last search result in the list.

The number of entriesBefore and entriesAfter displayed will be limited by the beginning and end of the virtual list. ldapsearch takes results and displays the control response to give the total count of entries in the virtual list and the actual index of the target entry. We can use these values to refine our search with more accurate index and count parameters.

SSL (Secure Socket Layer) Options

It allows you to use LDAPS (LDAP over SSL) to establish a secure connection for the search. These options can be used only when LDAPS has been enabled and configured in your SSL-enabled directory server. Please see some of the useful SSL options below:

-P path

It is used to specify the path and filename of the client’s certificate database. for example: -P /home/username/.netscape/cert7.db . When using this command on the same host as the directory server, you may use the server’s own certificate database, for Example:-P installDir/slapd-serverID/alias/cert7.db. We can even use the -P option alone to specify server authentication only.

-Z

This will issue StartTLS (Transport Layer Security) extended operation. If you use -ZZ, the command will require the
operation to be successful. This option requires the -N and -W options and any other of the SSL options needed to identify the certificate and the key database.

-N certificate

It is used to specify the certificate name to use for certificate-based client authentication, for example: -N "Directory-Cert".

-m path

It is used to specify the path to the security module database. For example:

-m /usr/iplanet/servers/slapd-serverID/secmodule.db

You need to specify this option only if the security module database is in a different directory from the certificate database itself.

-K keyFile

It is used to specify the file and path name of the client’s private key database. This option may be ignored if the key database is in the location already given by the -P option.

-W password

It is used to specify the password for the client’s key database given in the -K or -P options. This option is recommended for certificate-based client authentication.

Test an LDAP connection

You can bind to your LDAP directory server by running this ldapsearch command from the client/server. I run this command from my client machine to my LDAP server and save the details in a text file.

root@ldapclient:~# ldapsearch -x -b " dc=ldap01,dc=linoxide,dc=com" >> all.txt
root@ldapclient:~# cat all.txt
# extended LDIF
#
# LDAPv3
# base < dc=ldap01,dc=linoxide,dc=com> with scope subtree
# filter: (objectclass=*)
# requesting: ALL
#

# ldap01.linoxide.com
dn: dc=ldap01,dc=linoxide,dc=com
objectClass: top
objectClass: dcObject
objectClass: organization
o: VIP
dc: ldap01

# admin, ldap01.linoxide.com
dn: cn=admin,dc=ldap01,dc=linoxide,dc=com
objectClass: simpleSecurityObject
objectClass: organizationalRole
cn: admin
description: LDAP administrator

# search result
search: 2
result: 0 Success

# numResponses: 3
# numEntries: 2

We can even use this command to return all entries in our preferred directory service using filters as below.

root@ldapclient:~# ldapsearch -x -b " dc=ldap01,dc=linoxide,dc=com" -s sub "objectclass=*"
# extended LDIF
#
# LDAPv3
# base < dc=ldap01,dc=linoxide,dc=com> with scope subtree
# filter: objectclass=*
# requesting: ALL
#

# ldap01.linoxide.com
dn: dc=ldap01,dc=linoxide,dc=com
objectClass: top
objectClass: dcObject
objectClass: organization
o: VIP
dc: ldap01

# admin, ldap01.linoxide.com
dn: cn=admin,dc=ldap01,dc=linoxide,dc=com
objectClass: simpleSecurityObject
objectClass: organizationalRole
cn: admin
description: LDAP administrator

# search result
search: 2
result: 0 Success

# numResponses: 3
# numEntries: 2

Conclusion

In this article, we've dealt with some of the useful options of ldapsearch command. You can get more information about the usages here.  Ldapsearch is one of the best tools to search for records in an LDB database. These options allow you to sort the results, limit how much information is returned, control how referrals are followed, enable a secure connection, set a time limit for the operation and much more. Results of the search are displayed as LDIF text to the standard output. The results may also be reformatted using command-line options.

Filed Under : MAIL SERVER

Tagged With :

Free Linux Ebook to Download

Leave a Reply

All comments are subject to moderation.