17 Managing Directory Data

This chapter describes how to add, modify, remove, and search data in the directory server. The chapter includes information about how to make searches more efficient, by indexing data, how to ensure that entries are unique, and how to use advanced data features such as virtual attributes.

This chapter covers the following topics:

17.1 Importing and Exporting Data

The directory server provides several mechanisms to move data into and out of a specific back end. This chapter outlines the various options and then describes the import and export mechanisms in more detail.

This section covers the following topics:

Note:

When you import user entries, note that Oracle Unified Directory cannot verify that pre-encrypted passwords match the password policy. Pre-encrypted passwords are therefore rejected with the following error:

LDAP: error code 53 - Pre-encoded passwords are not allowed for the password attribute userPassword.

To allow pre-encrypted passwords when you import user entries using ldapmodify or import-ldif, change the default password policy by setting the advanced property allow-pre-encoded-passwords to true. For more information, see Section 24.2.2, "To Modify the Default Password Policy".

17.1.1 Populating a Stand-Alone Directory Server With Data

To populate a stand-alone directory server with data, use one of the following methods:

  • Import the data from an LDAP Data Interchange Format (LDIF) file while you are setting up the server, either by using the setup utility in GUI mode or by using the setup utility in interactive command-line mode. This is the most convenient method of initializing a stand-alone server or the first server in a replicated topology.

  • Start with an empty suffix and add entries by using the ldapmodify command, for example:

    $ ldapmodify -h localhost -p 1389 -D "cn=Directory Manager" -j pwd-file \
  -a -f /usr/local/add_entry.ldif

  • Import data from an LDIF file, using the import-ldif command. For example:

    $ import-ldif -b dc=example,dc=com -n userRoot -l /var/tmp/Example.ldif

    This method is much more efficient for the addition of bulk entries. The import-ldif command imports data from an LDIF file either by replacing any existing data in the suffix or by appending data to a base DN. Similarly, the export-ldif command exports entries from a database to an LDIF file, which can then be imported to another server. Both tools support file compression, SASL extension, and client/server authentication using SSL and startTLS.

  • Copy the binary database from another server. This method is also called binary copy.

    $ cp instance-path/db/example.db destination-path/db

  • Restore the database from a backup using the restore command, for example:

    $ restore -d /home/backup/userRoot

Note:

Performing a binary database copy or restoring a database from a backup requires the source server and the destination server to have the same database remote LDAP structures and indexes.

17.1.2 Importing Data Using import-ldif

The import-ldif command is used to populate a directory server back end with data read from an LDIF file or with data generated based on a Section 17.1.4, "Creating MakeLDIF Template Files." In most cases, import-ldif is significantly faster than adding entries using ldapmodify.

The import-ldif command supports both LDIF files and compressed files (.zip).

Note the following aspects of an import operation:

  • A complete import to an entire Oracle Berkeley DB Java Edition (JE) back end will have better performance than a partial import to a branch of the JE back end. All imported LDIF files must use UTF-8 character-set encoding.

  • Importing suffixes is a resource-intensive operation. If you import LDIF files that include a large number of suffixes, your system might have insufficient heap to complete the import operation. Before importing such LDIF files, you should therefore increase the heap as much as possible. For more information, see Chapter 30, "Tuning Performance" and Section 17.2, "Importing Large Data Sets."

  • You do not need root privileges to import an LDIF file, but you must authenticate as a user with root permissions, such as cn=Directory Manager.

The following sections describe how to import data using the import-ldif command:

17.1.2.1 import-ldif Operation Modes

The import-ldif command has two modes of operation: online and offline.

  • Online mode. In online mode, import-ldif contacts a running directory server instance and registers an import task. The command accesses the task back end over SSL via the administration connector. For more information, see Section 14.3, "Managing Administration Traffic to the Server." Online mode runs automatically when any connection options (such as --hostname, --port, --bindDN, and --bindPasswordFile) are specified.

    Note that, even for an online import, the backend is unavailable during the import. In a replicated topology, the overall service remains available through the referral on update feature. For more information, see Section 17.13.1, "Referrals in a Replicated Topology".

    In general, if you expect to do online imports, you should increase the heap when you start the server. For more information, see Chapter 30, "Tuning Performance."

  • Offline mode. When no connection options are specified, the command runs in offline mode. In offline mode, import-ldif accesses the database directly rather than through a directory server instance. In this case, the directory server must be stopped.

17.1.2.2 To Import Data in Offline Mode

This procedure imports a remote LDAP database with new entries specified in an import LDIF file. The command runs in offline mode, which requires the server to be shut down prior to import.

  1. Stop the server if it is running.

    $ stop-ds

  2. Import the LDIF file, as shown in the following example:

    $ import-ldif -b dc=example,dc=com -n userRoot -l Example.ldif

    This command specifies the base DN for the branch of the data that should be included in the import (-b), the back-end ID into which the data is imported (-n), and the LDIF file used for the import (-l).

17.1.2.3 To Replace Existing Data During an Offline Import

The following procedure replaces an existing back-end with new entries specified in an import file.

  1. Stop the server if it is running.

    $ stop-ds

  2. Import the LDIF file, replacing the existing data. For example:

    $ import-ldif --includeBranch dc=example,dc=com --backendID userRoot \
  --replaceExisting --ldifFile Example.ldif

17.1.2.4 To Append Imported Data to Existing Data

The following procedure appends the entries in an import file to the existing entries in the back end.

  1. Stop the server if it is running.

    $ stop-ds

  2. Import the LDIF file, appending the new data to the existing data. For example:

    $ import-ldif --backendID userRoot --append --ldifFile new.ldif

17.1.2.5 To Import Fractional Files

The import-ldif command provides options to import a portion of an import file by specifying the base DN to include or exclude during the process.

This example imports all entries below the base DN, dc=example,dc=com, and excludes all entries below ou=People,dc=example,dc=com.

  1. Stop the server if it is running.

    $ stop-ds

  2. Import a portion of the LDIF file. For example:

    $ import-ldif --includeBranch dc=example,dc=com \
  --excludeBranch ou=People,dc=example,dc=com --backendID userRoot \
  --replaceExisting --ldifFile Example.ldif

17.1.2.6 To Import Fractional Files by Using Filters

The import-ldif command provides options to import part of an import file by using filters for data inclusion or exclusion. Make sure that you fully understand how this mechanism works before you use it.

In this example, the contents of an LDIF file are imported, except those entries that match the search filter l=Auckland (that is, location=Auckland).

The --includeFilter option works in a similar manner to --excludeFilter, except that it includes all entries that match the search filter during import

  1. Stop the server if it is running.

    $ stop-ds

  2. Import a portion of the file by using an exclude filter. For example:

    $ import-ldif --excludeFilter "(l=Auckland)" --backendID userRoot \
  --replaceExisting --ldifFile Example.ldif

17.1.2.7 To Include or Exclude Attributes During Import

The import-ldif command provides options to include and exclude attributes during import by using the --includeAttribute and --excludeAttribute options, respectively. Make sure that you fully understand how this mechanism works before you use it.

  1. Stop the server if it is running.

    $ stop-ds

  2. View the entries of the import file before you start the import.

    The directory server provides useful utilities to search, modify, compare, or delete import files without connecting to the server. You can use the ldifsearch command to display an entry in your import file. For example, to display the entry for Sam Carter, use the following command:

    $ ldifsearch -b dc=example,dc=com --ldifFile Example.ldif "(cn=Sam Carter)"
dn: uid=scarter,ou=People,dc=example,dc=com
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: top
givenname: Sam
uid: scarter
cn: Sam Carter
telephonenumber: +1 408 555 4798
sn: Carter
userpassword: sprain
roomnumber: 4612
mail: scarter@example.com
l: Sunnyvale
ou: Accounting
ou: People
facsimiletelephonenumber: +1 408 555 9751

    In this entry, notice the presence of the roomnumber attribute below the telephonenumber attribute.

  3. Import the file, excluding the roomnumber attribute for all entries.

    $ import-ldif --excludeAttribute "roomnumber" --backendID userRoot \
  --replaceExisting --ldifFile Example.ldif

  4. Start the server.

    $ start-ds

  5. Perform an ldapsearch to verify the import.

    The following example shows that the roomnumber attribute is now absent from Sam Carter's entry.

    $ ldapsearch --port 1389 --baseDN dc=example,dc=com --bindDN "cn=Directory Manager" \
  --bindPassword password "(cn=Sam Carter)"
dn: uid=scarter,ou=People,dc=example,dc=com \
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
givenName: Sam
uid: scarter
cn: Sam Carter
sn: Carter
telephoneNumber: +1 408 555 4798
ou: Accounting
ou: People
l: Sunnyvale
mail: scarter@example.com
facsimileTelephoneNumber: +1 408 555 9751

17.1.2.8 To Import a Compressed LDIF File

The import-ldif utility supports compressed LDIF files.

  1. Stop the server if it is running.

    $ stop-ds

  2. Import the compressed LDIF file.

    $ import-ldif --includeBranch dc=example,dc=com 
  --excludeBranch "ou=People,dc=example,dc=com" --ldifFile Example.ldif \
  --backendID userRoot --replaceExisting --isCompressed

17.1.2.9 To Record Rejected or Skipped Entries During Import

The import-ldif command provides a means to write to an output file for any entries that are rejected or skipped during the import process. This enables easy debugging of an LDIF file. Rejected entries occur when the directory server rejects the added entries due to schema violations. Skipped entries occur when entries cannot be placed under the specified base DN.

  1. Stop the server if it is running.

    $ stop-ds

  2. Import the file, using the --rejectFile and --skipFile options.

    You can also use the --overWrite option to replace any previous items in the two files. Without the option, the directory server appends new rejected and skipped entries to the existing files.

    $ import-ldif --backendID userRoot --append --ldifFile new.ldif 
  --overwrite --rejectFile rejected.ldif --skipFile skipped.ldif

  3. View the contents of the rejectFile and skipFile to determine which entries were rejected or skipped during the import. For example:

    $ more rejected.ldif
# Entry ou=Contractors,dc=example,dc=com read from LDIF starting at line 1 
is not valid because it violates the server's schema configuration: 
Entry ou=Contractors,dc=example,dc=com violates the Directory Server schema 
configuration because it includes attribute changeType which is not allowed. 
changetype: add objectclasses defined in that entry objectclass: top 
objectclass: organizationalUnit ou: Contractors ou: Product Testing 
ou: Product Dev ou: Accounting ...

$ more skipped.ldif
# Skipping entry ou=People,dc=example,dc=com because the DN is not one that should be 
  included based on the include and exclude branches objectclass: top 
  objectclass: organizationalunit ou: People 
  aci: (target ="ldap:///ou=People,dc=example,dc=com")(targetattr ="userpassword || 
  telephonenumber || facsimiletelephonenumber")(version 3.0;acl "Allow self entry 
  modification"; allow (write)(userdn = "ldap:///self");) 
  aci: (target ="ldap:///ou=People,dc=example,dc=com")(targetattr h3.="cn || sn || 
  uid") (targetfilter ="(ou=Accounting)")(version 3.0;acl "Accounting Managers Group 
  Permissions"; allow (write) 
  (groupdn = "ldap:///cn=Accounting Managers,ou=groups,dc=example,dc=com");) 
  aci: (target ="ldap:///ou=People,dc=example,dc=com")(targetattr h3.="cn || sn || 
  uid") (targetfilter ="(ou=Human Resources)")(version 3.0;acl "HR Group Permissions"; 
  allow write)(groupdn = "ldap:///cn=HR Managers,ou=groups,dc=example,dc=com");) aci: 
  (target ="ldap:///ou=People,dc=example,dc=com")(targetattr h3.="cn ||sn || uid") 
  (targetfilter ="(ou=Product Testing)")(version 3.0;acl "QA Group Permissions"; allow 
  (write)(groupdn = "ldap:///cn=QA Managers,ou=groups,dc=example,dc=com");) 
  aci: (target ="ldap:///ou=People,dc=example,dc=com")(targetattr h3.="cn || sn || 
  uid") (targetfilter ="(ou=Product Development)")(version 3.0;acl "Engineering Group 
  Permissions"; allow (write)(groupdn = 
  "ldap:///cn=PD Managers,ou=groups,dc=example,dc=com");) ...

17.1.2.10 To Import Data From a MakeLDIF Template

The directory server includes the Java utility, makeLDIF, that can be used to generate sample data for import. The makeLDIF utility requires a template file. You can create your own template file, or you can use the template file located in INSTANCE_DIR/OUD/config/MakeLDIF/example.template, editing it as required. For more information, see Section 17.1.4, "Creating MakeLDIF Template Files" and Appendix A, "make-ldif."

  1. Stop the server if it is running.

    $ stop-ds

  2. Import the data, using a template file.

    The sample template generates 10,003 sample entries in the specified back end.

    $ import-ldif --backendID userRoot --templateFile example.template \
  --randomSeed 0

17.1.2.11 To Run an Import in Online Mode

The import-ldif utility can also be run with the server online. In online mode, the command accesses the task back end over SSL via the administration connector. To run the command in online mode you must specify the relevant connection options, including how the SSL certificate will be trusted. This example uses the -X option to trust all certificates. For more information, see Section 14.3, "Managing Administration Traffic to the Server."

Run the import-ldif command with the appropriate connection options.

$ import-ldif -h localhost -port 4444 -D "cn=Directory Manager" -j pwd-file -X \
  -l /ldif-files/example.ldif

17.1.2.12 To Schedule an Import

The import-ldif utility provides a --start option for scheduling the import at some future date. You can view this scheduled task by using the manage-tasks utility. The command accesses the task back end over SSL via the administration connector. To schedule an import task, you must specify the relevant connection options, including how the SSL certificate will be trusted. This example uses the -X option to trust all certificates.

Run the import-ldif command with the --start option.

$ import-ldif -h localhost -port 4444 -D "cn=Directory Manager" -j pwd-file -X \
  -l /ldif-files/example.ldif --start 20080124121500

For more information, see Section 14.4, "Configuring Commands As Tasks."

17.1.3 Exporting Data Using export-ldif

The export-ldif command is used to export data from a directory server back end. The command is useful for the following tasks:

  • Backing up directory data

  • Exporting data to another application

  • Repopulating a database after a change to the directory topology

  • Reinitializing master servers in a replicated topology

Note:

The export-ldif command cannot be used to export data from the following back ends: monitor, ads-truststore, backup, and config-file-handler.

The following sections describe how to export data using the export-ldif command:

17.1.3.1 export-ldif Operation Modes

The export-ldif command has two modes of operation: online and offline.

  • Online mode. In online mode, export-ldif contacts a running directory server instance and registers an export task. This mode runs automatically when the LDAP connection options (--hostname, --port, --bindDN, and --bindPasswordFile) are used. The command accesses the task back end over SSL via the administration connector. For more information, see Section 14.3, "Managing Administration Traffic to the Server."

  • Offline mode. When no connection options are specified, the command runs in offline mode. In offline mode, export-ldif accesses the database directly rather than through a directory server instance. In this case, the directory server must be stopped.

For more information, see Appendix A, "export-ldif".

17.1.3.2 To Export Data to LDIF

  1. Stop the server if it is running.

    $ stop-ds

  2. Export the back end to a specified LDIF file.

    $ export-ldif --includeBranch "dc=example,dc=com" --backendID userRoot \
  --ldifFile example.ldif

17.1.3.3 To Export Partial Data

The export-ldif command provides options to export a part of a back end by specifying the base DN and its children for inclusion or exclusion during processing.

  1. Stop the server if it is running.

    $ stop-ds

  2. Export a portion of the back end.

    In this example, only the entries under ou=People,dc=example,dc=com are exported.

    $ export-ldif --includeBranch ou=People,dc=example,dc=com --backendID userRoot \
  --ldifFile example-people.ldif

  3. Use the ldifsearch command to verify the exported file.

    The ldifsearch command verifies entries in an LDIF file without connecting to the directory server. You can use it in a manner similar to the ldapsearch command. For example:

    $ ldifsearch -b dc=example,dc=com --ldifFile export.ldif "(objectclass=*)"
dn: ou=People,dc=example,dc=com
objectClass: organizationalunit
objectClass: top
ou: People
dn: uid=scarter,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
givenName: Sam
uid: scarter
cn: Sam Carter
sn: Carter
telephoneNumber: +1 408 555 4798
userPassword: {SSHA}Ocpp2P4sImz2MziL69AUG9+khdIhFpmU4B5mvA==
roomNumber: 4612
ou: Accounting
ou: People
l: Sunnyvale
mail: scarter@example.com
facsimileTelephoneNumber: +1 408 555 9751 ...

17.1.3.4 To Export Part of a Back End by Using Filters

The export-ldif command provides options to export part of a back end by using a search filter. The directory server includes or excludes all entries that match the filter. Make sure that you fully understand how this mechanism works before you use it.

In this example, only those entries that match the search filter l=Cupertino (that is, location=Cupertino) are exported. The --excludeFilter option works in a similar manner to --includeFilter, except that it excludes all entries that match the filter during export.

  1. Stop the server if it is running.

    $ stop-ds

  2. Export a portion of the back end by using the --includeFilter option.

    $ export-ldif --includeFilter "(l=Cupertino)" --backendID userRoot \
  --ldifFile export.ldif

17.1.3.5 To Include or Exclude Attributes During Export

The export-ldif utility provides options to include and exclude attributes during export by using the --includeAttribute and --excludeAttribute options, respectively. Make sure that you fully understand how this mechanism works before you use it.

  1. With the server running, view a sample entry, by using the ldapsearch command. For example:

    $ ldapsearch --baseDN dc=example,dc=com "(cn=Sam Carter)"
dn: uid=scarter,ou=People,dc=example,dc=com
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: top
givenname: Sam
uid: scarter
cn: Sam Carter
telephonenumber: +1 408 555 4798
sn: Carter
userpassword: sprain
roomnumber: 4612
mail: scarter@example.com
l: Sunnyvale
ou: Accounting
ou: People
facsimiletelephonenumber: +1 408 555 9751

  2. Stop the server.

    $ stop-ds

  3. Export the back end, using the --includeAttribute option to specify the attributes that should be included in the export.

    You can use the --includeAttribute option multiple times for each attribute that should be included. In this example, only the top level attributes are exported.

    $ export-ldif --backendID userRoot --includeAttribute dn --includeAttribute dc \
  --includeAttibute cn --includeAttribute sn --includeAttribute givenname \ 
  --includeAttribute objectclass --includeAttribute ou --includeAttribute uid \ 
  --ldifFile export.ldif

  4. Use the ldifsearch command to verify the export file.

    If an error occurs, the server continues processing the command.

    $ ldifsearch --baseDN dc=example,dc=com --ldifFile export.ldif "(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 
cn: Directory Administrators 
ou: Groups  
dn: ou=People,dc=example,dc=com 
objectClass: organizationalunit 
objectClass: top 
ou: People ...

17.1.3.6 To Export to LDIF and Then Compress the File

The export-ldif command allows you to compress the output LDIF file.

  1. Stop the server if it is running.

    $ stop-ds

  2. Export to LDIF and then compress the file.

    $ export-ldif --backendID userRoot --ldifFile export.ldif --compress

17.1.3.7 To Run an Export in Online Mode

The export-ldif command can also be run with the server online. In online mode, the command accesses the task back end over SSL via the administration connector. For more information, see Section 14.3, "Managing Administration Traffic to the Server". To run the command in online mode you must specify the relevant connection options, including how the SSL certificate will be trusted. This example uses the -X option to trust all certificates.

Run the export-ldif command with the LDAP connection options. For example:

$ export-ldif -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \ 
  --includeBranch "dc=example,dc=com" --backendID userRoot --ldifFile export.ldif

17.1.3.8 To Schedule an Export

The export-ldif utility provides a --start option for scheduling the export at some future date. You can view this scheduled task by using the manage-tasks utility. The command accesses the task back end over SSL via the administration connector. For more information, see Section 14.3, "Managing Administration Traffic to the Server." To schedule an export task, you must specify the relevant connection options, including how the SSL certificate will be trusted. This example uses the -X option to trust all certificates.

The server must be running to schedule an export.

Run the export-ldif command with the --start option and the LDAP connection parameters.

The --start option takes as its value a date and time in the format yyyymmddhhmmss. For example:

$ export-ldif -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X \ 
  --includeBranch "dc=example,dc=com" --backendID userRoot \ 
  --ldifFile export.ldif --start 20080124121500

17.1.4 Creating MakeLDIF Template Files

The make-ldif command can use template files to define the way in which LDIF files are to be generated. This approach allows for flexibility without the need to alter any code to produce the desired result. The topics in this section describe how to use the make-ldif command to create customized LDIF files.

17.1.4.1 The Template File Format

Template files can contain up to four sections, that must be provided in the following order:

  1. Section 17.1.4.1.1, "Custom Tag Includes"

  2. Section 17.1.4.1.2, "Global Replacement Variables"

  3. Section 17.1.4.1.3, "Branch Definitions"

  4. Section 17.1.4.1.4, "Template Definitions"

17.1.4.1.1 Custom Tag Includes

Custom tag includes provide a mechanism for loading custom tags and making them available for use when processing make-ldif templates. This should be done using the include directive, as follows:

include com.example.opends.makeldif.MyCustomTag

The specified class must be in the class path, and it must be a subclass of the org.opends.server.tools.makeldif.Tag class. For information about developing custom tags, see Section 17.1.4.3, "Defining Custom Tags."

All of the standard replacement tags that are provided with make-ldif are automatically available for use and therefore do not require an explicit include directive.

17.1.4.1.2 Global Replacement Variables

The first section that should be present in the template file is the section that defines the global replacement variables. Global replacement variables are used to define strings of text that can be referenced later in the template file and are automatically replaced as each line is read into memory (much like a C preprocessor replaces macros in code with their defined values). For example, the following replacement variable definition creates a global replacement variable named suffix with a value of dc=example,dc=com:

define suffix=dc=example,dc=com

When a global replacement variable is defined, any case in which that variable name appears in square brackets (for example, [suffix]), causes the token to be replaced with the value that has been defined for that replacement variable.

When all the replacement variable definitions have been read (as signified by the first blank line following one or more replacement variable definitions), all remaining lines that are read from the template file are processed on a line-by-line basis. Any occurrences of a replacement variable name in square brackets are replaced with the value of that variable. Because that replacement is done as the template file is read into memory, replacement variables can occur in any point, including branch and template definitions, and even inside tags.

If there are global replacement variables defined in the template file, they must appear at the top of the file and there should not be any spaces between them. However, replacement variables are not required. If there are no replacement variables, the template file must start with the branch definitions.

17.1.4.1.3 Branch Definitions

Branch definitions are used in make-ldif template files to define the basic structure to use for the generated LDIF. They specify the entry or entries that should appear at the top of the hierarchy, and the number and types of entries that should appear below them.

The most basic form of a branch definition is as follows:

branch: dc=example,dc=com

This example specifies that the following entry is to be created with a DN of dc=example,dc=com:

dn: dc=example,dc=com
objectClass: top
objectClass: domain
dc: example

The basic structure of the entry is defined by the RDN attribute of dc specified in the DN of the branch definition. The make-ldif command automatically associates the dc RDN attribute with the domain object class. The make-ldif command has similar definitions for other common RDN attributes in branch entries:

o

Creates an entry with the organization object class.

ou

Creates an entry with the organizationalUnit object class.

c

Creates an entry with the country object class.

You can also use any other kind of RDN attribute for a branch entry. For branch entries with an RDN attribute other than the ones specified above, the entry is created with the untypedObject and extensibleObject object classes.

The branch definition provided above does not cause any additional entries to be created below that branch entry. To do this, you must specify one or more subordinateTemplate lines. For example:

branch: ou=People,dc=example,dc=com
subordinateTemplate: person:100

This causes the ou=People,dc=example,dc=com entry to be created, and then 1000 other entries created below it modeled after the person template. The person template should be defined later in the template file. For more information, see Section 17.1.4.1.4, "Template Definitions."

Branch entries are not limited to just one subordinateTemplate definition. You can specify multiple subordinateTemplate definitions by including them on separate lines of the branch definition. The following example creates 1000 entries based on the person template and an additional 100 entries based on the certificatePerson template:

branch: ou=People,dc=example,dc=com
subordinateTemplate: person:10000
subordinateTemplate: certificatePerson:100

In all of the examples described previously, the branch entries themselves contain only the DN, the RDN attribute, and the object classes associated with the RDN attribute. You can include any other attributes in the branch entry by including them in the branch definition in the template file. For example, the branch definition:

branch: dc=example,dc=com
description: This is the description for dc=example,dc=com

creates the entry:

dn: dc=example,dc=com
objectClass: top
objectClass: domain
dc: example
description: This is the description for dc=example,dc=com

This additional text can be static, can contain any defined global replacement variables, or can contain a subset of the replacement tags that can be used in template definitions. For an overview of the tags available and information about which tags can be used in branch definitions, see Section 17.1.4.2.1, "Standard Replacement Tags."

17.1.4.1.4 Template Definitions

The heart of the make-ldif template file structure is the set of template definitions. Templates define the structure of the entries that are generated. They specify the set of attributes that should be included in the entries and the types of values that those attributes should contain. The specification of values is handled through tags that are parsed by make-ldif and replaced with the appropriate values for those tags.

A sample template definition might look as follows:

template: person
rdnAttr: uid
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
givenName: <first>
sn: <last>
cn: {givenName} {sn}
initials: {givenName:1}<random:chars:ABCDEFGHIJKLMNOPQRSTUVWXYZ:1>{sn:1}
employeeNumber: <sequential:0>
uid: user.{employeeNumber}
mail: {uid}@[maildomain]
userPassword: password
telephoneNumber: <random:telephone>
homePhone: <random:telephone>
pager: <random:telephone>
mobile: <random:telephone>
street: <random:numeric:5> <file:streets> Street
l: <file:cities>
st: <file:states>
postalCode: <random:numeric:5>
postalAddress: {cn}${street}${l}, {st}  {postalCode}
description: This is the description for {cn}.

This example illustrates some of the flexibility that make-ldif provides when generating LDIF data. The tags that can be included in a template definition are described in the topics that follow (see Section 17.1.4.2.1, "Standard Replacement Tags" and Section 17.1.4.2.2, "Attribute Value Reference Tags").

At the top of the template definition are two lines that provide information about the template itself and are not included in the entries created from this template. The first line specifies the name of the template. This is the name that is referenced in the subordinateTemplate lines of the branch definition. The second line specifies the name of the attribute that should be used as the RDN attribute for the entry. The RDN attribute must be assigned a value in the body of the template definition, and the way in which the value is assigned must ensure that the value will be unique among all other entries created with the same template below the same parent.

Note:

It is possible to specify multi-valued RDNs by separating the attribute names with a plus sign, as shown in the following example:

rdnAttr: uid+employeeNumber

If multi-valued RDNs are used, all of the RDN attributes must be defined values in the template body and the combination of the RDN values for each entry must be unique. However, it is possible for one or more of the attributes in the RDN to be non-unique as long as the combination is never duplicated.

In addition to the template and rdnAttr lines, you can include one or more subordinateTemplate lines. This enables you to include dynamically-generated entries below other entries that have been dynamically generated (for example, if each user entry has one or more entries below it), and to allow for complex hierarchies. Although there is no limit placed on this level of nesting, you must ensure that no recursive loops are created by having a subordinateTemplate that either directly or indirectly will create additional entries using the same template.

Template definitions also support the concept of inheritance through the use of the extends keyword. For example, entries generated from the following template definition include all of the attributes defined in the person template as well as userCertificate;binary with the specified format:

template: certificatePerson
rdnAttr: uid
extends: person
userCertificate;binary:: <random:base64:1000>

Multiple inheritance is allowed (by including multiple lines with the extends keyword), but as with the subordinateTemplate keyword it is important not to create a recursive loop in which a template file could either directly or indirectly inherit from itself.

17.1.4.2 make-ldif Template File Tags

To ensure that make-ldif can generate LDIF files that can be used to simulate a wide variety of deployments, a large number of tags have been defined for use in templates. This section describes the standard set of tags that can be used in a make-ldif template file. You can also create custom tags, as described in Section 17.1.4.3, "Defining Custom Tags."

This section contains the following topics:

17.1.4.2.1 Standard Replacement Tags

The make-ldif standard replacement tags are special elements that are enclosed in angle brackets (beginning with a less-than sign (<) and ending with a greater-than sign (>) that are dynamically replaced with generated values. Some standard replacement tags do not require any arguments (for example, <first>). Others do take arguments, in which case the tag name comes first followed by a colon and the argument list with a colon between each argument (for example, <random:numeric:5>). The tag name is treated in a case-insensitive manner, although the arguments are generally case sensitive.

The following types of standard replacement tags are currently included as part of make-ldif:

The DN tag

The DN standard replacement tag is replaced with the DN of the current entry. If that DN is not yet available (for example, because the RDN attribute has not yet been assigned a value in the entry being generated), it is replaced with an empty string. In general, you should ensure that all RDN attributes are assigned values earlier in the template before this tag is used.

The DN tag can be used without any arguments (for example, <DN>), in which case it is replaced with the full DN of the entry. The tag can also take a single integer argument, which specifies the maximum number of components to include in the output. For example, the tag <DN:1> will only include the left most DN component (often called the RDN) for the entry. So if the entry being generated will have a DN of uid=john.doe,ou=People,dc=example,dc=com, the tag <DN:1> will be replaced with uid=john.doe. If the argument value is negative rather than positive, then it takes the absolute value of the given argument value and takes that number of components from the end of the DN. For example, using a DN of uid=john.doe,ou=People,dc=example,dc=com the tag <DN:-1> is replaced with dc=com.

This tag can be used in both branch and template definitions.

The File tag

The File standard replacement tag is replaced with a line from a specified file. It requires either one or two arguments. The first argument is the path to the data file, and can be either an absolute path or the name of a file (with no path information) that is contained in the config/MakeLDIF directory. If there is a second argument, it must have a value of either sequential or random, which indicates whether the lines in the file should be taken in sequential order or chosen at random. If the second argument is not provided, the values are selected at random. For example, the tags <file:cities> and <file:cities:random> both cause the tag to be replaced with a randomly-selected line from the cities file, but the tag <file:cities:sequential> causes the city names to be taken in sequential order. If sequential ordering is used and all values are exhausted, it will wrap back around to the first line of the file.

The make-ldif command includes a number of standard data files that can be used in generated data. These files are included in the config/MakeLDIF directory and therefore only the filename is required. The files include:

cities — contains a list of common city names

first.names — contains a list of common first names

last.names — contains a list of common last names

states — contains a list of all two-character US state abbreviations

streets — contains a list of common street names

This tag can be used in both branch and template definitions.

The First tag

The First standard replacement tag is replaced with a first name taken from the config/MakeLDIF/first.names file. Note that there is a special relationship between the <first> and <last> tags such that the combination of the first and last names is always unique. When every possible combination from the first and last name files has been exhausted, make-ldif appends an integer value onto the last name to ensure that the value always remains unique.

The <first> tag does not take any arguments. It can be used only in template definitions. It is not allowed for use in branch definitions.

The GUID tag

The GUID standard replacement tag is replaced with a randomly generated GUID (globally-unique identifier) value. All GUID values generated are guaranteed to be unique. The values generated consist of 32 hexadecimal digits in dash-delimited groups of 8, 4, 4, 4, and 12 digits, respectively (for example, 12345678-90ab-cdef-1234-567890abcdef).

The <guid> tag does not take any arguments. It can be used in both branch and template definitions.

The IfAbsent tag

The IfAbsent standard replacement tag does not generate any value of its own, and is therefore always be replaced with an empty string. However, its value is that it can prevent an attribute from appearing in the entry altogether based on whether a specified attribute or attribute value exists.

For example, consider the following template:

template: example
rdnAttr: cn
objectClass: top
objectClass: untypedObject
objectClass: extensibleObject
cn: <guid>
displayName: <presence:50>{cn}
description: <ifabsent:displayName>{cn}

In this case, the description attribute is only included in the generated entry if the displayName attribute is not included (that is, the resulting entry will contain either displayName or description but not both).

The IfAbsent tag requires either one or two arguments. The first argument is the name of the target attribute. If there is a second argument, it specifies a particular value for the target attribute. If a value is provided, the IfAbsent tag takes action if that value is included in the generated entry.

This tag can be used in both branch and template definitions.

The IfPresent tag

The IfPresent standard replacement tag does not generate any value of its own, and is therefore always replaced with an empty string. However, its value is that it can prevent an attribute from appearing in the entry altogether based on whether a specified attribute or attribute value exists.

For example, consider the following template:

template: example
rdnAttr: cn
objectClass: top
objectClass: untypedObject
objectClass: extensibleObject
cn: <guid>
displayName: <presence:50>{cn}
description: <ifpresent:displayName>{cn}

In this case, the description attribute will only be included in the generated entry if the displayName attribute is also included (that is, the resulting entry will either contain neither attribute or it will contain both attributes).

The IfPresent tag requires either one or two arguments. The first argument is the name of the target attribute. If there is a second argument, it specifies a particular value for the target attribute. If a value is provided, the IfPresent tag will only take action if that value is included in the generated entry.

This tag can be used in both branch and template definitions.

The Last tag

The Last standard replacement tag is replaced with a last name taken from the config/MakeLDIF/last.names file. Note that there is a special relationship between the <first> and <last> tags such that the combination of the first and last names will always be unique. When every possible combination from the first and last name file has been exhausted, make-ldif will append an integer value onto the last name to ensure that the value always remains unique.

The <last> tag does not take any arguments. It can only be used in template definitions. It is not allowed for use in branch definitions.

The List tag

The List standard replacement tag is replaced with a string selected from a provided list of values. The values to use should be provided as arguments to the List tag (at least one argument must be provided). Optionally, each value can be followed with a semicolon and an integer value that specifies the relative weight for that value. If a value does not include a weight, the weight for that item is assumed to be one. The weight is used to control how frequently the associated value is chosen compared with all of the other values in the list.

For example, to select from a list of the colors red, green, and blue in which all listed colors have equal weights, you can use:

<list:red:green:blue>

If the color red is to appear twice as frequently as either of the other colors, you can use:

<list:red;2:green;1:blue;1>

Note that in this case, the 1 following the green and blue elements are not technically needed since the weight of any item that does not explicitly include a weight is one, but it is provided in the example above for clarity.

This tag can be used in both branch and template definitions.

The ParentDN tag

The ParentDN standard replacement tag is replaced with the DN of the parent entry of the entry being generated. This should always be available.

This tag does not take any arguments. It can only be used in template definitions. It cannot be used in branch definitions.

The Presence tag

The Presence standard replacement tag does not generate any value of its own, and is therefore always replaced with an empty string. However, its value is that it can be used to cause the associated attribute to appear in the entry a specified percentage of the time.

For example, consider the following template:

template: example
rdnAttr: cn
objectClass: top
objectClass: untypedObject
objectClass: extensibleObject
cn: <guid>
displayName: <presence:50>{cn}

In this case, the displayName attribute will only be present in about 50% of the entries generated.

The Presence tag requires exactly one argument, which is an integer value between 0 and 100, indicating the percentage of entries that should have the associated attribute.

This tag can be used in both branch and template definitions.

The Random tag

The Random standard replacement tag is replaced with a randomly-generated value. A number of different types of values can be generated. This tag accepts a variable number of arguments, but the first argument always specifies the type of value to generate. That type may be one of the following values:

  • alpha. This causes the tag to be replaced with a specified number of lowercase ASCII alphabetic characters (that is, the character set abcdefghijklmnopqrstuvwxyz). This requires exactly one more argument, which is an integer specifying the number of characters to include in the generated value. For example, <random:alpha:5> generates a string of five randomly-selected alphabetic characters.

  • numeric. This causes the tag to be replaced with one or more numeric digits. There can be either one or two additional arguments. If there is one additional argument, it specifies the number of numeric digits to include in the value (for example, <random:numeric:5> will generate a string of five numeric digits). If there are two additional arguments, they will specify the upper and lower bounds for a randomly-generated number (for example, <random:numeric:5:10> will generate a random integer between 5 and 10, inclusive).

  • alphanumeric. This causes the tag to be replaced with a specified number of lowercase ASCII alphabetic characters (that is, the character set abcdefghijklmnopqrstuvwxyz) and/or numeric digits (that is, the character set 0123456789). This requires exactly one more argument, which is an integer specifying the number of characters to include in the generated value. For example, <random:alphanumeric:5> will generate a string of five randomly-selected alphanumeric characters.

  • chars. This causes the tag to be replaced with characters from a user-defined character set. This can take either two or three additional arguments. The first additional argument is the characters for the user-defined character set. If there is a single argument after the character set, it specifies the number of characters to take from that set (for example, <random:chars:abcd:3> will cause three characters to be chosen in which each of those characters is either a, b, c, or d). If there are two arguments after the character set, they must be integer values and the number of characters generated will be an integer between this range (for example, <random:chars:abcd:3:5> will cause between 3 and 5 characters to be included in the value, where each character is either a, b, c, or d).

  • hex. This causes the tag to be replaced with a specified number of hexadecimal characters (that is, the character set 0123456789abcdef). This requires exactly one more argument, which is an integer specifying the number of characters to include in the generated value. For example, <random:hex:5> will generate a string of five randomly-selected hexadecimal characters.

  • base64. This causes the tag to be replaced with a specified number of characters allowed in the base64 character set (ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz01234567890+/). This requires exactly one more argument, which is an integer specifying the number of characters to include in the generated value. For example, <random:base64:5> will generate a string of five randomly-selected hexadecimal characters.

  • month.This causes the tag to be replaced with the name of a month of the year. If there are no additional arguments, the full name of the month is included (for example, <random:month> might return a value of October). If there is a single additional argument, it must be an integer value that specifies the maximum number of characters to include from the name of the month (for example, <random:month:3> might generate a value of Oct).

  • telephone.This causes the tag to be replaced with a randomly-generated telephone number in the format 123-456-7890. It does not take any additional arguments (that is, it should always be used like <random:telephone>).

This tag can be used in both branch and template definitions.

The RDN tag

The RDN standard replacement tag is replaced with the RDN (that is, the leftmost DN component) of the current entry. If the RDN is not yet available (for example, because the RDN attribute has not yet been assigned a value in the entry being generated), it will be replaced with an empty string. In general, you should ensure that all RDN attributes are assigned values earlier in the template before this tag is used. The behavior of this tag is identical to that of the DN tag when used with a single argument whose value is one (that is, <dn:1>).

The RDN tag does not take any arguments. It can be used in both branch and template definitions.

The Sequential tag

The Sequential standard replacement tag is replaced with an integer value. Each entry is given a sequentially-incrementing value (for example, the first entry is given a value of zero, the next entry a value of one, and so on).

This tag can take zero, one, or two arguments:

  • If there are no arguments (that is, the tag is <sequential>), the first value will be zero, and the value will be reset to zero for each new branch.

  • If there is a single argument, it must be an integer that specifies the initial value to use (for example, a tag of <sequential:1000> will start generating values at 1000 instead of 0). The value will be reset to the specified initial value for each new branch.

  • If there are two arguments, the first must be an integer that specifies the initial value, and the second should be a Boolean value of either true or false indicating whether to reset the counter each time a new branch is started.

This tag can be used in both branch and template definitions.

The _DN tag

The _DN (note the leading underscore character) standard replacement tag is replaced with the DN of the entry being generated, but with an underscore used instead of a comma between DN components. Apart from using underscores instead of commas, this works exactly like the DN tag. As such, it can also take an optional integer argument that specifies the number of components from the left (or from the right if the value is negative) should be included.

This tag can be used in both branch and template definitions.

The _ParentDN tag

The _ParentDN (note the leading underscore character) standard replacement tag is replaced with the DN of the parent entry of the entry being generated, but with an underscore used instead of a comma between DN components. This should always be available.

This tag does not take any arguments. It can only be used in template definitions. It cannot be used in branch definitions.

17.1.4.2.2 Attribute Value Reference Tags

Attribute value reference tags can be used to replace the tag with the value of a specified attribute from the same entry. They are used by enclosing the name of the desired attribute in curly braces. For example, {cn} will be replaced with the value of the cn attribute, if it has already been given a value in the target entry. If the target attribute has not yet been given a value in the entry, the tag will be replaced with an empty string.

For example, consider the following excerpt from a template:

givenName: <first>
sn: <last>
uid: {givenName}.{sn}
cn: {givenName} {sn}
mail: {uid}@example.com

If the value chosen for the first name is John and the last name is Doe, then the resulting LDIF output would be:

givenName: John
sn: Doe
uid: John.Doe
cn: John Doe
mail: John.Doe@example.com

It is also possible to place a colon after the name of the attribute followed by a positive integer value specifying the maximum number of characters to include from the target attribute. For example, the template excerpt:

givenName: <first>
sn: <last>
initials: {givenName:1}{sn:1}

would cause the following LDIF to be generated:

givenName: John
sn: Doe
initials: JD

If the specified length is longer than the value of the named attribute, the entire value is used with no padding added. Otherwise, the specified number of characters are taken from the value.

17.1.4.2.3 Tag Evaluation Order

All tags in the make-ldif syntax are currently given equal priority. As such, they are evaluated in the order that they appear in the template definition, from top to bottom, and from left to right within a given line. It is not possible to embed one tag within another.

17.1.4.3 Defining Custom Tags

The make-ldif utility has been designed in an extensible manner so that new tags can be defined and used in template files.

All tags must be subclasses of the org.opends.server.tools.makeldif.Tag abstract class. Custom tag definitions must include the following methods:

public String getName()

This retrieves the name that should be used to reference the tag. The value that it returns must be unique among all other tags in use by the server.

public boolean allowedInBranch()

This indicates whether the tag will be allowed in branch definitions. If it returns a value of true, then the tag may be used in both branch and template definitions. If it returns a value of false, then the tag may be used in template definitions but not branch definitions.

public void initializeForBranch(TemplateFile templateFile, Branch branch, String[] arguments, int lineNumber, List<String> warnings)

This performs any initialization that may be required if the tag is to be used in a branch definition. This does not need to be implemented if allowedInBranch() returns false.

public void initializeForTemplate(TemplateFile templateFile, Template template, String[] arguments, int lineNumber, List<String> warnings)

This performs any initialization that may be required of the tag is to be used in a template definition.

public void initializeForParent(TemplateEntry parentEntry)

This performs any initialization that may be required before starting to generate entries below a new parent. This does not need to be implemented if no special initialization is required.

public TagResult generateValue(TemplateEntry templateEntry, TemplateValue templateValue)

This generates the value that will be used to replace the associated tag when generating entries.

All of the tags available in make-ldif are included in the org.opends.server.tools.makeldif package. They may be used for reference to understand what is involved in implementing a custom tag.

Note:

If you define a custom tag, ensure that it is available for use in any template file that might need it. This is done using the include statement, that should appear at the top of the template file. For more information, see Section 17.1.4.1.1, "Custom Tag Includes."

17.2 Importing Large Data Sets

The topics in this section provide tips on improving performance when importing large data sets to the directory server. By default, the server imports data with a fixed set of parameters. You can change the default behavior in two ways:

17.2.1 Setting the Import Options

The following options of the import-ldif command are useful when you are importing particularly large databases:

  • --skipDNValidation

    This option significantly speeds up a large import because no DN validation or database loading is performed during the first phase of the import. The DNs in the LDIF file are treated as regular indexes and are written to a scratch index file that is loaded in phase two of the import.

    During the second phase of the import, limited DN parental checking is performed. During this evaluation, the DNs in the LDIF file are examined to make sure that each DN has a correct parent DN. When a DN is detected without a parent, a dummy entry is written to the reject file.

    If the --skipDNValidation option is specified, no duplicate DN checking is performed.

    The server does not remove bad entry IDs from the index database during phase two of the import. It is therefore essential that the LDIF import file is correct if the --skipDNValidation option is specified. Correct LDIF files are generally those that are generated by using the make-ldif command, LDIF files exported from an LDAP server, or LDIF files created by scripts that are historically known to generate correct LDIF files.

  • --threadCount

    This option speeds up a large import by enabling you to specify that more threads are dedicated to the import process. By default, two threads per CPU are used for an import operation.

    Increasing the --thread-count also increases the buffer space that is required in phase one of the LDIF import.

  • --tmpDirectory

    In the first phase of the import, the server parses the LDIF file, sorts the index records, and writes the records to temporary files. By default, the temporary index files are written to intall-dir/import-tmp. If you are importing particularly large index files, you might want to specify another location that has more disk space.

    The amount of space required for the temporary index files depends on the following factors:

    • The number of entries in the LDIF file.

    • The size of the entries in the LDIF file.

      Entries with large numbers of attributes that require indexing will require more space in the temporary directory location, and in the database directory.

    • The number of indexes that are configured.

      The more indexes that are configured, the more disk space is required in the temporary directory location, and in the database directory. Substring indexes require more temporary disk space to process than other types of indexes.

    • Increasing the index-entry-limit for all indexes, or for individual indexes, requires more disk space.

      This is especially true for substring indexes. If you are importing an LDIF file with a large number of entries, you should turn off all substring indexing to prevent a number of the index records will hitting the index-entry-limit.

17.2.2 Tuning the JVM and Java Arguments

Tuning the JVM heap is essential to the performance of the import-ldif command. Although the import-ldif command attempts to limit the amount of JVM heap that it requires, you should allocate as large a JVM heap as possible to import-ldif if you are importing a large number of entries.

The following JVM tuning considerations have specific impact on the import-ldif operation:

  • Performing an online import uses the JVM settings that were specified when the server was started. If you plan to import a large LDIF file by using the online import, you should provide extra JVM heap when the server is started. In general, if you need to import a large LDIF file, the best option is to perform an offline import.

  • The 32-bit JVM generally performs better for smaller LDIF files and for most larger LDIF files.

    You should always try this JVM first, with as large a heap as can be spared. A minimum heap of 2 Gbytes is recommended.

  • You might require a 64-bit JVM with a large JVM heap (greater than 4 Gbytes) for extremely large LDIF files, depending on the size of the entries and the indexes configured.

    The 64-bit JVM does not generally perform as well as the 32-bit JVM.

  • The default JVM ergonomics might be too small for some JVMs and can seriously impact performance.

    Take note of the default ergonomic values for your JVM (these values differ by vendor and by operating system).

  • If you are using replication, you should budget additional JVM heap, particularly if you plan to do a full initialization of the other replicas in the topology after an online import.

  • Enable parallel garbage collection for large imports.

  • Use the Concurrent Mark Sweep (CMS) garbage collector. This option allows the JVM to minimize the response time of LDAP operations, but it can have a small impact on the overall performance (throughput) of the server.

When you have calculated the memory requirement, perform the following steps:

  1. Edit the instance-dir/OUD/config/java.properties file and set the following values:

    overwrite-env-java-args=true
import-ldif.offline.java-args=-Xms2560M -Xmx2560M -XX:+UseParallelGC -XX:+UseConcMarkSweepGC

  2. Run the dsjavaproperties command:

    $ bin/dsjavaproperties

Note:

Running the dsjavaproperties command, or setting the OPENDS_JAVA_ARGS environment variable, only has a performance impact if the import is offline. If the server is already running and you perform an online import, changing the Java arguments has no impact on the import performance because the import is performed by the server JVM.

17.3 Backing Up and Restoring Data

Oracle Unified Directory provides an extensible framework that supports a variety of repository types. The directory server uses the Berkeley DB Java Edition (JE) as its primary back end. The JE back end provides some advantages over other databases as it provides a high-performance, scalable transactional B-tree database with full support for ACID semantics for small to very large data sets. It can also store its entries in encoded form and provide indexes for fast, efficient data retrieval.

This section covers the following topics:

17.3.1 Overview of the Backup and Restore Process

To maintain the directory data on the JE back end, Oracle Unified Directory provides efficient backup and restore utilities that support full and incremental backups. A full backup saves the directory data files in the environment as a compressed archive file. An incremental backup saves and compresses just those files that have been written since the previous backup, together with a list of names of files that are unchanged since the previous backup. Oracle Unified Directory stores its backup information in a backup back end for easy restores

Directory server backups can be made on the local disks or on remote disks, for example, on network-attached storage (NAS). If you run a backup locally, you should then copy and store the backup on a different machine or file system for security purposes.

Before you start backing up and restoring data, consider the following:

  • You must design a workable backup and restore strategy for your directory services system. For example, you can run an incremental backup daily and perform a full backup at least once a week. Test your backup process and your ability to restore regularly. For data restores, many companies restore a directory server from a replicated server, which ensures that the most update copy of the directory data is used. Backup tapes are still needed if the directory data is damaged (for example, missing entries) and the corrupted data has been replicated to other servers.

  • Ensure that you have a disaster recovery plan in place. Disaster recovery is necessary when catastrophic events, data corruption, or data tampering occurs. Companies devise their own plans or out source the work to third party specialists. See Section 17.3.4, "Backing Up for Disaster Recovery" for more information.

  • Ensure that you have a place to store your back ups. Store the archived data, configuration directory, schema subdirectory, and installation directory used for your server together in a single location. All these items are required when you restore the server.

17.3.2 Backing Up Data

The directory server provides an efficient command-line utility (backup) to back up databases. The backup command can be run immediately or scheduled as a task. If the backup is scheduled, the command contacts the server over SSL, using the administration connector, and registers a backup task. If no connection options are specified, the command runs immediately.

The following procedures show the use of the backup command in various backup scenarios.

17.3.2.1 To Back Up All Back Ends

You can back up all back ends end by using the --backUpAll option.

The following command is run on a standalone directory server and specifies that all databases should be backed up, compresses the backup file, and saves the file to a specified location.

$ backup --backUpAll --compress --backupDirectory /tmp/backup

The backup directory contains subdirectories for each back end:

$ ls /tmp/backup
./ ../ config/ schema/ tasks/ userRoot/

The backup utility writes the backup to the specified directory and creates a backup.info file that provides details about the backup. The directory server assigns a backup ID based on the current date and time. To create your own ID, use the --backupID option:

$ ls /tmp/backup/config
./ backup.info
../ config-backup-20070827153501Z

The backup.info file contains detailed information about the current backup.

$ more /tmp/backup/config/backup.info
backend_dn=ds-cfg-backend-id=config,cn=Backends,cn=config

backup_id=20070827153501Z
backup_date=20070827153511Z
incremental=false
compressed=true
encrypted=false
property.archive_file=config-backup-20070827153501Z

17.3.2.2 To Back Up All Back Ends with Encryption and Signed Hashes

The backup utility provides encryption and signed hash support for secure backups. The use of the encryption and signed hash options requires a connection to an online server instance, so the appropriate connection options must be specified.

Run the backup command.

The following command backs up all back ends, compresses them, generates a hash, signs the hash, and encrypts the data.

$ backup -h localhost -p 4444 -D "cn=directory manager" -j pwd-file --backUpAll \
  -X --compress --hash --signHash --encrypt --backupID 123 \
  --backupDirectory /tmp/backup

17.3.2.3 To Perform an Incremental Backup on All Back Ends

Incremental backups save only those changes that have occurred since the last backup (full or incremental). The main advantage of an incremental backup is the faster time to back up a system when compared to that of full backups. The disadvantage of an incremental backup is that each incremental backup must be restored, which requires more time and care than that of a full restore.

To perform an incremental backup, run the backup command with the --incremental option, as follows:

$ backup --backUpAll --incremental --compress --backupDirectory /tmp/backup

17.3.2.4 To Back Up a Specific Back End

You can back up a single back end by using the --backendID option, which specifies the back end to save.

  1. List the back ends that are configured on the server, by running the list-backends command. For example:

    $ list-backends

Backend ID     Base DN
-------------- -----------------
adminRoot      cn=admin data
ads-truststore cn=trust-store
backup         cn=backups
config         cn=config
monitor        cn=monitor
schema         cn=schema
tasks          cn=tasks
userRoot       dc=example,dc=com

  2. Run the backup command with the --backendID option.

    For example, to back up the userRoot back end, run the following command:

    $ backup --backendID userRoot --backupDirectory /tmp/backup

    If you back up a single back end and replication is configured, any changes that you make to that back end are stored in the change log on the replication server. When you restore that back end, the replication server detects that the back end is not up to date and replays the changes made after the backup. This behavior occurs even if there is only one directory server in the replicated topology, because the changes are stored on the replication server.

    If you do not want this behavior, back up all back ends in a replicated environment. This ensures that the data, and the replication server are backed up. In this case when a restore is done, the directory server and the replication server are restored to their state before the back up, and no memory of subsequent changes remains.

17.3.2.5 To Perform an Incremental Backup on a Specific Back End

  1. List the back ends that are configured on the server, by running the list-backends command. For example:

    $ list-backends

Backend ID     Base DN
-------------- -----------------
adminRoot      cn=admin data
ads-truststore cn=trust-store
backup         cn=backups
config         cn=config
monitor        cn=monitor
schema         cn=schema
tasks          cn=tasks
userRoot       dc=example,dc=com

  2. Run the backup command with the --incremental option.

    $ backup --incremental --backendID userRoot --backupDirectory /tmp/backup

17.3.2.6 To Schedule a Backup as a Task

The directory server provides a task back end for processing administrative tasks, such as backups and restores. You can specify the start time for a backup or restore by using the -t or --start option. If one of these options is provided, the utility exits immediately after scheduling the task. To schedule a task for immediate execution and have the utility exit immediately after scheduling the task, specify 0 as the value for the start time. If the -t or --start option is omitted, the utility schedules the task for immediate execution and tracks the task's progress, printing log messages as they are available and exiting when the task has completed.

Access to the task back end is provided over SSL via the administration connector. If you schedule the backup as a task, you must therefore specify how the SSL certificate will be trusted. This example schedules a backup for execution at a future time. The -X option specifies that all certificates presented by the server are trusted. For more information, see Section 14.3, "Managing Administration Traffic to the Server."

  1. Run the backup command with the following options:

    $ backup --port 4444 --bindDN "cn=Directory Manager" \
  --bindPasswordFile pwd-file -X \
  --backUpAll --backupDirectory /tmp/backups --start 20080601121500 \
  --completionNotify admin@example.com --errorNotify admin@example.com

  2. View information about the scheduled task by using the manage-tasks command. For example:

    $ manage-tasks --port 4444 --bindDN "cn=Directory Manager" \
  --bindPasswordFile pwd-file -X --info 2008040210324704 --no-prompt

17.3.3 Backing Up the Server Configuration

All configuration settings for a directory server instance are stored in the config.ldif file, which is located in the config directory. The directory server automatically saves the config.ldif file to ensure that changes are properly accounted for in the configuration. The file is saved at two specific times:

  • At startup. If the current configuration does not match the archived configuration, the server saves the config.ldif file.

  • At modification time. Whenever a directory administrator makes changes to the configuration by using the dsconfig utility with the server online, the directory server saves the config.ldif file prior to the change.

You can access archived configuration files from the INSTANCE_DIR/OUD/config/archived-configs directory. This directory lists each saved configuration file, compresses it as a.gz file, and saves the configuration as config-timestamp.gz. For example, you can see archived config.ldif files as follows:

$ ls config/archived-configs
09/02/2010 03:43 PM 9,045 config-20100819055359Z.gz

17.3.4 Backing Up for Disaster Recovery

Directory and system administrators should have a disaster recovery plan in place in the event of a natural, human-induced, or catastrophic disaster. If your directory service is distributed over multiple individual servers, back up all the servers individually or back up all the directory data from a central location.

Alternatively, consider replication as a backup and restore strategy. Replication provides faster restores and more update data from another replicated server. For more information, see Section 17.3.7, "Restoring Replicated Directory Servers."

17.3.4.1 To Back Up the Directory Server For Disaster Recovery

  1. Make a backup of all back ends by using the --backUpAll option, for example:

    $ backup --backUpAll --backupDirectory /tmp/backup

  2. Copy the configuration directory, INSTANCE_DIR /OUD/config.

    Make sure that the schema subdirectory is present within the INSTANCE_DIR /OUD/config directory.

  3. Copy the files in INSTANCE_DIR/OUD/logs.

  4. Make a copy of the installation directory.

  5. Store the archived data, configuration directory, schema subdirectory, log files and installation directory together in a single location.

    All items are required when restoring the server.

17.3.5 Backing up and Restoring Data Using File System Snapshots

For certain deployments, file system snapshot technologies offer a viable alternative to the traditional backup. On Solaris systems, ZFS enables file system snapshots that are space efficient, very quick to create, and portable between systems. By dedicating a Directory Server per data center, or two if your entire service runs in one data center, you deploy an effective, redundant solution for restoring data as part of your disaster recovery plan.

This section contains the following topics:

17.3.5.1 To Take a ZFS Snapshot On a Dedicated Backup Server

  1. Because the Directory Server is dedicated to backup, configure the server as a read-only replica if you have not already done so.

    $ dsconfig -h host -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-global-configuration-prop --set writability-mode:internal-only

    When you restore a server from the snapshot of the read-only replica, the restored server accepts only replication traffic until you enable writability, after the server has caught up with other replicas in the topology.

  2. Take the ZFS snapshot.

    For example, if the Directory Server files are stored in the file system corresponding to zpool/DS_FS, the command is:

    $ zfs snapshot zpool/DS_FS@{todays_date}

  3. Back up the snapshot to other storage.

    $ zfs send zpool/DS_FS@{today_date} > /backups/DS_FS.{today_date}.zfs

    Do not keep snapshots longer than the replication purge delay, because when you restore from a snapshot, the replication mechanism has to be able to replay all the missing changes on the replica.

17.3.5.2 To Restore a Directory Server From a ZFS Snapshot

  1. Import the backup zpool.

    Create a ZFS file system to access the backup pool, using /backups as the mount point.

  2. Stop the Directory Server that is being restored.

  3. Initialize the ZFS file system from /backups.

    $ dd if=/backups/DS_FS.{date_to_restore}.zfs bs=32k | zfs receive -F zpool/DS_FS

  4. Adapt the configuration as necessary to use the host name and port numbers of the Directory Server to restore.

  5. Start the Directory Server.

  6. Monitor replication until you observe that the Directory Server is in sync with other replicas in the topology.

  7. Set the writability-mode to enabled, allowing the Directory Server to process write operations from clients.

    $ dsconfig -h restored-host -p 4444 -D "cn=Directory Manager" -j pwd-file -X \
  -n set-global-configuration-prop --set writability-mode:enabled

17.3.6 Restoring Data

You can restore data by using the restore utility. The restore utility allows you to restore only one back end at a time. The directory server must be stopped prior to a restore, unless you are scheduling a restore task, or you are restoring data that has been signed or hashed.

This section contains the following topics:

17.3.6.1 To Restore a Back End

  1. Stop the server, if it is running.

  2. Display the backup information by running the restore command with the --listBackups option. For example:

    $ restore --listBackups --backupDirectory backup/userRoot  
Backup ID: 20080827153501Z 
Backup Date: 27/Aug/2008:10:35:11 -0500 
Is Incremental: false 
Is Compressed: true 
Is Encrypted: false 
Has Unsigned Hash: false 
Has Signed Hash: false 
Dependent Upon: none

  3. Restore the back end.

    $ restore --backupDirectory backup/userRoot

  4. Repeat the restore for the other back ends.

17.3.6.2 To Restore a Back End From Incremental Backups

Typically, system administrators run a weekly full backup with daily incremental backups. Be aware that it takes longer to restore your system from incremental backups.

  1. Restore the last full backup on your system by using the restore command.

    Each back end must be restored individually.

  2. Restore each incremental backup by using the restore command.

    Restore each incremental backup starting from the last full backup.

17.3.6.3 To Schedule a Restore as a Task

The directory server provides a task back end for processing administrative tasks, such as backups and restores. You can specify the start time for a restore by using the -t or --start option. If one of these options is provided, the utility exits immediately after scheduling the task. To schedule a task for immediate execution and have the utility exit immediately after scheduling the task, specify 0 as the value for the start time. If the -t or --start option is omitted, the utility schedules the task for immediate execution and tracks the task's progress, printing log messages as they are available and exiting when the task has completed.

Access to the task back end is provided over SSL, using the administration connector. If you schedule the restore as a task, you must therefore specify how the SSL certificate will be trusted.

  1. Ensure that the server is stopped prior to the scheduled restore time.

  2. Schedule the restore by using the -t or --start option of the restore command.

    The following command restores the userRoot back end at a scheduled start time by using the --start option. The restore sends a completion and error notification to admin@example.com. The -X option specifies that all certificates presented by the server are trusted.

    $ restore -p 4444 -D "cn=Directory Manager" -j pwd-file -X \ 
  -d /backup/userRoot --start 20080125121500 --completionNotify admin@example.com \
  --errorNotify admin@example.com

  3. You can view this scheduled task by using the manage-tasks utility.

    For more information, see Section 14.4, "Configuring Commands As Tasks."

17.3.6.4 To Restore the Configuration File

You might need to restore the configuration file to transfer the configuration to another server, for disaster recovery purposes, or for other events. In general, if a server is online, the current configuration file is equivalent to the latest archived configuration file. However, you can choose to restore the config.ldif file from a previous date.

  1. Stop the server if it is running.

  2. Locate the required configuration file on the system. For example:

    $ ls INSTANCE_DIR/OUD/config/archived-configs
./ 
../
config-20110817192057Z.gz
config-20110827153200Z.gz
config-20110817192052Z.gz
config-20110827153214Z-2.gz

  3. Manually decompress the archived configuration file, using a decompression utility such as gunzip.

  4. Copy the file to the config directory, replacing the current config.ldif file.

    $ cp config-20110817192057Z INSTANCE_DIR/OUD/config/config.ldif

17.3.6.5 To Restore a Directory Server During Disaster Recovery

  1. Install the same version of the directory server that was previously installed on the host.

  2. Create a server instance by using the setup command.

  3. Copy the saved config directory to INSTANCE_DIR/OUD/config.

    The config.ldif file should reside in this directory. The saved schema subdirectory should be located in INSTANCE_DIR/OUD/config/schema.

  4. Check that the configuration for the restored server is correct.

  5. Restore the individual back ends by using the restore command.

17.3.7 Restoring Replicated Directory Servers

Performing binary restores in replicated environments requires special care depending on your replicated topology. If possible, update your back end by using the replication mechanisms in your system instead of restoring it from a backup. Replication has distinct advantages over traditional tape backups. Data restores are much faster than tape restores, and the data is more up to date. However, tapes are still needed in the event that the replicated data is corrupt and has been propagated to other servers.

When restoring a replicated server, ensure that the configuration file INSTANCE_DIR/OUD/config/config.ldif is the same as when the backup was made. Restore the config.ldif file prior to restoring the server back ends.

You cannot restore an old backup to a master server because it might be out of date. Rather allow the replication mechanism to bring a master up to date with the other master servers by setting that master to read-only. When the master has been synchronized, you can reset it to read-write.

If you need to restore a replicated server, reinitialize the server from one of the other replicated servers by importing an LDIF file.

For very large databases (millions of entries), make a binary copy of one server and restore it on the other replicated server.

If you have a fairly recent backup (one that is not older than the maximum age of the change log contents on any of the other replicated servers), you can use that version to restore your data. When the old backup is restored, the other servers will update that server with recent updates made since the backup was saved.

17.3.8 Deleting Backup Data

If you run regular backups, the backup files might start to consume too much disk space. You must remove the old backup files manually to create space for new ones.

17.3.8.1 To Delete Backup Files

When you delete backup files manually, make sure that you do not break any dependencies between backup sets.

  1. List the existing backups in your backup directory.

    For example, to list the backups in the default backup directory, run the following command:

    UNIX: $ ls INSTANCE_DIR/OUD/bak
       backup-userRoot-20110929184101Z backup-userRoot-20111029184509Z
       backup.info backup.info.save

WINDOWS: C:\> dir INSTANCE_DIR\OUD\bak
         backup-userRoot-20110929184101Z backup-userRoot-20111029184509Z
         backup.info backup.info.save

  2. Delete the backup file from the backup directory.

    For example, to remove the oldest backup of the userRoot database in the preceding step, run the following command:

    UNIX: $ rm INSTANCE_DIR/OUD/bak/backup-userRoot-20110929184101Z

WINDOWS C:\> del INSTANCE_DIR\OUD\bak\backup-userRoot-20110929184101Z

  3. Remove the associated backup information from the backup.info file.

    You can display the contents of the backup.info, as follows (on UNIX systems):

    $ more INSTANCE_DIR/OUD/bak/backup.info
backend_dn=ds-cfg-backend-id=userRoot,cn=Backends,cn=config

     backup_id=20110929184101Z
     backup_date=20110929184104Z
     incremental=false
     compressed=false
     encrypted=false
     property.last_logfile_name=00000000.jdb
     property.last_logfile_size=160773
     property.archive_file=backup-userRoot-20110929184101Z
     
     backup_id=20111029184509Z
     backup_date=20111029184512Z
     incremental=false
     compressed=false
     encrypted=false
     property.last_logfile_name=00000000.jdb
     property.last_logfile_size=160773
     property.archive_file=backup-userRoot-20111029184509Z

    For Windows systems, use an appropriate text editor.

17.4 Searching Directory Data

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.

This section contains the following topics:

17.4.1 Overview of the ldapsearch Command

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.

17.4.2 ldapsearch Location and Format

The ldapsearch utility is found in the following location:

(UNIX, Linux) INSTANCE_DIR/OUD/bin
(Windows) INSTANCE_DIR\OUD\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.

17.4.2.1 Common ldapsearch Options

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:

-h, --hostname address

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.

-p, --port port

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.

-b, --baseDN baseDN

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.

-s, --searchScope scope

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.

-D, --bindDN bindDN

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.

-w, --bindPassword bindPassword

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 -.

-l, --timeLimit numSeconds

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.

-z, --sizeLimit numEntries

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.

-S, --sortOrder sortOrder

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.

17.4.3 Understanding Search Criteria

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.

This section describes the different filter options, and contains the following topics:

17.4.3.1 Specifying Filter Types and Operators

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.

Search Filter Operator Description

Presence

attr=*

Return all entries that have any value associated with the specified attribute. The filter uses the wildcard character to denote zero or more characters in the string. For example, the following filter is common and returns all entries that have an object class with any value, which every entry has: (objectclass=\*).

Note: the LDAP protocol specifies that filters should have the form "(filter)", which includes parentheses surrounded by quotation marks. Although most directory servers accept filters without the parentheses and quotation marks, it is good practice to include them.

Equality

attr=value

Return entries containing attributes equal to a specified value. For example: (sn=Bergin) returns all entries that have a surname (sn) attribute with the value of Bergin.

Note: The sn value is case insensitive, so entries associated with sn=bergin or sn=Bergin will be returned.

Substring

attr=<initial-string><any substring><final-string>

Return entries with attributes containing a specified substring or partial substring. The filter uses the wildcard character to denote zero or more characters in the string.

  • Run an initial substring search that looks for all attribute values that have the characters Ber at the start of the string: (sn=Ber\*)

  • Specify the middle substring of an attribute value. For example: (sn=\*erg\*)

  • Specify the end of a substring of an attribute value. For example: (sn=\*gin). Or you can specify some combination of substrings

  • Specify the initial and middle substring: (sn=ber\*gi\*)

  • Specify the initial and ending substrings: (sn=be\*in)

  • Specify the middle and end substrings: (sn=\*er\*in)

    Note: Substring filters do not use true wild cards such as in system listings or regular expressions. Thus, the following filter would be invalid because of too many criteria: (sn=\*B\*rg\*n).

Greater than or equal to

attr>=value

Return entries containing attributes that are greater than or equal to the specified value. For example, (sn>=Bergin) returns all entries that have an attribute greater than or equal to the value, Bergin, based on the matching rules for attributes (see Understanding Matching Rules).

Less than or equal to

attr<=value

Return entries containing attributes that are less than or equal to the specified value. For example, (sn&lt;=Bergin) returns all entries that have an attribute less than or equal to the value, Bergin, based on the matching rules for attributes.

Approximate

attr~=value

Return entries containing the specified attribute with a value that is approximately equal to the value specified in the search filter. For example: (sn~=Bergan) could return the entry associated with (sn=Bergin) or (sn=Bergan). The Approximate search filter works only with English language strings. It does not work with non-ASCII-based strings, such as Ja or Zn.

Extensible match

attr= attr [":dn"] [":" matchingrule] ":=" value Or:[:dn] ":" matchingrule ":=" value

Return the results entries when an attribute equals the value with the specified matching rule. LDAP version 3 enables you to build match operators and rules for a particular attribute. Matching rules define how to compare attribute values with a particular syntax. In other words, an extensible search filter enables you to add a matching rule to a search filter. For example, the following search filter compares entries containing the surname attribute with value equal to "Jensen" by using the matching rule designated by OID 2.5.13.5: (sn:2.5.13.5:=Jensen). Another example illustrates the use of the ":dn" notation to indicate that the OID 2.5.13.5 should be used when making comparisons, and that the attributes of an entry should be considered part of the entry when evaluating the match:(sn:dn:2.5.13.5:=Jensen)

17.4.3.2 Using Compound Search Filters

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.

Search Filter Operator Description

AND

(&(filter)(filter))

All specified filters must be true for the statement to be true. For example, (&(sn=Carter)(l=Cupertino)) returns all entries that have the surname attribute equal to "Carter" and the location attribute equal to Cupertino if any.

OR

(|(filter)(filter))

At least one specified filter must be true for the statement to be true. For example, (|(sn=Carter)(l=Cupertino)) returns all entries that have the surname attribute equal to Carter or the location attribute equal to Cupertino if any.

NOT

(!(filter)(filter))

The specified filter must not be true for the statement to be true. For example, (!(sn=Bergin)) returns all entries that do not have a surname attribute equal to the string Smith. The filter also returns all entries that do not have the sn attribute.

17.4.3.3 Using UTF-8 Encoding in Search Filters

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)

17.4.3.4 Using Special Characters in Search Filters

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").

17.4.4 ldapsearch Examples

The following examples show the use of the ldapsearch command with various search options. These examples all assume that your current working directory is INSTANCE_DIR/OUD/bin (INSTANCE_DIR\OUD\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 INSTANCE_DIR/OUD/bin at the beginning of your $PATH.

This section contains the following topics:

17.4.4.1 To Return All Entries

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.

Run the ldapsearch command with the filter (objectclass=*).

$ 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
...

17.4.4.2 To Search For a Specific User

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".

Run the ldapsearch command with the filter "(cn=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

17.4.4.3 To Search for Specific User Attributes

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.

Run the ldapsearch command with the filter "(cn=Frank Albers)" and the corresponding attributes.

$ 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

17.4.4.4 To Perform a Search With Base Scope

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.

Run the ldapsearch command with the --searchScope base option.

$ ldapsearch --hostname localhost --port 1389 --baseDN "dc=example,dc=com" \
  --searchScope base "(objectclass=*)"
dn: dc=example,dc=com
objectClass: domain
objectClass: top
dc: example

17.4.4.5 To Perform a Search With One-Level Scope

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.

Run the ldapsearch command with the --searchScope one option.

$ 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

17.4.4.6 To Perform a Search With Subtree Scope

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.

Run the ldapsearch command with the --searchScope sub option.

$ 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

17.4.4.7 To Return Attribute Names Only

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.

Run the ldapsearch command with the --typesOnly option.

$ 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 ...

17.4.4.8 To Return User Attributes Only

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.

Run the ldapsearch command, specifying '*' after the search filter.

$ 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

17.4.4.9 To Return Base DNs Only

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.

Run the ldapsearch command, specifying 1.1 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
...

17.4.4.10 To Search For Specific Object Classes

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.

Run the ldapsearch command, specifying @ and the object class 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 ...

17.4.4.11 To Return a Count of All Entries in the Directory

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.

Run the ldapsearch command with the --countEntries option.

$ 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

17.4.4.12 To Perform a Search With a Compound Filter

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.

Run the ldapsearch command with a compound search filter.

$ 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

17.4.4.13 To Perform a Search Using a Filter File

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.

  1. Create the filter file.

    For this example, create a file called myfilter.txt with the following content:(&(sn=jensen)(l=Cupertino)(!(ou=Accounting)))

  2. Run the ldapsearch command, specifying the file name as a filter.

    $ 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

17.4.4.14 To Limit the Number of Entries Returned in a Search

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.

Run the ldapsearch command with the --sizeLimit option.

$ 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

17.4.5 Searching Data With Oracle Directory Services Manager

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.

17.4.5.1 Perform a Complex LDAP Search

To perform a complex LDAP search by using the ODSM advanced search facility, complete the following steps:

  1. Connect to the directory server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."

  2. Select the Advanced Search tab.

  3. Select the appropriate network group from the Network Group list.

  4. 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.

  5. 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.

  6. 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 Section 17.4.3.1, "Specifying Filter Types and Operators."

  7. From the Search Results Size list, select how you want ODSM to limit the number of entries that are returned by the search.

17.5 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 Section 17.4, "Searching Directory Data," Appendix A, "Using a Properties File With Server Commands," and Appendix A, "ldapsearch."

This section contains the following topics:

17.5.1 Searching for Special Entries and Attributes

This section describes how to search for operational attributes and how to search the Root DSE entry, and contains the following topics:

17.5.1.1 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" \
  -j pwd-file -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
...

17.5.1.2 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" \
  -j pwd-file -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 
...

17.5.1.3 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" \
  -j pwd-file -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";)

17.5.1.4 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" \
  -j pwd-file -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' )
...

17.5.1.5 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. The dsconfig command connects to the directory server over SSL via the administration connector. For more information, see Section 14.3, "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" -j pwd-file

For more information about accessing the server configuration by using dsconfig, see Section 14.1, "Managing the Server Configuration With dsconfig."

17.5.1.6 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 Section 14.3, "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" \
  -j pwd-file -b cn=monitor "(objectclass=*)"
dn: cn=monitor
startTime: 20120119135658Z
objectClass: extensibleObject
objectClass: top
objectClass: ds-monitor-entry
cn: monitor
vendorName: Oracle Corporation
currentTime: 20120125145650Z
vendorVersion: Oracle Unified Directory 11.1.2.0.0
maxConnections: 3
productName: Oracle Unified Directory
currentConnections: 1
totalConnections: 22
upTime: 6 days 0 hours 59 minutes 52 seconds
...

17.5.2 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.

This section contains the following topics:

17.5.2.1 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=*)"

17.5.2.2 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=*)"

17.5.2.3 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

17.5.2.4 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=*)"

17.5.2.5 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=*)"

17.5.2.6 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=*)"

17.5.2.7 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=*)"

17.5.2.8 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=*)"

17.5.3 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.

This section contains the following topics:

17.5.3.1 Viewing 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.1413
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.26027.1.5.5
supportedControl: 1.3.6.1.4.1.26027.1.5.6
supportedControl: 1.3.6.1.4.1.26027.2.3.1
supportedControl: 1.3.6.1.4.1.26027.2.3.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.1
supportedControl: 1.3.6.1.4.1.4203.1.10.2
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.4
supportedControl: 2.16.840.1.113730.3.4.5
supportedControl: 2.16.840.1.113730.3.4.9
supportedControl: 2.16.840.1.113894.1.8.21
supportedControl: 2.16.840.1.113894.1.8.31

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.1413

LDAP Ease Modify Restrictions 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.26027.1.5.5

Network Group Selection Control

1.3.6.1.4.1.26027.1.5.6

Network Group Query Control

1.3.6.1.4.1.26027.2.3.1

Join Search Control

1.3.6.1.4.1.26027.2.3.2

Proximity Search 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.4

Netscape Password Expired LDAPv3 Control

2.16.840.1.113730.3.4.5

Netscape Password Expiring LDAPv3 Control

2.16.840.1.113730.3.4.9

Virtual List View Control

2.16.840.1.113894.1.8.21

Search Count Request Control

2.16.840.1.113894.1.8.31

ECID Execution Info control

17.5.3.2 Searching Using the Join Search Control

The Join Search Control retrieves related entry tree chains such as friends, managers, and so forth, in a single search operation. The Join Control can only target entry chains with established relationships that can (but do not have to) be cross referenced.

For example, the following entry is part of an established "friends" relationship hierarchy where each participating entry has links to other participating entries. In this case these links are formed by the friend attribute.

dn: uid=user.3,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalperson
objectClass: inetorgperson
objectClass: top
uid: user.3
cn: Kenny McCormick
sn: McCormick
friend: uid=user.0,ou=People,dc=example,dc=com
friend: uid=user.1,ou=People,dc=example,dc=com
friend: uid=user.2,ou=People,dc=example,dc=com
...

In a search operation with the Join Control, the search parameters such as scope and filter apply to the join search, that is, to entries evaluated during the join. This means that only matching results are returned. This functionality enables you to retrieve the entire linked relationship hierarchy, or a subset of it, in a single search operation, based on specific search criteria and scope.

You can specify the Proximity Search Control with the ldapsearch command by using the --control or -J option with the Proximity Search Control OID (1.3.6.1.4.1.26027.2.3.1) as follows:

OID:criticality:attribute

where attribute is the attribute on which the relationship between entries is based.

The following example requests the subset of user entries that are linked through the friend attribute.

$ ldapsearch -h localhost -p 1389 -D "cn=directory manager" -j pwd-file \
  --baseDN "uid=user.3,ou=People,dc=example,dc=com" \
  --searchScope sub \
  -J "1.3.6.1.4.1.26027.2.3.1:true:friend" \
  "(objectClass=person)"

In a join search, the search parameters have the following significance:

  • baseDN

    The search base is used to specify the precise entry from which to start the join search.

  • searchScope

    The search scope is used to specify distinct levels of join depth.

    • A search scope of base retrieves only direct relationships, for example, direct friends that are specified by the friend attribute in the sample entry.

    • A search scope of one goes one level deep, retrieving direct friends of direct friends of the sample entry.

    • A search scope of sub traverses the entire hierarchy chain no matter how many levels.

    • A search scope of subordinate has the same effect as sub, but does not include the base entry in search results.

  • filter

    The search filter is used to evaluate candidate entries during the join for inclusion in the search results. The filter can be used to refine the search to include only specific entries. It works in exactly the same way as the filter for standard search operations but is applicable only to join search results.

17.5.3.3 Searching Using the Proximity Search Control

The Proximity Search Control provides base location data to the server in the search request. This enables the server to generate proximity virtual attribute values for all candidate entries that include location data. The value of the location attribute in an entry is the latitude-longitude GPS coordinates, in WGS84 standard format. User applications can periodically update the value of this attribute with the last known location of the user. For example, the following entry extract shows an entry whose location has been updated to the coordinates of Golden Gate Bridge:

dn: uid=user.1,ou=People,dc=example,dc=com
objectClass: geoObject
objectClass: person
objectClass: organizationalperson
objectClass: inetorgperson
objectClass: top
objectClass: geoObject
uid: user.1
cn: Bob Smith
sn: Smith
location: 37.81997, -122.47859
...

The server can calculate the location proximity of each entry to the base location provided in the Proximity Search Control.

A client application can therefore request a proximity value to be calculated and returned for each matching search result entry. The client application can use the proximity attribute in the search filter of the search operation itself and can therefore request matching search result entries based on their proximity to a given base location.

You can specify the Proximity Search Control with the ldapsearch command by using the --control or -J option with the Proximity Search Control OID (1.3.6.1.4.1.26027.2.3.2) as follows:

OID:criticality:location

where location represents the latitude-longitude GPS coordinates in WGS84 standard format.

The following example sets the base location to the coordinates of the Eiffel Tower (48.858844, 2.294351) and requests all user entries whose location is within 500 meters of the base location.

$ ldapsearch -h localhost -p 1389 -D "cn=directory manager" -j pwd-file \
  -b "dc=example,dc=com" --searchScope sub \
  -J "1.3.6.1.4.1.26027.2.3.2:true:48.858844,2.294351" \
  "(&(objectClass=person)(proximity<=500))"

17.5.3.4 Searching 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
...

17.5.3.5 Searching 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" \
  -j pwd-file -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

17.5.3.6 Searching 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.

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

    $ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -j pwd-file \
  -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

...

  2. 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" -j pwd-file \
  -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

  3. 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" -j pwd-file \
  -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 )

17.5.3.7 Searching 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" -j pwd-file \
  -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

17.5.3.8 Searching 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, as follows:

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

17.5.3.9 Searching 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.

To use the Manage DSA IT control in a search, run the ldapsearch command with the -J option, as follows:

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -j pwd-file \
  -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.

17.5.3.10 Searching 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" -j pwd-file \
  -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

17.5.3.11 Searching 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" -j pwd-file \
  -b dc=example,dc=com -s base --usePasswordPolicyControl "(objectclass=*)"

17.5.3.12 Searching 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.

  1. Run the ldapsearch command as follows:

    $ ldapsearch -h localhost -p 1389 -D "cn=admin,cn=Administrators,cn=config" \
  -j pwd-file -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.

  2. 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

  3. 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

  4. To terminate the session, press Control-D (Unix/Linux) or Control-C (Windows), and then type Y to quit.

    Terminate batch job (Y/N)?

17.5.3.13 Searching 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 with the --proxyAs option, as follows:

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" -j pwd-file \
  -s sub -b dc=example,dc=com \
  --proxyAs "dn:uid=acctgAdmin,ou=Administrators,ou=People,dc=example,dc=com" \
  "(uid=kvaughan)" mail

17.5.3.14 Searching 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.

  1. 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" -j pwd-file \
  --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>...

  2. 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" -j pwd-file \
  -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>...

17.5.3.15 Searching 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

17.5.3.16 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.

17.5.3.16.1 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
17.5.3.16.2 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" -j pwd-file \
  -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
17.5.3.16.3 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" -j pwd-file \
  -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
17.5.3.16.4 Allowing Anonymous Access to the Virtual List View Control

By default, access to the virtual list view control is allowed for authenticated users only. To allow unauthenticated users to access the virtual list view control, the OID for the virtual list view control (2.16.840.1.113730.3.4.9) must be added to the "Anonymous control access" global ACI and removed from the "Authenticated users control access" global ACI.

ds-cfg-global-aci: (targetcontrol="2.16.840.1.113730.3.4.2 || 
2.16.840.1.113730.3.4.17 || 2.16.840.1.113730.3.4.19 || 
1.3.6.1.4.1.4203.1.10.2 || 1.3.6.1.4.1.42.2.27.8.5.1 || 
2.16.840.1.113730.3.4.16 || 2.16.840.1.113894.1.8.31") (version 3.0; acl 
"Anonymous control access"; allow(read) userdn="ldap:///anyone";) 
ds-cfg-global-aci: (targetcontrol="1.3.6.1.1.12 || 1.3.6.1.1.13.1 || 
1.3.6.1.1.13.2 || 1.2.840.113556.1.4.319 || 1.2.826.0.1.3344810.2.3 || 
2.16.840.1.113730.3.4.18 || 2.16.840.1.113730.3.4.9 || 1.2.840.113556.1.4.473 
|| 1.3.6.1.4.1.42.2.27.9.5.9 || 1.2.840.113556.1.4.473") (version 3.0; acl 
"Authenticated users control access"; allow(read) userdn="ldap:///all";)

The easiest way to modify these global ACIs is to use ODSM, as follows:

  1. Connect to the directory server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."

  2. Select the Security tab.

  3. Under the Root menu, select Anonymous control access.

  4. In the Targets table on the right hand pane, select the Target Control field, and click Edit.

  5. From the Available Controls list, select Virtual List View Control (2.16.840.1.113730.3.4.9).

  6. Click the right arrow to move the VLV control to the Selected Controls list.

  7. Click OK.

  8. Click Apply to save your changes.

  9. Under the Root menu, select Authenticated users control access.

  10. In the Targets table on the right hand pane, select the Target Control field, and click Edit.

  11. From the Selected Controls list, select Virtual List View Control (2.16.840.1.113730.3.4.9).

  12. Click the left arrow to move the VLV control to the Available Controls list.

  13. Click OK.

  14. Click Apply to save your changes.

You can also use dsconfig to modify the global ACIs, but it is not possible to modify an ACI value with dsconfig. Instead, the ACIs must be deleted and recreated. For more information, see Section 22.1.1, "Default Global ACIs".

17.5.4 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, and contains the following topics:

17.5.4.1 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" -j pwd-file \
   -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
...

17.5.4.2 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 Appendix A, "Using a Properties File With Server Commands."

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

    hostname=localhost 
port=1389 
bindDN=cn=Directory Manager 
bindPasswordFile=pwd-file 
baseDN=dc=example,dc=com 
searchScope=sub 
sortOrder=givenName 
virtualListView=0:2:1:0

  2. Save the file as tools.properties.

  3. Use the ldapsearch with the --propertiesFilePath option.

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

17.5.5 Searching Internationalized Entries

Oracle Unified Directory supports collation rules that match entries and can be used with the Section 17.5.3.14, "Searching Using the Server-Side Sort 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

  • matchingRule can specified as either a numeric suffix or a character suffix appended to the locale, as listed in Table 17-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 17-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"

This section contains the following topics:

17.5.5.1 Examples

Example 17-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" -j pwd-file -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 17-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 departmentnumber value of abc119:

$ ldapsearch -D "cn=directory manager" -j pwd-file -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 17-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 departmentnumber value of abc119:

$ ldapsearch -D "cn=directory manager" -j pwd-file -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 17-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" -j pwd-file -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 17-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" -j pwd-file -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 17-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" -j pwd-file -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"

17.5.5.2 Supported Collation Rules

The following table lists the internationalization locales supported by Oracle Unified Directory, alphabetized by character suffix.

Table 17-2 Supported Collation Rules

Locale Character Suffix OID

Arabic

ar

1.3.6.1.4.1.42.2.27.9.4.3.1

Arabic United Arab Emirates

ar-AE

1.3.6.1.4.1.42.2.27.9.4.4.1

Arabic Bahrain

ar-BH

1.3.6.1.4.1.42.2.27.9.4.5.1

Arabic Algeria

ar-DZ

1.3.6.1.4.1.42.2.27.9.4.6.1

Arabic Egypt

ar-EG

1.3.6.1.4.1.42.2.27.9.4.7.1

Arabic India

ar-IQ

1.3.6.1.4.1.42.2.27.9.4.9.1

Arabic Jordan

ar-JO

1.3.6.1.4.1.42.2.27.9.4.10.1

Arabic Kuwait

ar-KW

1.3.6.1.4.1.42.2.27.9.4.11.1

Arabic Lebanon

ar-LB

1.3.6.1.4.1.42.2.27.9.4.12.1

Arabic Lybia

ar-LY

1.3.6.1.4.1.42.2.27.9.4.13.1

Arabic Morocco

ar-MA

1.3.6.1.4.1.42.2.27.9.4.14.1

Arabic Oman

ar-OM

1.3.6.1.4.1.42.2.27.9.4.15.1

Arabic Qatar

ar-QA

1.3.6.1.4.1.42.2.27.9.4.16.1

Arabic Saudi Arabia

ar-SA

1.3.6.1.4.1.42.2.27.9.4.17.1

Arabic Sudan

ar-SD

1.3.6.1.4.1.42.2.27.9.4.18.1

Arabic Syria

ar-SY

1.3.6.1.4.1.42.2.27.9.4.19.1

Arabic Tunisia

ar-TN

1.3.6.1.4.1.42.2.27.9.4.20.1

Arabic Yemen

ar-YE

1.3.6.1.4.1.42.2.27.9.4.21.1

Byelorussian

be

1.3.6.1.4.1.42.2.27.9.4.22.1

Bulgaria

bg

1.3.6.1.4.1.42.2.27.9.4.23.1

Catalan

ca

1.3.6.1.4.1.42.2.27.9.4.25.1

Czech

cs

1.3.6.1.4.1.42.2.27.9.4.26.1

Danish

da

1.3.6.1.4.1.42.2.27.9.4.27.1

German

de

1.3.6.1.4.1.142.2.27.9.4.28.1

German Germany

de-DE

1.3.6.1.4.1.142.2.27.9.4.28.1

German Austria

de-AT

1.3.6.1.4.1.42.2.27.9.4.29.1

German Swiss

de-CH

1.3.6.1.4.1.42.2.27.9.4.31.1

German Luxembourg

de-LU

1.3.6.1.4.1.42.2.27.9.4.32.1

Greek

el

1.3.6.1.4.1.42.2.27.9.4.33.1

English

en

1.3.6.1.4.1.42.2.27.9.4.34.1

English US

en-US

1.3.6.1.4.1.42.2.27.9.4.34.1

English Australia

en-AU

1.3.6.1.4.1.42.2.27.9.4.35.1

English Canada

en-CA

1.3.6.1.4.1.42.2.27.9.4.36.1

English Great Britain

en-GB

1.3.6.1.4.1.42.2.27.9.4.37.1

English Ireland

en-IE

1.3.6.1.4.1.42.2.27.9.4.39.1

English India

en-IN

1.3.6.1.4.1.42.2.27.9.4.40.1

English New Zealand

en-NZ

1.3.6.1.4.1.42.2.27.9.4.42.1

English South Africa

en-ZA

1.3.6.1.4.1.42.2.27.9.4.46.1

Spanish

es

1.3.6.1.4.1.42.2.27.9.4.49.1

Spanish Spain

es-ES

1.3.6.1.4.1.42.2.27.9.4.49.1

Spanish Argentina

es-AR

1.3.6.1.4.1.42.2.27.9.4.50.1

Spanish Bolivia

es-BO

1.3.6.1.4.1.42.2.27.9.4.51.1

Spanish Chile

es-CL

1.3.6.1.4.1.42.2.27.9.4.52.1

Spanish Colombia

es-CO

1.3.6.1.4.1.42.2.27.9.4.53.1

Spanish Costa Rica

es-CR

1.3.6.1.4.1.42.2.27.9.4.54.1

Spanish Dominican Republic

es-DO

1.3.6.1.4.1.42.2.27.9.4.55.1

Spanish Ecuador

es-EC

1.3.6.1.4.1.42.2.27.9.4.56.1

Spanish Guatemala

es-GT

1.3.6.1.4.1.42.2.27.9.4.57.1

Spanish Honduras

es-HN

1.3.6.1.4.1.42.2.27.9.4.58.1

Spanish Mexico

es-MX

1.3.6.1.4.1.42.2.27.9.4.59.1

Spanish Nicaragua

es-NI

1.3.6.1.4.1.42.2.27.9.4.60.1

Spanish Panama

es-PA

1.3.6.1.4.1.42.2.27.9.4.61.1

Spanish Peru

es-PE

1.3.6.1.4.1.42.2.27.9.4.62.1

Spanish Puerto Rico

es-PR

1.3.6.1.4.1.42.2.27.9.4.63.1

Spanish Paraguay

es-PY

1.3.6.1.4.1.42.2.27.9.4.64.1

Spanish Salvador

es-SV

1.3.6.1.4.1.42.2.27.9.4.65.1

Spanish Uraguay

es-UY

1.3.6.1.4.1.42.2.27.9.4.67.1

Spanish Venezuela

es-VE

1.3.6.1.4.1.42.2.27.9.4.68.1

Estonian

et

1.3.6.1.4.1.42.2.27.9.4.69.1

Finnish

fi

1.3.6.1.4.1.42.2.27.9.4.74.1

French

fr

1.3.6.1.4.1.42.2.27.9.4.76.1

French

fr-FR

1.3.6.1.4.1.42.2.27.9.4.76.1

French

fr-BE

1.3.6.1.4.1.42.2.27.9.4.77.1

French

fr-CA

1.3.6.1.4.1.42.2.27.9.4.78.1

French

fr-CH

1.3.6.1.4.1.42.2.27.9.4.79.1

French

fr-LU

1.3.6.1.4.1.42.2.27.9.4.80.1

Hebrew

he

1.3.6.1.4.1.42.2.27.9.4.85.1

Croatian

hr

1.3.6.1.4.1.42.2.27.9.4.87.1

Hungarian

hu

1.3.6.1.4.1.42.2.27.9.4.88.1

Icelandic

is

1.3.6.1.4.1.42.2.27.9.4.91.1

Italian

it

1.3.6.1.4.1.42.2.27.9.4.92.1

Italian-Swiss

it-CH

1.3.6.1.4.1.42.2.27.9.4.93.1

Japanese

ja

1.3.6.1.4.1.42.2.27.9.4.94.1

Korean

ko

1.3.6.1.4.1.42.2.27.9.4.97.1

Lithuanian

lt

1.3.6.1.4.1.42.2.27.9.4.100.1

Latvian

lv

1.3.6.1.4.1.42.2.27.9.4.101.1

Macedonian

mk

1.3.6.1.4.1.42.2.27.9.4.102.1

Dutch

nl

1.3.6.1.4.1.42.2.27.9.4.105.1

Dutch Netherlands

nl-NL

1.3.6.1.4.1.42.2.27.9.4.105.1

Dutch Belgium

nl-BE

1.3.6.1.4.1.42.2.27.9.4.106.1

Norwegian

no

1.3.6.1.4.1.42.2.27.9.4.107.1

Norwegian Norway

no-NO

1.3.6.1.4.1.42.2.27.9.4.107.1

Norwegian Nynorsk

no-NO-NY

1.3.6.1.4.1.42.2.27.9.4.108.1

Polish

pl

1.3.6.1.4.1.42.2.27.9.4.114.1

Portuguese

pt

1.3.6.1.4.1.42.2.27.9.4.115.1

Portuguese Portugal

pt-PT

1.3.6.1.4.1.42.2.27.9.4.115.1

Portugues Brazil

pt-BR

1.3.6.1.4.1.42.2.27.9.4.116.1

Romanian

ro

1.3.6.1.4.1.42.2.27.9.4.117.1

Russian

ru

1.3.6.1.4.1.42.2.27.9.4.118.1

Russian Russia

ru-RU

1.3.6.1.4.1.42.2.27.9.4.118.1

Slovak

sk

1.3.6.1.4.1.42.2.27.9.4.121.1

Slovenia

sl

1.3.6.1.4.1.42.2.27.9.4.122.1

Albanian

sq

1.3.6.1.4.1.42.2.27.9.4.127.1

Serbian

sr

1.3.6.1.4.1.42.2.27.9.4.128.1

Swedish

sv

1.3.6.1.4.1.42.2.27.9.4.129.1

Swedish Sweden

sv-SE

1.3.6.1.4.1.42.2.27.9.4.129.1

Thai

th

1.3.6.1.4.1.42.2.27.9.4.136.1

Turkish

tr

1.3.6.1.4.1.42.2.27.9.4.140.1

Ukrainian

uk

1.3.6.1.4.1.42.2.27.9.4.141.1

Vietnamese

vi

1.3.6.1.4.1.42.2.27.9.4.142.1

Chinese

zh

1.3.6.1.4.1.42.2.27.9.4.143.1

Chinese China

zh-CN

1.3.6.1.4.1.42.2.27.9.4.144.1

Chinese Hong Kong

zh-HK

1.3.6.1.4.1.42.2.27.9.4.145.1

Chinese Taiwan

zh-TW

1.3.6.1.4.1.42.2.27.9.4.148.1

17.6 Adding, Modifying, and Deleting Directory Data

The directory server provides a full set of LDAPv2- and LDAPv3-compliant client tools to manage directory entries. You can add, update, or remove entries by using the ldapmodify and ldapdelete utilities. The LDAP command-line utilities require LDAP Data Interchange Format (LDIF)-formatted input, entered through the command line or read from a file.

Before you make modifications to directory data, make sure that you understand the following concepts:

  • The privilege and access control mechanisms.

    For information about setting privileges, Chapter 22, "Controlling Access To Data."

  • The structure of your directory server.

  • The schema of your directory server.

This section contains the following topics:

17.6.1 Adding Directory Entries

You can add one or more entries to a directory server by using the ldapmodify command. ldapmodify opens a connection to the directory server, binds to it, and performs the modification to the database (in this case, an "add") as specified by the command-line options.

ldapmodify enables you to add entries in one of two ways:

  • Using the --defaultAdd option. Use the --defaultAdd option to add new entries to the directory when data is entered on the command line. Press Ctrl-D (UNIX, Linux) or Ctrl-Z (Windows) when finished, or use an input file with your changes.

  • Using LDIF update statements. LDIF update statements define how ldapmodify changes the directory entry. LDIF update statements contain the DN of the entry to be modified, changetype that defines how a specific entry is to be modified (add, delete, modify, modrdn), and a series of attributes and their changed values.

Note:

Any newly added entry must conform to the directory's schema. If you add any entry that does not conform to the schema, the server responds with an Object Class Violation error. You can view the details of the error in the errors log.

This section contains the following topics:

17.6.1.1 To Create a Root Entry

The root entry is the topmost entry in the directory and must contain the naming context, or root suffix. You can set up the root entry when you first install the directory server using the graphical user interface (GUI) or the command-line. If you install the directory without any data, create a root entry using the ldapmodify command with the --defaultAdd option.

  1. Create the root entry using ldapmodify.

    $ ldapmodify --hostname localhost --port 1389 --defaultAdd \
  --bindDN "cn=Directory Manager" --bindPassword password
dn: dc=example,dc=com
objectclass: domain
objectclass: top
dc: example
(Press Ctrl-D on Unix, Linux)
(Press Ctrl-Z on Windows), then press ENTER.

Processing ADD request for dc=example,dc=com
ADD operation successful for DN dc=example,dc=com

    Note:

    The --bindDN and --bindPassword options specify the bind DN and password, respectively, of the user with permissions to add new entries. You can provide the clear-text version of the password. The server encrypts this value and store only the encrypted one. Be sure to limit read permissions to protect clear passwords that appear in LDIF files. To avoid this security issue, use SSL or startTLS.

  2. Verify the change by using the ldapsearch command.

    $ ldapsearch --hostname localhost --port 1389 --baseDN "dc=example,dc=com" \
  --searchScope base --bindDN "cn=Directory Manager" --bindPassword password \
  "(objectclass=*)"
dn: dc=example,dc=com
objectClass: domain
objectClass: top
dc: example

17.6.1.2 To Add an Entry Using the --defaultAdd Option With ldapmodify

  1. Create your directory entry in LDIF format.

    Before you add an entry, ensure that the suffix to which you want to add the entry exists in your database (for example, ou=People,dc=example,dc=com).

    For this example, create an input file called new.ldif with the following contents:

    dn: uid=Marcia Garza,ou=People,dc=example,dc=com
cn: Marcia Garza
sn: Garza
givenName: Marcia
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
ou: Accounting
ou: People
l: Santa Clara
uid: mgarza
mail: mgarza@example.com
roomnumber: 5484
userpassword: donuts

  2. Add the entry using ldapmodify with the --defaultAdd option.

    $ ldapmodify --hostname localhost --port 1389 --bindDN "cn=Directory Manager" \
  --bindPassword password --defaultAdd --filename /tmp/new.ldif

17.6.1.3 To Add Entries Using an LDIF Update Statement With ldapmodify

  1. Create the entry in LDIF format with the changetype:add element.

    Make sure that there are no trailing spaces after add. If a space exists after add, the server base-64 encodes the value to represent the space, which can cause problems.

    For this example, create an input LDIF file named new.ldif.

    dn: uid=Marcia Garza,ou=People,dc=example,dc=com
changetype: add
cn: Marcia Garza
sn: Garza
givenName: Marcia
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
ou: Accounting
ou: People
l: Santa Clara
uid: mgarza
mail: mgarza@example.com
roomnumber: 5484
userpassword: donuts

  2. Add the entry using ldapmodify.

    Do not include the -a option as the changetype attribute specifies the action.

    $ ldapmodify --hostname localhost --port 1389 --bindDN "cn=Directory Manager" \
  --bindPassword password --filename /tmp/new.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

17.6.2 Adding Attributes

The LDIF changetype:add statement adds an entry to the directory. To add attributes to an entry, use the changetype:modify statement, as shown in the following examples. You can combine multiple commands within a file by separating each command with a dash ("-").

This section describes how to manage an entry, and contains the following topics:

17.6.2.1 To Add an Attribute to an Entry

  1. Create the entry in LDIF format with the changetype:modify element.

    Use the modify change type, because you are modifying an existing entry with the addition of a new attribute. Make sure that there are no trailing spaces after modify. After the changetype, specify add: newAttributeName and, on the following line, the value of the new attribute.

    For this example, create an input LDIF file called add_attribute.ldif, as follows:

    dn: uid=Marcia Garza,ou=People,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: +1 408 555 8283

    Note:

    To add multiple attributes, separate the attributes with a dash (-), for example:

    dn: uid=Marcia Garza,ou=People,dc=example,dc=com
changetype: modify
add: telephonenumber
telephonenumber: +1 408 555 8283
-
add: building
building: sc09

  2. Add the attribute by using ldapmodify.

    $ ldapmodify --hostname localhost --port 1389 --bindDN "cn=Directory Manager" \
  --bindPassword password --filename /tmp/add_attribute.ldif

Processing MODIFY request for uid=Marcia Garza,ou=People,dc=example,dc=com
MODIFY operation successful for DN uid=Marcia Garza,ou=People,dc=example,dc=com

17.6.2.2 To Add an ACI Attribute

You can use ldapmodify to add access control instructions (ACIs) to manage access rights for a user's account. For more information, see Chapter 22, "Controlling Access To Data" and ACI Syntax.

The following example allows a user to modify her own directory attributes.

  1. Create the LDIF file containing the ACI.

    dn: uid=Marcia Garza,ou=People,dc=example,dc=com
changetype: modify
add: aci
aci: (target="ldap:///uid=Marcia Garza,ou=People,dc=example,dc=com")
 (targetattr="*")(version 3.0; acl "mgarza rights"; allow (write)
 userdn="ldap:///self";)

  2. Add the attribute by using ldapmodify.

    $ ldapmodify --hostname localhost --port 1389 --bindDN "cn=Directory Manager" \
  --bindPassword password --filename /tmp/add_aci.ldif

Processing MODIFY request for uid=Marcia Garza,ou=People,dc=example,dc=com
MODIFY operation successful for DN uid=Marcia Garza,ou=People,dc=example,dc=com

17.6.2.3 To Add an International Attribute

The directory server represents international locales using a language tag in the form attribute;language-subtype. For example, homePostalAddress;lang-jp:address specifies the postal address with the locale in Japan (subtype=jp).

Use ldapmodify to add the attribute.

Affix the language subtype, lang-cc, where cc is the country code.

$ ldapmodify --hostname localhost --port 1389 --bindDN "cn=Directory Manager" \ 
  --bindPassword password 
dn: uid=jarrow,ou=People,dc=example,dc=com
changetype: modify
add: homePostalAddress;lang-jp
homePostalAddress;lang-jp: 1-8-15 Azuchimachi, Chuo-ku
(Press Ctrl-D on Unix, Linux)
(Press Ctrl-Z on Windows), then press ENTER.

Note:

If the attribute value contains non-ASCII characters, they must be UTF-8 encoded.

17.6.3 Modifying Directory Entries

Use the LDIF update statement changetype:modify to make changes to existing directory data. The following procedures provide examples of modifying directory entries, and contains the sections:

For more information, see Appendix A, "ldapmodify."

17.6.3.1 To Modify an Attribute Value

Use ldapmodify to change the entry, using the changetype:modify and replace elements.

Ensure that there are no trailing spaces after modify.

This example modifies a user's existing telephone number.

$ ldapmodify -h localhost -p 1389 D "cn=Directory Manager" -j pwd-file \
dn: uid=Marcia Garza,ou=People,dc=example,dc=com
changetype: modify
replace: telephonenumber
telephonenumber: +1 408 555 8288

Processing MODIFY request for uid=Marcia Garza,ou=People,dc=example,dc=com 
MODIFY operation successful for DN uid=Marcia Garza,ou=People,dc=example,dc=com

To modify multiple attributes, separate the attributes with a dash (-), for example:

dn: uid=Marcia Garza,ou=People,dc=example,dc=com
changetype: modify
replace: telephonenumber
telephonenumber: +1 408 555 6465
-
add: facsimiletelephonenumber
facsimiletelephonenumber: +1 408 222 4444
-
replace: l
l: Sunnyvale

17.6.3.2 To Modify an Attribute With Before and After Snapshots

The ldapmodify command provides the options, --preReadAttribute and --postReadAttribute, that return the modified attribute value with a before and after snapshot, respectively.

Use ldapmodify with the --preReadAttribute and --postReadAttribute options.

This example modifies a user's existing telephone number.

$ ldapmodify -h localhost -p 1389 D "cn=Directory Manager" -j pwd-file \
  --preReadAttributes telephoneNumber --postReadAttributes telephoneNumber
dn: uid=Marcia Garza,ou=People,dc=example,dc=com
changetype: modify
replace: telephonenumber
telephonenumber: +1 408 555 8288

Processing MODIFY request for uid=Marcia Garza,ou=People,dc=example,dc=com
MODIFY operation successful for DN uid=Marcia Garza,ou=People,dc=example,dc=com

Target entry before the operation:
dn: uid=Marcia Garza,ou=People,dc=example,dc=com
telephonenumber: +1 408 555 4283

Target entry after the operation:
dn: uid=Marcia Garza,ou=People,dc=example,dc=com
telephonenumber: +1 408 555 8288

17.6.3.3 To Delete an Attribute

This example deletes the location (l) attribute from an entry.

Use the ldapmodify to delete the attribute.

$ ldapmodify -h localhost -p 1389 -D "cn=Directory Manager" -j pwd-file 
dn: uid=Marcia Garza,ou=People,dc=example,dc=com
changetype: modify
delete: l 
(Press CTRL-D for Unix, Linux) (Press CTRL-Z for Windows), then press ENTER.

Processing MODIFY request for uid=Marcia Garza,ou=People,dc=example,dc=com 
MODIFY operation successful for DN uid=Marcia Garza,ou=People,dc=example,dc=com

Type control-D (UNIX, Linux) or control-Z (Windows) to complete the input.

17.6.3.4 To Change an RDN

The distinguished name (DN) of an entry uniquely identifies and describes that entry. A distinguished name consists of the name of the entry itself as well as the names, in order from bottom to top, of the objects above it in the directory.

The relative distinguished name (RDN) is the leftmost element in an entry DN. For example, the RDN for uid=Marcia Garza,ou=People,dc=example,dc=com is uid=Marcia Garza. To change an RDN, use the changetype:moddn LDIF update statement.

You can specify if the old RDN should be retained in the directory by using the deleteoldrdn attribute. A deleteoldrdn value of 0 indicates that the existing RDN should be retained in the directory. A value of 1 indicates that the existing RDN should be replaced by the new RDN value.

  1. Use the ldapmodify command to rename the entry.

    In this example, an employee Marcia Garza wants to change to her married name, Marcia Peters.

    $ ldapmodify -h localhost -p 1389 -D "cn=Directory Manager" -j pwd-file
dn: uid=Marcia Garza,ou=Marketing,dc=example,dc=com 
changetype: moddn 
newrdn: uid=Marcia Peters 
deleteoldrdn: 1
Processing MODIFY DN request for uid=Marcia Garza,ou=People,dc=example,dc=com 
MODIFY DN operation successful for DN uid=Marcia Garza,ou=People,dc=example,dc=com

  2. Change any other attributes as necessary.

    In this example, certain attributes might still list the user's previous name.

    $ ldapmodify -h localhost -p 1389 -D "cn=Directory Manager" -j pwd-file 
dn: uid=Marcia Peters,ou=People,dc=example,dc=com 
changetype: modify
replace: sn
sn: Peters
-
replace: cn
cn: Marcia Peters
-
replace: uid
uid: mpeters
uid: Marcia Peters
-
replace: mail
mail: mpeters@example.com
(Press Ctrl-D on Unix, Linux)
(Press Ctrl-Z on Windows), then press ENTER.

Processing MODIFY request for uid=Marcia Peters,ou=People,dc=example,dc=com
MODIFY operation successful for DN uid=Marcia Peters,ou=People,dc=example,dc=com

17.6.3.5 To Move an Entry

If you are moving an entry from one parent to another, extend the access control instruction (ACI) rights on the parent entries. On the current parent entry of the entry to be moved, ensure that the ACI allows the export operations by using the syntax allow(export...). On the future parent entry of the entry to be moved, ensure that the ACI allows the import operations by using the syntax allow(import...).

In this example, move uid=sgarza from the ou=Contractors,dc=example,dc=com suffix to the ou=People,dc=example,dc=com subtree.

  1. Use ldapmodify with the moddn changetype to move the entry.

    $ ldapmodify -h localhost -p 1389 -D "cn=Directory Manager" -j pwd-file
dn: uid=sgarza,ou=Contractors,dc=example,dc=com 
changetype: moddn
newrdn: uid=sgarza 
deleteoldrdn: 0 
newsuperior: ou=People,dc=example,dc=com
--filename move_entry.ldif  
Processing MODIFY DN request for uid=sgarza,ou=Contractors,dc=example,dc=com 
MODIFY DN operation successful for DN uid=sgarza,ou=Contractors,dc=example,dc=com

  2. Change any other attribute values, as required.

    The following example provides before and after snapshot changes for the ou attribute.

    $ ldapmodify -h localhost -p 1389 -D "cn=Directory Manager" -j pwd-file \
  --preReadAttributes ou --postReadAttributes ou
dn: uid=sgarza,ou=People,dc=example,dc=com
changetype: modify
replace: ou
ou: People
ou: Product Testing
(Press Ctrl-D on Unix, Linux)
(Press Ctrl-Z on Windows), then press ENTER.

Processing MODIFY request for uid=sgarza,ou=People,dc=example,dc=com
MODIFY operation successful for DN uid=sgarza,ou=People,dc=example,dc=com

Target entry before the operation:
dn: uid=sgarza,ou=People,dc=example,dc=com
ou: Contractors
ou: Product Testing

Target entry after the operation:
dn: uid=sgarza,ou=People,dc=example,dc=com
ou: People
ou: Product Testing

17.6.4 Deleting Directory Entries

You can use ldapmodify and ldapdelete to remove entries from the directory. The ldapmodify command removes entries and attributes by using the LDIF update statements changetype:delete and changetype:modify with the delete attribute, respectively. The ldapdelete tool removes only entries.

Note:

You cannot delete an entry that has children entries. If you want to delete an entry that has children, first delete all the children entries below the targeted entry, then delete the entry.

For more information, see Appendix A, "ldapdelete."

This section describes how to delete directory entries, and contains the following topics:

17.6.4.1 To Delete an Entry With ldapmodify

Use the ldapmodify command with the changetype:delete statement.

$ ldapmodify -h localhost -p 1389 -D "cn=Directory Manager" -j pwd-file
dn: uid=Marcia Garza,ou=People,dc=example,dc=com
changetype: delete 
(Press CTRL-D for Unix) 
(Press CTRL-Z for Windows), then press ENTER.

Processing DELETE request for uid=Marcia Garza,ou=People,dc=example,dc=com
DELETE operation successful for DN uid=Marcia Garza,ou=People,dc=example,dc=com
The number of entries deleted was 1

17.6.4.2 To Delete an Entry With ldapdelete

Use the ldapdelete command and specify the entry that you want to delete.

$ ldapdelete -h localhost -p 1389 -D "cn=Directory Manager" -j pwd-file
"uid=mgarza,ou=People,dc=example,dc=com"

Processing DELETE request for uid=Marcia Garza,ou=People,dc=example,dc=com
DELETE operation successful for DN uid=Marcia Garza,ou=People,dc=example,dc=com

17.6.4.3 To Delete Multiple Entries by Using a DN File

  1. Create a file that contains a list of DNs to be deleted.

    In this example, the file is named delete.ldif. The file must list each DN on a separate line, for example:

    uid=mgarza,ou=People,dc=example,dc=com
uid=wsmith,ou=People,dc=example,dc=com
uid=jarrow,ou=People,dc=example,dc=com
uid=mbean,ou=People,dc=example,dc=com

  2. Delete the entries by passing the file as an argument to the ldapdelete command.

    $ ldapdelete -h localhost -p 1389 -D "cn=Directory Manager" -j pwd-file \
  --continueOnError --filename delete.ldif

Processing DELETE request for uid=mgarza,ou=People,dc=example,dc=com
DELETE operation successful for DN uid=mgarza,ou=People,dc=example,dc=com
Processing DELETE request for uid=wsmith,ou=People,dc=example,dc=com
DELETE operation successful for DN uid=wsmith,ou=People,dc=example,dc=com
Processing DELETE request for uid=jarrow,ou=People,dc=example,dc=com
DELETE operation successful for DN uid=jarrow,ou=People,dc=example,dc=com
Processing DELETE request for uid=mbean,ou=People,dc=example,dc=com
DELETE operation successful for DN uid=mbean,ou=People,dc=example,dc=com

    Note:

    The --continueOnError option specifies that if an error occurs, the command continues to the next search item.

17.7 Indexing Directory Data

This section describes how to index attributes using the dsconfig command-line tool. Indexes are configured per server and index configuration is not replicated.

You can use dsconfig to create local database indexes and Virtual List View (VLV) indexes. A local database index is used to find entries that match search criteria. A VLV index is used to process searches efficiently with VLV controls.

Unindexed searches are denied by default, unless the user has the unindexed-search privilege. For more information, see Section 23.3.5, "To Change a Root User's Privileges."

You can determine whether a search is indexed in two ways:

  • Try to perform the search anonymously. (The server rejects unindexed anonymous searches by default.)

  • Use the debugsearchindex operational attribute. This attribute provides the indexes used in the search, the number of candidate entries from each index, and the final indexed status. Include the debugsearchindex attribute in your ldapsearch command, as follows:

    $ ldapsearch -h localhost -p 1389 -b "dc=example,dc=com" "(objectClass=*)" debugsearchindex

This section describes how to index data, and contains the following topics:

17.7.1 Configuring Indexes on the Local DB Back End

The Local DB back end supports the following index types:

  • approximate — Improves the efficiency of searches using approximate search filters.

  • equality - Improves the efficiency of searches using equality search filters.

  • ordering - Improves the efficiency of searches using "greater than or equal to" or "less than or equal to" search filters. In the future, this index type might also be used for server-side sorting.

  • presence - Improves the efficiency of searches using presence search filters.

  • substring - Improves the efficiency of searches using substring search filters.

The directory server supports indexing for only a subset of extensible matching operations, including indexes based on collation matching rules and the relative time and partial date and time matching rules. For more information, see Section 17.5.5, "Searching Internationalized Entries," and Section 9.1.3, "Relative Time Matching Rules" and Section 9.1.4, "Partial Date Or Time Matching Rules."

When you create a new local DB back end with dsconfig, the following default indexes are created automatically:

  • aci (presence index)

  • ds-sync-hist (ordering index)

  • entryuuid (equality index)

  • objectclass (equality index)

This section contains the following topics:

17.7.1.1 To Create a New Local DB Index

This procedure demonstrates the steps for creating a new local DB index.

Note:

After you have created a new index, you must rebuild the indexes using the rebuild-index utility. The directory server cannot use the new index until the indexes have been rebuilt. For more information, see Appendix A, "rebuild-index."

  1. Create the new index.

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  create-local-db-index \
  --element-name backend --index-name attribute \
  --set index-type:index-type

  2. Check that the index was created by listing the local DB indexes for that back end.

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  list-local-db-indexes \
  --element-name backend

  3. Configure any specific index properties.

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \ 
  set-local-db-index-prop \
  --element-name backend --index-name attribute \
  --set property:value

  4. List the index properties to verify your change.

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  get-local-db-index-prop \
  --element-name backend --index-name attribute

  5. Rebuild the index.

    1. Either stop the server, rebuild the index, then restart the server.

      $ stop-ds
$ rebuild-index --baseDN baseDN --index attribute
$ start-ds

    2. Or, rebuild the index online by running the rebuild-index command as a task.

      $ rebuild-index -h localhost -p 4444 -D "cn=Directory manager" -j pwd-file \
 -X -n --baseDN dc=example,dc=com --index aci
Rebuild Index task 20110201162742312 scheduled to start immediately
...
Rebuild Index task 20110201162742312 has been successfully completed

      Note that, even for an online re-index operation, the backend is unavailable during the re-index. In a replicated topology, the overall service remains available through the referral on update feature. For more information, see Section 17.13.1, "Referrals in a Replicated Topology".

Example 17-7 Creating a New Equality Index

This example creates a new equality index for the employeeNumber attribute, verifies the index properties, and sets the index entry limit to 5000.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  create-local-db-index \
  --element-name userRoot --index-name employeeNumber \
  --set index-type:equality

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  list-local-db-indexes \
  --element-name userRoot
Local DB Index : Type    : index-type
---------------:---------:-----------
...
employeeNumber : generic : equality
...
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  get-local-db-index-prop \
  --element-name userRoot --index-name employeeNumber
Property                       : Value(s)
-------------------------------:---------------
attribute                      : employeenumber
index-entry-limit              : 4000
index-extensible-matching-rule : -
index-type                     : equality
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-local-db-index-prop \
  --element-name userRoot --index-name employeeNumber --set index-entry-limit:5000
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  get-local-db-index-prop \
  --element-name userRoot --index-name employeeNumber
Property                       : Value(s)
-------------------------------:---------------
attribute                      : employeenumber
index-entry-limit              : 5000
index-extensible-matching-rule : -
index-type                     : equality
$ rebuild-index -h localhost -p 4444 -D "cn=Directory manager" -j pwd-file -X \
  --baseDN dc=example,dc=com --index employeeNumber

Example 17-8 Adding a Substring Index

This example adds a substring index to the index created in the previous example.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-local-db-index-prop \
  --'
p userRoot --index-name employeeNumber \
  --add index-type:substring
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  get-local-db-index-prop \
  --element-name userRoot --index-name employeeNumber
Property                       : Value(s)
-------------------------------:---------------
attribute                      : employeenumber
index-entry-limit              : 5000
index-extensible-matching-rule : -
index-type                     : equality, substring
$ rebuild-index -h localhost -p 4444 -D "cn=Directory manager" -j pwd-file -X \
  --baseDN dc=example,dc=com --index employeeNumbe

17.7.2 Configuring VLV Indexes

A VLV index applies to a particular search on a given base entry and its subtree. The sort order, scope of the index, base DN, and filter must be defined when you create the index.

After you have created a new VLV index, you must rebuild the indexes using the rebuild-index command, appending vlv. in front of the index name. The directory server cannot use the new index until the indexes have been rebuilt. For more information, see Appendix A, "rebuild-index."

Note that access to the VLV request control is allowed to authenticated users only, by default. If you want to allow unauthenticated users to use the VLV control in search requests, you must change the corresponding global ACIs. For more information, see Section 17.5.3.16.4, "Allowing Anonymous Access to the Virtual List View Control".

17.7.2.1 To Create a New VLV Index

  1. Use dsconfig to create a new VLV index as follows:

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  create-local-db-vlv-index \
  --element-name backend --index-name name --set sort-order:attributes \
  --set scope:scope --set base-dn:baseDN --set filter:filter

    where:

    • index-name specifies a unique index name, which cannot be altered after the VLV index is created.

    • sort-order specifies the names of the attributes by which the entries are sorted and their order of precedence, from highest to lowest.

    • scope specifies the LDAP scope of the query being indexed and can be one of base-object, single-level, subordinate-subtree, or whole-subtree.

    • base-dn specifies the base DN used in the search query being indexed.

    • filter specifies the LDAP filter used in the query being indexed and can be any valid LDAP filter.

  2. Check that the index was created by listing the existing VLV indexes.

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  list-local-db-vlv-indexes \
  --element-name backend

  3. Display the index properties to verify your change.

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  get-local-db-vlv-index-prop \
  --element-name backend --index-name name

  4. Rebuild the index.

    1. Either stop the server, rebuild the index, then restart the server.

      $ stop-ds
$ rebuild-index --baseDN baseDN --index vlv.name
$ start-ds

    2. Or, rebuild the index online by running the rebuild-index command as a task.

      $ rebuild-index -h localhost -p 4444 -D "cn=Directory manager" -j pwd-file -X \
  --baseDN baseDN --index vlv.name

Example 17-9 Creating a New VLV Index

The following example creates a new VLV index to sort entries first by surname and then by common name for queries sn=*. The example then rebuilds the index online.

$ dsconfig -D "cn=directory manager" -j pwd-file -n create-local-db-vlv-index \
  --element-name userRoot --index-name myVLVIndex --set sort-order:"sn cn" \
  --set scope:base-object --set base-dn:dc=example,dc=com --set filter:sn=*
$ rebuild-index -h localhost -p 4444 -D "cn=Directory manager" -j pwd-file -X \
  -b "dc=example,dc=com" --index vlv.myVLVIndex

17.8 Reducing Stored Data Size

The directory server provides two mechanisms for reducing the size of stored data:

  • Compact encoding. When compact encoding is enabled, the back end uses a compact form when encoding entries by compressing the attribute descriptions and object class sets. This property applies only to the entries themselves and does not impact the index data. Compact encoding is enabled by default but can be disabled if required. If your deployment requires user-supplied capitalization in object class and attribute type names, you might want to disable compact encoding because user-supplied capitalization is not preserved in compacted entries. The compaction does, however, provide a performance gain and is therefore beneficial in deployments where user-supplied capitalization can be sacrificed for performance, or is not required.

  • Entry compression. Entry compression uses a deflator to compress the data before it is stored. When entry compression is enabled, the back end attempts to compress entries before storing them in the database. This property also applies only to the entries themselves and does not impact the index data. The effectiveness of entry compression is based on the type of data contained in the entry.

You can enable one or both of these mechanisms to reduce the size of the stored data. Because enabling these mechanisms affects future writes only, the database might contain a mixture of compressed and uncompressed records. Either type of record can be read regardless of the compression settings.

This section describes the following topics:

17.8.1 To Enable or Disable Compact Encoding

Compact encoding is configured by setting the compact-encoding property of a local backend workflow element. Changes to this setting will only take effect for writes that occur after the change is made. Existing data is not changed retroactively.

Disable compact encoding on the "userRoot" workflow element.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-workflow-element-prop --element-name="userRoot" --set compact-encoding:false

17.8.2 To Enable or Disable Entry Compression

Entry compression is configured by setting the entries-compressed property of a local backend workflow element. Changes to this setting will only take effect for writes that occur after the change is made. Existing data is not changed retroactively.

Enable entry compression on the "userRoot" back end.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-workflow-element-prop --element-name="userRoot" \
  --set entries-compressed:true

17.9 Ensuring Attribute Value Uniqueness

A directory's structure requires that distinguished names be unique to identify the object and its place in the directory information tree. The directory server provides a Unique Attribute plug-in, which ensures that the value of an attribute is unique when the attribute is added, modified, or moved within the directory.

This section describes the following topics:

17.9.1 Overview of the Unique Attribute Plug-In

The unique attribute plug-in is disabled by default. You can enable the plug-in by using the dsconfig command and can define the suffix and attributes that it should check. When it is enabled, the plug-in identifies whether an LDAP add, modify, or modify DN operation causes two entries to have the same attribute value before the database is updated by the operation. If the server recognizes a conflict, the operation is terminated and an LDAP_CONSTRAINT_VIOLATION error is returned to the client.

When you enable attribute uniqueness on an existing directory, the server does not check for uniqueness among existing entries. After the plug-in is enabled, uniqueness is enforced when an entry is added, modified, or moved.

The unique attribute plug-in can be configured to enforce uniqueness in one or more subtrees in the directory or among entries of a specific object class. You can define several instances of the unique attribute plug-in if you want to enforce the uniqueness of other attributes. Typically, you define one plug-in instance for each attribute whose value must be unique. You can also have several plug-in instances for the same attribute to enforce "separate" uniqueness in several sets of entries.

The unique attribute plug-in is disabled by default, so that multi-master replication configuration is not affected. When the plug-in is enabled, it checks that the uid attribute is unique prior to any add, modify, or modify DN operations for stand-alone systems and checks for uniqueness after synchronization in replicated environments.

Like other plug-ins, the unique attribute plug-in is configured by using the dsconfig command. For more information, see Section 14.1.9, "Configuring Plug-Ins With dsconfig." The easiest way to configure plug-ins is to use dsconfig in interactive mode. Interactive mode functions like a wizard and walks you through the plug-in configuration. Because the interactive mode is self-explanatory, the examples in this section do not demonstrate interactive mode, but provide the equivalent complete dsconfig commands.

17.9.2 Configuring the Unique Attribute Plug-In Using dsconfig

The following procedures explain how to configure attribute value uniqueness.

17.9.2.1 To Ensure Uniqueness of the Value of the uid Attribute

The unique attribute plug-in checks the uid attribute by default. The following task enables the unique attribute plug-in, and sets the base DN under which attribute value uniqueness for the uid attribute should be checked.

  1. Display the plug-ins that are currently defined in the server.

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  list-plugins

    Depending on your installation, the output will be similar to the following.

    Plugin                          : Type                            : enabled
--------------------------------:---------------------------------:--------
7-Bit Clean                     : seven-bit-clean                 : false
Change Number Control           : change-number-control           : true
Entry UUID                      : entry-uuid                      : true
LastMod                         : last-mod                        : true
LDAP Attribute Description List : ldap-attribute-description-list : true
Password Policy Import          : password-policy-import          : true
Profiler                        : profiler                        : true
Referential Integrity           : referential-integrity           : false
UID Unique Attribute            : unique-attribute                : false

  2. Display the properties that are configured for the unique attribute plug-in

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  get-plugin-prop \
  --plugin-name "UID Unique Attribute" \
Property : Value(s)
---------:---------
base-dn  : -
enabled  : false
type     : uid

  3. Enable the unique attribute plug-in.

    $ dsconfig --advanced -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  set-plugin-prop \
  --plugin-name "UID Unique Attribute" --set enabled:true

    Note:

    Ensure that you run the dsconfig command with --advanced subcommand. This subcommand modifies the display output to show the advanced plug-ins like postaddoperation, postmodifyoperation, and postmodifydnoperation that can be selected. The default values are pre-operation plug-ins like preaddoperation, premodifyoperation, and postmodifyoperation. You must select a matching pre-operation plug-in with a post-operation plug-in.

  4. Set the base DN under which uniqueness is checked.

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  set-plugin-prop \
  --plugin-name "UID Unique Attribute" --set base-dn:ou=People,dc=example,dc=com

17.9.2.2 To Ensure Uniqueness of the Value of Any Other Attribute

The unique attribute plug-in checks the uid attribute by default. If you want to ensure uniqueness for a different attribute, create a new instance of the unique attribute plug-in and set its type property.

This example creates a new instance of the unique attribute plug-in and ensures uniqueness of the mail attribute.

  1. Create and enable a new instance of the unique attribute plug-in.

    Set the type property to the name of the attribute that should be unique (in this case, mail.

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  create-plugin \
  --type unique-attribute --plugin-name "MAIL unique attribute"
  --set enabled:true --set type:mail

  2. Enable the new unique attribute plug-in.

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  set-plugin-prop \
  --plugin-name "MAIL Unique Attribute" --set enabled:true

  3. Set the base DN under which uniqueness is checked.

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  set-plugin-prop \
  --plugin-name "MAIL Unique Attribute" --set base-dn:ou=People,dc=example,dc=com

  4. Specify the attribute whose value must be unique.

    This example specifies the mail attribute.

    $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  set-plugin-prop \
  --plugin-name "MAIL Unique Attribute" --set type:mail

To ensure that the values of more than one attribute are unique, create and enable multiple instances of the unique attribute plug-in.

17.9.3 Replication and the Unique Attribute Plug-In

The Unique Attribute plug-in does not check attribute uniqueness when an update is performed as part of a replication operation. To ensure attribute value uniqueness in a replication environment, enable the unique attribute plug-in for the same attribute in the same subtree on all servers in the topology.

17.10 Configuring Virtual Attributes

Virtual attributes are attributes whose values do not exist in persistent storage but are dynamically generated in some way.

Oracle Unified Directory supports the following virtual attribute types:

  • collective attribute subentries

  • entryDN

  • entryUUID

  • governingStructureRule

  • hasSubordinates

  • isMemberOf

  • member

  • nsuniqueid

  • numSubordinates

  • orclguid

  • Password Policy Subentry

  • Proximity

  • structuralObjectClass

  • subschemaSubentry

  • User-defined virtual attributes

Virtual attributes are configured by using the dsconfig command. The dsconfig command accesses the plug-in configuration over SSL via the Section 14.3, "Managing Administration Traffic to the Server." The easiest way to configure virtual attributes is to use dsconfig in interactive mode. Interactive mode functions like a wizard and walks you through the virtual attribute configuration. Because the interactive mode is self-explanatory, the examples in this section do not demonstrate interactive mode, but provide the equivalent complete dsconfig commands.

For more information about using dsconfig, see Section 14.1, "Managing the Server Configuration With dsconfig."

This section describes the following topics:

17.10.1 To List the Existing Virtual Attributes

The directory server provides a number of virtual attribute rules by default. This example lists all configured virtual attribute rules.

Run the dsconfig command as follows:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n list-virtual-attributes

Virtual Attribute               : Type                            : enabled : attribute-type
--------------------------------:---------------------------------:---------:------------------
Collective Attribute Subentries : collective-attribute-subentries : true    : collectiveattributesubentries
entryDN                         : entry-dn                        : true    : entrydn
entryUUID                       : entry-uuid                      : true    : entryuuid
governingStructureRule          : governing-structure-rule        : true    : governingstructurerule
hasSubordinates                 : has-subordinates                : true    : hassubordinates
isMemberOf                      : is-member-of                    : true    : ismemberof
nsuniqueid                      : nsuniqueid                      : true    : nsuniqueid
numSubordinates                 : num-subordinates                : true    : numsubordinates
orclguid                        : orclguid                        : true    : orclguid
Password Policy Subentry        : password-policy-subentry        : true    : pwdpolicysubentry
Proximity                       : proximity                       : true    : proximity
structuralObjectClass           : structural-object-class         : true    : structuralobjectclass
subschemaSubentry               : subschema-subentry              : true    : subschemasubentry
Virtual Static member           : member                          : true    : member
Virtual Static uniqueMember     : member                          : true    : uniquemember

The output of this command shows the following (from left to right):

  • Virtual Attribute. The name of the virtual attribute, usually descriptive of what it does.

  • Type. The type of virtual attribute. It is possible to define more then one virtual attribute of a specific type.

  • enabled. Virtual attributes can either be enabled or disabled. Disabled virtual attributes remain in the server configuration, but their values are never generated.

  • attribute-type. Specifies the type of attribute for which virtual values are generated.

17.10.2 To Create a New Virtual Attribute

This example creates and enables a virtual attribute rule that adds a virtual fax number of +61 2 45607890 to any user entry with a location of Sydney (unless they already have a fax number in their entry):

Run the dsconfig command as follows:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  create-virtual-attribute \
  --type user-defined --name "Sydney Fax Number" \
  --set attribute-type:facsimiletelephonenumber --set enabled:true \
  --set value:+61245607890 --set filter:"(&(objectClass=person)(l=Sydney))"

17.10.3 To Enable or Disable a Virtual Attribute

To enable a virtual attribute, set the enabled property to true. To disable a virtual attribute, set the enabled property to false. This example disables the virtual attribute created in the previous example:

Run the dsconfig command as follows:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  set-virtual-attribute-prop --name="Sydney Fax Number" --set enabled:false

17.10.4 To Display the Configuration of a Virtual Attribute

Use the get-*-prop subcommand of dsconfig to display the virtual attribute configuration. This example displays the properties of the virtual attribute created in the previous example:

Run the dsconfig command as follows:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \
  get-virtual-attribute-prop --name="Sydney Fax Number"
Property          : Value(s)
------------------:----------------------------------
attribute-type    : facsimiletelephonenumber
base-dn           : -
conflict-behavior : real-overrides-virtual
enabled           : false
filter            : (&(objectClass=person)(l=Sydney))
group-dn          : -
value             : +61245607890

17.10.5 To Change the Configuration of a Virtual Attribute

Use the set-*-prop subcommand of dsconfig to change the virtual attribute configuration. This example changes the behavior of the virtual attribute if a conflict occurs. By default, the value of a real attribute overwrites the value of the virtual attribute. With this change, the value of the real attribute and that of the virtual attribute are merged.

Run the dsconfig command as follows:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \
  set-virtual-attribute-prop --name="Sydney Fax Number" \
  --set conflict-behavior:merge-real-and-virtual

17.11 Using LDAP Subentries

LDAP subentries are special entries that hold operational data for the server, and have the ldapSubEntry object class. They are similar to operational attributes in that they are not returned to clients unless explicitly requested by including a Subentries Control request control.

LDAP subentries can be used to specify a range of entries. This functionality is used in the definition of collective attributes and can also be useful in other areas like access control. For more information, see Section 17.12, "Using Collective Attributes" and Section 24.4.7, "To Define a Password Policy as an LDAP Subentry".

A subtree specification uses the following parameters to define the set of entries:

  • Base

    This is the relative name of the root of the subtree relative to the administrative point. So, if the administrative point is ou=system and the base is ou=users, the subtree begins at ou=users,ou=system. The base can be any length of name components, including "". In this case, the subtree begins at the administrative point, ou=system in the previous example.

  • Chop

    The chopBefore and chopAfter parameters are names relative to the base of the subtree, that specify whether an entry and its descendants should be excluded from the collection.The minimum parameter describes the minimum number of name components between the base and the target entry required to include entries within the selection. The maximum parameter describes the maximum length between the base and the target allowed before entries are excluded from the collection.

  • Specification filter

    The specification filter refines the subtree that has been defined by the previous parameters so that it is not a contiguous set of entries but rather a set of collected entries based on the objectClass characteristics of the entries.

    For example, you can define a subtree to cover a region of an administrative area but include only inetOrgPersons within this region.

The Oracle Unified Directory implementation of LDAP subentries is based on RFC 3672 (http://www.ietf.org/rfc/rfc3672.txt), with one extension - relative subtrees, described in the following section.

17.11.1 Relative Subtrees

Relative subtrees function like standard LDAP subtrees, with the exception that the specification filter is not a set of refinements but an LDAP search filter.

For relative subtree specification ensure that you use the relativeBase keyword to specify the root of the subtree. Do not use the base keyword to specify the root of the subtree.

For example, the following subtree definition targets all users under the base DN ou=People, whose location is Paris:

subtreeSpecification: {relativeBase "ou=people", specificationFilter "(l=Paris)" }

17.12 Using Collective Attributes

Collective attributes are attributes whose values are shared across a collection of entries. Collective attributes provide similar functionality to the Oracle Directory Server Enterprise Edition Class of Service feature.

Oracle Unified Directory collective attributes are like virtual attributes but are defined and stored with the user data as LDAP subentries. As part of the user data, collective attributes can be replicated to other servers in the topology.

This section describes the collective attribute implementation in Oracle Unified Directory and explains how to configure collective attributes. The section covers the following topics:

17.12.1 Extensions to the Collective Attributes Standard

The Oracle Unified Directory implementation of collective attributes is based on RFC 3671 (http://www.ietf.org/rfc/rfc3671.txt) and RFC 3672 (http://www.ietf.org/rfc/rfc3672.txt), with a few specific extensions. These extensions make Oracle Unified Directory collective attributes more transparent for LDAP client applications, and are described in the following sections:

17.12.1.1 Naming Collective Attributes

According to RFC 3671 (http://www.ietf.org/rfc/rfc3671.txt), collective attributes must have the COLLECTIVE attribute type, be derived from regular user attributes defined in the schema, and have the c- prefix. For example c-l is a collective attribute for the standard l attribute, and affected user entries have c-l added to them on the fly.

This specification can cause problems for many client applications, which are typically not aware of collective attributes and might need to be modified or extended to handle collective attributes. Oracle Unified Directory therefore removes this restriction and supports the definition of any regular attribute defined in the schema as a collective attribute. This extension is facilitated by adding the required attribute to the related collective attribute subentry and marking the attribute with the collective option.

17.12.1.2 Collective Attributes and Conflict Resolution

Collective attributes can be named in various ways. Due to this, a conflict resolution mechanism is provided for affected user entries already containing related real attributes. Oracle Unified Directory provides the same conflict resolution options for collective attributes as it does for virtual attributes: real-overrides-virtual, virtual-overrides-real, and merge-real-and-virtual.

The default conflict resolution rule is real-overrides-virtual. If an entry already has the same attribute type defined, the explicitly defined attribute takes precedence over the collective attribute. This behavior can be changed for each collective attribute subentry (to virtual-overrides-real or merge-real-and-virtual) by using the collectiveConflictBehavior attribute.

The following example dynamically adds the l collective attribute with a value of Paris to each applicable user entry under ou=people. The value of the collective attribute overrides any value for l that is specific to the entry:

dn: cn=People Locale,dc=example,dc=com
objectClass: top
objectClass: subentry
objectClass: collectiveAttributeSubentry
objectClass: extensibleObject
cn: People Locale
l;collective: Savoie
subtreeSpecification: {base "ou=people", minimum 1}
collectiveConflictBehavior: virtual-overrides-real

17.12.1.3 Excluding Collective Attributes From Specific Entries

In some instances, it might be necessary to avoid having collective attributes in specific user entries. You can add the collectiveExclusions operational attribute to such entries to achieve this behavior. To exclude specific collective attributes, list the attribute names as values of the collectiveExclusions attribute. To exclude all collective attributes, set the value of collectiveExclusions to excludeAllCollectiveAttributes.

The following example excludes the preferredLanguage attribute from being applied to the entry for user.0:

dn: uid=user.0,ou=People,dc=example,dc=com
objectclasses and other user attributes
collectiveExclusions: preferredLanguage

The following example excludes the c-l attribute from being applied to the entry for user.1:

dn: uid=user.1,ou=People,dc=example,dc=com
objectclasses and other user attributes
collectiveExclusions: c-l

The following example excludes both the preferredLanguage and c-l attributes from being applied to the entry for user.2:

dn: uid=user.2,ou=People,dc=example,dc=com
objectclasses and other user attributes
collectiveExclusions: preferredLanguage
collectiveExclusions: c-l

The following example excludes all collective attributes from being applied to the entry for user.0:

dn: uid=user.0,ou=People,dc=example,dc=com
objectclasses and other user attributes
collectiveExclusions: excludeAllCollectiveAttributes

17.12.2 Configuring Collective Attributes

Collective attributes are defined using LDAP subentries within the directory tree where they are applicable. The following examples use a simple tree with multiple user entries.

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
        ...

To add a common preferredLanguage attribute for all users, create and add a collective attribute subentry similar to the following:

dn: cn=People Preferred Language,dc=example,dc=com
objectClass: top
objectClass: subentry
objectClass: collectiveAttributeSubentry
objectClass: extensibleObject
cn: People Preferred Language
preferredLanguage;collective: fr
subtreeSpecification: {base "ou=people", minimum 1}

The preferredLanguage attribute-value pair is dynamically added to all user entries under ou=people, as shown in the following example:

dn: uid=user.0,ou=People,dc=example,dc=com
objectclasses and other user attributes
preferredLanguage: fr

dn: uid=user.1,ou=People,dc=example,dc=com
objectclasses and other user attributes
preferredLanguage: fr

...

The same procedure applies for collective attribute types. For example, the c-l collective attribute type specifies a locality name for a collection of entries. The following example adds a common c-l collective attribute:

dn: cn=People Locale,dc=example,dc=com
objectClass: top
objectClass: subentry
objectClass: collectiveAttributeSubentry
objectClass: extensibleObject
cn: People Locale
c-l: Paris
subtreeSpecification: {base "ou=people", minimum 1}

The c-l: Paris attribute is added to applicable entries, as shown in this example:

dn: uid=user.0,ou=People,dc=example,dc=com
objectclasses and other user attributes
c-l: Paris

dn: uid=user.1,ou=People,dc=example,dc=com
objectclasses and other user attributes
c-l: Paris

...

You can define multiple collective attributes in the subentry of any collective attribute in the following ways:

  • by adding the collective attribute types to the subentry

  • by adding regular attribute types with the collective option

  • by adding a combination of the two

Collective attribute subentries allow for flexible and complex definitions. For information about collective attribute scoping and the subtreeSpecification syntax, see RFC 3671 (http://www.ietf.org/rfc/rfc3671.txt) and RFC 3672 (http://www.ietf.org/rfc/rfc3672.txt).

This section describes the following topics about collective attributes:

17.12.2.1 To Create a New Collective Attribute

  1. Create an LDIF file with the changetype: add element that specifies the collective attribute subentry.

    Make sure that there are no trailing spaces after add. If a space exists after add, the server base-64 encodes the value to represent the space, which can cause problems.

    This example uses an input LDIF file named add_collective_attr.ldif.

    dn: cn=People Preferred Language,dc=example,dc=com
changetype: add
objectClass: top
objectClass: subentry
objectClass: collectiveAttributeSubentry
objectClass: extensibleObject
cn: People Preferred Language
preferredLanguage;collective: fr
subtreeSpecification: {base "ou=people", minimum 1}

  2. Use the ldapmodify command to add the collective attribute, as shown in the following example.

    $ ldapmodify -p 1389 -h localhost -D "cn=Directory Manager" -j pwd-file \
-f /usr/local/add_collective_attr.ldif
Processing ADD request for cn=People Preferred Language,dc=example,dc=com
ADD operation successful for DN cn=People Preferred Language,dc=example,dc=com

17.12.2.2 To Delete a Collective Attribute

You can delete a collective attribute by using either the ldapdelete command or the ldapmodify command. This example uses the ldapmodify command.

Use the ldapmodify command with the changetype: delete element, as shown in the following example.

$ ldapmodify -h localhost -p 1389 -D "cn=Directory Manager" -j pwd-file
  dn: cn=People Preferred Language,dc=example,dc=com
  changetype: delete
  deleting entry cn=People Preferred Language,dc=example,dc=com

17.12.2.3 To List the Collective Attributes That Apply to an Entry

To list the collective attribute subentries that apply to a specific user entry, request the collectiveAttributeSubentries operational attribute for that entry.

Use the ldapsearch command to list the collective attribute subentries that apply to the user.0 entry:

$ ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -j pwd-file \
  -b "uid=user.0,ou=People,dc=example,dc=com" \
  "objectclass=*" "collectiveAttributeSubentries"
  
  version: 1
  dn: uid=user.0,ou=People,dc=example,dc=com
  collectiveAttributeSubentries: cn=People Preferred Language,dc=example,dc=com

17.12.3 Inherited Collective Attributes

Inherited attributes enable a common set of attributes to be shared by nature of their inheritance. Inherited collective attributes provide flexible scoping mechanisms using the standard subentry subtree specification, and support any attribute type for RDN definition and construction.

The main difference between collective attributes and inherited collective attributes is the source of attribute values:

  • A collective attribute always derives its value from its definition entry.

  • An inherited collective attribute can inherit the collective attribute values from other entities, either directly or indirectly.

The inherited collective attributes functionality is built upon and extends collective attributes. Inherited attributes are defined as a specific type of collective attribute subentry (inheritedCollectiveAttributeSubentry). This type is further divided into the following two distinct subtypes:

  • inheritedFromDNCollectiveAttributeSubentry

  • inheritedFromRDNCollectiveAttributeSubentry

Each subtype has its own set of configuration attributes. The subtypes cannot be mixed in a single definition, so an inherited attribute definition can be of only one subtype.

Entries that are under the scope of an inherited collective attribute entry can potentially point to multiple "template" entries and can therefore inherit values for the inheritAttribute from multiple entries. In this case, the first value that is processed takes precedence.

As with other virtual attributes, no schema checking is performed on inherited attributes. Inheritance can, therefore, result in entries that violate the schema. However, since these attributes are all virtual, this kind of schema violation can be ignored as it does not have an impact on server function.

Inherited collective attributes provide similar functionality to the Oracle Directory Server Enterprise Edition Class of Service (Classic CoS). For example, suppose you have the following user entry:

uid=psmith,ou=people,dc=example,dc=com 
departmentNumber: 123
...

the following department entry:

cn=123,ou=departments,dc=example,dc=com 
telephoneNumber: 4486152643
...

and the following inherited attribute definition:

dn: cn=classicCOS,dc=example,dc=com 
objectClass: top 
objectClass: subentry 
objectClass: inheritedCollectiveAttributeSubentry 
objectClass: inheritedFromRDNCollectiveAttributeSubentry 
cn: classicCOS 
subtreeSpecification: {base "ou=people"} 
inheritFromBaseRDN: ou=departments 
inheritFromRDNAttribute: departmentNumber 
inheritFromRDNType: cn 
inheritAttribute: telephoneNumber

The inherited collective attribute sub-entry would apply to user entries under ou=people,dc=example,dc=com. The telephoneNumber attribute would be added to each of these entries. The value of the telephoneNumber attribute would be inherited from the entry whose DN is constructed with the following logic:

inheritFromRDNType=inheritFromRDNAttribute,inheritFromBaseRDN,"inherited collective attribute sub-entry rootDN"

or cn=123,ou=departments,dc=example,dc=com

The affected user entries would therefore be of the form:

uid=psmith,ou=people,dc=example,dc=com 
departmentNumber: 123
...
telephoneNumber: 4486152643

17.12.3.1 Specifying Inherited Collective Attributes

Like regular collective attributes, inherited collective attributes are defined using LDAP subentries within the directory tree where they are applicable.

The following examples use a simple tree with multiple user entries.

dn: dc=example,dc=com
     dn: ou=People,dc=example,dc=com
         dn: uid=hpollock,ou=People,dc=example,dc=com
         dn: uid=cventer,ou=People,dc=example,dc=com
         dn: uid=sdonnelly,ou=People,dc=example,dc=com
         ...

To add an inherited postalAddress attribute for all users, create and add an inherited collective attribute subentry similar to the following:

dn: cn=indirectCOS,dc=example,dc=com
objectClass: top
objectClass: subentry
objectClass: inheritedCollectiveAttributeSubentry
objectClass: inheritedFromDNCollectiveAttributeSubentry
cn: indirectCOS
subtreeSpecification: {base "ou=people"}
inheritFromDNAttribute: manager
inheritAttribute: postalAddress

This subentry specifies that the user entry inherits its postalAddress value from the entry referenced by the manager attribute in the user's entry.

The manager's entry contains the real value for the postalAddress attribute:

dn: uid=dsmith,ou=People,dc=example,dc=com
... objectclasses and other user attributes
postalAddress: 650 Granger Parkway, Redwood Shores, CA 94065

Each user entry references the manager entry, and inherits its postalAddress from that entry:

dn: uid=hpollock,ou=People,dc=example,dc=com
... objectclasses and other user attributes
manager: uid=dsmith,ou=People,dc=example,dc=com
postalAddress: 650 Granger Parkway, Redwood Shores, CA 94065

dn: uid=cventer,ou=People,dc=example,dc=com
... objectclasses and other user attributes
manager: uid=dsmith,ou=People,dc=example,dc=com
postalAddress: 650 Granger Parkway, Redwood Shores, CA 94065

dn: uid=sdonnelly,ou=People,dc=example,dc=com
... objectclasses and other user attributes
manager: uid=dsmith,ou=People,dc=example,dc=com
postalAddress: 650 Granger Parkway, Redwood Shores, CA 94065

17.13 Configuring Referrals

A referral is a pointer to a remote suffix or entry that is returned to a client instead of a result. When a server is unable to handle a client's request, it sends a list of referrals to the client, which point the client to other servers in the topology. The client then performs the operation again on one of the remote servers in the referral list.

The server returns a list of referrals in the following cases:

  • Writability is disabled or set to internal-only on the server or on the local backend workflow element. For more information, see Section D.22.6, "writability mode".

    This kind of referral is called referral on update.

  • The local backend workflow element has been placed in maintenance mode.

    You can place a local backend workflow element in maintenance mode if you want to prevent the server from responding to client requests temporarily.

    To place a backend in maintenance mode, set the maintenance property of the local backend workflow element to true.

  • The backend is unavailable for some reason, for example a data import or reindex is in process.

  • The client request specifically targets a smart referral. For more information, see Section 17.13.3, "Smart Referrals".

A referral URL is an LDAP URL that includes the host name, port number, and optionally a DN on the local host or on another server. For more information, see Section 17.13.4, "LDAP URLs".

The server returns the result code REFERRAL (10) along with a list of referral URLs, if available. If no referral URLs are available, the server returns the result code UNAVAILABLE (52).

The list of referral URLs can be created in two ways:

17.13.1 Referrals in a Replicated Topology

The replication service generates a list of referral URLs to which requests can be redirected. This list corresponds to the LDAP/LDAPS connection handlers configured on each local server. To publish a value other than the LDAP/LDAPS connection handler, you can define your own referral URLs as values of the referrals-url property of the replication domain on the local server.

When a client request targets a replicated server that is unavailable, the server sends the list of referral URLs to which the request can be redirected.

The list of referral URLs is organized according to the protocol that was used for the request. For example, if an operation is done over LDAPS, the first URLs that are provided are those that use the same secure protocol (LDAPS).

In addition, the list is organized by groupID. The URLs that represent a server in the same replication group are presented first. The list of URLs is limited to 16 URLs for each protocol type (LDAP/LDAPS) and excludes any untrusted servers.

For security considerations, referrals that are propagated by the replication service are not returned on untrusted servers. Untrusted servers should not divulge information about the rest of the topology. If a client request targets an untrusted server, the list of referral URLs will only include the servers that are managed by the administrator on the local backend. In addition, the referral URLs that are provided by the replication service exclude any untrusted servers in the topology.

If the publish-referrals configuration property of a replication domain is set to false, that server will not be included in the list of referrals that is generated by the replication service.

17.13.2 Configuring the Referral List Manually

To override the list of referral URLs that is presented by the replication service, or to set up referrals outside of a replicated topology, set the referrals-url property of the DB local backend workflow element.

The referrals-url property takes one or more LDAP URLs as values.

The following example specifies that any client requests targeting the dc=example,dc=com suffix should be referred to the server running on the host host1.example.com and listening on port 2389.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \                                                          
 set-workflow-element-prop --element-name userRoot \
 --set referrals-url:ldap://host1.example.com:2389/dc=example,dc=com

To specify multiple LDAP URLs, use the --add suboption multiple times. For example:

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -X -n \                                                          
 set-workflow-element-prop --element-name userRoot \
 --add referrals-url:ldap://host1.example.com:2389/dc=example,dc=com
 --add referrals-url:ldap://host2.example.com:1389/dc=example,dc=com

17.13.3 Smart Referrals

A smart referral is a special type of entry that references content on another server or in another suffix. Smart referral entries contain the referral object class with one or more instances of the ref attribute. Each ref attribute contains an LDAP URL that is used in the referral.

17.13.3.1 To Configure a Smart Referral

To configure a smart referral, add a new entry that contains a referral object class and a ref attribute. The ref attribute must contain an LDAP URL.

This example creates a referral on server B for a user entry that exists on server A.

  1. Locate the user entry on server A by running the following search command:

    $ ldapsearch -h serverA -p 1389 -b dc=example,dc=com "uid=user.199" cn
dn: uid=user.199,ou=People,dc=example,dc=com
cn: Alfred Altay

  2. Add a referral entry to the directory on server B.

    $ ldapmodify -h serverB -p 2389 -D "cn=directory manager" -j pwd-file
dn: uid=aaltay,ou=People,dc=example,dc=com
changetype: add
objectclass: top
objectclass: extensibleObject
objectclass: referral
uid: aaltay
ref: ldap://serverA:1389/dc=example,dc=com??sub?(uid=user.199)

Processing ADD request for uid=aaltay,ou=People,dc=example,dc=com
ADD operation successful for DN uid=aaltay,ou=People,dc=example,dc=com

  3. As a user with sufficient access rights, search for the user entry on server B.

    $ ldapsearch -h serverB -p 2389 -D "cn=directory manager" -j pwd-file \
  -b dc=example,dc=com "uid=aaltay"
SearchReference(referralURLs={ldap://localhost:1389/dc=example,dc=com??sub?})

17.13.3.2 To Modify a Smart Referral

To view or modify a smart referral, use the ldapsearch or ldapmodify commands with the manageDsaIT control. This control informs the server that you intend to manage the referral object as a regular entry and prevents the server from sending a referral result for requests that read or update referral objects.

  1. Use the ldapsearch command to view the referral.

    $ ldapsearch -h serverB -p 2389 -D "cn=Directory Manager" -j pwd-file \
  -b dc=example,dc=com --control managedsait "(uid=aaltay)" ref
dn: uid=aamar,ou=People,dc=example,dc=com
ref: ldap://serverA:1389/dc=example,dc=com??sub?(uid=user.199)

  2. Use the ldapmodify command to modify the referral.

    This example changes the server to which the referral points and the base DN under which the entry is located.

    $ ldapmodify -h serverB -p 2389 -D "cn=Directory Manager" -j pwd-file \
  --control managedsait
dn: uid=aaltay,ou=People,dc=example,dc=com
changetype: modify
replace: ref
ref: ldap://serverC:1389/ou=People,dc=example,dc=com??sub?(uid=user.199)
Processing MODIFY request for uid=aaltay,ou=People,dc=example,dc=com
MODIFY operation successful for DN uid=aaltay,ou=People,dc=example,dc=com

17.13.3.3 To Delete a Smart Referral

To delete a smart referral, use the ldapdelete command with the manageDsaIT control. This control informs the server that you intend to manage the referral object as a regular entry and prevents the server from sending a referral result for requests that read or update referral objects.

  1. Use the ldapsearch command to view the referral.

    $ ldapsearch -h serverB -p 2389 -D "cn=Directory Manager" -j pwd-file \
  -b dc=example,dc=com --control managedsait "(uid=aaltay)" ref
dn: uid=aamar,ou=People,dc=example,dc=com
ref: ldap://serverA:1389/dc=example,dc=com??sub?(uid=user.199)

  2. Use the ldapdelete command to delete the referral.

    $ ldapdelete -h serverB -p 2389 -D "cn=Directory Manager" -j pwd-file \
  --control managedsait "uid=aaltay,ou=People,dc=example,dc=com"
Processing DELETE request for uid=aaltay,ou=People,dc=example,dc=com
DELETE operation successful for DN uid=aaltay,ou=People,dc=example,dc=com

17.13.4 LDAP URLs

The format of an LDAP URL is described in RFC 4516 and is summarized as follows:

ldap[s]://hostname:port/base_dn?attributes?scope?filter

An LDAP URL includes the following components:

ldap[s]

Indicates whether to connect to the server (ldap:), or connect to the server over SSL (ldaps:).

hostname

Specifies the host name or IP address of the LDAP server.

port

Specifies the port number of the LDAP server. If no port is specified, the default LDAP port (389) or LDAPS port (636) is used.

base_dn

Specifies the distinguished name (DN) of an entry in the directory. This DN identifies the entry that is the starting point of the search. If no base DN is specified, the search starts at the root of the directory tree.

attributes

Returns the specified attributes. Use commas to separate more than one attribute. If no attributes are specified, the search returns all attributes.

scope

Specifies the scope of the search:

  • base. Search only the base entry specified by base_dn.

  • one. Search one level below the base entry specified by base_dn

  • sub. Search the base entry and all entries below the specified base_dn

If no scope is specified, the server performs a base search.

filter

Specifies the search filter to apply to entries within the specified scope of the search. If no filter is specified, the server uses the default (objectclass=*).

Any spaces must be escaped using a character appropriate to your shell.

Note:

Unless an LDAP client provides authentication, any search request initiated by means of an LDAP URL is anonymous (unauthenticated).

17.13.4.1 Example LDAP URLs

  • The following LDAP URL specifies a search for all entries that have the surname Jensen at any level under dc=example,dc=com. No port is specified, so the default (389) is used. No attributes are specified, so all attributes will be returned.

    ldap://example.com/dc=example,dc=com??sub?(sn=Jensen)

  • The following LDAP URL specifies a search for the cn and telephoneNumber attributes at any level under dc=example,dc=com. The server contacts the remote server at port 2389. Because no search filter is specified, the server uses the default filter (objectclass=*).

    ldap://example.com:2389/dc=example,dc=com?cn,telephoneNumber?sub

17.14 Managing Virtual Attributes With Oracle Directory Services Manager

The Configuration tab of each server instance in ODSM enables you create, delete, and modify virtual attributes.

The following sections describe how to manage virtual attributes with ODSM, and contains the topics:

17.14.1 Display Existing Virtual Attributes

To display the existing virtual attributes with ODSM, perform the following steps:

  1. Connect to the directory server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."

  2. Select the Configuration tab.

  3. Expand the General Configuration node.

  4. Expand the attributes in the Virtual Attributes node to display all the existing virtual attributes.

    Figure 17-1 Virtual Attributes

    Description of Figure 17-1 follows
    Description of "Figure 17-1 Virtual Attributes"

  5. Click the virtual attribute that you want to view in the left-hand pane.

    The virtual attribute details are displayed in the right-hand pane.

17.14.2 Create Virtual Attributes

To create a virtual attribute using ODSM, perform the following steps:

  1. Connect to the directory server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."

  2. Select the Configuration tab.

  3. From the Create menu, select Virtual Attributes.

  4. In the Name field, type the name of the virtual attribute.

  5. From the Virtual Attribute Type list, select the type of virtual attribute.

  6. Click the Add icon to enter the Base DN for the branches containing entries that are eligible to use this virtual attribute.

    Do one of the following to enter the Base DN:

    • In the Base DN field, type the desired Base DN.

    • Click Select to use the Tree view or the Search view to select entries.

  7. Click the Add icon to specify the DNs of the group whose members are eligible to use this virtual attribute.

    Do one of the following to specify the DNs of the group:

    • In the Group DN field, type the desired Group DN.

    • Click Select to use the Tree view or the Search view to select entries.

  8. Click the Add icon to specify the search filters to apply against these entries to determine if virtual attribute needs to be generated for those entries.

  9. Click Create.

Note:

The properties described in the preceding procedure are the same for all virtual attributes except for User Defined and Member virtual attributes, because they contain some additional properties.

User Defined Virtual Attributes

It contains the following additional properties:

Conflict Behavior: Specifies the behavior that the server has to exhibit for entries that already contain one or more real values for the associated attribute. It has the following values:

  • Merge real and virtual: Indicates that the virtual attribute provider is to preserve any real values contained in the entry and merge them with the set of generated virtual values so that both the real and virtual values are used.

  • Real overrides virtual: Indicates that any real values contained in the entry are preserved and used, and virtual values are not generated.

  • Virtual overrides real: Indicates that the virtual attribute provider suppresses any real values contained in the entry, and generates virtual values and uses them.

Value: Specifies the values to be included in the virtual attribute.

Member Virtual Attributes

It contains the following additional properties:

Conflict Behavior: It is similar to the User Defined Virtual Attributes.

Allow Retrieving Membership: Indicates whether to handle requests that demands all values for the virtual attribute. The default value is false.

17.15 Managing Data With Oracle Directory Services Manager

The Data Browser tab of each server instance in ODSM enables you to perform a basic search on the directory data, and to add, delete, and modify entries.

ODSM includes an "auto-suggest" facility that enables you to enter a subset of characters in any of the data fields. ODSM then returns all entries that match that subset of characters. The auto-suggest feature returns only those entries that have already been cached by ODSM.

The following sections describe how to manage data with ODSM, and contains the topics:

17.15.1 Display Entries

To display directory entries by using the ODSM data browser, complete the following steps:

  1. Connect to the directory server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."

  2. Select the Data Browser tab.

  3. Select the appropriate network group from the Network Group list.

  4. Expand the entries in the Entry pane to display all of the entries in the required subtree.

    A maximum of 200 entries is displayed at a time.

  5. To restrict the entries to a specific entry set, select the subtree (for example, ou=People) and click the Filter icon.

    In the Filter field, type the required filter (for example, surname=a*) and click OK.

  6. Select the entry that you want to view in the left hand pane.

    The entry details are displayed in the tabs on the right.

See also Section 17.15.2, "View the Attributes of an Entry."

17.15.2 View the Attributes of an Entry

To view the attributes of an entry:

  1. Display the entry as described in Section 17.15.1, "Display Entries."

  2. Select the entry that you want to view in the left hand pane.

    The entry details are displayed in the tabs on the right.

    Every entry has a corresponding Properties tab, that displays all the possible attributes of the entry (mandatory and optional). In addition, the following types of entries have a customized tab that displays the mandatory attributes of the entry in a layout that is logical for the entry type:

    • inetorgperson entries have a corresponding User Page tab.

    • group entries have a corresponding Group Page tab.

    • country entries have a corresponding Country Page tab.

    • domain entries have a corresponding Domain Page tab.

    • organization entries have a corresponding Organization Page tab.

    • organization unit entries have a corresponding Organization Unit Page tab.

17.15.3 Search for Entries

The basic search function on the Data Browser tab enables you to search for user or group entries. To perform a basic search on the directory data, complete the following steps:

  1. Connect to the directory server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."

  2. Select the Data Browser tab.

  3. Select the appropriate network group from the Network Group list.

  4. Select the Search tab on the left hand pane.

  5. From the For list, select whether you are searching for a user entry or a group entry.

  6. Enter any part of the entry name and click the right arrow button. For example, to search for user John Smith, you might enter Smith, or Smi, or John, and so forth.

  7. When the entry is displayed in the left pane, double-click on the entry to display its details in the right pane.

17.15.4 Add an Entry

To add or delete entries with Oracle Directory Services Manager, you must have write access to the parent entry and you must know the DN to use for the new entry. To add an entry by using the ODSM data browser, complete the following steps:

  1. Connect to the directory server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."

  2. Select the Data Browser tab.

  3. Select the appropriate network group from the Network Group list.

  4. Click the Add Entry icon and select the kind of entry that you want to add, for example User Entry.

  5. Enter the DN of the parent entry. This is the entry beneath which the new entry will appear in the directory tree, for example, ou=people,dc=example,dc=com.

    To select an existing entry as the parent entry, 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.

  6. Enter any additional information for the new entry.

  7. When the required details have been entered, click Create.

17.15.5 Add an Entry Based on an Existing Entry

To add an entry that is based on an existing entry by using the ODSM data browser, complete the following steps:

  1. Display the existing entries as described in Section 17.15.1, "Display Entries."

  2. Select the entry on which you want to base the new entry and click the Create like entry icon.

    The details of the existing entry are displayed in the right pane.

  3. Provide a new Common Name and User Name for the entry.

  4. Modify any other details of the entry.

  5. Click Create.

17.15.6 Delete an Entry

To delete an entry by using the ODSM data browser, complete the following steps:

  1. Display the existing entries as described in Section 17.15.1, "Display Entries."

  2. Select the entry that you want to delete and click the Delete icon.

  3. On the Delete Entry dialog, verify that you are deleting the correct entry and click OK.

17.15.7 Delete an Entry and its Subtree

To delete an entry and all entries beneath it in the directory tree, complete the following steps:

  1. Display the existing entries as described in Section 17.15.1, "Display Entries."

  2. Select the entry that you want to delete and click the Delete Entry and its Subtree icon.

  3. On the Delete Subtree dialog, verify that you are deleting the correct entry and click OK.

17.15.8 Modify an Entry's RDN

To modify the RDN of an entry by using the ODSM data browser, complete the following steps:

  1. Display the existing entries as described in Section 17.15.1, "Display Entries."

  2. Select the entry whose RDN you want to modify on which you want to base the new entry and click the Edit RDN icon.

  3. Provide a new RDN in the New RDN value field.

  4. Select Delete Old RDN if you want the values that formed the old RDN to be deleted from the entry. If you do not select this checkbox, the values that formed the old RDN are retained as non-distinguished attribute values of the entry.

  5. Optionally, click the Refresh subtree entries icon to verify the RDN change.

17.15.9 Import Data From an LDIF File

You can import entries from an LDIF file, as follows:

  1. Connect to the directory server from ODSM, as described in Section 18.2, "Connecting to the Server From Oracle Directory Services Manager."

  2. Select the Data Browser tab.

  3. Select the appropriate network group from the Network Group list.

  4. Click the Import LDIF icon.

  5. On the Import Entry(ies) dialog, click Choose File.

  6. Locate the LDIF file on your system and click OK.

  7. On the LDIF Import Progress dialog, monitor the progress of the import and click OK when the export has completed.

  8. The Data Browser tree refreshes to show the new entries.

17.15.10 Export Data to an LDIF File

You can export entries to an LDIF file, by using ODSM, as follows:

To export entries to an LDIF file, by using the ODSM data browser, complete the following steps:

  1. Display the entries as described in Section 17.15.1, "Display Entries."

  2. Navigate to the top level DN of the subtree you want to export and click the Export LDIF icon.

  3. On the Export Entry dialog, select Export Operational Attributes if you want the operational attributes to be exported.

  4. Click OK.

  5. Click here to open the LDIF file.

    The complete LDIF file is displayed in a separate tab of the browser window in which ODSM is running.

  6. Save the LDIF file to a writable location.

  7. Click OK on the Export Entry dialog to exit the export.