2 # Copyright 1999-2006 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 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 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
100 1.1.2.2 ObjectClasses
101 1.1.2.2.1 myObjectClass
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}} (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 {{ORG: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. The name should be both descriptive and not likely to
138 clash with names of other schema elements. In particular, any name
139 you choose should not clash with present or future Standard Track
142 To reduce (but not eliminate) the potential for name clashes, the
143 convention is to prefix names of non-Standard Track with a few
144 letters to localize the changes to your organization. The smaller
145 the organization, the longer your prefix should be.
147 In the examples below, we have chosen a short prefix '{{EX:my}}'
148 (to save space). Such a short prefix would only be suitable for a
149 very large, global organization. In general, we recommend something
150 like '{{EX:deFirm}}' (German company) or '{{EX:comExample}}' (elements
151 associated with 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:RFC2252}}) used by the attributeTypes
177 attribute found in the subschema subentry, e.g.:
179 E: attributetype <{{REF:RFC2252}} 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 (UTF-8 encoded Unicode) syntax. The syntax is specified by OID
231 (1.3.6.1.4.1.1466.115.121.1.15 identifies the directoryString
232 syntax). A length recommendation of 32768 is specified. Servers
233 should support values of this length, but may support longer values
234 The field does NOT specify a size constraint, so is ignored on
235 servers (such as slapd) which don't impose such size limits. In
236 addition, the equality and substring matching uses case ignore
237 rules. Below are tables listing commonly used syntax and
238 matching rules (OpenLDAP 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 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 'myUniqueName'
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 included in
303 {{EX:name}} assertions [e.g. {{EX:(name=*Jane*)}}], the attribute
304 could alternatively be defined as a subtype of {{EX:name}}, e.g.:
306 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
307 > DESC 'unique name with my organization'
313 Many organizations maintain a photo of each each user. A
314 {{EX:myPhoto}} 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 'myPhoto'
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 'myPhotoURI'
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:RFC2252}}) used by the objectClasses
350 attribute found in the subschema subentry, e.g.:
352 E: objectclass <{{REF:RFC2252}} 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 numeric 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 myPhoto to be added to any existing entry.
379 > objectclass ( 1.1.2.2.1 NAME 'myPhotoObject'
380 > DESC 'mixin myPhoto'
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 'myPerson'
396 > MUST ( myUniqueName $ givenName )
399 The object class inherits the required/allowed attribute
400 types of {{EX:inetOrgPerson}} but requires {{EX:myUniqueName}}
401 and {{EX:givenName}} and allows {{EX:myPhoto}}.
404 H2: Transferring Schema
406 Since the {{slapd.conf}}(5) schema directives use {{REF:RFC2252}}
407 format values, you can extract schema elements published by
408 any 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 'myPerson' DESC 'my person' SUP inet
434 > OrgPerson MUST ( myUniqueName $ givenName ) MAY myPhoto )
435 > attributeTypes: ( 1.1.2.1.1 NAME 'myUniqueName' DESC 'unique name wi
436 > th my organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubst
437 > ringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
438 > attributeTypes: ( 1.1.2.1.2 NAME 'myPhoto' 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 'myUniqueName'
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 'myPhoto'
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 'myPerson'
466 > MUST ( myUniqueName $ 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 'myPhotoURI'
493 > DESC 'URI and optional label referring to a photo'
495 > objectclass ( myObjectClass:1 NAME 'myPhotoObject'
496 > DESC 'mixin myPhoto'