The Enterprise Directory stores information as directory entries, each entry representing an object, such as a person, a place, an organization, or a computer.

The entries are organized into a Directory Information Tree (DIT), such that some entries are subordinate to others. The figure below illustrates the DIT structure, showing a number of directory entries forming a hierarchy beneath a root. Note that, by convention, the root of the DIT is at the top of the picture.

The position of entries in the hierarchy should be based on the relationships between the objects they represent in the real world. For example, an entry representing a person might be positioned beneath an entry representing the organization the person works for. The hierarchical structure is the basis of each entry’s name, as described in Section 1.1.2, “Entry Names”. The structure also enables the DIT to be divided into subtrees which can be distributed and replicated amongst multiple servers, as described in Section 1.2.2, “Distributing Directory Information”. This means that the DIT is scalable to any size.

1.1.1. Entries

Within the Enterprise Directory, objects are represented as directory entries. There should be one directory entry for each object that you want to represent. Each entry is made up of a set of attributes, each of which has one or more values. Figure 1.2, “A Typical Directory Entry” illustrates how an application might display a typical entry representing a person.

1.1.1.1. Attributes

An attribute is information of a particular type about an entry. Every attribute has an attribute type and at least one attribute value. For example, the entry in Figure 1.2, “A Typical Directory Entry” includes an attribute of the type commonName? with three values, each of which is a variation of the name of the person that the entry represents.

The definition of each attribute type specifies whether the attribute can have more than one value, and whether there are any constraints on the length or the range of the value. Section 1.2.1, “The Schema” explains how these definitions are enforced and managed. Note that the values of a multi-valued attribute are not ordered.

Every attribute type is associated with an attribute syntax which defines the format of its value. For example, the telephoneNumber attribute type uses the telephoneNumberSyntax.

Each attribute type is also associated with one or more matching rules. A matching rule specifies how the Enterprise Directory will compare attribute values with each other for certain user requests. For example, some matching rules are insensitive to the case of characters, such that a user searching for commonName="JOANSMITH" would find an entry with the value commonName="JoanSmith".

Each attribute type may be associated with matching rules that support exact matching, substring matching, approximate (phonetic) matching, and ordering of values. Later chapters of this guide explain how to define your own attributes as extensions to the product.

1.1.2. Entry Names

As Figure 1.2, “A Typical Directory Entry” illustrates, a typical entry can have several attribute values that represent names by which the object is known, such as surnames and common names. However, so that the Directory Service can unambiguously identify an individual entry, each entry also has a directory name.

A directory name identifies an individual entry in terms of that entry’s position in the hierarchy of the DIT (illustrated in Figure 1.1, “The Hierarchical or Tree Structure of Directory Information”).

There are two types of directory name:

• Distinguished names

• Alias names

Every directory entry has only one distinguished name, but can also have several alias names. Section 1.1.2.1, “Distinguished Names” and Section 1.1.2.2, “Alias Names” describe distinguished names and alias names in detail.

1.1.2.1. Distinguished Names

Every entry has one distinguished name. A distinguished name is made up of a sequence of terms, each of which is called a relative distinguished name (RDN).

Each RDN in an entry’s distinguished name represents one of the entries that forms the path from the root of the DIT to the entry.

Each RDN is an attribute type and value chosen from the attributes of the entry that it names. If the attribute type you use for naming has more than one value, then you must choose which value is to serve as the RDN. For example, for the typical entry illustrated in Figure 1.2, “A Typical Directory Entry”, if the commonName attribute type is used for naming, then you need to choose one of the three values of commonName. Any other values are still present in the entry, but do not form part of the entry’s distinguished name.

It is possible for an RDN to contain more than one attribute type and value from an entry. For example, a typical RDN would be commonName="JoanSmith", but it is also possible to have an RDN such as commonName="JoanSmith", locality="Lower Dingle". Typically, using more than one attribute in an RDN makes directory names less user friendly.

Note

Most directory applications use abbreviations for attribute types. For example, commonName is often abbreviated to CN. Thus, commonName="JoanSmith" is abbreviated to CN="Joan Smith".

Most examples in this guide use the default abbreviations to shorten entry names. You can customize VSI directory applications to suit local conventions or language.

No two entries that have the same immediately superior entry can have the same attribute type and value or combination of attribute types and values chosen to be the RDN. Thus, each RDN is unique amongst the subordinates of a given entry.

One of your planning tasks will be to decide how to resolve name clashes, for example, if you have two Joan Smiths in the same part of your organization. Chapter 4, Planning Your Directory Information Tree explains name planning.

Figure 1.3, “Distinguished Names” shows how RDNs are used to form unambiguous distinguished names.

The entry representing Joan Smith (at the bottom left of the illustration) has a distinguished name made up of four RDNs. The first three RDNs represent the three entries that form a path from the root of the DIT to Joan’s entry. The fourth RDN is that of Joan’s entry itself. Since each RDN is unique relative to its superior entry, the distinguished name is also guaranteed to be unique.

A typical directory application would display Joan’s distinguished name (using abbreviations) as follows:

/C=US/O=Abacus/OU=Sales/CN="Joan Smith"

The abbreviation C means countryName, O means organizationName, OU means organizationalUnitName, and CN means commonName. The four RDNs in the distinguished name are separated by the / character, and are listed in order of hierarchical superiority, with the RDN of the entry closest to the root of the DIT listed first.

The exact conventions used to display a distinguished name vary between applications. The conventions shown are the ones used byte X.500 Information Management (DXIM) utility. The LDAP convention is CN="Joan Smith", OU=Sales, O=Abacus, C=US.

1.1.2.2. Alias Names

Although an entry has only one distinguished name, there can be many alias names for an entry. This means that an entry can be referred to using either its distinguished name, or any one of its alias names.

An alias name looks just like a distinguished name. However, an alias name does not represent the direct path from the root of the DIT to the entry. Instead, as the Enterprise Directory follows the path from the root, it finds that the path leads to an alias entry. The alias entry has an attribute that contains the directory name of the entry to which the alias refers.

For example, if Joan Smith (see Figure 1.3, “Distinguished Names”) has recently married, and might still be known by her unmarried name Joan Meredith, then you could create an alias entry called /C=US/O=Abacus/OU=Sales/CN="Joan Meredith". Any user request that specifies this alias name is automatically redirected.

Section 1.1, “Directory Information” described the information that is stored in the directory. This section explains the services that the VSI Enterprise Directory product provides to its users.

A DSA is a server. It is responsible for storing directory entries, and for providing access to them. A DSA is also responsible for redirecting requests for information that it does not store. You can install one DSA per node (or one DSA per VMS cluster).

A DUA forms part of a client application. A DUA enables users to formulate requests for directory information, such as a request to create or view an entry. A DUA uses a standard protocol to pass requests to a DSA, and to receive answers back from the DSA. There might be many different client applications installed on a single system.

Figure 1.4, “The X.500 Model of Enterprise Directories” illustrates the X.500 model of directory components, showing how a number of DSAs serve a number of directory applications. Each directory application includes a DUA. The directory applications serve a number of users, which can be human users or other applications.

The VSI Enterprise Directory product provides a DSA and and the X.500 Information Management utility (DXIM). DXIM is an example of an application that includes a DUA. DXIM uses the standard protocol to communicate with DSAs.

Because HP’s DSAs and directory applications use standard protocols, they can interwork with other vendors’ X.500 conformant DSAs and directory applications. For example, you can use DXIM to manage entries in another vendor’s DSA, or use another vendor’s application to manage entries in a HP DSA.

The interrogation services provide different ways of looking at the information in the directory, such as inspecting particular attributes of an entry, or searching for entries that have a specified set of attributes. The modification services allow you to create new entries, remove entries, and modify the attributes of entries.

To provide an efficient and consistent service to users, DSAs can provide a set of services that are not necessarily visible to the user. These are:

These services are described in the following sections.

1.2.2. Distributing Directory Information

The amount of directory information a DSA can hold depends on the resources available on the DSA’s node. You can install one DSA per node or VMS cluster. A single DSA can hold tens or even hundreds of thousands of entries, depending on its resources.

To enable the DIT to exceed the capacity of a single DSA, the VSI Enterprise Directory product enables you to distribute directory information so that each DSA only holds part of the DIT.

You can divide your organization’s DIT into subtrees, each of which is called a naming context, and each DSA holds one or more naming contexts. Thus, although you can only have one DSA per node, that DSA can hold more than one naming context.

Figure 1.5, “A DIT Divided and Distributed Amongst Four DSAs” shows a DIT that is divided into four naming contexts, which are distributed amongst four DSAs. In this example, each DSA holds only one naming context.

Part II, “Planning” explains how to plan the distribution of directory information so that each DSA holds the naming contexts that are most useful to the DSA’s local users.

The ability to distribute directory information means that there is no limit to the total amount of information that can be stored. You can always add new DSAs to increase capacity.

However, the distribution of the DIT does not mean that a user needs to know which DSA to ask for a particular piece of information. Instead, each DSA keeps knowledge information that helps it redirect requests (see Section 1.2.4, “Distributing Requests for Information”).

Using this knowledge information, DSAs cooperate so that the user receives a response regardless of which DSA they originally contact. HP’s DSAs can have knowledge information about other vendors’ DSAs, as well as about other HP DSAs.

1.2.3. Replicating Directory Information

The VSI Enterprise Directory product not only enables you to distribute directory information (see Section 1.2.2, “Distributing Directory Information”), but it also enables you to copy information amongst your HP DSAs. This is known as replicating or shadowing information.?

This means that you can have copies of information in several locations, improving response times, and increasing the availability of information. Figure 1.6, “A DIT Distributed and Replicated Amongst Four DSAs” shows a DIT that is divided into four naming contexts that are distributed and replicated amongst four DSAs. The arrows show the source and destination of each replicated naming context.

The ability to replicate information makes the Enterprise Directory suitable for organizations that want users and applications in many locations to have efficient access to a large amount of directory information.

HP DSAs use standard protocols to ensure that copies of entries are kept up to date without manual intervention.

There are two types of management task for an X.500 Enterprise Directory, and VSI Enterprise Directory product divides the management functions accordingly. The management tasks reflect the division between the two sets of concepts:

Install the product, and do the post installation task(s), as documented on the installation card relevant to your system’s operating system.

Configure the DSA as follows:

From a privileged account, type:

$ @SYS$STARTUP:DXD$DUA_CONFIGURE.COM

Accept all defaults.

You now have a single node Enterprise Directory in which one DSA holds three directory entries. The entries represent Abacus, Sales, and Francis Black respectively. You can now experiment with these entries. For example:

dxim> search where surname=black all attributes
dxim> search where surname=b* all attributes
dxim> set /C=US/O=Abacus/OU=Sales/CN="Francis Black" -
_dxim> attribute telephone=123456
dxim> search where surname=black attributes telephone, commonName

Refer to the DXIM online help for details of all commands. The help contains descriptions and examples of all DXIM commands.

When you have finished experimenting with the example Enterprise Directory, you must delete it from your system.

To delete the example Enterprise Directory configuration, log in to a privileged account, and use the NCL director to disable and delete the DSA on each node, as follows:

NCL> DISABLE DSA
NCL> DELETE DSA

Then delete the database files and the defaults files on both systems, as follows:

$ DELETE DXD$DIRECTORY:DSA-INFORMATION-TREE.*;*
$ DELETE DXD$DIRECTORY:DXD$DUA_DEFAULTS.DAT;*

Deleting the database files means that the DSA is returned to its unconfigured state, as it was when you first installed the software. The DSA stores its configuration information and its entries in these files.

The tasks described in this chapter provide an Enterprise Directory with two DSAs on two nodes. The two DSAs hold different parts of the same directory information tree. Figure 3.1, “Structure and Distribution of the Example DIT” illustrates the example tree, and its distribution across the two DSAs.

The two DSAs are installed on nodes referred to as NODE_1 and NODE_2. You need to decide which of your two nodes is to play the role of NODE_1, and which is to be NODE_2, and then apply the tutorial commands as appropriate.

The two DSAs are referred to as CN=DSA1 and CN=DSA2 respectively. Use these exact names for your DSAs. The abbreviation CN means commonName, which is the attribute type used for naming DSAs in the directory.

The tutorial includes two entries representing people: Francis Black and Janice White. Francis’ entry is held on CN=DSA1 within a Sales organizational unit, and Janice’s entry is held on CN=DSA2 within an Accounts organizational unit.

Access control for the example tree is provided by the CN="Access Controls" entry shown in Figure 3.1, “Structure and Distribution of the Example DIT”. The access control entry states that Francis Black is a directory information manager, and that Janice White is an ordinary directory user. The tutorial will show how access rights for these two users differ because of the access controls.

Install the product on the two systems, as described in the installation documentation for the appropriate operating systems. Complete all post installation tasks.

The two systems need be able to connect to each other using DECnet-Plus networking or TCP/IP RFC1006 networking.

This version of the Enterprise Directory provides a new user application; the X.500 Lookup Client. The Lookup Client, an optional feature of this tutorial, makes it possible to complete the tasks in Section 3.12, “Using the Lookup Client”.

This section uses the DSA configuration utility to give each DSA a basic configuration.

This section completes the configuration for CN=DSA1 on your NODE_1. Type all commands exactly as shown, with the exception of the <address> variable.

This section completes the configuration of CN=DSA2 on your NODE_2.

Type all commands exactly as shown, with the exception of the <address> variable.

This section configures application defaults on both systems. The defaults provide directory applications with information about how to connect to their local DSA.

$ @SYS$STARTUP:DXD$LUC_CONFIGURE.COM

This section describes how to create the entry representing the Abacus organization and its subordinate entries, as shown in Figure 3.1, “Structure and Distribution of the Example DIT”.

Type all commands exactly as shown with the exception of the <address> variable.

The X.500 information management (DXIM) utility commands shown are not case sensitive, with the exception of passwords and presentation addresses. In this tutorial, passwords are always specified in upper case, and presentation addresses must be copied exactly from the output of the DSA configuration utility (see Section 3.3, “Run the DSA Configuration Utility on Both Systems”).

The next two tasks shown in this section create entries on CN=DSA2. Again, the commands will succeed even if you are using DXIM on NODE_1, because CN=DSA1 has a Subordinate Reference that enables it to pass the requests on to CN=DSA2.

The remaining commands create entries to represent the two DSAs themselves.

where, in each case, the password matches the password specified in Section 3.4, “Complete the Configuration for CN=DSA1” or Section 3.5, “Complete the Configuration for CN=DSA2” as appropriate, and the presentation addresses match the ones you made a note of in Section 3.3, “Run the DSA Configuration Utility on Both Systems” for each DSA.

The steps completed so far create a distributed directory shown in Figure 3.2, “Structure and Distribution of the Example DIT”. If you compare this picture to Figure 3.1, “Structure and Distribution of the Example DIT”, you can see that the only entry that has not yet been created is the Access Controls entry (see Section 3.9, “Setting Up Access Controls”).

Note that the DSA entries are both held by CN=DSA1; CN=DSA2 does not contain its own directory entry. The physical location of a directory entry is determined by its name, and both of the DSA entries have names that cause them to be created within the /C=US/O=Abacus naming context, which is held on CN=DSA1. There is no requirement for a DSA to hold its own directory entry.

The remaining tasks in this tutorial implement access controls, replication, and Lookup Client. There is also a section showing you how to experiment with the example Enterprise Directory, showing how access controls affect your ability to see and modify directory information.

By default, all users of the Enterprise Directory can modify entries and read information from entries. Indeed, in Section 3.7, “Create Some Entries” you created several entries. The only restriction enforced by the two DSAs, by default, is that they do not allow you to display password attributes.

Typically, you will want to set up some additional access controls. This section shows how to set up access controls that make Francis Black a directory manager with the right to modify all entries.

Note that system or superuser privileges do not provide privileged access to directory information. The Enterprise Directory uses its own mechanism for determining what access rights a user has, and applies this mechanism regardless of the account or operating system the user is using, or whether the user is remote or local to the DSA.

To help you set up some simple access controls, the Directory Service provides the following access control template file.

DXD$DIRECTORY:DXD$ACI_TEMPLATE.DXIM

The template file contains two incomplete DXIM commands. Make a copy of the file so that when you have completed this tutorial, you can return it to its original state.

In order to set up the access controls, you need to complete the commands in the template file, and then use DXIM to execute them, as follows:

Section 3.11, “Experimenting with the Example Enterprise Directory” shows how the access controls affect the ability of Francis Black and Janice White to access information in the DIT.

This section describes how to implement replication, so that both DSAs have copies of each other’s information.

The NCL commands need to be issued from a privileged account. See previous sections for details of how to invoke the NCL director.

Now that replication has been implemented, and the two DSAs are able to verify each other’s identities, future replications happen without management intervention. Every twelve hours the two DSAs automatically communicate to keep the replicated information up to date.

You now have a simple, secure, distributed and replicated Enterprise Directory provided by two DSAs. Figure 3.3, “DSA1 After All Tasks Are Completed” shows CN=DSA1 after all of the tasks described above are completed. The shading indicates which information is a copy of information from CN=DSA2.

Figure 3.4, “DSA2 After All Tasks Are Completed” shows CN=DSA2 after all the of tasks described above are completed. The shading indicates which information is a copy of information from CN=DSA1.

Note that the entry called /C=US is not included in the shaded area. This is because that entry is not part of the Abacus information tree. An organization such as Abacus should not claim ownership of entries representing countries. Such entries form part of the global directory infrastructure, and should be owned and managed by national authorities. This is explained in more detail in Chapter 4, Planning Your Directory Information Tree.

This section shows how to use DXIM to access information in the example Enterprise Directory. It demonstrates some of the commands available to the user, and shows how access is controlled for different users.

When you have finished experimenting with the DXIM interfaces, exit from them and proceed to the next section of this tutorial.

To start the Lookup Client graphical interface, type the following command:

$ RUN SYS$SYSTEM:DXD$LOOKUP_MOTIF.EXE

Type Francis Black into the input field and press Return to invoke a search. The Lookup Client displays the entry representing Francis Black. Refer to the Help menu for further details on how to use the Lookup Client.

Now that you have some experience of the tasks involved in setting up an Enterprise Directory, delete the example configuration, and read the planning and implementation chapters of this book.

NCL> DISABLE DSA
NCL> DELETE DSA

Then delete the database files and the defaults files on both systems, as follows:

$ DELETE DXD$DIRECTORY:DSA-INFORMATION-TREE.*;*
$ DELETE DXD$DIRECTORY:DXD$DUA_DEFAULTS.DAT;*
$ DELETE SYS$SYSTEM:DXDLU.DEFAULTS;*

Deleting the database files means that the DSA is returned to its unconfigured state, as it was when you first installed the software. The DSA stores its configuration information and its entries in these files.

You should also delete the access control template file you created in Section 3.9, “Setting Up Access Controls”, and copy back into the correct position the original template file. If you no longer have an original copy of the template file, you can copy it from another system, or reinstall the X.500 Base subset, or edit the file back to its original state.

Designing your organization’s DIT is the most important of the planning tasks, because it is difficult to restructure your DIT once you have implemented it. The following sections describe several factors that you must consider when planning the DIT, some of which might tend to conflict with each other. Some sections indicate that the advice conflicts with the advice in other sections. Your task is to design a DIT that provides the best compromise, for your organization, of all the conflicting considerations.

Use a Familiar Structure

Try to represent your organization in a way that is familiar to the human users of the Enterprise Directory (assuming you intend to allow your employees to use the directory).

By using a familiar hierarchy, you make it easier for users to use the service efficiently, as they can direct their requests towards particular subtrees. For example, a user searching for another user’s entry could be aided by the fact that the directory divides the organization into geographical localities, with which the user is familiar.

Names based on a familiar hierarchy will also be easier to remember from one occasion to the next. If your organization already has a naming scheme for identifying resources and employees, then you can use that scheme as input to the DIT design, although organizational charts are often far more detailed than your DIT needs to be.

Existing naming policies or organizational charts might influence whether you decide to use organizational or geographical elements in your DIT. Also, if you are considering using a mixture of geographical and organizational elements, then bear in mind that this tends to conflict with user friendliness, as users have to guess which type of element is actually being used in the part of the DIT that they are trying to search. Your users will find names easier to use and remember if they are constructed of a predictable and consistent set of components.

Use a Stable Structure

Try to represent your organizational structure in a way that is unlikely to change.

Once you have implemented a naming tree, it is difficult to revise it (although you could delete all entries and start again, or use alias entries to give the appearance of a different structure). Also, any redesign of the DIT changes the names of entries, so your users will be less likely to remember them, or to know where in the tree to look for particular information. Therefore, if your organization often reorganizes its structure, try to use structural features of your organization that are least likely to change.

The need for DIT stability might influence whether you use geographical and/or organizational elements in your DIT. In some organizations it might be common for employees to change group many times without having to relocate, in which case it makes sense to name people according to their location rather than their organizational unit. In other organizations, it might be more common for organizational units to relocate such that the organizational structure is stable, but the location of its groups is unstable. In that case, geographical details are of little lasting use in your DIT.

Use a Structure that Accommodates Resource Mobility

Try to divide your organization into subdivisions in which resources tend to stay for long periods.

If your employees and other resources move from group to group or location to location frequently, then there is a danger that you will need to do a lot of modifications to their entries. If you use units that resources stay in, you can reduce the amount of management required to keep the information up to date. One way to achieve this objective is to avoid dividing your organization into too many subdivisions.

For example, an engineer can be expected to remain in the Engineering part of the business, but to move between different engineering projects. If you use a structure that need frequent modification. If you simply place all engineers beneath an entry representing Engineering as a whole, the engineer’s entry need not be modified after each move.

Figure 4.4, “Accommodating Resource Mobility” illustrates part of a DIT in which an Engineering unit is subdivided into a number of smaller units, whereas a Sales unit is not subdivided. There is an engineer called Jane working for the hardware engineering group, and a salesman called Bill working for the hardware sales group. If Jane moves from hardware engineering to software engineering and then to office products engineering she would require her directory entry to be moved from unit to unit accordingly. However, if Bill moves from hardware sales to software sales and then to office products sales he would not require any modification to his entry, because it simply identifies him as an employee of Sales generally.

The part of the DIT representing Sales therefore minimizes the effect of resource movement within the organization. Bill’s entry would only need modification if Bill left the Sales unit altogether. However, note that this advice tends to conflict with the advice about avoiding name clashes, as well as the advice about dividing the DIT into manageable portions (as described in the following subsections).

Use a Structure that Divides the DIT into Manageable Portions

The easiest way to divide the management responsibility for the DIT is to assign managers to particular subtrees of the DIT. For example, to manage the DIT shown in (Figure 4.4, “Accommodating Resource Mobility”), you could have two DIT management teams; one for the Engineering entry and all of its subordinates, and the other for the Sales entry and all of its subordinates. Alternatively, you could have one management team for each of the three engineering subdivisions and one for the Sales unit.

Dividing your DIT into manageable portions may conflict with the advice about using few levels of hierarchy and about coping with resource mobility.

Use a Structure that Minimizes Name Clashes

Try to design a DIT that divides your organization into groupings of entries that cause as few name clashes as possible.

A name clash occurs when two or more entries require the same directory name. Every distinguished name must be unique, so, for example, if you have several John Smiths working for the same organizational unit, you have a name clash to resolve. Try to divide your organization so that organizational units are small enough for such clashes to be rare. (You can never completely avoid the possibility of name clashes, and Section 4.4.1, “Resolving Naming Clashes” explains how to resolve them when they occur.)

Dividing your organization into small units to reduce the chance of name clashes might conflict with the advice about using few levels of hierarchy and trying to cope with resource mobility.

Use Few Levels of Hierarchy

Try to use as few levels of hierarchy as possible. Each entry’s distinguished name is made up of the RDNs of all the entries directly above it in the DIT. Therefore, entries a long way down the hierarchy tend to have very long distinguished names. The most useful entries tend to be the ones at the lowest levels of the DIT, and therefore are the ones with the longest names. Long names are hard to remember and use, so a shallow hierarchy tends to be more usable.

You should avoid representing your organization in too much detail, with many levels of organizational or geographical unit. A common mistake is to design DITs which have many levels of organizational entry, so that entries’ names are useful information in their own right. This approach makes names longer, harder to memorize, less stable, and requires more processing for each attempt to find entries. A hierarchy with few levels provides shorter names that are likely to be more stable and manageable, and easier to remember.

Therefore, when you are analyzing your organizational structure and distribution, avoid including every tiny detail. Only subdivide a given unit if it will make the DIT more manageable or help minimize the probability of name clashes.

When deciding how many levels of entry to implement, there is no requirement for your DIT to be symmetrical: one part of your DIT can have more levels of entry than another.

Avoid Using a Confidential Structure

Remember that if you connect your organization’s X.500 Enterprise Directory to other X.500 Directory Services, the names of your entries will be visible to people outside of your organization.

Therefore, use an organizational structure that you do not mind being exposed to external organizations. For example, if you have a design department that includes groups working on sensitive projects, you might prefer not to subdivide your DIT beyond the level of the design department.

4.1.1. Representing Hierarchy as Attributes of an Entry

When you design your DIT, you might want to include several levels of organizational unit or geographical division so that an entry’s position in the DIT is fully representative of a resource’s position in your organization. However, as Section 4.1, “DIT Planning Considerations” explains, there are several reasons why you should not represent your organizational hierarchy in too much detail. Instead, you can use attributes of a given entry to represent organizational or geographical details.

For example, instead of creating a detailed hierarchy of entries representing organizational units or geographical areas as superiors of an entry representing an employee, you could use the optional organizationalUnitName and localityName attributes within the employee’s entry itself. The effect of this would be to reduce the depth of your DIT, as illustrated in Figure 4.5, “Two Ways to Represent Organizational and Geographical Details”.

The example on the left represents all organizational units and localities as entries in their own right, and the entry representing Alfred Shaw includes attributes for his surname, title, and telephone number. The example on the right places Alfred’s entry beneath only one organizational unit entry, and all the other details are represented as attributes of his entry, along with his surname, telephone number, and title. In the example on the left, Alfred’s entry has five superior entries, whereas on the right, Alfred’s entry has only two superior entries. Therefore, the distinguished name of the entry on the left would be longer than that of the entry on the right.

VSI recommends that you follow the example on the right, so that you can implement a DIT with as few levels of hierarchy as possible. When you have made a rough plan of how to represent your organization, review it to see whether all of the levels of hierarchy and geography are really necessary.

Remember that not all users are equally familiar with the hierarchical structure of different parts of your organization. Avoid using levels of hierarchy that are unfamiliar to users, since this does not help them to find information.

Having decided how to represent your organizational hierarchy, you need to plan exactly how to represent the organizational divisions and resources as X.500 directory entries. When you create an entry, you must specify what class of entry it is. The class of an entry determines what attributes it can have.

You need to choose a structural class that provides the attributes appropriate to each type of object. A structural class is a class that provides the basis of an entry. All entries must belong to a structural class, and once created cannot be modified to belong to any other structural class.

Your planning task is to decide which of the structural class definitions in the schema best represents each of your objects. If there is no structural class suitable for a given type of object, then you need to define a new structural class. However, for several types of object, the international standards bodies have provided useful definitions. By using these predefined structural classes, you improve your ability to interwork with other organizations’ Enterprise Directories.

The predefined structural classes are probably not perfect matches for the information that you require, but they provide a good foundation. You can then define auxiliary classes which enable you to use extra attributes that are not defined for the structural classes. An entry can belong to more than one auxiliary class, in addition to its structural class.

For example, the predefined structural class organizationalPerson permits you to use several attributes that the standards bodies considered would be useful. However, it is likely that your organization has some information that it would like to store about people, for which this structural class does not allow. You can therefore define an auxiliary class that permits the use of those extra items, and use the auxiliary class with the structural class. Chapter 6, Customizing the Schema explains this option in more detail.

The following list explains which structural class from the default schema is most suitable for a given type of object:

If you have objects that do not fall into any of the above categories of object, then you will need to define some completely new structural classes. Defining structural classes is a complex task, so use standard definitions if at all possible. Chapter 6, Customizing the Schema describes how to define a structural class.

When you choose classes to represent your objects, refer to the schema definitions for details of permitted structural rules between classes of entry. For example, there is a structure rule that states that an organizationalPerson entry is only permitted beneath entries of the organizationalUnit, locality, or organization classes.

If you have planned your DIT according to the advice at the beginning of this chapter, then you should find that the definitions do permit the hierarchy that you want. If not, you need to reassess your DIT hierarchy so that it does not conflict with the structure rules, or else to redefine the schema so that a different set of structural rules is allowed. For ease of implementation, VSI recommends that you use the structural rules permitted by the default schema, because redefining structure rules is complicated.

Figure 4.6, “The Most Frequently Used Default Structure Rules” illustrates the structure rules that VSI recommends you to use within your organization’s DIT. There are further possible relationships between these classes, which are illustrated in Appendix A, Default Schema Definitions. However, you should find that the relationships illustrated below are sufficient.

Each arrow in Figure 4.6, “The Most Frequently Used Default Structure Rules” represents a permitted relationship between entries, such that the arrow points from a class of entry to a permitted subordinate of that class of entry. For example, an organizationalPerson entry is permitted as a subordinate of an organization entry, or an organizationalUnit entry, or a locality entry. There are no permitted subordinates of an organizationalPerson entry.

Note that organizationalUnit and locality have arrows that loop back to themselves. This represents the ability of entries of those classes to be superior to further entries of the same classes, permitting distinguished names such as /C=US/O=Abacus/OU=Sales/OU=Metals/CN="Jo Brownly".

The DIT that you plan for objects within your organization is (or will become) part of a larger, global DIT.

By contacting a national or regional authority that is responsible for assigning names within the region in which your organization is based, you can make your DIT part of a global DIT. The role of the authority is to ensure that no two organizations have the same name. All entry names within your organization’s DIT can then be guaranteed to be globally unique, and it becomes possible for different organizations to refer to each other’s entries without ambiguity.

When you refer to such an authority, they will tell you how your DIT should fit into the global DIT. It is likely that the position of your DIT within the global DIT will mean that your directory entries are all subordinate to an entry representing your country, and perhaps an entry representing a region or state within your country. This means that the distinguished names of all of your organization’s entries will include relative distinguished names that are not planned by you.

The names of these superior entries form a global prefix to the names of your entries, and you need to know this prefix before you configure your Enterprise Directory.

For example, the highest entry in the Abacus DIT is called organizationName=Abacus. The Abacus organization is based in the United States. The Abacus organization contacts the authority responsible for assigning names in the United States, and are told that the Abacus DIT must be subordinate to an entry called countryName=US. Thus, the distinguished name of every entry in the Abacus DIT includes the relative distinguished name countryName=US. Figure 4.7, “The Abacus DIT with its Global Prefix” shows the relationship between that country entry and the DIT planned by the Abacus organization.

It is important to understand that the country entry is not part of the Abacus DIT, it is only a prefix. When the Abacus organization creates entries, it does not create any entries that are part of the prefix.

In this example, there is only one superior entry to the Abacus DIT, but there could be more. Some authorities will subdivide their country into regions, in the same way as Abacus divided its organization into organizational units and localities. For example, Abacus might have discovered that its DIT was subordinate to an entry called /C=US/locality=Florida. Thus, the names of all Abacus entries would include those two relative distinguished names.

When you refer to an authority, you also need confirmation that no other organization in your region has already registered the same organization name.

Once you have planned how your organization’s DIT fits into the global DIT, and what your DIT’s prefix is, you are ready to proceed to Section 4.4, “Naming Your Entries”, which explains how to name the entries in your DIT.

Having defined a policy for the representation of all types of entry, and planned any new class and attribute definitions that you need, the final task is to define a policy for naming entries as you create them.

When you create an entry, you must specify at least one attribute value to form the entry’s RDN.?

The chosen attribute becomes the RDN of the entry. When you choose the RDN for an entry, there are several things to consider.

Firstly, the definition of the entry’s object class states that the RDN must be chosen from particular attributes. For example, the schema’s naming rule for the locality object class states that the RDN must be a value of the localityName attribute. If you try to use any other attribute of the entry, the attempt to create the entry fails.

For most standard classes of entry, the attribute that you use for naming is the commonName attribute. Table 4.1, “Naming Attributes of Commonly Used Classes” lists the most frequently used exceptions.

Secondly, because the value that you choose is used as part of the distinguished name of the entry, and appears as part of the distinguished name of any entry subordinate to it, you should choose a value that is short and familiar to users. For example, if you want to create an entry to represent the locality Massachusetts, you need to decide whether to use the value Massachusetts, or the accepted abbreviation MA as the RDN.

Similarly, if your organization is international, you need to decide which language to use for the naming of some entries. For example, if you have an office in Munich, you need to decide whether to use the value Munich or München. The localityName attribute can be multivalued, and therefore can have both of the values, but only one of them can be used as the RDN. You should try to choose the value that you think users are most likely to use, recognize, and remember.

Figure 4.8, “The Abacus DIT with its Entries Named” shows the Abacus DIT plan after names have been chosen for entries.

VSI recommends that you represent your HP DSAs as directory entries of the decDSA class. This is recommended for four main reasons:

For these reasons, it is strongly recommended that you create decDSA entries, so that your DSAs cooperate openly with each other, yet provide a service that is adequately protected against certain types of request from unknown or untrusted DSAs and their users.

The decDSA class can also be used to represent other vendors’ DSAs. If you follow the same guidelines when creating entries to represent other vendors’ DSAs, then it becomes possible for your HP DSAs to consider other vendors’ DSAs to be trusted.

There is an alternative method for implementing security for your Directory Service. You can use NCL commands to configure trust. However, that method has some disadvantages. See Section 7.7, “Alternative Method of Controlling Access to DSAs” for details of the alternative method of configuring trust, and its disadvantages.

Even if you decide to use the alternative method, you should still plan DSA entries, because they also contain protocol and addressing information. The following sections describe how to plan these decDSA entries.

4.5.1. Recommended Position of DSA Entries in Your DIT

For ease of management, VSI recommends that you represent your DSAs as subordinates of the highest entry in your organization’s DIT. For example, the Abacus organization would create its DSA entries as subordinates of the directory entry called /C=US/O=Abacus.

The reason for this recommendation is that it simplifies the task of making the entries easily accessible to all DSAs. It is not essential that you name your DSA entries as immediate subordinates of your highest entry, but it greatly simplifies configuration, and improves the performance of security checking during normal DSA operation. This documentation set assumes that you accept this recommendation.

The class of the DSA entries is decDSA. The naming attribute of decDSA entries is the commonName attribute. You can use any policy for choosing common names for DSAs, but VSI suggests that you incorporate the DSA’s node name, so that managers can easily see which DSA is installed on which node.

For example, the Abacus organization might have six DSAs, called:

/C=US/O=Abacus/CN="NodeA DSA"
/C=US/O=Abacus/CN="NodeB DSA"
/C=US/O=Abacus/CN="NodeC DSA"
/C=US/O=Abacus/CN="NodeD DSA"
/C=US/O=Abacus/CN="NodeE DSA"
/C=US/O=Abacus/CN="NodeF DSA"

For the purposes of the examples used in this manual, the naming convention for DSAs is simplified, as follows:

/C=US/O=Abacus/CN=DSA1
/C=US/O=Abacus/CN=DSA2
/C=US/O=Abacus/CN=DSA3
/C=US/O=Abacus/CN=DSA4
/C=US/O=Abacus/CN=DSA5
/C=US/O=Abacus/CN=DSA6

These DSA distinguished names are also known as application entity titles (AE titles). When you configure each DSA using NCL commands, the DSA’s distinguished name is specified using the AETitle attribute of the DSA entity.

Figure 4.9, “DSA Entries Beneath the Organization Entry” shows the position of DSA entries in the Abacus DIT, as subordinates of the organization entry. The DSA entry called /C=US/O=Abacus/CN=DSA1 is shown, and the other five DSA entries are created in the same position relative to the organization entry.

Chapter 5, Planning DSAs to Hold Your Directory Information Tree includes an explanation of how to plan the DXIM commands that will create entries to represent your DSAs, and Chapter 8, Configuring DSAs explains when to use the commands. As with all directory entries, the ability to create the DSA entries depends on other configuration tasks described in Chapter 8, Configuring DSAs.

If you implement replication as recommended in Chapter 5, Planning DSAs to Hold Your Directory Information Tree and Chapter 8, Configuring DSAs, all DSAs will receive copies of the entries that represent DSAs. This enables all DSAs to interwork securely, because they use the attributes in the DSA entries to verify each other’s identities.

VSI recommends two ways of dividing your DIT into naming contexts, which are described in the following sections.

5.1.4. Distributing Naming Contexts

When you have divided your DIT, choose a master DSA for each naming context. A DSA can hold more than one naming context, but the total size of all naming contexts held on a DSA must not exceed its disk or memory capacity. Each DSA is responsible for responding to all requests to change any information for which it is the master DSA. Therefore, by assigning naming contexts to different master DSAs, you share the processing cost of keeping naming contexts up to date. On the other hand, by making one DSA the master DSA for all naming contexts, you centralize the management of the information. You need to decide where you want the master copy of each naming context to be.

Figure 5.2, “Distributing Naming Contexts to Their Master DSAs” shows how the four naming contexts from Figure 5.1, “Dividing a DIT into Naming Contexts” are distributed to four DSAs. This leaves some DSAs without a naming context. Those empty DSAs are to hold shadow copies of naming contexts only (see Section 5.1.5, “Replicating Naming Contexts”).

When you are distributing naming contexts to DSAs, consider the following factors:

• Try to put each naming context on a DSA that is easily accessible to the managers responsible for the directory entries they contain.

  Although the Enterprise Directory supports remote management of directory information, response times are best if the manager can connect directly to the master DSA that holds the relevant entries.

• Try to choose DSAs that are hosted by reliable systems.

  All modifications to directory entries require access to the master DSA that holds them. If the master DSA for a given entry is temporarily unavailable, attempts to modify the entry fail.

• The master DSA for your organization’s highest naming context (such as Naming Context A) needs to be installed on a node with good network accessibility.

  If you follow VSI’s recommendations, then that naming context contains the entries representing your DSAs. Those entries need to be accessible because HP’s DSAs refer to them and modify them automatically as part of normal operation. The efficiency of your Enterprise Directory depends on the accuracy of the information in your DSA entries.

For clarity, in Figure 5.2, “Distributing Naming Contexts to Their Master DSAs” and in all examples in this chapter, DSAs are identified by their last RDN, for example CN=DSA1. Real DSAs would have distinguished names such as /C=US/O=Abacus/CN=DSA1, but such names would make the following examples difficult to read and understand.

5.1.5. Replicating Naming Contexts

Having chosen master DSAs to hold each of your naming contexts (or your single naming context if your DIT is small enough), you can then choose any number of other DSAs to hold shadow copies of one or more of those naming contexts.

The purpose of replication is to place read-only copies of entries as near as possible to the users who require them most frequently, and to provide backup in case the DSA holding the master copy of a naming context becomes temporarily unavailable.

Your network could have many DSAs, most of which hold shadow copies only. You can have any number of shadow copies of a given naming context, although a given DSA only holds one copy of a given naming context.

Note

VSI strongly recommends that you give every DSA a shadow copy of the naming context that contains the highest entry in your organization’s DIT. This simplifies the configuration requirements of your DSAs (described in Section 5.2, “Planning DSA Configuration Information”), and improves the performance of search requests.

It also ensures that all of your DSAs have a local copy of the directory entries representing DSAs. This improves the performance of Enterprise Directory security checks, and ensures that each DSA has the information it requires for communicating openly with your other DSAs.

If you decide not to implement replication of decDSA entries to all of your DSAs, then you need to implement some additional DSA configuration to enable your DSAs to trust each other. Without either a copy of all decDSA entries or some additional management attributes, your users will find that requests that involve more than one DSA might fail. If you do not intend to implement replication as recommended, see Section 7.7, “Alternative Method of Controlling Access to DSAs” for details of the additional tasks.

A shadow copy of a naming context can be copied from the master DSA for that naming context, or from another shadow DSA for it. Thus, you can take shadow copies of entries (called primary shadowing), or shadow copies of shadow copies (called secondary shadowing).

Secondary shadowing enables you to spread the communication and processing costs of keeping shadow copies up to date. This is because each shadow DSA communicates with its supplier to ask for an update of the relevant naming context. Supplying shadow naming contexts requires considerable resources, depending on the size of the naming contexts being supplied. It also temporarily prevents the supplying DSA from answering some user requests, reducing the availability of directory information to end users. If the only supplier is the master DSA, then the master DSA spends a lot of its time communicating with shadow DSAs (consumers) simply to help them keep their shadow copies up to date. By allowing shadow DSAs to act as suppliers to further shadow DSAs, the processing cost of keeping shadow copies up to date is shared.

Figure 5.3, “Primary and Secondary Shadowing of Naming Contexts” illustrates how CN=DSA2 is a consumer of a naming context from CN=DSA1 (the master DSA of the illustrated naming context). However, CN=DSA2 is also a supplier of that naming context to CN=DSA3. The arrow leading from the naming context on CN=DSA1 means that the naming context has a consumer, and likewise for the arrow leading from the naming context on CN=DSA2. Thus, CN=DSA2 relieves CN=DSA1 of the cost of keeping CN=DSA3 up to date. The naming context held by CN=DSA3 is a secondary shadow copy.

Note

HP’s DSAs can only replicate directory information to and from other HP DSAs. You can have other vendors’ DSAs in your Enterprise Directory, but they cannot hold the same naming contexts as your HP DSAs.

Figure 5.4, “Replicating Naming Contexts to Their Shadow DSAs” shows how the four naming contexts from Figure 5.2, “Distributing Naming Contexts to Their Master DSAs” are replicated to other DSAs. The small naming context that is to contain the organization entry and the DSA entries is replicated to all DSAs. Each of the other naming contexts is replicated at least once according to the needs of the user communities near the various DSAs. Some of the DSAs have only shadow naming contexts, and some have a mixture of shadow naming contexts and master naming contexts. Some DSAs have more naming contexts than others, depending on DSA system capacity and the needs of the users local to each DSA. Note also that CN=DSA5 and CN=DSA6 have secondary shadows of the naming context containing the organization entry, supplied by CN=DSA3 rather than CN=DSA1.

Note that there are no empty DSAs. All DSAs now have at least one naming context.

To help you configure your DSAs to meet your distribution and replication requirements, VSI suggests that you create a worksheet for each system that is to host a DSA.

The following sections tell you how to fill out the worksheet. You might also find it useful to have an illustration like Figure 5.4, “Replicating Naming Contexts to Their Shadow DSAs” showing where you want each naming context to be, and with arrows showing the intended replication.

Having planned how to distribute and replicate your DIT across one or more DSAs, you need to plan the configuration details for each of your DSAs so that they fulfill their intended role within your Enterprise Directory.

Every DSA needs to know the following:

These items of information are called knowledge information, and many of them are manually configured. Knowledge information is represented using characteristic attributes of the DSA entity and its subentities. The different requirements are met by the following entities:

For each DSA, you need to plan which of these entities are required, and fill out a worksheet which will help you to configure them.

5.2.2. DSA Passwords

You need to choose a password for each of your DSAs. A DSA uses its password when communicating with other DSAs. For example, a DSA uses its password when it asks a supplier DSA to update its shadow copies, and when chaining a request on behalf of an authenticated user.

Note

DSA passwords are represented in two places: the Password attribute of the DSA entity in NCL, and the userPassword attribute of the decDSA entry that represents the DSA in the DIT.

When a DSA wants to make a secure connection to another DSA, it quotes the value of the Password characteristic attribute. The target DSA checks this value against the userPassword attribute of the decDSA entry. It is essential, therefore, that the two representations always match. If you ever change a DSA’s password, always change it in both the DSA entity and the decDSA entry.

The illustration below shows the worksheet for CN=DSA1 with the password filled in.

$ @SYS$STARTUP:DXD$DSA_CONFIGURE

ncl> SET DSA LDAP PORT 389

5.2.5. Naming Context Entities

A naming context is a subtree of the DIT. Each naming context held by a DSA is represented by a Naming Context entity. Without one or more Naming Context entities, a DSA would not know what entries it is expected to hold, and you would be unable to create the relevant part of your DIT.

Each DSA has one Naming Context entity for each naming context that it holds, either as a shadow DSA or as a master DSA. For example, CN=DSA2 in Figure 5.4, “Replicating Naming Contexts to Their Shadow DSAs” needs three Naming Context entities, although it is only the master of one naming context.

Amend your worksheets to list the naming contexts that each DSA is to hold. Section 5.1.3, “Assigning Names to Naming Contexts” explains how to determine the names of your naming contexts.

Figure 5.6, “Worksheet for CN=DSA2 Listing Naming Contexts” illustrates the worksheet for CN=DSA2 in Figure 5.1, “Dividing a DIT into Naming Contexts”. It indicates whether the DSA is the master DSA or a shadow DSA for each of its naming contexts.

The Naming Context entities for the master DSAs of naming contexts have to be created manually. The Naming Context entities for shadow DSAs of naming contexts are created automatically as a result of the replication process.

5.2.5.1. Planning Primary and Secondary Consumer Information

If you are not implementing replication, you do not need to read this section.

Having planned a Naming Context entity, you need to identify any consumers of that naming context (see Section 5.1.5, “Replicating Naming Contexts” for a discussion of consumers).

For example, CN=DSA1’s Naming Context entity (representing Naming Context A) requires consumer information that identifies each of CN=DSA2, CN=DSA3, and CN=DSA4. Each of those three DSAs is to be a consumer of that naming context directly from CN=DSA1 (see Figure 5.4, “Replicating Naming Contexts to Their Shadow DSAs”). They are primary shadows of the naming context.

Note that CN=DSA1 does not need to know about its secondary shadows; CN=DSA5 and CN=DSA6. Instead, CN=DSA5 and CN=DSA6 are consumers from CN=DSA3, so CN=DSA3 needs the consumer information.

When CN=DSA3 gets a copy of the Naming Context entity as a result of replication, you can add consumer access points to it. This is how you implement secondary shadowing.

Fill out your worksheets for each DSA to indicate the AE titles and presentation addresses of the DSAs that are to be consumer of each of its naming contexts (master or shadow).

Figure 5.7, “Worksheet for CN=DSA2 Listing Consumers” illustrates the worksheet for CN=DSA2 after information about one consumer DSA has been added.

In Figure 5.4, “Replicating Naming Contexts to Their Shadow DSAs” there is an arrow leading from each naming context to each of its shadows. Each arrow means that its naming context has a consumer, so you need as many items of consumer information for a given naming context as there are arrows. For CN=DSA2, only one of its naming contexts is consumed by another DSA (CN=DSA4 consumes a copy of naming context B), so it requires one item of consumer information for that naming context only.

Cross-check your DSA worksheets to ensure that each shadow DSA is listed as a consumer by each of its suppliers. For example, CN=DSA2 is a consumer of two naming contexts, so you would check the worksheets for CN=DSA1 and CN=DSA6 to ensure that they each list CN=DSA2 as a consumer of the relevant naming context.

The worksheets could also specify the details of each DSA’s suppliers. However, supplier details are automatically created on a consumer DSA during replication, so adding them to the worksheets is not essential. However, you do use the presentation address of a supplier when you replicate for the first time, so it is useful to make a note of them. Figure 5.8, “Worksheet for CN=DSA2 Listing Consumers” shows the worksheet for CN=DSA2 with the supplier details filled in for reference purposes.

5.2.6. Subordinate Reference Entities

If you are implementing your entire DIT as one naming context, you do not need to read this section.

Subordinate references serve two purposes:

• They provide DSAs with the information they need to locate naming contexts that they do not hold.

• They mark the boundaries between naming contexts, such that a DSA does not claim ownership of entries that actually belong in a naming context held by another DSA.

Your planning task is to identify which DSAs require the manual creation of Subordinate Reference entities. Subordinate references that mark the lower boundary of a naming context are always replicated with that naming context. Therefore, you only need to create the subordinate references on the master DSA for that naming context. Section 5.2.6.1, “Identifying Which DSAs Require Manually Created Subordinate References” explains how to identify which DSAs need the manual creation of Subordinate Reference entities.

5.2.6.1. Identifying Which DSAs Require Manually Created Subordinate References

Firstly, only master DSAs require the manual creation of Subordinate Reference entities. Any DSA that holds only shadow information requires no manual intervention.

For each master DSA, you need to consider each of its master naming contexts. Each master naming context that is immediately superior to another naming context requires a Subordinate Reference entity to that subordinate naming context. A given naming context may require multiple Subordinate Reference entities because it is immediately superior to several naming contexts.

This requirement applies regardless of whether the immediately subordinate naming contexts are held locally or remotely.

If you have followed VSI’s advice for dividing your DIT into naming contexts, you have only one naming context that has subordinate naming contexts.

The master DSA for that naming context requires you to create Subordinate Reference entities to mark the boundaries between the superior naming context and each of the subordinate naming contexts.

To return to the example DIT illustrated in Figure 5.1, “Dividing a DIT into Naming Contexts”, Naming Contexts B, C, and D are all immediately subordinate to Naming Context A. Therefore, CN=DSA1, the master DSA for Naming Context A (see Figure 5.4, “Replicating Naming Contexts to Their Shadow DSAs”), needs three Subordinate Reference entities that identify where naming contexts B, C, and D are held.

If you divided your DIT in a more complicated way, then you must consider the requirements of each master naming context that is superior to further naming contexts. For example, Figure 5.9, “A Multi-Layered Division of a DIT” illustrates a DIT that is divided into many layers of naming contexts. In this example, there are several naming contexts that have subordinate naming contexts, and therefore need subordinate references.

The disadvantage of this way of dividing your DIT is that you increase the amount of configuration that you need to do to ensure that all DSAs have a complete set of knowledge information. If any DSA has incomplete knowledge, it is likely that user requests for information will not be satisfied efficiently.

It is also possible that DSAs will not realise that some naming contexts exist, and that some entries will be created on the wrong DSA as part of the wrong naming context. To reduce the chance of having incomplete knowledge and to optimize performance, VSI recommends the simpler division of your DIT illustrated in Figure 5.1, “Dividing a DIT into Naming Contexts”.

Amend your worksheets to reflect your Subordinate Reference requirements. For each Subordinate Reference entity, make a list of the AE titles and the presentation addresses of the DSAs that hold a master or shadow copy of the naming context? to which the subordinate reference refers. Indicate whether each DSA referred to is the master DSA or a shadow DSA for the relevant naming context.

Figure 5.10, “Worksheet for CN=DSA1 Listing Subordinate Naming Contexts” illustrates the worksheet for CN=DSA1 after this information has been added.

dxim> create /C=US/O=Abacus/CommonName=DSA1 -
_dxim> attributes objectClass=(applicationEntity,dSA,decDSA), -
_dxim> trustedDSAname="/C=US/O=Abacus/CN=DSA1", -
_dxim> userPassword=unguessable-textstring, -
_dxim> paddr=’"DSA"/"DSA"/"DSA"/NS+49004005002B0AEBDB21,CLNS’

VSI’s schema is provided as a set of text files? with the file extension .SC.

To customize the schema, create a file with the file extension .SC in the relevant directory, for example, CUSTOMER.SC. Use this file to contain all of your definitions. Edit DXD$SCHEMA.SC, as appropriate, to make sure that your file is included whenever you run the schema compiler.

If you need to edit any of the schema files provided with the Directory Service, always make a copy of the file first, so that you can undo any mistakes easily. Ideally, you should experiment with the schema on a test system rather than on a production system.

The DSA and DXIM read the compiled schema during startup, so if you change the schema you need to stop and restart them.

-- this line is ignored during schema compilation

commonName ATTRIBUTE
           WITH ATTRIBUTE-SYNTAX stringSyntax (SIZE(1..64))
           EQUALITY MATCHING RULE caseIgnoreStringMatch
           ORDERING MATCHING RULE caseIgnoreStringMatch
           SUBSTRING MATCHING RULE caseIgnoreSubstringMatch
           APPROXIMATE MATCHING RULE initialWordApproximateMatch
           STORE NORMALIZED
           ::= {attributeType 3}

attributeName ATTRIBUTE
              WITH ATTRIBUTE-SYNTAX syntaxName [constraint]
              [EQUALITY MATCHING RULE matchingRuleName]
              [ORDERING MATCHING RULE matchingRuleName]
              [SUBSTRING MATCHING RULE matchingRuleName]
              [APPROXIMATE MATCHING RULE matchingRuleName]
              [SINGLE VALUED]
              STORE NORMALIZED | STORE ORIGINAL
              ::= {attributeType n}

The schema compiler reads the files included by DXD$SCHEMA.SC, and creates a single data file called DXD$SCHEMA.DAT. The schema file is required by the DSA and the DXIM utility.

During installation, a compiled version of the default schema data file is installed. The default schema contains standard object classes and attributes defined by international standards bodies and Enterprise Directory providers. If the default schema meets your requirements, you never need to use the schema compiler.

If you customize the schema, for example to define a new class, you need to recompile the schema, as follows.

$ SET DEFAULT DXD$DIRECTORY
$ RUN SYS$SYSTEM:DXD$SCHEMA_COMPILER.EXE

The compiled schema is created in the DXD$DIRECTORY directory.

If the schema compiler finds any errors in the schema text files, such as duplicate definitions or references to non-existent definitions, the compilation fails, and an error is displayed. Edit the files to fix any errors, and recompile.

After compiling the schema successfully, stop and restart the DSA as follows:

RUN SYS$SYSTEM:NCL
NCL> DISABLE DSA
NCL> DELETE DSA
NCL> CREATE DSA
NCL> ENABLE DSA

If the new schema is incompatible with the entries already in the DSA, the CREATE DSA directive fails, and issues a message identifying the definition that is missing from the schema. In this case, check your customizations carefully, correct any problems, recompile the schema, and repeat the sequence of commands as shown above for the relevant operating system.

If you want to run the DSA while you review and fix your customizations, copy the old schema data file back into position, and continue to use that. When reviewing your customizations, remember that the customized schema must continue to support all existing entries, as well as supporting the new classes and attributes that you define. If you really want to retire some definitions that are in use in the database, you need to delete any entries that are based on those definitions.

When you have customized the schema and restarted the DSA successfully, you should also stop and restart any DXIM processes so that they also read the new schema. If DXIM uses the same schema as your DSAs, then they can display information consistently, and allow you to create and modify entries based on the new definitions.

Many of the definitions you can make in the schema require a unique object identifier. The definitions that require object identifiers are:

Structure rule definitions have integer identifiers, but these are not required to be globally unique. Structure rule identifiers need only be unique within your schema. Other definitions have no identifier, or are not customer definable.

This section describes how to define an object identifier that uniquely identifies your organization’s schema customizations, and then a set of object identifiers for your organization’s attributes, classes, and name forms. If you do not ensure that your organization uses unique object identifiers for its schema customizations, there is a possibility that your definitions will clash with those of other organizations, causing interworking problems.

If there is a Enterprise Directory naming authority already established for your country or region, then you can refer to them and ask them to assign a unique object identifier to your organization’s schema customizations. If no such naming authority exists, then VSI’s schema files include an object identifier that you can use as the basis for unique object identifiers.

The schema file DEC.SC contains the following definitions:

customerSQMfacility OBJECT-IDENTIFIER ::= {dec-osi-directory 10}
customerIntTelNumber OBJECT-IDENTIFIER ::= {dec-osi-directory 11}

You use one of these definitions as follows:

You need to define either one of the above definitions. In either case, you can then use the unique identifier of your organization to make three further definitions, as follows:

abacusAttributeType OBJECT-IDENTIFIER ::= {abacusId 1}
abacusObjectClass OBJECT-IDENTIFIER ::= {abacusId 2}
abacusNameForm OBJECT-IDENTIFIER ::= {abacusId 3}

Having defined these three object identifiers, you can then use their descriptive names in your schema definitions of attributes, classes, and name forms. For example:

employeeNumber ATTRIBUTE
               WITH ATTRIBUTE-SYNTAX numericSyntax
               EQUALITY MATCHING RULE numericStringMatch
               SUBSTRING MATCHING RULE numericSubstringMatch
               STORE NORMALIZED
               ::= {abacusAttributeType 1}
abacusEmployee OBJECT-CLASS SUBCLASS OF top AUXILIARY
               MUST CONTAIN {
                    employeeNumber}
               MAY CONTAIN {
                    birthDate,
                    hireDate,
                    tmServer}
               ::= {abacusObjectClass 1}
dogNameForm NAME-FORM
            NAMES dog
            WITH ATTRIBUTES commonName
            ::= {abacusNameForm 100}

These object identifiers are guaranteed to be unique to your organization’s schema, and therefore will never clash with schema definitions of other organization’s whose Enterprise Directory you might connect to.

Having chosen a standard structural class, such as organizationalPerson to represent an object, and perhaps created entries using that class, you might decide that the class does not enable you to represent all of the information that you would like. Indeed, you might find that there is no standard structural class suitable for one of your types of object.

The following sections use case studies to illustrate how to plan extra information requirements, and then how to implement those plans.

Section 6.5, “Planning an Auxiliary Class” uses the example of employees to illustrate how to plan extra information for organizationalPerson entries.

Section 6.7, “Planning a Structural Class” explains how to plan a completely new structural class to represent an object for which there is no standard structural class.

Those two sections also describe any customizations you need to make to the schema files to provide user friendly displays of your new definitions in the DXIM utility.

In addition, Section 6.9, “Defining Search Filters and Filter Fields for the Windows Utility” describes how to customize or define user friendly search filters for use in the DXIM Find window. The purpose of the filter definitions is to reduce the amount of information that end users need to understand when they are searching the directory. If you do not intend to use the DXIM windows utility, then you do not need to read Section 6.9, “Defining Search Filters and Filter Fields for the Windows Utility”.

The Abacus organization wants to create X.500 entries to represent each of its employees. It has a list of information that it wants to represent in those entries, and has chosen the organizationalPerson class as a starting point.

The organizationalPerson class provides many useful attributes, but Abacus wants to represent a range of other information which is not provided for by that class. The list of other information that Abacus wants to represent is:

The personnel department stated a requirement for the first few attributes so that they could monitor employment trends; the time management application developers stated the requirement for the time management server name.

None of the attributes provided by the default schema meet these particular requirements. The Abacus planning team therefore has to plan how to extend the default schema so that the required information can be stored, and so that the newly defined attributes are permitted within entries of the organizationalPerson structural class.

To meet this requirement, the Abacus team define an auxiliary class called abacusEmployee. The auxiliary class can be used with all entries of the organizationalPerson structural class. The abacusEmployee class is to have four attributes, all of which are defined by Abacus.

For each of the new attributes, the planning team make a number of decisions, as follows:

Having planned the four new attributes that they want to use in employee entries, the Abacus team have to define the new attributes in the schema text files.

Section 6.5.1, “Defining an Auxiliary Class” describes how to edit the schema files to define an auxiliary class, and Section 6.5.3, “Defining Attributes” explains how to define new attributes.

classname OBJECT-CLASS SUBCLASS OF top AUXILIARY
     MUST CONTAIN {attribute [, attribute, ...]}
     MAY CONTAIN {attribute [, attribute, ...]}
     ::= {object-identifier}

abacusEmployee OBJECT-CLASS SUBCLASS OF top AUXILIARY
     MUST CONTAIN {
                   employeeNumber}
     MAY CONTAIN  {
                   birthDate,
                   hireDate,
                   tmServer}
     ::= {abacusObjectClass 1}

dxim> modify /c=us/o=abacus/ou=sales/cn="Jon Low" -
_dxim> add value objectclass=abacusEmployee -
_dxim> add attribute employeeNumber=1390921

dxim> create /c=us/o=abacus/ou=sales/cn="Jon Low" -
_dxim> attributes objectclass=(person,organizationalPerson,abacusEmployee), -
_dxim> surname=Low, employeeNumber=1390921

attributeName ATTRIBUTE
              WITH ATTRIBUTE-SYNTAX syntaxName [constraint]
              [EQUALITY MATCHING RULE matchingRuleName]
              [ORDERING MATCHING RULE matchingRuleName]
              [SUBSTRING MATCHING RULE matchingRuleName]
              [APPROXIMATE MATCHING RULE matchingRuleName]
              [SINGLE VALUED]
              STORE NORMALIZED | STORE ORIGINAL
              ::= {attributeType n}

commonName ATTRIBUTE
           WITH ATTRIBUTE-SYNTAX stringSyntax (SIZE(1..64))
           EQUALITY MATCHING RULE caseIgnoreStringMatch
           ORDERING MATCHING RULE caseIgnoreStringMatch
           SUBSTRING MATCHING RULE caseIgnoreSubstringMatch
           APPROXIMATE MATCHING RULE initialWordApproximateMatch
           STORE NORMALIZED
           ::= {attributeType 3}

favouriteSport ATTRIBUTE
               WITH ATTRIBUTE-SYNTAX stringSyntax (SIZE(1..64))
               EQUALITY MATCHING RULE caseIgnoreStringMatch
               ORDERING MATCHING RULE caseIgnoreStringMatch
               SUBSTRING MATCHING RULE caseIgnoreSubstringMatch
               APPROXIMATE MATCHING RULE initialWordApproximateMatch
               SINGLE VALUED
               STORE NORMALIZED
               ::= {attributeType 10007}


Sport ATTRIBUTE
      WITH ATTRIBUTE-SYNTAX stringSyntax (SIZE(1..64))
      EQUALITY MATCHING RULE caseIgnoreStringMatch
      ORDERING MATCHING RULE caseIgnoreStringMatch
      SUBSTRING MATCHING RULE caseIgnoreSubstringMatch
      APPROXIMATE MATCHING RULE initialWordApproximateMatch
      STORE NORMALIZED
      ::= {attributeType 10008}

surname ATTRIBUTE
        WITH ATTRIBUTE-SYNTAX stringSyntax (SIZE(1..64))
        EQUALITY MATCHING RULE caseIgnoreStringMatch
        ORDERING MATCHING RULE caseIgnoreStringMatch
        SUBSTRING MATCHING RULE caseIgnoreSubstringMatch
        APPROXIMATE MATCHING RULE initialWordApproximateMatch
        STORE NORMALIZED
        ::= {attributeType 4}

caseIgnoreStringMatch MATCHING-RULE
        WITH INDEX
        APPLIES TO
        stringSyntax, printableStringSyntax, countryNameSyntax
        ::= {matchingRule 21}


initialWordApproximateMatch MATCHING-RULE
        WITH INDEX
        APPLIES TO
        stringSyntax, printableStringSyntax
        ::= {decMatchingRule 3}

A label specifies alternative names for attributes, classes, and for DXIM windows (see Section 6.7.4, “Defining Window Definitions”).

Note that these labels affect DXIM and LDAP clients.

The alternative names improve the DXIM user interface, so that users and managers are not exposed to unfriendly, unpunctuated attribute names, such as stateOrProvinceName. A label can specify abbreviations and user friendly alternatives for long and unfriendly descriptive names. You can also use labels to provide foreign language support within DXIM.

The default schema includes labels for all attributes. Most labels are defined in DUA.SC, and you can customize them as much as you like.

The syntax of a label definition is as follows:

LABEL labelName
    [KEYWORD "keyword", "keyword", ...] [MENU "text"]
    [DESCRIPTION "text"]
END

All parts of a label are optional. You can specify more than one keyword, but only one menu label and one description label. Keywords must not contain spaces, and must use the printable string character set only.

Menu labels and description labels can contain spaces, but must also use the printable string character set.

The following example shows the label definition for the commonName attribute.

LABEL commonName
    KEYWORD "CN", "common", "Name"
    MENU "Name"
    DESCRIPTION "Common Name"
END

where:

If you do not specify a label for an attribute type, DXIM uses the string that uniquely identifies the attribute type definition. For example, if there is no label for the commonName attribute type, such as Common Name, DXIM uses the string commonName. This behaviour also applies to any other schema definitions that are displayed in the user interface, such as object class names, window names, filter names, and so on. Most definitions in the default schema have labels. You can modify these labels if you do not like the defaults, or if English is not your users’ first language.

This section demonstrates how to plan a new structural class when no existing classes are suitable for a given type of object that you want to represent.

The Abacus organization decides that it wants to represent dogs as directory entries. Many of the organization’s security guards own a guard dog, and the organization decides that it will be useful to have directory entries representing them.

No existing structural class is suitable for representing a dog, so Abacus decides to define a new class, and several new attributes.

The organization decide to define a structural class called dog. The dog class is not derived from any other class except top (from which all classes are derived). Its only inherited attribute is therefore the objectClass attribute (all classes inherit the mandatory and optional attributes of the classes from which they are derived).

The organization decide that the attributes of each dog are commonName, breed, birthDate, and handler.

The commonName attribute is a standard attribute provided by the default schema. It therefore requires no further planning, except to state that it is mandatory for a dog to have a common name.

The breed attribute is a new attribute. It is to be single-valued, mandatory, and have a printable string syntax.

The birthDate attribute is the same as the one planned in Section 6.5, “Planning an Auxiliary Class”, and requires no further planning except to state that it is optional for dogs.

The handler attribute is a new attribute. It is to be single-valued, optional, and have a distinguished name syntax. It is to contain the distinguished name of the security guard who is responsible for the dog.

Note that the organization deliberately reuses existing attribute definitions where possible, so that the amount of planning and implementation required is kept to a minimum, and so that information is represented as consistently as possible, even for different classes of entry. Defining new attributes for use with a structural class is the same as for an auxiliary class. Section 6.5.3, “Defining Attributes” explains how to define a new attribute.

The planners decide that all dog entries must be named using the commonName attribute. They need to define a name form for this rule. Section 6.7.2, “Defining Name Forms” explains how to define a name form for a new structural class.

The organization also decide that dog entries are to be created as subordinates of organizationalUnit or locality entries. They need to define some structure rules in the schema. Section 6.7.3, “Defining Structure Rules” explains how to define structure rules for a new structural class.

Section 6.7.1, “Defining a Structural Class” explains how to edit the schema text files to define a new structural class, such as dog. Section 6.7.4, “Defining Window Definitions” explains how to define a window definition for a new structural class.

Defining a label for a structural class is the same as for an auxiliary class. Section 6.6, “Defining a Label” explains how to define a label.

classname OBJECT-CLASS SUBCLASS OF superclass STRUCTURAL
    MUST CONTAIN {attribute [, attribute, ...]}
    MAY CONTAIN {attribute [, attribute, ...]}
    ::= {object-identifier}

dog OBJECT-CLASS SUBCLASS OF top STRUCTURAL
    MUST CONTAIN {
        commonName,
        breed}
    MAY CONTAIN {
        birthDate,
        handler}
    ::= {abacusObjectClass 100}

nameFormName NAME-FORM
    NAMES class
    WITH ATTRIBUTES attribute_list
    [AND OPTIONALLY attribute_list]
    ::= {object-identifier}

dogNameForm NAME-FORM
    NAMES dog
    WITH ATTRIBUTES commonName
    ::= {abacusNameForm 100}

dogNameForm NAME-FORM
    NAMES dog
    WITH ATTRIBUTES commonName, handler
    ::= {abacusNameForm 100}

dogNameForm NAME-FORM
    NAMES dog
    WITH ATTRIBUTES commonName
    AND OPTIONALLY handler, breed
    ::= {abacusNameForm 100}

structureRuleName STRUCTURE-RULE
        NAME FORM nameFormName
        ::= integer

organizationRootStructureRule STRUCTURE-RULE
        NAME FORM organizationNameForm
        ::= 3

structureRuleName STRUCTURE-RULE
        NAME FORM nameFormName
        SUPERIOR RULES ruleName [, ruleName, ...]
        ::= integer

organizationalPersonStructureRule STRUCTURE-RULE
        NAME FORM organizationalPersonNameForm
        SUPERIOR RULES
            organizationStructureRule, organizationRootStructureRule,
            localityStructureRule, localityRootStructureRule,
            organizationalUnitStructureRule
            ::= 7

dogStructureRule STRUCTURE-RULE
    NAME FORM dogNameForm
    SUPERIOR RULES
        organizationalUnitStructureRule,
        localityStructureRule, localityRootStructureRule
        ::= 10001

dogWindow WINDOW
          FOR CLASS dog NAMING ATTRIBUTES {
                commonName}
          ATTRIBUTES {
                breed, handler, birthDate}
          END

If you define a new structural class, then you might also want to define an alias class that mimics it.

For example, the default schema contains an alias class called organizationalPersonAlias which is designed to mimic the organizationalPerson structural class. This enables you to create alias entries that look as though they are organizationalPerson entries, but which are actually alias entries. The alias class is defined to have the same name form and structure rules as the structural class that it mimics.

The syntax of an alias class definition is as follows:

classname OBJECT-CLASS SUBCLASS OF alias ALIAS
    MUST CONTAIN {attribute [, attribute, ...]}
    MAY CONTAIN {attribute [, attribute, ...]}
    ::= {object-identifier}

where:

For example:

dogAlias OBJECT-CLASS SUBCLASS OF alias ALIAS
    MUST CONTAIN {commonName}
    ::= {abacusObjectClass 5}

The attribute commonName is specified because that is the attribute that is defined as the naming attribute of the dog structural class (see Section 6.7.1, “Defining a Structural Class”). The dogAlias definition could specify other attributes as mandatory or optional, but the purpose of an alias entry is only to provide an alternative name for another entry; not to hold information in its own right.

Because the alias class is defined as a subclass of the alias class, it inherits the aliasedObjectName attribute. This is the attribute that you use to hold the distinguished name of the entry for which you have created a given alias entry.

If you define an alias class, you need to define a name form and one or more structure rules. The definitions for these are the same as the name forms and structure rules of structural classes, and are described in Section 6.7, “Planning a Structural Class”.

There is no requirement for an alias class to have the same naming attributes as the class of entry that it is intended to provide an alias for. Similarly, there is no requirement for an alias class to have the same structure rules. In fact, there is no defined relationship between an alias class and any other class, and you could use an alias to provide an alias name for any other entry, regardless of class. For example, you could create a roleAlias class which you use to provide aliases for both organizationalPerson entries and organizationalRole entries.

Finally, when you define a new alias class, you need to define a window definition for it, so that the DXIM windows utility can display entries of this class consistently (see Section 6.7.4, “Defining Window Definitions”). You can also define labels for the alias class so that when its name appears on menus and screen displays, it looks user friendly (see Section 6.6, “Defining a Label”).

For example, the set of definitions required for an alias class that mimics the dog structural class (see Section 6.7, “Planning a Structural Class”), is as follows:

dogAlias OBJECT-CLASS SUBCLASS OF alias ALIAS
    MUST CONTAIN {
        commonName}
    ::= {abacusObjectClass 5}

dogAliasNameForm NAME-FORM
    NAMES dogAlias
    WITH ATTRIBUTES commonName
    ::= {abacusNameForm 5}

dogAliasStructureRule STRUCTURE-RULE
    NAME FORM dogAliasNameForm
    SUPERIOR RULES
        organizationalUnitStructureRule,
        localityStructureRule, localityRootStructureRule
    ::= 10002

dogAliasWindow WINDOW
    FOR CLASS dogAlias
        NAMING ATTRIBUTES {commonName}
        ATTRIBUTES {
                aliasedObjectName
                   }
        END

LABEL dogAlias
    KEYWORD "dogAlias"
    MENU "Dog Alias"
    DESCRIPTION "Dog Alias"
END

Note that the integer specified for the structure rule is in the range 10000 to 19999, as recommended in Section 6.7.3, “Defining Structure Rules”.

See Section 6.7.4, “Defining Window Definitions” for further details of window definitions. See Section 6.6, “Defining a Label” for further details of labels. See Section 6.7.2, “Defining Name Forms” for further details of name forms. See Section 6.7.3, “Defining Structure Rules” for further details of structure rules.

The DXIM Find window provides a simplified interface to the search services provided by the Enterprise Directory.

The purpose of the simplifications is to minimize the amount of X.500 knowledge required by end users of DXIM, making the windows utility suitable for end users as well as managers. A typical end user of the Directory Service might know a person’s name, but might not understand that a name can be represented using several different attributes.

The schema provided with the product includes user friendly filters for all of the classes defined in the default schema. If you define any new classes or attributes, then you probably need to customize the filters so that they support those new definitions.

All filters are defined in the schema file DUA.SC. There are actually two sets of definitions:

Depending on what customizations you make to the schema, you might want to create new filter definitions and/or new filter field definitions, or you might want to amend existing definitions.

Section 6.9.1, “Search Filter Definitions” explains the syntax and significance of filter definitions, and Section 6.9.2, “Filter Field Definitions” explains the syntax and significance of filter field definitions.

filtername FILTER
    WITH FIELDS {fieldname, fieldname, ...}
    [ AND VALUES
        {ATTRIBUTE attribute = "value", "value", ...}
    ]
END

organizationalPerson-filter FILTER
    WITH FIELDS {
        nameField,
        descriptionField,
        locationField
                }
    AND VALUES
        {ATTRIBUTE objectClass = "organizationalPerson" }
END

6.9.2. Filter Field Definitions

A filter field provides a user friendly interface to X.500 attribute types. A single filter field can map onto any number of attribute types, giving them the appearance of being one attribute. The end user therefore does not need to know exactly which attribute type is being used to store a particular item of information.

For example, the nameField maps onto a number of attributes: commonName, surname, title, organizationName, and organizationalUnitName. As far as the end user is concerned, all they need to specify is a "name".

If a user fills in a filter field, then the search only finds entries which have the specified value in at least one of the attribute types specified as being part of the filter field. For example, if the user specifies Name=Smith, then entries with a commonName and/or surname and/or title and/or organizationName and/or organizationalUnitName with the value Smith are found.

A filter field appears to the user as an input field on the right side of the DXIM Find window. Whatever the user types into that input field is processed by DXIM into a search request. The value specified by the user is searched for in all of the attributes listed in the filter field definition. Figure 6.1, “DXIM Find Window Showing Filter Fields” shows the DXIM Find window with several fields displayed. Each of the fields is listed within the filter definition for the Person filter.

The syntax of a filter field definition is as follows:

fieldname FILTER-FIELD
    ATTRIBUTES {attribute, attribute, ...}
END

where attribute is the name of an attribute that is included in this filter field.

For example, the default schema contains a nameField filter field:

nameField FILTER-FIELD
    ATTRIBUTES {commonName,
                surname,
                title,
                organizationName,
                organizationalUnitName}
END

To make the filter field name appear user friendly in the window, the schema also contains a label definition:

LABEL nameField
    MENU "Name"
END

See Section 6.6, “Defining a Label” for details of label definitions.

The definition of the filter field means that when a user supplies the value Jones, DXIM generates a search request that looks for entries that have the value Jones in any of the above attributes. This means that the user does not need to understand about different attribute types, and does not have to know which particular attribute to specify. As far as the user is concerned, the entry they are searching for simply has the name Jones, and DXIM supports this user expectation.

6.9.2.1. Customizing Filter Field Definitions

The most likely customizations to filter fields are as follows:

• To add another attribute to an existing filter field.

  If you define a new attribute (see Section 6.5.3, “Defining Attributes”) you might want to include it in an appropriate filter field.

• To create a new filter field.

  If you define a new filter field, you also need to define a search filter that uses it, or add the filter field to the list of filter fields for an existing search filter.

• To remove an attribute from a filter field.

  If a filter field contains attributes that you never use in your DIT, or that you do not want users to search on, then you can remove the attribute from the list. DXIM always searches for all of the listed attributes, so by reducing the list you can improve the performance of searches.

Note that a given filter field can be used by more than one search filter. If you decide to delete an attribute from a filter field, remember that the lack of that attribute might reduce the usefulness of the filter field in some of the search filters that use it.

Implementing access control is not mandatory; nor does access control have to be implemented immediately. HP DSAs have a default access control configuration that applies to all information until you decide to implement something different.

By default, HP’s DSAs allow everyone all access to all information except for the userPassword attribute. Users are not allowed to display passwords or search for them. For example, you cannot search for all entries with a specific password.

If this default level of access control is sufficient for your needs, then you do not need to read this chapter.

However, it is likely that you will eventually want to implement more restrictive controls, especially if other organizations will have access to your Enterprise Directory. If so, proceed to Section 7.2, “The Access Control Template File”.

To simplify the task of implementing non-default access control, VSI provides a template file. The template file contains two DXIM commands that, when completed and executed, create an access control subentry in your DIT. Your task is to specify the name of the access control subentry, and the directory names of the users who are to have management privileges.

If the template file does not meet your needs, you can customize it. You can change and execute the template more than once, if you decide that you need to change the access controls.

You can set up access control at the same time as you populate your DIT, or at any time afterwards.

To plan the name of the access control subentry, see Section 7.3, “Planning the Name of the Access Control Subentry”. If you want an overview of the access controls defined in the template file, see Section 7.4, “What the Access Control Template File Does”.

This section recommends a simple way to implement access controls. It assumes that you have planned your DIT as described in Chapter 4, Planning Your Directory Information Tree and illustrated in Figure 7.1, “Recommended Position for Creating an Access Control Subentry”.

Figure 7.1, “Recommended Position for Creating an Access Control Subentry” also shows the recommended position for the access control subentry. It is positioned immediately subordinate to the highest entry in the Abacus DIT. As such, the access control subentry is replicated as part of Naming Context A. Chapter 5, Planning DSAs to Hold Your Directory Information Tree recommends that your equivalent of Naming Context A is replicated to all DSAs.

The name of the access control subentry shown in Figure 7.1, “Recommended Position for Creating an Access Control Subentry” is C=US/O=Abacus/CN="Access Control".

In this example, none of the other three naming contexts contain an access control subentry. Any naming context that has no access control subentry can inherit? the access controls specified for a superior naming context that is held on the same DSA. Therefore, by replicating your equivalent of Naming Context A to all DSAs, you can ensure that all the other naming contexts inherit the same access controls.

Thus, creating one access control subentry entry in the recommended position has the following advantages:

Note that you could implement independent access controls for each naming context, but unless there is a security requirement to do this, or you have not followed VSI’s recommended replication model, it merely complicates the management of access control.

When you have decided where you need to create your access control subentry, and what its name will be, the only other thing that you need to plan is which users are to be information managers. Each directory information manager needs to be represented by a directory entry, and each of those entries needs a userPassword attribute. When you have all of this planned, you can complete and execute the template file as described in Chapter 11, Using the Access Control Template File.

If you want to know what access controls the file defines, see Section 7.4, “What the Access Control Template File Does”.

This section provides an overview of the access controls defined in the template file.

If these controls are suitable for your directory information, then all you need to do is insert the name of the access control subentry that the template file creates, and the names of people who are to have management access to the directory. You can then execute the file as described in Chapter 11, Using the Access Control Template File.

The template defines four access control information items (ACIitems), as follows:

VSI suggests that these four ACIitems should provide effective control to your directory information, at least until you have had time to understand the complexities of access control. Chapter 11, Using the Access Control Template File explains how to use the template file.

If the access controls specified by the template file do not meet your needs, you can customize the file, or create a completely different file.

If you want to customize access controls, you really need to understand:

This section provides an overview of how a HP DSA applies access controls to portions of its database, and how access controls are inherited from one portion to another.

The basic rules of X.500 access control supported by HP’s DSA are as follows:

For example, Figure 7.2, “Access Control in a DSA” illustrates a DSA that holds four naming contexts. The presence of an accessControlSubentry entry in a given naming context is represented by an entry marked ACI.

Naming Context W contains an accessControlSubentry entry with a prescriptiveACI attribute. Access to Naming Context W is defined by that entry.

Naming Context X does not contain an accessControlSubentry entry. However, it is directly subordinate to Naming Context W. It therefore inherits the access controls defined for Naming Context W.

Naming Context Y contains an accessControlSubentry entry. Access to Naming Context Y is defined by that entry. The fact that Naming Context Y is subordinate to Naming Context W has no effect on Naming Context Y because it has access controls of its own.

Naming Context Z does not contain an accessControlSubentry entry, and it is not subordinate to any naming context that does. Therefore, the DSA applies the default access controls to Naming Context Z.

This section explains how to implement security for accessing DSAs if you decide not to follow the recommended method.

The recommended method involves using decDSA entries as described in Section 4.5, “Planning Entries to Represent DSAs”, replicating them to all DSAs, as described in Section 5.1.5, “Replicating Naming Contexts”, and implementing access controls, as described in Section 7.1, “The Default Access Control”.

The advantages of implementing access controls as recommended are that:

It is also possible to implement a mixture of the recommended method and the methods described in the following sections. However, this makes diagnosing problems more difficult, as you need to understand how the various methods of control interact. It is therefore advisable to use only one method.

NCL> SET DSA TRUSTED DSA NAMES -
_NCL> {"/c=us/o=abacus/cn=DSA1", "/c=us/o=abacus/cn=DSA2"}

NCL> CREATE DSA ACCESSOR "/C=US/O=Abacus/CN=DSA2"-
_NCL> PASSWORD flobadob

NCL> SET DSA WRITER NAMES -
_NCL> {"/c=us/o=abacus/ou=sales/cn=Jon Mole" , -
_NCL> "/c=us/o=abacus/ou=sales/cn=Betty Hughes"}

NCL> SET DSA READER NAMES -
NCL> {"/c=us/o=abacus/ou=sales/cn=Jan Thorp" , -
_NCL> "/c=us/o=abacus/ou=sales/cn=Dave Hemmingly"}

NCL> CREATE DSA ACCESSOR "/C=US/O=Abacus/OU=Sales/CN=Jon Mole"-
_NCL> PASSWORD flimflam

The following sections explain some restrictions and requirements that you need to be aware of when you configure a DSA entity and its subentities, such as Naming Context entities and Subordinate Reference entities.

8.1.2. Configuring Entities of Different Types with the Same Name

If you need to create a Naming Context and a Subordinate Reference with the same name on the same DSA, you must create the Subordinate Reference first.

This situation applies to a DSA that is to hold contiguous master naming contexts, as shown in Figure 8.1, “Contiguous Naming Contexts”.

The DSA requires a subordinate reference to naming context Y, even though Y is to be held locally. The subordinate reference has the same name as the naming context to which it refers.

In such cases, you need to create the Subordinate Reference entity before you create the Naming Context entity of the same name. This restriction helps you to remember the requirement for the Subordinate Reference.

REASON: Has subordinates.
Description: The DSA already holds entries or entities subordinate
to the entity being created.

NCL> SET NCL TRANSPORT TCPIP

NCL> HELP DIRECTORY_MODULE

This version of the Enterprise Directory provides a DSA configuration utility.

The main benefit of this utility is that it configures a DSA’s presentation address, and sets the DSA’s LDAP port number to 389, rather than requiring you to plan and configure this manually.

The utility also sets a temporary AE title for a DSA, but you need to replace this temporary value with the value you planned in Section 5.2, “Planning DSA Configuration Information”. The temporary value enables you to start the DSA and experiment with it even before you have planned your final configuration properly.

If you have already used the DSA configuration utility, as described in Section 5.2.3, “DSA Presentation Addresses”, then there is no need to use it again.

You need SYSPRV and OPER privileges to run the configuration utility. To run the utility, type:

$ @SYS$STARTUP:DXD$DSA_CONFIGURE

The utility only sets an AE title for your DSA if the DSA does not already have one. It never overwrites an existing AE title. If the DSA has no AE title, the utility sets one based on the name of the DSA system.

If your privileges are insufficient, the utility displays an error message and exits.

Create a DSA entity on each system that is to host a DSA.

NCL> CREATE DSA

If the command fails, see VSI Enterprise Directory Problem Solving.

A created DSA can be configured, but needs to be enabled before it can receive connections from directory applications and other DSAs. Before you enable the DSA for the first time, you need to configure the planned AE Title and Password attributes. The DSA configuration utility (see Section 8.2, “Running the DSA Configuration Utility”) sets a temporary AE title which you need to replace with the planned value. You are also recommended to set the Volatile Modifications attribute to True. See Section 8.3.1, “Setting DSA AE Titles”, Section 8.3.2, “Setting DSA Passwords”, and Section 8.3.3, “Setting DSA Volatile Modifications” for details.

This version of the DSA uses memory image files rather than the snapshot files of previous versions. Memory image files provide superior startup and shutdown times, especially for very large databases.

Snapshot files are only supported for a small number of reasons:

For those occasions when you need snapshot files, the CREATE DSA and DELETE DSA commands support new options:

NCL> CREATE DSA FROM SNAPSHOT
NCL> DELETE DSA TO SNAPSHOT

If a given task requires a snapshot file, the documentation tells you what to do.

SET DSA AE TITLE "<AEtitle>"

NCL> SET DSA AE TITLE "/C=US/O=Abacus/CN=DSA1"

SET DSA PASSWORD "password"

ncl> SET DSA VOLATILE MODIFICATIONS TRUE

SET DSA PRESENTATION ADDRESS ’<paddr>’

NCL> SET DSA PRESENTATION ADDRESS ’"DSA"/"DSA"/"DSA"/NS+49200190400012,CLNS’

NCL> SET DSA PRESENTATION ADDRESS ’"DSA"/"DSA"/"DSA"/NS+490011AA0000021,CL NS|NS+37102251220021,CONS|RFC1006+11.22.33.44,RFC1006’

NCL> SET DSA LDAP PORT 389

A DSA can be either ON or OFF when you create a Naming Context entity. Remember that you must only create Naming Context entities for the naming contexts for which the DSA is the master DSA. Any naming contexts that are to be held as replicated copies are represented by entities that are created automatically during replication.

The syntax is:

CREATE DSA NAMING CONTEXT "<distinguished-name>"

where <distinguished-name> is the name of a naming context, in quotation marks. For example:

NCL> CREATE DSA NAMING CONTEXT "/C=US/O=Abacus"

Refer to the DSA worksheet to find out what naming contexts to specify for a given DSA. Remember that you must create subentities of the DSA in their order of hierarchical superiority (see Section 8.1, “Notes on Configuring a DSA”).

If the command fails, see VSI Enterprise Directory Problem Solving.

CREATE DSA NAMING CONTEXT "<distinguished_name>" -
  CONSUMER ACCESS POINT -
  {[AE TITLE = "<AEtitle>", PRESENTATION ADDRESS = ’<paddr>’]}

CREATE DSA NAMING CONTEXT "<distinguished_name>" -
  CONSUMER ACCESS POINT -
  {[AE TITLE = "<AEtitle>", PRESENTATION ADDRESS = ’<paddr>’], -
  [AE TITLE = "<AEtitle>", PRESENTATION ADDRESS = ’<paddr>’]}

To create a Subordinate Reference entity, use the following command syntax.

CREATE DSA SUBORDINATE REFERENCE "<distinguished-name>" -
 ACCESS POINT -
  {[AE TITLE = "<AEtitle>", PRESENTATION ADDRESS = ’<paddr>’]}, -
 COPY ACCESS POINT -
  {[AE TITLE = "<AEtitle>", PRESENTATION ADDRESS = ’<paddr>’]}

where <distinguished-name> is the name of a subordinate naming context in quotation marks, <AEtitle> is an application entity title in quotation marks of a DSA that holds the naming context, and <paddr> is the presentation address of a DSA that holds the naming context.

For example, the following command sets up a Subordinate Reference entity that provides a reference to the naming context called /C=US/O=Abacus/OU=Sales:

NCL> CREATE DSA SUBORDINATE REFERENCE "/C=US/O=Abacus/OU=Sales" -
_NCL> ACCESS POINT -
_NCL> {[AE TITLE = "/C=US/O=Abacus/CN=DSA2", -
_NCL> PRES ADDRESS=’"DSA"/"DSA"/"DSA"/NS+49AA001992AAA00000000,CLNS’]}, -
_NCL> COPY ACCESS POINT -
_NCL> {[AE TITLE = "/C=US/O=Abacus/CN=DSA4", -
_NCL> PRES ADDRESS=’"DSA"/"DSA"/"DSA"/NS+49AA001992AA900000000,CLNS’]}

The keywords PRESENTATION ADDRESS are abbreviated in this example, to save space.

The Access Point attribute contains information about the master DSA of the naming context for which this is a reference. The Copy Access Point attribute contains information about a shadow DSA for the subordinate naming context.

If you want to specify more than one Copy Access Point, because you know of more than one shadow DSA for the subordinate naming context, use the following syntax:

CREATE DSA SUBORDINATE REFERENCE "<distinguished-name>" -
 ACCESS POINT -
  {[AE TITLE = "<AEtitle>", PRESENTATION ADDRESS = ’<paddr>’]}, -
 COPY ACCESS POINT -
  {[AE TITLE = "<AEtitle>", PRESENTATION ADDRESS = ’<paddr>’], -
  [AE TITLE = "<AEtitle>", PRESENTATION ADDRESS = ’<paddr>’], -
  [AE TITLE = "<AEtitle>", PRESENTATION ADDRESS = ’<paddr>’]}

You need to specify at least one attribute for each subordinate reference, although it can be either an Access Point attribute or a Copy Access Point attribute.

Refer to the worksheet to find out what Subordinate Reference entities to create for a given DSA, and what presentation addresses and AE titles to specify for the attributes.

If the command fails, see VSI Enterprise Directory Problem Solving.

You can use the NCL SET, ADD, REMOVE, and SHOW directives to manage the access point information for the Subordinate Reference entity. For example, if a Subordinate Reference entity has a Copy Access Point attribute that contains an incomplete list of DSAs that hold copies of the naming context, you can use the ADD command to add further access points. Similarly, you can use the REMOVE command to remove access points from the list.

To create a Superior Reference entity, use the following command syntax:

CREATE DSA SUPERIOR REFERENCE -
 ACCESS POINT -
  {[AE TITLE = "<AEtitle>", -
    PRESENTATION ADDRESS = ’<paddr>’]}

where <AEtitle> is an application entity title, and <paddr> is a presentation address of a superior DSA.

For example, the following command sets up a superior reference for a DSA to a superior DSA called "/C=US/CN=National DSA":

NCL> CREATE DSA SUPERIOR REFERENCE -
_NCL> ACCESS POINT -
_NCL> {[AE TITLE = "/C=US/CN=National DSA", -
_NCL> PRESENTATION ADDRESS = ’"DSA"/"DSA"/"DSA"/NS+12341234123414,CLNS’]}

You only specify details of one superior DSA; multiple access points are not permitted. The superior DSA can be either a master DSA or a shadow DSA.

Refer to your worksheet DSA to find out what Superior Reference entity, if any, a given DSA requires.

If the command fails, see VSI Enterprise Directory Problem Solving.

The ENABLE DSA directive puts a DSA into state ENABLING. When the DSA has finished enabling, it goes into state ON. You cannot enable a DSA unless the AE Title and Presentation Address attributes are configured.

The command syntax is:

NCL> ENABLE DSA

When in state ON, a DSA can receive connections from directory applications and other DSAs. For example, you can use DXIM to bind to the DSA and create and display directory entries. In state ON, the DSA can also receive replication requests from other DSAs.

If the command fails, see VSI Enterprise Directory Problem Solving.

When you have configured the DSA that holds your organization’s highest naming context, you can create the directory entries that represent your DSAs. If you follow VSI’s recommendations, these entries are part of your highest naming context.

The DSA entries were planned in Section 4.5, “Planning Entries to Represent DSAs” and the DXIM commands that you use to create them were planned in Section 5.2.9.1, “Planning the DXIM Command to Create DSA Entries”. You can now create those entries, although you need to create their parent entry as well. For example:

If one or more of the DSA entries already exist, this is because HP DSAs attempt to create them automatically. This is not a problem.

When you have created all of the Naming Context entities and Subordinate References for a DSA, then the DSA is ready to be populated. Section 8.8, “Creating Directory Entries to Represent Your DSAs” shows how to begin populating your highest naming context to create the entries to represent your DSAs.

It is possible to configure and populate one naming context at a time, if you prefer. It is not advisable to populate a naming context before configuring the subordinate references related to that naming context.

The commands described in Section 8.3, “Creating DSAs” to Section 8.7, “Enabling DSAs” provide a distributed Enterprise Directory. Note that consumer information has not yet been configured, so replication is not yet implemented.

Also, only your equivalent of CN=DSA1 has a full set of knowledge about naming contexts held by other DSAs. The other DSAs are going to get these references automatically when they consume copies of the Naming Context called /C=US/O=Abacus. Section 8.10, “Implementing Replication” explains how to implement replication.

If you do not want to implement replication, then the alternative solution is to give each DSA a Superior Reference entity that identifies your equivalent of CN=DSA1. However, that solution greatly increases the workload of CN=DSA1, and if that DSA is unavailable for any reason, the usefulness of your whole Enterprise Directory is greatly reduced. By implementing replication as recommended, the workload of your Directory Service is shared by your DSAs, and performance is improved.

The example in Section 8.9.1, “Examples of Configuring DSAs” shows how the worksheet for CN=DSA1 (see Chapter 5, Planning DSAs to Hold Your Directory Information Tree) translates into a sequence of configuration commands.

8.9.1. Examples of Configuring DSAs

This section shows how the worksheets for CN=DSA1 (see Chapter 5, Planning DSAs to Hold Your Directory Information Tree) translates into a sequence of configuration commands.

The completed worksheet for CN=DSA1 is shown in Figure 8.2, “Worksheet for CN=DSA1”.

This DSA will be the master DSA for the highest naming context in the Abacus DIT. It will supply copies of that naming context to three other DSAs. However, consumer details will not be specified yet (see Section 8.10, “Implementing Replication”).

The DSA will have three subordinate references. Each of these includes details of the master DSA and all shadow DSAs for the three subordinate naming contexts.

The following sequence of NCL commands configures the DSA to implement these plans.

NCL> CREATE DSA
NCL> SET DSA AE TITLE "/C=US/O=Abacus/CN=DSA1"
NCL> SET DSA PRESENTATION ADDRESS -
_NCL> ’"DSA"/"DSA"/"DSA"/NS+49004005002B0AEBDB21,CLNS’
NCL> SET DSA LDAP PORT 389
NCL> SET DSA PASSWORD "unguessable-textstring"
NCL> CREATE DSA NAMING CONTEXT "/C=US/O=Abacus"
NCL> CREATE DSA SUBORDINATE REFERENCE "/C=US/O=Abacus/OU=Sales" -
_NCL> ACCESS POINT -
_NCL> {[AE TITLE="/C=US/O=Abacus/CN=DSA2", -
_NCL> PRES ADDRESS=’"DSA"/"DSA"/"DSA"/NS+49AA001992AAA00000000,CLNS’], -
_NCL> [AE TITLE="/C=US/O=Abacus/CN=DSA4", -
_NCL> PRES ADDRESS=’"DSA"/"DSA"/"DSA"/NS+49AA001992AA900000000,CLNS’]}
NCL> CREATE DSA SUBORDINATE REFERENCE "/C=US/O=Abacus/OU=Research" -
_NCL> ACCESS POINT -
_NCL> {[AE TITLE="/C=US/O=Abacus/CN=DSA6", -
_NCL> PRES ADDRESS=’"DSA"/"DSA"/"DSA"/NS+49AA001992AA220000000,CLNS’]} -
_NCL> COPY ACCESS POINT -
_NCL> {[AE TITLE="/C=US/O=Abacus/CN=DSA2", -
_NCL> PRES ADDRESS=’"DSA"/"DSA"/"DSA"/NS+49AA001992AAA00000000,CLNS’], -
_NCL> [AE TITLE="/C=US/O=Abacus/CN=DSA4", -
_NCL> PRES ADDRESS=’"DSA"/"DSA"/"DSA"/NS+49AA001992AA900000000,CLNS’]}
NCL> CREATE DSA SUBORDINATE REFERENCE "/C=US/O=Abacus/OU=Personnel" -
_NCL> ACCESS POINT -
_NCL> {[AE TITLE="/C=US/O=Abacus/CN=DSA5", -
_NCL> PRES ADDRESS=’"DSA"/"DSA"/"DSA"/NS+49AA001992AA300000000,CLNS’]} -
_NCL> COPY ACCESS POINT -
_NCL> {[AE TITLE="/C=US/O=Abacus/CN=DSA6", -
_NCL> PRES ADDRESS=’"DSA"/"DSA"/"DSA"/NS+49AA001992AA220000000,CLNS’]} -

The above commands provide CN=DSA1 with all of its knowledge information configuration. CN=DSA1 can now be enabled, as follows:

NCL> ENABLE DSA

DXIM can then bind to CN=DSA1, and populate the naming context for which it is the master DSA. See Chapter 9, Configuring and Running Directory Applications for details of configuring DXIM to bind to a DSA automatically.

When you populate your equivalent of the /C=US/O=Abacus naming context, remember to create decDSA entries, as described in Section 8.8, “Creating Directory Entries to Represent Your DSAs”.

This section describes how to implement replication for a typical Enterprise Directory. Note that replication cannot be guaranteed to succeed between DSAs with different schema. If you have customized the schema of any DSA, check that the same customizations have been applied to all DSAs (see Chapter 6, Customizing the Schema).

Figure 8.3, “Planned Replication of Naming Contexts” shows the planned replication between the six DSAs in the example Enterprise Directory discussed in Chapter 5, Planning DSAs to Hold Your Directory Information Tree.

The plan includes examples of primary and secondary shadowing.

When this plan is fully implemented, the following will all be true:

VSI recommends that the simplest way to reach that final state is to implement all of the replication plans for your equivalent of Naming Context A first.

Naming Context A contains the entries that represent your DSAs. As soon each DSA receives a copy of that naming context, it can verify the identities of all other DSAs, making further replication plans much easier to implement. This is one of the reasons why that naming context is replicated to all DSAs.

For the example shown in Figure 8.3, “Planned Replication of Naming Contexts”, the simplest sequence of tasks is as follows:

Replication of Naming Context A is now complete for all DSAs in the example Enterprise Directory. This means that all six DSAs can verify each other’s passwords, because they all hold copies of the decDSA entries.

All remaining replication can be implemented simply by adding the relevant Consumer Access Point attributes to Naming Contexts. Now that the DSAs can verify each other’s passwords, there is no need to use the UPDATE DSA directive to make DSAs replicate.

For example, to implement the replication plans for Naming Context B in Figure 8.3, “Planned Replication of Naming Contexts”, use NCL on CN=DSA2 to add a Consumer Access Point attribute with details of the planned consumer: CN=DSA4. When you add this attribute, CN=DSA2 automatically connects to CN=DSA4 and replication takes place almost immediately afterwards. There is no need to use the UPDATE DSA command on CN=DSA4.

dxim> search subordinates /C=US/O=Abacus -
_dxim> where objectClass=shadowingAgreement subentries local scope

/C=US/O=Abacus/CN="Consumer /C=US/O=Abacus/CN=DSA2 1"

/C=US/O=Abacus/CN="Supplier /C=US/O=Abacus/CN=DSA1 1"

dxim> show /C=US/O=Abacus/CN="Consumer /C=US/O=Abacus/CN=DSA2 1" -
_dxim> attribute shadowingFlags local scope
    /C=US/O=Abacus/CN="Consumer /C=US/O=Abacus/CN=DSA2 1"
    shadowingFlags = UseDOP+ConsumerInitiated+OtherTimes

dxim> show /C=US/O=Abacus/CN="Supplier /C=US/O=Abacus/CN=DSA1 1" -
_dxim> attribute shadowingFlags local scope
    /C=US/O=Abacus/CN="Supplier /C=US/O=Abacus/CN=DSA1 1"
    shadowingFlags = IsSupplier+UseDOP+ConsumerInitiated+OtherTimes

dxim> set <shadowingAgreement name> attributes -
_dxim> shadowingBeginTime=("0 010000", "0 070000", "0 130000", "0 190000"), -
_dxim> shadowingEndTime=("0 020000", "0 080000", "0 140000", "0 200000")

dxim> set <shadowingAgreement name> -
_dxim> attribute shadowingNextUpdate=19950705000000Z

dxim> set <shadowingAgreement name> attributes -
_dxim> shadowingFlags=UseDOP+IsSupplier+Onchange+OtherTimes

shadowingFlags=UseDOP+ConsumerInitiated+OtherTimes

dxim> set <shadowingAgreement name> attributes -
_dxim> shadowingFlags=UseDOP+ConsumerInitiated+OtherTimes

NCL> REMOVE DSA NAMING CONTEXT "/C=US/O=Abacus" -
_NCL> CONSUMER ACCESS POINT -
_NCL> {[AE TITLE = "/C=US/O=Abacus/CN=DSA5", -
_NCL> PRES ADDR ’"DSA"/"DSA"/"DSA"/NS+49aa001992aa30000000,CLNS’]}

The DISABLE DSA directive puts a DSA into state DISABLING, in which state it closes down its activities. When all activities have been terminated, the DSA goes into state OFF. For example:

NCL> DISABLE DSA

Disabling a DSA prevents it from receiving connections from directory applications and DSAs. This means that this DSA will not respond to user requests for information, and that it will not respond to other DSAs’ attempts to replicate information or modify shadowing agreements.

In state OFF, you can use NCL commands to manage attributes of the DSA. You cannot use the UPDATE DSA directive when the DSA is in state OFF.

The DELETE DSA directive removes a DSA from a system. For example:

NCL> DELETE DSA

A deleted DSA is no longer configurable, and is not available to respond to connections from directory applications or other DSAs.

The time taken for the DELETE DSA directive to complete depends on the amount of directory information held by the DSA.

This version of the DSA uses memory image files rather than the snapshot files of previous versions. Memory image files provide superior startup and shutdown times, especially for very large databases.

Snapshot files are only supported for a small number of reasons:

Different versions of the DSA may use different memory structures. A memory image file cannot, therefore, be supported through an upgrade. You need to make the DSA create a snapshot file shortly before an upgrade. The deinstallation procedure reminds you of this requirement if it finds no valid snapshot of the database.

For those few occasions when you need to use snapshot files, the CREATE DSA and DELETE DSA directives support a new command option:

NCL> CREATE DSA FROM SNAPSHOT
NCL> DELETE DSA TO SNAPSHOT

If a given task requires you to create a snapshot file, the documentation makes this clear, and reminds you of the command option required.

The installation card for OpenVMS systems explains that you can edit the system startup file to include the command that runs the Enterprise Directory startup file, SYS$STARTUP:DXD$COMMON_STARTUP.COM.

This file runs an NCL script file for starting the DSA. By default, the commands in that NCL script file are commented out. This means that the DSA is not created or enabled. This is because a DSA cannot be enabled until it has been configured, so the NCL commands would cause errors during every system startup.

After configuring a DSA, edit the DSA startup script SYS$STARTUP:DXD$DSA_STARTUP.NCL to remove the comment characters. Next time the system reboots, the DSA will start up automatically.

On clusters the file is installed in the system specific startup directory, and must be edited there.

The DUA configuration utility communicates with a DSA to find out its presentation address and AE title.

You need to run the utility on every system that runs DXIM, or the MAILbus 400 MTA. The DSA to which you want these applications to connect must be configured before you run the DUA configuration utility (see Section 5.2.3, “DSA Presentation Addresses”). The DSA may be on the same system as the applications, or remote.

The configuration utility contacts the relevant DSA to determine what values to use as DUA defaults. The DSA must be in state ON when you use the DUA configuration utility.

The configuration utility writes a DUA defaults file that includes the presentation address and AE title of a DSA on a specified node.

You need SYSPRV and OPER privileges to run the configuration utility. To run the utility, type:

$ @SYS$STARTUP:DXD$DUA_CONFIGURE

If your privileges are insufficient, the utility displays an error message and exits. Otherwise, the utility checks for the presence of both DECnet–Plus and RFC1006 on your system. Note that if both DECnet–Plus and RFC1006 are available, then the utility uses DECnet–Plus to connect to the DSA.

The utility then displays:

Enter the name of the node on which the DSA is located:

If the utility detects that there is a DSA installed on the local system, the local node name is offered as a default.

Specify the name of the DSA system and press RETURN. Note that there is no requirement for applications to use a local DSA, although that is more efficient. The option to use a remote DSA means that you can have applications on a system without a DSA.

When you specify a node name, the utility connects to the DSA on the specified system to find out what its presentation address and AE title are.

If DECnet-Plus is not present on your system, then the utility connects to the DSA using RFC1006. When using RFC1006 to connect to the DSA, the utility requests identifiers for the Upper Layer Selectors of the DSA’s presentation address:

Please enter the Upper Layer Selectors ["DSA"/"DSA"/"DSA"]

Note that the Upper Layer Selectors ["DSA"/"DSA"/"DSA"] are offered as a default. If you already know that these selectors are not used by the DSA, specify the correct selectors and press RETURN. If you do not know what selectors the DSA uses, press RETURN. It is most likely that the DSA uses the selectors shown by default.

Having contacted the specified DSA, the utility writes the information to DXD$DIRECTORY:DXD$DUA_DEFAULTS.DAT, displays a success message, and exits. If a file of that name already exists, a new version is created. No details from the existing version are included in the new version.

If the utility fails to contact the DSA on the specified node, or fails to obtain the presentation address and AE title information, it displays an error message, and asks whether you want to try a different DSA node. If you type yes, the utility asks you to specify the name of another node, and repeats the attempt to obtain defaults information and write a defaults file.

Having successfully used the utility to create a defaults file, you can invoke DXIM. DXIM automatically binds to the DSA whose details were written into the defaults file. This confirms that the defaults details are satisfactory.

Refer to Section 9.2, “System-wide DUA Defaults” for further details about the defaults file, and to Section 9.3, “DUA Defaults for Specific Users” for details of how an individual user can create and manage a defaults file for their own use of DXIM.

The configuration details that apply to a whole system are stored in the following file:

DXD$DIRECTORY:DXD$DUA_DEFAULTS.DAT

The file created by the configuration utility contains a number of defaults in addition to the presentation address and AE title. The following is a typical defaults file created by the utility:

DUA.KnownDSAs.paddr     = "DSA"/"DSA"/"DSA"/NS+490020001122ABA0012,CLNS
DUA.KnownDSAs.ae_title      = /C=US/O=Abacus/CN=DSA1
#DUA.PreferChaining         = true
#DUA.ChainingProhibited     = false
#DUA.LocalScope             = false
#DUA.DontUseCopy            = false
#DUA.DontDereferenceAliases = false
#DUA.ScopeOfReferral        = DMD
#DUA.TimeLimit              = 60
#DUA.SizeLimit              = 30
#DUA.Priority               = Medium
#DUA.DomainRoot             = /
#DUA.InitialEntry           = /

The # character at the beginning of most lines is a comment character. DXIM ignores lines that begin with a # character. By default, only the presentation address and AE title defaults are active. To use a particular default, specify the required value and remove the comment character from the line.

In addition to the list of defaults shown above, there are two defaults that you can add to the defaults file manually. These are:

DUA.AttributeSizeLimit     = integer
DUA.CopyShallDO            = True|False

Note that if you specify a given default more than once, only the first instance is ever used. If the first instance of a default is invalid, DXIM does not attempt to use a subsequent definition. There is no advantage in specifying more than one known DSA presentation address, for example.

Each default must be specified on a separate line, and must not wrap onto a second line.

The defaults that specify true or false are booleans, and you can change them from one value to the other. No other value is allowed for these defaults.

The DUA.ScopeOfReferral default specifies a restriction on any referrals returned by a DSA. The permitted values of this control are:

The DUA.ScopeOfReferral default means that when your DSA cannot satisfy a request, it can instead return a referral to the application, suggesting further DSAs to contact, but only suggesting DSAs within the specified scope.

The DUA.TimeLimit default specifies the number of seconds permitted for each user request to be answered. The value must be an integer no higher than 65535. The value 0 means that there is no time limit. By default, HP’s DSA imposes no time limit.

The DUA.SizeLimit default specifies the number of entries that can be returned for a single user request. The value must be an integer no higher than 65535. A value of 0 means that there is no limit on the number of entries that can be returned for a single request. By default, HP’s DSA imposes no size limit.

The DUA.Priority default specifies a default priority for all user requests. The permitted values are:

The DUA.DomainRoot default specifies a default prefix for all user commands that include incomplete distinguished names.

Use this control to specify the name of the entry at the top of your organization’s DIT, or of some entry within your organization’s DIT. The Abacus organization, for example, would edit this control to specify /C=US /O=Abacus. You can specify any valid directory name as the domain root.

This default enables a DXIM user to omit those terms from any distinguished name. For example, if the domain root is /C=US/O=Abacus, a DXIM user could use the following SHOW command:

dxim> show ou=sales/cn="Bryan Lea"

DXIM displays the entry /C=US/O=Abacus/ou=sales/cn="Bryan Lea".

The prefixing option also applies to distinguished names specified in attribute values. For example, you could specify an aliasedObjectName attribute as follows:

aliasedObjectName="ou=sales/cn=Bryan Lea"

The DUA.InitialEntry default specifies the name of a directory entry that is to be the default browse and search base for DXIM. By default, all commands apply to the initial entry, unless the user specifies otherwise.

As with DUA.DomainRoot, specify the name of the entry at the top of your organization’s DIT, or of an entry within your organization’s DIT.

If you do not specify a value for this default, DXIM uses DUA.DomainRoot as the initial entry. If neither default is specified, DXIM defaults to /, which might prove expensive, and might prevent the use of the DXIM Browse window.

The value of DUA.InitialEntry also provides a second prefixing option. For example, if the initial entry is /C=US/O=Abacus, a DXIM user could use the following command:

dxim> show ./ou=sales/cn="Bryan Lea"

DXIM displays the entry /C=US/O=Abacus/ou=sales/cn="Bryan Lea" The period character before the leading "/" is converted into the value of initial entry. This prefixing option cannot be used within attribute values, unlike the domain root.

The DUA.DomainRoot and DUA.InitialEntry controls are the ones that are most likely to need changing before you allow DXIM to be used by your user community.

The DUA.AttributeSizeLimit control enables you to specify a limit on the size of attribute values that you want returned in a request. This is useful if the DSA stores very large attributes. For example, the DSA supports the jpegPhoto attribute which can store images. If your directory application does not support the display of images, then you can set this control to ensure that images, which tend to be very large, are not returned. Specify the number of bytes that is to be the attribute size limit. The DXIM command line interface supports a maximum attribute size control that enables you to specify a limit interactively, to override the default. If you do not use this control, the DSA does not limit the size of attribute values it returns.

The DUA.CopyShallDo control enables you to indicate whether you want information from partial copies of entries. HP DSAs do not support partial copies of entries, so this control is only useful if you have another vendor’s DSA. Specify a default of TRUE or FALSE. If you do not use this control, the default setting is FALSE. The DXIM command line interface supports a partial information control that enables you to specify that partial information is acceptable interactively to override the default.

By default, all users are affected by the system-wide defaults file. Individual directory users might want to have their own definitions of some of the DUA defaults.

To provide an individual directory user with their own defaults for use of the directory, create a file in the user’s home or default directory, with the following name:

SYS$LOGIN:DXD$DUA_DEFAULTS.DAT

Edit the file to specify one or more of the following defaults:

DUA.DomainRoot
DUA.InitialEntry
DUA.Requestor
DUA.KnownDSAs.paddr

Note that none of the other defaults listed in Section 9.2, “System-wide DUA Defaults” are used in the user defaults file. If you specify them, they are ignored. The four defaults listed above, if present, override the values in the system defaults file. For example, the value of DUA.DomainRoot in a user defaults file overrides the value in the system defaults file.

See Section 9.2, “System-wide DUA Defaults” describes the DUA.DomainRoot and DUA.InitialEntry defaults.

The DUA.Requestor default specifies the distinguished name by which the user wants to be identified to the DSA. When the user invokes DXIM, the value of DUA.Requestor is passed to the Enterprise Directory.

Note that although the user’s name is passed to the DSA, their password is not. If the user is using the DXIM windows interface, they can use the Authenticate window. The Name field of that window is filled in automatically, so that the user only has to supply a password to achieve simple authentication. If the user is using the DXIM command line interface, they need to use the BIND command with the Password argument.

If there is no default requestor name in user defaults, then the Enterprise Directory treats the user as an unauthenticated, unnamed user. The user can still use the Authenticate window, or the DXIM BIND command to specify their name and password.

Note that the DUA.Requestor default is not specified in the system defaults file. DXIM only uses DUA.Requestor defaults specified in user defaults files.

The DUA.KnownDSAs.paddr default specifies the presentation address of a DSA. For example:

DUA.KnownDSAs.paddr = "DSA"/"DSA"/"DSA"/NS+490020001122ABA0012,CLNS

This is the presentation address of the DSA to which the DXIM windows interface binds on invocation for this user. It is also the default presentation address for the DXIM command line interface, so that when the user uses the BIND command, they do not need to type a presentation address. If there is no presentation address specified in user defaults, the default specified in the system defaults file is used.

If you want to configure the DXIM utility to use another vendor’s DSA, you might need to do this manually. If the other vendor’s DSA supports RFC1006 connections, and the DSA is running, then the configuration procedure might succeed.

However, if the configuration procedure fails, you need to find out the presentation address of the DSA, and edit the DUA.KnownDSAs.paddr parameter in the defaults file manually.

When you use the DXIM command line interface, you can use an initialization file in addition to the two defaults files. The initialization file is executed after DXIM has read the defaults files, and will override defaults specified in those files if appropriate. The initialization file must be created in your home or default directory.

The initialization file contains DXIM commands that are executed when you invoke the command line interface. For example, you could create an initialization file that contains a DXIM SET DEFAULT NO CHAINING command.

The initialization file has the following name:

SYS$LOGIN:DXD$DXIM.INI

The initialization file can contain any DXIM commands. For example:

bind to address "DSA"/"DSA"/"DSA"/NS+4900200011220000033,CLNS
set current /c=us/o=abacus/ou=sales

The example file uses a bind command to establish a binding to a particular DSA. It then defines a current entry, which overrides the value of DUA.InitialEntry. Refer to the DXIM online help for full details of these and other DXIM commands.

To run DXIM using the Motif windows interface, type one of the following:

$ DXIM
$ DXIM /INTERFACE=DECWINDOWS

To run DXIM using the command line interface, type the following:

$ DXIM /INTERFACE=CHARACTER_CELL

Note that /INTERFACE=DECWINDOWS is the default for OpenVMS systems.

You can also use DXIM from the shell or system prompt. For example, you can type:

$ DXIM SHOW /COUNTRYNAME=US ALL ATTRIBUTES

The presence of a DXIM command line means that it is not necessary to specify /INTERFACE=CHARACTER_CELL.

If you install the X.500 Lookup Client, then you need to run a configuration utility before you can use it.

Run the Lookup Client configuration utility, as follows:

$ @SYS$STARTUP:DXD$LUC_CONFIGURE.COM

Specify the name of the system that runs the DSA with a non-zero LDAP port.

The utility then prompts for a search base. Specify the name of an entry within your organization’s DIT. For example, you could specify the name of the highest entry in your organization’s DIT. Note that the Lookup Client uses a different convention for naming directory entries, such that an entry called /C=US/O=Abacus must be expressed as follows:

O=Abacus, C=US

The utility asks whether you want to specify another search base. Multiple search bases are supported by the Lookup Client windows interface. The search bases are offered as a menu enabling users to select a particular search base. The first search base you specify is the default search base, and is the only search base available to users of the Lookup Client command line interface.

Every time you specify a search base, the utility asks whether you want to specify another. When you have specified all of the search bases you require, type n, and the utility will exit.

The utility writes a defaults file called:

$ @SYS$SYSTEM:DXDLU.DEFAULTS

The defaults file is self documenting. The file defines what attributes the Lookup Client can display and manage, which attributes are searchable, how the Lookup Client handles search strings, what object class is searched for, what service controls to apply, and what fonts to use. For details of all of the defaults, refer to the defaults file. You can customize the file as described in the comments.

The defaults file applies to all users of the Lookup Client on the system, although individual users can make a copy of the file in their local area if they want a different set of defaults. When you invoke the Lookup Client, it checks for a defaults file in the areas defined by the $HOME environment variable, or SYS$LOGIN.

You can run the Lookup Client graphical interface as follows:

$ RUN SYS$SYSTEM:DXD$LOOKUP_MOTIF.EXE

You can run the command line interface as follows:

$ RUN SYS$SYSTEM:DXD$LOOKUP_CLI.EXE

On OpenVMS systems, you can define foreign commands for running the utility, for example:

$ DXDLU :== RUN SYS$SYSTEM:DXD$LOOKUP_MOTIF.EXE
$ DXDLUCLI :== RUN SYS$SYSTEM:DXD$LOOKUP_CLI.EXE

The online help for the utilities explains how to use them.

This section explains how to use a DXIM script file to populate a naming context. You do not have to populate the directory one naming context at a time, but it is a logical and efficient method. If you use script files, it may be useful to keep them for reference purposes.

This section explains how to create entries interactively using the DXIM management utility. Interactive entry creation is most suitable if you have a small number of entries to create.

When you create an entry interactively, it is less important that you bind directly to the master DSA for that entry. A small number of modifications can be passed to the relevant master DSA without inconveniencing the DSA to which you are bound.

If you have configured your DSAs correctly (see Chapter 8, Configuring DSAs) then whichever DSA you bind to will pass the request to the master DSA automatically. If this fails, then you need to find out which DSA has inaccurate or insufficient configuration, and correct it. It is important that your DSAs are configured correctly because an important part of the service they provide is the ability to pass requests to the correct DSA automatically.

Invoke DXIM using the DXIM shell or DCL command (see Section 9.6, “Running DXIM”). DXIM displays the dxim> prompt. If DXIM does not bind automatically using defaults information (see Chapter 9, Configuring and Running Directory Applications), use the DXIM bind command, for example:

dxim> bind to address <presentation_address>

where <presentation_address> is the network presentation address of a DSA.

If access controls are implemented, then the bind command can include your distinguished name and password. For example:

dxim> bind to address <presentation_address> -
_dxim> name /c=us/o=abacus/ou=sales/cn="Jon Hunter" password
Password>

Having bound successfully, type a DXIM command to create an entry:

dxim> create entry <distinguished_name> attributes <attr>=<value> ...

If the command fails, DXIM displays an error message. Refer to the DXIM online help for full details of the command syntax and of DXIM error messages.

To create an entry using the DXIM windows interface, use the Browse window to find the parent of the entry that you want to create. If you cannot find the parent entry using the Browse window, then you cannot create the new entry. If the entry configured to be the Browse base is not yet created, you cannot create any entries using the windows interface. The windows interface only allows you to create a new entry if it can find the parent entry.

If access controls are implemented, pull down the Directory menu and select the Authenticate option. Specify your distinguished name and password, and click on OK.

Click on the parent of the entry you want to create, and select the Create option from the Edit menu. Select a class of entry from the Create submenu. DXIM displays a Create window for that class of entry. Add values to the various attributes. Remember to supply values for all mandatory attributes, and to specify naming attributes. When you have finished, click on the OK button. DXIM attempts to create the entry. If it fails, DXIM displays an error message explaining why. Amend the window to correct the errors, and click on OK again.

If you want to create several entries as subordinates of the same parent, all of the same class, and with several attribute values in common, you can click on the Apply button to create an entry. In this case, when DXIM creates the entry, it leaves the Create window on your screen. Amend the window to suit

the second entry you want to create, and then click on Apply again. Remember to change the naming attributes, otherwise DXIM displays an error stating that the entry already exists. You can repeat this process for any number of new entries of the same class with the same parent entry.

One of the features of a very large Enterprise Directory can be that entry administration becomes a very repetitive and time consuming activity. The DXIM command line interface provides facilities for managing multiple entries much more efficiently than the basic services allow.

Typical uses of these facilities are:

The key to many of these activities is the ability to select multiple entries based on a search filter. Having made a selection, you can then apply a management command to the selection. For example:

dxim> select /C=US/O=Abacus where surname=Smith
Number of entries selected is 14.

dxim> modify selected add value surname=Smyth

The first command selects a number of entries that match the specified search filter, and the second command applies a modification to all of those entries. This is clearly a lot easier than modifying each of the entries individually.

For full details of the activities listed above, see the online help for the DXIM command line interface.