Methods for Extending the Schema

Windows 2000 gives you some choices regarding the way you accomplish schema extension. You can import and export objects in a batch mode by using each of these administrative tools: LDIF Directory Exchange (LDIFDE), CSV Directory Exchange (CSVDE), and ADSI scripts. These tools enable you to administer large numbers of objects (such as users, contacts, groups, servers, and printers) in one operation. By using these tools, it is possible to export Active Directory data to other applications and services and to import information from other sources into Active Directory. These tools are installed automatically on all Windows 2000 servers. Or you can perform schema extension programmatically by using ADSI Edit. You can also extend the schema from the user interface with the Active Directory Schema console.

LDAP Data Interchange Format

The LDAP Data Interchange Format (LDIF) (file) format has a command-line utility called "LDIFDE" that allows you to create, modify, and delete directory objects. It can be run on a Windows 2000–based server or copied to a Windows 2000–based workstation. For example, LDIFDE can be used to extend the schema, export Active Directory user and group information to other applications or services, and populate Active Directory with data from other directory services.

LDIF is an Internet standard for a file format to perform batch import and batch export operations for directories that conform to LDAP standards. An LDIF file consists of a series of records that are divided by line separators. A record describes either a single directory entry or a set of modifications to a single directory entry and consists of one or more lines in the file.

Using the LDIFDE Tool

The LDIFDE tool is executed from the command prompt. At the prompt, type the command LDIFDE and the appropriate parameters in the following form:

LDIFDE [ -i ] [ -f** ] [ -s ] [ -c ] [ -v ] [ -t ] [ -d ] [ -r ] [ -p ] [ -l ] [ -o ] [ -m ] [ -n ] [ -j ] [ -g ] [ -k ] [ -a ] [ -b ][ -? ][- u ][- y ]

note-icon

Note

A hyphen (-) is required before each parameter.

Table 4.13, Table 4.14, Table 4.15, and Table 4.16 contain descriptions of all of the parameters.

Table   4.13 LDIFDE Tool Basic Parameters

Basic Parameters

Value(s) to Specify

Description

-i

mode

Specifies import mode. If this parameter is not specified, the default mode for LDIFDE (and CSVDE) is export.

-f

filename

Identifies the import or export file name.

-s

server name

Specifies the domain controller to perform the import or export operation. If this parameter is not specified, the operation communicates with the domain controller of the domain to which the user is currently logged on.

-c

from distinguished name (string1)
to distinguished name (string2)

Replaces all occurrences of string1 with string2. This usually is used when you are importing data from one domain to another and the distinguished name of the export domain has to be replaced with that of the import domain. This parameter is designed to support the import of data when the receiving domain name is different than the exporting domain name.

-t

port number

Specifies a port number. The default LDAP port is 389. (The Global Catalog port is 3268.)

-v

verbose mode

Sets verbose mode, which provides more detailed status description of the import/export operation. If this parameter is not specified, the default is nonverbose mode.

-?

Help

Use to display Help.

Table 4.14 LDIFDE Tool Export-specific Parameters

Export-specific Parameters

Value(s) to Specify

Description

-d

base distinguished name

Sets the distinguished name of the search base for data export. If this parameter is not specified, it defaults to the root of the domain.

-r

LDAP filter

Creates an LDAP search filter for data export. For example, to export all users with your surname, the following filter could be used:
-r "(&(objectClass=user)(sn=yoursurname))".
Note that the default is (objectClass=*). For more information about LDAP search filters, see "Name Resolution in Active Directory" in this book.

-p

scope

Sets the search scope. Values are: Base, OneLevel, or SubTree. If not specified, the default is SubTree. For more information about the search scope, see "Name Resolution in Active Directory" in this book.

-l

LDAP attribute list

Sets the list of attributes to return in the results of an export query. If this parameter is omitted, all attributes are returned. For example, to retrieve only the distinguished name, common name, first name, surname, and telephone number of the returned objects, the following attribute list would be specified:
-l "distinguishedName, cn, givenName, sn, telephone".
(Note: Quotation marks around the list of attributes is optional.)

-o

attributes in results

Omits a list of attributes from the results of an export query. This is used when exporting objects from Active Directory and then importing them into another LDAP-compliant directory. Some attributes might not be supported in the directory receiving the objects. For example, to omit whenCreated and whenChanged , the following would be specified:
-o "whenChanged, whenCreated".
This parameter omits the attributes from the results. If not specified, all attributes are included.
(Note: Quotation marks around the list of attributes is optional.)

-m

Active Directory attributes

Omits attributes that apply to only Active Directory objects such as objectGUID (globally unique identifier), objectSID (security identifier), pwdLastSet (password last set), and samAccountType . By default, this parameter is disabled.
Its primary purpose is to export entries in preparation of re-importing them into Active Directory. This also activates the linked attribute option, which appends to the end of the file the values for attributes that are linked to the current object. For example, a parent object has linked attributes to a child object, and those entries are placed at the end of the file. (Note: Some attributes are read-only for Active Directory and, thus, cannot be re-imported. The -m option strips these attributes out at the time of export to prepare the file for re-importing.)

-n

binary values

Specifies not to export binary values. By default, this parameter is disabled.

-j

directory path

Sets the log file location. The default is the current directory.

-g

paged searches

Specifies not to perform paged searches. If not specified, it performs paged searches. Note that some servers might not support the paged search control.

-u

Unicode

Enables Unicode support. When this parameter is used during an export operation, a Unicode file is generated. When the parameter is used during an import operation, the tool would expect a Unicode file as input.

-y

 

Enables lazy commit to the directory.

Table 4.15 LDIFDE Tool Import-specific Parameters

Import-specific Parameters

Value(s) to Specify

Description

-k

action if errors are encountered

Skips errors during the import operation and continues processing. If not specified, the import operation stops if it encounters the following errors:
LDAP_ALREADY_EXISTS
LDAP_CONSTRAINT_VIOLATION
LDAP_ATTRIBUTE_OR_VALUE_EXISTS
LDAP_NO_SUCH_OBJECT
ERROR_MEMBER_IN_ALIAS
It will also skip objects with no attributes.
For more information about these errors, see the Microsoft Platform SDK link on the Web Resources page at https://windows.microsoft.com/windows2000/reskit/webresources .

Table 4.16 LDIFDE Tool Credentials Parameters

Credentials Parameters

Value(s) to Specify

Description

-a

user distinguished name
password OR *

Sets the command to run by using the supplied user distinguished name and password. The default is to run by using the credentials of the currently logged on user. For example,
-a "cn=yourname,dc=yourcompany,dc=com password".
* = option to hide password

-b

username domain password OR *

Sets the command to run as the username domain password. The default is to run using the credentials of the currently logged on user.
* = option to hide password

note-icon

Note

Make sure that all required attributes exist when you create or modify objects. For example, the required attributes for creating a user are distinguishedName , objectClass , and samAccountName .

Exporting and Re-Importing Objects

Linked attributes contain information about the links to a current object. During a normal export session, a parent object might be exported before its child object. On the re-import operation, if the parent object has been added before the child object, the operation fails because the child object is not yet in the directory.

However, when the -m parameter is used to export objects and re-import them into Active Directory, all entries that contain a linked attribute are appended to the end of the file. Moreover, the linked addition is separated from the main object creation call so that the failure in membership addition does not cause the object creation to fail. The linked attribute is appended to the end of the file.

Read-only Properties on Objects

Active Directory has Security Accounts Manager (SAM) properties that are read-only because they are set by the system at the time the object is created. When the -m parameter is used to export objects and re-import them into Active Directory, all of the SAM attributes are ignored during the export operation. In that way, when the entries are re-imported into Active Directory, they succeed because they do not contain any SAM information.

Example of an LDIF Import File

In the following example of an LDIF import file format, you also can see how to add a user object to the myDomain.microsoft.com domain:

dn: CN=sampleUser,CN=Users,DC=myDomain,DC=microsoft,DC=com
changetype: add
cn: sampleUser
description: Example of an Imported User using LDIFDE
objectClass: user
sAMAccountName: sampleUser

The following is an example of the command that is used to import the file in the preceding example:

ldifde -i -f import.ldf -v

Manipulating Data in an LDIF Export File

The preferred method of manipulating the distinguished name ( distinguishedName ) during an LDIFDE export operation is to use the –c parameter. For example, by using this parameter in conjunction with the –m parameter, you can import a large group of users from one domain into another domain.

note-icon

Note

You must use a text editor to make substantial changes to attribute values in your export file prior to import.

Comma-Separated Value File Format

The bulk import and export of data to and from Active Directory can be performed by using files that store data in the Microsoft comma-separated value (CSV) file format, also known as a .csv file. The CSV file format is supported by many other applications, such as Microsoft® Excel, that can read and save data in the CSV file format. Also, Microsoft® Exchange Server administration tools can import and export data by using the CSV format. The CSV format has a command-line utility called "CSVDE" that allows you only to add new objects. It can be run on a Windows 2000–based server or copied to a Windows 2000–based workstation.

The CSV format consists of a simple text file with one or more lines of data where each value is separated by a comma. The text file contains entries where the initial entry is a comma-separated list of attribute names. Each subsequent entry in the text file represents a single object in the directory. Attribute values are delimited by commas.

Using the CSVDE Tool

The CSVDE tool is executed from the command prompt. At the command prompt, type the command CSVDE . The parameters that are used for the CSVDE tool are the same as those that are used for the LDIFDE tool. However, unlike the LDIFDE tool, CSVDE creates files that can be read from applications other than LDAP servers. For example, if you want to view all Active Directory users in a Excel report, CSVDE is used to export the directory data into the .csv file format, which could then be read by Excel.

The CSVDE tool is executed from the command prompt. At the prompt, type the command CSVDE and the appropriate parameters in the following form:

CSVDE [-i] [-f ] [-s] [-c] [-v] [-t] [-d] [-r] [-p] [-l] [-o] [-m] [-n] [-e] [-j] [-g] [-k] [-a ] [-b] [-?][-u]

The descriptions of these parameters are contained in Table 4.13, Table 4.14, Table 4.15, and Table 4.16. As for the LDIFDE tool, the default mode for CSVDE is Export, unless otherwise specified by using the -i parameter for the import mode.

note-icon

Note

CSVDE cannot be used to modify or delete objects. It can be used only to add directory objects. A hyphen (-) is required before each parameter.

Viewing Data in the .csv File

When you view data in the .csv file, the values for multivalue attributes are expressed as a single value that is internally delimited by a second user-definable delimiting character (by default, $). Attribute values are listed left to right in the order in which the attribute names are listed in the initial entry. Values are positional, and every entry must account for each attribute listing in the initial entry. The attribute names must be in the same order as the data in any line that follows the first line, as shown in the following example:

dn,cn,firstName,surname,description,objectClass,sAMAccountname
"cn=John Smith,cn=Users,dc=myDomain,dc=microsoft,dc=com",John Smith,John,Smith,Manager,user,jsmith
"cn=Jane Smith,cn=Users,dc=myDomain,dc=microsoft,dc=com",Jane Smith,Jane,Smith,President,user,janes

Each object stands alone and does not need the context of another object to be listed in the .csv file, which simplifies the reading and writing of files and allows objects from different classes to be contained in a single file.

Another example shows the .csv file format and lists the header, which contains the LDAP display names of the properties ("attributes") — distinguished name, object class, common name, given name, surname, telephone number, street address, locale, country/region, and sAMAccountName.

dn,objectClass,cn,givenName,sn,telephoneNumber, street,l,c,sAMAccountName
"cn=James Smith,cn=Users,dc=myDomain,dc=microsoft,dc=com",user,James Smith,James,Smith, ,203-223-2233, 15 Woodbine St.,Fenwick,US,jsmith

All data values are represented as strings. Numeric values are represented by numeric strings; binary values are represented by hexadecimal strings. Hexadecimal strings start with the character "x," followed by a single quotation mark ('), then the hexadecimal string, and, finally, another single quotation mark ('). The following is an example of a hexadecimal string:

X'01050000000000051500000079e3fc535729024c235f636bf5010000'

Syntax information is stored in the schema of the destination directory. Programs that accept imported .csv files determine how to process the values by using the schema in the target directory.

A missing or unsupported attribute value has an empty position in the string. For example, if the third attribute value for an entry is missing, it would be expressed as follows:

firstvalue,secondvalue,,fourthvalue

Multivalue attributes are separated by semicolons (;). For example if there are three attributes and the second one is a multivalue attribute, it would be expressed as follows:

1stvalue,2ndvalue1;2ndvalue2;2ndvalue3,3rd value

Reserved characters that appear in string properties are represented through an escape mechanism. The following are reserved characters:

  • Backslash (\)

  • Semicolon (;)

  • Special character for hexadecimal representation (x')

The escape mechanism uses a backslash (\) before a reserved character as an escape character. If a value contains a backslash, the backslash in the value also must be preceded by the escape character — that is, by another backslash (for example, \\). The semicolon (;) character is used to delimit multivalues. If the value itself contains a semicolon, the semicolon in the value must be preceded by the escape character (for example, \;). The hexadecimal prefix (x') character, if used in a value, must also be preceded by an escape character (for example, \x').

There are two other characters that must be handled in a special way. They are the comma (,) and the double quotation marks (") characters. The comma (,) is treated as a special character in the CSV format because it is used to separate values. If the value contains a comma (,), the format specifies that the comma has to be enclosed by double quotation marks (for example, value1,value2 are represented as "value1,value2"). The double quotation marks (") character is used to contain values if the values contain commas (,). When a value contains a pair of double quotation marks as well as a comma, the quotation marks in the value have to be enclosed with another set of double quotation marks, as follows:

"value1","value2" is represented as ""value1"",""value2""

value1"value2 is represented as "value1""value2"

The following CSV file shows an example of adding an organizational unit, followed by a user, and a computer:

dn,cn,givenName,sn,description,objectClass,sAMAccountname

"ou=sampleOU,dc=myDomain,dc=microsoft,dc=com",,,,Sample Organizational Unit,organizationalUnit,

"cn=John Smith,ou=sampleOU,dc=myDomain,dc=microsoft,dc=com",John Smith,John,Smith,Sample User,user,jsmith

"cn=sampleComputer,ou=sampleOU,dc=myDomain,dc=microsoft,dc=com",sampleComputer,,,Sample Computer,computer,computer1

note-icon

Note

Both ANSI text and UNICODE are supported.

Using LDIFDE and CSVDE to Modify the Schema

LDIFDE and CSVDE use files that contain directory data in the appropriate format. These files can be imported or exported to LDAP-based directory servers as a means of populating a directory or modifying objects in a directory. Because the Active Directory schema exists as a collection of directory objects, either of these tools can be used to extend the schema.

note-icon

Note

At present, CSVDE can be used only for additions to the directory, not for modifications to the directory.

LDIF File Format

The LDIF file format can be used to perform batch operations on directories that conform to LDAP standards. It is suitable for additions to the directory as well as modifications and deletions of directory objects. A record in an LDIF file consists of a sequence of lines that either describe a directory entry or a set of changes to a single directory. This format can be used for all LDAP operations.

The preferred method when modifying the schema is to use the Active Directory Schema console to edit the schema on a practice system that is isolated from your real enterprise. You can use the LDIFDE export to produce a script, which you can then run against your live system. The following example represents the contents of a sample LDIF file that can be used to add a new attribute to Active Directory.

dn: CN=New-Attribute-Name,CN=Schema,CN=Configuration, DC=microsoft,DC=com
changetype: add
objectClass: attributeSchema
ldapDisplayName: newAttributeName
adminDisplayName: New-Attribute-Name
adminDescription: New-Attribute-Name
attributeId: 1.2.840.113556.1.4.8000.1 <-
the id has to be unique
attributeSyntax: 2.5.5.12
omSyntax: 64
isSingleValued: TRUE
systemOnly: FALSE
searchFlags: 0
showInAdvancedViewOnly: TRUE

The following example shows an LDIF file that can be used to force a schema cache update.

dn:
changeType: modify
add: schemaUpdateNow
schemaUpdateNow: 1

For more information about the LDIF format and using LDIFDE, see the Microsoft Platform SDK link on the Web Resources page at https://windows.microsoft.com/windows2000/reskit/webresources .

CSV File Format

The CSV file format is a simple format whose primary benefit is ease of use. In the CSV file format, each line represents a discrete object in the directory, with the object's attributes separated by commas. The first line of the file always contains all of the attribute names. Each subsequent line represents a different entry in the directory. Values for multivalue attributes can also be specified and are delimited by the semicolon (;) character.

Because this format is compatible with the Microsoft Excel CSV format, you can dump directory information to an Excel spreadsheet or import data from a spreadsheet into Active Directory. This format can be used only for additions to the directory. The following example represents the contents of a CSV file that can be used to add a user to Active Directory:

dn,objectClass,cn,sn,givenName,telephoneNumber,street,l,c,sAMAccountName
"CN=John Doe,DC=myDomain,DC=microsoft,DC=com",
User,John Doe,Doe,John, 555-456-7890,123 Magnolia Ave.,Redmond,US,jdoe

Both the CSVDE and LDIFDE tools have command line help that can be viewed by typing the command name at an MS-DOS® prompt. Because both of these tools allow data to be imported and exported, there are a number of different uses for them.

Migration to Active Directory    By using either of these tools, users of other directory services can import data to Active Directory. This works for any directory that is LDAP-compatible as long as the attribute names match.

Publishing Information from the Directory    You can use either of these tools to export directory data to another application that can read either the LDIF or CSV format. You can also export to other LDAP-compatible directory services, provided there are matching attribute names.

Adding Resources to the Directory    In addition to the Active Directory Users and Computer console and ADSI Edit, administrators can choose to use one of these tools to add objects to a directory. These tools lie somewhere between the other options in terms of ease of use and flexibility. Because the schema is represented in Active Directory as directory objects, you can use LDIFDE or CSVDE to extend the schema with new or modified schema objects. In fact, if your application requires schema modifications, the best way to accomplish this is to distribute an LDIF or CSV file with the application that is to be imported to the schema.

Figure 4.5 illustrates one way in which LDIF can be used to extend Active Directory.

Cc961584.DSBE06(en-us,TechNet.10).gif

Figure 4.5 Extending Active Directory with LDIF

Using Active Directory Service Interfaces and Visual Basic Scripts

Although one potential benefit of using an LDIF or CSV file is that the administrator can look at it to see what it does, consider the merits of extending the schema programmatically:

  • A programmatic extension is invariant; it is a Windows executable file. The binary cannot be tampered with, unlike an LDIF or a CSV file, either of which can be modified inadvertently or maliciously.

  • Programs can detect and recover from errors and provide intelligent feedback.

  • Programs handle Unicode without resorting to Base64 encoding. (Unicode is a 16-bit character set that contains all of the characters commonly used in information processing.)

  • Programs can use the Windows Installer (.msi) setup APIs.

  • Programs can be signed to prove their authenticity.

Active Directory provides a set of interfaces that enable you to gain access to directory objects, including schema objects, programmatically. ADSI defines a directory service model and a set of COM interfaces that you can easily use with a variety of programming languages. ADSI conforms to the Component Object Model and supports standard COM features.

By using Microsoft® Visual Basic® Script and ADSI, you can write scripts easily to accomplish various directory modifications, including extending the schema.

These are the specific ADSI interfaces to use when you extend the schema:

IADsContainer    Use IADsContainer::Create to create new classSchema and attributeSchema objects.

IADs    Use IADs::Get (or GetEx) to read the attributes of classSchema and attributeSchema objects. Use IADs::Put (or PutEx ) to set the attributes of classSchema and attributeSchema objects. PutEx is particularly useful in manipulating the lists of mustContain and mightContain attributes because it is designed specifically for handling multivalue attributes.

The code in the example that follows represents a script that you can use to add a user to Active Directory.

Dim oDomain
Dim oUser
Set oDomain=GetObject("LDAP://OU=Marketing,DC=antipodes,DC=com")
Set oUser = oDomain.Create("user","cn=John Smith")
oUser.Put "samAccountName","JSmith"
oUser.Put "givenName","John"
oUser.Put "sn","Smith"
oUser.Put "userPrincipalName","jsmith@antipodes.com"
oUser.SetInfo
MsgBox "User created " & oUser.Name
Set oDomain = Nothing
MsgBox "Finished"
WScript.Quit

note-icon

Note

For more information about ADSI and ADSI interfaces, see the Microsoft Platform SDK link on the Web Resources page at https://windows.microsoft.com/windows2000/reskit/webresources .

Using the Active Directory Schema Console

The Active Directory Schema console allows members of the Schema Administrators group to manage the schema through a graphical interface. With it, you can create and modify classes and attributes and also specify what attributes are indexed and what attributes are replicated to the Global Catalog. After you start the Active Directory Schema console, the first thing that you must do is to make sure that the tool is focused on the schema master for your enterprise.

note-icon

Note

The Schema Management snap-in is not one of the default MMC snap-ins that is provided with Windows 2000 Server. To make it appear in the list of available snap-ins, you must install the admin tools package (Adminpak.msi). To register the Schema Management snap-in, open your %SystemRoot%\System32 folder and run Regsvr32 Schmmgmt.dll from the command prompt or from the Run command on the Start menu.

To view or change the current schema master by using the Active Directory Schema console

  1. Open MMC, and then install the Active Directory Schema snap-in.

  2. Right-click Active Directory Schema , and then click Operations Master .

  3. The Current Operations Master that is displayed is the schema master. Click OK to leave it as is. – Or – Click Change to change the server that is the current FSMO Role Owner for the schema. If the current domain controller (the one that is listed in Current Focus ) is also the current operations master, you must use the Active Directory Tree console in MMC to focus on another domain controller before you can change the operations master.

After you have verified that the tool is focused on the current schema master, you can use it to add, modify, or deactivate attributes and classes. Remember that the account you are using must be a member of the Schema Administrators group and that the server must be set to allow schema modifications.

note-icon

Note

Schema objects that are part of the default base schema cannot be deactivated.