schema.sdf

ldap服务器源码

# $OpenLDAP: pkg/openldap-guide/admin/schema.sdf,v 1.39.2.3 2007/01/02 21:43:43 kurt Exp $
# Copyright 1999-2007 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 familar 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 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
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 Identifer
+	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	myAttribute
1.1.2.2		ObjectClasses
1.1.2.2.1	myObjectClass
!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 Identifers (and a listing service)
see {{URL:http://www.alvestrand.no/harald/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
including identifying LDAP schema elements.

Alternatively, OID name space may be available from a national
authority (e.g., {{ORG:ANSI}}, {{ORG:BSI}}).


H3: Name Prefix

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.

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.

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}}).


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:RFC2252}}) used by the attributeTypes
attribute found in the subschema subentry, e.g.:

E:	attributetype <{{REF:RFC2252}} Attribute Type Description>

where Attribute Type Description is defined by the following
{{TERM:BNF}}:

>      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) assciated 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}}
(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 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 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	arbitary octets
!endblock