1# OpenLDAP: pkg/openldap-guide/admin/schema.sdf,v 1.41.2.11 2010/04/19 15:58:40 quanah Exp 2# Copyright 1999-2010 The OpenLDAP Foundation, All Rights Reserved. 3# COPYING RESTRICTIONS APPLY, see COPYRIGHT. 4 5H1: Schema Specification 6 7This 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 11The first section, {{SECT:Distributed Schema Files}} details optional 12schema definitions provided in the distribution and where to obtain 13other definitions. 14The second section, {{SECT:Extending Schema}}, details how to define 15new schema items. 16!if 0 17The third section, {{SECT:Transferring Schema}} details how you can 18export schema definitions from an LDAPv3 server and transform it 19to {{slapd.conf}}(5) format. 20!endif 21 22This chapter does not discuss how to extend system schema used by 23{{slapd}}(8) as this requires source code modification. System 24schema includes all operational attribute types or any object class 25which allows or requires an operational attribute (directly or 26indirectly). 27 28 29H2: Distributed Schema Files 30 31OpenLDAP Software is distributed with a set of schema specifications for 32your use. Each set is defined in a file suitable for inclusion 33(using the {{EX:include}} directive) in your {{slapd.conf}}(5) 34file. 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" 39File Description 40core.schema OpenLDAP {{core}} (required) 41cosine.schema Cosine and Internet X.500 (useful) 42inetorgperson.schema InetOrgPerson (useful) 43misc.schema Assorted (experimental) 44nis.schema Network Information Services (FYI) 45openldap.schema OpenLDAP Project (experimental) 46!endblock 47 48To use any of these schema files, you only need to include the 49desired 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 57Additional files may be available. Please consult the OpenLDAP 58{{TERM:FAQ}} ({{URL:http://www.openldap.org/faq/}}). 59 60Note: You should not modify any of the schema items defined 61in provided files. 62 63 64H2: Extending Schema 65 66Schema used by {{slapd}}(8) may be extended to support additional 67syntaxes, matching rules, attribute types, and object classes. This 68chapter details how to add user application attribute types and 69object classes using the syntaxes and matching rules already supported 70by slapd. slapd can also be extended to support additional syntaxes, 71matching rules and system schema, but this requires some programming 72and hence is not discussed here. 73 74There 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 82H3: Object Identifiers 83 84Each schema element is identified by a globally unique {{TERM[expand]OID}} 85(OID). OIDs are also used to identify other objects. They are 86commonly found in protocols described by {{TERM:ASN.1}}. In 87particular, they are heavily used by the {{TERM[expand]SNMP}} (SNMP). 88As OIDs are hierarchical, your organization can obtain one OID and 89branch it as needed. For example, if your organization were assigned 90OID {{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" 94OID Assignment 951.1 Organization's OID 961.1.1 SNMP Elements 971.1.2 LDAP Elements 981.1.2.1 AttributeTypes 991.1.2.1.1 x-my-Attribute 1001.1.2.2 ObjectClasses 1011.1.2.2.1 x-my-ObjectClass 102!endblock 103 104You are, of course, free to design a hierarchy suitable to your 105organizational 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 107For more information about Object Identifiers (and a listing service) 108see {{URL:http://www.alvestrand.no/objectid/}}. 109 110.{{Under no circumstances should you hijack OID namespace!}} 111 112To obtain a registered OID at {{no cost}}, apply for a OID 113under the {{ORG[expand]IANA}} (ORG:IANA) maintained {{Private Enterprise}} arc. 114Any 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 116Note: PENs obtained using this form may be used for any purpose 117including identifying LDAP schema elements. 118 119Alternatively, OID name space may be available from a national 120authority (e.g., {{ORG:ANSI}}, {{ORG:BSI}}). 121 122 123H3: Naming Elements 124 125In addition to assigning a unique object identifier to each schema 126element, you should provide at least one textual name for each 127element. Names should be registered with the {{ORG:IANA}} or 128prefixed with "x-" to place in the "private use" name space. 129 130The name should be both descriptive and not likely to clash with 131names of other schema elements. In particular, any name you choose 132should not clash with present or future Standard Track names (this 133is assured if you registered names or use names beginning with "x-"). 134 135It is noted that you can obtain your own registered name 136prefix so as to avoid having to register your names individually. 137See {{REF:RFC4520}} for details. 138 139In the examples below, we have used a short prefix '{{EX:x-my-}}'. 140Such a short prefix would only be suitable for a very large, global 141organization. In general, we recommend something like '{{EX:x-de-Firm-}}' 142(German company) or '{{EX:x-com-Example}}' (elements associated with 143organization associated with {{EX:example.com}}). 144 145 146H3: Local schema file 147 148The {{EX:objectclass}} and {{EX:attributeTypes}} configuration file 149directives can be used to define schema rules on entries in the 150directory. It is customary to create a file to contain definitions 151of your custom schema items. We recommend you create a file 152{{F:local.schema}} in {{F:/usr/local/etc/openldap/schema/local.schema}} 153and then include this file in your {{slapd.conf}}(5) file immediately 154after 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 164H3: Attribute Type Specification 165 166The {{attributetype}} directive is used to define a new attribute 167type. The directive uses the same Attribute Type Description 168(as defined in {{REF:RFC4512}}) used by the attributeTypes 169attribute found in the subschema subentry, e.g.: 170 171E: attributetype <{{REF:RFC4512}} Attribute Type Description> 172 173where 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 200where whsp is a space ('{{EX: }}'), numericoid is a globally unique 201OID in dotted-decimal form (e.g. {{EX:1.1.0}}), qdescrs is one or 202more names, woid is either the name or OID optionally followed 203by a length specifier (e.g {{EX:{10}}}). 204 205For example, the attribute types {{EX:name}} and {{EX:cn}} are defined 206in {{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 217Notice that each defines the attribute's OID, provides a short name, 218and a brief description. Each name is an alias for the OID. 219{{slapd}}(8) returns the first listed name when returning results. 220 221The first attribute, {{EX:name}}, holds values of {{EX:directoryString}} 222({{TERM:UTF-8}} encoded Unicode) syntax. The syntax is 223specified by OID (1.3.6.1.4.1.1466.115.121.1.15 identifies the 224directoryString syntax). A length recommendation of 32768 is 225specified. Servers should support values of this length, but may 226support longer values. The field does NOT specify a size constraint, 227so is ignored on servers (such as slapd) which don't impose such 228size limits. In addition, the equality and substring matching uses 229case ignore rules. Below are tables listing commonly used syntax 230and 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" 234Name OID Description 235boolean 1.3.6.1.4.1.1466.115.121.1.7 boolean value 236directoryString 1.3.6.1.4.1.1466.115.121.1.15 Unicode (UTF-8) string 237distinguishedName 1.3.6.1.4.1.1466.115.121.1.12 LDAP {{TERM:DN}} 238integer 1.3.6.1.4.1.1466.115.121.1.27 integer 239numericString 1.3.6.1.4.1.1466.115.121.1.36 numeric string 240OID 1.3.6.1.4.1.1466.115.121.1.38 object identifier 241octetString 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" 248Name Type Description 249booleanMatch equality boolean 250caseIgnoreMatch equality case insensitive, space insensitive 251caseIgnoreOrderingMatch ordering case insensitive, space insensitive 252caseIgnoreSubstringsMatch substrings case insensitive, space insensitive 253caseExactMatch equality case sensitive, space insensitive 254caseExactOrderingMatch ordering case sensitive, space insensitive 255caseExactSubstringsMatch substrings case sensitive, space insensitive 256distinguishedNameMatch equality distinguished name 257integerMatch equality integer 258integerOrderingMatch ordering integer 259numericStringMatch equality numerical 260numericStringOrderingMatch ordering numerical 261numericStringSubstringsMatch substrings numerical 262octetStringMatch equality octet string 263octetStringOrderingMatch ordering octet string 264octetStringSubstringsMatch ordering octet string 265objectIdentiferMatch equality object identifier 266!endblock 267 268The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence 269it inherits the syntax, matching rules, and usage of {{EX:name}}. 270{{EX:commonName}} is an alternative name. 271 272Neither attribute is restricted to a single value. Both are meant 273for usage by user applications. Neither is obsolete nor collective. 274 275The following subsections provide a couple of examples. 276 277 278H4: x-my-UniqueName 279 280Many organizations maintain a single unique name for each user. 281Though one could use {{EX:displayName}} ({{REF:RFC2798}}), this 282attribute is really meant to be controlled by the user, not the 283organization. We could just copy the definition of {{EX:displayName}} 284from {{F:inetorgperson.schema}} and replace the OID, name, and 285description, 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 294However, if we want this name to be used in {{EX:name}} assertions, 295e.g. {{EX:(name=*Jane*)}}, the attribute could alternatively be 296defined 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 303H4: x-my-Photo 304 305Many organizations maintain a photo of each each user. A 306{{EX:x-my-Photo}} attribute type could be defined to hold a photo. 307Of course, one could use just use {{EX:jpegPhoto}} ({{REF:RFC2798}}) 308(or a subtype) to hold the photo. However, you can only do 309this if the photo is in {{JPEG File Interchange Format}}. 310Alternatively, an attribute type which uses the {{Octet String}} 311syntax 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 318In this case, the syntax doesn't specify the format of the photo. 319It's assumed (maybe incorrectly) that all applications accessing 320this attribute agree on the handling of values. 321 322If you wanted to support multiple photo formats, you could define 323a separate attribute type for each format, prefix the photo 324with some typing information, or describe the value using 325{{TERM:ASN.1}} and use the {{EX:;binary}} transfer option. 326 327Another alternative is for the attribute to hold a {{TERM:URI}} 328pointing to the photo. You can model such an attribute after 329{{EX:labeledURI}} ({{REF:RFC2079}}) or simply create a subtype, 330e.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 337H3: Object Class Specification 338 339The {{objectclasses}} directive is used to define a new object 340class. The directive uses the same Object Class Description 341(as defined in {{REF:RFC4512}}) used by the objectClasses 342attribute found in the subschema subentry, e.g.: 343 344E: objectclass <{{REF:RFC4512}} Object Class Description> 345 346where 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 361where whsp is a space ('{{EX: }}'), numericoid is a globally unique 362OID in dotted-decimal form (e.g. {{EX:1.1.0}}), qdescrs is one or more 363names, and oids is one or more names and/or OIDs. 364 365 366H4: x-my-PhotoObject 367 368To define an {{auxiliary}} object class which allows 369x-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 377H4: x-my-Person 378 379If your organization would like have a private {{structural}} 380object class to instantiate users, you can subclass one of 381the existing person classes, such as {{EX:inetOrgPerson}} 382({{REF:RFC2798}}), and add any additional attributes which 383you 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 391The object class inherits the required/allowed attribute 392types of {{EX:inetOrgPerson}} but requires {{EX:x-my-UniqueName}} 393and {{EX:givenName}} and allows {{EX:x-my-Photo}}. 394 395!if 0 396H2: Transferring Schema 397 398Since the {{slapd.conf}}(5) schema directives use {{REF:RFC4512}} 399format values, you can extract schema elements published by any 400{{TERM:LDAPv3}} server and easily construct directives for use with 401{{slapd}}(8). 402 403LDAPv3 servers publish schema elements in special {{subschema}} 404entries (or subentries). While {{slapd}}(8) publishes a single 405subschema subentry normally named {{EX:cn=Subschema}}, this behavior 406cannot be expected from other servers. The subschema subentry 407controlling a particular entry can be obtained by examining the 408{{EX:subschemaSubentry}} attribute contained in the entry at the 409root of each administrative context. For example, 410 411> ldapsearch -LLL -x -b "dc=example,dc=com" -s base "(objectclass=*)" subschemaSubentry 412 413To obtain the schema from a subschema subentry, you can use 414ldapsearch(1) as follows (replace the search base as needed): 415 416> ldapsearch -LLL -x -b "cn=Subschema" -s base "(objectclass=subschema)" attributeTypes objectClasses 417 418where "cn=Subschema" is the value of subschemaSubentry returned in 419the prior search. 420 421This will return {{TERM:LDIF}} output containing many type/value 422pairs. 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 433Capture 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 443For the three type/value pairs in our example, the edit should 444result 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 461Save in an appropriately named file (e.g. {{F:local.schema}}). 462You may now include this file in your {{slapd.conf}}(5) file. 463!endif 464 465 466H3: OID Macros 467 468To ease the management and use of OIDs, {{slapd}}(8) supports 469{{Object Identifier}} macros. The {{EX:objectIdentifier}} directive 470is used to equate a macro (name) with a OID. The OID may possibly 471be derived from a previously defined OID macro. The {{slapd.conf}}(5) 472syntax is: 473 474E: objectIdentifier <name> { <oid> | <name>[:<suffix>] } 475 476The following demonstrates definition of a set of OID macros 477and 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 492