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 what
98 hierarchy you choose, you should maintain a registry of assignments
99 you make. This can be a simple flat file or something more
100 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 service)
104 see {{URL:http://www.alvestrand.no/harald/objectid/}}.
106 .{{Under no circumstances should you hijack OID namespace!}}
108 To obtain a registered OID at {{no cost}}, apply for an OID under
109 the {{ORG[expand]IANA}} (IANA) maintained {{Private Enterprise}}
110 arc. Any private enterprise (organization) may request an OID to
111 be assigned under this arc. Just fill out the {{ORG:IANA}} form
112 at {{URL: http://www.iana.org/cgi-bin/enterprise.pl}} and your
113 official OID will be sent to you usually within a few days. Your
114 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
118 you. OIDs obtained using this form may be used for any purpose
119 including identifying LDAP schema elements.
121 Alternatively, OID name space may be available from a national
122 authority (e.g., ANSI).
124 For private experiments, OIDs under {{EX:1.1}} may be used. The
125 OID {{EX:1.1}} arc is regarded as dead name space.
130 In addition to assigning a unique object identifier to each schema
131 element, you should provide a least one textual name for each
132 element. The name should be both descriptive and not likely
133 to clash with names of other schema elements. In particular,
134 any name you choose should not clash with present or future
135 Standard Track names.
137 To reduce (but not eliminate) the potential for name clashes,
138 the convention is to prefix names of non-Standard Track with
139 a few letters to localize the changes to your organization.
140 The smaller the organization, the longer your prefix should
143 In the examples below, we have chosen a short prefix '{{EX:my}}'
144 (to save space). Such a short prefix would only be suitable for
145 a very large, global organization. For a small, local organization,
146 we recommend something like '{{EX:deFirm}}' (German company) or
147 '{{EX:comExample}}' (elements associated with organization associated
148 with {{EX:example.com}}).
151 H3: Local schema file
153 The {{EX:objectclass}} and {{EX:attributeTypes}} configuration file
154 directives can be used to define schema rules on entries in the
155 directory. It is customary to create a file to contain definitions
156 of your custom schema items. We recommend you create a file
157 {{F:local.schema}} in {{F:/usr/local/etc/openldap/schema/local.schema}}
158 and then include this file in your {{slapd.conf}}(5) file immediately
159 after other schema {{EX:include}} directives.
162 > include /usr/local/etc/openldap/schema/core.schema
163 > include /usr/local/etc/openldap/schema/cosine.schema
164 > include /usr/local/etc/openldap/schema/inetorgperson.schema
165 > # include local schema
166 > include /usr/local/etc/openldap/schema/local.schema
169 H3: Attribute Type Specification
171 The {{attributetype}} directive is used to define a new attribute
172 type. The directive uses the same Attribute Type Description
173 (as defined in {{REF:RFC2252}}) used by the attributeTypes
174 attribute found in the subschema subentry, e.g.:
176 E: attributetype <{{REF:RFC2252}} Attribute Type Description>
178 where Attribute Type Description is defined by the following
181 > AttributeTypeDescription = "(" whsp
182 > numericoid whsp ; AttributeType identifier
183 > [ "NAME" qdescrs ] ; name used in AttributeType
184 > [ "DESC" qdstring ] ; description
185 > [ "OBSOLETE" whsp ]
186 > [ "SUP" woid ] ; derived from this other
188 > [ "EQUALITY" woid ; Matching Rule name
189 > [ "ORDERING" woid ; Matching Rule name
190 > [ "SUBSTR" woid ] ; Matching Rule name
191 > [ "SYNTAX" whsp noidlen whsp ] ; Syntax OID
192 > [ "SINGLE-VALUE" whsp ] ; default multi-valued
193 > [ "COLLECTIVE" whsp ] ; default not collective
194 > [ "NO-USER-MODIFICATION" whsp ]; default user modifiable
195 > [ "USAGE" whsp AttributeUsage ]; default userApplications
199 > "userApplications" /
200 > "directoryOperation" /
201 > "distributedOperation" / ; DSA-shared
202 > "dSAOperation" ; DSA-specific, value depends on server
205 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
206 OID in dotted-decimal form (e.g. {{EX:1.1.0}}), qdescrs is one or
207 more names, woid is either the name or OID optionally followed
208 by a length specifier (e.g {{EX:{10}}}).
210 For example, the attribute types {{EX:name}} and {{EX:cn}} are defined
211 in {{F:core.schema}} as:
213 > attributeType ( 2.5.4.41 NAME 'name'
214 > DESC 'name(s) associated with the object'
215 > EQUALITY caseIgnoreMatch
216 > SUBSTR caseIgnoreSubstringsMatch
217 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} )
218 > attributeType ( 2.5.4.3 NAME ( 'cn' $ 'commonName' )
219 > DESC 'common name(s) assciated with the object'
222 Notice that each defines the attribute's OID, provides a short name,
223 and a brief description. Each name is an alias for the OID.
224 {{slapd}}(8) returns the first listed name when returning results.
226 The first attribute, {{EX:name}}, holds values of {{EX:directoryString}}
227 (UTF-8 encoded Unicode) syntax. The syntax is specified by OID
228 (1.3.6.1.4.1.1466.115.121.1.15 identifies the directoryString
229 syntax). A length recommendation of 32768 is specified. Servers
230 should support values of this length, but may support longer values
231 The field does NOT specify a size constraint, so is ignored on
232 servers (such as slapd) which don't impose such size limits. In
233 addition, the equality and substring matching uses case ignore
234 rules. Below are tables listing commonly used syntax and
235 matching rules (OpenLDAP supports these and many more).
237 !block table; align=Center; coltags="EX,EX,N"; \
238 title="Table 6.3: Commonly Used Syntaxes"
240 boolean 1.3.6.1.4.1.1466.115.121.1.7 boolean value
241 distinguishedName 1.3.6.1.4.1.1466.115.121.1.12 DN
242 directoryString 1.3.6.1.4.1.1466.115.121.1.15 UTF-8 string
243 IA5String 1.3.6.1.4.1.1466.115.121.1.26 ASCII string
244 Integer 1.3.6.1.4.1.1466.115.121.1.27 integer
245 Name and Optional UID 1.3.6.1.4.1.1466.115.121.1.34 DN plus UID
246 Numeric String 1.3.6.1.4.1.1466.115.121.1.36 numeric string
247 OID 1.3.6.1.4.1.1466.115.121.1.38 object identifier
248 Octet String 1.3.6.1.4.1.1466.115.121.1.40 arbitary octets
249 Printable String 1.3.6.1.4.1.1466.115.121.1.44 printable string
254 !block table; align=Center; coltags="EX,N"; \
255 title="Table 6.4: Commonly Used Matching Rules"
256 Name Type Description
257 booleanMatch equality boolean
258 octetStringMatch equality octet string
259 objectIdentiferMatch equality OID
260 distinguishedNameMatch equality DN
261 uniqueMemberMatch equality Name with optional UID
262 numericStringMatch equality numerical
263 numericStringOrderingMatch ordering numerical
264 numericStringSubstringsMatch substrings numerical
265 caseIgnoreMatch equality case insensitive, space insensitive
266 caseIgnoreOrderingMatch ordering case insensitive, space insensitive
267 caseIgnoreSubstringsMatch substrings case insensitive, space insensitive
268 caseExactMatch equality case sensitive, space insensitive
269 caseExactOrderingMatch ordering case sensitive, space insensitive
270 caseExactSubstringsMatch substrings case sensitive, space insensitive
271 caseIgnoreIA5Match equality case insensitive, space insensitive
272 caseIgnoreIA5OrderingMatch ordering case insensitive, space insensitive
273 caseIgnoreIA5SubstringsMatch substrings case insensitive, space insensitive
274 caseExactIA5Match equality case sensitive, space insensitive
275 caseExactIA5OrderingMatch ordering case sensitive, space insensitive
276 caseExactIA5SubstringsMatch substrings case sensitive, space insensitive
279 The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence
280 it inherits the syntax, matching rules, and usage of {{EX:name}}.
281 {{EX:commonName}} is an alternative name.
283 Neither attribute is restricted to a single value. Both are meant
284 for usage by user applications. Neither is obsolete nor collective.
286 The following subsections provide a couple of examples.
291 Many organizations maintain a single unique name for each user.
292 Though one could use {{EX:displayName}} ({{REF:RFC2798}}), this
293 attribute is really meant to be controlled by the user, not the
294 organization. We could just copy the definition of {{EX:displayName}}
295 from {{F:inetorgperson.schema}} and replace the OID, name, and
298 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
299 > DESC 'unique name with my organization'
300 > EQUALITY caseIgnoreMatch
301 > SUBSTR caseIgnoreSubstringsMatch
302 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
305 However, if we want this name to be included in
306 {{EX:name}} assertions [e.g. {{EX:(name=*Jane*)}}], the attribute
307 could alternatively be defined as a subtype of {{EX:name}}, e.g.:
309 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
310 > DESC 'unique name with my organization'
316 Many organizations maintain a photo of each each user. A
317 {{EX:myPhoto}} attribute type could be defined to hold a photo.
318 Of course, one could use just use {{EX:jpegPhoto}} ({{REF:RFC2798}})
319 (or a subtype) to hold the photo. However, you can only do
320 this if the photo is in {{JPEG File Interchange Format}}.
321 Alternatively, an attribute type which uses the {{Octet String}}
322 syntax can be defined, e.g.:
324 > attributetype ( 1.1.2.1.2 NAME 'myPhoto'
325 > DESC 'a photo (application defined format)'
326 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
329 In this case, the syntax doesn't specify the format of the photo.
330 It's assumed (maybe incorrectly) that all applications accessing
331 this attribute agree on the handling of values.
333 If you wanted to support multiple photo formats, you could define
334 a separate attribute type for each format, prefix the photo
335 with some typing information, or describe the value using
336 {{TERM:ASN.1}} and use the {{EX:;binary}} transfer option.
338 Another alternative is for the attribute to hold a {{TERM:URI}}
339 pointing to the photo. You can model such an attribute after
340 {{EX:labeledURI}} ({{REF:RFC2079}}) or simply create a subtype,
343 > attributetype ( 1.1.2.1.3 NAME 'myPhotoURI'
344 > DESC 'URI and optional label referring to a photo'
348 H3: Object Class Specification
350 The {{objectclasses}} directive is used to define a new object
351 class. The directive uses the same Object Class Description
352 (as defined in {{REF:RFC2252}}) used by the objectClasses
353 attribute found in the subschema subentry, e.g.:
355 E: objectclass <{{REF:RFC2252}} Object Class Description>
357 where Object Class Description is defined by the following
360 > ObjectClassDescription = "(" whsp
361 > numericoid whsp ; ObjectClass identifier
363 > [ "DESC" qdstring ]
364 > [ "OBSOLETE" whsp ]
365 > [ "SUP" oids ] ; Superior ObjectClasses
366 > [ ( "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" ) whsp ]
367 > ; default structural
368 > [ "MUST" oids ] ; AttributeTypes
369 > [ "MAY" oids ] ; AttributeTypes
372 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
373 OID in numeric form (e.g. {{EX:1.1.0}}), qdescrs is one or more
374 names, and oids is one or more names and/or OIDs.
379 To define an {{auxiliary}} object class which allows
380 myPhoto to be added to any existing entry.
382 > objectclass ( 1.1.2.2.1 NAME 'myPhotoObject'
383 > DESC 'mixin myPhoto'
390 If your organization would like have a private {{structural}}
391 object class to instantiate users, you can subclass one of
392 the existing person classes, such as {{EX:inetOrgPerson}}
393 ({{REF:RFC2798}}), and add any additional attributes which
396 > objectclass ( 1.1.2.2.2 NAME 'myPerson'
399 > MUST ( myUniqueName $ givenName )
402 The object class inherits the required/allowed attribute
403 types of {{EX:inetOrgPerson}} but requires {{EX:myUniqueName}}
404 and {{EX:givenName}} and allows {{EX:myPhoto}}.
407 H2: Transferring Schema
409 Since the {{slapd.conf}}(5) schema directives use {{REF:RFC2252}}
410 format values, you can extract schema elements published by
411 any LDAPv3 server and easily construct directives for use with
414 LDAPv3 servers publish schema elements in special {{subschema}}
415 entries (or subentries). {{slapd}}(8) publishes a single subschema
416 entry normally named {{EX:cn=Subschema}}. In a server which
417 supports a single subschema subentry, the DN of the subschema
418 subenty can usually be found by examining the value of the
419 {{EX:subschemaSubentry}} attribute type in the {{root DSE}}.
420 Other servers may publish multiple subschema entries. These
421 can be located by examining the {{EX:subschemaSubentry}} attribute
422 contained in the entry at the root of each administrative context.
424 To obtain the schema from a subschema subentry, you can use
425 ldapsearch(1) as follows (replace the search base as needed):
427 > ldapsearch -LLL -x -b "cn=Subschema" -s base "(objectclass=subschema)" attributeTypes objectClasses
429 This will return {{TERM:LDIF}} output containing many type/value
430 pairs. The following is an abbreviated example:
433 > attributeTypes: ( 1.1.2.1.1 NAME 'myUniqueName' DESC 'unique name wi
434 > th my organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubst
435 > ringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
436 > attributeTypes: ( 1.1.2.1.2 NAME 'myPhoto' DESC 'a photo (applicatio
437 > n defined format)' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
438 > objectClasses: ( 1.1.2.2.2 NAME 'myPerson' DESC 'my person' SUP inet
439 > OrgPerson MUST ( myUniqueName $ givenName ) MAY myPhoto )
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 ^ continue long directives over multiple lines
450 For the three type/value pairs in our example, the edit should
451 result in a file with contains of:
453 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
454 > DESC 'unique name with my organization'
455 > EQUALITY caseIgnoreMatch
456 > SUBSTR caseIgnoreSubstringsMatch
457 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
459 > attributeType ( 1.1.2.1.2 NAME 'myPhoto'
460 > DESC 'a photo (application defined format)'
461 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
462 > objectClass ( 1.1.2.2.2 NAME 'myPerson'
465 > MUST ( myUniqueName $ givenName )
468 Save in an appropriately named file (e.g. {{F:my.schema}}).
469 You may now include this file in your {{slapd.conf}}(5) file.
475 To ease the management and use of OIDs, {{slapd}}(8) supports
476 {{Object Identifier}} macros. The {{EX:objectIdentifier}} is used
477 to equate a macro (name) with a OID. The OID may possibly be derived
478 from a previously defined OID macro. The {{slapd.conf}}(5) syntax
481 E: objectIdentifier <name> { <oid> | <name>[:<suffix>] }
483 The following demonstrates definition of a set of OID macros
484 and their use in defining schema elements:
486 > objectIdentifier myOID 1.1
487 > objectIdentifier mySNMP myOID:1
488 > objectIdentifier myLDAP myOID:2
489 > objectIdentifier myAttributeType myLDAP:1
490 > objectIdentifier myObjectClass myLDAP:2
491 > attributetype ( myAttributeType:3 NAME 'myPhotoURI'
492 > DESC 'URI and optional label referring to a photo'
494 > objectclass ( myObjectClass:1 NAME 'myPhotoObject'
495 > DESC 'mixin myPhoto'