ldapsearch — perform LDAP search operations

Synopsis

ldapsearch {options} filter [attributes ...]

Description

This utility can be used to perform LDAP search operations in the Directory Server.

Options

The ldapsearch command takes the following options:

Command options:

-a | --dereferencePolicy {dereferencePolicy}

Alias dereference policy ('never', 'always', 'search', or 'find').

Default: never

-A | --typesOnly

Only retrieve attribute names but not their values.

Default: false

--assertionFilter {filter}

Use the LDAP assertion control with the provided filter.

-b | --baseDn {baseDN}

Search base DN.

-c | --continueOnError

Continue processing even if there are errors.

Default: false

-C | --persistentSearch ps[:changetype[:changesonly[:entrychgcontrols]]]

Use the persistent search control.

A persistent search allows the client to continue receiving new results whenever changes are made to data that is in the scope of the search, thus using the search as a form of change notification.

The optional changetype setting defines the kinds of updates that result in notification. If you do not set the changetype, the default behavior is to send notifications for all updates.

add

Send notifications for LDAP add operations.

del, delete

Send notifications for LDAP delete operations.

mod, modify

Send notifications for LDAP modify operations.

moddn, modrdn, modifydn

Send notifications for LDAP modify DN (rename and move) operations.

all, any

Send notifications for all LDAP update operations.

The optional changesonly setting defines whether the server returns existing entries as well as changes.

true

Do not return existing entries, but instead only notifications about changes.

This is the default setting.

false

Also return existing entries.

The optional entrychgcontrols setting defines whether the server returns an Entry Change Notification control with each entry notification. The Entry Change Notification control provides additional information about the change that caused the entry to be returned by the search. In particular, it indicates the change type, the change number if available, and the previous DN if the change type was a modify DN operation.

true

Do request the Entry Change Notification control.

This is the default setting.

false

Do not request the Entry Change Notification control.

--countEntries

Count the number of entries returned by the server.

Default: false

-e | --getEffectiveRightsAttribute {attribute}

Specifies geteffectiverights control specific attribute list.

-g | --getEffectiveRightsAuthzId {authzID}

Use geteffectiverights control with the provided authzid.

-G | --virtualListView {before:after:index:count | before:after:value}

Use the virtual list view control to retrieve the specified results page.

-J | --control {controloid[:criticality[:value|::b64value|:<filePath]]}

Use a request control with the provided information.

For some controloid values, you can replace object identifiers with user-friendly strings. The values are not case-sensitive:

Assertion, LdapAssertion

Assertion Request Control, Object Identifier: 1.3.6.1.1.12

AccountUsable, AccountUsability

Account Usability Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.8

AuthzId, AuthorizationIdentity

Authorization Identity Request Control, Object Identifier: 2.16.840.1.113730.3.4.16

Csn, ChangeNumber, ChangeSequenceNumber

Change Sequence Number Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.9

This is an internal DS server control.

EffectiveRights, GetEffectiveRights

Get Effective Rights Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.9.5.2

ManageDsaIt

Manage DSAIT Request Control, Object Identifier: 2.16.840.1.113730.3.4.2

Noop, No-Op

No-Op Request Control, Object Identifier: 1.3.6.1.4.1.4203.1.10.2

PwdPolicy, PasswordPolicy

Password Policy Request Control, Object Identifier: 1.3.6.1.4.1.42.2.27.8.5.1

PasswordQualityAdvice

Password Quality Advice Request Control, Object Identifier: 1.3.6.1.4.1.36733.2.1.5.5

PermissiveModify

Permissive Modify Request Control, Object Identifier: 1.2.840.113556.1.4.1413

PSearch, PersistentSearch

Persistent Search Request Control, Object Identifier: 2.16.840.1.113730.3.4.3

PostRead

Post Read Request Control, Object Identifier: 1.3.6.1.1.13.2

PreRead

Pre Read Request Control, Object Identifier: 1.3.6.1.1.13.1

ProxiedAuthV1

Proxied Authorization Request Control V1, Object Identifier: 2.16.840.1.113730.3.4.12

ProxiedAuth, ProxiedAuthV2

Proxied Authorization Request Control V2, Object Identifier: 2.16.840.1.113730.3.4.18

RealAttrsOnly, RealAttributesOnly

Real Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.17

RelaxRules

Relax Rules Request Control, Object Identifier: 1.3.6.1.4.1.4203.666.5.12

TreeDelete, SubTreeDelete

Subtree Delete Request Control, Object Identifier: 1.2.840.113556.1.4.805

Sort, ServerSideSort

Server Side Sort Request Control, Object Identifier: 1.2.840.113556.1.4.473

PagedResults, SimplePagedResults

Simple Paged Results Control, Object Identifier: 1.2.840.113556.1.4.319

SubEntries

Sub-Entries Request Control, Object Identifier: 1.3.6.1.4.1.4203.1.10.1

TxnId, TransactionId

Transaction ID Control, Object Identifier: 1.3.6.1.4.1.36733.2.1.5.1

This is an internal ForgeRock control.

VirtualAttrsOnly, VirtualAttributesOnly

Virtual Attributes Only Request Control, Object Identifier: 2.16.840.1.113730.3.4.19

Vlv, VirtualListView

Virtual List View Request Control, Object Identifier: 2.16.840.1.113730.3.4.9

-l | --timeLimit {timeLimit}

Maximum length of time in seconds to allow for the search.

Default: 0

--matchedValuesFilter {filter}

Use the LDAP matched values control with the provided filter.

-n | --dry-run

Show what would be done but do not perform any operation and do not contact the server.

Default: false

-s | --searchScope {searchScope}

Search scope ('base', 'one', 'sub', or 'subordinates'). Note: 'subordinates' is an LDAP extension that might not work with all LDAP servers.

Default: sub

-S | --sortOrder {sortOrder}

Use the server side sort control to have the server sort the results using the provided sort order. You can provide multiple comma separated sort keys. Sort key must respect the following pattern: "[-] attributeType [:OrderingRuleNameOrOID]". Minus character represent a descending sort order.

--simplePageSize {numEntries}

Use the simple paged results control with the given page size.

Default: 1000

--subEntries

Use subentries control to specify that subentries are visible and normal entries are not.

Default: false

-Y | --proxyAs {authzID}

Use the proxied authorization control with the given authorization ID.

-z | --sizeLimit {sizeLimit}

Maximum number of entries to return from the search.

Default: 0

LDAP connection options:

--connectTimeout {timeout}

Maximum length of time (in milliseconds) that can be taken to establish a connection. Use '0' to specify no time out.

Default: 30000

-D | --bindDn {bindDN}

DN to use to bind to the server.

Default:

-E | --reportAuthzId

Use the authorization identity control.

Default: false

-h | --hostname {host}

Fully-qualified server host name or IP address.

Default: localhost.localdomain

-N | --certNickname {nickname}

Nickname of the certificate that should be sent to the server for SSL client authentication.

-o | --saslOption {name=value}

SASL bind options.

-p | --port {port}

Directory server port number.

-q | --useStartTls

Use StartTLS to secure communication with the server.

Default: false

-T | --trustStorePassword {trustStorePassword}

Truststore cleartext password.

--useJavaKeyStore {keyStorePath}

JKS keystore containing the certificate which should be used for SSL client authentication.

--useJavaTrustStore {trustStorePath}

Use a JKS truststore file for validating server certificate.

--useJceKeyStore {keyStorePath}

JCEKS keystore containing the certificate which should be used for SSL client authentication.

--useJceTrustStore {trustStorePath}

Use a JCEKS truststore file for validating server certificate.

--useJvmTrustStore

Use the a JVM truststore for validating server certificate.

Default: false

--usePasswordPolicyControl

Use the password policy request control.

Default: false

--usePkcs11KeyStore

PKCS#11 keystore containing the certificate which should be used for SSL client authentication.

Default: false

--usePkcs12KeyStore {keyStorePath}

PKCS#12 keystore containing the certificate which should be used for SSL client authentication.

--usePkcs12TrustStore {trustStorePath}

Use a PKCS#12 truststore file for validating server certificate.

-w | --bindPassword {bindPassword}

Password to use to bind to the server. Omit this option while providing the bind DN to ensure that the command prompts for the password, rather than entering the password as a command argument.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

-X | --trustAll

Trust all server SSL certificates.

Default: false

-Z | --useSsl

Use SSL for secure communication with the server.

Default: false

Utility input/output options:

--no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail.

Default: false

--noPropertiesFile

No properties file will be used to get default command line argument values.

Default: false

--propertiesFilePath {propertiesFilePath}

Path to the file containing default property values used for command line arguments.

-t | --wrapColumn {wrapColumn}

Maximum length of an output line (0 for no wrapping).

Default: 0

-v | --verbose

Use verbose mode.

Default: false

General options:

-V | --version

Display Directory Server version information.

Default: false

-H | --help

Display this usage information.

Default: false

Filters

The filter argument is a string representation of an LDAP search filter as in (cn=Babs Jensen), (&(objectClass=Person)(|(sn=Jensen)(cn=Babs J*))), or (cn:caseExactMatch:=Fred Flintstone).

Attributes

The optional attribute list specifies the attributes to return in the entries found by the search. In addition to identifying attributes by name such as cn sn mail and so forth, you can use the following notations, too.

*

Return all user attributes such as cn, sn, and mail.

+

Return all operational attributes such as etag and pwdPolicySubentry.

@objectclass

Return all attributes of the specified object class, where objectclass is one of the object classes on the entries returned by the search.

1.1

Return no attributes, only the DNs of matching entries.

Exit Codes

0

The command completed successfully.

ldap-error

An LDAP error occurred while processing the operation.

LDAP result codes are described in RFC 4511. Also see the additional information for details.

89

An error occurred while parsing the command-line arguments.

Files

You can use ~/.opendj/tools.properties to set the defaults for bind DN, host name, and port number as in the following example:

hostname=directory.example.com
port=1389
bindDN=uid=kvaughan,ou=People,dc=example,dc=com

ldapcompare.port=1389
ldapdelete.port=1389
ldapmodify.port=1389
ldappasswordmodify.port=1389
ldapsearch.port=1389

Examples

The following example searches for entries with UID containing jensen, returning DNs and UIDs:

$ ldapsearch \
 --port 1389 \
 --baseDn dc=example,dc=com \
 "(uid=*jensen*)" \
 uid
dn: uid=ajensen,ou=People,dc=example,dc=com
uid: ajensen

dn: uid=bjensen,ou=People,dc=example,dc=com
uid: bjensen

dn: uid=gjensen,ou=People,dc=example,dc=com
uid: gjensen

dn: uid=jjensen,ou=People,dc=example,dc=com
uid: jjensen

dn: uid=kjensen,ou=People,dc=example,dc=com
uid: kjensen

dn: uid=rjensen,ou=People,dc=example,dc=com
uid: rjensen

dn: uid=tjensen,ou=People,dc=example,dc=com
uid: tjensen


Result Code:  0 (Success)

You can also use @objectclass notation in the attribute list to return the attributes of a particular object class. The following example shows how to return attributes of the inetOrgPerson object class:

$ ldapsearch \
 --port 1389 \
 --baseDn dc=example,dc=com \
 "(uid=bjensen)" \
 @inetorgperson
dn: uid=bjensen,ou=People,dc=example,dc=com
givenName: Barbara
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: posixAccount
objectClass: top
uid: bjensen
cn: Barbara Jensen
cn: Babs Jensen
telephoneNumber: +1 408 555 1862
sn: Jensen
roomNumber: 0209
mail: bjensen@example.com
l: San Francisco
ou: Product Development
ou: People
facsimileTelephoneNumber: +1 408 555 1992

You can use + in the attribute list to return all operational attributes, as in the following example:

$ ldapsearch \
 --port 1389 \
 --baseDn dc=example,dc=com \
 "(uid=bjensen)" \
 +
dn: uid=bjensen,ou=People,dc=example,dc=com
numSubordinates: 0
structuralObjectClass: inetOrgPerson
etag: 0000000073c29972
subschemaSubentry: cn=schema
hasSubordinates: false
entryDN: uid=bjensen,ou=people,dc=example,dc=com
entryUUID: fc252fd9-b982-3ed6-b42a-c76d2546312c
Read a different version of :