H1: Schema Specification
-This chapter describes how to extend the schema used by {{slapd}}(8).
+This chapter describes how to extend the user schema used by {{slapd}}(8).
The first section, {{SECT:Distributed Schema Files}} details optional
schema definitions provided in the distribution and where to obtain
other definitions.
cosine.schema Cosine and Internet X.500 (useful)
inetorgperson.schema InetOrgPerson (useful)
misc.schema Assorted (experimental)
-nadf.schema North American Directory Forum (FYI)
nis.schema Network Information Services (FYI)
openldap.schema OpenLDAP Project (experimental)
!endblock
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 attribute types and object classes
-using the syntaxes and matching rules already supported by slapd.
-slapd can also be extended to support additional syntaxes
-and matching rules, but this requires some programming and hence
-is not discussed here.
+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 Identifer
+ define custom attribute types (if necessary)
+ define custom object classes
+
H3: Object Identifiers
Each schema element is identified by a globally unique
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 a
+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/}}.
-.{{Under no circumstances should you use a fictious OID!}}
+.{{Under no circumstances should you use a fictitious OID!}}
To obtain a fully registered OID at {{no cost}}, apply for
-an OID under {{ORG[expand]IANA}} (IANA) maintained
+an OID under the {{ORG[expand]IANA}} (IANA) maintained
{{Private Enterprise}} arch. Any private enterprise (organization)
may request an OID to be assigned under this arch. 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}} were {{EX:X}}
+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.
The smaller the organization, the longer your prefix should
be.
-In the examples below, we have choosen a short prefix '{{EX:my}}'
+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. For a small, local organization,
we recommend something like '{{EX:deFirm}}' (German company) or
> [ "EQUALITY" woid ; Matching Rule name
> [ "ORDERING" woid ; Matching Rule name
> [ "SUBSTR" woid ] ; Matching Rule name
-> [ "SYNTAX" whsp noidlen whsp ] ; see section 4.3
+> [ "SYNTAX" whsp noidlen whsp ] ; Syntax OID
> [ "SINGLE-VALUE" whsp ] ; default multi-valued
> [ "COLLECTIVE" whsp ] ; default not collective
> [ "NO-USER-MODIFICATION" whsp ]; default user modifiable
>
where whsp is a space ('{{EX: }}'), numericoid is a globally unique
-OID in dotted-decimal form (e.g. {{EX:1.2.3}}), qdescrs is one or more
-names, woid is either the name or OID, and noidlen is an optional length
-specifier (e.g {{EX:{10}}}).
+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' ) SUP name )
-
-Notice that each defines the attribute's OID and descriptive
-names. Each name is an alias for the OID. {{slapd}}(8) returns
-the first listed name when returning results.
+> attributeType ( 2.5.4.3 NAME ( 'cn' $ 'commonName' )
+> DESC 'common name(s) assciated with the object'
+> SUP name )
-The first attribute, {{EX:name}}, has a syntax of {{EX:directoryString}}
-(a UTF-8 encoded Unicode string) with a recommend maximun length.
-Note that syntaxes are specified by OID. In addition, the equality
-and substring matching uses case ignore rules. Below are tables
-listing commonly used supported syntax and matching rules.
+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}}
+(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).
!block table; align=Center; coltags="EX,EX,N"; \
- title="Table 6.3: Supported Syntaxes"
+ title="Table 6.3: Commonly Used Syntaxes"
Name OID Description
-binary 1.3.6.1.4.1.1466.115.121.1.5 BER/DER data
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
>
!block table; align=Center; coltags="EX,N"; \
- title="Table 6.4: Supported Matching Rules"
+ title="Table 6.4: Commonly Used Matching Rules"
Name Type Description
booleanMatch equality boolean
+octetStringMatch equality octet string
objectIdentiferMatch equality OID
distinguishedNameMatch equality DN
-uniqueMemberMatch equality DN with optional UID
+uniqueMemberMatch equality Name with optional UID
numericStringMatch equality numerical
numericStringOrderingMatch ordering numerical
numericStringSubstringsMatch substrings numerical
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 and both are
-meant for usage by user applications. You likely won't need to
-specify other parameters such as {{EX:OBSOLETE}}.
+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.
> SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
> SINGLE-VALUE )
-As noted in the description, LDAP has no knowledge of the
-format of the photo. It's assumed that all applications
-accessing this attribute agree on the handling of values.
+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
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}}).
+{{EX:labeledURI}} ({{REF:RFC2079}}) or simply create a subtype,
+e.g.:
+
+> attributetype ( 1.1.2.1.3 NAME 'myPhotoURI'
+> DESC 'URI and optional label referring to a photo'
+> SUP labeledURI )
H3: Object Class Specification
> whsp ")"
where whsp is a space ('{{EX: }}'), numericoid is a globally unique
-OID in numeric form (e.g. {{EX:1.2.3}}), qdescrs is one or more
+OID in numeric form (e.g. {{EX:1.1.0}}), qdescrs is one or more
names, and oids is one or more names and/or OIDs.
> objectclass ( 1.1.2.2.2 NAME 'myPerson'
> DESC 'my person'
> SUP inetOrgPerson
-> MUST ( 'myUniqueName' $ 'givenName' )
-> MAY 'myPhoto' )
+> MUST ( myUniqueName $ givenName )
+> MAY myPhoto )
The object class inherits the required/allowed attribute
types of {{EX:inetOrgPerson}} but requires {{EX:myUniqueName}}
> attributeTypes: ( 1.1.2.1.2 NAME 'myPhoto' DESC 'a photo (applicatio
> n defined format)' SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
> objectClasses: ( 1.1.2.2.2 NAME 'myPerson' DESC 'my person' SUP inet
-> OrgPerson MUST ( 'myUniqueName' $ 'givenName' ) MAY 'myPhoto' )
+> OrgPerson MUST ( myUniqueName $ givenName ) MAY myPhoto )
Capture the output of the search in a file and then edit the file:
> objectClass ( 1.1.2.2.2 NAME 'myPerson'
> DESC 'my person'
> SUP inetOrgPerson
-> MUST ( 'myUniqueName' $ 'givenName' )
-> MAY 'myPhoto' )
+> MUST ( myUniqueName $ givenName )
+> MAY myPhoto )
Save in an appropriately named file (e.g. {{F:my.schema}}).
-You may now include this file in your {{slapd.conf}}(8) file.
+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}} 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 'myPhotoURI'
+> DESC 'URI and optional label referring to a photo'
+> SUP labeledURI )
+> objectclass ( myObjectClass:1 NAME 'myPhotoObject'
+> DESC 'mixin myPhoto'
+> AUXILIARY
+> MAY myPhoto )
+
projects / openldap / blobdiff