]> git.sur5r.net Git - openldap/blob - doc/guide/admin/schema.sdf
Merge remote-tracking branch 'origin/mdb.master'
[openldap] / doc / guide / admin / schema.sdf
1 # $OpenLDAP$
2 # Copyright 1999-2012 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
5 H1: Schema Specification
6
7 This chapter describes how to extend the user schema used by
8 {{slapd}}(8).  The chapter assumes the reader is familiar with the
9 {{TERM:LDAP}}/{{TERM:X.500}} information model.
10
11 The first section, {{SECT:Distributed Schema Files}} details optional
12 schema definitions provided in the distribution and where to obtain
13 other definitions.
14 The second section, {{SECT:Extending Schema}}, details how to define
15 new schema items.
16 !if 0
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.
20 !endif
21
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
26 indirectly).
27
28
29 H2: Distributed Schema Files
30
31 OpenLDAP Software 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.
36
37 !block table; colaligns="LR"; coltags="F,N"; align=Center; \
38         title="Table 8.1: Provided Schema Specifications"
39 File                    Description
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)
46 !endblock
47
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:
51
52 >       # include schema
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
56
57 Additional files may be available.  Please consult the OpenLDAP
58 {{TERM:FAQ}} ({{URL:http://www.openldap.org/faq/}}).
59
60 Note: You should not modify any of the schema items defined
61 in provided files.
62
63
64 H2: Extending Schema
65
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.
73
74 There are five steps to defining new schema:
75 ^       obtain Object Identifier
76 +       choose a name prefix
77 +       create local schema file
78 +       define custom attribute types (if necessary)
79 +       define custom object classes
80
81
82 H3: Object Identifiers
83
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:
91
92 !block table; colaligns="LR"; coltags="EX,N"; align=Center; \
93         title="Table 8.2: Example OID hierarchy"
94 OID             Assignment
95 1.1             Organization's OID
96 1.1.1           SNMP Elements
97 1.1.2           LDAP Elements
98 1.1.2.1         AttributeTypes
99 1.1.2.1.1       x-my-Attribute
100 1.1.2.2         ObjectClasses
101 1.1.2.2.1       x-my-ObjectClass
102 !endblock
103
104 You are, of course, free to design a hierarchy suitable to your
105 organizational needs under your organization's OID. No matter what hierarchy you choose, you should maintain a registry of assignments you make.  This can be a simple flat file or something more sophisticated such as the {{OpenLDAP OID Registry}} ({{URL:http://www.openldap.org/faq/index.cgi?file=197}}).
106
107 For more information about Object Identifiers (and a listing service)
108 see {{URL:http://www.alvestrand.no/objectid/}}.
109
110 .{{Under no circumstances should you hijack OID namespace!}}
111
112 To obtain a registered OID at {{no cost}}, apply for a OID
113 under the {{ORG[expand]IANA}} (ORG:IANA) maintained {{Private Enterprise}} arc.  
114 Any private enterprise (organization) may request a {{TERM[expand]PEN}} (PEN) to be assigned under this arc. Just fill out the IANA form at {{URL: http://pen.iana.org/pen/PenApplication.page}} and your official PEN will be sent to you usually within a few days. Your base OID will be something like {{EX:1.3.6.1.4.1.X}} where {{EX:X}} is an integer.
115
116 Note: PENs obtained using this form may be used for any purpose
117 including identifying LDAP schema elements.
118
119 Alternatively, OID name space may be available from a national
120 authority (e.g., {{ORG:ANSI}}, {{ORG:BSI}}).
121
122
123 H3: Naming Elements
124
125 In addition to assigning a unique object identifier to each schema
126 element, you should provide at least one textual name for each
127 element.  Names should be registered with the {{ORG:IANA}} or
128 prefixed with "x-" to place in the "private use" name space.
129
130 The name should be both descriptive and not likely to clash with
131 names of other schema elements.  In particular, any name you choose
132 should not clash with present or future Standard Track names (this
133 is assured if you registered names or use names beginning with "x-").
134
135 It is noted that you can obtain your own registered name
136 prefix so as to avoid having to register your names individually.
137 See {{REF:RFC4520}} for details.
138
139 In the examples below, we have used a short prefix '{{EX:x-my-}}'.
140 Such a short prefix would only be suitable for a very large, global
141 organization.  In general, we recommend something like '{{EX:x-de-Firm-}}'
142 (German company) or '{{EX:x-com-Example}}' (elements associated with
143 organization associated with {{EX:example.com}}).
144
145
146 H3: Local schema file
147
148 The {{EX:objectclass}} and {{EX:attributeTypes}} configuration file
149 directives can be used to define schema rules on entries in the
150 directory.  It is customary to create a file to contain definitions
151 of your custom schema items.  We recommend you create a file
152 {{F:local.schema}} in {{F:/usr/local/etc/openldap/schema/local.schema}}
153 and then include this file in your {{slapd.conf}}(5) file immediately
154 after other schema {{EX:include}} directives.
155
156 >       # include schema
157 >       include /usr/local/etc/openldap/schema/core.schema
158 >       include /usr/local/etc/openldap/schema/cosine.schema
159 >       include /usr/local/etc/openldap/schema/inetorgperson.schema
160 >       # include local schema
161 >       include /usr/local/etc/openldap/schema/local.schema
162
163
164 H3: Attribute Type Specification
165
166 The {{attributetype}} directive is used to define a new attribute
167 type.  The directive uses the same Attribute Type Description
168 (as defined in {{REF:RFC4512}}) used by the attributeTypes
169 attribute found in the subschema subentry, e.g.:
170
171 E:      attributetype <{{REF:RFC4512}} Attribute Type Description>
172
173 where Attribute Type Description is defined by the following
174 {{TERM:ABNF}}:
175
176 >      AttributeTypeDescription = "(" whsp
177 >            numericoid whsp              ; AttributeType identifier
178 >          [ "NAME" qdescrs ]             ; name used in AttributeType
179 >          [ "DESC" qdstring ]            ; description
180 >          [ "OBSOLETE" whsp ]
181 >          [ "SUP" woid ]                 ; derived from this other
182 >                                         ; AttributeType
183 >          [ "EQUALITY" woid              ; Matching Rule name
184 >          [ "ORDERING" woid              ; Matching Rule name
185 >          [ "SUBSTR" woid ]              ; Matching Rule name
186 >          [ "SYNTAX" whsp noidlen whsp ] ; Syntax OID
187 >          [ "SINGLE-VALUE" whsp ]        ; default multi-valued
188 >          [ "COLLECTIVE" whsp ]          ; default not collective
189 >          [ "NO-USER-MODIFICATION" whsp ]; default user modifiable
190 >          [ "USAGE" whsp AttributeUsage ]; default userApplications
191 >          whsp ")"
192 >
193 >      AttributeUsage =
194 >          "userApplications"     /
195 >          "directoryOperation"   /
196 >          "distributedOperation" / ; DSA-shared
197 >          "dSAOperation"          ; DSA-specific, value depends on server
198 >
199
200 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
201 OID in dotted-decimal form (e.g. {{EX:1.1.0}}), qdescrs is one or
202 more names, woid is either the name or OID optionally followed
203 by a length specifier (e.g {{EX:{10}}}).
204
205 For example, the attribute types {{EX:name}} and {{EX:cn}} are defined
206 in {{F:core.schema}} as:
207
208 >       attributeType ( 2.5.4.41 NAME 'name'
209 >               DESC 'name(s) associated with the object'
210 >               EQUALITY caseIgnoreMatch
211 >               SUBSTR caseIgnoreSubstringsMatch
212 >               SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} )
213 >       attributeType ( 2.5.4.3 NAME ( 'cn' 'commonName' )
214 >               DESC 'common name(s) assciated with the object'
215 >               SUP name )
216
217 Notice that each defines the attribute's OID, provides a short name,
218 and a brief description.  Each name is an alias for the OID.
219 {{slapd}}(8) returns the first listed name when returning results.
220
221 The first attribute, {{EX:name}}, holds values of {{EX:directoryString}}
222 ({{TERM:UTF-8}} encoded Unicode) syntax.  The syntax is
223 specified by OID (1.3.6.1.4.1.1466.115.121.1.15 identifies the
224 directoryString syntax).  A length recommendation of 32768 is
225 specified.  Servers should support values of this length, but may
226 support longer values. The field does NOT specify a size constraint,
227 so is ignored on servers (such as slapd) which don't impose such
228 size limits.  In addition, the equality and substring matching uses
229 case ignore rules.  Below are tables listing commonly used syntax
230 and matching rules ({{slapd}}(8) supports these and many more).
231
232 !block table; align=Center; coltags="EX,EX,N"; \
233         title="Table 8.3: Commonly Used Syntaxes"
234 Name                    OID                             Description
235 boolean                 1.3.6.1.4.1.1466.115.121.1.7    boolean value
236 directoryString         1.3.6.1.4.1.1466.115.121.1.15   Unicode (UTF-8) string
237 distinguishedName       1.3.6.1.4.1.1466.115.121.1.12   LDAP {{TERM:DN}}
238 integer                 1.3.6.1.4.1.1466.115.121.1.27   integer
239 numericString           1.3.6.1.4.1.1466.115.121.1.36   numeric string
240 OID                     1.3.6.1.4.1.1466.115.121.1.38   object identifier
241 octetString             1.3.6.1.4.1.1466.115.121.1.40   arbitrary octets
242 !endblock
243
244
245
246 !block table; align=Center; coltags="EX,N"; \
247         title="Table 8.4: Commonly Used Matching Rules"
248 Name                                    Type            Description
249 booleanMatch                            equality        boolean
250 caseIgnoreMatch                         equality        case insensitive, space insensitive
251 caseIgnoreOrderingMatch                 ordering        case insensitive, space insensitive
252 caseIgnoreSubstringsMatch               substrings      case insensitive, space insensitive
253 caseExactMatch                          equality        case sensitive, space insensitive
254 caseExactOrderingMatch                  ordering        case sensitive, space insensitive
255 caseExactSubstringsMatch                substrings      case sensitive, space insensitive
256 distinguishedNameMatch                  equality        distinguished name
257 integerMatch                            equality        integer
258 integerOrderingMatch                    ordering        integer
259 numericStringMatch                      equality        numerical
260 numericStringOrderingMatch              ordering        numerical
261 numericStringSubstringsMatch            substrings      numerical
262 octetStringMatch                        equality        octet string
263 octetStringOrderingMatch                ordering        octet string
264 octetStringSubstringsMatch      ordering        octet string
265 objectIdentiferMatch                    equality        object identifier
266 !endblock
267
268 The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence
269 it inherits the syntax, matching rules, and usage of {{EX:name}}.
270 {{EX:commonName}} is an alternative name.
271
272 Neither attribute is restricted to a single value.  Both are meant
273 for usage by user applications.  Neither is obsolete nor collective.
274
275 The following subsections provide a couple of examples.
276
277
278 H4: x-my-UniqueName
279
280 Many organizations maintain a single unique name for each user.
281 Though one could use {{EX:displayName}} ({{REF:RFC2798}}), this
282 attribute is really meant to be controlled by the user, not the
283 organization.  We could just copy the definition of {{EX:displayName}}
284 from {{F:inetorgperson.schema}} and replace the OID, name, and
285 description, e.g:
286
287 >       attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName'
288 >               DESC 'unique name with my organization' 
289 >               EQUALITY caseIgnoreMatch
290 >               SUBSTR caseIgnoreSubstringsMatch
291 >               SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
292 >               SINGLE-VALUE )
293
294 However, if we want this name to be used in {{EX:name}} assertions,
295 e.g. {{EX:(name=*Jane*)}}, the attribute could alternatively be
296 defined as a subtype of {{EX:name}}, e.g.:
297
298 >       attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName'
299 >               DESC 'unique name with my organization' 
300 >               SUP name )
301
302
303 H4: x-my-Photo
304
305 Many organizations maintain a photo of each each user.  A
306 {{EX:x-my-Photo}} attribute type could be defined to hold a photo.
307 Of course, one could use just use {{EX:jpegPhoto}} ({{REF:RFC2798}})
308 (or a subtype) to hold the photo.  However, you can only do
309 this if the photo is in {{JPEG File Interchange Format}}.
310 Alternatively, an attribute type which uses the {{Octet String}}
311 syntax can be defined, e.g.:
312
313 >       attributetype ( 1.1.2.1.2 NAME 'x-my-Photo'
314 >               DESC 'a photo (application defined format)' 
315 >               SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
316 >               SINGLE-VALUE )
317
318 In this case, the syntax doesn't specify the format of the photo.
319 It's assumed (maybe incorrectly) that all applications accessing
320 this attribute agree on the handling of values.
321
322 If you wanted to support multiple photo formats, you could define
323 a separate attribute type for each format, prefix the photo
324 with some typing information, or describe the value using
325 {{TERM:ASN.1}} and use the {{EX:;binary}} transfer option.
326
327 Another alternative is for the attribute to hold a {{TERM:URI}}
328 pointing to the photo.  You can model such an attribute after
329 {{EX:labeledURI}} ({{REF:RFC2079}}) or simply create a subtype,
330 e.g.:
331
332 >       attributetype ( 1.1.2.1.3 NAME 'x-my-PhotoURI'
333 >               DESC 'URI and optional label referring to a photo' 
334 >               SUP labeledURI )
335
336
337 H3: Object Class Specification
338
339 The {{objectclasses}} directive is used to define a new object
340 class.  The directive uses the same Object Class Description
341 (as defined in {{REF:RFC4512}}) used by the objectClasses
342 attribute found in the subschema subentry, e.g.:
343
344 E:      objectclass <{{REF:RFC4512}} Object Class Description>
345
346 where Object Class Description is defined by the following
347 {{TERM:ABNF}}:
348
349 >       ObjectClassDescription = "(" whsp
350 >               numericoid whsp      ; ObjectClass identifier
351 >               [ "NAME" qdescrs ]
352 >               [ "DESC" qdstring ]
353 >               [ "OBSOLETE" whsp ]
354 >               [ "SUP" oids ]       ; Superior ObjectClasses
355 >               [ ( "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" ) whsp ]
356 >                       ; default structural
357 >               [ "MUST" oids ]      ; AttributeTypes
358 >               [ "MAY" oids ]       ; AttributeTypes
359 >               whsp ")"
360
361 where whsp is a space ('{{EX: }}'), numericoid is a globally unique
362 OID in dotted-decimal form (e.g. {{EX:1.1.0}}), qdescrs is one or more
363 names, and oids is one or more names and/or OIDs.
364
365
366 H4: x-my-PhotoObject
367
368 To define an {{auxiliary}} object class which allows
369 x-my-Photo to be added to any existing entry.
370
371 >       objectclass ( 1.1.2.2.1 NAME 'x-my-PhotoObject'
372 >               DESC 'mixin x-my-Photo'
373 >               AUXILIARY
374 >               MAY x-my-Photo )
375
376
377 H4: x-my-Person
378
379 If your organization would like have a private {{structural}}
380 object class to instantiate users, you can subclass one of
381 the existing person classes, such as {{EX:inetOrgPerson}}
382 ({{REF:RFC2798}}), and add any additional attributes which
383 you desire.
384
385 >       objectclass ( 1.1.2.2.2 NAME 'x-my-Person'
386 >               DESC 'my person'
387 >               SUP inetOrgPerson
388 >               MUST ( x-my-UniqueName $ givenName )
389 >               MAY x-my-Photo )
390
391 The object class inherits the required/allowed attribute
392 types of {{EX:inetOrgPerson}} but requires {{EX:x-my-UniqueName}}
393 and {{EX:givenName}} and allows {{EX:x-my-Photo}}.
394
395 !if 0
396 H2: Transferring Schema
397
398 Since the {{slapd.conf}}(5) schema directives use {{REF:RFC4512}}
399 format values, you can extract schema elements published by any
400 {{TERM:LDAPv3}} server and easily construct directives for use with
401 {{slapd}}(8).
402
403 LDAPv3 servers publish schema elements in special {{subschema}}
404 entries (or subentries).  While {{slapd}}(8) publishes a single
405 subschema subentry normally named {{EX:cn=Subschema}}, this behavior
406 cannot be expected from other servers.  The subschema subentry
407 controlling a particular entry can be obtained by examining the
408 {{EX:subschemaSubentry}} attribute contained in the entry at the
409 root of each administrative context.  For example,
410
411 >       ldapsearch -LLL -x -b "dc=example,dc=com" -s base "(objectclass=*)" subschemaSubentry
412
413 To obtain the schema from a subschema subentry, you can use
414 ldapsearch(1) as follows (replace the search base as needed):
415
416 >       ldapsearch -LLL -x -b "cn=Subschema" -s base "(objectclass=subschema)" attributeTypes objectClasses
417
418 where "cn=Subschema" is the value of subschemaSubentry returned in
419 the prior search.
420
421 This will return {{TERM:LDIF}} output containing many type/value
422 pairs.  The following is an abbreviated example:
423
424 >       dn: cn=Subschema
425 >       objectClasses: ( 1.1.2.2.2 NAME 'x-my-Person' DESC 'my person' SUP inet
426 >        OrgPerson MUST ( x-my-UniqueName $ givenName ) MAY x-my-Photo )
427 >       attributeTypes: ( 1.1.2.1.1 NAME 'x-my-UniqueName' DESC 'unique name wi
428 >        th my organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstrin
429 >        gsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE )
430 >       attributeTypes: ( 1.1.2.1.2 NAME 'x-my-Photo' DESC 'a photo (applicatio
431 >        n defined format)' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
432
433 Capture the output of the search in a file and then edit the file:
434
435 + to contain only desired type/value pairs
436 ^ join LDIF continuation lines
437 ^ replace attribute type with directive name
438 (e.g. {{EX:s/attributeTypes:/attributeType /}} and
439 {{EX:s/objectClasses:/objectClass /}}).
440 ^ reorder lines so each element is defined before first use
441 ^ continue long directives over multiple lines
442
443 For the three type/value pairs in our example, the edit should
444 result in a file with contains of:
445
446 >       attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName'
447 >               DESC 'unique name with my organization' 
448 >               EQUALITY caseIgnoreMatch
449 >               SUBSTR caseIgnoreSubstringsMatch
450 >               SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
451 >               SINGLE-VALUE )
452 >       attributeType ( 1.1.2.1.2 NAME 'x-my-Photo'
453 >               DESC 'a photo (application defined format)'
454 >               SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
455 >       objectClass ( 1.1.2.2.2 NAME 'x-my-Person'
456 >               DESC 'my person'
457 >               SUP inetOrgPerson
458 >               MUST ( x-my-UniqueName $ givenName )
459 >               MAY x-my-Photo )
460
461 Save in an appropriately named file (e.g. {{F:local.schema}}).
462 You may now include this file in your {{slapd.conf}}(5) file.
463 !endif
464
465
466 H3: OID Macros
467
468 To ease the management and use of OIDs, {{slapd}}(8) supports
469 {{Object Identifier}} macros.  The {{EX:objectIdentifier}} directive
470 is used to equate a macro (name) with a OID.  The OID may possibly
471 be derived from a previously defined OID macro.   The {{slapd.conf}}(5)
472 syntax is:
473
474 E:      objectIdentifier <name> { <oid> | <name>[:<suffix>] }
475
476 The following demonstrates definition of a set of OID macros
477 and their use in defining schema elements:
478
479 >       objectIdentifier myOID  1.1
480 >       objectIdentifier mySNMP myOID:1
481 >       objectIdentifier myLDAP myOID:2
482 >       objectIdentifier myAttributeType        myLDAP:1
483 >       objectIdentifier myObjectClass  myLDAP:2
484 >       attributetype ( myAttributeType:3 NAME 'x-my-PhotoURI'
485 >               DESC 'URI and optional label referring to a photo' 
486 >               SUP labeledURI )
487 >       objectclass ( myObjectClass:1 NAME 'x-my-PhotoObject'
488 >               DESC 'mixin x-my-Photo'
489 >               AUXILIARY
490 >               MAY x-my-Photo )
491