You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 20 Next »

Add your first elements to the schema

This section shows how to define custom schema elements, and how to add them to an ApacheDS 1.5.0 instance.

Motivation

The schema of an LDAP server is comprised of object classes, attributes, syntaxes and matching rules. Basically it defines which entries are allowed within the server and how the server should handle them. In contrast to the 1.0 release, ApacheDS 1.5.0 comes with a completely redesigned schema subsystem. It enables dynamic schema updates, like the creation of new attribute types or object classes at runtime (i.e. without restarting the server).

Is it always necessary to define my own schema elements?

No. ApacheDS comes with a comprehensive set of predefined, standardized schema elements (like inetOrgPerson). It is quite common to solely use the predefined schema. The same holds true for other directory servers, by the way.

In the following text the addition of user defined schema elements to the schema is described in tutorial style.

Browsing the schema of ApacheDS

LDAPv3 servers publish their schema via LDAP. Thus it is possible to list the schema elements with standard LDAP tools. For instance it is possible to use the ldapsearch command line tool to list all object classes 

$ ldapsearch -h zanzibar -p 10389 -D "uid=admin,ou=system" -w ****** \
     -b "cn=schema" -s base "(objectclass=subschema)" objectclasses
...
objectClasses: ( 2.5.6.6 NAME 'person' DESC 'RFC2256: a person' SUP top 
  STRUCTURAL MUST ( sn $ cn ) MAY ( userPassword $ telephoneNumber $ 
  seeAlso $ description ) X-SCHEMA 'core' )
...

The output (formatted as defines in RFC 2252) contains all things which are interesting to know about an object class (required attributes, optional attributes etc.), but is not easy to read by a human user. It is therefore often appropriate to use a GUI tool to browse the schema (which basically performs the same search operations but presents the output prettily). One option is Apache Directory LDAP Studio, an Eclipse based LDAP tool set which contains a powerful graphical Schema browser:

The techniques described above work for all LDAP v3 compliant servers. The ability to browse the schema gives us a chance to check whether our future changes to the schema really took please.

The schema subsystem of ApacheDS 1.5 stores the schema elements as entries in the DIT. You can find them within a special partition with suffix ou=schema; simply browse the content with your favorite LDAP Browser. With LDAP Studio, it looks like this:

Browsing the schema like this gives a good impression of the ApacheDS implementation of the schema subsystem and an even better way to analyze effects during schema updates. But keep in mind that the storage scheme is server dependent; not all LDAP server implementations store the schema elements in the DIT.

Which OIDs should you use?

If you plan to add custom schema elements, you need numerical OIDs (object identifiers) for them. If you implement schema elements defined somewhere else (like eduPerson), you can use the OIDs which are are part of their descriptions. But what if you plan to design your own?

Some OID background information

An OID is a string formed by a series of numbers which are seperated by a dot (like "12.4.1971.0.1"). Many elements in directory world use OIDs: Controls, extended operations and schema elements (like "2.5.6.6" for object class person). They identify these objects in a unique fashion and therefore avoid name clashes.

How is this accomplished? OIDs are assigned hierarchically: The owner of an OID is allowed to create new IDs by simply appending numbers. S/he is also allowed to delegate ownership of newly created OIDs to someone else. This way every person or organization is able to allocate an arbitrary number of new OIDs after obtaining one from "higher command", and they are still unique world-wide.

OIDs in the example

OIDs starting with 1.3.6.1.4.1 represent IANA-registered private enterprises, Apache Software Foundation for instance owns the OID 1.3.6.1.4.1.18060. The 1.3.6.1.4.1.18060.0 has been assigned to the Apache Directory project by the ASF, and we have decided to use the branch "1.3.6.1.4.1.18060.0.4.3" for schema elements used as examples in the documentation.

OIDs for your own custom schema elements

If you just want to play around with the schema subsystem, want to explore the capabilities, or learn about LDAP in general, you will probably not mind about unique OIDs. This is comparable to using self-signed certificates for SSL experiments. But it is nevertheless necessary that you use OIDs which are not used in the schema yet (otherwise addition will fail).

But if you plan to use your schema elements in a production environment (an object class for instance which describes employees with company specific attributes), or to ship your schema elements with a product (e.g. a CRM or portal solution), you should definitely use unique OIDs. In order to do this you have to obtain OIDs from a branch assigned to your company or organization (your network administrators will be helpful here, do not invent OIDs without asking or obtaining a branch from someone who owns the prefix OID). If your company or organization does not own on OID, there are several option to obtain one, one is the IANA (Internet Assigned Numbers Authority). It is also possible to get an OID branch as an individual.

Obtaining a PEN

You can ask for your own PEN (Private Enterprise Number) here : http://pen.iana.org/pen/PenApplication.page
It takes a few weeks to have a private OID assigned to you, so be patient, or do it early !

A simple example

The goal is to store ship entries in our directory, backing the "Seven Seas" example used throughout the Basic User's Guide. There are no schema elements shipped with ApacheDS covering our naval requirements. So we add some.

Here is a sample entry for a ship in LDIF:

dn: cn=HMS Victory,ou=ships,o=sevenSeas
objectClass: top
objectClass: ship
cn: HMS Victory
numberOfGuns: 104
description: a ship of the line of the Royal Navy
description: built between 1759 and 1765

A ship entry is comprised of a mandatory value for common name (cn) of the ship, description values and the number of guns (numberOfGuns). Thus a new object class ship and a new attribute type numberOfGuns have to be added to the schema. There are different ways to accomplish the task. In any case, we have to add the attribute type first, because the object class refers to it.

attribute type numberOfGuns

Here is the definition of our custom attribute type numberOfGuns formatted according to RFC 2252.

attributetype ( 1.3.6.1.4.1.18060.0.4.3.2.1 
 NAME 'numberOfGuns'  DESC 'Number of guns of a ship'
 EQUALITY integerMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 
 SINGLE-VALUE 
)

object class ship

Custom object class ship is defined as follows

objectclass ( 1.3.6.1.4.1.18060.0.4.3.3.1 
 NAME 'ship' DESC 'An entry which represents a ship' 
 SUP top STRUCTURAL 
 MUST cn MAY ( numberOfGuns $ description ) 
)

Using LDAP Studio to load the new schema elements

A very convenient way to add your own schema elements to Apache Directory Server is to use LDAP Studio. It is even possible to define/design them within the UI, but we opt here use a prepared file in RFC 2252 format and import it to LDAP studio. This is a good choice if you have the schema to add already described that way.

Our file sevenSeas.schema looks like this:

attributetype ( 1.3.6.1.4.1.18060.0.4.3.2.1 
        NAME 'numberOfGuns' 
        DESC 'Number of guns of a ship'
        EQUALITY integerMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 
        SINGLE-VALUE 
 )
objectclass ( 1.3.6.1.4.1.18060.0.4.3.3.1 
	NAME 'ship'
        DESC 'An entry which represents a ship' 
	SUP top 
	STRUCTURAL 
	MUST cn 
	MAY ( numberOfGuns $ description ) 
 )

In an Eclipse with the LDAP Studio plugins installed (or alternativly the standalone RCP application of LDAP Studio, if you prefer this), open the Schemas view.

When it is shown, press the Open a schema file button in the toolbar of it. In the file dialog, open the sevenSeas.schema. It is loaded and added to the schemas within the view.

Select Export For ApacheDS ... in the context menu of the sevenSeas elements. The schema will be stored in an LDIF file which can directly be imported into ApacheDS (we choose the file name sevenSeas.ldif).

Use LDAP Studio to open a connection to your ApacheDS server, bind as administrator, and select Import | LDIF Import ... in the context menu of the DIT. Choose the LDIF file previously stored, and import the file. Alternatively, you can use command line tools like ldapmodify to load the file. If no errors are displayed, you are done.

Using JNDI to add the schema elements programmatically

Adding the attribute type

import javax.naming.NamingException;
import javax.naming.directory.Attributes;
import javax.naming.directory.BasicAttributes;
import javax.naming.directory.DirContext;
import javax.naming.directory.InitialDirContext;

public class CreateAttributeType {

    public static void main(String[] args) throws NamingException {

        DirContext ctx = new InitialDirContext();
        DirContext schema = ctx.getSchema("");

        Attributes attrs = new BasicAttributes(true);
        attrs.put("NUMERICOID", "1.3.6.1.4.1.18060.0.4.3.2.1");
        attrs.put("NAME", "numberOfGuns");
        attrs.put("DESC", "Number of guns of a ship");
        attrs.put("SINGLE-VALUE", "true");
        attrs.put("SYNTAX", "1.3.6.1.4.1.1466.115.121.1.27");
        attrs.put("EQUALITY", "integerOrderingMatch");
        
        schema.createSubcontext("AttributeDefinition/numberOfGuns", attrs);
    }
}

Adding the object class

import javax.naming.NamingException;
import javax.naming.directory.Attribute;
import javax.naming.directory.Attributes;
import javax.naming.directory.BasicAttribute;
import javax.naming.directory.BasicAttributes;
import javax.naming.directory.DirContext;
import javax.naming.directory.InitialDirContext;

public class CreateObjectClass {

    public static void main(String[] args) throws NamingException {

        DirContext ctx = new InitialDirContext();
        DirContext schema = ctx.getSchema("");

        Attributes attrs = new BasicAttributes(true);
        attrs.put("NUMERICOID", "1.3.6.1.4.1.18060.0.4.3.3.1");
        attrs.put("NAME", "ship");
        attrs.put("DESC", "An entry which represents a ship");
        attrs.put("SUP", "top");
        attrs.put("STRUCTURAL", "true");
        
        Attribute must = new BasicAttribute("MUST");
        must.add("cn");
        attrs.put(must);
        
        Attribute may = new BasicAttribute("MAY");
        may.add("numberOfGuns");
        may.add("description");
        attrs.put(may);

        schema.createSubcontext("ClassDefinition/ship", attrs);
    }
}

Verification of the change

There are several options to check whether the additions has be successful. One is to use the browse techniques described above. You can also use specific search commands like this one:

$ ldapsearch -h zanzibar -p 10389 -D "uid=admin,ou=system" -w ****** \\
    -b "ou=schema" -s sub "(m-name=numberOfGuns)"
version: 1
dn: m-oid=1.3.6.1.4.1.18060.0.4.3.2.1,ou=attributeTypes,cn=other,ou=schema
m-usage: USER_APPLICATIONS
m-equality: integerOrderingMatch
objectClass: metaAttributeType
objectClass: metaTop
objectClass: top
m-name: numberOfGuns
m-oid: 1.3.6.1.4.1.18060.0.4.3.2.1
m-singleValue: TRUE
m-description: Number of guns of a ship
m-collective: FALSE
m-obsolete: FALSE
m-noUserModification: FALSE
m-syntax: 1.3.6.1.4.1.1466.115.121.1.27

Using the new schema elements

Resources

  • Internet Assigned Numbers Authority (IANA), http://www.iana.org
  • RFC 2252 Lightweight Directory Access Protocol (v3): Attribute Syntax Definitions
  • No labels