Schema management
This chapter provides an introduction to the IBM Tivoli Directory Server for both distributed platforms and z/OS. Features and functions described in this chapter are based on ITDS 5.2 and LDAP for z/OS V1R4, therefore some of the functionality described may not be available in earlier releases. The topics covered in this section include:
•What is the schema
•Modifying the schema
•Migrating a schema
•Dynamic schema
11.1 What is the schema
A schema is a set of rules that governs the way that data can be stored in the directory. The schema defines the type of entries allowed, their attribute structure, and the syntax of the attributes.
Data is stored in the directory using directory entries. A entry consists of an object class, which is required, and its attributes. Attributes can be either required or optional. The object class specifies the kind of information that the entry describes and defines the set of attributes it contains. Each attribute has one or more associated values. See “Modifying the schema” on page 292 for additional information about entries.
The schema for the IBM Directory Version 5.2 is predefined, however, you can modify the schema, if you have additional requirements.
The IBM Tivoli Directory Server Version 5.2 includes dynamic schema support. The schema is published as part of the directory information, and is available in the Subschema entry (DN="cn=schema").
The schema has more configuration information than that included in the LDAP Version 3 Request For Comments (RFCs) or standard specifications. For example, for a given attribute, you can state which indexes must be maintained. This additional configuration information is maintained in the subschema entry as appropriate. An additional object class is defined for the subschema entry IBMsubschema, which has "MAY" attributes that hold the extended schema information.
IBM Tivoli Directory Server requires that the schema defined for a naming context be stored in a special directory entry, "cn=schema". The entry contains all of the schema defined for the server. To retrieve schema information, you can perform an ldap_search by using the following:
DN: "cn=schema", search scope: base, filter: objectclass=subschema
or objectclass=*
The schema provides values for the following attribute types:
•objectClasses
•attributeTypes
•IBMAttributeTypes
•matching rules
•LDAP syntaxes
The syntax of these schema definitions is based on the LDAP Version 3 RFCs. A sample schema can be seen in Example 11-1.
Example 11-1 Sample schema
objectclasses=( 1.3.6.1.4.1.1466.101.120.111
NAME 'extensibleObject'
SUP top AUXILIARY )
objectclasses=( 2.5.20.1
NAME 'subschema'
AUXILIARY MAY
( dITStructureRules
$ nameForms
$ ditContentRules
$ objectClasses
$ attributeTypes
$ matchingRules
$ matchingRuleUse ) )
objectclasses=( 2.5.6.1
NAME 'alias'
SUP top STRUCTURAL
MUST aliasedObjectName )
attributeTypes {
( 2.5.18.10 NAME 'subschemaSubentry' EQUALITY distinguishedNameMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 NO-USER-MODIFICATION
SINGLE-VALUE USAGE directoryOperation )
( 2.5.21.5 NAME 'attributeTypes'
EQUALITY objectIdentifierFirstComponentMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.3 USAGE directoryOperation )
( 2.5.21.6 NAME 'objectClasses'
EQUALITY objectIdentifierFirstComponentMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.37 USAGE directoryOperation )
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE directoryOperation )
}
ldapSyntaxes {
( 1.3.6.1.4.1.1466.115.121.1.5 DESC 'Binary' )
( 1.3.6.1.4.1.1466.115.121.1.7 DESC 'Boolean' )
( 1.3.6.1.4.1.1466.115.121.1.12 DESC 'DN' )
( 1.3.6.1.4.1.1466.115.121.1.15 DESC 'Directory String' )
( 1.3.6.1.4.1.1466.115.121.1.24 DESC 'Generalized Time' )
( 1.3.6.1.4.1.1466.115.121.1.26 DESC 'IA5 String' )
( 1.3.6.1.4.1.1466.115.121.1.27 DESC 'INTEGER' )
( 1.3.6.1.4.1.1466.115.121.1.50 DESC 'Telephone Number' )
( 1.3.6.1.4.1.1466.115.121.1.53 DESC 'UTC Time' )
}
matchingRules {
( 2.5.13.2 NAME 'caseIgnoreMatch'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )
( 2.5.13.0 NAME 'objectIdentifierMatch'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
( 2.5.13.30 NAME 'objectIdentifierFirstComponentMatch'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )
( 2.5.13.4 NAME 'caseIgnoreSubstringsMatch'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.58 )
}
As shown in the preceding example, it is not required that all of the attribute values of a given attribute type be provided in a single production.
11.1.1 Available schema files
Several schema files are shipped with the Tivoli IBM Directory Server and the z/OS IBM Directory Server to be used as a base for a directory, to allow for product integration, and to provide an area for custom schema changes and additions.
Modifying schema files directly is not recommended. However, additional information concerning adding and modifying Schema objectclasses and attributes can be found in “Modifying the schema” on page 292.
Table 11-1 reviews the schema files that ship with the product.
Table 11-1 Schema files
|
File name
|
Description
|
|
V3.Schema.at
|
Schema attribute file, specific to the operation of IBM Directory Server. Includes configuration information, password policy enforcement, and replication.
|
|
V3.Schema.oc
|
Schema objectclass file, specific to the operation of IBM Directory Server. Includes configuration information, password policy enforcement, and replication.
|
|
V3.ibm.at
|
Schema attribute file for IBM related products and technologies. One example is the AIX Authentication schema.
|
|
V3.ibm.oc
|
Schema objectclass file for IBM related products and technologies. One example is the AIX Authentication schema.
|
|
V3.user.at
|
Industry standard LDAP schema including attributes for person, organizationalperson, and inetorgperson.
|
|
V3.user.oc
|
Industry standard LDAP schema including objectclasses for person, organizationalperson, and inetorgperson.
|
|
V3.modifiedschema
|
Custom schema additions should be placed in this file.
|
11.1.2 Schema support
The IBM Directory supports standard directory schema as defined in the following:
•The Internet Engineering Task Force (IETF) LDAP Version 3 RFCs, such as RFC 2252 and 2256
•The Directory Enabled Network (DEN)
•The Common Information Model (CIM) from the Desktop Management Task Force (DMTF)
•The Lightweight Internet Person Schema (LIPS) from the Network Application Consortium
IBM Tivoli Directory Server 5.2 includes the LDAP Version 3 defined schema in the default schema configuration. It also includes the DEN schema definitions as well as a set of extended common schema definitions that other IBM products share when they exploit the LDAP directory. They include:
•Objects for white page applications such as eperson, group, country, organization, organization unit and role, locality, state, and so forth
•Objects for other subsystems such as accounts, services and access points, authorization, authentication, security policy, and so forth
|
Note: z/OS LDAP schema extensions can be found in the /usr/lpp/ldap/etc folder.
|
11.1.3 OID
An object identifier (OID) is a string, of decimal numbers, that uniquely identifies an objectclass or attribute. An OID is required for all objectclasses and attributes that are defined in the LDAP directory. There are two ways to handle new OIDs. They can be found at the Internet Assigned Number Authority Web site, http://www.iana.org/iana/, or be generated through a text OID assignment. An OID can be assigned the value of the objectclass or attribute name appended with an ‘-oid’. For example, a new attribute, myattribute, can be assigned the OID myattribute-oid.
11.1.4 Inheritance
IBM Tivoli Directory Server version 5.2 supports object inheritance for object class and attribute definitions. A new objectclass can be defined with parent classes (multiple inheritance) and the additional or changed attributes.Each entry is assigned to a single structural object class. All object classes inherit from the abstract object class top. They can also inherit from other object classes.
As already discussed, the structure of an objectclass determines the list of required and allowed attributes for a particular entry. An object class can only inherit from object classes that precede it. For example, the objectclass organizationalPerson is able to inherit the attributes of the person objectclass, automatically inheriting the required and permitted attributes for that objectclass as well as any additional permissions specific to organizationalPerson.
11.2 Modifying the schema
The schema for the IBM Tivoli Directory Server Version 5.2 is predefined, however, you can modify the schema, if necessary. It is a good idea to take a look at what the current schema initially looks like. this can be done with a simple ldapsearch command. The following command exports the schema to an LDIF file called schemaout.ldif.
ldapsearch -L -h <ipaddress> -p <port> -b “cn=schema, <suffix>” objectclass=* > schemaout.ldif
It should be noted that editing objectclasses and attributes directly is not recommended. A more accommodating option is to utilize objectclass inheritance, creating a new objectclass which inherits all properties of the desired objectclass with customized attributes and modifications contained within its definition.
11.2.1 IBMAttributetypes
The IBMAttributeTypes attribute can be used to define schema information not covered by the LDAP Version 3 standard for attributes. In the command line examples below, each attribute added has an example of how an IBMAttributetype can be added/modified/etc along side initial actions. This is effective in allowing attributes to include indexing extensions. Below is a template that an IBMAttributeType must comply with grammatically:
IBMAttributeTypesDescription = "(" whsp
numericoid whsp
[ "DBNAME" qdescrs ] ; at most 2 names (table, column)
[ "ACCESS-CLASS" whsp IBMAccessClass whsp ]
[ "LENGTH" wlen whsp ] ; maximum length of attribute
[ "EQUALITY" [ IBMwlen ] whsp ] ; create index for matching rule
[ "ORDERING" [ IBMwlen ] whsp ] ; create index for matching rule
[ "APPROX" [ IBMwlen ] whsp ] ; create index for matching rule
[ "SUBSTR" [ IBMwlen ] whsp ] ; create index for matching rule
[ "REVERSE" [ IBMwlen ] whsp ] ; reverse index for substring
whsp ")"
11.2.2 Working with objectclasses
Working with objectclasses allows a user to customize his or her directory beyond the base LDAP installation. Below are instructions for adding, modifying, and deleting an objectclass. All instructions are command line based and may be used with either the distributed LDAP or z/OS LDAP directory servers.
Adding an objectclass
To add an object class using the command line, issue the following command:
ldapmodify -D <adminDN> -w <adminPW> -i <filename>
Where <filename> contains:
dn: cn=Schema
changetype: modify
add: objectclasses
objectclasses: ( <myobjectClass-oid> NAME <myObjectClass> DESC <An objectclass I defined for my LDAP application> SUP <objectclassinheritance> <objectclasstype> MUST (<attribute1> $ <attribute2>) MAY (<attribute1> $ <attribute2>) )
Editing an objectclass
View the object classes contained in the schema issue the command:
ldapsearch -b cn=schema -s base objectclass=* objectclasses
To edit an object class using the command line, issue the following command:
ldapmodify -D <adminDN> -w <adminPW> -i <filename>
Where <filename> contains:
dn: cn=schema
changetype: modify
replace: objectclasses
objectclasses: ( <myobjectClass-oid> NAME ’<myObjectClass>’ DESC ’<An objectclass I defined for my LDAP application>’ SUP ’<newsuperiorclassobject>’ <newobjectclasstype> MUST (<attribute1> $ <attribute2>) MAY (<attribute1> $ <attribute2>) )
Deleting an objectclass
View the object classes contained in the schema issue the command:
ldapsearch -b cn=schema -s base objectclass=* objectclasses
Select the object class you want to delete and issue the following command:
ldapmodify -D <adminDN> -w <adminPW> -i <filename>
Where <filename> contains:
dn: cn=schema
changetype: modify
delete: objectclasses
objectclasses: ( <myobjectClass-oid> NAME ’<myObjectClass>’ DESC ’<An object class I defined for my LDAP application>’ SUP ’<objectclassinheritance>’ <objectclasstype > MUST (<attribute1> $ <attribute2>) > MAY (<attribute1> $ <attribute2>) )
11.2.3 Working with attributes
Every object class includes a number of required attributes and optional attributes. Required attributes are the attributes that must be present in entries using the object class. Optional attributes are the attributes that may be present in entries using the object class.
Below are instructions for adding, modifying, and deleting an attribute. All instructions are command line based and may be used with either the distributed LDAP or z/OS LDAP directory servers.
Adding an attribute
The following example adds an attribute type definition for an attribute called myattribute.
ldapmodify -D <admindn> -w <adminpw> -i myschema.ldif
Where the myschema.ldif file contains:
dn: cn=schema
changetype: modify
add: attributetypes
attributetypes: ( myAttribute-oid NAME ( ‘myAttribute’ )
DESC ‘An attribute I defined for my LDAP application’
EQUALITY 2.5.13.2 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
USAGE userApplications )
-
add: ibmattributetypes
ibmattributetypes: ( myAttribute-oid DBNAME ( ‘myAttrTable’ ‘myAttrColumn’ )
ACCESS-CLASS normal LENGTH 200 )
Editing an attribute
This example adds indexing to the attribute, so that searching on it is faster. Use the ldapmodify command and the LDIF file to change the definition:
ldapmodify -D <admindn> -w <adminpw> -i myschemachange.ldif
Where the myschemachange.ldif file contains:
dn: cn=schema
changetype: modify
replace: attributetypes
attributetypes: ( myAttribute-oid NAME ( ‘myAttribute’ ) DESC ‘An attribute I defined for my LDAP application’ EQUALITY 2.5.13.2 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE userApplications )
-
replace: ibmattributetypes
ibmattributetypes: ( myAttribute-oid DBNAME ( ‘myAttrTable’ ’myAttrColumn’ ) ACCESS-CLASS normal LENGTH 200 EQUALITY SUBSTR )
|
Note: Both portions of the definition (attributetypes and ibmattributetypes) must be included in the replace operation, even though only the ibmattributetypes section is changing.
|
Deleting an attribute
This example deletes the attribute ‘myattribute’ from the directory schema.
ldapmodify -D <admindn> -w <adminpw> -i myschemadelete.ldif
Where the myschemadelete.ldif file includes:
dn: cn=schema
changetype: modify
delete: attributetypes
attributetypes: ( myAttribute-oid NAME ( ’myAttribute’ ) DESC ’An attribute I defined for my LDAP application’ EQUALITY 2.5.13.2 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 USAGE userApplications )
-
delete: ibmattributetypes
ibmattributetypes: ( myAttribute-oid DBNAME ( ’myAttrTable’ ’myAttrColumn’ ) ACCESS-CLASS normal LENGTH 200 EQUALITY SUBSTR )
11.2.4 Disallowed schema changes
Not all schema changes are allowed.
Change restrictions include the following:
•Any change to the schema must leave the schema in a consistent state.
•An attribute type that is a supertype of another attribute type may not be deleted.
•An attribute type that is a MAY or a MUST attribute type of an object class may not be deleted.
•An object class that is a superclass of another may not be deleted.
•Attribute types or object classes that refer to nonexisting entities (for example, syntaxes or object classes) cannot be added.
•Attribute types or object classes cannot be modified in such a way that they end up referring to nonexisting entities (for example, syntaxes or object classes).
Changes to the schema that affect the operation of the server are also not allowed. The following schema definitions are required by the directory server. They must not be changed.
Object classes
The following object class definitions must not be modified:
•accessGroup
•accessRole
•alias
•referral
•replicaObject
•top
Attributes
The following attribute definitions must not be modified:
•Operational attributes
•Restricted attributes
•Root DSE attributes
•Schema definition attributes
•Configuration attributes
•User application attributes
•Syntaxes
•Matching rules
11.3 Indexing
Index rules attached to attributes make it possible to retrieve information faster. If only the attribute is given, no indexes are maintained. ITDS provides the following indexing rules:
•Equality
•Ordering
•Approximate
•Substring
•Reverse
Indexing rules specifications for attributes: Specifying an indexing rule for an attribute controls the creation and maintenance of special indexes on the attribute values. This greatly improves the response time to searches with filters which include those attributes. The five possible types of indexing rules are related to the operations applied in the search filter.
Equality
Applies to the following search operations:
equalityMatch '='
For example:
"cn = John Doe"
Ordering
Applies to the following search operation:
•greaterOrEqual '>='
•lessOrEqual '<='
For example:
"sn >= Doe"
Approximate
Applies to the following search operation:
approxMatch '~='
For example:
"sn ~= doe"
Substring
Applies to the search operation using the substring syntax:
substring '*'
For example:
"sn = McC*"
"cn = J*Doe"
Reverse
Applies to the following search operation:
'*' substring
For example:
"sn = *baugh"
At a minimum, it is recommended that you specify equal indexing on any attributes that are to be used in search filters.
11.4 Migrating the schema
Schema migrations are used most commonly when replicas servers are being set up, or additional LDAP environments are being created. These migrations allow the modifications made to a schema, adding, deleting, modifying any objectclasses or attributes, to be carried through to all new directories.
When IBM Tivoli Directory Server 5.2 is being used, the command line instructions should be followed. When z/OS LDAP is used, the schema2ldif utility can be used.
11.4.1 Exporting the schema
In this section we discuss exporting the schema.
From the command line
The following command will dump the existing schema into a file called schemaout in LDIF format.
ldapsearch -h <ipaddress> -L -D cn=<admindn> -w <password> -b "cn=schema,<suffix>” objectclass=* > schemaout.ldif
Schema2LDIF utility
The schema2ldif utility offered by the z/OS platform is used primarily to migrate from an RDBM or SDBM schema syntax to a schema syntax that will integrate well with the TDBM backend. This utility takes .at and .oc files containing attributes and objectclasses and outputs an ldif files that can be used with the ldapmodifyschema2ldif -s at.in oc.in -d output.ldif -l log.out command to be loaded into a TDBM backend LDAP directory.
The schema2ldif file can be found in the folder /usr/lpp/ldap/bin. In the following example, the schema2ldif command is using two input files, at.in and oc.in, and creating one ldif file as an output file. The log.out file is the file in which all activity is logged for this utility. For additional information, including additional options for this utility, see the z/OS LDAP Server Administration and Use Guide.
schema2ldif -s at.in oc.in -d output.ldif -l log.out
11.4.2 Importing the schema
Both methods of exporting the schema will result in an LDIF file. This LDIF file can then be used by the following LDAP command to load the schema into the directory.
ldapmodify -h ldaphost -p ldapport -D adminDN -w passwd -f schemaout.ldif
11.5 Dynamic schema
The IBM Tivoli Directory Server Version 5.2 includes dynamic schema support. To perform a dynamic schema change, use the ldap_modify API with a DN of cn=schema. Only one dynamic change to a schema entry can be made at a time.
To delete a schema entity, provide the oid in parentheses: (oid).
To add or replace a schema entity, you MUST provide a LDAP Version 3 definition and you MAY provide the IBM definition. In all cases, you must provide only the definition or definitions of the schema entity that you want to affect.
For example, to delete the attribute type ‘cn’ (its OID is 2.5.4.3), use ldap_modify() with:
LDAPMod attr;
LDAPMod *attrs[] = { &attr, NULL };
char *vals [] = { "( 2.5.4.3 )", NULL };
attr.mod_op = LDAP_MOD_DELETE;
attr.mod_type = "attributeTypes";
attr.mod_values = vals;
ldap_modify_s(ldap_session_handle, "cn=schema", attrs);
To add a new attribute type bar with OID 20.20.20 that has a NAME of length 20chars:
char *vals1[] = { "( 20.20.20 NAME fbarf SUP NAME )", NULL };
char *vals2[] = { "( 20.20.20 LENGTH 20 )", NULL };
LDAPMod attr1;
LDAPMod attr2;
LDAPMod *attrs[] = { &attr1, &attr2, NULL };
attr1.mod_op = LDAP_MOD_ADD;
attr1.mod_type = "attributeTypes";
attr1.mod_values = vals1;
attr2.mod_op = LDAP_MOD_ADD;
attr2.mod_type = "IBMattributeTypes";
attr2.mod_values = vals2;
ldap_modify_s(ldap_session_handle, "cn=schema", attrs);
|
Note: You cannot change the ACCESS-CLASS type to or from system or restricted.
|
|
Note: Dynamic schema changes can be performed only by a replication supplier or the administrator DN. When a dynamic schema change is performed, it is replicated just like any other ldap_modify operation.
|
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.