SCHMIG: Schema Migration Utility
Articles and Tips: article
Software Engineer Consultant
Strategic Partner Engineering Group
01 Sep 1999
Explores how to use SCHMIG to solve the NDS schema migration problems. SCHMIG solves the problems that administrators have with getting the schema extensions they created for Netscape's directory to work with NDS.
Introduction
NDS schema migration problems have long plagued Novell's partners. As administrators migrate their applications to work with NDS, they run into problems getting the schema extensions they created for Netscape's directory to work with NDS.
This article examines this problem and explores using the SCHMIG utility as an easy solution.
The Problem
A number of companies have written LDAP based applications integrated with a directory. In creating these applications, some of these companies have used Netscape's directory server as a directory to store their data. To store specific data within the directory, these companies have defined a set of schema extensions used to extend Netscape's directory schema. These schema extensions are defined in plain text files, usually named slapd.user_at.conf and slapd.user_oc.conf.
These files are in a format only usable by Netscape's directory utilities. Since many of these applications are based on LDAP, it requires only a minimal effort to make them run using NDS as the directory. The problems occur when these companies migrate their software to run using NDS. They have no way to migrate their directory schema extensions to NDS. The text files used to extend Netscape's directory schema are in a different format than those files used to extend NDS's schema.
As companies manually migrate these files to work with NDS, they find a number of problems with their files that prevent them from successfully extending the NDS schema. NDS applies a number of rules when the schema is extended that ensure the NDS schema is structurally correct and can maintain the integrity of the data stored in the directory. Netscape's directory does not enforce these rules. For example, with Netscape's directory, it is possible to create a schema definition that has a class that inherits from another class that does not exist. NDS will not allow its schema to be extended with this condition.
The Solution
But fear not, there is now a solution to these schema migration problems. The answer is found in the SCHMIG utility.
SCHMIG was created to help you migrate your directory applications to NDS, and provides an easy solution to schema migration problems.
SCHMIG converts the Netscape file format to a standard LDIF format that can be easily imported into NDS to extend the NDS schema.
This LDIF format is output in a plain text file. These LDIF files can then be provided as input to another Novell utility, SCHMAP to extend the NDS schema and create mappings between NDS and LDAP attribute and class names.
Please refer to "SCHMAP: NDS Schema Extension and LDAP-to-NDS Mapping Utility" in this issue of Novell Developer Notes for more information on the SCHMAP utility.
What Is SCHMIG?
SCHMIG creates a script file, which contains all the information needed to extend the NDS Schema and do the LDAP mappings. This script file is a LDAP Data Interchange Format (LDIF) type file. This was chosen since LDIF is an industry standard for modifying a directory. The directory may be modified by extending the schema or by importing data. The specification was put together by Gordon Good, of Netscape Communications. The draft can be inspected at ftp://ftp.ietf.org/internet-drafts/draft-good-ldap-ldif-03.txt.
SCHMIG is being submitted to the Novell Developer Kit (NDK), is on both of the NDS CDs and is available for download from Novell's Web site.
Usage
SCHMIG is a DOS-based command-line utility. To view the SCHMIG usage screen, go to a DOS prompt, make sure you have the correct path, then type "SCHMIG." The following information will be displayed:
Figure 1: The SCHMIG usage screen.
To use the SCHMIG utility, type "SCHMIG," followed by the Netscape attribute file, the Netscape class file, and then the output LDIF file name. Command line options may be added at the end, if desired. The following shows an example of running SCHMIG:
Figure 2: SCHMIG running and showing the user types.
Note that since this is a DOS based utility, all the file names must be specified in the DOS 8.3 format. Long file names are not supported.
Command Line Options and Function
There are two command line options provided by SCHMIG. They are:
/a
/n
/a causes SCHMIG to append to the output file rather than overwrite it. If the file does not exist, it will be created. If this option is not used, the output file is created, overwriting any file by that name.
/n causes the creation of a number of extra attributes in the output file. These are attributes that exist by default in Netscape's default schema, but do not exist by default in NDS. These attributes include:
departmentNumber
employeeType
homePhone
homePostalAddress
telephoneNumber
facsimileTelephoneNumber
preferredLanguage
mobile
pager
User Interface
SCHMIG uses a command line interface that simply shows a report of the number of attributes and classes that were processed from the input files. The following shows the output.
XXX Attributes Processed. XXX Classes Processed.
Processing Rules
As SCHMIG process the input file, it uses a number of rules to ensure the resulting output file will be compatible with NDS. SCHMIG creates the output file according to the following rules:
Attribute names and Class names cannot be longer than 32 characters in NDS. SCHMIG checks the length of the Netscape names and truncates them to 32 characters if necessary.
The input Netscape attribute file may contain attribute name aliases. These aliases are processed and discarded.
SCHMIG will make sure that all the classes to be added to the schema are added in the correct order. If there are dependencies on a given class, that class will be added first, so that the referenced class will be added to the directory first. NDS requires this integrity. SCHMIG also checks for circular dependencies and logs them into a log file.
SCHMIG checks to make sure all classes are inheriting from a valid class. NDS does not allow a class to inherit from another class that does not exist. SCHMIG checks all class inheritance and will reorder the classes, if necessary, to make sure that classes inheriting from other classes are written to the output file after those classes from which they are inheriting.
If a class inherits from another class that is not among those to be added, SCHMIG will also check to see if a mapping exists between the referenced class and the default LDAP mappings. If it finds the referenced name in the LDAP mapping list, the mapped NDS name is then substituted and used. If a mapping cannot be found, SCHMIG has to assume the class already exists in the directory schema and simply creates an entry in the log file indicating such.
Information about containment does not exist in the Netscape input files. This is required by NDS. SCHMIG adds containment values to each class it writes to the output file. The most common containers are used. These include Organization and Organizational Unit.
Information about naming is not included in the Netscape input files. Each class added to NDS must have at least one naming attribute. This naming attribute may be inherited from a superior class. However, if the class to be added to the schema inherits from `top', a naming attribute must be specified.
The naming attribute must have a syntax type of string. SCHMIG adds as naming attributes, all `required' attributes that have a valid syntax. If no required attributes are available, it scans the list of optional attributes and uses the first one it finds. If no optional attributes exist of the necessary syntax, the common name attribute, CN, is added as a required attribute and is used for the naming attribute.
Classes within NDS can either be effective, non-effective, or auxiliary classes. Objects can be created within the directory that are of the type of an effective class. Non-effective classes can only be used to create other classes with the new effective class inheriting from the non-effective class. Auxiliary classes are used to associate additional information to an object in the directory. An auxiliary class defines the additional information. The association is done at run-time, not when the classes are defined in the schema. Classes added to the schema by SCHMIG are always added as effective classes. In addition, all classes are flagged such that they are not containers, these flags can be changed in the SCHMIG output file, before the LDIF file is applied to the directory.
Log File
Anytime SCHMIG has to make assumptions, or finds potential problems, it creates an entry in the log file. The log file name is SCHMIG.LOG. It is always wise to review the log file before running SCHMAP to actually extend your NDS schema. The most common NDS related log messages are listed below. Other error messages such as memory allocation errors are also logged.
Warning: Class XXX is inheriting from class YYY which is not being added to the schema.
This warning indicates that SCHMIG cannot validate the class from which XXX is derived. SCHMIG cannot determine if YYY exists. An error would occur when running SCHMAP if YYY doesn't exist in the schema.
Warning: Class XXX is inheriting from class YYY which is not being added to the schema. ZZZ substituted.
This warning is the same as the one above except that SCHMIG has determined that YYY is an LDAP class name. In this case, SCHMIG will substitute ZZZ as the class from which XXX is inherited, and all will work. This warning is just to inform the user that the substitution took place.
Class inherits from top and has no required naming attribute. Making attribute required: XXX
NDS requires that all class be "named". If a class inherits from some other class, then the naming can also be inherited. However, if the class is inherited from top, then a naming attribute must be specified. SCHMIG will first attempt to use an attribute that is specified as "required." If one is not available, SCHMIG will attempt to use an attribute specified as "allows." If one of these attributes is used, SCHMIG also makes this attribute "required." In this case, SCHMIG will only add the first "allows" attribute it can use as the naming attribute. If an "allows" attribute is not available, SCHMIG will add "CN" as the naming attribute and make it required.
Warning: Class XXX is using LDAP name YYY. Substituting NDS name: ZZZ
This is warning indicates that class XXX is referencing an attribute which is not an NDS name, but an LDAP name. In the output file, SCHMIG will substitute the appropriate NDS attribute name (ZZZ).
Warning: Class XXX is requiring an unknown attribute: YYY
This warning indicates that SCHMIG doesn't know about YY. It is not an attribute that is being added in this session, and it is not an LDAP name that is already mapped to NDS. This is a warning that it is assumed that YY already exists in the schema. It is listed as a "required" attribute. This will be a common warning if, for example, class XXX references CN.
Warning: Class XXX is using an unknown attribute: YYY
This warning is the same as the one above, except that the attribute is listed as an "allows" attribute rather than a required attribute.
Attribute name is too long and will be truncated: XXX. Class name is too long and will be truncated: YYY
NDS attribute and class names have a maximum length of 32 characters. If SCHMIG detects a name that is longer, it truncates the name to 32 characters so that it can be properly added to the schema.
Error: Class contains no superior statement: XXX
The superior statement must be present for a class to be added to NDS. If the class is not inheriting from any specific class, the statement must be added for the class to have "top" as the superior. This error message will be preceded in the log file by the warning message #1 above with no class listed.
Error: Invalid class or attribute: XXX. Program: Terminated
This error message occurs when SCHMIG detects an invalid input file. The data in the input file is not valid according to Netscape's .conf file format.
Summary
SCHMIG was created to help Novell's partners migrate their directory applications to NDS. As these partners migrate their applications to work with NDS, they run into problems getting the schema extensions they created for Netscape's directory to work with NDS. SCHMIG helps solve this problem by providing a conversion of their schema extension files to a file format that can be used by NDS. SCHMIG cannot provide a perfect conversion, because the Netscape files contain insufficient information to create schema extension files for NDS. However, it does overcome many of the pitfalls partners are having in getting their NDS schema extended.
* Originally published in Novell AppNotes
Disclaimer
The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.