Adding upstream version 2.5.13+dfsg.upstream/2.5.13+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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 )
+