diff options
Diffstat (limited to 'doc/guide/admin/schema.sdf')
| -rw-r--r-- | doc/guide/admin/schema.sdf | 491 |
1 files changed, 491 insertions, 0 deletions
diff --git a/doc/guide/admin/schema.sdf b/doc/guide/admin/schema.sdf new file mode 100644 index 0000000..d80d9cd --- /dev/null +++ b/doc/guide/admin/schema.sdf @@ -0,0 +1,491 @@ +# $OpenLDAP$ +# Copyright 1999-2022 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). 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. +The second section, {{SECT:Extending Schema}}, details how to define +new schema items. +!if 0 +The third section, {{SECT:Transferring Schema}} details how you can +export schema definitions from an LDAPv3 server and transform it +to {{slapd.conf}}(5) format. +!endif + +This chapter does not discuss how to extend system schema used by +{{slapd}}(8) as this requires source code modification. System +schema includes all operational attribute types or any object class +which allows or requires an operational attribute (directly or +indirectly). + + +H2: Distributed Schema Files + +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 +{{F:/usr/local/etc/openldap/schema}} directory. + +!block table; colaligns="LR"; coltags="F,N"; align=Center; \ + title="Table 8.1: Provided Schema Specifications" +File Description +core.schema OpenLDAP {{core}} (required) +cosine.schema Cosine and Internet X.500 (useful) +inetorgperson.schema InetOrgPerson (useful) +misc.schema Assorted (experimental) +nis.schema Network Information Services (FYI) +openldap.schema OpenLDAP Project (experimental) +!endblock + +To use any of these schema files, you only need to include the +desired file in the global definitions portion of your +{{slapd.conf}}(5) file. For example: + +> # include schema +> include /usr/local/etc/openldap/schema/core.schema +> include /usr/local/etc/openldap/schema/cosine.schema +> include /usr/local/etc/openldap/schema/inetorgperson.schema + +Additional files may be available. Please consult the OpenLDAP +{{TERM:FAQ}} ({{URL:http://www.openldap.org/faq/}}). + +Note: You should not modify any of the schema items defined +in provided files. + + +H2: Extending Schema + +Schema used by {{slapd}}(8) may be extended to support additional +syntaxes, matching rules, attribute types, and object classes. This +chapter details how to add user application attribute types and +object classes using the syntaxes and matching rules already supported +by slapd. slapd can also be extended to support additional syntaxes, +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 Identifier ++ choose a name prefix ++ create local schema file ++ define custom attribute types (if necessary) ++ define custom object classes + + +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 +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: + +!block table; colaligns="LR"; coltags="EX,N"; align=Center; \ + title="Table 8.2: Example OID hierarchy" +OID Assignment +1.1 Organization's OID +1.1.1 SNMP Elements +1.1.2 LDAP Elements +1.1.2.1 AttributeTypes +1.1.2.1.1 x-my-Attribute +1.1.2.2 ObjectClasses +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}}). + +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 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., {{ORG:ANSI}}, {{ORG:BSI}}). + + +H3: Naming Elements + +In addition to assigning a unique object identifier to each schema +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-"). + +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 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 + +The {{EX:objectclass}} and {{EX:attributeTypes}} configuration file +directives can be used to define schema rules on entries in the +directory. It is customary to create a file to contain definitions +of your custom schema items. We recommend you create a file +{{F:local.schema}} in {{F:/usr/local/etc/openldap/schema/local.schema}} +and then include this file in your {{slapd.conf}}(5) file immediately +after other schema {{EX:include}} directives. + +> # include schema +> include /usr/local/etc/openldap/schema/core.schema +> include /usr/local/etc/openldap/schema/cosine.schema +> include /usr/local/etc/openldap/schema/inetorgperson.schema +> # include local schema +> include /usr/local/etc/openldap/schema/local.schema + + +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:RFC4512}}) used by the attributeTypes +attribute found in the subschema subentry, e.g.: + +E: attributetype <{{REF:RFC4512}} Attribute Type Description> + +where Attribute Type Description is defined by the following +{{TERM:ABNF}}: + +> AttributeTypeDescription = "(" whsp +> numericoid whsp ; AttributeType identifier +> [ "NAME" qdescrs ] ; name used in AttributeType +> [ "DESC" qdstring ] ; description +> [ "OBSOLETE" whsp ] +> [ "SUP" woid ] ; derived from this other +> ; AttributeType +> [ "EQUALITY" woid ; Matching Rule name +> [ "ORDERING" woid ; Matching Rule name +> [ "SUBSTR" woid ] ; Matching Rule name +> [ "SYNTAX" whsp noidlen whsp ] ; Syntax OID +> [ "SINGLE-VALUE" whsp ] ; default multi-valued +> [ "COLLECTIVE" whsp ] ; default not collective +> [ "NO-USER-MODIFICATION" whsp ]; default user modifiable +> [ "USAGE" whsp AttributeUsage ]; default userApplications +> whsp ")" +> +> AttributeUsage = +> "userApplications" / +> "directoryOperation" / +> "distributedOperation" / ; DSA-shared +> "dSAOperation" ; DSA-specific, value depends on server +> + +where whsp is a space ('{{EX: }}'), numericoid is a globally unique +OID in dotted-decimal form (e.g. {{EX:1.1.0}}), qdescrs is one or +more names, woid is either the name or OID optionally followed +by a length specifier (e.g {{EX:{10}}}). + +For example, the attribute types {{EX:name}} and {{EX:cn}} are defined +in {{F:core.schema}} as: + +> attributeType ( 2.5.4.41 NAME 'name' +> DESC 'name(s) associated with the object' +> EQUALITY caseIgnoreMatch +> SUBSTR caseIgnoreSubstringsMatch +> SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{32768} ) +> attributeType ( 2.5.4.3 NAME ( 'cn' 'commonName' ) +> DESC 'common name(s) associated with the object' +> SUP name ) + +Notice that each defines the attribute's OID, provides a short name, +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}} +({{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 +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 +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 +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 +it inherits the syntax, matching rules, and usage of {{EX:name}}. +{{EX:commonName}} is an alternative name. + +Neither attribute is restricted to a single value. Both are meant +for usage by user applications. Neither is obsolete nor collective. + +The following subsections provide a couple of examples. + + +H4: x-my-UniqueName + +Many organizations maintain a single unique name for each user. +Though one could use {{EX:displayName}} ({{REF:RFC2798}}), this +attribute is really meant to be controlled by the user, not the +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 '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 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 'x-my-UniqueName' +> DESC 'unique name with my organization' +> SUP name ) + + +H4: x-my-Photo + +Many organizations maintain a photo of each each user. A +{{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 'x-my-Photo' +> DESC 'a photo (application defined format)' +> SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 +> SINGLE-VALUE ) + +In this case, the syntax doesn't specify the format of the photo. +It's assumed (maybe incorrectly) that all applications accessing +this attribute agree on the handling of values. + +If you wanted to support multiple photo formats, you could define +a separate attribute type for each format, prefix the photo +with some typing information, or describe the value using +{{TERM:ASN.1}} and use the {{EX:;binary}} transfer option. + +Another alternative is for the attribute to hold a {{TERM:URI}} +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 'x-my-PhotoURI' +> DESC 'URI and optional label referring to a photo' +> SUP labeledURI ) + + +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:RFC4512}}) used by the objectClasses +attribute found in the subschema subentry, e.g.: + +E: objectclass <{{REF:RFC4512}} Object Class Description> + +where Object Class Description is defined by the following +{{TERM:ABNF}}: + +> ObjectClassDescription = "(" whsp +> numericoid whsp ; ObjectClass identifier +> [ "NAME" qdescrs ] +> [ "DESC" qdstring ] +> [ "OBSOLETE" whsp ] +> [ "SUP" oids ] ; Superior ObjectClasses +> [ ( "ABSTRACT" / "STRUCTURAL" / "AUXILIARY" ) whsp ] +> ; default structural +> [ "MUST" oids ] ; AttributeTypes +> [ "MAY" oids ] ; AttributeTypes +> whsp ")" + +where whsp is a space ('{{EX: }}'), numericoid is a globally unique +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: x-my-PhotoObject + +To define an {{auxiliary}} object class which allows +x-my-Photo to be added to any existing entry. + +> objectclass ( 1.1.2.2.1 NAME 'x-my-PhotoObject' +> DESC 'mixin x-my-Photo' +> AUXILIARY +> MAY x-my-Photo ) + + +H4: x-my-Person + +If your organization would like have a private {{structural}} +object class to instantiate users, you can subclass one of +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 'x-my-Person' +> DESC 'my person' +> SUP inetOrgPerson +> MUST ( x-my-UniqueName $ givenName ) +> MAY x-my-Photo ) + +The object class inherits the required/allowed attribute +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: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}} +entries (or subentries). While {{slapd}}(8) publishes a single +subschema subentry normally named {{EX:cn=Subschema}}, this behavior +cannot be expected from other servers. The subschema subentry +controlling a particular entry can be obtained by examining the +{{EX:subschemaSubentry}} attribute contained in the entry at the +root of each administrative context. For example, + +> ldapsearch -LLL -x -b "dc=example,dc=com" -s base "(objectclass=*)" subschemaSubentry + +To obtain the schema from a subschema subentry, you can use +ldapsearch(1) as follows (replace the search base as needed): + +> ldapsearch -LLL -x -b "cn=Subschema" -s base "(objectclass=subschema)" attributeTypes objectClasses + +where "cn=Subschema" is the value of subschemaSubentry returned in +the prior search. + +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 '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: + ++ to contain only desired type/value pairs +^ join LDIF continuation lines +^ replace attribute type with directive name +(e.g. {{EX:s/attributeTypes:/attributeType /}} and +{{EX:s/objectClasses:/objectClass /}}). +^ reorder lines so each element is defined before first use +^ continue long directives over multiple lines + +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 '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 '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 'x-my-Person' +> DESC 'my person' +> SUP inetOrgPerson +> 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. +!endif + + +H3: OID Macros + +To ease the management and use of OIDs, {{slapd}}(8) supports +{{Object Identifier}} macros. The {{EX:objectIdentifier}} directive +is used to equate a macro (name) with a OID. The OID may possibly +be derived from a previously defined OID macro. The {{slapd.conf}}(5) +syntax is: + +E: objectIdentifier <name> { <oid> | <name>[:<suffix>] } + +The following demonstrates definition of a set of OID macros +and their use in defining schema elements: + +> objectIdentifier myOID 1.1 +> objectIdentifier mySNMP myOID:1 +> objectIdentifier myLDAP myOID:2 +> objectIdentifier myAttributeType myLDAP:1 +> objectIdentifier myObjectClass myLDAP:2 +> attributetype ( myAttributeType:3 NAME 'x-my-PhotoURI' +> DESC 'URI and optional label referring to a photo' +> SUP labeledURI ) +> objectclass ( myObjectClass:1 NAME 'x-my-PhotoObject' +> DESC 'mixin x-my-Photo' +> AUXILIARY +> MAY x-my-Photo ) + |