6443N/A<?
xml version="1.0" encoding="UTF-8"?>
6443N/A ! This work is licensed under the Creative Commons 6443N/A ! Attribution-NonCommercial-NoDerivs 3.0 Unported License. 6443N/A ! To view a copy of this license, visit 6443N/A ! or send a letter to Creative Commons, 444 Castro Street, 6443N/A ! Suite 900, Mountain View, California, 94041, USA. 6443N/A ! You can also obtain a copy of the license at 6443N/A ! See the License for the specific language governing permissions 6443N/A ! and limitations under the License. 6443N/A ! If applicable, add the following below this CCPL HEADER, with the fields 6443N/A ! enclosed by brackets "[]" replaced with your own identifying information: 6443N/A ! Portions Copyright [yyyy] [name of copyright owner] 7097N/A ! Copyright 2011-2014 ForgeRock AS 6443N/A<
chapter xml:
id='chap-schema' 6443N/A <
title>Managing Schema</
title>
6443N/A <
indexterm><
primary>Schema</
primary></
indexterm>
6443N/A <
para>Schema definitions describe the data, and especially the object classes
6443N/A and attribute types that can be stored in the directory. By default OpenDJ
6443N/A conforms strictly to LDAPv3 standards pertaining to schema definitions and
6443N/A attribute syntax checking, ensuring that data stored is valid and properly
6443N/A formed. Unless your data use only standard schema present in OpenDJ when
6443N/A you install, then you must add additional schema definitions to account
6443N/A the data your applications stored.</
para>
6443N/A <
para>Out of the box, OpenDJ comes with many standard schema definitions.
6443N/A In addition you can update and extend schema definitions while OpenDJ
6443N/A is online. As a result you can add new applications requiring additional
6443N/A data without stopping your directory service.</
para>
6443N/A <
para>This chapter demonstrates how to change and to extend OpenDJ schema.
6443N/A This chapter also identifies the standard schema definitions available when
6443N/A <
section xml:
id="about-schema">
6443N/A <
title>About Directory Schema</
title>
6443N/A <
para>Directory schema, described in <
link 6443N/A the kinds of information you find in the directory, and can define how
6443N/A the information are related. This chapter focuses primarily on two types
6443N/A of directory schema definitions.</
para>
6443N/A <
para><
firstterm>Attribute type</
firstterm> definitions describe attributes
6443N/A of directory entries, such as <
literal>givenName</
literal> or
6443N/A <
literal>mail</
literal>.</
para>
6443N/A <
para>Here is an example of an attribute type definition.</
para>
7097N/A <
programlisting language="ldif">
6443N/AattributeTypes: ( 0.9.2342.19200300.100.1.3 NAME ( 'mail' 'rfc822Mailbox' )
6443N/A EQUALITY caseIgnoreIA5Match SUBSTR caseIgnoreIA5SubstringsMatch
7097N/A SYNTAX 1.3.6.1.4.1.1466.115.121.1.26{256} X-ORIGIN 'RFC 4524' )
6443N/A <
para>Attribute type definitions start with an object identifier (OID),
6443N/A and generally a short name or names that are easier to remember than the
6443N/A OID. The attribute type definition can specify how attribute values
6443N/A should be collated for sorting, and what syntax they use. The X-ORIGIN
6443N/A is an extension to identify where the definition originated. When you
6478N/A define your own schema, you likely want to provide an X-ORIGIN to help
6443N/A you to track versions of definitions, and where the definitions came
6443N/A <
para><
firstterm>Object class</
firstterm> definitions identify the
6443N/A attribute types that an entry must have, and may have. Examples of
6443N/A object classes include <
literal>person</
literal> and
6443N/A <
literal>organizationalUnit</
literal>.</
para>
6443N/A <
para>Here is an example of an object class definition.</
para>
7097N/A <
programlisting language="ldif">
6443N/AobjectClasses: ( 2.5.6.6 NAME 'person' SUP top STRUCTURAL MUST ( sn $ cn )
6443N/A MAY ( userPassword $ telephoneNumber $ seeAlso $ description )
6443N/A <
para>Entries all have an attribute identifying their object classes,
6443N/A called <
literal>objectClass</
literal>.</
para>
6443N/A <
para>Object class definitions start with an object identifier (OID), and
6443N/A generally a short name that is easier to remember than the OID. The
6443N/A definition here says that the person object class inherits from the top
6443N/A object class, which is the top-level parent of all object classes. When
6443N/A you view the objectclass attribute values on an entry, you see the list
6443N/A of object classes that the entry takes. An entry can have one STRUCTURAL
6443N/A object class inheritance branch, such as <
literal>top</
literal> -
6443N/A <
literal>person</
literal> - <
literal>organizationalPerson</
literal> -
6443N/A <
literal>inetOrgPerson</
literal>. Yet entries can have multiple
6443N/A AUXILIARY object classes. The object class then defines the attribute
6443N/A types that must be included, and the attribute types that may be included
6443N/A on entries having the object class.</
para>
6443N/A <
para>An <
firstterm>attribute syntax</
firstterm> constrains what directory
6443N/A clients can store as attribute values.</
para>
6443N/A <
para>An attribute syntax is identified in an attribute type definition by
6443N/A its OID. String-based syntax OIDs are optionally followed by a number, set
6443N/A between braces, that represents a minimum upper bound on the number of
6443N/A characters in the attribute value. For example, in the attribute type
6443N/A definition shown above, the syntax is
6443N/A <
literal>1.3.6.1.4.1.1466.115.121.1.26{256}</
literal>. The syntax is an
6443N/A IA5 string (composed of characters from the international version of the
6443N/A ASCII character set) that can contain at least 256 characters.</
para>
6443N/A <
para>You can find a table matching attribute syntax OIDs with their
6443N/A human-readable names in RFC 4517, <
link xlink:
show="new" 6443N/A Summary of Syntax Object Identifiers</
link>. The RFC describes
6443N/A attribute syntaxes in detail. Alternatively, you can see the attribute
6443N/A syntaxes that OpenDJ supports by opening the OpenDJ Control Panel and
6443N/A browsing to Schema > Manage Schema > Attribute Syntaxes. You can
6443N/A also list them by using the <
command>dsconfig</
command> command.</
para>
6443N/A <
para>Although attribute syntaxes are often specified in attribute type
6443N/A definitions, directory servers do not always check that attribute values
6443N/A comply with attribute syntaxes. OpenDJ directory server does tend to
6443N/A enforce compliance by default, in particular for certificates, country
6443N/A strings, directory strings, JPEG photos, and telephone numbers. The aim
6443N/A is to avoid accumulating garbage in your directory data.</
para>
6443N/A <
para>If you are trying unsuccessfully to import non-compliant data from a
6443N/A more lenient directory server, you can either clean the data before
6443N/A importing it, or if cleaning the data is not an option, read <
xref 6443N/A linkend="schema-legacy-support" />.</
para>
6443N/A <
para>When creating your own attribute type definitions, use existing
6443N/A attribute syntaxes where possible. If you must create your own attribute
6443N/A syntax, then consider the extensions in
6443N/A <
xref linkend="attr-syntax-schema-definition-extensions" />.</
para>
6443N/A <
para>Matching rules determine how the directory server compares attribute
6443N/A values to assertion values for LDAP search and LDAP compare
6443N/A <
para>For example, suppose you search with the filter
6443N/A <
literal>(uid=bjensen)</
literal>. The assertion value in this case is
6443N/A <
literal>bjensen</
literal>.</
para>
6443N/A <
para>OpenDJ has the following schema definition for the user ID
7097N/A <
programlisting language="ldif">
7097N/AattributeTypes: ( 0.9.2342.19200300.100.1.1 NAME ( 'uid' 'userid' )
6443N/A EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstringsMatch
7097N/A SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{256} X-ORIGIN 'RFC 4519' )
6443N/A <
para>When finding an equality match for your search, OpenDJ uses the
6443N/A <
literal>caseIgnoreMatch</
literal> matching rule to check for user ID
6443N/A attribute values that equal <
literal>bjensen</
literal> without regard
6443N/A <
para>You can see the matching rules that OpenDJ supports by opening the
6443N/A OpenDJ Control Panel and browsing to Schema > Manage Schema >
6443N/A Matching Rules. Notice that many matching rules support string collation
6443N/A in languages other than English. You can also list matching rules by
6443N/A using the <
command>dsconfig</
command> command.</
para>
7097N/A <
para>As you can read in examples like, <
link xlink:
show="new" 6443N/A xlink:
href="admin-guide#extensible-match-search" 6443N/A Active Accounts</
citetitle></
link>, OpenDJ matching rules enable
6443N/A directory clients to do more interesting searches than simply comparing
6443N/A strings. That example shows how to search for users who have
6443N/A authenticated in the last three months.</
para>
6443N/A <
para>OpenDJ exposes schema over protocol through the
6443N/A <
literal>cn=schema</
literal> entry. OpenDJ stores the schema definitions
6443N/A corresponding to the entry in LDIF under the
6443N/A and definitions pertaining to the server configuration are included at
6443N/A <
section xml:
id="update-schema">
6443N/A <
title>Updating Directory Schema</
title>
6443N/A <
primary>Replication</
primary>
6443N/A <
secondary>Schema definitions</
secondary>
6443N/A <
para>OpenDJ directory server is designed to permit updating the list of
6443N/A directory schema definitions while the server is running. As a result you can
6443N/A add support for new applications that require new attributes or new kinds
6443N/A of entries without interrupting the directory service. OpenDJ also replicates
6480N/A schema definitions, so the schema you add on one replica is propagated to
6443N/A other replicas without you having to intervene manually.</
para>
6443N/A <
para>As it is easy to introduce typos into schema definitions, the
6443N/A best way to start defining your own schema is with the OpenDJ Control
6443N/A Panel. Open the Control Panel > Schema > Manage Schema window to
6443N/A get started creating your custom object classes and attribute types.</
para>
6443N/A <
mediaobject xml:
id="figure-manage-schema">
6443N/A <
para>As object classes reference attribute types, you first create
6443N/A custom attribute types, and then create the object class that references
6443N/A the attribute types.</
para>
6443N/A <
para>Create a custom attribute type through the New Attribute window.</
para>
6443N/A <
mediaobject xml:
id="figure-custom-attrtype">
6443N/A <
para>Using the New Object Class window, create an auxiliary object class
6443N/A that allows your new custom attribute type. You set the type to Auxiliary
6443N/A under Extra Options.</
para>
6443N/A <
mediaobject xml:
id="figure-custom-objclass">
6443N/A <
para>When you finish, the schema changes show up by default in the file
6443N/A starts with a number, 99. This number is larger than the numbers prefixing
6443N/A other schema file names. In fact, OpenDJ reads the schema files in sorted
6443N/A order, reading schema definitions as they occur. If OpenDJ reads a schema
6443N/A definition for an object class before it has read the definitions of the
6443N/A attribute types mentioned in the object class definition, then it displays
6443N/A an error. Therefore, when naming your schema file, make sure the name appears
6443N/A in the sorted list of file names <
emphasis>after</
emphasis> all the schema
6443N/A files containing definitions that your schema definitions depends on. The
6443N/A that your definitions load only after all of the schema files installed by
6443N/A <
para>You can create this file in the lab using the Control Panel, and then
6443N/A apply the definitions in production by adapting the content for use with the
6443N/A <
command>ldapmodify</
command> command, for example.</
para>
7097N/A<
computeroutput>dn: cn=schema
6443N/AattributeTypes: ( temporary-fake-attr-id NAME 'myCustomAttribute' EQUALITY case
6443N/A IgnoreMatch ORDERING caseIgnoreOrderingMatch SUBSTR caseIgnoreSubstrings
6443N/A Match SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE userApplications )
6443N/AobjectClasses: ( temporary-fake-oc-id NAME 'myCustomObjClass
6443N/A ' SUP top AUXILIARY MAY myCustomAttribute )
6443N/AmodifiersName: cn=Directory Manager,cn=Root DNs,cn=config
7097N/AmodifyTimestamp: 20110620095948Z</
computeroutput>
6443N/A <
para>To test your schema definition, add the object class and attribute
7097N/A<
computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
6443N/AobjectClass: myCustomObjClass
7097N/AmyCustomAttribute: Testing 1, 2, 3...</
computeroutput>
7097N/A --bindDN "cn=Directory Manager" \
7097N/A<
computeroutput>Processing MODIFY request for uid=bjensen,ou=People,dc=example,dc=com
7097N/AMODIFY operation successful for DN uid=bjensen,ou=People,dc=example,dc=com</
computeroutput>
7097N/A --baseDN dc=example,dc=com \
7097N/A myCustomAttribute</
userinput>
7097N/A<
computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
7097N/AmyCustomAttribute: Testing 1, 2, 3...</
computeroutput>
6443N/A <
para>In addition to supporting the standard schema definitions that are
6443N/A >RFC 4512, section 4.1</
link>, OpenDJ also supports the following extensions
6443N/A that you can use when adding your own definitions.</
para>
6443N/A <
variablelist xml:
id="general-schema-definition-extensions">
6443N/A <
title>Extensions for All Schema Definitions</
title>
6443N/A <
secondary>Schema definition extensions</
secondary>
6443N/A <
term><
literal>X-ORIGIN</
literal></
term>
6443N/A <
para>Used to specify the origin of a schema element. Examples include
6443N/A <
literal>X-ORIGIN 'RFC 4519'</
literal>, <
literal>X-ORIGIN
6443N/A 'draft-ietf-ldup-subentry'</
literal>, and <
literal>X-ORIGIN
6443N/A 'OpenDJ Directory Server'</
literal>.</
para>
6443N/A <
term><
literal>X-SCHEMA-FILE</
literal></
term>
6443N/A <
para>Used to specify the relative path to the schema file containing the
6443N/A Schema definitions are located by default in
6443N/A <
variablelist xml:
id="attr-syntax-schema-definition-extensions">
6443N/A <
title>Extensions for Attribute Syntax Descriptions</
title>
6443N/A <
secondary>Schema definition extensions</
secondary>
6443N/A <
term><
literal>X-ENUM</
literal></
term>
6443N/A <
para>Used to define a syntax that is an enumeration of values. The
6443N/A following attribute syntax description defines a syntax allowing four
6443N/A possible attribute values for example.</
para>
7097N/A <
programlisting language="ldif">
7097N/AldapSyntaxes: ( security-label-syntax-oid DESC 'Security Label'
7097N/A X-ENUM ( 'top-secret' 'secret' 'confidential' 'unclassified' ) )
6443N/A <
term><
literal>X-PATTERN</
literal></
term>
6443N/A <
para>Used to define a syntax based on a regular expression pattern, where
6443N/A valid regular expressions are those defined for <
link xlink:
show="new" 6443N/A syntax description defines a simple, lenient SIP phone URI syntax
7097N/A <
programlisting language="ldif">
7097N/AldapSyntaxes: ( simple-sip-uri-syntax-oid DESC 'Lenient SIP URI Syntax'
7097N/A X-PATTERN '^sip:[a-zA-Z0-9.]+@[a-zA-Z0-9.]+(:[0-9]+)?$' )
6443N/A <
term><
literal>X-SUBST</
literal></
term>
6443N/A <
para>Used as a fallback to substitute a defined syntax for one that
6443N/A OpenDJ does not implement. The following example substitutes Directory
6443N/A String syntax, which has OID 1.3.6.1.4.1.1466.115.121.1.15, for a syntax
6443N/A that OpenDJ does not implement.</
para>
7097N/A <
programlisting language="ldif">
7097N/AldapSyntaxes: ( non-implemented-syntax-oid DESC 'Not Implemented in OpenDJ'
7097N/A X-SUBST '1.3.6.1.4.1.1466.115.121.1.15' )
6443N/A <
variablelist xml:
id="attr-type-schema-definition-extensions">
6443N/A <
title>Extension for Attribute Type Descriptions</
title>
6443N/A <
secondary>Schema definition extensions</
secondary>
6443N/A <
term><
literal>X-APPROX</
literal></
term>
6443N/A <
para><
literal>X-APPROX</
literal> is used to specify the approximate
6443N/A matching rule to use for a given attribute type when not using the default,
6443N/A xlink:
show="new">double metaphone approximate match</
link>.</
para>
6443N/A <
section xml:
id="schema-legacy-support">
6443N/A <
title>Relaxing Schema Checking to Import Legacy Data</
title>
6443N/A <
secondary>Legacy data</
secondary>
6443N/A <
para>By default, OpenDJ accepts data that follows the standards in terms of
6443N/A what is allowed and what is rejected. You might have legacy data from a
6443N/A directory service that is more lenient, allowing non-standard constructions
6443N/A such as multiple structural object classes per entry, not checking attribute
6443N/A value syntax, or even not respecting schema definitions.</
para>
6443N/A <
para>For example, when importing data with multiple structural object
6443N/A classes defined per entry, you can relax schema checking to warn rather
6443N/A than reject entries having this issue.</
para>
7097N/A set-global-configuration-prop \
7097N/A --bindDN "cn=Directory Manager" \
7097N/A --set single-structural-objectclass-behavior:warn \
6443N/A <
para>You can allow attribute values that do not respect the defined syntax
6443N/A with the <
command>dsconfig</
command> command as well.</
para>
7097N/A set-global-configuration-prop \
7097N/A --bindDN "cn=Directory Manager" \
7097N/A --set invalid-attribute-syntax-behavior:warn \
6443N/A <
para>You can even turn off schema checking altogether, although turning
6443N/A off schema checking only really makes sense when you are absolutely sure
6443N/A that the entries and attribute values respect the schema definitions, and
6443N/A you simply want to turn off schema checking temporarily to speed up import
7097N/A set-global-configuration-prop \
7097N/A --bindDN "cn=Directory Manager" \
6443N/A <
section xml:
id="standard-schema">
6443N/A <
title>Standard Schema Included With OpenDJ</
title>
6443N/A <
secondary>Bundled definitions</
secondary>
6443N/A contain schema definitions out of the box.</
para>
7255N/A This file contains a core set of
7255N/A attribute type and object class definitions
7255N/A from the following Internet-Drafts, RFCs, and standards:
7255N/A This file contains schema definitions from
7255N/A >draft-behera-ldap-password-policy</
link> (Draft 09),
7255N/A which defines a mechanism for storing password policy information
7255N/A in an LDAP directory server.
6443N/A <
para>This file contains the attribute type and objectclass definitions
6443N/A for use with the directory server configuration.</
para>
7255N/A This file contains schema definitions from
7255N/A >draft-good-ldap-changelog</
link>, which defines a mechanism
7255N/A for storing information about changes to directory server data.
7255N/A This file contains schema definitions from
7255N/A >RFC 2713</
link>, which defines a mechanism
7255N/A for storing serialized Java objects in the directory server.
7255N/A This file contains schema definitions from
7255N/A >RFC 2714</
link>, which defines a mechanism
7255N/A for storing CORBA objects in the directory server.
7255N/A This file contains schema definitions from
7255N/A >RFC 2739</
link>, which defines a mechanism
7255N/A for storing calendar and vCard objects in the directory server.
7255N/A Note that the definition in RFC 2739 contains a number of errors,
7255N/A and this schema file has been altered from the standard definition
7255N/A in order to fix a number of those problems.
7255N/A This file contains schema definitions from
7255N/A >RFC 2926</
link>, which defines a mechanism
7255N/A for mapping between Service Location Protocol (SLP) advertisements and LDAP.
7255N/A This file contains schema definitions from
7255N/A >RFC 3112</
link>, which defines the authentication password schema.
7255N/A This file contains schema definitions from
7255N/A >RFC 3712</
link>, which defines a mechanism
7255N/A for storing printer information in the directory server.
7255N/A This file contains schema definitions from
7255N/A >RFC 4403</
link>, which defines a mechanism
7255N/A for storing UDDIv3 information in the directory server.
7255N/A This file contains schema definitions from
7255N/A >draft-howard-rfc2307bis</
link>, which defines a mechanism
7255N/A for storing naming service information in the directory server.
7255N/A This file contains schema definitions from
7255N/A >RFC 4876</
link>, which defines a schema
7255N/A for storing Directory User Agent (DUA) profiles and preferences
6443N/A <
para>This file contains schema definitions required when storing Samba
6443N/A user accounts in the directory server.</
para>
6443N/A <
para>This file contains schema definitions required for Solaris and
6443N/A OpenSolaris LDAP naming services.</
para>
6443N/A <
para>This file contains the attribute type and objectclass definitions
6443N/A for use with the directory server configuration.</
para>
