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 ({{TERM[expand]PEN}})
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 ({{TERM[expand]PEN}} - PEN)
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.
106 No matter what hierarchy you choose, you should maintain a registry
107 of assignments you make. This can be a simple flat file or something
108 more 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 {{TERM[expand]PEN}}at {{no cost}}, apply for a PEN
117 under the {{ORG[expand]IANA}} (ORG:IANA) maintained {{Private Enterprise}} arc.
118 Any private enterprise (organization) may request an PEN to be assigned under
119 this arc. Just fill out the IANA form at {{URL: http://pen.iana.org/pen/PenApplication.page}}
120 and your official PEN will be sent to you usually within a few days.
121 Your base OID will be something like {{EX:1.3.6.1.4.1.X}} where {{EX:X}} is an integer.
123 Note: Don't let the "MIB/SNMP" statement on the IANA page confuse
124 you. OIDs obtained using this form may be used for any purpose
125 including identifying LDAP schema elements.
127 Alternatively, OID name space may be available from a national
128 authority (e.g., {{ORG:ANSI}}, {{ORG:BSI}}).
133 In addition to assigning a unique object identifier to each schema
134 element, you should provide a least one textual name for each
135 element. Names should be registered with the {{ORG:IANA}} or
136 prefixed with "x-" to place in the "private use" name space.
138 The name should be both descriptive and not likely to clash with
139 names of other schema elements. In particular, any name you choose
140 should not clash with present or future Standard Track names (this
141 is assured if you registered names or use names begining with "x-").
143 It is noted that you can obtain your own registered name
144 prefix so as to avoid having to register your names individually.
145 See {{REF:RFC4520}} for details.
147 In the examples below, we have used a short prefix '{{EX:x-my-}}'.
148 Such a short prefix would only be suitable for a very large, global
149 organization. In general, we recommend something like '{{EX:x-de-Firm-}}'
150 (German company) or '{{EX:x-com-Example}}' (elements associated with
151 organization associated with {{EX:example.com}}).
154 H3: Local schema file
156 The {{EX:objectclass}} and {{EX:attributeTypes}} configuration file
157 directives can be used to define schema rules on entries in the
158 directory. It is customary to create a file to contain definitions
159 of your custom schema items. We recommend you create a file
160 {{F:local.schema}} in {{F:/usr/local/etc/openldap/schema/local.schema}}
161 and then include this file in your {{slapd.conf}}(5) file immediately
162 after other schema {{EX:include}} directives.
165 > include /usr/local/etc/openldap/schema/core.schema
166 > include /usr/local/etc/openldap/schema/cosine.schema
167 > include /usr/local/etc/openldap/schema/inetorgperson.schema
168 > # include local schema
169 > include /usr/local/etc/openldap/schema/local.schema
172 H3: Attribute Type Specification
174 The {{attributetype}} directive is used to define a new attribute
175 type. The directive uses the same Attribute Type Description
176 (as defined in {{REF:RFC4512}}) used by the attributeTypes
177 attribute found in the subschema subentry, e.g.:
179 E: attributetype <{{REF:RFC4512}} Attribute Type Description>
181 where Attribute Type Description is defined by the following
184 > AttributeTypeDescription = "(" whsp
185 > numericoid whsp ; AttributeType identifier
186 > [ "NAME" qdescrs ] ; name used in AttributeType
187 > [ "DESC" qdstring ] ; description
188 > [ "OBSOLETE" whsp ]
189 > [ "SUP" woid ] ; derived from this other
191 > [ "EQUALITY" woid ; Matching Rule name
192 > [ "ORDERING" woid ; Matching Rule name
193 > [ "SUBSTR" woid ] ; Matching Rule name
194 > [ "SYNTAX" whsp noidlen whsp ] ; Syntax OID
195 > [ "SINGLE-VALUE" whsp ] ; default multi-valued
196 > [ "COLLECTIVE" whsp ] ; default not collective
197 > [ "NO-USER-MODIFICATION" whsp ]; default user modifiable
198 > [ "USAGE" whsp AttributeUsage ]; default userApplications
202 > "userApplications" /
203 > "directoryOperation" /
204 > "distributedOperation" / ; DSA-shared
205 > "dSAOperation" ; DSA-specific, value depends on server
208 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
209 OID in dotted-decimal form (e.g. {{EX:1.1.0}}), qdescrs is one or
210 more names, woid is either the name or OID optionally followed
211 by a length specifier (e.g {{EX:{10}}}).
213 For example, the attribute types {{EX:name}} and {{EX:cn}} are defined
214 in {{F:core.schema}} as:
216 > attributeType ( 2.5.4.41 NAME 'name'
217 > DESC 'name(s) associated with the object'
218 > EQUALITY caseIgnoreMatch
219 > SUBSTR caseIgnoreSubstringsMatch
220 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} )
221 > attributeType ( 2.5.4.3 NAME ( 'cn' 'commonName' )
222 > DESC 'common name(s) assciated with the object'
225 Notice that each defines the attribute's OID, provides a short name,
226 and a brief description. Each name is an alias for the OID.
227 {{slapd}}(8) returns the first listed name when returning results.
229 The first attribute, {{EX:name}}, holds values of {{EX:directoryString}}
230 ({{TERM:UTF-8}} encoded Unicode) syntax. The syntax is
231 specified by OID (1.3.6.1.4.1.1466.115.121.1.15 identifies the
232 directoryString syntax). A length recommendation of 32768 is
233 specified. Servers should support values of this length, but may
234 support longer values The field does NOT specify a size constraint,
235 so is ignored on servers (such as slapd) which don't impose such
236 size limits. In addition, the equality and substring matching uses
237 case ignore rules. Below are tables listing commonly used syntax
238 and matching rules ({{slapd}}(8) supports these and many more).
240 !block table; align=Center; coltags="EX,EX,N"; \
241 title="Table 8.3: Commonly Used Syntaxes"
243 boolean 1.3.6.1.4.1.1466.115.121.1.7 boolean value
244 directoryString 1.3.6.1.4.1.1466.115.121.1.15 Unicode (UTF-8) string
245 distinguishedName 1.3.6.1.4.1.1466.115.121.1.12 LDAP {{TERM:DN}}
246 integer 1.3.6.1.4.1.1466.115.121.1.27 integer
247 numericString 1.3.6.1.4.1.1466.115.121.1.36 numeric string
248 OID 1.3.6.1.4.1.1466.115.121.1.38 object identifier
249 octetString 1.3.6.1.4.1.1466.115.121.1.40 arbitary octets
254 !block table; align=Center; coltags="EX,N"; \
255 title="Table 8.4: Commonly Used Matching Rules"
256 Name Type Description
257 booleanMatch equality boolean
258 caseIgnoreMatch equality case insensitive, space insensitive
259 caseIgnoreOrderingMatch ordering case insensitive, space insensitive
260 caseIgnoreSubstringsMatch substrings case insensitive, space insensitive
261 caseExactMatch equality case sensitive, space insensitive
262 caseExactOrderingMatch ordering case sensitive, space insensitive
263 caseExactSubstringsMatch substrings case sensitive, space insensitive
264 distinguishedNameMatch equality distinguished name
265 integerMatch equality integer
266 integerOrderingMatch ordering integer
267 numericStringMatch equality numerical
268 numericStringOrderingMatch ordering numerical
269 numericStringSubstringsMatch substrings numerical
270 octetStringMatch equality octet string
271 octetStringOrderingStringMatch ordering octet string
272 octetStringSubstringsStringMatch ordering octet string
273 objectIdentiferMatch equality object identifier
276 The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence
277 it inherits the syntax, matching rules, and usage of {{EX:name}}.
278 {{EX:commonName}} is an alternative name.
280 Neither attribute is restricted to a single value. Both are meant
281 for usage by user applications. Neither is obsolete nor collective.
283 The following subsections provide a couple of examples.
288 Many organizations maintain a single unique name for each user.
289 Though one could use {{EX:displayName}} ({{REF:RFC2798}}), this
290 attribute is really meant to be controlled by the user, not the
291 organization. We could just copy the definition of {{EX:displayName}}
292 from {{F:inetorgperson.schema}} and replace the OID, name, and
295 > attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName'
296 > DESC 'unique name with my organization'
297 > EQUALITY caseIgnoreMatch
298 > SUBSTR caseIgnoreSubstringsMatch
299 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
302 However, if we want this name to be used in {{EX:name}} assertions,
303 e.g. {{EX:(name=*Jane*)}}, the attribute could alternatively be
304 defined as a subtype of {{EX:name}}, e.g.:
306 > attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName'
307 > DESC 'unique name with my organization'
313 Many organizations maintain a photo of each each user. A
314 {{EX:x-my-Photo}} attribute type could be defined to hold a photo.
315 Of course, one could use just use {{EX:jpegPhoto}} ({{REF:RFC2798}})
316 (or a subtype) to hold the photo. However, you can only do
317 this if the photo is in {{JPEG File Interchange Format}}.
318 Alternatively, an attribute type which uses the {{Octet String}}
319 syntax can be defined, e.g.:
321 > attributetype ( 1.1.2.1.2 NAME 'x-my-Photo'
322 > DESC 'a photo (application defined format)'
323 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
326 In this case, the syntax doesn't specify the format of the photo.
327 It's assumed (maybe incorrectly) that all applications accessing
328 this attribute agree on the handling of values.
330 If you wanted to support multiple photo formats, you could define
331 a separate attribute type for each format, prefix the photo
332 with some typing information, or describe the value using
333 {{TERM:ASN.1}} and use the {{EX:;binary}} transfer option.
335 Another alternative is for the attribute to hold a {{TERM:URI}}
336 pointing to the photo. You can model such an attribute after
337 {{EX:labeledURI}} ({{REF:RFC2079}}) or simply create a subtype,
340 > attributetype ( 1.1.2.1.3 NAME 'x-my-PhotoURI'
341 > DESC 'URI and optional label referring to a photo'
345 H3: Object Class Specification
347 The {{objectclasses}} directive is used to define a new object
348 class. The directive uses the same Object Class Description
349 (as defined in {{REF:RFC4512}}) used by the objectClasses
350 attribute found in the subschema subentry, e.g.:
352 E: objectclass <{{REF:RFC4512}} Object Class Description>
354 where Object Class Description is defined by the following
357 > ObjectClassDescription = "(" whsp
358 > numericoid whsp ; ObjectClass identifier
360 > [ "DESC" qdstring ]
361 > [ "OBSOLETE" whsp ]
362 > [ "SUP" oids ] ; Superior ObjectClasses
363 > [ ( "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" ) whsp ]
364 > ; default structural
365 > [ "MUST" oids ] ; AttributeTypes
366 > [ "MAY" oids ] ; AttributeTypes
369 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
370 OID in dotted-decimal form (e.g. {{EX:1.1.0}}), qdescrs is one or more
371 names, and oids is one or more names and/or OIDs.
376 To define an {{auxiliary}} object class which allows
377 x-my-Photo to be added to any existing entry.
379 > objectclass ( 1.1.2.2.1 NAME 'x-my-PhotoObject'
380 > DESC 'mixin x-my-Photo'
387 If your organization would like have a private {{structural}}
388 object class to instantiate users, you can subclass one of
389 the existing person classes, such as {{EX:inetOrgPerson}}
390 ({{REF:RFC2798}}), and add any additional attributes which
393 > objectclass ( 1.1.2.2.2 NAME 'x-my-Person'
396 > MUST ( x-my-UniqueName $ givenName )
399 The object class inherits the required/allowed attribute
400 types of {{EX:inetOrgPerson}} but requires {{EX:x-my-UniqueName}}
401 and {{EX:givenName}} and allows {{EX:x-my-Photo}}.
404 H2: Transferring Schema
406 Since the {{slapd.conf}}(5) schema directives use {{REF:RFC4512}}
407 format values, you can extract schema elements published by any
408 {{TERM:LDAPv3}} server and easily construct directives for use with
411 LDAPv3 servers publish schema elements in special {{subschema}}
412 entries (or subentries). While {{slapd}}(8) publishes a single
413 subschema subentry normally named {{EX:cn=Subschema}}, this behavior
414 cannot be expected from other servers. The subschema subentry
415 controlling a particular entry can be obtained by examining the
416 {{EX:subschemaSubentry}} attribute contained in the entry at the
417 root of each administrative context. For example,
419 > ldapsearch -LLL -x -b "dc=example,dc=com" -s base "(objectclass=*)" subschemaSubentry
421 To obtain the schema from a subschema subentry, you can use
422 ldapsearch(1) as follows (replace the search base as needed):
424 > ldapsearch -LLL -x -b "cn=Subschema" -s base "(objectclass=subschema)" attributeTypes objectClasses
426 where "cn=Subschema" is the value of subschemaSubentry returned in
429 This will return {{TERM:LDIF}} output containing many type/value
430 pairs. The following is an abbreviated example:
433 > objectClasses: ( 1.1.2.2.2 NAME 'x-my-Person' DESC 'my person' SUP inet
434 > OrgPerson MUST ( x-my-UniqueName $ givenName ) MAY x-my-Photo )
435 > attributeTypes: ( 1.1.2.1.1 NAME 'x-my-UniqueName' DESC 'unique name wi
436 > th my organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstrin
437 > gsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
438 > attributeTypes: ( 1.1.2.1.2 NAME 'x-my-Photo' DESC 'a photo (applicatio
439 > n defined format)' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
441 Capture the output of the search in a file and then edit the file:
443 + to contain only desired type/value pairs
444 ^ join LDIF continuation lines
445 ^ replace attribute type with directive name
446 (e.g. {{EX:s/attributeTypes:/attributeType /}} and
447 {{EX:s/objectClasses:/objectClass /}}).
448 ^ reorder lines so each element is defined before first use
449 ^ continue long directives over multiple lines
451 For the three type/value pairs in our example, the edit should
452 result in a file with contains of:
454 > attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName'
455 > DESC 'unique name with my organization'
456 > EQUALITY caseIgnoreMatch
457 > SUBSTR caseIgnoreSubstringsMatch
458 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
460 > attributeType ( 1.1.2.1.2 NAME 'x-my-Photo'
461 > DESC 'a photo (application defined format)'
462 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
463 > objectClass ( 1.1.2.2.2 NAME 'x-my-Person'
466 > MUST ( x-my-UniqueName $ givenName )
469 Save in an appropriately named file (e.g. {{F:local.schema}}).
470 You may now include this file in your {{slapd.conf}}(5) file.
476 To ease the management and use of OIDs, {{slapd}}(8) supports
477 {{Object Identifier}} macros. The {{EX:objectIdentifier}} directive
478 is used to equate a macro (name) with a OID. The OID may possibly
479 be derived from a previously defined OID macro. The {{slapd.conf}}(5)
482 E: objectIdentifier <name> { <oid> | <name>[:<suffix>] }
484 The following demonstrates definition of a set of OID macros
485 and their use in defining schema elements:
487 > objectIdentifier myOID 1.1
488 > objectIdentifier mySNMP myOID:1
489 > objectIdentifier myLDAP myOID:2
490 > objectIdentifier myAttributeType myLDAP:1
491 > objectIdentifier myObjectClass myLDAP:2
492 > attributetype ( myAttributeType:3 NAME 'x-my-PhotoURI'
493 > DESC 'URI and optional label referring to a photo'
495 > objectclass ( myObjectClass:1 NAME 'x-my-PhotoObject'
496 > DESC 'mixin x-my-Photo'