2 # Copyright 1999-2007 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
5 H1: Schema Specification
7 This chapter describes how to extend the user schema used by
8 {{slapd}}(8). The chapter assumes the reader is familar with the
9 {{TERM:LDAP}}/{{TERM:X.500}} information model.
11 The first section, {{SECT:Distributed Schema Files}} details optional
12 schema definitions provided in the distribution and where to obtain
14 The second section, {{SECT:Extending Schema}}, details how to define
17 The third section, {{SECT:Transferring Schema}} details how you can
18 export schema definitions from an LDAPv3 server and transform it
19 to {{slapd.conf}}(5) format.
22 This chapter does not discuss how to extend system schema used by
23 {{slapd}}(8) as this requires source code modification. System
24 schema includes all operational attribute types or any object class
25 which allows or requires an operational attribute (directly or
29 H2: Distributed Schema Files
31 OpenLDAP Software is distributed with a set of schema specifications for
32 your use. Each set is defined in a file suitable for inclusion
33 (using the {{EX:include}} directive) in your {{slapd.conf}}(5)
34 file. These schema files are normally installed in the
35 {{F:/usr/local/etc/openldap/schema}} directory.
37 !block table; colaligns="LR"; coltags="F,N"; align=Center; \
38 title="Table 8.1: Provided Schema Specifications"
40 core.schema OpenLDAP {{core}} (required)
41 cosine.schema Cosine and Internet X.500 (useful)
42 inetorgperson.schema InetOrgPerson (useful)
43 misc.schema Assorted (experimental)
44 nis.schema Network Information Services (FYI)
45 openldap.schema OpenLDAP Project (experimental)
48 To use any of these schema files, you only need to include the
49 desired file in the global definitions portion of your
50 {{slapd.conf}}(5) file. For example:
53 > include /usr/local/etc/openldap/schema/core.schema
54 > include /usr/local/etc/openldap/schema/cosine.schema
55 > include /usr/local/etc/openldap/schema/inetorgperson.schema
57 Additional files may be available. Please consult the OpenLDAP
58 {{TERM:FAQ}} ({{URL:http://www.openldap.org/faq/}}).
60 Note: You should not modify any of the schema items defined
66 Schema used by {{slapd}}(8) may be extended to support additional
67 syntaxes, matching rules, attribute types, and object classes. This
68 chapter details how to add user application attribute types and
69 object classes using the syntaxes and matching rules already supported
70 by slapd. slapd can also be extended to support additional syntaxes,
71 matching rules and system schema, but this requires some programming
72 and hence is not discussed here.
74 There are five steps to defining new schema:
75 ^ obtain Object Identifer
76 + choose a name prefix
77 + create local schema file
78 + define custom attribute types (if necessary)
79 + define custom object classes
82 H3: Object Identifiers
84 Each schema element is identified by a globally unique {{TERM[expand]OID}}
85 (OID). OIDs are also used to identify other objects. They are
86 commonly found in protocols described by {{TERM:ASN.1}}. In
87 particular, they are heavily used by the {{TERM[expand]SNMP}} (SNMP).
88 As OIDs are hierarchical, your organization can obtain one OID and
89 branch it as needed. For example, if your organization were assigned
90 OID {{EX:1.1}}, you could branch the tree as follows:
92 !block table; colaligns="LR"; coltags="EX,N"; align=Center; \
93 title="Table 8.2: Example OID hierarchy"
95 1.1 Organization's OID
98 1.1.2.1 AttributeTypes
99 1.1.2.1.1 x-my-Attribute
100 1.1.2.2 ObjectClasses
101 1.1.2.2.1 x-my-ObjectClass
104 You are, of course, free to design a hierarchy suitable to your
105 organizational needs under your organization's OID. No matter what
106 hierarchy you choose, you should maintain a registry of assignments
107 you make. This can be a simple flat file or something more
108 sophisticated such as the {{OpenLDAP OID Registry}}
109 ({{URL:http://www.openldap.org/faq/index.cgi?file=197}}).
111 For more information about Object Identifers (and a listing service)
112 see {{URL:http://www.alvestrand.no/harald/objectid/}}.
114 .{{Under no circumstances should you hijack OID namespace!}}
116 To obtain a registered OID at {{no cost}}, apply for an OID under
117 the {{ORG[expand]IANA}} (ORG:IANA) maintained {{Private Enterprise}}
118 arc. Any private enterprise (organization) may request an OID to
119 be assigned under this arc. Just fill out the IANA form
120 at {{URL: http://www.iana.org/cgi-bin/enterprise.pl}} and your
121 official OID will be sent to you usually within a few days. Your
122 base OID will be something like {{EX:1.3.6.1.4.1.X}} where {{EX:X}}
125 Note: Don't let the "MIB/SNMP" statement on the IANA page confuse
126 you. OIDs obtained using this form may be used for any purpose
127 including identifying LDAP schema elements.
129 Alternatively, OID name space may be available from a national
130 authority (e.g., {{ORG:ANSI}}, {{ORG:BSI}}).
135 In addition to assigning a unique object identifier to each schema
136 element, you should provide a least one textual name for each
137 element. Names should be registered with the {{ORG:IANA}} or
138 prefixed with "x-" to place in the "private use" name space.
140 The name should be both descriptive and not likely to clash with
141 names of other schema elements. In particular, any name you choose
142 should not clash with present or future Standard Track names (this
143 is assured if you registered names or use names begining with "x-").
145 It is noted that you can obtain your own registered name
146 prefix so as to avoid having to register your names individually.
147 See {{REF:RFC4520}} for details.
149 In the examples below, we have used a short prefix '{{EX:x-my-}}'.
150 Such a short prefix would only be suitable for a very large, global
151 organization. In general, we recommend something like '{{EX:x-de-Firm-}}'
152 (German company) or '{{EX:x-com-Example}}' (elements associated with
153 organization associated with {{EX:example.com}}).
156 H3: Local schema file
158 The {{EX:objectclass}} and {{EX:attributeTypes}} configuration file
159 directives can be used to define schema rules on entries in the
160 directory. It is customary to create a file to contain definitions
161 of your custom schema items. We recommend you create a file
162 {{F:local.schema}} in {{F:/usr/local/etc/openldap/schema/local.schema}}
163 and then include this file in your {{slapd.conf}}(5) file immediately
164 after other schema {{EX:include}} directives.
167 > include /usr/local/etc/openldap/schema/core.schema
168 > include /usr/local/etc/openldap/schema/cosine.schema
169 > include /usr/local/etc/openldap/schema/inetorgperson.schema
170 > # include local schema
171 > include /usr/local/etc/openldap/schema/local.schema
174 H3: Attribute Type Specification
176 The {{attributetype}} directive is used to define a new attribute
177 type. The directive uses the same Attribute Type Description
178 (as defined in {{REF:RFC4512}}) used by the attributeTypes
179 attribute found in the subschema subentry, e.g.:
181 E: attributetype <{{REF:RFC4512}} Attribute Type Description>
183 where Attribute Type Description is defined by the following
186 > AttributeTypeDescription = "(" whsp
187 > numericoid whsp ; AttributeType identifier
188 > [ "NAME" qdescrs ] ; name used in AttributeType
189 > [ "DESC" qdstring ] ; description
190 > [ "OBSOLETE" whsp ]
191 > [ "SUP" woid ] ; derived from this other
193 > [ "EQUALITY" woid ; Matching Rule name
194 > [ "ORDERING" woid ; Matching Rule name
195 > [ "SUBSTR" woid ] ; Matching Rule name
196 > [ "SYNTAX" whsp noidlen whsp ] ; Syntax OID
197 > [ "SINGLE-VALUE" whsp ] ; default multi-valued
198 > [ "COLLECTIVE" whsp ] ; default not collective
199 > [ "NO-USER-MODIFICATION" whsp ]; default user modifiable
200 > [ "USAGE" whsp AttributeUsage ]; default userApplications
204 > "userApplications" /
205 > "directoryOperation" /
206 > "distributedOperation" / ; DSA-shared
207 > "dSAOperation" ; DSA-specific, value depends on server
210 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
211 OID in dotted-decimal form (e.g. {{EX:1.1.0}}), qdescrs is one or
212 more names, woid is either the name or OID optionally followed
213 by a length specifier (e.g {{EX:{10}}}).
215 For example, the attribute types {{EX:name}} and {{EX:cn}} are defined
216 in {{F:core.schema}} as:
218 > attributeType ( 2.5.4.41 NAME 'name'
219 > DESC 'name(s) associated with the object'
220 > EQUALITY caseIgnoreMatch
221 > SUBSTR caseIgnoreSubstringsMatch
222 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} )
223 > attributeType ( 2.5.4.3 NAME ( 'cn' 'commonName' )
224 > DESC 'common name(s) assciated with the object'
227 Notice that each defines the attribute's OID, provides a short name,
228 and a brief description. Each name is an alias for the OID.
229 {{slapd}}(8) returns the first listed name when returning results.
231 The first attribute, {{EX:name}}, holds values of {{EX:directoryString}}
232 ({{TERM:UTF-8}} encoded Unicode) syntax. The syntax is
233 specified by OID (1.3.6.1.4.1.1466.115.121.1.15 identifies the
234 directoryString syntax). A length recommendation of 32768 is
235 specified. Servers should support values of this length, but may
236 support longer values The field does NOT specify a size constraint,
237 so is ignored on servers (such as slapd) which don't impose such
238 size limits. In addition, the equality and substring matching uses
239 case ignore rules. Below are tables listing commonly used syntax
240 and matching rules ({{slapd}}(8) supports these and many more).
242 !block table; align=Center; coltags="EX,EX,N"; \
243 title="Table 8.3: Commonly Used Syntaxes"
245 boolean 1.3.6.1.4.1.1466.115.121.1.7 boolean value
246 directoryString 1.3.6.1.4.1.1466.115.121.1.15 Unicode (UTF-8) string
247 distinguishedName 1.3.6.1.4.1.1466.115.121.1.12 LDAP {{TERM:DN}}
248 integer 1.3.6.1.4.1.1466.115.121.1.27 integer
249 numericString 1.3.6.1.4.1.1466.115.121.1.36 numeric string
250 OID 1.3.6.1.4.1.1466.115.121.1.38 object identifier
251 octetString 1.3.6.1.4.1.1466.115.121.1.40 arbitary octets
256 !block table; align=Center; coltags="EX,N"; \
257 title="Table 8.4: Commonly Used Matching Rules"
258 Name Type Description
259 booleanMatch equality boolean
260 caseIgnoreMatch equality case insensitive, space insensitive
261 caseIgnoreOrderingMatch ordering case insensitive, space insensitive
262 caseIgnoreSubstringsMatch substrings case insensitive, space insensitive
263 caseExactMatch equality case sensitive, space insensitive
264 caseExactOrderingMatch ordering case sensitive, space insensitive
265 caseExactSubstringsMatch substrings case sensitive, space insensitive
266 distinguishedNameMatch equality distinguished name
267 integerMatch equality integer
268 integerOrderingMatch ordering integer
269 numericStringMatch equality numerical
270 numericStringOrderingMatch ordering numerical
271 numericStringSubstringsMatch substrings numerical
272 octetStringMatch equality octet string
273 octetStringOrderingStringMatch ordering octet string
274 octetStringSubstringsStringMatch ordering octet string
275 objectIdentiferMatch equality object identifier
278 The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence
279 it inherits the syntax, matching rules, and usage of {{EX:name}}.
280 {{EX:commonName}} is an alternative name.
282 Neither attribute is restricted to a single value. Both are meant
283 for usage by user applications. Neither is obsolete nor collective.
285 The following subsections provide a couple of examples.
290 Many organizations maintain a single unique name for each user.
291 Though one could use {{EX:displayName}} ({{REF:RFC2798}}), this
292 attribute is really meant to be controlled by the user, not the
293 organization. We could just copy the definition of {{EX:displayName}}
294 from {{F:inetorgperson.schema}} and replace the OID, name, and
297 > attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName'
298 > DESC 'unique name with my organization'
299 > EQUALITY caseIgnoreMatch
300 > SUBSTR caseIgnoreSubstringsMatch
301 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
304 However, if we want this name to be used in {{EX:name}} assertions,
305 e.g. {{EX:(name=*Jane*)}}, the attribute could alternatively be
306 defined as a subtype of {{EX:name}}, e.g.:
308 > attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName'
309 > DESC 'unique name with my organization'
315 Many organizations maintain a photo of each each user. A
316 {{EX:x-my-Photo}} attribute type could be defined to hold a photo.
317 Of course, one could use just use {{EX:jpegPhoto}} ({{REF:RFC2798}})
318 (or a subtype) to hold the photo. However, you can only do
319 this if the photo is in {{JPEG File Interchange Format}}.
320 Alternatively, an attribute type which uses the {{Octet String}}
321 syntax can be defined, e.g.:
323 > attributetype ( 1.1.2.1.2 NAME 'x-my-Photo'
324 > DESC 'a photo (application defined format)'
325 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
328 In this case, the syntax doesn't specify the format of the photo.
329 It's assumed (maybe incorrectly) that all applications accessing
330 this attribute agree on the handling of values.
332 If you wanted to support multiple photo formats, you could define
333 a separate attribute type for each format, prefix the photo
334 with some typing information, or describe the value using
335 {{TERM:ASN.1}} and use the {{EX:;binary}} transfer option.
337 Another alternative is for the attribute to hold a {{TERM:URI}}
338 pointing to the photo. You can model such an attribute after
339 {{EX:labeledURI}} ({{REF:RFC2079}}) or simply create a subtype,
342 > attributetype ( 1.1.2.1.3 NAME 'x-my-PhotoURI'
343 > DESC 'URI and optional label referring to a photo'
347 H3: Object Class Specification
349 The {{objectclasses}} directive is used to define a new object
350 class. The directive uses the same Object Class Description
351 (as defined in {{REF:RFC4512}}) used by the objectClasses
352 attribute found in the subschema subentry, e.g.:
354 E: objectclass <{{REF:RFC4512}} Object Class Description>
356 where Object Class Description is defined by the following
359 > ObjectClassDescription = "(" whsp
360 > numericoid whsp ; ObjectClass identifier
362 > [ "DESC" qdstring ]
363 > [ "OBSOLETE" whsp ]
364 > [ "SUP" oids ] ; Superior ObjectClasses
365 > [ ( "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" ) whsp ]
366 > ; default structural
367 > [ "MUST" oids ] ; AttributeTypes
368 > [ "MAY" oids ] ; AttributeTypes
371 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
372 OID in dotted-decimal form (e.g. {{EX:1.1.0}}), qdescrs is one or more
373 names, and oids is one or more names and/or OIDs.
378 To define an {{auxiliary}} object class which allows
379 x-my-Photo to be added to any existing entry.
381 > objectclass ( 1.1.2.2.1 NAME 'x-my-PhotoObject'
382 > DESC 'mixin x-my-Photo'
389 If your organization would like have a private {{structural}}
390 object class to instantiate users, you can subclass one of
391 the existing person classes, such as {{EX:inetOrgPerson}}
392 ({{REF:RFC2798}}), and add any additional attributes which
395 > objectclass ( 1.1.2.2.2 NAME 'x-my-Person'
398 > MUST ( x-my-UniqueName $ givenName )
401 The object class inherits the required/allowed attribute
402 types of {{EX:inetOrgPerson}} but requires {{EX:x-my-UniqueName}}
403 and {{EX:givenName}} and allows {{EX:x-my-Photo}}.
406 H2: Transferring Schema
408 Since the {{slapd.conf}}(5) schema directives use {{REF:RFC4512}}
409 format values, you can extract schema elements published by any
410 {{TERM:LDAPv3}} server and easily construct directives for use with
413 LDAPv3 servers publish schema elements in special {{subschema}}
414 entries (or subentries). While {{slapd}}(8) publishes a single
415 subschema subentry normally named {{EX:cn=Subschema}}, this behavior
416 cannot be expected from other servers. The subschema subentry
417 controlling a particular entry can be obtained by examining the
418 {{EX:subschemaSubentry}} attribute contained in the entry at the
419 root of each administrative context. For example,
421 > ldapsearch -LLL -x -b "dc=example,dc=com" -s base "(objectclass=*)" subschemaSubentry
423 To obtain the schema from a subschema subentry, you can use
424 ldapsearch(1) as follows (replace the search base as needed):
426 > ldapsearch -LLL -x -b "cn=Subschema" -s base "(objectclass=subschema)" attributeTypes objectClasses
428 where "cn=Subschema" is the value of subschemaSubentry returned in
431 This will return {{TERM:LDIF}} output containing many type/value
432 pairs. The following is an abbreviated example:
435 > objectClasses: ( 1.1.2.2.2 NAME 'x-my-Person' DESC 'my person' SUP inet
436 > OrgPerson MUST ( x-my-UniqueName $ givenName ) MAY x-my-Photo )
437 > attributeTypes: ( 1.1.2.1.1 NAME 'x-my-UniqueName' DESC 'unique name wi
438 > th my organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstrin
439 > gsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
440 > attributeTypes: ( 1.1.2.1.2 NAME 'x-my-Photo' DESC 'a photo (applicatio
441 > n defined format)' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
443 Capture the output of the search in a file and then edit the file:
445 + to contain only desired type/value pairs
446 ^ join LDIF continuation lines
447 ^ replace attribute type with directive name
448 (e.g. {{EX:s/attributeTypes:/attributeType /}} and
449 {{EX:s/objectClasses:/objectClass /}}).
450 ^ reorder lines so each element is defined before first use
451 ^ continue long directives over multiple lines
453 For the three type/value pairs in our example, the edit should
454 result in a file with contains of:
456 > attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName'
457 > DESC 'unique name with my organization'
458 > EQUALITY caseIgnoreMatch
459 > SUBSTR caseIgnoreSubstringsMatch
460 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
462 > attributeType ( 1.1.2.1.2 NAME 'x-my-Photo'
463 > DESC 'a photo (application defined format)'
464 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
465 > objectClass ( 1.1.2.2.2 NAME 'x-my-Person'
468 > MUST ( x-my-UniqueName $ givenName )
471 Save in an appropriately named file (e.g. {{F:local.schema}}).
472 You may now include this file in your {{slapd.conf}}(5) file.
478 To ease the management and use of OIDs, {{slapd}}(8) supports
479 {{Object Identifier}} macros. The {{EX:objectIdentifier}} directive
480 is used to equate a macro (name) with a OID. The OID may possibly
481 be derived from a previously defined OID macro. The {{slapd.conf}}(5)
484 E: objectIdentifier <name> { <oid> | <name>[:<suffix>] }
486 The following demonstrates definition of a set of OID macros
487 and their use in defining schema elements:
489 > objectIdentifier myOID 1.1
490 > objectIdentifier mySNMP myOID:1
491 > objectIdentifier myLDAP myOID:2
492 > objectIdentifier myAttributeType myLDAP:1
493 > objectIdentifier myObjectClass myLDAP:2
494 > attributetype ( myAttributeType:3 NAME 'x-my-PhotoURI'
495 > DESC 'URI and optional label referring to a photo'
497 > objectclass ( myObjectClass:1 NAME 'x-my-PhotoObject'
498 > DESC 'mixin x-my-Photo'