Skip Navigation Links | |
Exit Print View | |
Oracle Fusion Middleware Administration Guide for Oracle Unified Directory 11g Release 1 (11.1.1) |
1. Starting and Stopping the Server
2. Configuring the Server Instance
3. Configuring the Proxy Components
4. Configuring Security Between Clients and Servers
5. Configuring Security Between the Proxy and the Data Source
6. Managing Oracle Unified Directory With Oracle Directory Services Manager
Populating a Stand-Alone Directory Server With Data
Importing Data Using import-ldif
To Import Data in Offline Mode
To Replace Existing Data During an Offline Import
To Append Imported Data to Existing Data
To Import Fractional Files by Using Filters
To Include or Exclude Attributes During Import
To Import a Compressed LDIF File
To Record Rejected or Skipped Entries During Import
To Import Data From a MakeLDIF Template
To Run an Import in Online Mode
Exporting Data Using export-ldif
To Export Part of a Back End by Using Filters
To Include or Exclude Attributes During Export
To Export to LDIF and Then Compress the File
To Run an Export in Online Mode
Creating MakeLDIF Template Files
Attribute Value Reference Tags
Tuning the JVM and Java Arguments
Overview of the Backup and Restore Process
To Back Up All Back Ends with Encryption and Signed Hashes
To Perform an Incremental Backup on All Back Ends
To Back Up a Specific Back End
To Perform an Incremental Backup on a Specific Back End
To Schedule a Backup as a Task
Backing Up the Server Configuration
Backing Up for Disaster Recovery
To Back Up the Directory Server For Disaster Recovery
Backing up and Restoring Data Using File System Snapshots
To Take a ZFS Snapshot On a Dedicated Backup Server
To Restore a Directory Server From a ZFS Snapshot
To Restore a Back End From Incremental Backups
To Schedule a Restore as a Task
To Restore the Configuration File
To Restore a Directory Server During Disaster Recovery
Restoring Replicated Directory Servers
Overview of the ldapsearch Command
ldapsearch Location and Format
Specifying Filter Types and Operators
Using UTF-8 Encoding in Search Filters
Using Special Characters in Search Filters
To Search for Specific User Attributes
To Perform a Search With Base Scope
To Perform a Search With One-Level Scope
To Perform a Search With Subtree Scope
To Return Attribute Names Only
To Return User Attributes Only
To Search For Specific Object Classes
To Return a Count of All Entries in the Directory
To Perform a Search With a Compound Filter
To Perform a Search Using a Filter File
To Limit the Number of Entries Returned in a Search
Searching Data With Oracle Directory Services Manager
Using Advanced Search Features
Searching for Special Entries and Attributes
To Search for Operational Attributes
To Search the Configuration Entry
To Search the Monitoring Entry
To Search Over SSL With Blind Trust
To Search Over SSL Using a Trust Store
To Search Over SSL With No Trust Store
To Search Over SSL Using a Keystore
To Search Using SASL With DIGEST-MD5 Client Authentication
To Search Using SASL With the GSSAPI Mechanism
To Search Using SASL With the PLAIN Mechanism
To View the Available Controls
To Search Using the Account Usability Request Control
To Search Using the Authorization Identity Request Control
To Search Using the Get Effective Rights Control
To Search Using the LDAP Assertion Control
To Search Using the LDAP Subentry Control
To Search Using the Manage DSA IT Control
To Search Using the Matched Values Filter Control
To Search Using the Password Policy Control
To Search Using the Persistent Search Control
To Search Using the Proxied Authorization Control
To Search Using the Server-Side Sort Control
To Search Using the Simple Paged Results Control
Searching Using the Virtual List View Control
To Search Using the Virtual List View Control
To Search Using Virtual List View With a Specific Target
To Search Using Virtual List View With a Known Total
Searching in Verbose Mode and With a Properties File
To Search Using a Properties File
Adding, Modifying, and Deleting Directory Data
To Add an Entry Using the --defaultAdd Option With ldapmodify
To Add Entries Using an LDIF Update Statement With ldapmodify
To Add an Attribute to an Entry
To Add an International Attribute
To Modify an Attribute With Before and After Snapshots
To Delete an Entry With ldapmodify
To Delete an Entry With ldapdelete
To Delete Multiple Entries by Using a DN File
Configuring Indexes on the Local DB Back End
To Create a New Local DB Index
To Enable or Disable Compact Encoding
To Enable or Disable Entry Compression
Ensuring Attribute Value Uniqueness
Overview of the Unique Attribute Plug-In
Configuring the Unique Attribute Plug-In Using dsconfig
To Ensure Uniqueness of the Value of the uid Attribute
To Ensure Uniqueness of the Value of Any Other Attribute
Replication and the Unique Attribute Plug-In
Configuring Virtual Attributes
To List the Existing Virtual Attributes
To Create a New Virtual Attribute
To Enable or Disable a Virtual Attribute
To Display the Configuration of a Virtual Attribute
To Change the Configuration of a Virtual Attribute
Extensions to the Collective Attributes Standard
Collective Attributes and Conflict Resolution
Excluding Collective Attributes From Specific Entries
Configuring Collective Attributes
To Create a New Collective Attribute
To Delete a Collective Attribute
To List the Collective Attributes That Apply to an Entry
Inherited Collective Attributes
Specifying Inherited Collective Attributes
Managing Data With Oracle Directory Services Manager
View the Attributes of an Entry
Add an Entry Based on an Existing Entry
Delete an Entry and its Subtree
10. Managing Users and Groups With dsconfig
11. Managing Password Policies
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.
This section describes how to search for operational attributes and how to search the Root DSE entry.
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.
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 ...
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.
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 ...
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.
$ 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";)
The directory server holds schema information in the schema entry (cn=schema) for the object classes and attributes defined on your instance.
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' ) ...
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.
$ 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.
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.
$ 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 ...
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.
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.
The following command searches the Root DSE.
$ ldapsearch -h localhost -p 1636 --useSSL --trustAll -b "" \ --searchScope base "(objectClass=*)"
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.
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=*)"
If no trust store is specified, you are prompted as to whether the certificate that was presented to the client should be trusted.
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
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.
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=*)"
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).
The following command searches the Root DSE using startTLS.
$ ldapsearch -h localhost -p 1389 --startTLS \ -b "" --searchScope base "(objectClass=*)"
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.
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=*)"
The GSSAPI mechanism performs authentication in a Kerberos environment and requires that the client system be configured to participate in such an environment.
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=*)"
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.
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=*)"
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.
You can view the current list of controls for your directory server by searching the Root DSE entry for the supportedControl attribute.
$ 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.
|
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.
$ 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 ...
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.
$ 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
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.
$ 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 ...
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
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 )
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.
$ 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
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.
$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \ -b "cn=schema" --subEntries "(objectclass=*)"
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.
$ 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.
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.
$ 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
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.
$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -w password \ -b dc=example,dc=com -s base --usePasswordPolicyControl "(objectclass=*)"
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.
$ 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.
$ 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
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
Terminate batch job (Y/N)?
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.
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
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 --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 --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>...
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.
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
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.
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.
$ 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
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.
$ 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
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.
$ 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
This section describes how to search in verbose mode and how to search by using a properties file.
Verbose mode displays the processing information that is transmitted between client and server. This mode is convenient for debugging purposes.
$ 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 ...
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.
hostname=localhost port=1389 bindDN=cn=Directory Manager bindPassword=password baseDN=dc=example,dc=com searchScope=sub sortOrder=givenName virtualListView=0:2:1:0
$ ldapsearch --propertiesFilePath tools.properties "(objectclass=*)"
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
|
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"
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"
The following filters return the same results:
"cn:en:=sanchez"
"cn:en.3:=sanchez"
"cn:en.eq:=sanchez"
"cn:1.3.6.1.4.1.42.2.27.9.4.34.1.3:=sanchez"
Example 7-2 Less-Than Search
The following search uses a filter with the es (es-ES) locale and performs a less-than search and returns the entry with a departmentnumbervalue of abc119:
$ ldapsearch -D "cn=directory manager" -w password -b "o=test" \ "departmentnumber:1.3.6.1.4.1.42.2.27.9.4.49.1.1:=abc120"
The following filters return the same results:
"departmentnumber:es.1:=abc120"
"departmentnumber:es.lt:=abc120"
Example 7-3 Less-Than-or-Equal-To Search
The following search uses a filter with the es (es-ES) locale and performs a less-than-or-equal-to search that returns the entry with a departmentnumbervalue of abc119:
$ ldapsearch -D "cn=directory manager" -w password -b "o=test" \ "departmentnumber:1.3.6.1.4.1.42.2.27.9.4.49.1.2:=abc119"
The following filters return the same results:
"departmentnumber:es.2:=abc119"
"departmentnumber:es.lte:=abc119"
Example 7-4 Greater-Than-or-Equal-To Search
The following search uses a filter with the fr (fr-FR) locale and performs a greater-than-or-equal-To search that returns an entry with a departmentnumber value of abc119
$ ldapsearch -D "cn=directory manager" -w password -b "o=test" \ "departmentnumber:fr.4:=abc119"
The following filters return the same results:
"departmentnumber:1.3.6.1.4.1.42.2.27.9.4.76.1.4:=abc119"
"departmentnumber:fr.gte:=abc119"
Example 7-5 Greater-Than Search
The following search uses a filter with the fr (fr-FR) locale and performs a greater-than search:
$ ldapsearch -D "cn=directory manager" -w password -b "o=test" \ "departmentnumber:fr.5:=abc119"
The above search should not return an entry with a departmentnumber value of abc119.
The following filters return the same results:
"departmentnumber:1.3.6.1.4.1.42.2.27.9.4.76.1.5:=abc119"
"departmentnumber:fr.gt:=abc119"
Example 7-6 Substring Search
The following search uses a filter with the en (en-US) locale and performs a substring search that returns an entry with an sn value of “Quebec”:
$ ldapsearch -D "cn=directory manager" -w password -b "o=test" \ "sn:en.6:=*u*bec"
The following filters return the same results:
"sn:1.3.6.1.4.1.42.2.27.9.4.34.1.6:=*u*bec"
"sn:en.sub:=*u*bec"
The following table lists the internationalization locales supported by Oracle Unified Directory, alphabetized by character suffix.
Table 7-2 Supported Collation Rules
|