Chapter 13. Customizing Schema
This chapter describes the default schema included with Penrose Virtual Directory and explains how to create and load custom 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.
For more detailed information on schema, check out Understanding and Deploying LDAP Directory Services by T. Howes, M. Smith, and G. Good and the IETF definitions at http://www.ietf.org/rfc/rfc2252.txt.
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:
An object identifier (OID)
The syntax of the attribute, meaning the kind of value that is allowed, like an integer or string (see Table 13.2, “Common LDAP Syntaxes”)
Whether there can only be a single value or whether there can be multiple uses of this attribute in the same entry
Indexing information
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.
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.
WARNINGSeveral 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. |
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.
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:
In the server entry, expand the Schema folder.
Right-click the Custom Schemas folder, and select New Schema....
Name the new schema, and click Finish.
Double-click the new schema entry to open the entry editor.
Click the Attributes tab at the bottom of the editor.
Click the Add button.
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 |
Fill in additional properties for the attribute.
The type of attribute, in the Usage drop-down menu, can be userApplication
(used by a client independent of the LDAP directory), directoryOperation
(used by the LDAP directory), distributedOperation
(shared between directory server instances), and dSAOperation
(unique to each individual directory server instance).
Whether the attribute is single- or multi-valued
Whether the attribute is shared among multiple types of entries (collective)
Whether the attribute definition can be modified
Whether the attribute is obsolete, which means it may not be widely supported
Add an attribute entry for every attribute which will be used by the object classes in the schema.
Click the Attributes tab at the bottom of the editor.
Click the Add button.
Fill in the object class information.
The OID (required), which can be defined by IANA or custom
The name (required)
The type (required)
Any superior object class (optional)
A description (optional)
Whether the object class is obsolete (optional)
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.
Penrose Server does not validate the schema, so it is possible to create schema entries which violate the LDAP standards.
Click Finish.
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.
Open the server entry.
In the top menu, expand the Partitions menu item, and select the Connections folder.
Open the Connections folder, and double-click the connection.
Click the Schema tab at the bottom of the window.
Click the Export link.
Select the location to save the schema file to.
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.
Any schema file must be of the type .schema
for Penrose Server to load it.
In the server entry, expand the Schema folder.
Right-click the Custom Schemas folder, and select Import Schema.
Name the schema entry.
Enter the absolute path to the schema file.
Click Finish.
Close Penrose Studio, and restart Penrose Server. When Penrose Studio is opened again, the new imported schema is listed under the Custom Schema folder.
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”.
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:
Create the schema file; this is described somewhat in Section 13.1, “About Directory Schema”.
The schema file must have a .schema
extension.
Copy the schema file into the /opt/vd-server-2.0/schema
directory.
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”.
Restart Penrose Server.
service vd-server restart
Always restart Penrose Server after editing the configuration file.
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.
Open the OpenDS directory for the integrated OpenDS services.
cd /opt/vd-server-2.0/services/OpenDS/bin/
Run the schema.sh
script to convert the specified schema file to the appropriate format.
schema.sh /path/to/file
.schema custom.ldif
Copy the converted schema file into the OpenDS directory.
cp custom.ldif /opt/vd-server-2.0/services/OpenDS/config/schema/custom.ldif
Restart Penrose Server.
service vd-server restart