1
# $OpenLDAP: pkg/openldap-guide/admin/schema.sdf,v 1.41.2.6 2008/02/11 23:26:39 kurt Exp $
2
# Copyright 1999-2008 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
8
{{slapd}}(8). The chapter assumes the reader is familiar with the
9
{{TERM:LDAP}}/{{TERM:X.500}} information model.
11
The first section, {{SECT:Distributed Schema Files}} details optional
12
schema definitions provided in the distribution and where to obtain
14
The second section, {{SECT:Extending Schema}}, details how to define
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.
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
29
H2: Distributed Schema Files
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.
37
!block table; colaligns="LR"; coltags="F,N"; align=Center; \
38
title="Table 8.1: Provided Schema Specifications"
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)
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:
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
57
Additional files may be available. Please consult the OpenLDAP
58
{{TERM:FAQ}} ({{URL:http://www.openldap.org/faq/}}).
60
Note: You should not modify any of the schema items defined
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.
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
82
H3: Object Identifiers
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:
92
!block table; colaligns="LR"; coltags="EX,N"; align=Center; \
93
title="Table 8.2: Example OID hierarchy"
95
1.1 Organization's OID
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
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}}).
107
For more information about Object Identifiers (and a listing service)
108
see {{URL:http://www.alvestrand.no/harald/objectid/}}.
110
.{{Under no circumstances should you hijack OID namespace!}}
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.
116
Note: PENs obtained using this form may be used for any purpose
117
including identifying LDAP schema elements.
119
Alternatively, OID name space may be available from a national
120
authority (e.g., {{ORG:ANSI}}, {{ORG:BSI}}).
125
In addition to assigning a unique object identifier to each schema
126
element, you should provide a 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.
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-").
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.
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}}).
146
H3: Local schema file
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.
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
164
H3: Attribute Type Specification
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.:
171
E: attributetype <{{REF:RFC4512}} Attribute Type Description>
173
where Attribute Type Description is defined by the following
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
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
194
> "userApplications" /
195
> "directoryOperation" /
196
> "distributedOperation" / ; DSA-shared
197
> "dSAOperation" ; DSA-specific, value depends on server
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}}}).
205
For example, the attribute types {{EX:name}} and {{EX:cn}} are defined
206
in {{F:core.schema}} as:
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'
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.
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).
232
!block table; align=Center; coltags="EX,EX,N"; \
233
title="Table 8.3: Commonly Used Syntaxes"
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
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
octetStringOrderingStringMatch ordering octet string
264
octetStringSubstringsStringMatch ordering octet string
265
objectIdentiferMatch equality object identifier
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.
272
Neither attribute is restricted to a single value. Both are meant
273
for usage by user applications. Neither is obsolete nor collective.
275
The following subsections provide a couple of examples.
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
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
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.:
298
> attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName'
299
> DESC 'unique name with my organization'
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.:
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
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.
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.
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,
332
> attributetype ( 1.1.2.1.3 NAME 'x-my-PhotoURI'
333
> DESC 'URI and optional label referring to a photo'
337
H3: Object Class Specification
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.:
344
E: objectclass <{{REF:RFC4512}} Object Class Description>
346
where Object Class Description is defined by the following
349
> ObjectClassDescription = "(" whsp
350
> numericoid whsp ; ObjectClass identifier
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
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.
368
To define an {{auxiliary}} object class which allows
369
x-my-Photo to be added to any existing entry.
371
> objectclass ( 1.1.2.2.1 NAME 'x-my-PhotoObject'
372
> DESC 'mixin x-my-Photo'
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
385
> objectclass ( 1.1.2.2.2 NAME 'x-my-Person'
388
> MUST ( x-my-UniqueName $ givenName )
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}}.
396
H2: Transferring Schema
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
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,
411
> ldapsearch -LLL -x -b "dc=example,dc=com" -s base "(objectclass=*)" subschemaSubentry
413
To obtain the schema from a subschema subentry, you can use
414
ldapsearch(1) as follows (replace the search base as needed):
416
> ldapsearch -LLL -x -b "cn=Subschema" -s base "(objectclass=subschema)" attributeTypes objectClasses
418
where "cn=Subschema" is the value of subschemaSubentry returned in
421
This will return {{TERM:LDIF}} output containing many type/value
422
pairs. The following is an abbreviated example:
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
433
Capture the output of the search in a file and then edit the file:
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
443
For the three type/value pairs in our example, the edit should
444
result in a file with contains of:
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
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'
458
> MUST ( x-my-UniqueName $ givenName )
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.
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)
474
E: objectIdentifier <name> { <oid> | <name>[:<suffix>] }
476
The following demonstrates definition of a set of OID macros
477
and their use in defining schema elements:
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'
487
> objectclass ( myObjectClass:1 NAME 'x-my-PhotoObject'
488
> DESC 'mixin x-my-Photo'
added
removed
doc/guide/admin/schema.sdf
