Using Advanced Search Features

The directory server supports LDAPv3-compliant search functionality by using the ldapsearch command. You can use special attributes, security options, and LDAP controls with the search process, based on your system configuration. For additional information, see Searching Directory Data, Using a Properties File With Server Commands in Oracle Fusion Middleware Command-Line Usage Guide for Oracle Unified Directory, and ldapsearch in Oracle Fusion Middleware Command-Line Usage Guide for Oracle Unified Directory.

Searching for Special Entries and Attributes

This section describes how to search for operational attributes and how to search the Root DSE entry.

To Search for Operational Attributes

Operational attributes are used for storing information needed for processing by the directory server itself or for holding any other data maintained by the directory server that was not explicitly provided by clients. Operational attributes are not included in entries returned from search operations unless they are explicitly included in the list of search attributes. You can request the directory server to return operational attributes by adding + (the plus sign) in your ldapsearch command.

Run the ldapsearch command with the + character.

You must escape the character using a means appropriate to your shell.

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" \
  -w password -b "dc=example,dc=com" "(objectclass=*)" "+" 
...
dn: cn=PD Managers,ou=groups,dc=example,dc=com 
numSubordinates: 0 
hasSubordinates: false 
subschemaSubentry: cn=schema 
entryDN: cn=pd managers,ou=groups,dc=example,dc=com
entryUUID: 38666d52-7a53-332e-902f-e34dd4aaa7a0
...

To Search the Root DSE Entry

The Root DSE is a special entry that provides information about the server's name, version, naming contexts, and supported features. Because many of the attributes are operational, you must specify + (the plus sign) to display the attributes of the Root DSE entry.

Run the ldapsearch command with a baseDN of "".

Specify the scope as base and include the + character to display operational attributes.

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" \
  -w password -b "" --searchScope base "(objectclass=*)" "+"
dn: 
supportedExtension: 1.3.6.1.4.1.4203.1.11.3 
supportedExtension: 1.3.6.1.4.1.4203.1.11.1 
supportedExtension: 1.3.6.1.4.1.26027.1.6.2 
supportedExtension: 1.3.6.1.4.1.26027.1.6.1 
supportedExtension: 1.3.6.1.1.8 
supportedExtension: 1.3.6.1.4.1.1466.20037 
...

To Search for ACI Attributes

The directory server stores access control instructions (ACIs) as one or more values of the aci attribute on an entry to allow or deny access to the directory database. The aci attribute is a multi-valued operational attribute that can be read and modified by directory users and that should itself be protected by ACIs. Administrative users are usually given full access to the aci attribute and can view its values by running an ldapsearch command.

Run the ldapsearch command as follows:

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" \
  -w password -b dc=example,dc=com --searchScope base "(aci=*)" aci  
dn: dc=example,dc=com 
aci: (target ="ldap:///dc=example,dc=com")(targetattr h3.="userPassword")
  (version 3.0;acl "Anonymous read-search access";allow (read, search, compare)
  (userdn = "ldap:///anyone");) 
aci: (target="ldap:///dc=example,dc=com") (targetattr = "*")
  (version 3.0; acl "allow all Admin group"; allow(all) 
  groupdn = "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)

To Search the Schema Entry

The directory server holds schema information in the schema entry (cn=schema) for the object classes and attributes defined on your instance.

Run the ldapsearch command on the cn=schema base DN.

Because the attributes in the schema are operational attributes, you must include "+" at the end of your search.

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" \
  -w password -b cn=schema --searchScope base "(objectclass=*)" "+"
dn: cn=schema
nameForms: ( 1.3.6.1.1.10.15.1 NAME 'uddiBusinessEntityNameForm' OC uddiBusiness
 Entity MUST ( uddiBusinessKey ) X-ORIGIN 'RFC 4403' )
nameForms: ( 1.3.6.1.1.10.15.2 NAME 'uddiContactNameForm' OC uddiContact MUST 
 (uddiUUID ) X-ORIGIN 'RFC 4403' )
nameForms: ( 1.3.6.1.1.10.15.3 NAME 'uddiAddressNameForm' OC uddiAddress MUST 
 (uddiUUID ) X-ORIGIN 'RFC 4403' )
...
attributeTypes: ( 1.3.6.1.1.1.1.12 NAME 'memberUid' EQUALITY caseExactIA5Match 
 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 X-ORIGIN 'draft-howard-rfc2307bis' )
attributeTypes: ( 1.3.6.1.1.1.1.13 NAME 'memberNisNetgroup' EQUALITY caseExactIA
 5Match SUBSTR caseExactIA5SubstringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.26
 X-ORIGIN 'draft-howard-rfc2307bis' )
attributeTypes: ( 1.3.6.1.1.1.1.14 NAME 'nisNetgroupTriple' DESC 'Netgroup 
 triple' EQUALITY caseIgnoreIA5Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 X-ORIGIN 
 'draft-howard-rfc2307bis' )
...

To Search the Configuration Entry

The directory server stores its configuration under the cn=config entry. Direct access to this entry over LDAP is not advised. The configuration is accessible and modifiable by using the dsconfig command. dsconfig connects to the directory server over SSL via the administration connector. For more information, see Managing Administration Traffic to the Server.

To search the configuration entry using dsconfig in interactive mode, run the command as follows:
```
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -w password
```
For more information about accessing the server configuration by using dsconfig, see Managing the Server Configuration With dsconfig.

To Search the Monitoring Entry

The directory server monitor entry cn=monitor provides statistical information about the server performance, state, and version. You can access this information by using the ldapsearch command.

Although you can access cn=monitor using any configured LDAP connection handler, it is recommended that you use the administration connector for all access to administrative suffixes. Using the administration connector ensures that monitoring data is not polluted and that server administration takes precedence over user traffic. To use the administration connector, specify the administration port, and include the --useSSL option. For more information, see Managing Administration Traffic to the Server.

Run the ldapsearch command on the base DN cn=monitor.

$ ldapsearch -h localhost -p 4444 --useSSL -D "cn=Directory Manager" \
  -w password -b cn=monitor "(objectclass=*)"
dn: cn=monitor
startTime: 20110119135658Z
objectClass: extensibleObject
objectClass: top
objectClass: ds-monitor-entry
cn: monitor
vendorName: Oracle Corporation
currentTime: 20110125145650Z
vendorVersion: Oracle Unified Directory 11.1.1.5.0
maxConnections: 3
productName: Oracle Unified Directory
currentConnections: 1
totalConnections: 22
upTime: 6 days 0 hours 59 minutes 52 seconds
...

Searching Over SSL

If you have configured the directory server to accept SSL connections by using a self-signed certificate or certificate, you can search using client authentication. The following procedures show how to search the directory over SSL using various authentication mechanisms.

To Search Over SSL With Blind Trust

You can configure the client to automatically trust any certificate that the server presents to it. However, this method is not secure and is vulnerable to man-in-the-middle attacks. Generally, you should use this type of authentication for testing purposes only.

Run the ldapsearch command with the --trustAll option.

The following command searches the Root DSE.

$ ldapsearch -h localhost -p 1636 --useSSL --trustAll -b "" \
  --searchScope base "(objectClass=*)"

To Search Over SSL Using a Trust Store

You can configure the client to use a certificate trust store, which contains information about the certificates it can trust. The client can check any server certificate to those listed in its trust store. If the client finds a match, a secure communication can take place with the server. If no match is found, the server cannot be trusted. You must ensure that the presented certificate is valid and add it to the trust store, which then allows secure communication.

Run the ldapsearch command with the --trustStorePath option.

The following command searches the Root DSE using a trust store.

$ ldapsearch -h localhost -p 1636 --useSSL \
  --trustStorePath /home/scarter/security/cert.db -b "" \
  --searchScope base "(objectClass=*)"

To Search Over SSL With No Trust Store

If no trust store is specified, you are prompted as to whether the certificate that was presented to the client should be trusted.

Run the ldapsearch command without the --trustStorePath option.

The following command searches the Root DSE without using a trust store.

$ ldapsearch -h localhost -p 1636 --useSSL -b "" \
  --searchScope base "(objectclass=*)"
The server is using the following certificate: 
Subject DN: CN=example.com, O=Example Corp, C=US
Issuer DN: CN=example.com, O=Example Corp, C=US
Validity: Fri Mar 02 16:48:17 CST 2007 through Thu May 31 17:48:17 CDT 2007
Do you wish to trust this certificate and continue connecting to the server?
Please enter "yes" or "no": yes

dn: objectClass: ds-rootDSE
objectClass: top

To Search Over SSL Using a Keystore

If the client is required to present its own certificate to the directory server, that client must know which certificate keystore to use. The client can determine the certificate keystore by specifying the --keyStorePath option with either the --keyStorePassword or --keyStorePasswordFile. This scenario typically occurs when the client performs a SASL EXTERNAL authentication or if the server always requires the client to present its own certificates.

Run the ldapsearch command with the --keyStore... options.

The following command searches the Root DSE using a trust store and a key store.

$ ldapsearch -h localhost -p 1636 --useSSL \
  --keyStorePath /home/scarter/security/key.db \
  --keyStorePasswordFile /home/keystore.pin \
  --trustStorePath /home/scarter/security/cert.db --useSASLExternal -b "" \
  --searchScope base "(objectClass=*)"

To Search Using StartTLS

The process for using StartTLS with the ldapsearch utility is very similar to the process for using SSL. However, you must do the following:

Use the port on which the server is listening for unencrypted LDAP requests
Indicate that StartTLS should be used instead of SSL (that is, use the --startTLS option instead of the --useSSL option).

Run the ldapsearch command with the --startTLS option.
The following command searches the Root DSE using startTLS.
```
$ ldapsearch -h localhost -p 1389 --startTLS \
  -b "" --searchScope base "(objectClass=*)"
```

To Search Using SASL With DIGEST-MD5 Client Authentication

The directory server supports a number of Simple Authentication and Security Layer (SASL) mechanisms. DIGEST-MD5 is one form of SASL authentication to the server that does not expose the clear-text password.

Run the ldapsearch command with the appropriate --saslOption options.
The authid option specifies the identity of the user that is authenticating to the server. The option can be in the form of a dn (for example, dn:uid=scarter,dc=example,dc-com) or a user name (for example, authid=u:sam.carter). The attribute can be used to indicate that the search operation should be performed under the authority of another user after authentication. The realm specifies the fully qualified name of the server host machine and is optional.
This example searches the Root DSE.
```
$ ldapsearch -h localhost -p 1636 --useSSL \
  --trustStorePath /home/cert.db --certNickName "my-cert" -w - \ 
  --saslOption mech=DIGEST-MD5 --saslOption realm="example.com" \ 
  --saslOption authid="dn:uid=scarter,dc=example,dc=com" -b "" "(objectclass=*)"
```

To Search Using SASL With the GSSAPI Mechanism

The GSSAPI mechanism performs authentication in a Kerberos environment and requires that the client system be configured to participate in such an environment.

Run the ldapsearch command to search as a user who already has a valid Kerberos session.
The authid attribute specifies the authentication ID that should be used to identify the user.
This example searches the Root DSE.
```
$ ldapsearch -h localhost -p 1389 \
  --saslOption mech=GSSAPI --saslOption authid="dn:uid=scarter,dc=example,dc=com" \
  --searchScope "" -b "" "(objectclass=*)"
```

To Search Using SASL With the PLAIN Mechanism

The PLAIN mechanism performs authentication in a manner similar to LDAP simple authentication except that the user is identified in the form of an authorization ID rather than a full DN.

Run the ldapsearch command to search as a user who already has a valid Kerberos session.
The authid attribute specifies the authentication ID that should be used to identify the user.
This example searches the Root DSE.
```
$ ldapsearch -h localhost -p 1389 \
  --saslOption mech=PLAIN --saslOption authid="dn:uid=scarter,dc=example,dc=com" \
  --searchScope "" -b "" "(objectclass=*)"
```

Searching Using Controls

LDAP controls extend the functionality of LDAP commands, such as ldapsearch, to carry out additional operations on top of the search. Each control is defined as an object identifier (OID) that uniquely identifies the control, a criticality flag, and any associated values. If the client sets the criticality flag when sending the control to the directory server, the directory server must either perform the operation with the control or not process it. If the flag is not set by the client, the directory server is free to ignore the control if it cannot process it.

You can use multiple controls in a single operation, such as the virtual list view with server-side sorting. The virtual list view control requires additional explanation and is therefore described in its own section, following this one.

To View the Available Controls

You can view the current list of controls for your directory server by searching the Root DSE entry for the supportedControl attribute.

Run the ldapsearch command on the Root DSE entry.

$ ldapsearch -h localhost -p 1389 -b "" --searchScope base \ 
  "(objectclass=*)" supportedControl
dn:
supportedControl: 1.2.826.0.1.3344810.2.3
supportedControl: 1.2.840.113556.1.4.319
supportedControl: 1.2.840.113556.1.4.473
supportedControl: 1.2.840.113556.1.4.805
supportedControl: 1.3.6.1.1.12
supportedControl: 1.3.6.1.1.13.1
supportedControl: 1.3.6.1.1.13.2
supportedControl: 1.3.6.1.4.1.26027.1.5.2
supportedControl: 1.3.6.1.4.1.42.2.27.8.5.1
supportedControl: 1.3.6.1.4.1.42.2.27.9.5.2
supportedControl: 1.3.6.1.4.1.42.2.27.9.5.8
supportedControl: 1.3.6.1.4.1.4203.1.10.2
supportedControl: 1.3.6.1.4.1.4203.1.10.1
supportedControl: 2.16.840.1.113730.3.4.12
supportedControl: 2.16.840.1.113730.3.4.16
supportedControl: 2.16.840.1.113730.3.4.17
supportedControl: 2.16.840.1.113730.3.4.18
supportedControl: 2.16.840.1.113730.3.4.19
supportedControl: 2.16.840.1.113730.3.4.2
supportedControl: 2.16.840.1.113730.3.4.3
supportedControl: 2.16.840.1.113730.3.4.9

The controls are returned as a list of OIDs. See the following table for a description of the control that corresponds to each OID. Note that not all of these controls can be used with the ldapsearch command.

OID	Control
`1.2.826.0.1.3344810.2.3`	Matched Values Control
`1.2.840.113556.1.4.319`	Simple Paged Results Control
`1.2.840.113556.1.4.473`	Server-Side Sort Control
`1.2.840.113556.1.4.805`	Subtree Delete Control
`1.3.6.1.1.12`	LDAP Assertion Control
`1.3.6.1.1.13.1`	LDAP Pre-Read Control
`1.3.6.1.1.13.2`	LDAP Post-Read Control
`1.3.6.1.4.1.26027.1.5.2`	Replication Repair Control
`1.3.6.1.4.1.42.2.27.8.5.1`	Password Policy control
`1.3.6.1.4.1.42.2.27.9.5.2`	Get Effective Rights Control
`1.3.6.1.4.1.42.2.27.9.5.8`	Account Usability Request Control
`1.3.6.1.4.1.4203.1.10.2`	LDAP No-Op Control
`1.3.6.1.4.1.4203.1.10.1`	LDAP Subentry Request Control
`2.16.840.1.113730.3.4.12`	Proxied Authorization v1 Control
`2.16.840.1.113730.3.4.16`	Authorization Identity Control
`2.16.840.1.113730.3.4.17`	Real Attributes Only Control
`2.16.840.1.113730.3.4.18`	Proxied Authorization v2 Control
`2.16.840.1.113730.3.4.19`	Virtual Attributes Only Control
`2.16.840.1.113730.3.4.2`	Manage DSA IT Control
`2.16.840.1.113730.3.4.3`	Persistent Search Control
`2.16.840.1.113730.3.4.9`	Virtual List View Control

To Search Using the Account Usability Request Control

The Account Usability Request Control determines if a user account can be used to authenticate to a server. If the user account is available, the control adds a message before any entry about whether the account is usable.

You can specify the Account Usability Request Control with ldapsearch in the following ways:

OID. Use the --control or -J option with the Account Usability Request Control OID: 1.3.6.1.4.1.42.2.27.9.5.8 with no value.
Named constant. Use a named constant, accountusable or accountusability, with the --control or -J option, instead of using the Account Usability Request Control OID. For example, use -J accountusable or -J accountusability with the ldapsearch command.

Use the ldapsearch command with the --control option or its short form -J.

$ ldapsearch -h localhost -p 1389 -b "dc=example,dc=com" \
  --searchScope sub -J "accountusability:true" "(objectclass=*)"
# Account Usability Response Control
# The account is usable
dn: dc=example,dc=com
objectClass: domain
objectClass: top
dc: example
...

To Search Using the Authorization Identity Request Control

The Authorization Identity Request Control allows the client to obtain the authorization identity for the client connection during the LDAP bind request. The authorization ID returned by the server is displayed to the client as soon as authentication has completed. The line containing the authorization ID is prefixed with a # character, making it a comment if the output is to be interpreted as an LDIF.

You can specify the Authorization Identity Request Control with ldapsearch in a number of ways:

OID. Use the --control or -J option with the Authorization Identity Request Control OID: 2.16.840.1.113730.3.4.16 with no value.
Named constant. Use a named constant, authzid or authorizationidentity with the -control or -J option instead of using the Authorization Identity Request Control OID. For example, use -J authzid or -J authorizationidentity with the ldapsearch command.

Use the ldapsearch command with the --reportAuthzID option.

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" \
  -w password -b dc=example,dc=com --searchScope base \
  --reportAuthzID "(objectclass=*)"
# Bound with authorization ID dn:cn=Directory Manager,cn=Root DNs,cn=config
dn: dc=example,dc=com
objectClass: domain
objectClass: top
dc: example

To Search Using the Get Effective Rights Control

The Get Effective Rights Control enables you to evaluate existing or new ACIs and to see the effective rights that they grant for a user on a specified entry.

The response to this control is to return the effective rights information about the entries and attributes in the search results. This extra information includes read and write permissions for each entry and for each attribute in each entry. The permissions can be requested for the bind DN used for the search or for an arbitrary DN, allowing administrators to test the permissions of directory users.

The ldapsearch command provides two ways to use the Get Effective Rights Control:

Use -J effectiverights or the OID -J "1.3.6.1.4.1.42.2.27.9.5.2". The request only takes an authorization ID (authzid). If you specify a NULL value for the authorization ID (authzid), the bind user is used as the authzid.
Use -g dn:"dn". The command option shows the effective rights of the user binding with the given DN. You can use this option together with the -e option to include the effective rights on the named attributes. You can use the option to determine if a user has permission to add an attribute that does not currently exist in an entry.

Note - You cannot use the -g option with the -J option.

To view effective rights, you should specify the virtual attributes aclRights and aclRightsInfo, which are generated by the server in response to the effective rights request. Thus, you should not use these attributes in search commands of any kind.

Use the ldapsearch command to display the effective rights of all users.

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \
  -b dc=example,dc=com -J effectiverights "(objectclass=*)" aclRights  

dn: dc=example,dc=com 
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

dn: ou=Groups, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

dn: ou=People, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

dn: cn=Accounting Managers,ou=groups,dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

dn: cn=HR Managers,ou=groups,dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

...

Use the ldapsearch command to display the effective rights of a specific user.

This example uses the --getEffectiveRightsAuthzid option. You can also use the --control or -J option, such as -J geteffectiverights.

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \
  -b dc=example,dc=com \
  --getEffectiveRightsAuthzid "dn:uid=scarter,ou=People,dc=example,dc=com" \
  "(uid=scarter)" aclRights
dn: uid=scarter,ou=People,dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:1,proxy:0

Use the ldapsearch command to display effective rights information for a specific user.

The aclRightsInfo attribute provides more detailed logging information that explains how effective rights are granted or denied.

ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \
  -b dc=example,dc=com \ 
  --getEffectiveRightsAuthzid "dn:uid=scarter,ou=People,dc=example,dc=com"\
  "(uid=scarter)" aclRightsInfo

dn: uid=scarter,ou=People,dc=example,dc=com
aclRightsInfo;logs;entryLevel;add: acl_summary(main): access not allowed(add) on 
entry/attr(uid=scarter,ou=People,dc=example,dc=com, NULL) to 
 (uid=scarter,ou=People,dc=example,dc=com) 
(not proxied) ( reason: no acis matched the subject )
aclRightsInfo;logs;entryLevel;proxy: acl_summary(main): access not allowed(proxy ) on 
entry/attr(uid=scarter,ou=People,dc=example,dc=com, NULL) to 
 (uid=scarter, ou=People,dc=example,dc=com) 
(not proxied) ( reason: no acis matched the subject )
aclRightsInfo;logs;entryLevel;write: acl_summary(main): access allowed(write) on  
entry/attr(uid=scarter,ou=People,dc=example,dc=com, NULL) to 
 (uid=scarter,ou=People,dc=example,dc=com) 
(not proxied) ( reason: evaluated allow , deciding_aci : Allow self entry modification)
aclRightsInfo;logs;entryLevel;read: acl_summary(main): access allowed(read) on 
entry/attr(uid=scarter,ou=People,dc=example,dc=com, NULL) to 
 (uid=scarter,ou=People,dc=example,dc=com) 
(not proxied) ( reason: evaluated allow , deciding_aci: Anonymous extended 
 operation access)
aclRightsInfo;logs;entryLevel;delete: acl_summary(main): access not allowed(delete) on 
entry/attr(uid=scarter,ou=People,dc=example,dc=com, NULL) to 
 (uid=scarter,ou=People,dc=example,dc=com) 
(not proxied) ( reason: no acis matched the subject )

To Search Using the LDAP Assertion Control

The LDAP Assertion Control allows you to specify a condition that must evaluate to true for the searching operation to process. The value of the control should be in the form of an LDAP search filter. The server tests the base object before searching for entries that match the search scope and filter. If the assertion fails, no entries are returned.

This example determines first if the assertion is met, and returns the entry if it matches the search filter.

Run the ldapsearch command with the --assertionFilter option using the assertion (objectclass=top).

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \
  -b "cn=HR Managers,ou=Groups,dc=example,dc=com" \ -s sub \
  --assertionFilter "(objectclass=top)" "(objectclass=*)"  
dn: cn=HR Managers,ou=groups,dc=example,dc=com
objectClass: groupOfUniqueNames
objectClass: top
ou: groups
description: People who can manage HR entries
uniqueMember: uid=kvaughan, ou=People, dc=example,dc=com
uniqueMember: uid=cschmith, ou=People, dc=example,dc=com
cn: HR Managers

To Search Using the LDAP Subentry Control

The LDAP Subentry Control allows the client to request that the server return only entries with the ldapSubEntry object class during a search operation. LDAP subentries are operational objects, similar to operational attributes, that are returned only if they are explicitly requested. Typically, you can use the control when searching the schema.

You request the server to return subentries with ldapsearch in the following ways:

Using the --subEntries option to specify the LDAP Subentry Control.
Specifying base search scope to retrieve a specific subentry if its base DN is known.
Using the equality filter, (objectclass=ldapSubentry).

Note - Using the equality filter is not part of the standard and is supported for backward compatibility only.

Run the ldapsearch command with the --subEntries option.

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \
  -b "cn=schema" --subEntries "(objectclass=*)"

To Search Using the Manage DSA IT Control

The Manage DSA IT Control allows the client to request that the server treat smart referrals as regular entries during the search. A smart referral is an entry that references another server or location in the directory information tree DIT and contains the referral object class with one or more attributes containing the LDAP URLs that specify the referral.

You can specify the Manage DSA IT Control with ldapsearch in a number of ways:

OID. Use the --control or -J option with the Manage DSA IT Control OID: 2.16.840.1.113730.3.4.2 with no value.
Named constant. Use the named constant, managedsait with the --control or -J option instead of the Manage DSA IT Control OID. For example, use -J managedsait with the ldapsearch command.

Run the ldapsearch command with the -J option.

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \
  -b dc=example,dc=com -J managedsait "(uid=president)" ref
dn: uid=president,ou=People,dc=example,dc=com
ref: ldap://example.com:389/dc=example,dc=com??sub?(uid=bjensen)

Note - Without the -J managedsait argument, the command returns the referred entry.

To Search Using the Matched Values Filter Control

The Matched Values Filter Control allows clients to request a subset of attribute values from an entry that evaluate to TRUE. This control allows the user to selectively read a subset of attribute values without retrieving all values, and then scan for the desired set locally.

Run the ldapsearch command with the --matchedValuesFilter option.

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \
  -b ou=groups,dc=example,dc=com --matchedValuesFilter "(uniquemember=uid=kvaughan*)" 
  "(objectclass=*)"
dn: ou=Groups,dc=example,dc=com
dn: cn=Directory Administrators,ou=Groups,dc=example,dc=com
uniqueMember: uid=kvaughan, ou=People, dc=example,dc=com
dn: cn=Accounting Managers,ou=groups,dc=example,dc=com
dn: cn=HR Managers,ou=groups,dc=example,dc=com
uniqueMember: uid=kvaughan, ou=People, dc=example,dc=com
dn: cn=QA Managers,ou=groups,dc=example,dc=com
dn: cn=PD Managers,ou=groups,dc=example,dc=com

To Search Using the Password Policy Control

The Password Policy Control allows a client to request information about the current password policy information for a user entry.

You can specify the Password Policy Control with ldapsearch in a number of ways:

OID. Use the --control or -J option with the Password Policy Control OID: 1.3.6.1.4.1.42.2.27.8.5.1 with no value.
Named constant. Use the named constants, pwpolicy or passwordpolicy with the --control or -J option instead of the Password Policy Control OID. For example, use -J pwpolicy or -J passwordpolicy with ldapsearch.
Option. Use the --usePasswordPolicyControl option.

Note - The -J or --control option is used to specify which controls to use in a search request. The --usePasswordPolicyControl option is used for bind requests.

Run the ldapsearch command with the --usePasswordPolicyControl option.

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \
  -b dc=example,dc=com -s base --usePasswordPolicyControl "(objectclass=*)"

To Search Using the Persistent Search Control

The Persistent Search Control allows a client to receive notification when entries in the directory are changed by an add, delete, or modify operation. When a change occurs, the server sends the updated entry to the client if the entry matches the search criteria that was used by the Entry Change Notification Control.

The ldapsearch command provides an option to run a persistent search (-C) that keeps the connection open and displays the entries that match the scope and filter whenever any changes (add, delete, modify, or all) occur. You can quit the search by pressing Control-C.

The value for this argument must be in the form: ps[[:''changetype''[[:''changesonly''[[:''entrychangecontrols'']]]

The elements of this value include the following:

ps — Required operator.
changetype — Indicates the types of changes for which the client wants to receive notification. This element can be any of add, del, mod, or moddn, or it can be all to register for all change types. It can also be a comma-separated list to register for multiple specific change types. If this element is not provided, it defaults to including all change types.
changesonly — If True, the client should only be notified of changes that occur to matching entries after the search is registered. If False, the server should also send all existing entries in the server that match the provided search criteria. If this element is not provided, then it will default to only returning entries for updates that have occurred since the search was registered.
entrychangecontrols — If True, the server should include the Entry Change Notification Control in entries sent to the client as a result of changes. If False, the Entry Change Notification Control should not be included. If this element is not provided, then it will default to including the Entry Change Notification Controls.

Run the ldapsearch command as follows:

$ ldapsearch -h localhost -p 1389 -D "cn=admin,cn=Administrators,cn=config" \
  -w password -b dc=example,dc=com --persistentSearch ps:add:true:true \
  "(objectclass=*)"

Note - When you use this command, the server waits for any changes made using add, delete, modify or all to return values.

Open another terminal window , and use ldapmodify to add a new entry.

$ ldapmodify -h localhost -p 1389 -b dc=example,dc=com \
  --defaultAdd --filename new_add.ldif
Processing ADD request for uid=Marcia Garza,ou=People,dc=example,dc=com
ADD operation successful for DN uid=Marcia Garza,ou=People,dc=example,dc=com

The original terminal window shows the change.

To end the session, press Control-Z (Unix/Linux) or Control-C (Windows).

# Persistent search change type:  add
dn: uid=Marcia Garza,ou=People,dc=example,dc=com
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: top
givenName: Marcia
uid: mgarza
uid: Marcia Garza
cn: Marcia Garza
sn: Garza
userpassword: {SSHA}SNfL1RUm5uvTnLK+G0K3oz+Peb1i5/+YsylfBg==
roomnumber: 5484
l: Santa Clara
ou: Accounting
ou: People
mail: mgarza@example.com

To terminate the session, press Control-D (Unix/Linux) or Control-C (Windows), and then type Y to quit.
```
Terminate batch job (Y/N)?
```

To Search Using the Proxied Authorization Control

The Proxied Authorization Control allows a client to impersonate another entry for a specific operation. This control can be useful in trusted applications that need to perform on behalf of many different users, so that the application does not need to re-authenticate for each operation.

Run the ldapsearch command.

Here, clientApp must have the appropriate ACI permissions within the subtree to use the Proxied Authorization Control. If not granted, LDAP error 50 insufficient access rights will be returned to the client.

$ ldapsearch -h localhost -p 1389 \
  -D "uid=clientApp,ou=Applications,dc=example,dc=com" -w password \
  -s sub -b dc=example,dc=com \
  --proxyAs "dn:uid=acctgAdmin,ou=Administrators,ou=People,dc=example,dc=com" \
  "(uid=kvaughan)" mail

To Search Using the Server-Side Sort Control

The Server-Side Sort Control allows the client to request that the server sort the search results before sending them to the client. This is convenient when the server has indexes that can satisfy the sort order requested by the client faster than the client can.

You can sort the number of entries returned by using the --sortOrder option. If you do not specify + (a plus sign) for ascending or - (a minus sign) for descending, then the default option is to sort in ascending order.

Use the ldapsearch command to search all entries and to display the results in ascending order.

Use the --sortOrder option sorted on the attributes sn and givenName.

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \
  --s sub -b dc=example,dc=com --sortorder sn,givenName "(objectclass)"
dn: uid=dakers,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
...<search results>...

Use the ldapsearch command to search all entries and display the results in descending order.

Use the --sortorder option sorted on the attribute sn.

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \
  -s sub -b dc=example,dc=com --sortOrder -sn "(objectclass)"
dn: uid=pworrell,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
...<search results>...

To Search Using the Simple Paged Results Control

The Simple Paged Results Control allows a search operation to return only a subset of the results at a time. It can be used to iterate through the search results a page at a time. It is similar to the Virtual List View Control with the exception that it does not require the results to be sorted and can only be used to iterate sequentially through the search results.

Use the ldapsearch command with the --simplePageSize option.

The following command also uses the --countEntries option to mark each page.

$ ldapsearch --hostname localhost --port 1389 \
 --bindDN "cn=Directory Manager" --bindPassword password \
 --searchScope sub --baseDN dc=example,dc=com \
 --simplePageSize 2 --countEntries "(objectclass=*)"

dn: ou=Groups,dc=example,dc=com
objectClass: organizationalunit
objectClass: top
ou: Groups

dn: ou=People,dc=example,dc=com
objectClass: organizationalunit
objectClass: top
ou: People

# Total number of matching entries: 2

dn: ou=Special Users,dc=example,dc=com
objectClass: organizationalUnit
objectClass: top
description: Special Administrative Accounts
ou: Special Users

dn: ou=Company Servers,dc=example,dc=com
objectClass: organizationalUnit
objectClass: top
description: Standard branch for Company Server registration
ou: Company Servers

# Total number of matching entries: 2

dn: ou=Contractors,dc=example,dc=com
objectClass: organizationalUnit
objectClass: top
ou: Contractors
ou: Product Testing
ou: Product Development
ou: Accounting

# Total number of matching entries: 1

Searching Using the Virtual List View Control

The Virtual List View Control allows a client to request that the server send search results in small, manageable chunks within a specific range of entries. It also allows a client to move forward and backward through the results of a search operation if configured with a GUI browser or application, or jump directly to a particular entry.

Note - The Virtual List View Control requires that the returned entries be sorted.

Together with the --virtualListView option or its short form -G, specify the following arguments:

before. Specify the number of entries before the target to include in the results.

If the before value is greater than or equal to the target offset, then the before value is adjusted so that the first entry returned is the beginning of the list.
after. Specify the number of entries after the target to include in the results.
index. Specify the offset of the target entry within the result set. An index of 1 always means the first entry. If index and content_count are equal, the last entry is selected.

If the index value is negative, the server rejects the request.

If the index value is 0, it is adjusted to 1 so that returned values are displayed.

If the index value is greater than the total number of matching values, it is adjusted to one greater than the content count.

The value of index can also be an assertion value, so that the returned entry contains that value. If the returned entry is so near the end of the list that the value of after extends beyond the last entry, the value of after is adjusted to display the appropriate entries.
count. Specify the expected size of the result set.
- count=0. The target entry is the entry at the specified index position, starting from 1 and relative to the entire list of sorted results. Use this argument if the client does not know the size of the result set.
- count=1. The target entry is the first entry in the list of sorted results.
- count>1. The target entry is the first entry in the portion of the list represented by the fraction index/count. To target the last result in the list, use an index argument greater than the count argument. Client applications can use interfaces that allow users to move around a long list by using a scroll bar. For example, for an index of 33 and a count of 100, the application can jump 33 percent of the way into the list.

For example, the arguments (0:4:1:0) indicate that you want to show 0 entries before and 4 entries after the target entry at index 1. If the client does not know the size of the set, the count is 0.

To Search Using the Virtual List View Control

The sort order option (-S) must be used with the Virtual List View control. This example uses the Virtual List View Control options to specify the following:

Before=0. Specifies that 0 entries before the target should be displayed.
After=2. Specifies that 2 entries after the target should be displayed.
Index=1. Specifies that the offset of the target entry within the result set should be returned.
Count=0. Specifies that target entry at the index position should be returned, which is the first entry.

Thus, the server returns the first entry plus two entries after the target sorted in ascending order by the givenName attribute.

Use the ldapsearch command with the --virtualListView option.

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w bindPassword \
  -b dc=example,dc=com --searchScope sub --sortOrder givenName \
  --virtualListView "0:2:1:0" "(objectclass=*)"

dn: uid=awhite,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
givenName: Alan
uid: awhite
cn: Alan White
sn: White
...

dn: uid=aworrell,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
givenName: Alan
uid: aworrell
cn: Alan Worrell
sn: Worrell
...

dn: uid=alutz,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
givenName: Alexander
uid: alutz
cn: Alexander Lutz
sn: Lutz
...

# VLV Target Offset: 1
# VLV Content Count: 172

To Search Using Virtual List View With a Specific Target

The sort order (-S) option must also be used with Virtual List View. The example command uses the Virtual List View Control options to specify the following:

Before=0. Specifies that 0 entries before the target should be displayed.
After=4. Specifies that 4 entries after the target should be displayed.
Index=jensen. Specifies that the string jensen within the result set be returned.
Count=not specified. Use the default count=0, which is the first entry.

Thus, the server returns the first sn attribute that matches jensen plus four sn attributes after the target sorted in ascending order by the sn attribute.

Use the ldapsearch command with the --virtualListView option.

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \
  -b dc=example,dc=com --searchScope sub --sortOrder sn \
  --virtualListView "0:4:jensen" "(objectclass=*)" sn

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

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

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

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

dn: uid=ajensen,ou=People,dc=example,dc=com
sn: Jensen

# VLV Target Offset: 56
# VLV Content Count: 172

To Search Using Virtual List View With a Known Total

The sort order (-S) option must also be used with Virtual List View. The example command uses the Virtual List View Control options to specify the following:

Before=0. Specifies that 0 entries before the target should be displayed.
After=2. Specifies that 2 entries after the target should be displayed.
Index=57. Specifies that the index of 57 within the result set should be returned. This is roughly one-third of the list.
Count=172. Use the total count.

Thus, the server returns the first sn attribute that is one-third within the list, plus two sn attributes sorted in ascending order by the sn attribute.

Use the ldapsearch command with the --virtualListView option.

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \
  -b dc=example,dc=com -s sub --sortOrder sn \
  --virtualListView "0:2:57:172" "(objectclass=*)" sn

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

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

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

# VLV Target Offset: 57
# VLV Content Count: 172

Searching in Verbose Mode and With a Properties File

This section describes how to search in verbose mode and how to search by using a properties file.

To Search in Verbose Mode

Verbose mode displays the processing information that is transmitted between client and server. This mode is convenient for debugging purposes.

Use the ldapsearch command as follows:

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \
   -b dc=example,dc=com -s base --verbose "(objectclass=*)" 
LDAP: C>S 01:43:46.140 (0ms) LDAPMessage(msgID=1, protocolOp=BindRequest
  (version =3, dn=cn=Directory Manager, password=password)) 
ASN1: C>S 01:43:46.140 (0ms) ASN.1 Sequence
  BER Type: 30 
  Decoded Values: 
  ASN1Integer(type=02, value=1) 
  ASN1Sequence(type=60, values={ ASN1Integer(type=02, value=3), 
    cn=Directory Manager, opends }) 
  Value:
  02 01 01 60 23 02 01 03   04 14 63 6E 3D 64 69 72     `#  cn=directory
  65 63 74 6F 72 79 20 6D   61 6E 61 67 65 72 80 08          manager
  70 61 73 73 77 6F 72 64                                    password
...

To Search Using a Properties File

The directory server supports the use of a properties file that holds default argument values used with the ldapsearch command. The properties file is convenient when working in different configuration environments, especially in scripted or embedded applications. For more information, see Using a Properties File With Server Commands in Oracle Fusion Middleware Command-Line Usage Guide for Oracle Unified Directory.

Create a properties file in any text editor, with the following content:

hostname=localhost 
port=1389 
bindDN=cn=Directory Manager 
bindPassword=password 
baseDN=dc=example,dc=com 
searchScope=sub 
sortOrder=givenName 
virtualListView=0:2:1:0

Save the file as tools.properties.

Use the ldapsearch with the --propertiesFilePath option.

$ ldapsearch --propertiesFilePath tools.properties "(objectclass=*)"

Searching Internationalized Entries

Oracle Unified Directory supports collation rules that match entries and can be used with the server-side sorting control to sort search results. The collation rule is specified in the search filter as a matching rule, delimited by colons, as shown here:

locale.matchingRule

where:

locale is specified in one of the following ways
- Locale OID
- Locale character suffix (such as ar, en, or fr-CA).
  
  See Supported Collation Rules at the end of this section for a list of supported locales, their OIDs, and tags.
matchingRule can specified as either a numeric suffix or a character suffix appended to the locale, as listed in Table 7-1.

Note - If the locale is specified by its OID, then the matching rule must be specified by its numeric suffix. In this case, the matching rule cannot be specified by the character suffix.

Table 7-1 Matching Rule Suffixes

Matching Rule	Numeric Suffix	Character Suffix
Less than	.1	.lt
Less than or equal to	.2	.lte
Equality	.3	.eq (default)
Greater than or equal to	.4	.gte
Greater than	.5	.gt
Substring	.6	.sub

Equality is the default matching rule. That is, when no matching rule suffix is specified, the collation rule uses equality matching rule. The two following examples are equivalent and specify the English collation rule and the equality matching rule, but the second example specifies the equality matching rule explicitly with the .eq suffix:

"cn:en:=sanchez"
"cn:en.eq:=sanchez"

The next example shows the same search filter, but specified using the locale's character suffix and the matching rule's numeric code:

"cn:en.3:=sanchez"

The following example shows the same search filter specified using the locale OID and the matching rule numeric suffix:

"cn:1.3.6.1.4.1.42.2.27.9.4.34.1.3:=sanchez"

The following examples specify the same search filter but with a Spanish collation rule.

"cn:es.eq:=sanchez"
"cn:1.3.6.1.4.1.42.2.27.9.4.49.1.3:=sanchez"
"cn:es.3:=sanchez"

The following examples specify a similar search filter that uses a greater-than matching rule with the Spanish collation rule.

"cn:es.gt:=sanchez"
"cn:1.3.6.1.4.1.42.2.27.9.4.49.1.5:=sanchez"
"cn:es.5:=sanchez"

Examples

Example 7-1 Equality Search

The following search uses a filter with the en (en-US) locale OID to perform an equality search to return any entry with a cn value of sanchez:

$ ldapsearch -D "cn=directory manager" -w password -b "o=test" \
  "cn:1.3.6.1.4.1.42.2.27.9.4.34.1:=sanchez"