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 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 nadf.schema North American Directory Forum (FYI)
35 nis.schema Network Information Services (FYI)
36 openldap.schema OpenLDAP Project (experimental)
39 To use any of these schema files, you only need to include the
40 desired file in the global definitions portion of your
41 {{slapd.conf}}(5) file. For example:
44 > include /usr/local/etc/openldap/schema/core.schema
45 > include /usr/local/etc/openldap/schema/cosine.schema
46 > include /usr/local/etc/openldap/schema/inetorgperson.schema
48 Additional files may be available. Please consult the OpenLDAP
49 FAQ ({{URL:http://www.openldap.org/faq/}}).
51 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.
58 This chapter details how to add attribute types and object classes
59 using the syntaxes and matching rules already supported by slapd.
60 slapd can also be extended to support additional syntaxes
61 and matching rules, but this requires some programming and hence
62 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
71 H3: Object Identifiers
73 Each schema element is identified by a globally unique
74 {{TERM[expand]OID}} (OID). OIDs are also used to identify
76 They are commonly found in protocols described by {{TERM:ASN.1}}. In
77 particular, they are heavily used by the {{TERM[expand]SNMP}} (SNMP).
78 As OIDs are hierarchical, your organization
79 can obtain one OID and branch it as needed. For example,
80 if your organization were assigned OID {{EX:1.1}}, you could branch
83 !block table; colaligns="LR"; coltags="EX,N"; align=Center; \
84 title="Table 6.2: Example OID hierarchy"
86 1.1 Organization's OID
89 1.1.2.1 AttributeTypes
92 1.1.2.2.1 myObjectClass
95 You are, of course, free to design a hierarchy suitable to your
96 organizational needs under your organization's OID. No matter
97 what hierarchy you choose, you should maintain a registry of
98 assignments you make. This can be a simple flat file or a
99 something more sophisticated such as the {{OpenLDAP OID Registry}}
100 ({{URL:http://www.openldap.org/faq/index.cgi?file=197}}).
102 For more information about Object Identifers (and a listing
103 service) see {{URL:http://www.alvestrand.no/harald/objectid/}}.
105 .{{Under no circumstances should you use a fictious OID!}}
107 To obtain a fully registered OID at {{no cost}}, apply for
108 an OID under {{ORG[expand]IANA}} (IANA) maintained
109 {{Private Enterprise}} arch. Any private enterprise (organization)
110 may request an OID to be assigned under this arch. Just fill
111 out the {{ORG:IANA}} form at {{URL: http://www.iana.org/cgi-bin/enterprise.pl}}
112 and your official OID will be sent to you usually within a few days.
113 Your base OID will be something like {{EX:1.3.6.1.4.1.X}} were {{EX:X}}
116 Note: Don't let the "MIB/SNMP" statement on the IANA page confuse you.
117 OIDs obtained using this form may be used for any purpose including
118 identifying LDAP schema elements.
123 In addition to assigning a unique object identifier to each schema
124 element, you should provide a least one textual name for each
125 element. The name should be both descriptive and not likely
126 to clash with names of other schema elements. In particular,
127 any name you choose should not clash with present or future
128 Standard Track names.
130 To reduce (but not eliminate) the potential for name clashes,
131 the convention is to prefix names of non-Standard Track with
132 a few letters to localize the changes to your organization.
133 The smaller the organization, the longer your prefix should
136 In the examples below, we have choosen a short prefix '{{EX:my}}'
137 (to save space). Such a short prefix would only be suitable for
138 a very large, global organization. For a small, local organization,
139 we recommend something like '{{EX:deFirm}}' (German company) or
140 '{{EX:comExample}}' (elements associated with organization associated
141 with {{EX:example.com}}).
144 H3: Local schema file
146 The {{EX:objectclass}} and {{EX:attributeTypes}} configuration file
147 directives can be used to define schema rules on entries in the
148 directory. It is customary to create a file to contain definitions
149 of your custom schema items. We recommend you create a file
150 {{F:local.schema}} in {{F:/usr/local/etc/openldap/schema/local.schema}}
151 and then include this file in your {{slapd.conf}}(5) file immediately
152 after other schema {{EX:include}} directives.
155 > include /usr/local/etc/openldap/schema/core.schema
156 > include /usr/local/etc/openldap/schema/cosine.schema
157 > include /usr/local/etc/openldap/schema/inetorgperson.schema
158 > # include local schema
159 > include /usr/local/etc/openldap/schema/local.schema
162 H3: Attribute Type Specification
164 The {{attributetype}} directive is used to define a new attribute
165 type. The directive uses the same Attribute Type Description
166 (as defined in {{REF:RFC2252}}) used by the attributeTypes
167 attribute found in the subschema subentry, e.g.:
169 E: attributetype <{{REF:RFC2252}} Attribute Type Description>
171 where Attribute Type Description is defined by the following
174 > AttributeTypeDescription = "(" whsp
175 > numericoid whsp ; AttributeType identifier
176 > [ "NAME" qdescrs ] ; name used in AttributeType
177 > [ "DESC" qdstring ] ; description
178 > [ "OBSOLETE" whsp ]
179 > [ "SUP" woid ] ; derived from this other
181 > [ "EQUALITY" woid ; Matching Rule name
182 > [ "ORDERING" woid ; Matching Rule name
183 > [ "SUBSTR" woid ] ; Matching Rule name
184 > [ "SYNTAX" whsp noidlen whsp ] ; Syntax OID
185 > [ "SINGLE-VALUE" whsp ] ; default multi-valued
186 > [ "COLLECTIVE" whsp ] ; default not collective
187 > [ "NO-USER-MODIFICATION" whsp ]; default user modifiable
188 > [ "USAGE" whsp AttributeUsage ]; default userApplications
192 > "userApplications" /
193 > "directoryOperation" /
194 > "distributedOperation" / ; DSA-shared
195 > "dSAOperation" ; DSA-specific, value depends on server
198 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
199 OID in dotted-decimal form (e.g. {{EX:1.2.3}}), qdescrs is one or
200 more names, woid is either the name or OID optionally followed
201 length specifier (e.g {{EX:{10}}}).
203 For example, the attribute types {{EX:name}} and {{EX:cn}} are defined
204 in {{F:core.schema}} as:
206 > attributeType ( 2.5.4.41 NAME 'name'
207 > DESC 'name(s) associated with the object'
208 > EQUALITY caseIgnoreMatch
209 > SUBSTR caseIgnoreSubstringsMatch
210 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} )
211 > attributeType ( 2.5.4.3 NAME ( 'cn' $ 'commonName' )
212 > DESC 'common name(s) assciated with the object'
215 Notice that each defines the attribute's OID, provides a short name,
216 and a brief description. Each name is an alias for the OID.
217 {{slapd}}(8) returns the first listed name when returning results.
219 The first attribute, {{EX:name}}, holds values of {{EX:directoryString}}
220 (UTF-8 encoded Unicode) syntax. The syntax are specified by OID
221 (1.3.6.1.4.1.1466.115.121.1.15 identifies the directoryString
222 syntax). An length recommendation of 32768 is specified. Servers
223 should support values of this length, but may support longer values
224 The field does NOT specify a size constraint, so is ignored on
225 servers (such as slapd) which don't impose such size limits. In
226 addition, the equality and substring matching uses case ignore
227 rules. Below are tables listing commonly used syntax and
228 matching rules (OpenLDAP supports these and many more).
230 !block table; align=Center; coltags="EX,EX,N"; \
231 title="Table 6.3: Commonly Used Syntaxes"
233 binary 1.3.6.1.4.1.1466.115.121.1.5 BER/DER data
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 objectIdentiferMatch equality OID
253 distinguishedNameMatch equality DN
254 uniqueMemberMatch equality DN with optional UID
255 numericStringMatch equality numerical
256 numericStringOrderingMatch ordering numerical
257 numericStringSubstringsMatch substrings numerical
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 caseIgnoreIA5Match equality case insensitive, space insensitive
265 caseIgnoreIA5OrderingMatch ordering case insensitive, space insensitive
266 caseIgnoreIA5SubstringsMatch substrings case insensitive, space insensitive
267 caseExactIA5Match equality case sensitive, space insensitive
268 caseExactIA5OrderingMatch ordering case sensitive, space insensitive
269 caseExactIA5SubstringsMatch substrings case sensitive, space insensitive
272 The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence
273 it inherits the syntax, matching rules, and usage of {{EX:name}}.
274 {{EX:commonName}} is an alternative name.
276 Neither attribute is restricted to a single value. Both are meant
277 for usage by user applications. Neither is obsolete nor collective.
279 The following subsections provide a couple of examples.
284 Many organizations maintain a single unique name for each user.
285 Though one could use {{EX:displayName}} ({{REF:RFC2798}}), this
286 attribute is really meant to be controlled by the user, not the
287 organization. We could just copy the definition of {{EX:displayName}}
288 from {{F:inetorgperson.schema}} and replace the OID, name, and
291 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
292 > DESC 'unique name with my organization'
293 > EQUALITY caseIgnoreMatch
294 > SUBSTR caseIgnoreSubstringsMatch
295 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
298 However, if we want this name to be included in
299 {{EX:name}} assertions [e.g. {{EX:(name=*Jane*)}}], the attribute
300 could alternatively be defined as a subtype of {{EX:name}}, e.g.:
302 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
303 > DESC 'unique name with my organization'
309 Many organizations maintain a photo of each each user. A
310 {{EX:myPhoto}} attribute type could be defined to hold a photo.
311 Of course, one could use just use {{EX:jpegPhoto}} ({{REF:RFC2798}})
312 (or a subtype) to hold the photo. However, you can only do
313 this if the photo is in {{JPEG File Interchange Format}}.
314 Alternatively, an attribute type which uses the {{Octet String}}
315 syntax can be defined, e.g.:
317 > attributetype ( 1.1.2.1.2 NAME 'myPhoto'
318 > DESC 'a photo (application defined format)'
319 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
322 As noted in the description, LDAP has no knowledge of the
323 format of the photo. It's assumed that all applications
324 accessing this attribute agree on the handling of values.
326 If you wanted to support multiple photo formats, you could define
327 a separate attribute type for each format, prefix the photo
328 with some typing information, or describe the value using
329 {{TERM:ASN.1}} and use the {{EX:;binary}} transfer option.
331 Another alternative is for the attribute to hold a {{TERM:URI}}
332 pointing to the photo. You can model such an attribute after
333 {{EX:labeledURI}} ({{REF:RFC2079}}).
336 H3: Object Class Specification
338 The {{objectclasses}} directive is used to define a new object
339 class. The directive uses the same Object Class Description
340 (as defined in {{REF:RFC2252}}) used by the objectClasses
341 attribute found in the subschema subentry, e.g.:
343 E: objectclass <{{REF:RFC2252}} Object Class Description>
345 where Object Class Description is defined by the following
348 > ObjectClassDescription = "(" whsp
349 > numericoid whsp ; ObjectClass identifier
351 > [ "DESC" qdstring ]
352 > [ "OBSOLETE" whsp ]
353 > [ "SUP" oids ] ; Superior ObjectClasses
354 > [ ( "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" ) whsp ]
355 > ; default structural
356 > [ "MUST" oids ] ; AttributeTypes
357 > [ "MAY" oids ] ; AttributeTypes
360 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
361 OID in numeric form (e.g. {{EX:1.2.3}}), qdescrs is one or more
362 names, and oids is one or more names and/or OIDs.
367 To define an {{auxiliary}} object class which allows
368 myPhoto to be added to any existing entry.
370 > objectclass ( 1.1.2.2.1 NAME 'myPhotoObject'
371 > DESC 'mixin myPhoto'
378 If your organization would like have a private {{structural}}
379 object class to instantiate users, you can subclass one of
380 the existing person classes, such as {{EX:inetOrgPerson}}
381 ({{REF:RFC2798}}), and add any additional attributes which
384 > objectclass ( 1.1.2.2.2 NAME 'myPerson'
387 > MUST ( 'myUniqueName' $ 'givenName' )
390 The object class inherits the required/allowed attribute
391 types of {{EX:inetOrgPerson}} but requires {{EX:myUniqueName}}
392 and {{EX:givenName}} and allows {{EX:myPhoto}}.
395 H2: Transferring Schema
397 Since the {{slapd.conf}}(5) schema directives use {{REF:RFC2252}}
398 format values, you can extract schema elements published by
399 any LDAPv3 server and easily construct directives for use with
402 LDAPv3 servers publish schema elements in special {{subschema}}
403 entries (or subentries). {{slapd}}(8) publishes a single subschema
404 entry normally named {{EX:cn=Subschema}}. In a server which
405 supports a single subschema subentry, the DN of the subschema
406 subenty can usually be found by examining the value of the
407 {{EX:subschemaSubentry}} attribute type in the {{root DSE}}.
408 Other servers may publish multiple subschema entries. These
409 can be located by examining the {{EX:subschemaSubentry}} attribute
410 contained in the entry at the root of each administrative context.
412 To obtain the schema from a subschema subentry, you can use
413 ldapsearch(1) as follows (replace the search base as needed):
415 > ldapsearch -LLL -x -b "cn=Subschema" -s base "(objectclass=subschema)" attributeTypes objectClasses
417 This will return {{TERM:LDIF}} output containing many type/value
418 pairs. The following is an abbreviated example:
421 > attributeTypes: ( 1.1.2.1.1 NAME 'myUniqueName' DESC 'unique name wi
422 > th my organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubst
423 > ringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
424 > attributeTypes: ( 1.1.2.1.2 NAME 'myPhoto' DESC 'a photo (applicatio
425 > n defined format)' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
426 > objectClasses: ( 1.1.2.2.2 NAME 'myPerson' DESC 'my person' SUP inet
427 > OrgPerson MUST ( 'myUniqueName' $ 'givenName' ) MAY 'myPhoto' )
429 Capture the output of the search in a file and then edit the file:
431 + to contain only desired type/value pairs
432 ^ join LDIF continuation lines
433 ^ replace attribute type with directive name
434 (e.g. {{EX:s/attributeTypes:/attributeType/}} and
435 {{EX:s/objectClasses:/objectClass/}}).
436 ^ continue long directives over multiple lines
438 For the three type/value pairs in our example, the edit should
439 result in a file with contains of:
441 > attributetype ( 1.1.2.1.1 NAME 'myUniqueName'
442 > DESC 'unique name with my organization'
443 > EQUALITY caseIgnoreMatch
444 > SUBSTR caseIgnoreSubstringsMatch
445 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
447 > attributeType ( 1.1.2.1.2 NAME 'myPhoto'
448 > DESC 'a photo (application defined format)'
449 > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
450 > objectClass ( 1.1.2.2.2 NAME 'myPerson'
453 > MUST ( 'myUniqueName' $ 'givenName' )
456 Save in an appropriately named file (e.g. {{F:my.schema}}).
457 You may now include this file in your {{slapd.conf}}(8) file.