| Preparations

## Contents of the Directory

> Once you've set up the directory, or have directed your program to communicate with an existing directory, what sort of information can you expect to find there? You can get two kinds of information from the directory: bindings and attributes.

> The directory can be viewed as consisting of name-to-object bindings. That is, each object in the directory has a corresponding name. You can retrieve an object in the directory by looking up its name. If you are using a naming service such as the file system (as you will be doing in some of this tutorial's examples), then the objects are files and they are bound to filenames.

> Also stored in the directory are attributes. An object in the directory, in addition to having a name, also has an optional set of attributes. You can ask the directory for an object's attributes, as well as ask it to search for an object that has certain attributes.

> This trail gives examples of accessing both kinds of information. The specifics of exactly what you can access from a naming or directory service depend on how the particular service has been laid out and what information has been added into it.

> #### Directory Schema

> A schema specifies the types of objects that a directory may contain. This tutorial populates the directory with entries, some of which require special schema definitions. To accommodate these entries, you must first either turn off schema-checking in the server or add the schema files that accompany this tutorial to the server. Both of these tasks are typically performed by the directory server's administrator.

> This tutorial comes with two schema files that must be installed:

> - Schema for Java objects
> - Schema for CORBA objects
> The format of these files is a formal description that possibly cannot be directly copied and pasted into server configuration files. Specifically, the attribute syntaxes are described in terms of RFC 2252.

> Different directory servers have different ways of configuring their schema. This tutorial includes some tools for installing the Java and CORBA schemas on directory servers that permit their schemas to be modified via the LDAP. It also includes tools for updating an existing directory that has older versions of these schemas. Following is a list of tasks the tools can perform.

> 1. Create Java Schema
> 2. Create CORBA Schema
> 3. Update directory entries that use an outdated Java schema
> 4. Update directory entries that use an outdated CORBA schema
> Follow the instructions in the accompanying README file to run these programs.

> > Note 1: If you are using Netscape Directory Server 4.1, then you must update the schema.

> > If you are updating the schema by manually updating its configuration files, then first locate the `java-object-schema.conf` file in the server installation at the directory named

> > > NETSCAPE-DIRECTORY-HOME`/slapd-`SERVER-ID`/config/`

> > The contents of `java-object-schema.conf` are out-of-date. You must replace them with the contents of the updated schema. See Note 2 for further instructions.

> > If you are updating the schema using the Java programs that accompany this tutorial, then first locate the `ns-schema.conf` file in the server installation at the directory named

> > > NETSCAPE-DIRECTORY-HOME`/slapd-`SERVER-ID`/config/`

> > Comment out the line that contains `java-object-schema.conf` because that schema is out-of-date. Restart the server and use the `CreateJavaSchema` program to install the updated schema. You need to manually remove the reference to the old schema from the list of built-in schemas in `ns-schema.conf`. This is because the server does not permit such built-in schemas to be modified via the LDAP.

> > Note 2: The Netscape Directory Server 4.1 has a different way of identifying attribute syntaxes than RFC 2252. For that server, you should use the following substitutions:

> > - "case ignore string" for the attributes with the Directory String syntax (1.3.6.1.4.1.1466.115.121.1.15)
> > - "binary" for the attribute with the Octet String syntax (1.3.6.1.4.1.1466.115.121.1.40)

> > Note 3: Windows Active Directory. Active Directory manages its schema by using an internal format. To update the schema, you can use either the Active Directory Management Console snap-in, `ADSIEdit`, or the `CreateJavaSchema` utility, following the instructions for Active Directory.

> #### Providing Directory Content for This Tutorial

> To set up the file system namespace, run the `Setup` program. This program creates a file subtree that provides a common frame of reference for discussing what to expect in terms of listing and looking up objects from the file system. To run this program, give it the name of the directory in which to create the tutorial test namespace. For example, typing the following

> >     # java Setup /tmp/tutorial

> creates a directory `/tmp/tutorial` and populates it with directories and files.

> In the directory examples in this trail, the results shown reflect how the LDAP directory has been set up using the configuration file (tutorial.ldif) that accompanies this tutorial. If you are using an existing server, or a server with a different setup, then you might see different results. Before you can load the configuration file (tutorial.ldif) into the directory server, you must follow the instructions for updating the server's schema.

> > Installation Note: Access Control. Different directory servers handle access control differently. Some examples in this tutorial perform updates to the directory. Also, the part of the namespace where you have installed the tutorial might have read access restrictions. Therefore, you need to take server-specific actions to make the directory readable and/or updatable in order for those examples to work. For the Netscape Directory Server, add the `aci` entry suggested in the `netscape.aci.ldif` file to the `dn: o=JNDITutorial` entry to make the entire directory readable and updatable. Alternatively, you may change the examples so that they authenticate to the directory. Details of how to do this are described in the Security Lesson

> > Installation Note: Namespace Setup. The entries in the tutorial.ldif file use the distinguished name (DN) "o=JNDITutorial" for the root naming context. If you have not configured your directory server to have "o=JNDITutorial" as a root naming context, then your attempt to import `tutorial.ldif` will fail. The easiest way to get around this problem is to add the DN of an existing root naming context to each "dn:" line in the `tutorial.ldif` file. For example, if your server already has the root naming context "dc=imc,dc=org", then you should change the line

> > >     dn: o=JNDITutorial

> > to

> > >     dn: o=JNDITutorial, dc=imc, dc=org

> > Make this change for each line that begins with "dn:" in the file. Then, in all of the examples in this tutorial, whereever it uses "o=JNDITutorial", use "o=JNDITutorial,dc=imc,dc=org" instead.

> > Installation Note: File Format. Depending on the operating system platform that you are using, you might need to edit `tutorial.ldif` so that it contains the correct newline characters for that platform. For example, if you find that `tutorial.ldif` contains Windows-style newline characters (CRLF) and you are importing this file into a directory server that is running on a Unix platform, then you need to edit the file and replace CRLF with LF. A symptom of this problem is that the directory server rejects all of the entries in `tutorial.ldif`.

> > Installation Note: Windows Active Directory.

> > 1. The root naming context is not going to be "o=jnditutorial". It will be of the form "dc=x,dc=y,dc=z". You need to follow the previous Namespace Setup note.
> > 2. Add the object classes and related attributes for the "inetOrgPerson" and "groupOfUniqueNames" object classes to the Active Directory schema by using the Active Directory Management Console snap-in, `ADSIEdit`. "groupOfUniqueNames" is defined in RFC 2256, "inetOrgPerson" in RFC 2798
> > 3. Some of hierarchical relationships used by the tutorial are not allowed by default in Active Directory. To enable these relationships, add them by using the Active Directory Management Console snap-in, `ADSIEdit`.

> >    >     objectclass: organizationalUnit
> >    >     possible superiors: domainDNS
> >    >                         inetOrgPerson
> >    >                         organizaton
> >    >                         organizationalPerson
> >    >                         organizationalUnit
> >    >                         person
> >    >                         top

> >    >     objectclass: groupOfUniqueNames
> >    >     possible superiors: top

> >    >     objectclass: inetOrgPerson
> >    >     possible superiors: container
> >    >                         organizationalPerson
> >    >                         person
> >    >                         top

> > 4. Delete one of the two "sn" attributes from the Mark Twain entry in `tutorial.ldif`. Active Directory defines "sn" to be a single-valued attribute, contrary to RFC 2256.
> > 5. Use the `ldifde` command-line utility to load the modified `tutorial.ldif` file.

> >    >     # ldifde -i -v -f tutorial.ldif

> > 6. Most of the examples assume that the directory has been set up to permit unauthenticated read and update access. Your Active Directory setup might not allow you to do that. See the Access Control installation note.
> > 7. Reading an entry sometimes produces more attributes than are shown in the tutorial because Active Directory often returns some internal attributes.
> > 8. Creation of entries might require the specification of additional Active Directory-specific attributes or the use of other object classes.

| Preparations