7
Managing Directory Entries

This chapter explains how to view, add, and modify entries.

This chapter contains these topics:

• Managing Entries by Using Oracle Directory Manager

• Managing Entries by Using Command Line Tools

• Managing Entries by Using Bulk Tools

• Managing Entries with Attribute Options

• Managing Knowledge References (Referrals)

  See Also: Chapter 2, "Concepts and Architecture" for an overview of directory entries, directory information trees, distinguished names, and relative distinguished names

Managing Entries by Using Oracle Directory Manager

This section contains these topics:

• Searching for Entries by Using Oracle Directory Manager

• Searching for Audit Log Entries by Using Oracle Directory Manager

• Viewing Attributes by Using Oracle Directory Manager

• Adding Entries by Using Oracle Directory Manager

• Modifying Entries by Using Oracle Directory Manager

Searching for Entries by Using Oracle Directory Manager

You can display all entries by using the navigator pane, or search for one or more specific entries by using the Oracle Directory Manager search feature.

To display an entry, in the navigator pane, expand Entry Management to display its subtree.

The root of the tree is listed first, then the second level, and so forth, moving from left to right. The subtree lists the RDN of each entry in hierarchical order. To see the lower level entries within any subtree, click the plus sign (+) to the left of the parent entry.

To search for a directory entry:

1. In the navigator pane, expand Oracle Internet Directory Servers > directory_server_instance, and select Entry Management. The Search fields appear in the right pane.

2. In the Root of the Search field, enter the DN of the root of your search.

   For example, suppose you want to search for an employee who works in the Manufacturing division in the IMC organization in the Americas. The DN of the root of your search would be:

   ou=Manufacturing,ou=Americas,o=IMC,c=US
   
   
   

   You would therefore type that DN in the Root of the Search text box.

   You can also select the root of your search by browsing the directory information tree (DIT). To do this:

   1. Click Browse to the right of the Root of the Search field. The Select Distinguished Name (DN) Path: Tree View dialog box appears.

   2. Click the plus sign (+) next to Tree View to display its entries.

   3. Continue navigating to the entry that represents the level you want for the root of your search.

   4. Select that entry, then click OK. The DN for the root of your search appears in the Root of the Search text box in the right pane.

3. In the Max Results (entries) box, type the maximum number of entries you want your search to retrieve. The default is 200.

4. In the Max Search Time (seconds) box, type the maximum number of seconds for the duration of your search. The value you enter here must be at least that of the default, namely, 25.

5. In the Search Depth list, select the level to which you want to search.

   The options are:

   • Base: Retrieves a particular directory entry. Along with this search depth, you use the Search criteria bar to select the attribute objectClass and the filter Present.

   • One Level: Limits your search to all entries beginning one level down from the root of your search

   • Subtree: Searches entries within the entire subtree, including the root of your search

6. In the Search Criteria box, use the lists and text fields on the search criteria bar to focus your search.
   1. From the list at the left end of the search criteria bar, select an attribute of the entry for which you want to search.

      Note: Not all attributes are used in every entry. Be sure that the attribute you specify actually corresponds to one in the entry for which you are looking. Otherwise, the search will fail.

   2. In the text box at the right end of the search criteria bar, type the value for the attribute you just selected. For example, if the attribute you selected was cn, you could type the particular common name you want to find.

   3. From the list in the middle of the search criteria bar, select a filter. Options are:

      Filter	Description
      Begins With	Searches by using only the first few characters of the attribute's value. For example, cn Begins With Fran retrieves all entries in which the first few letters of the cn attribute are Fran. These would include Frank, Fran, Frances, Franklin, etc.
      Ends With	Searches for an entry by using only the last few characters of the specified attribute's value. For example, cn Ends With son retrieves Baldisson, Jacobson, Johnson, etc.
      Contains	Searches for an entry in which the attribute you specified includes, but is not necessarily limited to, the value you enter. For example, cn Contains Wins retrieves all entries in which the cn attribute contains the letters wins. These would include Winslow, Czerwinski, Winship, etc.
      Exact Match	Searches for an entry whose specified attribute is the same as the value you enter. For example, cn Exactly Matches Franklin Baldwins retrieves all entries in which the cn attribute has the value Franklin Baldwins.
      Greater or Equal	Searches for an entry in which the specified attribute is numerically or alphabetically greater than or equal to the value you enter. For example, cn Greater or Equal Frank retrieves all entries with cn attributes that range from the first Frank to the end of the alphabet.
      Less or Equal	Searches for entries in which the specified attribute is numerically or alphabetically less than or equal to the value you enter. For example, cn Less or Equal Frank retrieves all cn attributes from the first Frank to the beginning of the alphabet.
      Present	Determines if an entry with the specified attribute is present at that level of the tree. You do not need to enter a value to use this relationship. The phrase cn Present retrieves all entries with the cn attribute at that level of the tree.

7. To further refine your search, use the buttons in the Search Criteria box to enhance the search criteria bar.

   Button	Description
   New	Creates a new search criteria bar in the Search Criteria field. This button is enabled only when the Search Criteria field is empty.
   And	Creates another search criteria bar in the Search Criteria field. Matches all entries with one specified attribute with those that also have another specified attribute. For example, cn=Baldwins And title=Laborer retrieves all Baldwins who are also laborers.
   Or	Creates another search criteria bar in the Search Criteria field. Matches all entries with either one specified attribute or another. For example, title=Laborer Or title=Foreman retrieves all employees who are either laborers or foremen.
   Not	Negates the criterion in the selected search criteria bar and retrieves all entries that do not have the specified criterion. For example, cn=Frank And Not title=Laborer retrieves all persons named Frank who are not laborers.
   Delete	Deletes a selected search criteria bar

8. Click Search. The results of your search appear in the Distinguished Name box.

   See Also: "Configuring Searches" for instructions on setting the number of entries to display in searches, and to set the time limit for searches

Searching for Audit Log Entries by Using Oracle Directory Manager

You can also search for audit log entries by using Oracle Directory Manager.

To use Oracle Directory Manager to view audit log entries:

1. In the navigator pane, expand Oracle Internet Directory Servers > directory_server_instance, and select Audit Log Management. The corresponding right pane appears.

2. Follow the instructions in "Searching for Entries by Using Oracle Directory Manager" to search for particular types of entries in the audit log. The results of the search appear in the lower box.

3. To view the properties of a particular audit log entry, select it in the lower box, then click View Properties. The Audit Log Entry dialog box displays the properties for the audit log entry you selected.

   See Also: "Configuring Searches" for instructions on setting the number of entries to display in searches, and to set the time limit for searches

Viewing Attributes by Using Oracle Directory Manager

Once you have displayed the results of your search, click the entry whose attributes you want to view. An Entry dialog box displays the attributes for that entry.

Some attributes can also be DNs. For example, one attribute for a given employee might be that employee's manager who, in turn, has a DN. In this case, when you display the Entry dialog box for the employee, you would see a Browse button next to the Manager text box. To find information about that manager, click Browse to display the Directory: Entry Management dialog box, then follow the steps mentioned in "Searching for Entries by Using Oracle Directory Manager".

Adding Entries by Using Oracle Directory Manager

Note: This release of Oracle Internet Directory does not support the adding of JPEG images by using Oracle Directory Manager. You may add a JPEG image by using the ldapadd command. For more information, see "Example: Adding a User Entry by Using ldapadd".

Adding a New Entry by Using Oracle Directory Manager

To add or delete entries with Oracle Directory Manager, you must have write access to the parent entry and you must know the DN for the new entry.

To add a new entry:

1. Expand Oracle Internet Directory Servers > directory_server_instance, then select Entry Management.

2. On the toolbar, click Create. The New Entry dialog box appears.

3. In the Distinguished Name field, type the full DN. You may also click Browse to locate and select the DN of the parent for the entry you want to add. The entry you select appears in the Distinguished Name field. To the left of that parent DN, type the RDN for your new entry, followed by a comma.

4. To specify the object classes for the new entry, next to the Object Classes box, click Add. The Super Class Selector dialog box appears.

5. In the Super Class Selector dialog box, select an object class, then click Select. As you select from the object class list, mandatory and optional attributes populate the windows in the tab pages in the lower half of the New Entry dialog box. You must enter values into the mandatory attributes fields. You are not required to enter values into the optional attributes fields.

6. When you have selected the object classes and provided values for the appropriate attributes, click OK.

Adding an Entry by Copying an Existing Entry in Oracle Directory Manager

You can use Oracle Directory Manager to create a new entry by copying from an existing entry and changing its DN. When you do this, you should also change the attributes, such as name and address, so that they correspond to the new DN. To add an entry, you must have write access to its parent.

Tip: You can find a template for the new DN by looking up other similar entries in the search pane.

To add an entry by copying an existing entry:

1. In the navigator pane, expand Oracle Internet Directory Servers > directory_server_instance, then select Entry Management. The Search pane appears. Use it to search for an entry that you want to use as a template.

2. Double-click an entry from those retrieved. The Entry dialog box for that entry appears. This entry will serve as your template in the Create Like pane.

3. In the Entry dialog box, click Create Like. A New Entry: Create Like dialog box appears.

4. Change critical fields to tailor this entry to the one that you want to create. You must always change the DN and the common name in this operation, or the pane will not save your new entry data. For example, if you create an entry for Henri Latrobe using the entry for Henri Latour as the template, then you have to change cn=Henri Latour in the DN to cn=Henri Latrobe. You also have to change the Henri Latour value in the common name attribute to Henri Latrobe, and any other attributes that must be unique, such as employee number and telephone number.

5. Click OK to save your changes.

   See Also: The online help for this dialog box for details about adding information into fields

Example: Adding a User Entry by Using Oracle Directory Manager

In this example, we create a user named Anne Smith and assign her a password.

1. Login as the administrator.

2. Expand Oracle Internet Directory Services > directory_server_instance, and select Entry Management.

3. On the toolbar, click the Create button. The New Entry dialog box appears.

4. In the Distinguished Name field, type the full DN. You may also click the Browse button to locate the DN of the parent for this entry, then type the RDN, namely, cn=Anne Smith, followed by a comma, to the left of that parent DN.

5. To the right of the Object Classes box, Click Add. The Super Class Selector dialog box appears.

6. In the Super Class Selector dialog box, select the person object class, then click Select. This returns you to the New Entry dialog box.

7. In the New Entry dialog box, click the Optional Properties tab, and scroll to the userPassword window.

8. Type the password for Anne Smith.

Adding Group Entries by Using Oracle Directory Manager

A group entry is one that contains a list of entries, for example, an e-mail list. You associate it with either the groupOfNames or groupOfUniqueNames object class, which has the object class orclPrivilegeGroup as a subclass.

You determine membership in the group by adding DNs to the multivalued attribute member if the entry belongs to the groupOfNames object class, or uniqueMember if the entry belongs to the groupOfUniqueNames object class.

To add a group entry:

1. Expand Oracle Internet Directory Servers > directory_server_instance, then select Entry Management.

2. On the toolbar, click Create. The New Entry dialog box appears.

3. In the Distinguished Name field, type the full DN. You may also use the Browse button to locate the DN of the parent for the entry you want to add, then type the RDN for the new entry, followed by a comma, to the left of that parent DN.

4. To specify the object classes you want to use for the new entry, to the right of the Object Classes box, click Add. The Super Class Selector dialog box appears.

5. In the Super Class Selector dialog box, select the top object class, then click the Select button. The top object class appears in the Object Classes box of the New Entry dialog box.

6. In the same way:
   1. To the right of the Object Classes box, click Add.

   2. From the Super Class Selector dialog box, select the groupOfNames or groupOfUniqueNames object class.

   3. Click Select. The object class you selected appears in the Object Classes window of the New Entry dialog box.

7. Enter the mandatory and optional attributes for your group entry.

   If you selected the groupOfNames object class, a Browse button appears next to some of the fields, for example, the member field on the Mandatory Properties tab page. To enter a mandatory property by browsing:

   1. Click Browse. The Directory: Entry Management dialog box appears.

   2. Use this dialog box to search for a particular entry you want to add to the list.

   3. In the Distinguished Name window of the Directory: Entry Management dialog box, select the entry, then click OK. This returns you to the New Entry dialog box. The entry you just selected is added to the list in the members window.

8. Click Ok.

   See Also: "Searching for Entries by Using Oracle Directory Manager" for instructions on using the search pane "Privilege Groups" for instructions on setting access control policies for group entries Access Control and Authorization and Chapter 9, "Managing Directory Access Control" for information about access privileges

Modifying Entries by Using Oracle Directory Manager

Oracle Directory Manager is governed by standard LDAP conventions, including the following:

• You cannot change object classes that are used by an entry once you have assigned object classes to that entry and populated its attributes with data.

  For example, if you configure an entry to use object classes Person and Organizational Role, you cannot later add another object class to this entry.

• You cannot add mandatory attributes to an object class already in use by some entries. You may add optional attributes to object classes that are already in use by entries. If you add optional attributes to an object class already in use by some entries, no special rules apply--they are added as empty attributes to those entries.

To modify an entry:

1. Perform a search for the entry you want to modify as described in "Searching for Entries by Using Oracle Directory Manager".

2. In the Distinguished Name box of the right pane, select the entry you want to modify.

3. Click Edit. The Entry dialog box appears.

4. Select the Properties tab page. If you do not see the attributes you want to add or modify, then, at the top of the tab page, select View Properties: All.

5. In the Properties tab page, modify the values of any editable attributes.

6. Click OK.

Example: Modifying a User Entry by Using Oracle Directory Manager

In this example, we modify the password for the entry we created for Anne Smith in the section "Example: Adding a User Entry by Using Oracle Directory Manager".

1. Perform a search for the Anne Smith entry.

2. In the Distinguished Name box of the right pane, select the entry for Anne Smith.

3. Click Edit.

4. In the Entry dialog box, scroll to the userPassword window and modify the value.

5. Click OK.

Managing Entries by Using Command Line Tools

This section points you to the command line tools you can use in managing entries. It also provides several examples of entry management by using command line tools. It contains these topics:

• Command Line Tools for Managing Entries

• Example: Adding a User Entry by Using ldapadd

• Example: Adding an Attribute Option

• Example: Modifying a User Entry by Using ldapmodify

Command Line Tools for Managing Entries

The following table lists each of the command line tools, and tells you where to find syntax and usage notes for each one.

Tool	Task(s)	Syntax and Usage Notes
ldapsearch	Search for directory entries.	"ldapsearch Syntax"
ldapbind	Authenticate a user or client to a directory server. Verify that you can connect a client to a server.	"ldapbind Syntax"
ldapadd	Add entries one at a time. Add new configuration set entries. Configure a server with an input file.	"ldapadd Syntax"
ldapaddmt	Add several entries concurrently by using this multithreaded tool.	"ldapaddmt Syntax"
ldapmodify	Create, update, and delete attribute data for an entry. Modify configuration set entries. Modify DN or RDN of an entry.	"ldapmodify Syntax"
ldapmodifymt	Modify several entries concurrently by using this multithreaded tool.	"ldapmodifymt Syntax"
ldapdelete	Delete entries.	"ldapdelete Syntax"
ldapcompare	Compare attribute values you specify with those in a directory entry.	"ldapcompare Syntax"
ldapmoddn	Modify the DN or RDN of an entry. Rename an entry or a subtree. Move an entry or a subtree under a new parent.	"ldapmoddn Syntax"

Example: Adding a User Entry by Using ldapadd

The following example shows an LDIF file, named entry.ldif, for the user entry for an employee named John:

dn: cn=john, c=us
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: john
cn;lang-fr:Jean
cn;lang-en-us:John
sn: Doe
jpegPhoto: /photo/john.jpg

userpassword: welcome

This file contains the cn, sn, jpegPhoto, and userpassword attributes.

For the cn attribute, it specifies two options: cn;lang-fr, and cn;lang-en-us. These options return the common name in either French or American English.

For the jpegPhoto attribute, it specifies the path and file name of the corresponding JPEG image you want to include as an entry attribute.

Example: Modifying a User Entry by Using ldapmodify

The following example changes the password for a user named Audrey from welcome to audreyspassword. As in the example above, the data for this user entry is in the entry.ldif file. This file contains the following:

dn: cn=audrey,c=us
changetype: modify
replace: userpassword
userpassword: audreyspassword

Issue this command to modify the file:

ldapmodify -p 389 -b  -f entry.ldif

Managing Entries by Using Bulk Tools

This section lists and describes some of the more common tasks you perform with bulk tools.

This section contains these topics:

• Importing an LDIF File by Using bulkload

• Converting Directory Data to LDIF

• Modifying a Large Number of Entries

• Deleting a Large Number of Entries

  See Also: "Using Bulk Tools" for an overview of these tools

Importing an LDIF File by Using bulkload

To import an LDIF file, you use the bulkload utility. This section discusses the tasks to process an LDIF file through bulkload.

Note: Before performing a bulk load, stop the Oracle Internet Directory processes. See Chapter 3, "Preliminary Tasks" for instructions on stopping directory server instances.

This section contains these topics:

• Task 1: Back Up the Oracle Server

• Task 2: Find Out the Oracle Internet Directory Password

• Task 3: Check Input for Schema and Data Consistency Violations

• Task 4: Generate the Input Files for SQL*Loader

• Task 5: Load the Input Files

• If Bulk Loading Fails

Task 1: Back Up the Oracle Server

Before you import the file, back up the Oracle database server as a safety precaution.

See Also: Oracle8i Backup and Recovery Guide

Task 2: Find Out the Oracle Internet Directory Password

To use bulkload and the other shell script tools that have commands that end with.sh, you must provide the Oracle Internet Directory password. The default password is ods, although the system administrator can change it by using the OID Database Password Utility.

See Also: "Using the OID Database Password Utility"

Task 3: Check Input for Schema and Data Consistency Violations

On Solaris, the bulkload.sh file usually resides in
$ORACLE_HOME/ldap/bin. On Windows NT, this file usually resides in
ORACLE_HOME\ldap\bin.

Check the input file by typing:

bulkload.sh -connect net_service_name -check path_to_ldif-filename

All schema violations are reported in
$ORACLE_HOME/ldap/log/schemacheck.log

If any violations are detected in the input file, use an ASCII text file editor to fix or remove them. If there are any duplicate entries, their DNs are logged in $ORACLE_HOME/ldap/log/duplicate.log.

Task 4: Generate the Input Files for SQL*Loader

After you have fixed any errors in the input file, rerun bulkload with the -generate option as shown in the following example. During this step, LDIF data is converted to SQL*Loader specific format.

bulkload.sh -connect net_service_name -generate ldif-filename

All loading errors are reported in
$ORACLE_HOME/ldap/log

When this command completes successfully, it generates *.dat files in the $ORACLE_HOME/ldap/load directory to be used by SQL*Loader in -load mode. Do not modify these files.

Task 5: Load the Input Files

After you have generated the input files, rerun bulkload with the -load option. During this step, the *.dat files, which are in Oracle SQL*Loader specific format, are loaded into the database and the attribute indexes are created. The syntax is:

bulkload.sh -connect net_service_name -load

If Bulk Loading Fails

All loading errors are reported in the $ORACLE_HOME/ldap/log/directory with the file extension .bad.
If bulk loading fails, the database could be left in an inconsistent state. It may be necessary to restore the database to its state prior to the bulk loading operation.

Converting Directory Data to LDIF

Converting directory data to LDIF by using LDIF Writer makes the data available for loading into a new node in a replicated directory or into another node for backup storage.

See Also: "ldifwrite Syntax"

Modifying a Large Number of Entries

The bulkmodify utility enables you to modify a large number of existing entries in an efficient way.

See Also: "bulkmodify Syntax"

Deleting a Large Number of Entries

The bulkdelete utility enables you to delete an entire subtree efficiently.

See Also: "bulkdelete Syntax"

Managing Entries with Attribute Options

To manage entries with attribute options, you use command line tools. This section contains these topics:

• Example: Adding an Attribute Option

• Example: Deleting an Attribute Option

• Example: Searching for Entries with Attribute Options

Example: Adding an Attribute Option

Suppose that you were adding the Spanish equivalent of an entry for John. As in the example above, the data for this user entry is in the entry.ldif file. This file contains the following:

dn: cn=john,c=us
changeType: modify
add: cn;lang-sp
cn;lang-sp: Juan

Issue this command to modify the file:

ldapmodify -p 389 -b  -f entry.ldif

Example: Deleting an Attribute Option

The following example deletes the cn;lang-fr attribute option from the entry for John. As in the previous example, the data for this user entry is in the entry.ldif file. This file contains the following:

dn: cn=john, c=us
changetype: modify
delete: cn;lang-fr
cn;lang-fr: Jean

Issue this command to modify the file:

ldapmodify -p 389 -b  -f entry.ldif

Example: Searching for Entries with Attribute Options

The following example retrieves entries with common name (cn) attributes that have an option specifying a language code attribute option. This particular example retrieves entries in which the common names are in French and begin with the letter R.

ldapsearch -p 389 -h myhost -b "c=US" -s sub "cn;lang-fr=R*"

Suppose that, in the entry for John, no value is set for the cn;lang-it language code attribute option. In this case, the following example fails:

ldapsearch -p 389 -h myhost -b "c=us" -s sub "cn;lang-it=Giovanni

See Also: "Attribute Options"

Managing Knowledge References (Referrals)

A knowledge reference, also called a referral, is represented in the directory as a particular type of entry. When you create a knowledge reference entry, you associate it with the referral and extensibleObject object classes. Typically, you create knowledge reference entries at the place in the DIT where you want to establish the partition.

Knowledge references provide users with LDAP URLs. You enter these URLs as values for the ref attribute. There can be multiple ref attributes specified for any knowledge reference entry. Similarly, there can be multiple knowledge reference entries in the DIT.

See Also: "Distributed Directories: Partitioning" for an overview of knowledge references and a description of smart knowledge references and default knowledge references

This section contains these topics:

• Configuring Smart Knowledge References

• Configuring Default Knowledge References

Configuring Smart Knowledge References

When a user performs a search operation, Oracle Internet Directory looks for the knowledge reference entry within the specified scope of the search. If it finds the knowledge reference, then Oracle Internet Directory returns it to the client.

If a user performs an add, delete, or modify operation on an entry located below the knowledge reference entry, then Oracle Internet Directory returns the knowledge reference.

Note: A search result can contain regular entries along with knowledge references.

For example, suppose you want to partition the DIT based on the geographical location of the directory servers. In this example, assume that:

• The c=us naming context is held locally on Server A and Server B in the United States.

• The c=uk naming context is held locally on Server C and Server D in the United Kingdom.

You would configure knowledge references between these two naming contexts as follows:

1. On Server A in the United States, configure a knowledge reference for the c=uk object on Server C and Server D:

   dn: c=uk
   c: uk
   ref: ldap://host C:389/c=uk
   ref: ldap://host D:686/c=uk
   objectclass: top
   objectclass: referral
   objectClass: extensibleObject
   
   
   

2. Configure a similar knowledge reference on Server C in the United Kingdom for the c=us object on Server A and Server B:

   dn: c=us
   c: us
   ref: ldap://host A:4000/c=us
   ref: ldap://host B:5000/c=us
   objectclass: top
   objectclass: referral
   objectClass: extensibleObject
   
   
   

Results:

• A client querying Server A with base o=foo,c=uk receives a knowledge reference

• A client querying Server C with base o=foo,c=us receives a knowledge reference

• An add operation of o=foo,c=uk on either Server A or Server B fails. Instead, Oracle Internet Directory returns a knowledge reference.

Configuring Default Knowledge References

Oracle Internet Directory uses the namingcontext attribute in the DSE to determine all the naming contexts held locally by the server. Be sure that the namingContext attribute correctly reflects the naming context information.

You specify default knowledge references by entering a value for the ref attribute in the DSE entry. If the ref attribute is not in the DSE entry, then no default knowledge reference is returned.

When configuring a default knowledge reference, do not specify the DN in the LDAP URL.

For example, suppose that the DSE entry on Server A contains the following namingContext value:

namingcontext: c=us

Further, suppose that the default knowledge reference is:

Ref: ldap://host PQR:389

Now, suppose that a user enters an operation on Server A that has a base DN in the naming context c=canada, for example:

ou=marketing,o=foo,c=canada

This user would receive a knowledge reference to the host PQR. This is because Server A does not hold the c=canada base DN, and the namingcontext attribute in its DSE does not hold the value c=canada.

See Also: "About Knowledge References (Referrals)" for a conceptual discussion of knowledge references