# $OpenLDAP$
-# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 1999-2007 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Schema Specification
-This chapter describes how to extend the user schema used by {{slapd}}(8).
+This chapter describes how to extend the user schema used by
+{{slapd}}(8). The chapter assumes the reader is familar with the
+{{TERM:LDAP}}/{{TERM:X.500}} information model.
+
The first section, {{SECT:Distributed Schema Files}} details optional
schema definitions provided in the distribution and where to obtain
other definitions.
to {{slapd.conf}}(5) format.
!endif
+This chapter does not discuss how to extend system schema used by
+{{slapd}}(8) as this requires source code modification. System
+schema includes all operational attribute types or any object class
+which allows or requires an operational attribute (directly or
+indirectly).
+
+
H2: Distributed Schema Files
OpenLDAP is distributed with a set of schema specifications for
{{F:/usr/local/etc/openldap/schema}} directory.
!block table; colaligns="LR"; coltags="F,N"; align=Center; \
- title="Table 6.1: Provided Schema Specifications"
+ title="Table 8.1: Provided Schema Specifications"
File Description
core.schema OpenLDAP {{core}} (required)
cosine.schema Cosine and Internet X.500 (useful)
H3: Object Identifiers
-Each schema element is identified by a globally unique
-{{TERM[expand]OID}} (OID). OIDs are also used to identify
-other objects.
-They are commonly found in protocols described by {{TERM:ASN.1}}. In
+Each schema element is identified by a globally unique {{TERM[expand]OID}}
+(OID). OIDs are also used to identify other objects. They are
+commonly found in protocols described by {{TERM:ASN.1}}. In
particular, they are heavily used by the {{TERM[expand]SNMP}} (SNMP).
-As OIDs are hierarchical, your organization
-can obtain one OID and branch it as needed. For example,
-if your organization were assigned OID {{EX:1.1}}, you could branch
-the tree as follows:
+As OIDs are hierarchical, your organization can obtain one OID and
+branch it as needed. For example, if your organization were assigned
+OID {{EX:1.1}}, you could branch the tree as follows:
!block table; colaligns="LR"; coltags="EX,N"; align=Center; \
- title="Table 6.2: Example OID hierarchy"
+ title="Table 8.2: Example OID hierarchy"
OID Assignment
1.1 Organization's OID
1.1.1 SNMP Elements
!endblock
You are, of course, free to design a hierarchy suitable to your
-organizational needs under your organization's OID. No matter
-what hierarchy you choose, you should maintain a registry of
-assignments you make. This can be a simple flat file or a
-something more sophisticated such as the {{OpenLDAP OID Registry}}
+organizational needs under your organization's OID. No matter what
+hierarchy you choose, you should maintain a registry of assignments
+you make. This can be a simple flat file or something more
+sophisticated such as the {{OpenLDAP OID Registry}}
({{URL:http://www.openldap.org/faq/index.cgi?file=197}}).
-For more information about Object Identifers (and a listing
-service) see {{URL:http://www.alvestrand.no/harald/objectid/}}.
+For more information about Object Identifers (and a listing service)
+see {{URL:http://www.alvestrand.no/harald/objectid/}}.
-.{{Under no circumstances should you use a fictitious OID!}}
+.{{Under no circumstances should you hijack OID namespace!}}
-To obtain a fully registered OID at {{no cost}}, apply for
-an OID under {{ORG[expand]IANA}} (IANA) maintained
-{{Private Enterprise}} arch. Any private enterprise (organization)
-may request an OID to be assigned under this arch. Just fill
-out the {{ORG:IANA}} form at {{URL: http://www.iana.org/cgi-bin/enterprise.pl}}
-and your official OID will be sent to you usually within a few days.
-Your base OID will be something like {{EX:1.3.6.1.4.1.X}} were {{EX:X}}
+To obtain a registered OID at {{no cost}}, apply for an OID under
+the {{ORG[expand]IANA}} (IANA) maintained {{Private Enterprise}}
+arc. Any private enterprise (organization) may request an OID to
+be assigned under this arc. Just fill out the {{ORG:IANA}} form
+at {{URL: http://www.iana.org/cgi-bin/enterprise.pl}} and your
+official OID will be sent to you usually within a few days. Your
+base OID will be something like {{EX:1.3.6.1.4.1.X}} where {{EX:X}}
is an integer.
-Note: Don't let the "MIB/SNMP" statement on the IANA page confuse you.
-OIDs obtained using this form may be used for any purpose including
-identifying LDAP schema elements.
+Note: Don't let the "MIB/SNMP" statement on the IANA page confuse
+you. OIDs obtained using this form may be used for any purpose
+including identifying LDAP schema elements.
+
+Alternatively, OID name space may be available from a national
+authority (e.g., {{ORG:ANSI}}, {{ORG:BSI}}).
H3: Name Prefix
In addition to assigning a unique object identifier to each schema
element, you should provide a least one textual name for each
-element. The name should be both descriptive and not likely
-to clash with names of other schema elements. In particular,
-any name you choose should not clash with present or future
-Standard Track names.
+element. The name should be both descriptive and not likely to
+clash with names of other schema elements. In particular, any name
+you choose should not clash with present or future Standard Track
+names.
-To reduce (but not eliminate) the potential for name clashes,
-the convention is to prefix names of non-Standard Track with
-a few letters to localize the changes to your organization.
-The smaller the organization, the longer your prefix should
-be.
+To reduce (but not eliminate) the potential for name clashes, the
+convention is to prefix names of non-Standard Track with a few
+letters to localize the changes to your organization. The smaller
+the organization, the longer your prefix should be.
In the examples below, we have chosen a short prefix '{{EX:my}}'
-(to save space). Such a short prefix would only be suitable for
-a very large, global organization. For a small, local organization,
-we recommend something like '{{EX:deFirm}}' (German company) or
-'{{EX:comExample}}' (elements associated with organization associated
-with {{EX:example.com}}).
+(to save space). Such a short prefix would only be suitable for a
+very large, global organization. In general, we recommend something
+like '{{EX:deFirm}}' (German company) or '{{EX:comExample}}' (elements
+associated with organization associated with {{EX:example.com}}).
H3: Local schema file
where whsp is a space ('{{EX: }}'), numericoid is a globally unique
OID in dotted-decimal form (e.g. {{EX:1.1.0}}), qdescrs is one or
more names, woid is either the name or OID optionally followed
-length specifier (e.g {{EX:{10}}}).
+by a length specifier (e.g {{EX:{10}}}).
For example, the attribute types {{EX:name}} and {{EX:cn}} are defined
in {{F:core.schema}} as:
> EQUALITY caseIgnoreMatch
> SUBSTR caseIgnoreSubstringsMatch
> SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} )
-> attributeType ( 2.5.4.3 NAME ( 'cn' $ 'commonName' )
+> attributeType ( 2.5.4.3 NAME ( 'cn' 'commonName' )
> DESC 'common name(s) assciated with the object'
> SUP name )
{{slapd}}(8) returns the first listed name when returning results.
The first attribute, {{EX:name}}, holds values of {{EX:directoryString}}
-(UTF-8 encoded Unicode) syntax. The syntax are specified by OID
+(UTF-8 encoded Unicode) syntax. The syntax is specified by OID
(1.3.6.1.4.1.1466.115.121.1.15 identifies the directoryString
syntax). A length recommendation of 32768 is specified. Servers
should support values of this length, but may support longer values
matching rules (OpenLDAP supports these and many more).
!block table; align=Center; coltags="EX,EX,N"; \
- title="Table 6.3: Commonly Used Syntaxes"
+ title="Table 8.3: Commonly Used Syntaxes"
Name OID Description
boolean 1.3.6.1.4.1.1466.115.121.1.7 boolean value
-distinguishedName 1.3.6.1.4.1.1466.115.121.1.12 DN
-directoryString 1.3.6.1.4.1.1466.115.121.1.15 UTF-8 string
-IA5String 1.3.6.1.4.1.1466.115.121.1.26 ASCII string
-Integer 1.3.6.1.4.1.1466.115.121.1.27 integer
-Name and Optional UID 1.3.6.1.4.1.1466.115.121.1.34 DN plus UID
-Numeric String 1.3.6.1.4.1.1466.115.121.1.36 numeric string
+directoryString 1.3.6.1.4.1.1466.115.121.1.15 Unicode (UTF-8) string
+distinguishedName 1.3.6.1.4.1.1466.115.121.1.12 LDAP DN
+integer 1.3.6.1.4.1.1466.115.121.1.27 integer
+numericString 1.3.6.1.4.1.1466.115.121.1.36 numeric string
OID 1.3.6.1.4.1.1466.115.121.1.38 object identifier
-Octet String 1.3.6.1.4.1.1466.115.121.1.40 arbitary octets
-Printable String 1.3.6.1.4.1.1466.115.121.1.44 printable string
+octetString 1.3.6.1.4.1.1466.115.121.1.40 arbitary octets
!endblock
>
!block table; align=Center; coltags="EX,N"; \
- title="Table 6.4: Commonly Used Matching Rules"
-Name Type Description
-booleanMatch equality boolean
-octetStringMatch equality octet string
-objectIdentiferMatch equality OID
-distinguishedNameMatch equality DN
-uniqueMemberMatch equality Name with optional UID
-numericStringMatch equality numerical
-numericStringOrderingMatch ordering numerical
-numericStringSubstringsMatch substrings numerical
-caseIgnoreMatch equality case insensitive, space insensitive
-caseIgnoreOrderingMatch ordering case insensitive, space insensitive
-caseIgnoreSubstringsMatch substrings case insensitive, space insensitive
-caseExactMatch equality case sensitive, space insensitive
-caseExactOrderingMatch ordering case sensitive, space insensitive
-caseExactSubstringsMatch substrings case sensitive, space insensitive
-caseIgnoreIA5Match equality case insensitive, space insensitive
-caseIgnoreIA5OrderingMatch ordering case insensitive, space insensitive
-caseIgnoreIA5SubstringsMatch substrings case insensitive, space insensitive
-caseExactIA5Match equality case sensitive, space insensitive
-caseExactIA5OrderingMatch ordering case sensitive, space insensitive
-caseExactIA5SubstringsMatch substrings case sensitive, space insensitive
+ title="Table 8.4: Commonly Used Matching Rules"
+Name Type Description
+booleanMatch equality boolean
+caseIgnoreMatch equality case insensitive, space insensitive
+caseIgnoreOrderingMatch ordering case insensitive, space insensitive
+caseIgnoreSubstringsMatch substrings case insensitive, space insensitive
+caseExactMatch equality case sensitive, space insensitive
+caseExactOrderingMatch ordering case sensitive, space insensitive
+caseExactSubstringsMatch substrings case sensitive, space insensitive
+distinguishedNameMatch equality distinguished name
+integerMatch equality integer
+integerOrderingMatch ordering integer
+numericStringMatch equality numerical
+numericStringOrderingMatch ordering numerical
+numericStringSubstringsMatch substrings numerical
+octetStringMatch equality octet string
+octetStringOrderingStringMatch ordering octet string
+octetStringSubstringsStringMatch ordering octet string
+objectIdentiferMatch equality object identifier
!endblock
The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence
{{slapd}}(8).
LDAPv3 servers publish schema elements in special {{subschema}}
-entries (or subentries). {{slapd}}(8) publishes a single subschema
-entry normally named {{EX:cn=Subschema}}. In a server which
-supports a single subschema subentry, the DN of the subschema
-subenty can usually be found by examining the value of the
-{{EX:subschemaSubentry}} attribute type in the {{root DSE}}.
-Other servers may publish multiple subschema entries. These
-can be located by examining the {{EX:subschemaSubentry}} attribute
-contained in the entry at the root of each administrative context.
+entries (or subentries). While {{slapd}}(8) publishes a single
+subschema subentry normally named {{EX:cn=Subschema}}, this behavior
+cannot be expected from other servers. The subschema subentry
+controlling a particular entry can be obtained by examining the
+{{EX:subschemaSubentry}} attribute contained in the entry at the
+root of each administrative context. For example,
+
+> ldapsearch -LLL -x -b "dc=example,dc=com" -s base "(objectclass=*)" subschemaSubentry
To obtain the schema from a subschema subentry, you can use
ldapsearch(1) as follows (replace the search base as needed):
> ldapsearch -LLL -x -b "cn=Subschema" -s base "(objectclass=subschema)" attributeTypes objectClasses
+where "cn=Subschema" is the value of subschemaSubentry returned in
+the prior search.
+
This will return {{TERM:LDIF}} output containing many type/value
pairs. The following is an abbreviated example:
> dn: cn=Subschema
+> objectClasses: ( 1.1.2.2.2 NAME 'myPerson' DESC 'my person' SUP inet
+> OrgPerson MUST ( myUniqueName $ givenName ) MAY myPhoto )
> attributeTypes: ( 1.1.2.1.1 NAME 'myUniqueName' DESC 'unique name wi
> th my organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubst
> ringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
> attributeTypes: ( 1.1.2.1.2 NAME 'myPhoto' DESC 'a photo (applicatio
> n defined format)' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
-> objectClasses: ( 1.1.2.2.2 NAME 'myPerson' DESC 'my person' SUP inet
-> OrgPerson MUST ( myUniqueName $ givenName ) MAY myPhoto )
Capture the output of the search in a file and then edit the file:
+ to contain only desired type/value pairs
^ join LDIF continuation lines
^ replace attribute type with directive name
-(e.g. {{EX:s/attributeTypes:/attributeType/}} and
-{{EX:s/objectClasses:/objectClass/}}).
+(e.g. {{EX:s/attributeTypes:/attributeType /}} and
+{{EX:s/objectClasses:/objectClass /}}).
+^ reorder lines so each element is defined before first use
^ continue long directives over multiple lines
For the three type/value pairs in our example, the edit should
> MUST ( myUniqueName $ givenName )
> MAY myPhoto )
-Save in an appropriately named file (e.g. {{F:my.schema}}).
+Save in an appropriately named file (e.g. {{F:local.schema}}).
You may now include this file in your {{slapd.conf}}(5) file.
!endif
H3: OID Macros
To ease the management and use of OIDs, {{slapd}}(8) supports
-{{Object Identifier}} macros. The {{EX:objectIdentifier}} is used
-to equate a macro (name) with a OID. The OID may possibly be derived
-from a previously defined OID macro. The {{slapd.conf(5)}} syntax
-is:
+{{Object Identifier}} macros. The {{EX:objectIdentifier}} directive
+is used to equate a macro (name) with a OID. The OID may possibly
+be derived from a previously defined OID macro. The {{slapd.conf}}(5)
+syntax is:
E: objectIdentifier <name> { <oid> | <name>[:<suffix>] }
The following demonstrates definition of a set of OID macros
and their use in defining schema elements:
-> objectIdentifier myOrgOID 1.1
-> objectIdentifier myOrgSNMP myOrgOID:1
-> objectIdentifier myOrgLDAP myOrgOID:2
-> objectIdentifier myAttributeType myOrgLDAP:1
-> objectIdentifier myObjectClass myOrgLDAP:2
+> objectIdentifier myOID 1.1
+> objectIdentifier mySNMP myOID:1
+> objectIdentifier myLDAP myOID:2
+> objectIdentifier myAttributeType myLDAP:1
+> objectIdentifier myObjectClass myLDAP:2
> attributetype ( myAttributeType:3 NAME 'myPhotoURI'
> DESC 'URI and optional label referring to a photo'
> SUP labeledURI )