git.sur5r.net Git - openldap/blob - doc/guide/admin/schema.sdf

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