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
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
Searching Internationalized Entries
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 provides a suite of LDAPv3-compliant command-line tools, including a sophisticated look-up operation in the form of a search function and filters. You can also use Oracle Directory Services Manager to search directory data. This section explains how to use the ldapsearch command-line utility and Oracle Directory Services Manager to locate entries in the directory.
The ldapsearch command allows you to enter a search request where you specify the host name, port, bind DN and password plus search criteria to locate entries in the directory. When an LDAP client makes a search request to the directory server, it opens a connection to the directory server over TCP/IP. The client then performs a bind operation to the directory server by attempting to match a given entry, which effectively authenticates the client. Most users have the option to bind as a particular user, such as a Directory Administrator or themselves, or to not bind as any user, in which case the directory server assumes that the user is bound as an anonymous user.
Because all access to directory data is based on how a connection is bound, the directory server checks the client's privileges to see if the client can run a particular search operation. After the directory server checks the user's access rights, the client passes a search request consisting of a set of search criteria and options to the directory server.
The directory server searches all entries that match the search criteria and options. It then returns the entries, the DN, and all attributes for each entry, in the form of LDIF text to standard output. If an error occurs, the directory server displays an error message indicating the error. Finally, the client closes the connection when the search operation has completed.
The ldapsearch utility is found in the following location:
(UNIX, Linux) install-dir/bin (Windows) install-dir\bat
The utility has the following format:
ldapsearch optional-options search-filter optional-list-of-attributes
where:
optional-options are command-line options that must appear before the search filter.
search-filter is an LDAP search filter either specified on the command-line or in a file.
optional-list-of-attributes is a list of attributes separated by a space. The list of attributes must appear after the search filter.
The ldapsearch command has many options to search entries in the directory. Options are allowed in either their short form (for example, -b baseDN) or their long form (for example, --baseDN). The most common command options to use with ldapsearch are as follows:
Specifies the host name or IP address of the directory server on which the search should be run. It can be an IP address or a resolvable name. If this is not provided, a default value of localhost is used.
Specifies the directory server port. It should be an integer value between 1 and 65535, inclusive. If this is not provided, a default port of 389 is used.
Specifies the base DN to use for the search operation. If a file containing multiple filters is provided using the --filename option, this base DN is used for all of the searches. This is a required option.
Sets the scope for the search operation. Its value must be one of the following:
base. Searches only the entry specified by the --baseDN or -b option.
one. Searches only the entry specified by the --baseDN or -b option and its immediate children.
sub or subordinate. Searches the entire subtree whose base is the entry specified by the --baseDN or -b option. This is the default option when no --searchScope option is provided.
Specifies the DN to use when binding to the directory server through simple authentication. This option is not required when using SASL authentication or anonymous binding.
Specifies the password to use when binding to the directory server. This option is used for simple authentication, as well as for password-based SASL mechanisms like CRAM-MD5, DIGEST-MD5, and PLAIN. It is not required if anonymous binding is used. This option must not be used in conjunction with the --bindPasswordFile option. To prompt for the password, type -w -.
Sets the maximum length of time in seconds that the directory server should spend processing any search request. If this is not provided, no time limit is imposed by the client. Note that the directory server may enforce a lower time limit than the one requested by the client.
Sets the maximum number of matching entries that the directory server should return to the client. If this is not provided, no maximum size is imposed by the client. Note that the directory server may enforce a lower size limit than the one requested by the client.
Sorts the results before returning them to the client. The sort order is a comma-delimited list of sort keys, where each sort key consists of the following elements:
+/- (plus or minus sign). Indicates that the sort should be in ascending (+) or descending (-) order. If this value is omitted, the sort uses ascending order by default.
Attribute name. The name of the attribute to sort the data. This element is required.
Name or OID Matching Rule. An optional colon followed by the name or OID of the matching rule used to perform the sort. If this is not provided, the default ordering matching rule for the specified attribute type is used.
For example, the sort order string sn,givenName sorts the entries in ascending order first by sn and then by givenName. Alternately, using -modifyTimestamp, the directory server sorts the modifyTimestamp attributes with the most recent values first.
The ldapsearch command requires three sets of information to specify where and what to search in the directory information tree:
Base DN. By specifying the base DN, you are defining the topmost distinguished name (DN) or starting point in the directory to conduct the search. All searches begin at or below the base DN, depending on the scope, and move down the tree, never upwards. Examples of base DNs are: dc=example,dc=com and ou=People,dc=example,dc=com.
Scope. The scope determines which set of entries at or below the base DN should be evaluated by the search filter. The search scope and base DN together indicate "where" to look for entries in the directory.
Search filter. The search filter specifies the conditions that the entries must meet to be returned to the client.
The directory server provides seven types of search filters, defined in the LDAP protocol. With each search filter type, you use operators that test the relationships between two entities, attribute and value.
The following table shows how search filters are used to return specific entries in a search query.
|
Multiple search filter components can be combined and evaluated by using the operator:
(Boolean-Operator(filter)(filter)(filter))
Boolean operators can be combined and nested together to form complex expressions:
(Boolean-Operator(filter)(Boolean-operator(filter)(filter)))
The following table describes the Boolean operators.
|
UTF8 is a byte-order, variable-length character code for Unicode and a subset of ASCII. You use UTF-8 for multiple-language support by replacing each character of a non 7-bit ASCII character with a byte of a UTF-8 encoding. Typically, you must escape the UTF-8 encoding with a backslash.
For example, the character é has a UTF-8 representation of c3a9 and è has a UTF-8 representation c3a8. A UTF-8 encoding is represented with an escaped backslash. So, é is represented as \\c3\\a9 and è is represented as \\c3\\a8. To represent cn=Hélène Laurent, you would use the following encoding:
(cn=H\\c3\\a9l\\c3\\a8ne Laurent)
You must specify special characters (for example, a space, backslash, asterisk, comma, period, or others) by using the escape backslash.
Asterisk. Represent an asterisk (*) as \\2a. For example, Five*Star would be represented as "(cn=Five\\2aStar)".
Backslash. Represent a backslash (\) as \\5c. For example, c:\\file would be represented as "(cn=c:\\5c\\5cfile)".
Parentheses. Represent parentheses ( ) as \\28 and \\29, respectively. For example, John Doe (II) would be represented as "(cn=John Doe \\28II\\29)".
Null. Represent null as \\00. For example, 0001 would be represented as "(bin=\\00\\00\\00\\01)".
Comma. Represent a comma (,) by escaping it as \\,. For example, "(cn=Mkt\\,Peru,dc=example,dc=com)".
Space. Generally, use quotation marks around strings that contain a space. For example, (cn="HR Managers,ou=Groups,dc=example,dc=com").
The following examples show the use of the ldapsearch command with various search options. These examples all assume that your current working directory is install-dir/bin (install-dir\bat on Windows systems).
The following points pertain to all the examples in this section:
If the example does not specify a scope (with the --searchScope or -s option), ldapsearch assumes that the scope is subordinate or sub, which returns the full subtree of the base DN.
If no attributes are specified, the command returns all attributes and their values.
If no --bindDN and --bindPassword are specified, the search uses an anonymous bind.
If no --hostname is specified, the default (localhost) is used.
Note - Many UNIX and Linux operating systems provide an installed version of common LDAP-client tools, such as ldapsearch, ldapmodify, and ldapdelete in the /usr/bin directory. You should use the ldapsearch provided with the directory server to search the directory server. You can check which version of ldapsearch you are using by typing the following command:
$ which ldapsearch
If you are using the ldapsearch in /usr/bin, put install-dir/bin at the beginning of your $PATH.
You can return all entries below a specified branch DN using the presence search filter (objectclass=*). The search filter looks for all entries that have one or more object classes with any value. Because all entries have several object class definitions, the filter guarantees that all entries will be returned.
$ ldapsearch --hostname localhost --port 1389 --baseDN "dc=example,dc=com" \ "(objectclass=*)" dn: dc=example,dc=com objectClass: domain objectClass: top dc: example dn: ou=Groups,dc=example,dc=com objectClass: organizationalunit objectClass: top ou: Groups dn: cn=Directory Administrators,ou=Groups,dc=example,dc=com objectClass: groupofuniquenames objectClass: top ou: Groups cn: Directory Administrators uniquemember: uid=kvaughan, ou=People, dc=example,dc=com uniquemember: uid=rdaugherty, ou=People, dc=example,dc=com uniquemember: uid=hmiller, ou=People, dc=example,dc=com ...
You can use an equality filter to locate a specific user in the directory. This example locates an employee with the common name of "Frank Albers".
$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=Frank Albers)" dn: uid=falbers,ou=People,dc=example,dc=com objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson objectClass: top givenName: Frank uid: falbers cn: Frank Albers sn: Albers telephoneNumber: +1 408 555 3094 userPassword: {SSHA}nDTQJ9DDiMUrBwR0WNKq0tgS4iB2A9QJFgpZiA== roomNumber: 1439 ou: Accounting ou: People l: Sunnyvale mail: falbers@example.com facsimileTelephoneNumber: +1 408 555 9751
You can use an equality filter to locate an entry's attribute(s) in the directory. Specify one or more attributes by placing them after the search filter. This example locates the telephoneNumber and mail attributes from the user entry for Frank Albers.
$ ldapsearch --port 1389 --baseDN dc=example,dc=com \ "(cn=Frank Albers)" telephoneNumber mail dn: uid=falbers,ou=People,dc=example,dc=com telephoneNumber: +1 408 555 3094 mail: falbers@example.com
Together with the search base DN, the scope determines what part of the directory information tree (DIT) is examined. A base scope examines only the level specified by the base DN (and none of its child entries). You specify a base scope by using the --searchScope base option or its short form equivalent -s base.
$ ldapsearch --hostname localhost --port 1389 --baseDN "dc=example,dc=com" \ --searchScope base "(objectclass=*)" dn: dc=example,dc=com objectClass: domain objectClass: top dc: example
A one-level scope examines only the level immediately below the base DN. You specify a one-level scope by using the --searchScope one option or its short form equivalent -s one. This example displays the entries immediately below the base DN.
$ ldapsearch --hostname localhost --port 1389 --baseDN "dc=example,dc=com" \ --searchScope one "(objectclass=*)" dn: ou=Groups,dc=example,dc=com objectClass: top objectClass: organizationalunit ou: Groups dn: ou=People,dc=example,dc=com objectClass: top objectClass: organizationalunit ou: People dn: ou=Special Users,dc=example,dc=com objectClass: top objectClass: organizationalUnit ou: Special Users description: Special Administrative Accounts dn: ou=Company Servers,dc=example,dc=com objectClass: top objectClass: organizationalUnit ou: Company Servers description: Standard branch for Company Server registration
The subtree scope examines the subtree below the base DN and includes the base DN level. You specify a subtree scope using the --searchScope sub option, or its short form equivalent -s sub. If you do not specify the --searchScope, ldapsearch assumes a subtree scope.
$ ldapsearch --hostname localhost --port 1389 \ --baseDN "cn=Directory Administrators,ou=Groups,dc=example,dc=com" \ --searchScope sub "(objectclass=*)" dn: cn=HR Managers,ou=groups,dc=example,dc=com objectClass: groupOfUniqueNames objectClass: top ou: groups description: People who can manage HR entries cn: HR Managers uniqueMember: uid=kvaughan, ou=People, dc=example,dc=com uniqueMember: uid=cschmith, ou=People, dc=example,dc=com
The ldapsearch command provides a convenient option to check if an attribute is present in the directory. Use the --typesOnly option or its short form equivalent -A to instruct the directory server to display the attribute names but not their values.
$ ldapsearch --hostname localhost --port 1389 \ --baseDN "dc=example,dc=com" --typesOnly "(objectclass=*)" dn: dc=example,dc=com objectClass dc dn: ou=Groups,dc=example,dc=com objectClass ou ...
You can use ldapsearch to return only user attributes for entries that match the search filter, by including an asterisk *. User attributes (as opposed to operational attributes) store user information in the directory. If you do not specify the asterisk, the user attributes are returned by default. You must escape the asterisk appropriately for your shell.
$ ldapsearch --hostname localhost --port 1389 --baseDN "dc=example,dc=com" \ "(objectclass=*)" '*' dn: cn=Aggie Aguirre,ou=People,dc=example,dc=com objectClass: person objectClass: inetorgperson objectClass: organizationalperson objectClass: top postalAddress: Aggie Aguirre$15172 Jackson Street$Salt Lake City, MI 49843 postalCode: 49843 uid: user.99 description: This is the description for Aggie Aguirre. employeeNumber: 99 initials: AGA givenName: Aggie pager: +1 514 297 1830 mobile: +1 030 300 0720 cn: Aggie Aguirre telephoneNumber: +1 730 027 2062 sn: Aguirre street: 15172 Jackson Street homePhone: +1 229 128 3072 mail: user.99@maildomain.net l: Salt Lake City st: MI
You can use ldapsearch to return only the base DNs for entries that match the search filter by including a 1.1 string after the search filter.
$ ldapsearch --hostname localhost --port 1389 --baseDN "dc=example,dc=com" \ "(objectclass=*)" 1.1 version: 1 dn: cn=Richard Arnold,ou=people,dc=example,dc=com dn: cn=Kevin Booysen,ou=people,dc=example,dc=com dn: cn=Steven Morris,ou=people,dc=example,dc=com dn: cn=Leila Shakir,ou=people,dc=example,dc=com dn: cn=Emily Smith,ou=people,dc=example,dc=com ...
You can search all entries where the attributes are referenced by a specific object class by prepending a @ character to the object class name. For example, to view all entries that have an object class of groupOfUniqueNames, include @groupOfUniqueNames after the search filter.
$ ldapsearch --hostname localhost --port 1389 \ --baseDN "ou=Groups,dc=example,dc=com" "(objectclass=*)" @groupOfUniqueNames dn: ou=Groups,dc=example,dc=com ou: Groups objectClass: organizationalunit objectClass: top dn: cn=Directory Administrators,ou=Groups,dc=example,dc=com ou: Groups objectClass: groupofuniquenames objectClass: top cn: Directory Administrators uniqueMember: uid=kvaughan, ou=People, dc=example,dc=com uniqueMember: uid=rdaugherty, ou=People, dc=example,dc=com uniqueMember: uid=hmiller, ou=People, dc=example,dc=com ...
The ldapsearch command provides the --countEntries to return the total number of entries in the directory. The directory server returns all entries that match the search filter and displays the total number on the last line. This example determines the number of employee entries whose location is Cincinnati.
$ ldapsearch --hostname localhost --port 1389 --bindDN "cn=Directory Manager" \ --bindPassword password --baseDN dc=example,dc=com --countEntries "l=Cincinnati" dn: cn=Adi Adamski,ou=People,dc=example,dc=com ... l: Cincinnati st: OH dn: Aggi Aguinsky,ou=People,dc=example,dc=com objectClass: person ... l: Cincinnati st: OH # Total number of matching entries: 2
Compound search filters involve multiple tests using the boolean operators AND (&), OR (|), or NOT (!). You can combine and nest boolean operators and filters together to form complex expressions. The following example searches for all entries for employees named Jensen who work in Cupertino. The command returns two results.
$ ldapsearch --hostname localhost --port 1389 --bindDN "cn=Directory Manager" \ --bindPassword password --baseDN dc=example,dc=com "(&(sn=jensen)(l=Cupertino))" dn: uid=bjensen,ou=People,dc=example,dc=com objectClass: person objectClass: inetOrgPerson objectClass: top objectClass: organizationalPerson ou: Product Development ou: People sn: Jensen ... l: Cupertino st: CA dn: uid=rjensen,ou=People,dc=example,dc=com objectClass: person objectClass: inetOrgPerson objectClass: top objectClass: organizationalPerson ou: Accounting ou: People sn: Jensen ... l: Cupertino st: CA
You can place complex or multiple filters in a file by using the --filename option. If the file contains multiple filters, the file should be structured with one filter per line. Searches are performed using the same connection to the directory server in the order in which they appear in the filter file. If the --filename option is used, any trailing options are treated as separate attributes. Otherwise, the first trailing option must be the search filter.
This example searches all entries for employees named Jensen who work in Cupertino and who do not work in the Accounting department.
For this example, create a file called myfilter.txt with the following content:(&(sn=jensen)(l=Cupertino)(!(ou=Accounting)))
$ ldapsearch --hostname localhost --port 1389 --bindDN "cn=Directory Manager" \ --bindPassword password --baseDN dc=example,dc=com --filename myfilter.txt dn: uid=bjensen,ou=People,dc=example,dc=com objectClass: person objectClass: inetOrgPerson objectClass: top objectClass: organizationalPerson ou: Product Development ou: People sn: Jensen l: Cupertino cn: Barbara Jensen cn: Babs Jensen telephoneNumber: +1 408 555 1862 givenName: Barbara uid: bjensen mail: bjensen@example.com
You can limit the number of entries that are returned by using the -z or --sizeLimit option. If the number of entries exceeds the number that is specified, the search returns the specified number of entries, then returns an error stating that the size limit was exceeded. The following example requests a maximum of 5 entries.
$ ldapsearch --hostname localhost --port 1389 -b "dc=example,dc=com" \ --sizeLimit 5 "objectclass=*" 1.1 dn: dc=example,dc=com dn: ou=People,dc=example,dc=com dn: uid=user.0,ou=People,dc=example,dc=com dn: uid=user.1,ou=People,dc=example,dc=com dn: uid=user.2,ou=People,dc=example,dc=com SEARCH operation failed Result Code: 4 (Size Limit Exceeded) Additional Information: This search operation has sent the maximum of 5 entries to the client
The Advanced Search tab of each server instance in ODSM enables you to perform complex searches on directory data, as described in the following section.
To perform a complex LDAP search by using the ODSM advanced search facility, complete the following steps:
Connect to the directory server from ODSM, as described in Connecting to the Server From Oracle Directory Services Manager.
Select the Advanced Search tab.
Select the appropriate network group from the Network Group list.
In the Base Search DN field, enter the DN that will be the starting point of the search.
To select an entry as Base Search DN, click Select.
In the Entry Picker window, select Tree View to navigate the directory tree and locate the entry, or Search View to search for the entry.
Select the scope of the search from the Scope list. The LDAP search scope indicates the set of entries at or below the search base DN that will be considered potential matches for a search operation. The scope can be one of:
Base. This specifies that the search operation should only be performed against the entry specified as the search base DN. No entries below it will be considered.
One Level. This specifies that the search operation should only be performed against entries that are immediate subordinates of the entry specified as the search base DN. The base entry itself is not included, nor are any entries below the immediate subordinates of the search base entry.
Subtree. This specifies that the search operation should be performed against the entry specified as the search base and all of its subordinates to any depth.
In the Filter field, enter a valid LDAP search filter.
Alternatively, click Filter Builder and enter the required information for ODSM to build the LDAP search filter.
For more information about LDAP search filters, see Specifying Filter Types and Operators.
From the Search Results Size list, select how you want ODSM to limit the number of entries that are returned by the search.
Set Limit enables you to specify the precise number of entries that are returned.
Use Virtual List View enables you to use a virtual list view index in the search. For more information, see Searching Using the Virtual List View Control.
Use Paging enables you to specify that only a subset of the results should be returned at a time, and allows you to indicate the number of results on each page.. For more information, see To Search Using the Simple Paged Results Control.