git.sur5r.net Git - openldap/blob - doc/guide/admin/schema.sdf

   1 # $OpenLDAP$
   2 # Copyright 1999-2000, The OpenLDAP Foundation, All Rights Reserved.
   3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
   4
   5 H1: Schema Specification
   6
   7 This chapter describes how to extend slapd(8) schema.  The
   8 first section details how to extend schema using provided
   9 schema files.  The second section details how to define
  10 new schema items.
  11
  12 H2: Distributed Schema Files
  13
  14 OpenLDAP is distributed with a set of schema specifications for
  15 your use.  Each set is defined in a file suitable for inclusion
  16 (using the {{EX:include}} directive) in your {{slapd.conf}}(5)
  17 file.  These schema files are normally installed in the
  18 {{F:/usr/local/etc/openldap/schema}} directory.
  19
  20 !block table; colaligns="LR"; align=Center; \
  21         title="Table 6.1: Provided Schema Specifications"
  22 File                            Description
  23 {{F:core.schema}}               OpenLDAP {{core}} (required)
  24 {{F:cosine.schema}}             Cosine and Internet X.500 (useful)
  25 {{F:inetorgperson.schema}}      InetOrgPerson (useful)
  26 {{F:misc.schema}}               Assorted (experimental)
  27 {{F:nadf.schema}}               North American Directory Forum (FYI)
  28 {{F:nis.schema}}                Network Information Services (FYI)
  29 {{F:openldap.schema}}           OpenLDAP Project (experimental)
  30 {{F:pilot.schema}}              Cosine Pilot (obsolete)
  31 !endblock
  32
  33 To use any of these schema files, you only need to include the
  34 the desired file in the global definitions portion of your
  35 {{slapd.conf}}(5) file.  For example:
  36
  37 >       # include schema
  38 >       include /usr/local/etc/openldap/schema/core.schema
  39 >       include /usr/local/etc/openldap/schema/cosine.schema
  40 >       include /usr/local/etc/openldap/schema/inetorgperson.schema
  41
  42 Additional files may be available.  Please consult the OpenLDAP
  43 FAQ ({{URL:http://www.openldap.org/faq/}}).
  44
  45 Note: You should not modify any of the schema items defined
  46 in provided files.
  47
  48 H2: Extending Schema
  49
  50 Schema used by {{slapd}}(8) can be extended to support additional
  51 syntaxes, matching rules, attribute types, and object classes.
  52 This chapter details how to add attribute types and object classes
  53 using the syntaxes and matching rules already support by slapd.
  54 slapd(8) can also be extended to support additional syntaxes
  55 and matching rules, but this requires some programming and hence
  56 is not discussed here.
  57
  58 There are four steps to defining new schema:
  59 ^       obtain Object Identifer
  60 +       create local schema file
  61 +       define custom attribute types (if necessary)
  62 +       define custom object classes
  63
  64 H2: Object Identifiers
  65
  66 Each schema element is identified by a globally unique
  67 {{TERM[expand]OID}} ({{TERM:OID}}).  OIDs are also used to identify
  68 other objects.
  69 They are commonly found in protocols described by {{TERM:ASN.1}}.  In
  70 particular, they are heavy used by Simple Network Management
  71 Protocol (SNMP).  As OIDs are hierarchical, your organization
  72 can obtain one OID and branch it as needed.  For example,
  73 if your organization were assigned OID {{EX:1.1}}, you could branch
  74 the tree as follows:
  75
  76 !block table; colaligns="LR"; align=Center; \
  77         title="Table 6.2: Example OID hierarchy"
  78 OID                     Assignment
  79 {{EX:1.1}}              Organization's OID
  80 {{EX:1.1.1}}            SNMP Elements
  81 {{EX:1.1.2}}            LDAP Elements
  82 {{EX:1.1.2.1}}          AttributeTypes
  83 {{EX:1.1.2.1.1}}        myAttribute
  84 {{EX:1.1.2.2}}          ObjectClasses
  85 {{EX:1.1.2.2.1}}        myObjectClass
  86 !endblock
  87
  88 You are, of course, free to design a hierarchy suitable to your
  89 organizational needs under your organization's OID.  No matter
  90 what hierarchy you choose, you should maintain a registry of
  91 assignments you make.  This can be a simple flat file or a
  92 something more sophisticated such as the OpenLDAP OID Registry
  93 {{URL:http://www.openldap.org/faq/index.cgi?file=197}}.
  94
  95 For more information about Object Identifers (and a listing
  96 service) see {{URL:http://www.alvestrand.no/harald/objectid/}}.
  97
  98 .{{Under no circumstances should you use a fictious OID!}}
  99
 100 To obtain a fully registered OID at {{no cost}}, apply for
 101 a OID under {{ORG[expand]IANA}} maintained
 102 {{Private Enterprise}} arch.  Any private enterprise (organization)
 103 may request an OID to be assigned under this arch.  Just fill
 104 out the form at {{URL: http://www.iana.org/cgi-bin/enterprise.pl}}
 105 and your official OID will be sent to you usually within a few days.
 106 Your base OID will be something like {{EX:1.3.6.1.4.1.X}} were {{EX:X}}
 107 is an integer.
 108
 109 Note: Don't let the "MIB/SNMP" statement on the IANA page confuse you.
 110 OIDs obtained using this form may be used for any purpose including
 111 identifying LDAP schema elements.
 112
 113
 114 H3: Local schema file
 115
 116 The {{EX:objectclass}} and {{EX:attributeTypes}} configuration file
 117 directives can be used to define schema rules on entries in the
 118 directory.  It is customary to create a file to contain definitions
 119 of your custom schema items.  We recommend you create a file
 120 {{F:local.schema}} in {{F:/usr/local/etc/openldap/schema/local.schema}}
 121 and then include this file in your {{slapd.conf}}(5) file immediately
 122 after other schema {{EX:include}} directives.
 123
 124 >       # include schema
 125 >       include /usr/local/etc/openldap/schema/core.schema
 126 >       include /usr/local/etc/openldap/schema/cosine.schema
 127 >       include /usr/local/etc/openldap/schema/inetorgperson.schema
 128 >       # include local schema
 129 >       include /usr/local/etc/openldap/schema/local.schema
 130
 131
 132 H2: AttributeType Specification
 133
 134 {{B:To be specified.}}
 135
 136 E:      attributetype <{{REF:RFC2252}} Attribute Type Description>
 137
 138 H2: ObjectClass Specification
 139
 140 The schema rules are defined by one or more
 141 objectclass lines, and enforcement is turned on or off via the
 142 schemacheck directives. The format of an {{EX:objectclass}} line is:
 143
 144 E:      objectclass <{{REF:RFC2252}} Object Class Description>
 145
 146 This directive defines the schema rules for the object class
 147 given by {{EX:<name>}}. Schema rules consist of the attributes the
 148 entry is required to have (given by the requires {{EX:<attrs>}}
 149 clause) and those attributes that it may optionally have (given
 150 by the allows {{EX:<attrs>}} clause). In both clauses, {{EX:<attrs>}}
 151 is a comma-separated list of attribute names.
 152
 153 For example, to define an object class called {{myPerson}}, you
 154 might include a definition like this:
 155
 156 >       objectclass ( 1.2.3 NAME 'myPerson'
 157 >               DESC 'my person'
 158 >               MUST ( cn $ sn )
 159 >               MAY ( mail $ phone $ fax ) )
 160
 161