Chapter 13. Customizing Schema

Chapter 13. Customizing Schema

13.1. About Directory Schema
13.2. Default Schema Elements and Files
13.3. Creating Custom Schema
13.4. Exporting Schema
13.5. Importing Schema Files
13.6. Loading a Schema File Manually
13.7. Converting the Schema Formatting from OpenLDAP to OpenDS

This chapter describes the default schema included with Penrose Virtual Directory and explains how to create and load custom schema.

13.1. About Directory Schema

Schema is the way the LDAP directories like Red Hat Directory Server and Active Directory describe entries. The schema defines the type of entry in general through the object classes. Each object class has certain attributes, something which describes a part of the entry. For example, a person object class is for a general entry about a person. This has attributes for a person's first and last names and telephone number, all normal information to describe about a person.

The schema elements (object classes and attributes) which are available for Penrose Virtual Directory entries are loaded in schema files.

An attribute entry must define the following:

For example, this is the Penrose Virtual Directory schema entry for the displayName attribute:

# displayName
attributetype ( 2.16.840.1.113730.3.1.241
        NAME 'displayName'
        DESC 'RFC2798: preferred name to be used when displaying entries'
        EQUALITY caseIgnoreMatch
        SUBSTR caseIgnoreSubstringsMatch
        SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
        SINGLE-VALUE )

An object class entry must define the following:

  • An object identifier (OID)

  • The list of required (MUST) and allowed (MAY) attributes

  • Any superior object classes; a superior object class is an object class from which this object class inherits required and allowed attributes, without having to include those attributes in this object class definition

  • The function of the object class. STRUCTURAL defines the type of entry being created and there can be only one per entry. AUXILIARY is an object class which contains attributes that can apply to many different kinds of directory entries. An ABSTRACT object class is not used directly by an LDAP entry but is referenced as a subclass by a STRUCTURAL or AUXILIARY object class.

For example, this is the Penrose Virtual Directory schema entry for the inetorgperson object class:

# inetOrgPerson
objectclass     ( 2.16.840.1.113730.3.2.2
    NAME 'inetOrgPerson'
    DESC 'RFC2798: Internet Organizational Person'
    SUP organizationalPerson
    STRUCTURAL
        MAY (
                audio $ businessCategory $ carLicense $ departmentNumber $
                displayName $ employeeNumber $ employeeType $ givenName $
                homePhone $ homePostalAddress $ initials $ jpegPhoto $
                labeledURI $ mail $ manager $ mobile $ o $ pager $
                photo $ roomNumber $ secretary $ uid $ userCertificate $
                x500uniqueIdentifier $ preferredLanguage $
                userSMIMECertificate $ userPKCS12 )
        )

Penrose Virtual Directory schema files use the OpenLDAP schema formatting. This means that each schema file has the extension .schema and uses some of the default OpenLDAP schema files. For more information on OpenLDAP schema elements and files, see http://www.openldap.org/doc/admin24/schema.html.

13.2. Default Schema Elements and Files

A variety of applciations use schemas to describe their information; some of these schemas conform to international standards, and some are specific to the application. Penrose Virtual Directory has schema definitions for a variety of common directory applications loaded to define a variety of information in the virtual directory; these are listed in Table 13.1, “Default Virtual Directory Schema Files”.

In Penrose Virtual Directory, all of the schema files are located in the /opt/vd-server-2.0/schema.

Schema File Description
apache.schema Contains object classes and attributes required to define Apache LDAP directory server entries.
apachedns.schema Contains object classes and attributes required to define DNS records.
autofs.schema Contains object classes and attributes required to define NFS mount shares in an NIS entry.
changelog.schema Contains object classes and attributes required to define a changelog entry to track changes in data masters.
collective.schema Contains X.500 elements for collective attributes for LDAP entries.
corba.schema Contains schema elements to represent CORBA objects in an LDAP directory.
core.schema Contains the core OpenLDAP schema elements.
cosine.schema Contains LDAP schema derived from X.500 COSINE pilot schema.
dhcp.schema Contains object classes and attributes to define DHCP server information.
extension.schema Contains object classes and attributes to extend LDAP support in applications like Outlook and PAM.
inetorgperson.schema Contains attributes to define inetOrgPerson entries for people within an organization.
java.schema Contains object classes and attributes to define Java objects in an LDAP directory.
krb5kdc.schema Contains object classes and attributes to define Kerberos configuration entries.
misc.schema Contains various object classes and attributes to define mail entries, including as mail accounts and mail servers.

WARNING

Several of these attributes are obsolete, not fully supported, or depend on expired standards. These attributes should not be used in a full production environment.

nis.schema Contains object classes and attributes to define NIS servers and domains in an LDAP directory.
samba.schema Contains object classes and attributes for storing Samba user accounts and group maps in LDAP entries.
solaris.schema Contains object classes and attributes required to configure a NIS entry in a Red Hat Directory Server-style LDAP directory on Solaris.
system.schema Contains required and administrative object classes and attributes to configure an LDAP directory, including root DSEs, administrative subschema, referrals, and general entry information.
Table 13.1. Default Virtual Directory Schema Files

These files are listed in Penrose Studio in the Built-in Schema folder.

The full configuration for each schema file is viewable in Penrose Studio and can be edited by double-clicking the attribute or object class to edit its setup, but adding additional schema elements, or by removing schema elements.

13.3. Creating Custom Schema

Schema files can be created through Penrose Studio. The new schema is then processed through Penrose Studio and sent to the Penrose Server, which writes it to a new file in the server configuration.

To create custom schema in Penrose Studio:

  1. In the server entry, expand the Schema folder.

  2. Right-click the Custom Schemas folder, and select New Schema....

  3. Name the new schema, and click Finish.

  4. Double-click the new schema entry to open the entry editor.

  5. Click the Attributes tab at the bottom of the editor.

  6. Click the Add button.

  7. Fill in the new attribute informaton.

    • The OID (required)

    • The name (required)

    • The OID of the syntax, which is the format of the attribute value (required)

    • A description (optional)

    • The matching rules for equality, substring, and ordering indexes, such as caseIgnoreMatch (optional)

    The OID can be any attribute defined by IANA or can be custom. The possible syntax OIDs are listed in Table 13.2, “Common LDAP Syntaxes”.

    OID Name
    1.3.6.1.4.1.1466.115.121.1.4 Audio
    1.3.6.1.4.1.1466.115.121.1.5 Binary
    1.3.6.1.4.1.1466.115.121.1.7 Boolean
    1.3.6.1.4.1.1466.115.121.1.12 DN
    1.3.6.1.4.1.1466.115.121.1.15 Directory String
    1.3.6.1.4.1.1466.115.121.1.22 Telephone Number
    1.3.6.1.4.1.1466.115.121.1.24 Generalized Time
    1.3.6.1.4.1.1466.115.121.1.26 IA5 String
    1.3.6.1.4.1.1466.115.121.1.27 Integer
    1.3.6.1.4.1.1466.115.121.1.28 JPEG
    1.3.6.1.4.1.1466.115.121.1.36 Numeric String
    1.3.6.1.4.1.1466.115.121.1.40 Octet String
    1.3.6.1.4.1.1466.115.121.1.38 OID
    1.3.6.1.4.1.1466.115.121.1.41 Postal Address
    Table 13.2. Common LDAP Syntaxes

  8. Fill in additional properties for the attribute.

  9. Add an attribute entry for every attribute which will be used by the object classes in the schema.

  10. Click the Attributes tab at the bottom of the editor.

  11. Click the Add button.

  12. Fill in the object class information.

  13. Click the Attributes tab at the top of the object class editor, and click Add to add any required or allowed attributes for the object class.

  14. Click Finish.

  15. Close Penrose Studio, and restart Penrose Server. When Penrose Studio is opened again, the new imported schema is listed under the Custom Schema folder.

It is possible to export the schema configured for a connection so it can be used in other areas of Penrose Server or with other applications.

Importing a schema file uses Penrose Studio to load an existing schema file into Penrose Server. As with creating a new schema file, the local file is imported into the Penrose Studio configuration, serialized to Penrose Server, and written into the server configuration.

NOTE

Any schema file must be of the type .schema for Penrose Server to load it.

13.6. Loading a Schema File Manually

Any schema file can be loaded into Penrose Server to be available for the virtual directory entries. For Penrose Server to recognize the schema file, it must have a .schema extension.

To load the schema into Penrose Server manually:

  1. Create the schema file; this is described somewhat in Section 13.1, “About Directory Schema”.

    NOTE

    The schema file must have a .schema extension.

  2. Copy the schema file into the /opt/vd-server-2.0/schema directory.

  3. All custom schema files must also be loaded into Penrose Virtual Directory's OpenDS service. The formats used for Penrose Virtual Directory and OpenDS schema are the same, but the extensions are different. Schema files in Penrose Virtual Directory have a .schema extension and in OpenDS have a .ldif extension.

    cp custom.schema /opt/vd-server-2.0/services/OpenDS/config/schema/custom.ldif

    If necessary, convert the custom schema file to an OpenDS format, as described in Section 13.7, “Converting the Schema Formatting from OpenLDAP to OpenDS”.

  4. Restart Penrose Server.

    service vd-server restart

    IMPORTANT

    Always restart Penrose Server after editing the configuration file.

13.7. Converting the Schema Formatting from OpenLDAP to OpenDS

Penrose Virtual Directory uses OpenDS-style schema files for some internal operations and OpenLDAP-style schema files for others. Penrose Virtual Directory has a tool, schema.sh, which can convert the OpenLDAP schema files to OpenDS schema files so that they can be loaded into Penrose Server.

Any custom schema file used with Penrose Virtual Directory has to be loaded into its OpenDS service as well as Penrose Server.

  1. Open the OpenDS directory for the integrated OpenDS services.

    cd /opt/vd-server-2.0/services/OpenDS/bin/
  2. Run the schema.sh script to convert the specified schema file to the appropriate format.

    schema.sh /path/to/file.schema custom.ldif
  3. Copy the converted schema file into the OpenDS directory.

    cp custom.ldif /opt/vd-server-2.0/services/OpenDS/config/schema/custom.ldif
  4. Restart Penrose Server.

    service vd-server restart