2 # Copyright 1999-2000, 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 {{slapd}}(8).
8 The first section, {{SECT:Distributed Schema Files}} details optional
9 schema definitions provided in the distribution and where to obtain
11 The second section, {{SECT:Extending Schema}}, details how to define
14 The third section, {{SECT:Transferring Schema}} details how you can
15 export schema definitions from an LDAPv3 server and transform it
16 to {{slapd.conf}}(5) format.
19 This chapter does discuss how to extend system schema used by
20 {{slapd}}(8) as this requires source code modification. System
21 schema includes all operational attribute types or any object class
22 which allows or requires an operational attribute (directly or
26 H2: Distributed Schema Files
28 OpenLDAP is distributed with a set of schema specifications for
29 your use. Each set is defined in a file suitable for inclusion
30 (using the {{EX:include}} directive) in your {{slapd.conf}}(5)
31 file. These schema files are normally installed in the
32 {{F:/usr/local/etc/openldap/schema}} directory.
34 !block table; colaligns="LR"; coltags="F,N"; align=Center; \
35 title="Table 8.1: Provided Schema Specifications"
37 core.schema OpenLDAP {{core}} (required)
38 cosine.schema Cosine and Internet X.500 (useful)
39 inetorgperson.schema InetOrgPerson (useful)
40 misc.schema Assorted (experimental)
41 nis.schema Network Information Services (FYI)
42 openldap.schema OpenLDAP Project (experimental)
45 To use any of these schema files, you only need to include the
46 desired file in the global definitions portion of your
47 {{slapd.conf}}(5) file. For example:
50 > include /usr/local/etc/openldap/schema/core.schema
51 > include /usr/local/etc/openldap/schema/cosine.schema
52 > include /usr/local/etc/openldap/schema/inetorgperson.schema
54 Additional files may be available. Please consult the OpenLDAP
55 FAQ ({{URL:http://www.openldap.org/faq/}}).
57 Note: You should not modify any of the schema items defined
63 Schema used by {{slapd}}(8) may be extended to support additional
64 syntaxes, matching rules, attribute types, and object classes. This
65 chapter details how to add user application attribute types and
66 object classes using the syntaxes and matching rules already supported
67 by slapd. slapd can also be extended to support additional syntaxes,
68 matching rules and system schema, but this requires some programming
69 and hence is not discussed here.
71 There are five steps to defining new schema:
72 ^ obtain Object Identifer
73 + choose a name prefix
74 + create local schema file
75 + define custom attribute types (if necessary)
76 + define custom object classes
79 H3: Object Identifiers
81 Each schema element is identified by a globally unique
82 {{TERM[expand]OID}} (OID). OIDs are also used to identify
84 They are commonly found in protocols described by {{TERM:ASN.1}}. In
85 particular, they are heavily used by the {{TERM[expand]SNMP}} (SNMP).
86 As OIDs are hierarchical, your organization
87 can obtain one OID and branch it as needed. For example,
88 if your organization were assigned OID {{EX:1.1}}, you could branch
91 !block table; colaligns="LR"; coltags="EX,N"; align=Center; \
92 title="Table 8.2: Example OID hierarchy"
94 1.1 Organization's OID
97 1.1.2.1 AttributeTypes
100 1.1.2.2.1 myObjectClass
103 You are, of course, free to design a hierarchy suitable to your
104 organizational needs under your organization's OID. No matter what
105 hierarchy you choose, you should maintain a registry of assignments
106 you make. This can be a simple flat file or something more
107 sophisticated such as the {{OpenLDAP OID Registry}}
108 ({{URL:http://www.openldap.org/faq/index.cgi?file=197}}).
110 For more information about Object Identifers (and a listing service)
111 see {{URL:http://www.alvestrand.no/harald/objectid/}}.
113 .{{Under no circumstances should you hijack OID namespace!}}
115 To obtain a registered OID at {{no cost}}, apply for an OID under
116 the {{ORG[expand]IANA}} (IANA) maintained {{Private Enterprise}}
117 arc. Any private enterprise (organization) may request an OID to
118 be assigned under this arc. Just fill out the {{ORG:IANA}} form
119 at {{URL: http://www.iana.org/cgi-bin/enterprise.pl}} and your
120 official OID will be sent to you usually within a few days. Your
121 base OID will be something like {{EX:1.3.6.1.4.1.X}} where {{EX:X}}
124 Note: Don't let the "MIB/SNMP" statement on the IANA page confuse
125 you. OIDs obtained using this form may be used for any purpose
126 including identifying LDAP schema elements.
128 Alternatively, OID name space may be available from a national
129 authority (e.g., ANSI, BSI).
131 For private experiments, OIDs under {{EX:1.1}} may be used. The
132 OID {{EX:1.1}} arc is regarded as dead name space.
137 In addition to assigning a unique object identifier to each schema
138 element, you should provide a least one textual name for each
139 element. The name should be both descriptive and not likely to
140 clash with names of other schema elements. In particular, any name
141 you choose should not clash with present or future Standard Track
144 To reduce (but not eliminate) the potential for name clashes, the
145 convention is to prefix names of non-Standard Track with a few
146 letters to localize the changes to your organization. The smaller
147 the organization, the longer your prefix should be.
149 In the examples below, we have chosen a short prefix '{{EX:my}}'
150 (to save space). Such a short prefix would only be suitable for a
151 very large, global organization. In general, we recommend something
152 like '{{EX:deFirm}}' (German company) or '{{EX:comExample}}' (elements
153 associated with 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:RFC2252}}) used by the attributeTypes
179 attribute found in the subschema subentry, e.g.:
181 E: attributetype <{{REF:RFC2252}} 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 (UTF-8 encoded Unicode) syntax. The syntax is specified by OID
233 (1.3.6.1.4.1.1466.115.121.1.15 identifies the directoryString
234 syntax). A length recommendation of 32768 is specified. Servers
235 should support values of this length, but may support longer values
236 The field does NOT specify a size constraint, so is ignored on
237 servers (such as slapd) which don't impose such size limits. In
238 addition, the equality and substring matching uses case ignore
239 rules. Below are tables listing commonly used syntax and
240 matching rules (OpenLDAP 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 distinguishedName 1.3.6.1.4.1.1466.115.121.1.12 DN
247 directoryString 1.3.6.1.4.1.1466.115.121.1.15 UTF-8 string
248 IA5String 1.3.6.1.4.1.1466.115.121.1.26 ASCII string
249 Integer 1.3.6.1.4.1.1466.115.121.1.27 integer
250 Name and Optional UID 1.3.6.1.4.1.1466.115.121.1.34 DN plus UID
251 Numeric String 1.3.6.1.4.1.1466.115.121.1.36 numeric string
252 OID 1.3.6.1.4.1.1466.115.121.1.38 object identifier
253 Octet String 1.3.6.1.4.1.1466.115.121.1.40 arbitary octets
254 Printable String 1.3.6.1.4.1.1466.115.121.1.44 printable string
259 !block table; align=Center; coltags="EX,N"; \
260 title="Table 8.4: Commonly Used Matching Rules"
261 Name Type Description
262 booleanMatch equality boolean
263 octetStringMatch equality octet string
264 objectIdentiferMatch equality OID
265 distinguishedNameMatch equality DN
266 uniqueMemberMatch equality Name with optional UID
267 numericStringMatch equality numerical
268 numericStringOrderingMatch ordering numerical
269 numericStringSubstringsMatch substrings numerical
270 caseIgnoreMatch equality case insensitive, space insensitive
271 caseIgnoreOrderingMatch ordering case insensitive, space insensitive
272 caseIgnoreSubstringsMatch substrings case insensitive, space insensitive
273 caseExactMatch equality case sensitive, space insensitive
274 caseExactOrderingMatch ordering case sensitive, space insensitive
275 caseExactSubstringsMatch substrings case sensitive, space insensitive
276 caseIgnoreIA5Match equality case insensitive, space insensitive
277 caseIgnoreIA5OrderingMatch ordering case insensitive, space insensitive
278 caseIgnoreIA5SubstringsMatch substrings case insensitive, space insensitive
279 caseExactIA5Match equality case sensitive, space insensitive
280 caseExactIA5OrderingMatch ordering case sensitive, space insensitive
281 caseExactIA5SubstringsMatch substrings case sensitive, space insensitive
284 The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence
285 it inherits the syntax, matching rules, and usage of {{EX:name}}.
286 {{EX:commonName}} is an alternative name.
288 Neither attribute is restricted to a single value. Both are meant
289 for usage by user applications. Neither is obsolete nor collective.
291 The following subsections provide a couple of examples.
296 Many organizations maintain a single unique name for each user.
297 Though one could use {{EX:displayName}} ({{REF:RFC2798}}), this
298 attribute is really meant to be controlled by the user, not the
299 organization. We could just copy the definition of {{EX:displayName}}
300 from {{F:inetorgperson.schema}} and replace the OID, name, and
303 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
304 > DESC 'unique name with my organization'
305 > EQUALITY caseIgnoreMatch
306 > SUBSTR caseIgnoreSubstringsMatch
307 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
310 However, if we want this name to be included in
311 {{EX:name}} assertions [e.g. {{EX:(name=*Jane*)}}], the attribute
312 could alternatively be defined as a subtype of {{EX:name}}, e.g.:
314 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
315 > DESC 'unique name with my organization'
321 Many organizations maintain a photo of each each user. A
322 {{EX:myPhoto}} attribute type could be defined to hold a photo.
323 Of course, one could use just use {{EX:jpegPhoto}} ({{REF:RFC2798}})
324 (or a subtype) to hold the photo. However, you can only do
325 this if the photo is in {{JPEG File Interchange Format}}.
326 Alternatively, an attribute type which uses the {{Octet String}}
327 syntax can be defined, e.g.:
329 > attributetype ( 1.1.2.1.2 NAME 'myPhoto'
330 > DESC 'a photo (application defined format)'
331 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
334 In this case, the syntax doesn't specify the format of the photo.
335 It's assumed (maybe incorrectly) that all applications accessing
336 this attribute agree on the handling of values.
338 If you wanted to support multiple photo formats, you could define
339 a separate attribute type for each format, prefix the photo
340 with some typing information, or describe the value using
341 {{TERM:ASN.1}} and use the {{EX:;binary}} transfer option.
343 Another alternative is for the attribute to hold a {{TERM:URI}}
344 pointing to the photo. You can model such an attribute after
345 {{EX:labeledURI}} ({{REF:RFC2079}}) or simply create a subtype,
348 > attributetype ( 1.1.2.1.3 NAME 'myPhotoURI'
349 > DESC 'URI and optional label referring to a photo'
353 H3: Object Class Specification
355 The {{objectclasses}} directive is used to define a new object
356 class. The directive uses the same Object Class Description
357 (as defined in {{REF:RFC2252}}) used by the objectClasses
358 attribute found in the subschema subentry, e.g.:
360 E: objectclass <{{REF:RFC2252}} Object Class Description>
362 where Object Class Description is defined by the following
365 > ObjectClassDescription = "(" whsp
366 > numericoid whsp ; ObjectClass identifier
368 > [ "DESC" qdstring ]
369 > [ "OBSOLETE" whsp ]
370 > [ "SUP" oids ] ; Superior ObjectClasses
371 > [ ( "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" ) whsp ]
372 > ; default structural
373 > [ "MUST" oids ] ; AttributeTypes
374 > [ "MAY" oids ] ; AttributeTypes
377 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
378 OID in numeric form (e.g. {{EX:1.1.0}}), qdescrs is one or more
379 names, and oids is one or more names and/or OIDs.
384 To define an {{auxiliary}} object class which allows
385 myPhoto to be added to any existing entry.
387 > objectclass ( 1.1.2.2.1 NAME 'myPhotoObject'
388 > DESC 'mixin myPhoto'
395 If your organization would like have a private {{structural}}
396 object class to instantiate users, you can subclass one of
397 the existing person classes, such as {{EX:inetOrgPerson}}
398 ({{REF:RFC2798}}), and add any additional attributes which
401 > objectclass ( 1.1.2.2.2 NAME 'myPerson'
404 > MUST ( myUniqueName $ givenName )
407 The object class inherits the required/allowed attribute
408 types of {{EX:inetOrgPerson}} but requires {{EX:myUniqueName}}
409 and {{EX:givenName}} and allows {{EX:myPhoto}}.
412 H2: Transferring Schema
414 Since the {{slapd.conf}}(5) schema directives use {{REF:RFC2252}}
415 format values, you can extract schema elements published by
416 any LDAPv3 server and easily construct directives for use with
419 LDAPv3 servers publish schema elements in special {{subschema}}
420 entries (or subentries). {{slapd}}(8) publishes a single subschema
421 entry normally named {{EX:cn=Subschema}}. In a server which
422 supports a single subschema subentry, the DN of the subschema
423 subenty can usually be found by examining the value of the
424 {{EX:subschemaSubentry}} attribute type in the {{root DSE}}.
425 Other servers may publish multiple subschema entries. These
426 can be located by examining the {{EX:subschemaSubentry}} attribute
427 contained in the entry at the root of each administrative context.
429 To obtain the schema from a subschema subentry, you can use
430 ldapsearch(1) as follows (replace the search base as needed):
432 > ldapsearch -LLL -x -b "cn=Subschema" -s base "(objectclass=subschema)" attributeTypes objectClasses
434 This will return {{TERM:LDIF}} output containing many type/value
435 pairs. The following is an abbreviated example:
438 > attributeTypes: ( 1.1.2.1.1 NAME 'myUniqueName' DESC 'unique name wi
439 > th my organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubst
440 > ringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
441 > attributeTypes: ( 1.1.2.1.2 NAME 'myPhoto' DESC 'a photo (applicatio
442 > n defined format)' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
443 > objectClasses: ( 1.1.2.2.2 NAME 'myPerson' DESC 'my person' SUP inet
444 > OrgPerson MUST ( myUniqueName $ givenName ) MAY myPhoto )
446 Capture the output of the search in a file and then edit the file:
448 + to contain only desired type/value pairs
449 ^ join LDIF continuation lines
450 ^ replace attribute type with directive name
451 (e.g. {{EX:s/attributeTypes:/attributeType/}} and
452 {{EX:s/objectClasses:/objectClass/}}).
453 ^ continue long directives over multiple lines
455 For the three type/value pairs in our example, the edit should
456 result in a file with contains of:
458 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
459 > DESC 'unique name with my organization'
460 > EQUALITY caseIgnoreMatch
461 > SUBSTR caseIgnoreSubstringsMatch
462 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
464 > attributeType ( 1.1.2.1.2 NAME 'myPhoto'
465 > DESC 'a photo (application defined format)'
466 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
467 > objectClass ( 1.1.2.2.2 NAME 'myPerson'
470 > MUST ( myUniqueName $ givenName )
473 Save in an appropriately named file (e.g. {{F:my.schema}}).
474 You may now include this file in your {{slapd.conf}}(5) file.
480 To ease the management and use of OIDs, {{slapd}}(8) supports
481 {{Object Identifier}} macros. The {{EX:objectIdentifier}} is used
482 to equate a macro (name) with a OID. The OID may possibly be derived
483 from a previously defined OID macro. The {{slapd.conf}}(5) syntax
486 E: objectIdentifier <name> { <oid> | <name>[:<suffix>] }
488 The following demonstrates definition of a set of OID macros
489 and their use in defining schema elements:
491 > objectIdentifier myOID 1.1
492 > objectIdentifier mySNMP myOID:1
493 > objectIdentifier myLDAP myOID:2
494 > objectIdentifier myAttributeType myLDAP:1
495 > objectIdentifier myObjectClass myLDAP:2
496 > attributetype ( myAttributeType:3 NAME 'myPhotoURI'
497 > DESC 'URI and optional label referring to a photo'
499 > objectclass ( myObjectClass:1 NAME 'myPhotoObject'
500 > DESC 'mixin myPhoto'