X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fguide%2Fadmin%2Fschema.sdf;h=7300b7e3471a093d4466927b9f58020f0ac2ab8a;hb=f9e417a2634a6681941772ed488ffaff47f33a4c;hp=0f5a7f7825b5818be9ddb1b8ce7106eeb61e59cd;hpb=f914c0545ce6487316ca9c097447e0e580b4c0df;p=openldap diff --git a/doc/guide/admin/schema.sdf b/doc/guide/admin/schema.sdf index 0f5a7f7825..7300b7e347 100644 --- a/doc/guide/admin/schema.sdf +++ b/doc/guide/admin/schema.sdf @@ -1,10 +1,13 @@ # $OpenLDAP$ -# Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved. +# Copyright 1999-2013 The OpenLDAP Foundation, All Rights Reserved. # COPYING RESTRICTIONS APPLY, see COPYRIGHT. H1: Schema Specification -This chapter describes how to extend the user schema used by {{slapd}}(8). +This chapter describes how to extend the user schema used by +{{slapd}}(8). The chapter assumes the reader is familiar with the +{{TERM:LDAP}}/{{TERM:X.500}} information model. + The first section, {{SECT:Distributed Schema Files}} details optional schema definitions provided in the distribution and where to obtain other definitions. @@ -25,7 +28,7 @@ indirectly). H2: Distributed Schema Files -OpenLDAP is distributed with a set of schema specifications for +OpenLDAP Software is distributed with a set of schema specifications for your use. Each set is defined in a file suitable for inclusion (using the {{EX:include}} directive) in your {{slapd.conf}}(5) file. These schema files are normally installed in the @@ -52,7 +55,7 @@ desired file in the global definitions portion of your > include /usr/local/etc/openldap/schema/inetorgperson.schema Additional files may be available. Please consult the OpenLDAP -FAQ ({{URL:http://www.openldap.org/faq/}}). +{{TERM:FAQ}} ({{URL:http://www.openldap.org/faq/}}). Note: You should not modify any of the schema items defined in provided files. @@ -69,7 +72,7 @@ matching rules and system schema, but this requires some programming and hence is not discussed here. There are five steps to defining new schema: -^ obtain Object Identifer +^ obtain Object Identifier + choose a name prefix + create local schema file + define custom attribute types (if necessary) @@ -78,15 +81,13 @@ There are five steps to defining new schema: H3: Object Identifiers -Each schema element is identified by a globally unique -{{TERM[expand]OID}} (OID). OIDs are also used to identify -other objects. -They are commonly found in protocols described by {{TERM:ASN.1}}. In +Each schema element is identified by a globally unique {{TERM[expand]OID}} +(OID). OIDs are also used to identify other objects. They are +commonly found in protocols described by {{TERM:ASN.1}}. In particular, they are heavily used by the {{TERM[expand]SNMP}} (SNMP). -As OIDs are hierarchical, your organization -can obtain one OID and branch it as needed. For example, -if your organization were assigned OID {{EX:1.1}}, you could branch -the tree as follows: +As OIDs are hierarchical, your organization can obtain one OID and +branch it as needed. For example, if your organization were assigned +OID {{EX:1.1}}, you could branch the tree as follows: !block table; colaligns="LR"; coltags="EX,N"; align=Center; \ title="Table 8.2: Example OID hierarchy" @@ -95,62 +96,51 @@ OID Assignment 1.1.1 SNMP Elements 1.1.2 LDAP Elements 1.1.2.1 AttributeTypes -1.1.2.1.1 myAttribute +1.1.2.1.1 x-my-Attribute 1.1.2.2 ObjectClasses -1.1.2.2.1 myObjectClass +1.1.2.2.1 x-my-ObjectClass !endblock You are, of course, free to design a hierarchy suitable to your -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}}). +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}}). -For more information about Object Identifers (and a listing service) -see {{URL:http://www.alvestrand.no/harald/objectid/}}. +For more information about Object Identifiers (and a listing service) +see {{URL:http://www.alvestrand.no/objectid/}}. .{{Under no circumstances should you hijack OID namespace!}} -To obtain a registered OID at {{no cost}}, apply for an OID under -the {{ORG[expand]IANA}} (IANA) maintained {{Private Enterprise}} -arc. Any private enterprise (organization) may request an OID to -be assigned under this arc. Just fill out the {{ORG:IANA}} form -at {{URL: http://www.iana.org/cgi-bin/enterprise.pl}} and your -official OID 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. - -Note: Don't let the "MIB/SNMP" statement on the IANA page confuse -you. OIDs obtained using this form may be used for any purpose +To obtain a registered OID at {{no cost}}, apply for a OID +under the {{ORG[expand]IANA}} (ORG:IANA) maintained {{Private Enterprise}} arc. +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. + +Note: PENs obtained using this form may be used for any purpose including identifying LDAP schema elements. Alternatively, OID name space may be available from a national -authority (e.g., ANSI, BSI). +authority (e.g., {{ORG:ANSI}}, {{ORG:BSI}}). -For private experiments, OIDs under {{EX:1.1}} may be used. The -OID {{EX:1.1}} arc is regarded as dead name space. - -H3: Name Prefix +H3: Naming Elements In addition to assigning a unique object identifier to each schema -element, you should provide a least one textual name for each -element. The name should be both descriptive and not likely to -clash with names of other schema elements. In particular, any name -you choose should not clash with present or future Standard Track -names. +element, you should provide at least one textual name for each +element. Names should be registered with the {{ORG:IANA}} or +prefixed with "x-" to place in the "private use" name space. + +The name should be both descriptive and not likely to clash with +names of other schema elements. In particular, any name you choose +should not clash with present or future Standard Track names (this +is assured if you registered names or use names beginning with "x-"). -To reduce (but not eliminate) the potential for name clashes, the -convention is to prefix names of non-Standard Track with a few -letters to localize the changes to your organization. The smaller -the organization, the longer your prefix should be. +It is noted that you can obtain your own registered name +prefix so as to avoid having to register your names individually. +See {{REF:RFC4520}} for details. -In the examples below, we have chosen a short prefix '{{EX:my}}' -(to save space). Such a short prefix would only be suitable for a -very large, global organization. In general, we recommend something -like '{{EX:deFirm}}' (German company) or '{{EX:comExample}}' (elements -associated with organization associated with {{EX:example.com}}). +In the examples below, we have used a short prefix '{{EX:x-my-}}'. +Such a short prefix would only be suitable for a very large, global +organization. In general, we recommend something like '{{EX:x-de-Firm-}}' +(German company) or '{{EX:x-com-Example}}' (elements associated with +organization associated with {{EX:example.com}}). H3: Local schema file @@ -175,13 +165,13 @@ H3: Attribute Type Specification The {{attributetype}} directive is used to define a new attribute type. The directive uses the same Attribute Type Description -(as defined in {{REF:RFC2252}}) used by the attributeTypes +(as defined in {{REF:RFC4512}}) used by the attributeTypes attribute found in the subschema subentry, e.g.: -E: attributetype <{{REF:RFC2252}} Attribute Type Description> +E: attributetype <{{REF:RFC4512}} Attribute Type Description> where Attribute Type Description is defined by the following -{{TERM:BNF}}: +{{TERM:ABNF}}: > AttributeTypeDescription = "(" whsp > numericoid whsp ; AttributeType identifier @@ -229,56 +219,50 @@ and a brief description. Each name is an alias for the OID. {{slapd}}(8) returns the first listed name when returning results. The first attribute, {{EX:name}}, holds values of {{EX:directoryString}} -(UTF-8 encoded Unicode) syntax. The syntax is specified by OID -(1.3.6.1.4.1.1466.115.121.1.15 identifies the directoryString -syntax). A length recommendation of 32768 is specified. Servers -should support values of this length, but may support longer values -The field does NOT specify a size constraint, so is ignored on -servers (such as slapd) which don't impose such size limits. In -addition, the equality and substring matching uses case ignore -rules. Below are tables listing commonly used syntax and -matching rules (OpenLDAP supports these and many more). +({{TERM:UTF-8}} encoded Unicode) syntax. The syntax is +specified by OID (1.3.6.1.4.1.1466.115.121.1.15 identifies the +directoryString syntax). A length recommendation of 32768 is +specified. Servers should support values of this length, but may +support longer values. The field does NOT specify a size constraint, +so is ignored on servers (such as slapd) which don't impose such +size limits. In addition, the equality and substring matching uses +case ignore rules. Below are tables listing commonly used syntax +and matching rules ({{slapd}}(8) supports these and many more). !block table; align=Center; coltags="EX,EX,N"; \ title="Table 8.3: Commonly Used Syntaxes" Name OID Description boolean 1.3.6.1.4.1.1466.115.121.1.7 boolean value -distinguishedName 1.3.6.1.4.1.1466.115.121.1.12 DN -directoryString 1.3.6.1.4.1.1466.115.121.1.15 UTF-8 string -IA5String 1.3.6.1.4.1.1466.115.121.1.26 ASCII string -Integer 1.3.6.1.4.1.1466.115.121.1.27 integer -Name and Optional UID 1.3.6.1.4.1.1466.115.121.1.34 DN plus UID -Numeric String 1.3.6.1.4.1.1466.115.121.1.36 numeric string +directoryString 1.3.6.1.4.1.1466.115.121.1.15 Unicode (UTF-8) string +distinguishedName 1.3.6.1.4.1.1466.115.121.1.12 LDAP {{TERM:DN}} +integer 1.3.6.1.4.1.1466.115.121.1.27 integer +numericString 1.3.6.1.4.1.1466.115.121.1.36 numeric string OID 1.3.6.1.4.1.1466.115.121.1.38 object identifier -Octet String 1.3.6.1.4.1.1466.115.121.1.40 arbitary octets -Printable String 1.3.6.1.4.1.1466.115.121.1.44 printable string +octetString 1.3.6.1.4.1.1466.115.121.1.40 arbitrary octets !endblock > !block table; align=Center; coltags="EX,N"; \ title="Table 8.4: Commonly Used Matching Rules" -Name Type Description -booleanMatch equality boolean -octetStringMatch equality octet string -objectIdentiferMatch equality OID -distinguishedNameMatch equality DN -uniqueMemberMatch equality Name with optional UID -numericStringMatch equality numerical -numericStringOrderingMatch ordering numerical -numericStringSubstringsMatch substrings numerical -caseIgnoreMatch equality case insensitive, space insensitive -caseIgnoreOrderingMatch ordering case insensitive, space insensitive -caseIgnoreSubstringsMatch substrings case insensitive, space insensitive -caseExactMatch equality case sensitive, space insensitive -caseExactOrderingMatch ordering case sensitive, space insensitive -caseExactSubstringsMatch substrings case sensitive, space insensitive -caseIgnoreIA5Match equality case insensitive, space insensitive -caseIgnoreIA5OrderingMatch ordering case insensitive, space insensitive -caseIgnoreIA5SubstringsMatch substrings case insensitive, space insensitive -caseExactIA5Match equality case sensitive, space insensitive -caseExactIA5OrderingMatch ordering case sensitive, space insensitive -caseExactIA5SubstringsMatch substrings case sensitive, space insensitive +Name Type Description +booleanMatch equality boolean +caseIgnoreMatch equality case insensitive, space insensitive +caseIgnoreOrderingMatch ordering case insensitive, space insensitive +caseIgnoreSubstringsMatch substrings case insensitive, space insensitive +caseExactMatch equality case sensitive, space insensitive +caseExactOrderingMatch ordering case sensitive, space insensitive +caseExactSubstringsMatch substrings case sensitive, space insensitive +distinguishedNameMatch equality distinguished name +integerMatch equality integer +integerOrderingMatch ordering integer +numericStringMatch equality numerical +numericStringOrderingMatch ordering numerical +numericStringSubstringsMatch substrings numerical +octetStringMatch equality octet string +octetStringOrderingMatch ordering octet string +octetStringSubstringsMatch ordering octet string +objectIdentiferMatch equality object identifier !endblock The second attribute, {{EX:cn}}, is a subtype of {{EX:name}} hence @@ -291,7 +275,7 @@ for usage by user applications. Neither is obsolete nor collective. The following subsections provide a couple of examples. -H4: myUniqueName +H4: x-my-UniqueName Many organizations maintain a single unique name for each user. Though one could use {{EX:displayName}} ({{REF:RFC2798}}), this @@ -300,33 +284,33 @@ organization. We could just copy the definition of {{EX:displayName}} from {{F:inetorgperson.schema}} and replace the OID, name, and description, e.g: -> attributetype ( 1.1.2.1.1 NAME 'myUniqueName' +> attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName' > DESC 'unique name with my organization' > EQUALITY caseIgnoreMatch > SUBSTR caseIgnoreSubstringsMatch > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 > SINGLE-VALUE ) -However, if we want this name to be included in -{{EX:name}} assertions [e.g. {{EX:(name=*Jane*)}}], the attribute -could alternatively be defined as a subtype of {{EX:name}}, e.g.: +However, if we want this name to be used in {{EX:name}} assertions, +e.g. {{EX:(name=*Jane*)}}, the attribute could alternatively be +defined as a subtype of {{EX:name}}, e.g.: -> attributetype ( 1.1.2.1.1 NAME 'myUniqueName' +> attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName' > DESC 'unique name with my organization' > SUP name ) -H4: myPhoto +H4: x-my-Photo Many organizations maintain a photo of each each user. A -{{EX:myPhoto}} attribute type could be defined to hold a photo. +{{EX:x-my-Photo}} attribute type could be defined to hold a photo. Of course, one could use just use {{EX:jpegPhoto}} ({{REF:RFC2798}}) (or a subtype) to hold the photo. However, you can only do this if the photo is in {{JPEG File Interchange Format}}. Alternatively, an attribute type which uses the {{Octet String}} syntax can be defined, e.g.: -> attributetype ( 1.1.2.1.2 NAME 'myPhoto' +> attributetype ( 1.1.2.1.2 NAME 'x-my-Photo' > DESC 'a photo (application defined format)' > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 > SINGLE-VALUE ) @@ -345,7 +329,7 @@ pointing to the photo. You can model such an attribute after {{EX:labeledURI}} ({{REF:RFC2079}}) or simply create a subtype, e.g.: -> attributetype ( 1.1.2.1.3 NAME 'myPhotoURI' +> attributetype ( 1.1.2.1.3 NAME 'x-my-PhotoURI' > DESC 'URI and optional label referring to a photo' > SUP labeledURI ) @@ -354,13 +338,13 @@ H3: Object Class Specification The {{objectclasses}} directive is used to define a new object class. The directive uses the same Object Class Description -(as defined in {{REF:RFC2252}}) used by the objectClasses +(as defined in {{REF:RFC4512}}) used by the objectClasses attribute found in the subschema subentry, e.g.: -E: objectclass <{{REF:RFC2252}} Object Class Description> +E: objectclass <{{REF:RFC4512}} Object Class Description> where Object Class Description is defined by the following -{{TERM:BNF}}: +{{TERM:ABNF}}: > ObjectClassDescription = "(" whsp > numericoid whsp ; ObjectClass identifier @@ -375,22 +359,22 @@ where Object Class Description is defined by the following > whsp ")" where whsp is a space ('{{EX: }}'), numericoid is a globally unique -OID in numeric form (e.g. {{EX:1.1.0}}), qdescrs is one or more +OID in dotted-decimal form (e.g. {{EX:1.1.0}}), qdescrs is one or more names, and oids is one or more names and/or OIDs. -H4: myPhotoObject +H4: x-my-PhotoObject To define an {{auxiliary}} object class which allows -myPhoto to be added to any existing entry. +x-my-Photo to be added to any existing entry. -> objectclass ( 1.1.2.2.1 NAME 'myPhotoObject' -> DESC 'mixin myPhoto' +> objectclass ( 1.1.2.2.1 NAME 'x-my-PhotoObject' +> DESC 'mixin x-my-Photo' > AUXILIARY -> MAY myPhoto ) +> MAY x-my-Photo ) -H4: myPerson +H4: x-my-Person If your organization would like have a private {{structural}} object class to instantiate users, you can subclass one of @@ -398,22 +382,22 @@ the existing person classes, such as {{EX:inetOrgPerson}} ({{REF:RFC2798}}), and add any additional attributes which you desire. -> objectclass ( 1.1.2.2.2 NAME 'myPerson' +> objectclass ( 1.1.2.2.2 NAME 'x-my-Person' > DESC 'my person' > SUP inetOrgPerson -> MUST ( myUniqueName $ givenName ) -> MAY myPhoto ) +> MUST ( x-my-UniqueName $ givenName ) +> MAY x-my-Photo ) The object class inherits the required/allowed attribute -types of {{EX:inetOrgPerson}} but requires {{EX:myUniqueName}} -and {{EX:givenName}} and allows {{EX:myPhoto}}. +types of {{EX:inetOrgPerson}} but requires {{EX:x-my-UniqueName}} +and {{EX:givenName}} and allows {{EX:x-my-Photo}}. !if 0 H2: Transferring Schema -Since the {{slapd.conf}}(5) schema directives use {{REF:RFC2252}} -format values, you can extract schema elements published by -any LDAPv3 server and easily construct directives for use with +Since the {{slapd.conf}}(5) schema directives use {{REF:RFC4512}} +format values, you can extract schema elements published by any +{{TERM:LDAPv3}} server and easily construct directives for use with {{slapd}}(8). LDAPv3 servers publish schema elements in special {{subschema}} @@ -438,12 +422,12 @@ This will return {{TERM:LDIF}} output containing many type/value pairs. The following is an abbreviated example: > dn: cn=Subschema -> objectClasses: ( 1.1.2.2.2 NAME 'myPerson' DESC 'my person' SUP inet -> OrgPerson MUST ( myUniqueName $ givenName ) MAY myPhoto ) -> attributeTypes: ( 1.1.2.1.1 NAME 'myUniqueName' DESC 'unique name wi -> th my organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubst -> ringsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) -> attributeTypes: ( 1.1.2.1.2 NAME 'myPhoto' DESC 'a photo (applicatio +> objectClasses: ( 1.1.2.2.2 NAME 'x-my-Person' DESC 'my person' SUP inet +> OrgPerson MUST ( x-my-UniqueName $ givenName ) MAY x-my-Photo ) +> attributeTypes: ( 1.1.2.1.1 NAME 'x-my-UniqueName' DESC 'unique name wi +> th my organization' EQUALITY caseIgnoreMatch SUBSTR caseIgnoreSubstrin +> gsMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE ) +> attributeTypes: ( 1.1.2.1.2 NAME 'x-my-Photo' DESC 'a photo (applicatio > n defined format)' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 Capture the output of the search in a file and then edit the file: @@ -459,20 +443,20 @@ Capture the output of the search in a file and then edit the file: For the three type/value pairs in our example, the edit should result in a file with contains of: -> attributetype ( 1.1.2.1.1 NAME 'myUniqueName' +> attributetype ( 1.1.2.1.1 NAME 'x-my-UniqueName' > DESC 'unique name with my organization' > EQUALITY caseIgnoreMatch > SUBSTR caseIgnoreSubstringsMatch > SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 > SINGLE-VALUE ) -> attributeType ( 1.1.2.1.2 NAME 'myPhoto' +> attributeType ( 1.1.2.1.2 NAME 'x-my-Photo' > DESC 'a photo (application defined format)' > SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 -> objectClass ( 1.1.2.2.2 NAME 'myPerson' +> objectClass ( 1.1.2.2.2 NAME 'x-my-Person' > DESC 'my person' > SUP inetOrgPerson -> MUST ( myUniqueName $ givenName ) -> MAY myPhoto ) +> MUST ( x-my-UniqueName $ givenName ) +> MAY x-my-Photo ) Save in an appropriately named file (e.g. {{F:local.schema}}). You may now include this file in your {{slapd.conf}}(5) file. @@ -497,11 +481,11 @@ and their use in defining schema elements: > objectIdentifier myLDAP myOID:2 > objectIdentifier myAttributeType myLDAP:1 > objectIdentifier myObjectClass myLDAP:2 -> attributetype ( myAttributeType:3 NAME 'myPhotoURI' +> attributetype ( myAttributeType:3 NAME 'x-my-PhotoURI' > DESC 'URI and optional label referring to a photo' > SUP labeledURI ) -> objectclass ( myObjectClass:1 NAME 'myPhotoObject' -> DESC 'mixin myPhoto' +> objectclass ( myObjectClass:1 NAME 'x-my-PhotoObject' +> DESC 'mixin x-my-Photo' > AUXILIARY -> MAY myPhoto ) +> MAY x-my-Photo )