18 Managing Directory Data
18.1 Importing and Exporting Data
The directory server provides several mechanisms to move data into and out of a specific back end.
The following topics outline the various options and then describes the import and export mechanisms in more detail:
Note:
When you import user entries, be aware 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 Modifying the Default Password Policy.
18.1.1 Populating a Stand-Alone Directory Server With Data
You can populate a stand-alone directory by importing data from an LDAP Data Interchange Format (LDIF) using setup utility or import-ldif command, copying the binary database from another server, restoring from a previous backup, if any, or by adding entries using the ldapmodify command.
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
setuputility in GUI mode or by using thesetuputility 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
ldapmodifycommand, 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-ldifcommand. 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-ldifcommand imports data from an LDIF file either by replacing any existing data in the suffix or by appending data to a base DN. Similarly, theexport-ldifcommand 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
restorecommand, 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.
18.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 from MakeLDIF Template files. In most cases, import-ldif is significantly faster than adding entries using ldapmodify.
For information on creating MakeLDIF files, see About Creating MakeLDIF Template Files. 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 Tuning Performance and 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:
18.1.2.1 About import-ldif Operation Modes
The import-ldif command has two modes of operation: online and offline.
-
Online mode. In online mode,
import-ldifcontacts a running directory server instance and registers an import task. The command accesses the task back end over SSL through the administration connector. For more information, see Managing Administration Traffic to the Server. Online mode runs automatically when any connection options (such as--hostname,--port,--bindDN, and--bindPasswordFile) are specified.Note:
Even for an online import, the back end is unavailable during the import. In a replicated topology, the overall service remains available through the referral on update feature. For more information, see Understanding 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 Tuning Performance.
-
Offline mode. When no connection options are specified, the command runs in offline mode. In offline mode,
import-ldifaccesses the database directly rather than through a directory server instance. In this case, the directory server must be stopped.
18.1.2.2 Importing Data in Offline Mode
The following 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.
18.1.2.3 Replacing Existing Data During an Offline Import
The following procedure replaces an existing back-end with new entries specified in an import file.
18.1.2.4 Appending Imported Data to Existing Data
The following procedure appends the entries in an import file to the existing entries in the back end.
18.1.2.5 Importing 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.
18.1.2.6 Importing Fractional Files Using Filters
The import-ldif command provides options to import part of an import file by using filters for data inclusion or exclusion. Ensure 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
18.1.2.7 Including or Excluding Attributes During Import
The import-ldif command provides options to include and exclude attributes during import by using the --includeAttribute and --excludeAttribute options, respectively. Ensure that you fully understand how this mechanism works before you use it.
18.1.2.9 Recording 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 file 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.
18.1.2.10 Importing 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 About Creating MakeLDIF Template Files and make-ldif.
18.1.2.11 Running 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 through 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 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
18.1.2.12 Scheduling 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 through 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 Configuring Commands As Tasks.
18.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:
18.1.3.1 About export-ldif Operation Modes
The export-ldif command has two modes of operation: online and offline.
-
Online mode. In online mode,
export-ldifcontacts 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 through the administration connector. For more information, see Managing Administration Traffic to the Server. -
Offline mode. When no connection options are specified, the command runs in offline mode. In offline mode,
export-ldifaccesses the database directly rather than through a directory server instance. In this case, the directory server must be stopped.
For more information, see export-ldif.
18.1.3.2 Exporting Data to LDIF
This procedure explains how to export data to LDIF. Follow these steps:
18.1.3.3 Exporting 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.
18.1.3.4 Exporting Part of a Back End 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. Ensure 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.
18.1.3.5 Including or Excluding Attributes During Export
The export-ldif utility provides options to include and exclude attributes during export by using the --includeAttribute and --excludeAttribute options, respectively. Ensure that you fully understand how this mechanism works before you use it.
18.1.3.6 Exporting to LDIF and Then Compress the File
The export-ldif command allows you to compress the output LDIF file.
18.1.3.7 Running 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 through the administration connector. For more information, see 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
18.1.3.8 Scheduling 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 through the administration connector. For more information, see 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
18.1.4 About 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:
18.1.4.1 Understanding the Template File Format
Template files can contain up to four sections, which must be provided in the following order:
18.1.4.1.1 Understanding 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 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.
18.1.4.1.2 Understanding 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.
18.1.4.1.3 Understanding 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
organizationobject class. -
ou -
Creates an entry with the
organizationalUnitobject class. -
c -
Creates an entry with the
countryobject 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 Understanding 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 Understanding Standard Replacement Tags.
18.1.4.1.4 Understanding 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 how make-ldif provides some flexibility when generating LDIF data. The tags that can be included in a template definition are described in the topics that follow (see Understanding Standard Replacement Tags and Using 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 if the combination is never duplicated.
In addition to the template and rdnAttr lines, you can include one or more subordinateTemplate lines, which enables you to include dynamically-generated entries below other dynamically generated entries (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 with 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.
18.1.4.2 Understanding 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. You can also create custom tags, as described in Defining Custom Tags.
The following topics describe the standard set of tags that can be used in a make-ldif template file:
18.1.4.2.1 Understanding 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 ofuid=john.doe,ou=People,dc=example,dc=com, the tag<DN:1>will be replaced withuid=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 ofuid=john.doe,ou=People,dc=example,dc=comthe tag<DN:-1>is replaced withdc=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/MakeLDIFdirectory. If there is a second argument, it must have a value of eithersequentialorrandom, 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 thecitiesfile, 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-ldifcommand includes several standard data files that can be used in generated data. These files are included in theconfig/MakeLDIFdirectory and therefore only the filename is required. The files include:cities— contains a list of common city namesfirst.names— contains a list of common first nameslast.names— contains a list of common last namesstates— contains a list of all two-character US state abbreviationsstreets— contains a list of common street namesThis 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.namesfile. 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
descriptionattribute is only included in the generated entry if thedisplayNameattribute is not included (that is, the resulting entry will contain eitherdisplayNameordescriptionbut not both).The
IfAbsenttag 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, theIfAbsenttag 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
IfPresentstandard 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
descriptionattribute will only be included in the generated entry if thedisplayNameattribute is also included (that is, the resulting entry will either contain neither attribute or it will contain both attributes).The
IfPresenttag 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 act if that value is included in the generated entry.This tag can be used in both branch and template definitions.
-
The Last Tag
The
Laststandard replacement tag is replaced with a last name taken from theconfig/MakeLDIF/last.namesfile. 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-ldifwill 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>
In this case, the
1following the green and blue elements are not technically needed because 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
ParentDNstandard 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
Presencestandard 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
displayNameattribute will only be present in about 50% of the entries generated.The
Presencetag 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
Randomstandard replacement tag is replaced with a randomly-generated value. Many 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 value 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), numeric digits (that is, the character set0123456789), or both. 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 ofOctober). 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 ofOct). -
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
RDNstandard 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
RDNtag does not take any arguments. It can be used in both branch and template definitions. -
The Sequential Tag
The
Sequentialstandard 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
trueorfalseindicating 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.
18.1.4.2.2 Using 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.
18.1.4.2.3 About 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.
18.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.
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 Understanding Custom Tag Includes.
Custom tag definitions must include the following methods:
| Methods | Description |
|---|---|
|
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 |
|
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 |
|
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. |
18.2 Importing Large Data Sets
Understand on improving performance when importing large data sets to the directory server from this topic.. By default, the server imports data with a fixed set of parameters.
You can change the default behavior in two ways:
-
Specify certain options when you run the
import-ldifcommand.For more information, see About the Import Options Setup.
-
Use the
dsjavapropertiescommand to set the appropriate Java arguments before running theimport-ldifcommand.For more information, see Tuning the JVM and Java Arguments.
18.2.1 About the Import Options Setup
There are various options of import-ldif command that are useful when importing particularly large databases. The options are listed out and described in this topic.
They are listed below: following options of the import-ldif command are useful when you are importing particularly large databases:
-
--skipDNValidationThis 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 ensure 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
--skipDNValidationoption 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
--skipDNValidationoption is specified. Generally, you can generate correct LDIF files by using themake-ldifcommand, LDIF files exported from an LDAP server, or LDIF files created by scripts that are historically known to generate correct LDIF files. -
--threadCountThis 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-countalso increases the buffer space that is required in phase one of the LDIF import. -
--tmpDirectoryIn 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-limitfor 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, turn off all substring indexing to prevent most of the index records from hitting the
index-entry-limit.
-
18.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.
This section contains the following topics:
18.2.2.1 Considerations for Tuning JVM Arguments
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 must 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.
18.2.2.2 Tuning JVM Arguments
When you have calculated the memory requirement, perform the following steps:
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.
18.3 Backing Up, Purging, 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:
18.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 Backing Up the Directory Server 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.
18.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:
18.3.2.1 Backing Up All Back Ends
You can back up the back ends by using the --backUpAll option.
You must note that when you execute the backup command with --backUpAll option, the following runtime data is not backed up. You can back up all the other backends.
adminRoot:cn=admin data
ads-truststore:cn=ads-truststore
backup:cn=backups
monitor:cn=monitorThe 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 ./ ../ 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/userRoot ./ backup.info ../ backup-userRoot-20231003090628Z
The backup.info file contains detailed information about the current backup.
$ more /tmp/backup/userRoot/backup.info backend_id=userRoot backup_id=20231003090628Z backup_date=20231003090629Z incremental=false compressed=true encrypted=false property.archive_file=backup-userRoot-20231003090628Z property.last_logfile_size=58339 property.last_logfile_name=00000000.jdb
18.3.2.2 Backing 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
18.3.2.3 Performing 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
18.3.2.4 Backing 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.
18.3.2.5 Performing an Incremental Backup on a Specific Back End
Perform an incremental backup on a specific backend following these steps:
18.3.2.6 Scheduling 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 through 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 Managing Administration Traffic to the Server.
18.3.3 About the Server Configuration Back Up
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.ldiffile. -
At modification time. Whenever a directory administrator makes changes to the configuration by using the
dsconfigutility with the server online, the directory server saves theconfig.ldiffile 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
18.3.4 Backing Up the Directory Server for Disaster Recovery
Directory and system administrators should have a disaster recovery plan in place in case a natural, human-induced, or catastrophic disaster occurs. 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 Considerations for Re-instating Replicated Directory Servers.
The following procedure explains how to back up the Directory Server for Disaster Recovery:
18.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:
18.3.5.1 Taking a ZFS Snapshot On a Dedicated Backup Server
The following procedure explains how to take a ZFS snapshot on a dedicated server:
18.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:
18.3.6.2 Restoring 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.
18.3.6.3 Scheduling 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.
18.3.6.4 Restoring 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.
18.3.7 Considerations for Re-instating 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 re-instating 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 re-instating a replicated server, ensure that the configuration file INSTANCE_DIR/OUD/config/config.ldif is the same as when the backup was made. Re-instate the config.ldif file prior to re-instating the server back ends.
You cannot re-instate 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 must re-instate a replicated server, re-initialize 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 re-instate 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 re-instate your data using the restore command. When the old backup is re-instated, the other servers will update that server with recent updates made since the backup was saved. See Changing the Data Set in an Existing Replicated Topology for more information on replication changelogDB.
18.3.8 Deleting Backup Data Files
By running 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.
Note:
Beginning with OUD Bundle Patch 12.2.1.4.230919 and later releases, backup data files can be automatically purged using the newpurge-backup utility. This can be done both offline and online. Based on the purge criteria set, it automatically trims the backup.info file and deletes the backup data files. See Purging Backup Data Files Automatically.
When you delete backup files manually, ensure that you do not break any dependencies between backup sets.
Perform the following procedure to delete the backup data:
18.3.9 Purging Backup Data Files Automatically
The directory server provides an effective command-line utility, purge-backup, for automatically purging backup data files.
The following content applies only to OUD Bundle Patch 12.2.1.4.230928 and later releases.
The purge-backup command can be executed immediately or as a scheduled job. If the purge-backup is scheduled, the command contacts the server over SSL, using the administration connector, and registers a purge-backup task. If no connection options are specified, the command runs immediately. Based on the purge criteria set, this job automatically trims the backup.info file and deletes the backup data files.
The following procedures demonstrate how to utilize the purge-backup command in a variety of scenarios:
18.3.9.1 Purging Backup Data for All Back Ends
You can purge the backup data files for all back ends using the --purgeAll option. You can use this option when a prior backup has been executed using the --backUpAll option.
See Backing Up All Back Ends for a list of back ends for which backup is supported. The same is applicable for purging as well.
All purge-backup operations expect a --purgeDelay argument, which defines the number of days before which the backup data is purged. The backup directory is anticipated to have subdirectories for each back end, with each subdirectory including the backup.info file as well as the backup data files.
Consider the following example. Here you run the following command on a standalone directory server, which specifies that backup data for all back ends older than 30 days should be considered for purging in the specified backup location.
./purge-backup --backupDirectory /tmp/backup --purgeDelay 30 --purgeAllThe utility trims the backup.info file by eliminating all backup info sets that have qualified for purge depending on the purgeDelay parameter, and then deletes the backup files from the backup directory. You must bear in mind that the most recent backup set will not be considered for purge.
Following the completion of the purge-backup operation, the contents of /tmp/backup/userRoot would be as follows:
$ls /tmp/backup/userRoot/
backup.info backup-userRoot-20230924134151Z
backup.info would look like:
backend_id=userRoot
backup_id=20230924134151Z
backup_date=20230924134155Z
incremental=false
compressed=true
encrypted=false
property.archive_file=backup-userRoot-20230924134151Z
property.last_logfile_size=37964
property.last_logfile_name=00000000.jdb18.3.9.2 Purging Backup Data for Specific Back Ends
You can purge backup data for a single back end using the --backendID option.
Run the listbackends command to see a list of the back ends that are configured on the server. See Backing Up a Specific Back End.
To purge backup data for the userRoot back end, execute the following command:
purge-backup --backendID userRoot --backupDirectory /tmp/backup/userRoot --purgeDelay 1018.3.9.3 Scheduling a Purge-Backup as a Task
You can periodically purge old backup files. The directory server provides a task back end for processing administrative tasks, such as purge-backup.
You can specify the start time for a purge-backup 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 through the administration connector. If you schedule the purge-backup as a task, you must therefore specify how the SSL certificate will be trusted. This example schedules a purge-backup for execution at a future time. The -X option specifies that all certificates presented by the server are trusted. See Managing Administration Traffic to the Server.
Run the purge-backup command with the following options:
purge-backup --port 4444 --bindDN "cn=Directory Manager" \
--bindPasswordFile pwd-file -X \
--purgeAll \
--purgeDelay 30 \
--backupDirectory /tmp/backups
--start 20230924131502417manage-tasks command. For example:manage-tasks --port 4444 --bindDN "cn=Directory Manager" \
--bindPasswordFile pwd-file -X --info 20230924131220034 --no-prompt18.4 About 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 Unified Directory Services Manager to locate entries in the directory.
This section contains the following topics:
18.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.
18.4.2 About ldapsearch Location and Format
Learn about the ldapsearch location and the format. Understand about the purpose of each option in the 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.
About Common ldapsearch Options explains about the common ldapsearch options in detail.
18.4.2.1 About 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
localhostis used. -
-p, --port port -
Specifies the directory server port. It should be an integer value between
1and65535, inclusive. If this is not provided, a default port of389is used. -
-b, --baseDN baseDN -
Specifies the base DN to use for the search operation. If a file containing multiple filters is provided using the
--filenameoption, 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--baseDNor-boption. -
one. Searches only the entry specified by the--baseDNor-boption and its immediate children. -
suborsubordinate. Searches the entire subtree whose base is the entry specified by the--baseDNor-boption. This is the default option when no--searchScopeoption 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 with the
--bindPasswordFileoption. 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:
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:
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. -
NameorOID 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,givenNamesorts the entries in ascending order first bysnand then bygivenName. Alternately, using-modifyTimestamp, the directory server sorts themodifyTimestampattributes with the most recent values first.
-
18.4.3 Understanding Search Criteria
Learn about the search criteria and the various filter options.
This section contains the following topics:
18.4.3.1 Overview of 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=comandou=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.
18.4.3.2 Search Filter Types and Operators Specifications
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 |
|
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: 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 |
|
Return entries containing attributes equal to a specified value. For example: Note: The |
|
Substring |
|
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.
|
|
Greater than or equal to |
|
Return entries containing attributes that are greater than or equal to the specified value. For example, |
|
Less than or equal to |
|
Return entries containing attributes that are less than or equal to the specified value. For example, |
|
Approximate |
|
Return entries containing the specified attribute with a value that is approximately equal to the value specified in the search filter. For example: |
|
Extensible match |
|
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 " |
18.4.3.3 Compound Search Filters Evaluation
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 |
|
All specified filters must be true for the statement to be true. For example, |
|
OR |
|
At least one specified filter must be true for the statement to be true. For example, |
|
NOT |
|
The specified filter must not be true for the statement to be true. For example, |
18.4.3.4 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)
18.4.3.5 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*Starwould be represented as"(cn=Five\\2aStar)". -
Backslash. Represent a backslash (
\) as\\5c. For example,c:\\filewould be represented as"(cn=c:\\5c\\5cfile)". -
Parentheses. Represent parentheses
()as\\28and\\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").
18.4.4 Using ldapsearch Command
You can use ldapsearch command to search for specific user attributes, perform search with different scopes, return attributes and entries. Learn about using ldapsearch command from the following topics.
This section contains the following topics that explain the use ofldapsearch command:
18.4.4.1 About ldapsearch Command Options
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
--searchScopeor-soption),ldapsearchassumes that the scope issubordinateorsub, which returns the full subtree of the base DN. -
If no attributes are specified, the command returns all attributes and their values.
-
If no
--bindDNand--bindPasswordare specified, the search uses an anonymous bind. -
If no
--hostnameis 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.
18.4.4.2 Returning 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 ...
18.4.4.3 Searching 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 975118.4.4.4 Searching 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
18.4.4.5 Performing 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
18.4.4.6 Performing 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
18.4.4.7 Performing 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
18.4.4.8 Returning 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 ...
18.4.4.9 Returning 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
18.4.4.10 Returning 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 ...
18.4.4.11 Searching 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 ...
18.4.4.12 Returning A Count of Matching Entries in the Directory
The ldapsearch command provides the --countEntries to return the total number of matching entries returned by the directory server. 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
18.4.4.13 Performing 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
18.4.4.14 Performing 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.
18.4.4.15 Limiting 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
18.4.5 Searching Data Using OUDSM
The Advanced Search tab of each server instance in OUDSM enables you to perform complex searches on directory data.
The following section describes about searching data using OUDSM:
To perform a complex LDAP search using the OUDSM advanced search facility, complete the following steps:
18.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.
This section contains the following topics:
For additional information, see About Searching Directory Data, Using a Properties File With Server Commands, and ldapsearch
18.5.1 Searching for Special Entries and Attributes
Learn how to search for operational attributes and Root DSE entry.
This section contains the following topics:
18.5.1.1 Searching 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 ...
18.5.1.2 Searching 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 ...
18.5.1.3 Searching 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";)
18.5.1.4 Searching 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' ) ...
18.5.1.5 Searching 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 through the administration connector. For more information, see Managing Administration Traffic to the Server.
To search the configuration entry using dsconfig in interactive mode, run the command as follows:
$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file
For more information about accessing the server configuration by using dsconfig, see Managing the Server Configuration Using dsconfig.
18.5.1.6 Searching the Monitoring Entry
The directory server monitor entry cn=monitor provides statistical information about the server performance, state, and version. You can access this information by using the ldapsearch command.
Although you can access cn=monitor using any configured LDAP connection handler, it is recommended that you use the administration connector for all access to administrative suffixes. Using the administration connector ensures that monitoring data is not polluted and that server administration takes precedence over user traffic. To use the administration connector, specify the administration port, and include the --useSSL option. For more information, see Managing Administration Traffic to the Server.
Run the ldapsearch command on the base DN cn=monitor.
$ ldapsearch -h localhost -p 4444 --useSSL -D "cn=Directory Manager" \ -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 ...
18.5.2 Searching Over SSL
You can search using client authentication, if you have configured the directory server to accept SSL connections by using a self-signed certificate or certificate.
The following topics describes procedures to show how to search the directory over SSL using various authentication mechanisms:
18.5.2.1 Searching 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=*)"
18.5.2.2 Searching 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=*)"
18.5.2.3 Searching Over SSL With No Trust Store
If no trust store is specified, then you are prompted about 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
18.5.2.4 Searching 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=*)"
18.5.2.5 Searching Using useStartTLS
The process for using useStartTLS 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
useStartTLSshould be used instead of SSL (that is, use the--useStartTLSoption instead of the--useSSLoption).
Run the ldapsearch command with the --useStartTLS option.
The following command searches the Root DSE using useStartTLS.
$ ldapsearch -h localhost -p 1389 --useStartTLS \ -b "" --searchScope base "(objectClass=*)"
18.5.2.6 Searching Using SASL With DIGEST-MD5 Client Authentication
The directory server supports several 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=*)"
18.5.2.7 Searching 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=*)"
18.5.2.8 Searching 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=*)"
18.5.3 Searching Using Controls
LDAP controls extend the functionality of LDAP commands, such as ldapsearch, to perform 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:
18.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.
Note:
Not all of these controls can be used with the ldapsearch command. For a description of the control that corresponds to each, and for more information about supported LDAP controls, see Supported LDAP Controls.
18.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:
-
baseDNThe search base is used to specify the precise entry from which to start the join search.
-
searchScopeThe search scope is used to specify distinct levels of join depth.
-
A search scope of
baseretrieves only direct relationships, for example, direct friends that are specified by thefriendattribute in the sample entry. -
A search scope of
onegoes one level deep, retrieving direct friends of direct friends of the sample entry. -
A search scope of
subtraverses the entire hierarchy chain no matter how many levels. -
A search scope of
subordinatehas the same effect assub, but does not include the base entry in search results.
-
-
filterThe 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.
18.5.3.3 Searching Using the Proximity Search Control
The Proximity Search Control provides base location data to the server in the search request, which 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))"
18.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
--controlor-Joption with the Account Usability Request Control OID:1.3.6.1.4.1.42.2.27.9.5.8with no value. -
Named constant. Use a named constant,
accountusableoraccountusability, with the--controlor-Joption, instead of using the Account Usability Request Control OID. For example, use-J accountusableor-J accountusabilitywith theldapsearchcommand.
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 ...
18.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 the following ways:
-
OID. Use the
--controlor-Joption with the Authorization Identity Request Control OID:2.16.840.1.113730.3.4.16with no value. -
Named constant. Use a named constant,
authzidorauthorizationidentitywith the-controlor-Joption instead of using the Authorization Identity Request Control OID. For example, use-J authzidor-J authorizationidentitywith theldapsearchcommand.
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
18.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 effectiverightsor 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 theauthzid. -
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-eoption 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, specify the virtual attributes aclRights and aclRightsInfo, which the server generates in response to the effective rights request. Thus, you should not use these attributes in search commands of any kind.
18.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
18.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
--subEntriesoption 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=*)"
18.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 the following ways:
-
OID. Use the
--controlor-Joption with the Manage DSA IT Control OID:2.16.840.1.113730.3.4.2with no value. -
Named constant. Use the named constant,
managedsaitwith the--controlor-Joption instead of the Manage DSA IT Control OID. For example, use-J managedsaitwith theldapsearchcommand.
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.
18.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
18.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 the following ways:
-
OID. Use the
--controlor-Joption with the Password Policy Control OID:1.3.6.1.4.1.42.2.27.8.5.1with no value. -
Named constant. Use the named constants,
pwpolicyorpasswordpolicywith the--controlor-Joption instead of the Password Policy Control OID. For example, use-J pwpolicyor-J passwordpolicywithldapsearch. -
Option. Use the
--usePasswordPolicyControloption.
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=*)"
18.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 ofadd,del,mod, ormoddn, or it can beallto 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 includingallchange types. -
changesonly— IfTrue, the client should only be notified of changes that occur to matching entries after the search is registered. IfFalse, 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— IfTrue, the server should include the Entry Change Notification Control in entries sent to the client as a result of changes. IfFalse, 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.
18.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
18.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.
18.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 except 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
18.5.3.16 Searching Using the Virtual List View Control
The following topics describe procedures to search using the Virtual List View control:
18.5.3.16.1 About 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
beforevalue is greater than or equal to the target offset, then thebeforevalue 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
indexandcontent_countare equal, the last entry is selected.If the
indexvalue is negative, the server rejects the request.If the
indexvalue is0, it is adjusted to1so that returned values are displayed.If the
indexvalue is greater than the total number of matching values, it is adjusted to one greater than the content count.The value of
indexcan 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 ofafterextends beyond the last entry, the value ofafteris 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.
18.5.3.16.2 Searching 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
18.5.3.16.3 Searching Using Virtual List View With a Specific Target
You can use the sort order (-S) option 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
jensenwithin 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
18.5.3.16.4 Searching 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
18.5.3.16.5 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 OUDSM, as follows:
- Connect to the directory server from OUDSM, as described in Connecting to the Server Using OUDSM.
- Select the Security tab.
- Under the Root menu, select Anonymous control access.
- In the Targets table on the right hand pane, select the Target Control field, and click Edit.
- From the Available Controls list, select Virtual List View Control (2.16.840.1.113730.3.4.9).
- Click the right arrow to move the VLV control to the Selected Controls list.
- Click OK.
- Click Apply to save your changes.
- Under the Root menu, select Authenticated users control access.
- In the Targets table on the right hand pane, select the Target Control field, and click Edit.
- From the Selected Controls list, select Virtual List View Control (2.16.840.1.113730.3.4.9).
- Click the left arrow to move the VLV control to the Available Controls list.
- Click OK.
- 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 About Default Global ACIs.
18.5.4 Searching in Verbose Mode and With a Properties File
You can understand how to search in verbose mode and by using a properties file. The verbose mode is convenient for debugging purposes whereas the properties file is convenient when working in different configuration environments.
This section contains the following topics:
18.5.4.1 Searching 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
...18.5.4.2 Searching Using a Properties File
The directory server supports the use of a properties file that holds default argument values used with the ldapsearch command. The properties file is convenient when working in different configuration environments, especially in scripted or embedded applications. For more information, see Using a Properties File With Server Commands.
18.5.5 Searching Internationalized Entries
You can search for Internationalized entries by using collation rules, by understanding search examples and by using supported collation rules.
This section contains the following topics:
18.5.5.1 Using Collation Rules to Search Internationalized Entries
The following topics describe how to use collation rules to search internationalized entries:
18.5.5.1.1 About Collation Rules
Oracle Unified Directory supports collation rules that match entries and can be used with the 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
-
Locale OID
-
Locale character suffix (such as
ar,en, orfr-CA).See Supported Collation Rules for a list of supported locales, their OIDs, and tags.
-
-
matchingRule can specified as either a numeric suffix or a character suffix appended to the locale, as listed in Table 18-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 18-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.
18.5.5.1.2 Examples of Using Collation Rules
The 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"
18.5.5.2 Understanding Search Examples
This section describes the various searches available:
-
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 acnvalue ofsanchez:$ 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"
-
-
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 adepartmentnumbervalue ofabc119:$ 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"
-
-
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 adepartmentnumbervalue ofabc119:$ 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"
-
-
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 adepartmentnumbervalue ofabc119$ 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"
-
-
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
departmentnumbervalue ofabc119.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"
-
-
Substring Search
The following search uses a filter with the
en(en-US) locale and performs a substring search that returns an entry with ansnvalue 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"
-
18.5.5.3 Supported Collation Rules
The following table lists the internationalization locales supported by Oracle Unified Directory, alphabetized by character suffix.
Table 18-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 |
18.5.6 Sorting Multi-Valued Attributes in a Search Response
Multi-valued attributes in an entry are usually returned in the order they were added or modified. To return them in sorted order, set the sort-multivalued-attributes configuration parameter of the DB Local Backend Workflow Element to true. By default, this value is false.
This content applies only to OUD Bundle Patch 12.2.1.4.240319 and later releases.
Note:
You should enable this configuration only for specific user backends where sorting of multi-valued attributes is highly desirable, as it may have an impact on performance. Only User Attributes with an ordering matching rule are considered for sorting. Sorting excludes DNs, operational attributes, binary attributes, objectclass attributes, and groups. This feature is not supported by OUD Proxy.To enable sorting of multi-valued attributes for a specific backend, set the sort-multivalued-attributes parameter to true using the dsconfig command as follows:
dsconfig set-workflow-element-prop \
--element-name userRoot \
--set sort-multivalued-attributes:true \
--hostname hostname \
--port admin-port \
--portProtocol LDAP \
--trustStorePath INSTALL_PATH/asinst_1/OUD/config/admin-truststore \
--bindDN cn=Directory\ Manager \
--bindPasswordFile ****** \
--no-promptConsider the following scenario in which a user has multiple uid and mail values, without sorting enabled:
dn: uid=user1,ou=People,dc=example,dc=com
mail: abc@mycompany
mail: zxy@mycompany
mail: mno@mycompany
sn: user1
cn: user1
objectClass: top
objectClass: organizationalPerson
objectClass: person
objectClass: inetorgperson
uid: user1@mycompany.com
uid: user1When you enable the sort-multivalued-attributes configuration parameter and then run ldapsearch, it will return the uid and mail values sorted according to the ordering matching rule.
./ldapsearch -h localhost -p 1389 -D "cn=Directory Manager" -j pwd-file -b "dc=example,dc=com" -s sub "(uid=user1)"
dn: uid=user1,ou=People,dc=example,dc=com
mail: abc@mycompany.com
mail: mno@mycompany.com
mail: zxy@mycompany.com
sn: user1
cn: user1
objectClass: top
objectClass: organizationalPerson
objectClass: person
objectClass: inetorgperson
uid: user1
uid: user1@mycompany.comNote:
In the preceding example, only multi-valued user attributes, such asmail and uid (with an ordering matching rule) are sorted.
18.6 Handling 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, ensure that you understand the following concepts:
-
The privilege and access control mechanisms.
For information about setting privileges, Controlling Access To Data.
-
The structure of your directory server.
-
The schema of your directory server.
This section contains the following topics:
18.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
--defaultAddoption 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
ldapmodifychanges 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:
18.6.1.1 Creating 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.
18.6.1.2 Adding an Entry Using the --defaultAdd Option With ldapmodify
To add an entry using the --defaultAdd option, run the ldapmodify command as follows:
18.6.2 Adding Attributes
To add attributes to an entry, use the changetype:modify statement, as shown in examples in the following sections. You can combine multiple commands within a file by separating each command with a dash ("-").
The LDIF changetype:add statement adds an entry to the directory.
This section describes how to manage an entry, and contains the following topics:
18.6.2.2 Adding 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 Controlling Access To Data and ACI Syntax.
The following example allows a user to modify her own directory attributes.
18.6.2.3 Adding 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.
18.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 ldapmodify
18.6.3.1 Modifying 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
18.6.3.2 Modifying 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
18.6.3.3 Deleting 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.
18.6.3.4 Changing 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.
18.6.3.5 Moving 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.
18.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.
The following topics describe how to delete directory entries:
For more information, see ldapdelete.
18.6.4.1 Deleting an Entry Using 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
18.6.4.2 Deleting an Entry Using 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
18.7 Indexing Directory Data
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 Changing 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
debugsearchindexoperational attribute. This attribute provides the indexes used in the search, the number of candidate entries from each index, and the final indexed status. Include thedebugsearchindexattribute in yourldapsearchcommand, as follows:$ ldapsearch -h localhost -p 1389 -b "dc=example,dc=com" "(objectClass=*)" debugsearchindex
The following sections describe how to index attributes using the dsconfig command-line tool:
18.7.1 Configuring Indexes on the Local DB Back End
Understand about the supported index types on the local DB back end and create new local DB index. There are examples included in this section to create and add indexes.
This section contains the following topics:
18.7.1.1 Supported Index Types 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 Searching Internationalized Entries, and Understanding Relative Time Matching Rules, and Understanding 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)
18.7.1.2 Creating a New Local DB Index
To create a new local DB index, perform the following steps:
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 rebuild-index.
-
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
-
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 -
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
-
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
-
Rebuild the index.
-
Either stop the server, reb evenuild the index, then restart the server.
$ stop-ds $ rebuild-index --baseDN baseDN --index attribute $ start-ds
-
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:
Even for an online re-index operation, the back end 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 Understanding Referrals in a Replicated Topology.
-
18.7.1.3 Examples on Creating and Adding Indexes
The following examples show how to create a new Equality Index and how to add a Substring Index:
18.7.1.3.1 Creating a New Equality Index
The example in this section 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
18.7.1.3.2 Adding a Substring Index
The example in this section adds a substring index to the index created in the earlier 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
18.7.2 Configuring VLV Indexes
Understand about VLV index configuration and learn to create new VLV index with the help of examples.
The following topics describe about configuring VLV Indexes:
18.7.2.1 About VLV Indexes Configuration
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 rebuild-index.
Note:
Access to the VLV request control is allowed only to authenticated users, 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 Allowing Anonymous Access to the Virtual List View Control.
18.7.2.2 Creating a New VLV Index
To create a new VLV Index, follow these steps:
-
Use
dsconfigto 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-namespecifies a unique index name, which cannot be altered after the VLV index is created. -
sort-orderspecifies the names of the attributes by which the entries are sorted and their order of precedence, from highest to lowest. -
scopespecifies the LDAP scope of the query being indexed and can be one ofbase-object,single-level,subordinate-subtree, orwhole-subtree. -
base-dnspecifies the base DN used in the search query being indexed. -
filterspecifies the LDAP filter used in the query being indexed and can be any valid LDAP filter.
-
-
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 -
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
-
Rebuild the index.
-
Either stop the server, rebuild the index, then restart the server.
$ stop-ds $ rebuild-index --baseDN baseDN --index vlv.name $ start-ds
-
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
-
18.7.2.3 Example of Creating 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
18.8 Reducing Stored Data Size
The directory server provides two mechanisms for reducing the size of stored data. These mechanisms are Compact encoding and Entry compression.
The following topics enables you to understand about reducing stored data size using one of the above mentioned mechanisms and about saving database space using tokens for attribute values:
18.8.1 About Stored Data Size Reduction
You can reduce the size of the stored data by enabling compact encoding and entry compression.
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.
18.8.2 Enabling or Disabling 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
18.8.3 Enabling or Disabling 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
18.8.4 Saving Database Space Using Tokens for Attribute Values
Oracle Unified Directory server can compact attributes that have a small number of values and are repeated a large number of times in many entries. The server references these attributes and their values using tokens. The server stores the tokens and their values once in a separate table and then stores only the tokens in the database entries. This optimization saves space when attribute values would otherwise be repeated across many database entries. It can also improve cache efficiency when the entire database does not otherwise fit in memory.
For example, consider a telco with a mobile-phone user attribute that stores the names of mobile phones and models used by all customers (users). Every user entry in the telco's database has a mobile-phone attribute value (if not several values). The set of values the mobile-phone can acquire is limited, and the most popular mobile-phone values are repeated thousands (or even millions) of times across the users in the database.
However, using this optimization, Oracle Unified Directory server uses tokens to store the mobile-phone attribute values. The server stores the tokens with the attribute values only once in a separate table and then stores the tokens in the database entries.
To configure a list of attributes that should be compacted using tokens, set the multivalued ds-cfg-compact-attribute-values-using-tokens property in the DB Local Backend workflow element. For example:
$ dsconfig set-workflow-element-prop \
--element-name userRoot \
--set compact-attribute-values-using-tokens:mobile-phone \
--hostname host --port admim-port \
--trustStorePath INSTALL_PATH/asinst_1/OUD/config/admin-truststore \
--bindDN "cn=Directory Manager" \
--bindPasswordFile ****** --no-prompt
After you set this property, changes take effect only for writes that occur after the change. Existing data is not changed retroactively.
To compact existing data for an attribute that preceded the configuration using the ds-cfg-compact-attribute-values-using-tokens property, you can export and then re-import that data (although you should consider the cost of this operation against the performance you will gain by using a token for the attribute).
After you compact attributes using the ds-cfg-compact-attribute-values-using-tokens property, the dbtest command displays the total number of tokens that have been created in the database to store the values. For example:
$ dbtest list-database-containers -n userRoot Database Name Database Type JE Database Name Entry Count --------------------------------------------------------------------------------- Schema maps compressed_object_classes 8 compressed_attributes 32 compressed_values 14 ...
The compressed_values line shows that in this deployment, 14 values have been encoded as tokens and can be reused for the encoding of a large number of values. You can use dbtest to check that this feature has been configured correctly and that the number of tokens does not become too large.
18.8.5 Retrieving Multi-Valued Attributes in the Order of Creation
You can store and retrieve multi-valued attributes in the order in which they are created.
You can store multiple values for an attribute. However, because of the compact encoding feature, whenever multi-valued attributes are queried, there is no guarantee that multiple values of the attribute would be returned in the order in which they are created. While retrieving multiple attribute values, if you want the values to be returned in the same order in which they are created, then you should disable compact encoding. Refer to Enabling or Disabling Compact Encoding on how to disable compact encoding.
18.9 Configuring Selective Attribute Caching
You can use selective attribute caching to reduce memory requirements for larger deployments and improve performance when working with large entries.
The following topics describe how you can use selective attribute caching:
18.9.1 Understanding Selective Attribute Caching
Oracle Unified Directory performs I/O and database caching on the entire LDAP entry for read or write operations. However, most read and write operations only target specific attributes and rarely access other attributes being stored in the database. For larger deployments and large entries, this behavior can impact memory and performance.
Selective attribute caching enables you to better manage these operations by differentiating the attributes in an LDAP entry, based on how often they are accessed:
-
Regular attributes: Attributes that are frequently accessed. For example, office phone numbers, user IDs, or email addresses.
-
Cold attributes: Attributes that are rarely accessed. For example, pager numbers, home phone numbers, or binary data such as jpeg photos.
You can configure cold attributes that work only on operational demand or that fit certain use cases.
Note:
You must have a very good understanding of your applications to effectively designate cold attributes.
Be aware that regular and cold attributes may differ for various LDAP application workloads. For example, if your deployment rarely accesses employee pager numbers or home phone numbers, you could configure those attributes as cold attributes. However, another customer's deployment might frequently access employee pager numbers and phone numbers, so in their case it would be inappropriate to configure those attributes as cold.
Note:
Although there are no restrictions on which attributes you can configure as cold, designating as cold any attributes used by various core server features (such as the following) could negate the benefit of selective attribute caching and cause unexpected behavior in some core server features.
-
Groups (definitions could be based on an entry attribute)
-
Virtual attributes (they could depend on other entry attributes)
-
Password policy attributes (they read and change policy attributes)
-
User Account Notification
-
Assertion Control
-
Persistent Search
Designating these core server attributes as cold is not supported.
After specifying cold attributes, the server then splits the LDAP entry store into two databases, id2entry and id2entry-cold. The server stores regular attributes in the regular id2entry database and cold attributes in the id2entry-cold database. Using two databases reduces I/O for operations on the partial entry data and reduces the memory footprint for the java heap, database cache, and file system (FS) cache.
18.9.2 Example of Using Selective Attribute Caching
Learn more about using selective attribute caching.
Consider a scenario where your LDAP entry store contains the following attributes:
dn: uid=user.0,ou=People,dc=example,dc=com objectClass: top objectClass: person objectClass: organizationalperson objectClass: inetorgperson givenName: Aaccf sn: Amar cn: Aaccf Amar employeeNumber: 0 uid: user.0 mail: user.0@example.com userPassword: password telephoneNumber: +1 024 705 1954 homePhone: +1 021 391 6930 mobile: +1 195 481 7233 initials: AFA street: 77569 Lake Street l: Elmira st: ND postalCode: 31858 postalAddress: Aaccf Amar$77569 Lake Street$Elmira, ND 31858 description: This is the description for Aaccf Amar. pager: +1 575 339 1600
You might decide to configure and store the attributes as follows:
| id2entry Database | id2entry-cold Database |
|---|---|
dn: uid=user.0,ou=People,dc=example,dc=com objectClass: top objectClass: person objectClass: organizationalperson objectClass: inetorgperson givenName: Aaccf sn: Amar cn: Aaccf Amar employeeNumber: 0 uid: user.0 mail: user.0@example.com userPassword: password telephoneNumber: +1 024 705 1954 homePhone: +1 021 391 6930 mobile: +1 195 481 7233 |
initials: AFA street: 77569 Lake Street l: Elmira st: ND postalCode: 31858 postalAddress: Aaccf Amar$77569 Lake Street$Elmira, ND 31858 description: This is the description for Aaccf Amar. pager: +1 575 339 1600 |
Oracle Unified Directory caches attributes from the id2entry-cold database only if they are accessed and caching priority is given to regular attributes over cold attributes. Consequently, operations that do not target cold attributes are more likely to get into the cache.
Also, if write operations are not targeting any cold attributes, then those operations do not have to rewrite the id2entry-cold database, which makes them faster particularly when larger attributes are declared as cold attributes.
Note:
Selective attribute caching might not improve search performance for databases that completely fit in the DB cache. However, selective attribute caching allows you to increase cache hits for the most commonly used attributes in the cases where the database does not completely fit in memory.
18.9.3 Configuring Attribute-Level Caching
The attribute-level caching is related to the DB cache, hence the configuration stays in the back-end configuration entry.
To configure cold attributes in the DB Local Backend Workflow Element, use the multi-valued ds-cfg-cold-attribute property to specify the names of cold attributes for your database.
Note:
You can specify any attributes as cold attributes, but you should avoid specifying any attributes that your server relies on for processing your operations; such as ACI, password policy, and other previously mentioned core server features.
For example,
dsconfig set-workflow-element-prop \
--element-name userRoot \
--add cold-attribute:description \
--add cold-attribute:initials \
--add cold-attribute:l \
--add cold-attribute:pager \
--add cold-attribute:postalAddress \
--add cold-attribute:postalCode \
--add cold-attribute:st \
--add cold-attribute:street \
After executing this dsconfig command, the userRoot workflow element properties (as displayed by dsconfig) will look like the following:
Property : Value(s) -----------------------------:------------------------------- 1) base-dn : "dc=example,dc=com" 2) cold-attribute : description, initials, l, pager, postalAddress, postalCode,st, street ...
After executing the dsconfig command, the userRoot workflow element entry under cn=config will look like the following:
dn : cn=userRoot,cn=Workflow Elements,cn=config objectClass : ds-cfg-local-backend-workflow-element objectClass : ds-cfg-workflow-element objectClass : ds-cfg-db-local-backend-workflow-element objectClass : top ... ds-cfg-cold-attribute : description ds-cfg-cold-attribute : pager ds-cfg-cold-attribute : postalCode ds-cfg-cold-attribute : postalAddress ds-cfg-cold-attribute : st ds-cfg-cold-attribute : l ds-cfg-cold-attribute : street ds-cfg-cold-attribute : initials
Note:
When you define cold attributes, the server does not move any existing data into the cold database. The server starts storing cold attributes in the cold database only when you add a new entry or modify an existing entry.
Ideally, do a fresh import of your data after defining cold attributes.
Restrictions
When using cold attributes, the following restrictions apply:
-
As previously mentioned, designating as cold any attributes that are used by the core server features (such as access control instructions (ACIs) or virtual ACIs, password policy attributes, groups, etc.) could negate the benefit of selective attribute caching and could lead to unexpected behavior of some core server features. Designating these attributes as cold is not supported.
-
Oracle Unified Directory cannot cache entries with cold attributes in the entry cache. Attribute-level caching is useful when the deployment is constrained by memory and the entry cache should not be used because it is very costly in memory.
18.9.4 Monitoring Cold Attributes Usage
Oracle Unified Directory provides a Cold Attributes Usage monitor that keeps track of each time the server accesses a cold attribute. This monitor is disabled by default to prevent a performance hit, but you can enable it for diagnostic purposes by using the ds-cfg-monitor-cold-attributes backend configuration property.
After configuring cold attributes, you can enable the monitor and run the server using specific application workloads. The monitor records which cold attributes were accessed by the server and how many times they were accessed. You can use this data to refine your cold attributes configuration. For example, if monitoring shows that a cold attribute has been accessed a large number of times, then you may want to reconsider reconfiguring it as a regular attribute.
In the following sample output, you can see that the description attribute was accessed nine times and that all of the other cold attributes were accessed three times.
For Example, consider the following sample monitoring output:
dn: cn=dc_example_dc_com Cold Attributes Usage,cn=monitor objectClass: top objectClass: ds-monitor-entry objectClass: extensibleObject cn: dc_example_dc_com Cold Attributes Usage l: 3 st: 3 initials: 3 postalCode: 3 pager: 3 description: 9 postalAddress: 3 street: 3
18.10 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:
18.10.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.
You can configure the unique attribute plug-in 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 Configuring Plug-Ins Using 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.
18.10.2 Configuring the Unique Attribute Plug-In Using dsconfig
Learn to configure the attribute value uniqueness using dsconfig command.
This section contains the following topics:
Note:
See Using a Password File With Server Commands to learn how to create a password file, for examplepwd-file, used in the preceding procedures.
18.10.2.1 Ensuring Uniqueness of the uid Attribute Value
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.
18.10.2.2 Ensuring Uniqueness of Any Other Attribute Value
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.
To ensure that the values of more than one attribute are unique, create and enable multiple instances of the unique attribute plug-in.
18.10.3 Ensuring Unique Attribute Values in a Replication Environment
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. It is recommended that you direct all the updates to a single server which then replicates.
18.11 Configuring Virtual Attributes
Virtual attributes are attributes whose values do not exist in persistent storage but are dynamically generated.
You can configure virtual attributes by using the dsconfig command or using the OUDSM graphical user interface, as described in the following sections:
18.11.1 Supported Virtual Attributes
Understand about the supported virtual attributes from the following tabular column.
Oracle Unified Directory supports the following virtual attribute types:
Table 18-3 Supported Virtual Attributes
| Virtual Attribute Name | Description |
|---|---|
|
|
Generates a virtual attribute that specifies all collective attribute subentries that affect the entry. |
|
|
Generates the entryDN operational attribute in directory entries, which contains a normalized form of the entry's DN. |
|
|
Ensures that all entries contained in private back ends have values for the entryUUID operational attribute. |
|
|
Specifies the DIT structure rule with the schema definitions in effect for the entry. |
|
|
Indicates whether the entry has any subordinate entries. |
|
|
Contains the DNs of the groups in which the user is a member. |
|
|
Generates a member or |
|
|
Generates a unique identifier that is assigned to each entry in the directory server to resolve naming conflicts while migrating legacy applications using Oracle Directory Server Enterprise Edition as an LDAP database to Oracle Unified Directory. |
|
|
Specifies the number of immediate child entries that exist below the entry. |
|
|
Creates an orclguid virtual attribute. |
|
|
Indicates the exact time after which the user's password expires. You can issue a |
|
|
Points to the Password Policy subentry in effect for the entry. |
|
|
Specifies location based proximity in meters. |
|
|
Specifies the structural object class with the schema definitions in effect for the entry. |
|
|
Specifies the location of the subschemaSubentry with the schema definitions in effect for the entry. |
|
|
Creates virtual attributes with user-defined values in entries that match the criteria defined in the plug-in's configuration. |
18.11.2 Configuring Virtual Attributes Using dsconfig
The easiest way to configure virtual attributes using dsconfig is 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.
The following topics describe how to configure and manage virtual attributes using the dsconfig command:
-
Viewing the Configuration of a Virtual Attribute Using dsconfig
-
Changing the Configuration of a Virtual Attribute Using dsconfig
For more information about using dsconfig, see Managing the Server Configuration Using dsconfig.
18.11.2.1 Listing the Existing Virtual Attributes Using dsconfig
The directory server provides several virtual attribute rules by default.
To view a list of all configured virtual attribute rules, run the following dsconfig command:
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n list-virtual-attributes
The following example shows a sample output of the above command which is a list of all configured virtual attribute rules.
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 Expiration Time : password-expiration-time : true : passwordexpirationtime 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 following information (from left to right) is included in the above listed sample output of the command:
-
Virtual Attribute. Displays the name of the virtual attribute, which is usually descriptive of what it does. -
Type. Displays the type of virtual attribute. You can define more than one virtual attribute of a specific type. -
enabled. Indicates whether the virtual attribute is enabled or disabled. Disabled virtual attributes remain in the server configuration, but their values are never generated. -
attribute-type. Displays the type of attribute for which the virtual values are generated.
18.11.2.2 Creating a New Virtual Attribute Using dsconfig
To create new virtual attributes, use the create-virtual-attribute subcommand.
For example, you could run the following dsconfig command to create and enable 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):
$ 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))"
18.11.2.3 Enabling or Disabling a Virtual Attribute Using dsconfig
To enable a virtual attribute, set the enabled property to true. To disable a virtual attribute, set the enabled property to false.
For example, run the following command to disable the virtual attribute created in the previous example:
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -j pwd-file -n \ set-virtual-attribute-prop --name="Sydney Fax Number" --set enabled:false
18.11.2.4 Viewing the Configuration of a Virtual Attribute Using dsconfig
To display the configuration of a virtual attribute, use the get-*-prop subcommand.
For example, run the following command to view a list of properties for the virtual attribute created in Creating Virtual Attributes Using OUDSM:
$ 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
18.11.2.5 Changing the Configuration of a Virtual Attribute Using dsconfig
To change the configuration of a virtual attribute, use the set-*-prop subcommand.
For example, you could use this command to change the behavior of a virtual attribute when a conflict occurs. By default, the value of a real attribute overwrites the virtual attribute value. Running the following command, merges the real attribute value and the virtual attribute value.
$ 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
18.11.3 Configuring Virtual Attributes Using OUDSM
You can manage virtual attributes using OUDSM.
The following topics describe how to display and create virtual attributes by using the Configuration tab in OUDSM:
18.11.3.1 Listing Existing Virtual Attributes Using OUDSM
To view a list of existing virtual attributes with OUDSM:
- Expand the attributes in the Virtual Attributes node to display all the existing virtual attributes.
18.11.3.3 Viewing the Configuration of a Virtual Attribute Using OUDSM
To view the configuration settings of a virtual attribute:
18.11.3.4 Changing the Configuration of a Virtual Attribute Using OUDSM
To change the configuration settings of a virtual attribute:
18.11.3.5 Enabling or Disabling a Virtual Attribute Using OUDSM
You can enable or disable a virtual attribute by opening the attribute's configuration page (as described in Changing the Configuration of a Virtual Attribute Using OUDSM) and using the Enabled box:
-
To enable the virtual attribute, check the box.
-
To disable the virtual attribute, clear the box.
18.12 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.
This section includes the following topics:
18.12.1 About LDAP Subentries
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 Using Collective Attributes and Defining 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=systemand the base isou=users, the subtree begins atou=users,ou=system. The base can be any length of name components, including "". In this case, the subtree begins at the administrative point,ou=systemin the previous example. -
Chop
The
chopBeforeandchopAfterparameters are names relative to the base of the subtree, that specify whether an entry and its descendants should be excluded from the collection.Theminimumparameter describes the minimum number of name components between the base and the target entry required to include entries within the selection. Themaximumparameter 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
objectClasscharacteristics of the entries.For example, you can define a subtree to cover a region of an administrative area but include only
inetOrgPersonswithin 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.
18.12.2 Relative Subtrees
Relative subtrees function like standard LDAP subtrees, except 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)" }18.13 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.
The following sections describe the collective attribute implementation in Oracle Unified Directory and explains how to configure collective attributes:
18.13.1 Extensions to the Collective Attributes Standard
The Oracle Unified Directory implementation of collective attributes is based on RFC 3671 and RFC 3672 with a few specific extensions. These extensions make Oracle Unified Directory collective attributes more transparent for LDAP client applications.
See RFC 3671 (http://www.ietf.org/rfc/rfc3671.txt) and RFC 3672 (http://www.ietf.org/rfc/rfc3672.txt). Oracle Unified Directory collective attributes are described in the following sections:
18.13.1.1 About Collective Attributes Naming
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 as needed.
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.
18.13.1.2 Example of Using Collective Attributes Naming and Conflict Resolution
Collective attributes can be named in various ways. Consequently, 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-real18.13.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: excludeAllCollectiveAttributes18.13.2 Configuring Collective Attributes
Learn about configuring and managing collective attributes.
This section contains the following topics:
18.13.2.1 Handling Collective Attributes Configuration
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).
18.13.2.2 Creating a New Collective Attribute
To enable you to create a new collection attribute, follow these steps:
18.13.2.3 Deleting a Collective Attribute
You can delete a collective attribute by using either the ldapdelete command or 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
18.13.2.4 Listing 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
18.13.3 Overview of 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.
This section contains the following topics about inherited collective attributes:
18.13.3.1 About Inherited Collective Attributes
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
18.13.3.2 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
18.14 Configuring Referrals
A referral is a pointer to a remote suffix or entry that is returned to a client instead of a result.
The following topics describe how to configure referrals:
18.14.1 Overview of Configuring Referrals
When a server cannot 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. Understand about the Referrals from this topic.
The server returns a list of referrals in the following cases:
-
Writability is disabled or set to
internal-onlyon the server or on the Local Backend workflow element. For more information, see 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 back end in maintenance mode, set the
maintenanceproperty of the Local Backend workflow element totrue. -
The back end is unavailable for some reason, for example a data import or re-index is in process.
-
The client request specifically targets a smart referral. For more information, see Managing 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 Understanding 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:
-
For replicated servers, use the replication service to propagate the list. For more information, see Understanding Referrals in a Replicated Topology.
-
Create the list manually by setting the
ds-cfg-referrals-urlproperty of the DB Local Backend workflow element. For more information, see Configuring the Referral List Manually.
18.14.2 Understanding 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 back end. 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.
18.14.3 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
18.14.4 Managing 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.
This section contains the following topics:
18.14.4.1 Configuring 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.
18.14.4.2 Modifying 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.
18.14.4.3 Deleting 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.
18.14.5 Understanding LDAP URLs
RFC 4516 describes the format of an LDAP URL, which is summarized as follows:
ldap[s]://hostname:port/base_dn?attributes?scope?filter
An LDAP URL includes the following components:
-
ldaps[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).
The following is a list of example LDAP URLs:
-
The following LDAP URL specifies a search for all entries that have the surname
Jensenat any level underdc=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
cnandtelephoneNumberattributes at any level underdc=example,dc=com. The server contacts the remote server at port2389. Because no search filter is specified, the server uses the default filter(objectclass=*).ldap://example.com:2389/dc=example,dc=com?cn,telephoneNumber?sub
18.15 Retaining Case Sensitivity in Attributes During Upgrade
You can retain case sensitive values after an upgrade from 11.1.2.2.0 to 11.1.2.3.0 by setting the value of compact-encoding flag to false right before the upgrade.
dn (Domain Name) attribute may contain cn (Common Name), uid (Unique Identity) or any other attribute as part of dn. In the example below, value of cn and dn are equal in letter case. If the specified attributes are equal in value and letter case, there will be no loss of case sensitivity after upgrade from 11.1.2.2.0 to 11.1.2.3.0.dn: cn=john.doe1,ou=people,dc=example,dc=com
givenName: John
mail: john.doe1@example.com
userPassword: password
cn: john.doe1The following table explains the default behavior of case sensitive data with respect to the compact-encoding flag value.
| Compact Encoding Flag Set to False | Compact Encoding Flag Set to True |
|
In 11.1.2.2.0, with the If you try to create a user with the above details, the created user entry will have the same |
In 11.1.2.3.0, with the flag set to true by default, If you have not provided value for If you try to create a user with the above details, OUD will create an entry with |
In 11.1.2.2.0, you can provide a value for cn or uid that differs from dn and Oracle Unified Directory will consider the value provided irrespective of value present in dn. This is the default behavior when compact-encoding feature is not present.
dn: uid=john.doe1,ou=people,dc=example,dc=com
givenName: John
mail: john.doe1@example.com
userPassword: password
uid: John.Doe1If the attribute is present as part of dn, then the case sensitive values are retained. For example, if dn contains uid attribute and if uid value is not provided explicitly, then the uid value specified in dn will be considered.
In 11.1.2.3.0, the attributes are expected to be equal in value and letter case; hence Oracle Unified Directory considers value present in dn when the entry is created, as it is the default behavior in 11.1.2.3.0. By default, the compact-encoding flag is set to true in 11.1.2.3.0. During upgrade, case sensitivity of the specified cn or uid attribute will be lost, especially with static groups, due to the way these groups are stored in 11.1.2.3.0. This is the default behavior when compact-encoding flag is set to true.
To retain the case sensitive values, you need to explicitly set the value of the compact-encoding flag to false right before upgrade. For more information, see Enabling or Disabling Compact Encoding.
If the compact-encoding flag is not set to false, then after upgrade, OUD will only consider the cn or uid attribute value specified in dn.
Note:
You can also retain case sensitivity in attributes when you upgrade from version 11.1.2.2.0 to 12.2.1.3.0 version.18.16 Managing Data Using OUDSM
The Data Browser tab of each server instance in OUDSM enables you to perform a basic search on the directory data, and to add, delete, and modify entries.
OUDSM includes an "auto-suggest" facility that enables you to enter a subset of characters in any of the data fields. OUDSM then returns all entries that match that subset of characters. The auto-suggest feature returns only those entries that have already been cached by OUDSM.
The following sections describe how to manage data with OUDSM:
18.16.1 Viewing Entries
You can view the entries and restrict entries to a specific entry set from the Entry pane in the Data Browser tab.
To view directory entries by using the OUDSM data browser, follow these steps:
See also Viewing the Attributes of an Entry.
18.16.2 Viewing the Attributes of an Entry
You can view the attributes of an entry and learn about the different types of entries from this topic.
To view the attributes of an entry, follow these steps:
18.16.3 Searching 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, follow these steps:
- Connect to the directory server from OUDSM, as described in Connecting to the Server Using OUDSM.
- Select the Data Browser tab.
- Select the appropriate network group from the Network Group list.
- Select the Search tab on the left hand pane.
- From the For list, select whether you are searching for a user entry or a group entry.
- 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, orSmi, orJohn, and so forth. - When the entry is displayed in the left pane, double-click the entry to display its details in the right pane.
18.16.4 Adding an Entry
To add or delete entries with Oracle Unified Directory Services Manager, you must have write access to the parent entry and you must know the DN to use for the new entry.
18.16.5 Adding an Entry Based on an Existing Entry
You can add an entry based on the existing entry by using the Create like entry option.
To add an entry that is based on an existing entry by using the OUDSM data browser, follow these steps:
18.16.6 Deleting an Entry
You can delete an entry from the OUDSM data browser by using Delete option.
To delete an entry by using the OUDSM data browser, follow these steps:
- Display the existing entries as described in Viewing Entries.
- Select the entry that you want to delete and click the Delete icon.
- On the Delete Entry dialog, verify that you are deleting the correct entry and click OK.
18.16.7 Deleting an Entry and Its Subtree
You can delete an entry and all entries beneath it in the directory tree by using the Delete Entry and its Subtree option.
To delete an entry and its subtree, follow these steps:
- Display the existing entries as described in Viewing Entries.
- Select the entry that you want to delete and click the Delete Entry and its Subtree icon.
- On the Delete Subtree dialog, verify that you are deleting the correct entry and click OK.
18.16.8 Modifying an Entry's RDN
You can modify the RDN of an entry by using the OUDSM data browser.
Perform the following steps:
- Display the existing entries as described in Viewing Entries.
- Select the entry whose RDN you want to modify on which you want to base the new entry and click the Edit RDN icon.
- Provide a new RDN in the New RDN value field.
- 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.
- Optionally, click the Refresh subtree entries icon to verify the RDN change.
18.16.9 Importing Data From an LDIF File
You can import data from an LDIF file using the Import LDIF option in the OUDSM Data Browser.
To import entries from an LDIF file, follow these steps:
- Connect to the directory server from OUDSM, as described in Connecting to the Server Using OUDSM.
- Select the Data Browser tab.
- Select the appropriate network group from the Network Group list.
- Click the Import LDIF icon.
- On the Import Entry(ies) dialog, click Choose File.
- Locate the LDIF file on your system and click OK.
- On the LDIF Import Progress dialog, monitor the progress of the import and click OK when the export has completed.
- The Data Browser tree refreshes to show the new entries.