idsldapsearch, ldapsearch

Description

The idsldapsearch is a command-line interface to the ldap_search library call.

The idsldapsearch command opens a connection to an LDAP server, binds to the LDAP server, and does a search by using the filter. The filter must conform to the string representation for LDAP filters. For information about filters that are used in ldap_search, see Programming Reference section of the IBM Security Directory Server documentation.

If idsldapsearch finds one or more entries that match the filter, the attributes and its values that are specified by attributes are retrieved. The entries and attribute values are printed to a standard output. If no attributes are listed, all attributes are returned.

To see syntax help foridsldapsearch, type idsldapsearch -?.

Synopsis

ldapsearch [-b basedn] [options] filter [attributes...] 

• basedn: Specifies the base DN for a search. It is optional if the LDAP_BASEDN variable is set in the environment.
• filter: Specifies an LDAP search filter.
• attributes: Specifies a list of whitespace-separated attributes to retrieve, if no attribute list is specified all attributes are retrieved.

Options

-a deref

Specifies how to dereference aliases. The value of deref must be:

• never: specifies that aliases are never dereferenced
• always: specifies that aliases are always dereferenced
• search: specifies that aliases are dereferenced for searching
• find: specifies that aliases are dereferenced only when used to locate the base object for the search

The default behavior of deref is to never dereference aliases.

-A

Specifies to retrieve attributes only (no values). This option is useful when you want to see whether an attribute is present in an entry and is not interested in the specific values.

-b searchbase

Specifies to use searchbase as the starting point for the search, instead of the default. If -b is not specified, this utility examines the LDAP_BASEDN environment variable for a searchbase definition. If neither is set, the default base is set to "", which is a null search. To see all entries under a subtree, the search requires a -s subtree option. Otherwise, an error message is returned. Null based search requests use considerable system resource.

-B

Specifies not to suppress non-ASCII values from showing in output. This option is useful when you use values that contain character sets such as ISO-8859.1. This option is implied by the -L option.

-c pattern

Runs a persistent search. The pattern format must be ps:changeType[:changesOnly[:entryChangeControls]], where changeType can be operations such as add, delete, modify, moddn, and any. The changesOnly and entryChangeControls parameters can be set to TRUE or FALSE.

Note: When alias dereferencing option is find, then only the search base object is dereferenced if it is an alias. This means that even if it is a one-level or subtree search, the subordinate alias entries under the base are not expected to be dereferenced. If a persistent search reports changed entries, and the entry is an alias then it is dereferenced even though it is subordinate to the search base.

-C charset

Specifies a string to the command be represented in a local character set, as specified by charset. String input includes the filter, the bind DN, and the base DN. When search result is returned, idsldapsearch converts data that is received from the LDAP server to the specified character set. Also, if the -C option and the -L option are both specified, parameter is assumed to be in the specified character set. However, the output from idsldapsearch is always preserved in its UTF-8 representation, or a base-64 encoded representation of the data when non-printable characters are detected. The reason for the conversion is because standard LDIF files contain UTF-8 (or base-64 encoded UTF-8) representations of string data.

Use -C charset to override the default, where string must be supplied in UTF-8. For information about the specific charset values that are supported for each operating system, see Supported IANA character sets. The supported values for charset are the same values that are supported for the charset tag that is optionally defined in version 1 LDIF files.

-d debuglevel

Sets the LDAP debug level to debuglevel in LDAP library. This option causes the utility to generate debug output to stdout. The debuglevel is a bit mask that controls which output is generated with values from 1 to 65535. For information about debug levels, see Debugging levels.

-D bindDN

Specifies the bindDN to bind to an LDAP directory. The bindDN variable is a string-represented value. When used with -m DIGEST-MD5, it specifies the authorization ID. It can be either a DN or an authorization ID string that starts with dn: or u:.

-e

Specifies to show the LDAP library version information.

-E token_pw

Specifies the token password to access a crypto device.

-f file

Specifies to run searches by using the filters in the file file. For the filter, %s must be substituted.

-F sep

Specifies to use sep as the field separator between attribute names and values. The default separator is =, unless -L is specified, in which case this option is ignored.

-g before:after:index:count | before:after:value

The before and after values are the number of entries around index, count is the content count, and value is the assertion value for the primary sort key.

-G realm

Specifies the realm name. When used with -m DIGEST-MD5, the value is passed to the server during a bind.

-h ldaphost

Specifies the hostname of the system where an LDAP server is running.

-i file

Specifies to read a series of lines from file, and to run one LDAP search for each line. In this option, the filter that is provided to the command is treated as a pattern, where the first occurrence of %s is replaced with a line from file. If file is a single - character, then the lines are read from standard input.

For example, in this example, idsldapsearch -V3 -v -b "o=sample" -D "cn=admin" -w ldap -i filter.input %s dn, the filter.input file might contain the following filter information.

(cn=*Z)
(cn=*Z*)
(cn=Z*)
(cn=*Z*)
(cn~=A)
(cn>=A)
(cn<=B)

Note: Each filter must be specified on a separate line.

In the example, the command runs a search on o=sample for each of the filters that begin with cn=*Z. When the search is complete, another search begins for the next filter cn=*Z*, and then the next filter, until the search for the last filter cn<=B is completed.

Note: The -i file option replaces the -f file option. The -f option is still supported, although it is deprecated.

-I

Specifies a crypto device with key storage by using PKCS11.

-j limit

Specifies the maximum number of values that can be returned for an attribute within an entry. The default value is 0, which means unlimited.

-J limit

Specifies the maximum number of attributes that can be returned per entry. The default value is 0, which means unlimited.

-k

Specifies to send the server administration control. For more information about this control, see Programming Reference section of the IBM Security Directory Server documentation.

-K keyfile

Specifies the name of the SSL or TLS key database file with the default extension of kdb. If the key database file is not in the current directory, specify the fully qualified key database file name. If a key database file name is not specified, this utility first looks for the presence of the SSL_KEYRING environment variable with an associated file name. If the SSL_KEYRING environment variable is not defined, the default keyring file is used, if present.

A default keyring file, ldapkey.kdb, and the associated password stash file, ldapkey.sth, are installed in the etc directory in IDS_LDAP_HOME. Where, IDS_LDAP_HOME is the installation path of IBM® Security Directory Server. The value of the IDS_LDAP_HOME variable varies depending on the operating system. The default path on various operating system is listed.

• AIX® operating systems: /opt/IBM/ldap/V6.4
• Linux® operating systems: /opt/ibm/ldap/V6.4
• Solaris operating systems: /opt/IBM/ldap/V6.4
• Windows operating systems: C:\Program Files\IBM\ldap\V6.4
  Note: The C:\Program Files\IBM\ldap\V6.4 path is the default installation location. The actual IDS_LDAP_HOME is determined during the installation.

For information about the default key database files and default certificate authorities (CAs), see Programming Reference section of the IBM Security Directory Server documentation.

If a keyring database file cannot be located, a hard coded set of default trusted certificate authority roots is used. The key database file typically contains one or more certificates of CAs that are trusted by the client. These types of X.509 certificates are known as trusted roots. For information about managing an SSL or TLS key database, see Administering section of the IBM Security Directory Server documentation. Also, see the Security functions section.

This parameter effectively enables the -Z switch.

-l timelimit

Specifies to wait at most timelimit seconds for a search to complete.

-L

Specifies to show search results in LDIF format. This option activates the -B option, and causes the -F option to be ignored.

-m mechanism

Specifies the SASL mechanism to use when you bind to the server. The ldap_sasl_bind_s() API is used for this option. The -m parameter is ignored if -V 2 is set. If -m is not specified, simple authentication is used.

-M

Specifies to manage referral objects as regular entries.

-n

Specifies to demonstrate the action of the operation without actually doing it.

Tip: The -n parameter with the -v parameter is useful when you debug any related problem.

-N certificatename

Specifies the label that is associated with the client certificate in the key database file. If an LDAP server is configured to use server authentication only, a client certificate is not required. If the LDAP server is configured to use client and server authentication, a client certificate might be required. This parameter is not required if a default certificate / private key pair is assigned as the default. Similarly, certificatename is not required if there is a single certificate / private key pair in the designated key database file. This parameter is ignored if -Z or -K parameter is not specified.

-o attr_type

Specifies an attribute to use for sort criteria of search results, you can use the -o parameter. You can use multiple -o parameters to further define the sort order. In the example, the search results are sorted first by sn and then by givenname. The givenname values are sorted in reverse (descending) order, which is specified by the prefixed minus sign (-).

-o sn -o -givenname

The syntax of the sort parameter is

[-]attribute_name [:matching rule OID]

where,

• attribute_name is the name of the attribute you want to sort
• matching rule OID is the optional OID of a matching rule that you want to use for sorting
• - minus sigh indicates that the result must be ordered in reverse order
• The criticality for this option is always critical

By default, the idsldapsearch operation does not return result in the sorted order.

This option sends the Sorted search results control to the LDAP server. For information about sorted search results control, see Programming Reference section of the IBM Security Directory Server documentation.

-O maxhops

Specify maxhops to set the maximum number of hops that the client library takes when it chases the referrals. The default hop count is 10.

-p ldapport

Specifies a port for the LDAP server to listen. The default LDAP port is 389. If -p is not specified and -Z is specified, the default LDAP secure port, 636, is used.

-P keyfilepw

Specifies the key database password. Password is required to access the encrypted information in the key database file, which might include one or more private keys. If a password stash file is associated with the key database file, then the password is obtained from the password stash file. In this case, the -P parameter is not required. This parameter is ignored if -Z or -K is not specified.

-q pagesize

Specifies the page size for search results. To set page size for results, use the two parameters -q (query page size), and -T (time between searches in seconds).

Use the example values to return a page of 25 entries at a time, every 15 seconds until all the results for the search is returned.

-q 25 -T 15

The idsldapsearch client handles all connection continuation for each paged result request for the life of the search operation.

If the -v parameter is specified, idsldapsearch lists how many entries are returned.

You can provide multiple -q parameters to specify different page sizes throughout the life of a single search operation. Use the example values to specify that the first page is of 15 entries, the second page of 20 entries, and the third parameter to end the paged result.

-q 15 -q 20 -q 0

To specify the first page is of 15 entries, and the rest of the pages are of 20 entries, continuing with the last specified -q value until the search operation completes, use the example values.

-q 15 -q 20

By default, the idsldapsearch operation returns all entries in a single request. No paging is done for the default idsldapsearch operation.

This option sends the Paged search results control. For information about paged search results control, see Programming Reference section of the IBM Security Directory Server documentation.

-Q operation

Specifies the crypto device operation with PKCS11. The operation variable must be assigned one of the following values:

0: No accelerator mode
1: Symmetric 
2: Digest
3: Digest and Symmetric 
4: Random 
5: Random and Symmetric
6: Random and Digest
7: Random, Digest and Symmetric

-r

Specified to return deleted entries.

-R

Specifies not to chase referrals automatically.

-s scope

Specifies the scope of the search. The scope variable must be assigned one of the following values:

• base: specifies a base object search
• one: specifies a one-level search
• sub: specifies a subtree search

The default scope is sub.

-S token_label

Specifies the token label of the crypto device.

-t

Specifies to write retrieved values to a set of temporary files. This option is useful for dealing with non-ASCII values such as jpegPhoto or audio.

-T seconds

Specifies the time in seconds between searches. The -T option is only supported when the -q option is specified.

-U username

Specifies the user name. This name is required with -m DIGEST-MD5, and is ignored when any other mechanism is used. The value of username depends on what attribute the server is configured to use. It might be a uid or any other value that is used to locate the entry.

-v

Indicates to run in verbose mode.

-V

Specifies the LDAP protocol version to use. By default, an LDAP V3 connection is established. To explicitly select LDAP V3, specify -V 3. To run as an LDAP V2 application, specify -V 2.

-w passwd | ?

Specifies the password for authentication. Use the ? prompt to generate a non-echoed password prompt. In UNIX, use backslash \? to avoid matching single character file names. If you use the password prompt, it prevents your password from being visible through the ps command.

-x

Specifies to use FIPS mode processing. This mode is applicable with SSL or TLS only.

-X lib_path

Specifies the library path of the crypto device.

-y proxydn

Specifies the DN to use for proxied authorization.

-Y

Specifies to use a secure LDAP connection by using Transport Layer Security (TLS). The -Y option is only supported when GSKit is installed.

-z sizelimit

Specifies to limit the search results to at most sizelimit entries. This option makes it possible to place an upper bound on the number of entries that are returned for a search operation.

-Z

Specifies to use a secure LDAP connection by using Secure Sockets Layer (SSL) and Transport Layer Security (TLS). The -Z option is only supported for SSL component entry, and only when GSKit is installed.

-1 sec:usec

Specifies the timeout for the connect() function in seconds and microseconds. The values that are provided for seconds and microseconds must be positive integers.

-9 p

Sets criticality for paging to false. The search is handled without paging.

-9 s

Sets criticality for sorting to false. The search is handled without sorting.

filter

Specifies a string representation of the filter to apply in the search. Simple filters can be specified as attributetype=attributevalue. More complex filters are specified by using a prefix notation according to the following Backus Naur Form (BNF):

<filter> ::='('<filtercomp>')'
<filtercomp> ::= <and>|<or>|<not>|<simple>
<and> ::= '&' <filterlist>
<or> ::= '|' <filterlist>
<not> ::= '!' <filter>
<filterlist> ::= <filter>|<filter><filtertype>
<simple> ::= <attributetype><filtertype>
<attributevalue>
<filtertype> ::= '='|'~='|'<='|'>='

The ~= construct specifies an approximate matching. The representation for attributetype and attributevalue are as described in "RFC 2252, LDAP V3 Attribute Syntax Definitions". In addition, attributevalue can be a single * to achieve an attribute existence test, or can contain text and asterisks (*) interspersed to achieve substring matching.

For example, the filter mail=* finds any entries that have a mail attribute. The filter mail=*@student.of.life.edu finds any entries that have a mail attribute that ends in the specified string. To put parentheses in a filter, escape them with a backslash (\) character.

Note: A filter like cn=Bob *, where there is a space between Bob and the asterisk (*), matches "Bob Carter" but not "Bobby Carter" in IBM Directory. The space between "Bob" and the wildcard character (*) affects the outcome of a search by using filters.

For information about the complete description of allowed filters, see "RFC 2254, A String Representation of LDAP Search Filters".

attrs

Specifies a whitespace-separated list of attribute type names to return for each entry that matches the search filter. Individual attribute type names might be specified. Additionally, the following special notations can be used:

*

Indicates to return all attribute types other than operational attributes.

1.1

Specifies to return no attributes and requests the search to return only the matching distinguished names.

+

Indicates to return the operational attributes.

+ibmaci

Indicates to return the access control related operational attributes.

+ibmentry

Indicates to return the operational attributes that every entry contains, such as creatorsName, create_Timestamp, and modifiersname to name a few.

+ibmrepl

Indicates to return operational attributes that are related to replication.

+ibmpwdpolicy

Indicates to return operational attributes that are related to password policy.

++

Indicates to return ALL operational attributes, even attributes considered expensive to return such as ibm-allGroups and ibm-replicationPendingChanges.

++ibmaci

Includes ALL access control related operational attributes.

++ibmentry

Includes ALL operational attributes that every entry contains such as numsubordinates and ibm-entryChecksum.

++ibmrepl

Includes ALL operational attributes that are related to replication.

++ibmpwdpolicy

Includes ALL operational attributes that are related to password policy.

-?

Specifies to show the syntax format.

Output format

Distinguished Name (DN)

attributename=value

attributename=value

attributename=value

…

Exit status

Security functions

See also