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 H2: Distributed Schema Files
21 OpenLDAP is distributed with a set of schema specifications for
22 your use. Each set is defined in a file suitable for inclusion
23 (using the {{EX:include}} directive) in your {{slapd.conf}}(5)
24 file. These schema files are normally installed in the
25 {{F:/usr/local/etc/openldap/schema}} directory.
27 !block table; colaligns="LR"; coltags="F,N"; align=Center; \
28 title="Table 6.1: Provided Schema Specifications"
30 core.schema OpenLDAP {{core}} (required)
31 cosine.schema Cosine and Internet X.500 (useful)
32 inetorgperson.schema InetOrgPerson (useful)
33 misc.schema Assorted (experimental)
34 nis.schema Network Information Services (FYI)
35 openldap.schema OpenLDAP Project (experimental)
38 To use any of these schema files, you only need to include the
39 desired file in the global definitions portion of your
40 {{slapd.conf}}(5) file. For example:
43 > include /usr/local/etc/openldap/schema/core.schema
44 > include /usr/local/etc/openldap/schema/cosine.schema
45 > include /usr/local/etc/openldap/schema/inetorgperson.schema
47 Additional files may be available. Please consult the OpenLDAP
48 FAQ ({{URL:http://www.openldap.org/faq/}}).
50 Note: You should not modify any of the schema items defined
56 Schema used by {{slapd}}(8) may be extended to support additional
57 syntaxes, matching rules, attribute types, and object classes. This
58 chapter details how to add user application attribute types and
59 object classes using the syntaxes and matching rules already supported
60 by slapd. slapd can also be extended to support additional syntaxes,
61 matching rules and system schema, but this requires some programming
62 and hence is not discussed here.
64 There are five steps to defining new schema:
65 ^ obtain Object Identifer
66 + choose a name prefix
67 + create local schema file
68 + define custom attribute types (if necessary)
69 + define custom object classes
72 H3: Object Identifiers
74 Each schema element is identified by a globally unique
75 {{TERM[expand]OID}} (OID). OIDs are also used to identify
77 They are commonly found in protocols described by {{TERM:ASN.1}}. In
78 particular, they are heavily used by the {{TERM[expand]SNMP}} (SNMP).
79 As OIDs are hierarchical, your organization
80 can obtain one OID and branch it as needed. For example,
81 if your organization were assigned OID {{EX:1.1}}, you could branch
84 !block table; colaligns="LR"; coltags="EX,N"; align=Center; \
85 title="Table 6.2: Example OID hierarchy"
87 1.1 Organization's OID
90 1.1.2.1 AttributeTypes
93 1.1.2.2.1 myObjectClass
96 You are, of course, free to design a hierarchy suitable to your
97 organizational needs under your organization's OID. No matter
98 what hierarchy you choose, you should maintain a registry of
99 assignments you make. This can be a simple flat file or
100 something more sophisticated such as the {{OpenLDAP OID Registry}}
101 ({{URL:http://www.openldap.org/faq/index.cgi?file=197}}).
103 For more information about Object Identifers (and a listing
104 service) see {{URL:http://www.alvestrand.no/harald/objectid/}}.
106 .{{Under no circumstances should you use a fictitious OID!}}
108 To obtain a fully registered OID at {{no cost}}, apply for
109 an OID under the {{ORG[expand]IANA}} (IANA) maintained
110 {{Private Enterprise}} arch. Any private enterprise (organization)
111 may request an OID to be assigned under this arch. Just fill
112 out the {{ORG:IANA}} form at {{URL: http://www.iana.org/cgi-bin/enterprise.pl}}
113 and your official OID will be sent to you usually within a few days.
114 Your base OID will be something like {{EX:1.3.6.1.4.1.X}} where {{EX:X}}
117 Note: Don't let the "MIB/SNMP" statement on the IANA page confuse you.
118 OIDs obtained using this form may be used for any purpose including
119 identifying LDAP schema elements.
124 In addition to assigning a unique object identifier to each schema
125 element, you should provide a least one textual name for each
126 element. The name should be both descriptive and not likely
127 to clash with names of other schema elements. In particular,
128 any name you choose should not clash with present or future
129 Standard Track names.
131 To reduce (but not eliminate) the potential for name clashes,
132 the convention is to prefix names of non-Standard Track with
133 a few letters to localize the changes to your organization.
134 The smaller the organization, the longer your prefix should
137 In the examples below, we have chosen a short prefix '{{EX:my}}'
138 (to save space). Such a short prefix would only be suitable for
139 a very large, global organization. For a small, local organization,
140 we recommend something like '{{EX:deFirm}}' (German company) or
141 '{{EX:comExample}}' (elements associated with organization associated
142 with {{EX:example.com}}).
145 H3: Local schema file
147 The {{EX:objectclass}} and {{EX:attributeTypes}} configuration file
148 directives can be used to define schema rules on entries in the
149 directory. It is customary to create a file to contain definitions
150 of your custom schema items. We recommend you create a file
151 {{F:local.schema}} in {{F:/usr/local/etc/openldap/schema/local.schema}}
152 and then include this file in your {{slapd.conf}}(5) file immediately
153 after other schema {{EX:include}} directives.
156 > include /usr/local/etc/openldap/schema/core.schema
157 > include /usr/local/etc/openldap/schema/cosine.schema
158 > include /usr/local/etc/openldap/schema/inetorgperson.schema
159 > # include local schema
160 > include /usr/local/etc/openldap/schema/local.schema
163 H3: Attribute Type Specification
165 The {{attributetype}} directive is used to define a new attribute
166 type. The directive uses the same Attribute Type Description
167 (as defined in {{REF:RFC2252}}) used by the attributeTypes
168 attribute found in the subschema subentry, e.g.:
170 E: attributetype <{{REF:RFC2252}} Attribute Type Description>
172 where Attribute Type Description is defined by the following
175 > AttributeTypeDescription = "(" whsp
176 > numericoid whsp ; AttributeType identifier
177 > [ "NAME" qdescrs ] ; name used in AttributeType
178 > [ "DESC" qdstring ] ; description
179 > [ "OBSOLETE" whsp ]
180 > [ "SUP" woid ] ; derived from this other
182 > [ "EQUALITY" woid ; Matching Rule name
183 > [ "ORDERING" woid ; Matching Rule name
184 > [ "SUBSTR" woid ] ; Matching Rule name
185 > [ "SYNTAX" whsp noidlen whsp ] ; Syntax OID
186 > [ "SINGLE-VALUE" whsp ] ; default multi-valued
187 > [ "COLLECTIVE" whsp ] ; default not collective
188 > [ "NO-USER-MODIFICATION" whsp ]; default user modifiable
189 > [ "USAGE" whsp AttributeUsage ]; default userApplications
193 > "userApplications" /
194 > "directoryOperation" /
195 > "distributedOperation" / ; DSA-shared
196 > "dSAOperation" ; DSA-specific, value depends on server
199 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
200 OID in dotted-decimal form (e.g. {{EX:1.1.0}}), qdescrs is one or
201 more names, woid is either the name or OID optionally followed
202 by a length specifier (e.g {{EX:{10}}}).
204 For example, the attribute types {{EX:name}} and {{EX:cn}} are defined
205 in {{F:core.schema}} as:
207 > attributeType ( 2.5.4.41 NAME 'name'
208 > DESC 'name(s) associated with the object'
209 > EQUALITY caseIgnoreMatch
210 > SUBSTR caseIgnoreSubstringsMatch
211 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} )
212 > attributeType ( 2.5.4.3 NAME ( 'cn' $ 'commonName' )
213 > DESC 'common name(s) assciated with the object'
216 Notice that each defines the attribute's OID, provides a short name,
217 and a brief description. Each name is an alias for the OID.
218 {{slapd}}(8) returns the first listed name when returning results.
220 The first attribute, {{EX:name}}, holds values of {{EX:directoryString}}
221 (UTF-8 encoded Unicode) syntax. The syntax is specified by OID
222 (1.3.6.1.4.1.1466.115.121.1.15 identifies the directoryString
223 syntax). A length recommendation of 32768 is specified. Servers
224 should support values of this length, but may support longer values
225 The field does NOT specify a size constraint, so is ignored on
226 servers (such as slapd) which don't impose such size limits. In
227 addition, the equality and substring matching uses case ignore
228 rules. Below are tables listing commonly used syntax and
229 matching rules (OpenLDAP supports these and many more).
231 !block table; align=Center; coltags="EX,EX,N"; \
232 title="Table 6.3: Commonly Used Syntaxes"
234 boolean 1.3.6.1.4.1.1466.115.121.1.7 boolean value
235 distinguishedName 1.3.6.1.4.1.1466.115.121.1.12 DN
236 directoryString 1.3.6.1.4.1.1466.115.121.1.15 UTF-8 string
237 IA5String 1.3.6.1.4.1.1466.115.121.1.26 ASCII string
238 Integer 1.3.6.1.4.1.1466.115.121.1.27 integer
239 Name and Optional UID 1.3.6.1.4.1.1466.115.121.1.34 DN plus UID
240 Numeric String 1.3.6.1.4.1.1466.115.121.1.36 numeric string
241 OID 1.3.6.1.4.1.1466.115.121.1.38 object identifier
242 Octet String 1.3.6.1.4.1.1466.115.121.1.40 arbitary octets
243 Printable String 1.3.6.1.4.1.1466.115.121.1.44 printable string
248 !block table; align=Center; coltags="EX,N"; \
249 title="Table 6.4: Commonly Used Matching Rules"
250 Name Type Description
251 booleanMatch equality boolean
252 octetStringMatch equality octet string
253 objectIdentiferMatch equality OID
254 distinguishedNameMatch equality DN
255 uniqueMemberMatch equality Name with optional UID
256 numericStringMatch equality numerical
257 numericStringOrderingMatch ordering numerical
258 numericStringSubstringsMatch substrings numerical
259 caseIgnoreMatch equality case insensitive, space insensitive
260 caseIgnoreOrderingMatch ordering case insensitive, space insensitive
261 caseIgnoreSubstringsMatch substrings case insensitive, space insensitive
262 caseExactMatch equality case sensitive, space insensitive
263 caseExactOrderingMatch ordering case sensitive, space insensitive
264 caseExactSubstringsMatch substrings case sensitive, space insensitive
265 caseIgnoreIA5Match equality case insensitive, space insensitive
266 caseIgnoreIA5OrderingMatch ordering case insensitive, space insensitive
267 caseIgnoreIA5SubstringsMatch substrings case insensitive, space insensitive
268 caseExactIA5Match equality case sensitive, space insensitive
269 caseExactIA5OrderingMatch ordering case sensitive, space insensitive
270 caseExactIA5SubstringsMatch substrings case sensitive, space insensitive
273 The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence
274 it inherits the syntax, matching rules, and usage of {{EX:name}}.
275 {{EX:commonName}} is an alternative name.
277 Neither attribute is restricted to a single value. Both are meant
278 for usage by user applications. Neither is obsolete nor collective.
280 The following subsections provide a couple of examples.
285 Many organizations maintain a single unique name for each user.
286 Though one could use {{EX:displayName}} ({{REF:RFC2798}}), this
287 attribute is really meant to be controlled by the user, not the
288 organization. We could just copy the definition of {{EX:displayName}}
289 from {{F:inetorgperson.schema}} and replace the OID, name, and
292 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
293 > DESC 'unique name with my organization'
294 > EQUALITY caseIgnoreMatch
295 > SUBSTR caseIgnoreSubstringsMatch
296 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
299 However, if we want this name to be included in
300 {{EX:name}} assertions [e.g. {{EX:(name=*Jane*)}}], the attribute
301 could alternatively be defined as a subtype of {{EX:name}}, e.g.:
303 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
304 > DESC 'unique name with my organization'
310 Many organizations maintain a photo of each each user. A
311 {{EX:myPhoto}} attribute type could be defined to hold a photo.
312 Of course, one could use just use {{EX:jpegPhoto}} ({{REF:RFC2798}})
313 (or a subtype) to hold the photo. However, you can only do
314 this if the photo is in {{JPEG File Interchange Format}}.
315 Alternatively, an attribute type which uses the {{Octet String}}
316 syntax can be defined, e.g.:
318 > attributetype ( 1.1.2.1.2 NAME 'myPhoto'
319 > DESC 'a photo (application defined format)'
320 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
323 In this case, the syntax doesn't specify the format of the photo.
324 It's assumed (maybe incorrectly) that all applications accessing
325 this attribute agree on the handling of values.
327 If you wanted to support multiple photo formats, you could define
328 a separate attribute type for each format, prefix the photo
329 with some typing information, or describe the value using
330 {{TERM:ASN.1}} and use the {{EX:;binary}} transfer option.
332 Another alternative is for the attribute to hold a {{TERM:URI}}
333 pointing to the photo. You can model such an attribute after
334 {{EX:labeledURI}} ({{REF:RFC2079}}) or simply create a subtype,
337 > attributetype ( 1.1.2.1.3 NAME 'myPhotoURI'
338 > DESC 'URI and optional label referring to a photo'
342 H3: Object Class Specification
344 The {{objectclasses}} directive is used to define a new object
345 class. The directive uses the same Object Class Description
346 (as defined in {{REF:RFC2252}}) used by the objectClasses
347 attribute found in the subschema subentry, e.g.:
349 E: objectclass <{{REF:RFC2252}} Object Class Description>
351 where Object Class Description is defined by the following
354 > ObjectClassDescription = "(" whsp
355 > numericoid whsp ; ObjectClass identifier
357 > [ "DESC" qdstring ]
358 > [ "OBSOLETE" whsp ]
359 > [ "SUP" oids ] ; Superior ObjectClasses
360 > [ ( "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" ) whsp ]
361 > ; default structural
362 > [ "MUST" oids ] ; AttributeTypes
363 > [ "MAY" oids ] ; AttributeTypes
366 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
367 OID in numeric form (e.g. {{EX:1.1.0}}), qdescrs is one or more
368 names, and oids is one or more names and/or OIDs.
373 To define an {{auxiliary}} object class which allows
374 myPhoto to be added to any existing entry.
376 > objectclass ( 1.1.2.2.1 NAME 'myPhotoObject'
377 > DESC 'mixin myPhoto'
384 If your organization would like have a private {{structural}}
385 object class to instantiate users, you can subclass one of
386 the existing person classes, such as {{EX:inetOrgPerson}}
387 ({{REF:RFC2798}}), and add any additional attributes which
390 > objectclass ( 1.1.2.2.2 NAME 'myPerson'
393 > MUST ( myUniqueName $ givenName )
396 The object class inherits the required/allowed attribute
397 types of {{EX:inetOrgPerson}} but requires {{EX:myUniqueName}}
398 and {{EX:givenName}} and allows {{EX:myPhoto}}.
401 H2: Transferring Schema
403 Since the {{slapd.conf}}(5) schema directives use {{REF:RFC2252}}
404 format values, you can extract schema elements published by
405 any LDAPv3 server and easily construct directives for use with
408 LDAPv3 servers publish schema elements in special {{subschema}}
409 entries (or subentries). {{slapd}}(8) publishes a single subschema
410 entry normally named {{EX:cn=Subschema}}. In a server which
411 supports a single subschema subentry, the DN of the subschema
412 subenty can usually be found by examining the value of the
413 {{EX:subschemaSubentry}} attribute type in the {{root DSE}}.
414 Other servers may publish multiple subschema entries. These
415 can be located by examining the {{EX:subschemaSubentry}} attribute
416 contained in the entry at the root of each administrative context.
418 To obtain the schema from a subschema subentry, you can use
419 ldapsearch(1) as follows (replace the search base as needed):
421 > ldapsearch -LLL -x -b "cn=Subschema" -s base "(objectclass=subschema)" attributeTypes objectClasses
423 This will return {{TERM:LDIF}} output containing many type/value
424 pairs. The following is an abbreviated example:
427 > attributeTypes: ( 1.1.2.1.1 NAME 'myUniqueName' DESC 'unique name wi
428 > th my organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubst
429 > ringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
430 > attributeTypes: ( 1.1.2.1.2 NAME 'myPhoto' DESC 'a photo (applicatio
431 > n defined format)' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
432 > objectClasses: ( 1.1.2.2.2 NAME 'myPerson' DESC 'my person' SUP inet
433 > OrgPerson MUST ( myUniqueName $ givenName ) MAY myPhoto )
435 Capture the output of the search in a file and then edit the file:
437 + to contain only desired type/value pairs
438 ^ join LDIF continuation lines
439 ^ replace attribute type with directive name
440 (e.g. {{EX:s/attributeTypes:/attributeType/}} and
441 {{EX:s/objectClasses:/objectClass/}}).
442 ^ continue long directives over multiple lines
444 For the three type/value pairs in our example, the edit should
445 result in a file with contains of:
447 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
448 > DESC 'unique name with my organization'
449 > EQUALITY caseIgnoreMatch
450 > SUBSTR caseIgnoreSubstringsMatch
451 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
453 > attributeType ( 1.1.2.1.2 NAME 'myPhoto'
454 > DESC 'a photo (application defined format)'
455 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
456 > objectClass ( 1.1.2.2.2 NAME 'myPerson'
459 > MUST ( myUniqueName $ givenName )
462 Save in an appropriately named file (e.g. {{F:my.schema}}).
463 You may now include this file in your {{slapd.conf}}(5) file.
469 To ease the management and use of OIDs, {{slapd}}(8) supports
470 {{Object Identifier}} macros. The {{EX:objectIdentifier}} is used
471 to equate a macro (name) with a OID. The OID may possibly be derived
472 from a previously defined OID macro. The {{slapd.conf(5)}} syntax
475 E: objectIdentifier <name> { <oid> | <name>[:<suffix>] }
477 The following demonstrates definition of a set of OID macros
478 and their use in defining schema elements:
480 > objectIdentifier myOID 1.1
481 > objectIdentifier mySNMP myOID:1
482 > objectIdentifier myLDAP myOID:2
483 > objectIdentifier myAttributeType myLDAP:1
484 > objectIdentifier myObjectClass myLDAP:2
485 > attributetype ( myAttributeType:3 NAME 'myPhotoURI'
486 > DESC 'URI and optional label referring to a photo'
488 > objectclass ( myObjectClass:1 NAME 'myPhotoObject'
489 > DESC 'mixin myPhoto'