Importing and Exporting Modifying Directory Objects

Importing and Exporting Modifying Directory Objects

By default, every Windows 2000- or Windows .NET-based domain controller contains two utilities installed — LDIF Directory Exchange (LDIFDE.exe) and CSV Directory Exchange (CSVDE.exe) — that are primarily intended for bulk operations. Unlike Ds* family tools (DsQuery.exe, DsAdd.exe, DsMod.exe, etc.), these utilities can save results in a file for consequent operations and read data from a file. You can use these utilities to:

  • Export Active Directory information to a text file (in LDIF or CSV format) that can be easily viewed or/and edited. The retrieved information can be used for:

    • Composing documentation on directory objects

    • Performing bulk editing operations that cannot be carried out using the standard administrative snap-ins

    • Creating templates for new users (if the standard option of copying user accounts is not convenient for you)

    • Migrating directory objects between domains into the same or another domain forest

    • Backing up the existing domain configuration (for safety or for re-installation of domain controllers)

  • Import Active Directory information from a file. This means creating new objects or modifying the attributes of existing ones in batch mode. Besides the already mentioned export operations that imply import — bulk editing, migrating, backing up, and creating user templates — the import into Active Directory can be carried out for:

    • Deploying a pre-configured domain configuration (by the way, import is performed when a domain controller is promoted — the CSVDE utility is used for creating the "default" Active Directory structure)

    • Deploying Active Directory-based applications (extending the schema is also possible)

    Note 

    Normally, the standard Backup utility is used for backing up and restoring Active Directory. However, in some cases, export/import may be a preferable choice for preserving domain configuration.

You can select either of these utilities for your tasks so long as you keep in mind the two main differences between LDIFDE and CSVDE for a user.

  • Data format — LDIFDE uses files that respond to the LDIF standard, whereas CSVDE supports the CSV format (see the appropriate section on each tool).

  • Possible operations — CSVDE can only export and import (create) data; LDIFDE also allows you to modify attributes and delete objects.

The book contains a few examples of how to use LDIFDE and CSVDE. These examples can be tested with either utility, depending on your specific requirements.

All of the tasks listed can also be fulfilled (and often, more effectively!) with custom ADSI scripts. Knowing the possibilities and restrictions of all the tools permits you to save time and select the appropriate tool for a specific task.

Basic information on the LDIFDE and CSVDE utilities is contained in the Help and Support Center (search for "LDIFDE CSVDE"). (The -u parameter is missing in the Help!) You can also run the utilities without parameters and get help information.

Error Logs 

Both utilities create an error log file (csvde.err or ldif.err) and a log for completed operations (csvde.log or ldif.log). By default, these files are stored in the current folder, and the logs' location is configured.

Parameters

Table 12.1 lists some of the most frequently used parameters of both utilities – LDIFDE and CSVDE.

Table 12.1: Some Parameters of the LDIFDE and CSVDE Utilities

Parameter

Description and comments

Meaning (or value) if the parameter is omitted(default)


Common parameters

f

Input or output filename. "f con" can be used for output to the console. Required parameter

No

s

DC name

The name of the DC the user is currently logged on to

t

Port number. The Global Catalog port (3268) can also be used

389 (LDAP)

u

Use Unicode format

ANSI format is used


Parameters for export operations

d

Search base

Domain naming context

c

Replace all occurrences of string 1 with string 2. Very helpful for copying data from one domain to another

No

r

Search filter

(objectClass=*)

p

Search scope

Subtree

l

Selection. A list of attributes. "1.1" or empty string can be used with the meaning of "no attributes returned" (if you need only a list of objects)

All attributes

o

The list of attributes omitted during an export operation

No


Parameters for import operations

i

Specifies import mode

Export mode

k

Skip errors. If some objects were successfully imported to the directory and others weren't, you may correct errors in the import file and continue its processing

No

Note 

Do not forget about the omitted parameters (which have default values), or you may obtain an undesirable or unpredictable result. Compare, for example, cases when you only want to export OU objects and when you need to export an entire OU subtree (default).

Exporting and Re-Importing Objects

Export operations are usually successful. (The worst-case scenario is when an export file does not contain all the objects you expect it to contain.) You need only take into consideration the following: when you specify a list of attributes (by using the l parameter) in the export command, LDIFDE and CSVDE do not include any information about non-defined attributes in the output file. Therefore, you might need to manually include the attributes' names (if you need them) in the import file and as-sign the appropriate values.

Note 

It is not possible to export security descriptors (or group policies — for domains and/or OUs). You must also be careful about built-in and default groups, such as Domain Users.

In the exported file, you may see a list of members different from the one that the Active Directory Users and Computers snap-in displays.

The (givenName=*) filter allows you to choose only accounts of newly created users, with the exception of built-in accounts. Built-in users (administrator, guest, etc.) do not have given names.

While exporting information from Global Catalog (using the 3268 port), do not forget that GC contains a restricted set of attributes. For example, 40-50 attributes (a very modest value, since the minimum is about 30 attributes and maximum is about two hundred) are exported for a user object by default. When GC is used, only 20-30 attributes are exported.

The number and type of the objects exported depend on a combination of the search base and the LDAP filter (described in detail in Chapter 1, "LDAP Basics"). You can export either a single directory object or all Active Directory objects. The choice of the appropriate search base and filter is not a challenge unless you do not use both or you have forgotten about the default values. The following two commands might seem equivalent since either can export a computer account (provided that the computer's cn attribute has a unique value in the domain):

   ldifde -f Export. ldf -d "CN=Comp1, OU=Staff, DC=net, DC=dom"   ldifde -f Export.ldf -r "(&(objectCategory=computer) (cn=Comp1))   

In fact, the first command can export a few objects, and the second exports strictly one object. In both cases, the omitted p parameter (the scope of the search) means that the search will be conducted in the subtree. Since the computer object is a container and can have child objects, the first command exports the entire "family". The second command finds the specified computer in the domain and exports it alone (since there is no computer with such a name in the domain).

After a little practice with search base and filters, you will learn how select only the necessary objects from Active Directory in the most effective and precise way. (See more examples of command string in this chapter.)

Note 

I prefer to specify objectCategory in filters rather than objectClass. Both attributes are replicated in Global Catalog. However, the former attribute is indexed, and the latter is not. As a result, filters with objectCategory are more effective.

There is, however, a pitfall to such an approach. (objectCategory=Person) defines users as well as contacts. Consequently, you need to add the objectClass attribute in the filter. Test your filters carefully before using them in real conditions.

Errors are more frequent when import operations are performed. There are three main sources of errors.

  • Read-only attributes, which only the system can change. A typical error message: ‘Unwilling To Perform. The server side error is "Access to the attribute is not permitted because the attribute is owned by the Security Accounts Manager (SAM)."’ You cannot include such attributes as objectSID, objectGUID, etc., in the import files and must always use the m parameter while exporting objects if a consequent import is planned. When the m parameter is specified, all of the SAM attributes are ignored (see also "Working with User Objects" later in this chapter).

  • Missed mandatory attributes. Refer to Table 12.2 to see which attributes must be defined in import files when new directory objects are created. The objectSID attribute is shown in bold to remind you that, notwithstanding the fact that it is a mandatory attribute, it must not be used in import.

    Table 12.2: Some Important Object Classes and Their Mandatory Attributes

    Object class (category)

    Mandatory attributes


    computer (Computer)

    cn, instanceType, objectCategory, objectClass, objectSIDsA-MAccountName

    group (Group)

    cn, group Type, instanceType, objectCategory, objectClass, objectSID, sAMAccountName

    organizationalUnit (Organizational-Unit)

    instanceType, objectCategory, objectClass, ou

    printQueue (Print-Queue)

    cn, instanceType, objectCategory, objectClass, printerName, serverName, shortServerName, uNCName, versionNumber

    user (Person)

    cn, instanceType, objectCategory, objectClass, objectSID, sAMAccountName

    volume (Volume)

    cn, instanceType, objectCategory, objectClass, uNCName

  • Violations of syntax rules, inconsistency of attribute values, values of wrong types, or values out of range. For example, using the c parameter may result in incorrect values of naming attributes (see later in the chapter). If you are creating new objects from scratch, carefully verify attribute types and values, and refer to the abstract schema and schema container if needed (see also the schema description in Chapter 16, "Active Directory Service Interfaces (ADSI)").

When directory objects are copied (exported and imported) from one domain to another, it is helpful to use the c parameter.

Unicode Support

LDFIDE and CSVDE have some problems with support of Unicode (namely, with non-Latin localized string values). You should take this into consideration if non-Latin values are stored in your Active Directory. Test your installation before starting the bulk import/export operations. Since such values aren't written in the output file in plain text format, it is hard to edit them. Encoding restrictions of the utilities are listed below.

LDIFDE

  • Unless the u parameter is specified, LDIFDE exports non-Latin Unicode values as Base64-encoded (e.g., cn:: 0JLQsNGB0Y=). (Notice that the colon character is doubled in such lines. Binary values are always encoded.) If non-Latin characters are included in the distinguished name of a directory object, the entire line (dn) name is coded. You can safely reimport all these values.

  • LDIFDE correctly imports non-Latin string values in an input file if only this file is saved as Unicode-encoded. Use common format with one colon!

CSVDE

  • Regardless of the presence of the u parameter, CSVDE exports non-Latin Unicode (and binary) values (except for dn) in the following format: X'8c39c3bc'. You can safely reimport these values. CSVDE fails to export directory objects that have non-Latin characters in their names if the u parameter has been omitted.

  • CSVDE imports the non-Latin string values in an input file (in usual format) if this file is saved both as Unicode- and ANSI-encoded. Windows 2000-version of CSVDE accepts only Unicode-encoded files.

LDIF Directory Exchange Utility (LDIFDE) (Sys)

LDIFDE, a command-line utility that is installed by default on every DC, can be used for adding, modifying, renaming, and deleting directory objects. This utility uses LDAP Data Interchange Format (LDIF) — an Internet standard that defines a file format to perform batch operations for LDAP-accessible directories. LDIFDE is also a preferred tool for extending the Active Directory schema.

Examples of LDIF files are shown below. LDIFDE can be run on any Windows 2000/XP/.NET-based client, provided you have supplied appropriate domain credentials.

Working with User Objects

Table 12.3 is a snippet of an export file and lists all attributes of an exported user object in LDIF format. Notice attributes in bold face, which are not exported when the m parameter is specified, and should not be imported. Notice also that the objectGUID and objectSID are exported as binary values (this is marked with a double colon). A few additional remarks are placed at the end of the table. These are not all of the possible attributes, only a typical minimal set. The names of some attributes as they are presented in the Active Directory Users and Computers snap-in's UI are specified in bold square brackets. The relative DN (RDN) is also specified, although it is not presented in the UI and cannot be directly modified. The mandatory attributes are show in italics.

Table 12.3: Influence of m Parameter on the Resulting Attribute List

Exported attributes and their values


 dn:   CN=John Smith, OU=Staff, DC=net, DC=dom changetype: add accountExpires:   9223372036854775807 badPasswordTime: 0   badPwdCount: 0    [**]cn: John Smith codePage: 0   countryCode: 0 displayName: John Smith [Display   name] distinguishedName: CN=John Smith, OU=Staff, DC=net, DC=dom   givenName: John [First name] homeDirectory:   \\netdc1\UsersData\jsmith homeDrive: W:   [**]instanceType: 4   lastLogoff: 0 lastLogon: 0 logonCount: 0 memberOf:   CN=Account Operators, CN=Builtin, DC=net, DC=dom memberOf: CN=Server Operators, CN=Builtin, DC=net,   DC=dom name: John Smith [**]objectCategory: CN=Person,   CN=Schema, CN=Configuration, DC=net, DC=dom    [*]objectClass:   organizationalPerson [*]objectClass: person   [*]objectClass: top      [*]objectClass: user   objectGUID:: pME9k/0HNk+lz9/kJBpp3g==   [**]objectSid::   AQUAAAAAAAVAAAAL9Xsbd3o5ByKpzI/UgQAAA== primaryGroupID: 513 profilePath:   \\netdc1\Profiles\jsmith pwdLastSet:   126609470367623296 [*]sAMAccountName: JSmith   [User logon name (pre-Windows 2000]   sAMAccountType: 805306368 scriptPath:   Users\Logons.vbs sn: Smith [Last name]    [***]userAccountControl: 512   userPrincipalName: JSmith@net [User logon   name]    [****]uSNChanged: 5950   [****]uSNCreated: 4194   [****]whenChanged:   20020320164127.0Z [****]whenCreated: 20020318174356.0Z   

[**]these attributes are mandatory for a user object, but are not required for an import operation since the system itself creates the corresponding values.

[*]these attributes are required for importing (creating) objects. To create a new user, it is sufficient to specify the objectClass and sAMAccountName attributes. Other objects will require some additional attributes (see Table 12.2).

[***]if this string is included in an import file, the new user will have to change his or her password at first logon; otherwise the new account will be disabled.

[****]these attributes are exported, too, with the m parameter, but it makes absolutely no sense to import them.

Here is a sample command string that allows you to export the specified attributes of all users (except for built-in accounts) from your current domain:

  ldifde -f  ExportedUSERs.ldf -r  "(&(objectCategory=Person) (objectClass=user)  (givenName=*))" -l  "cn, givenName, objectClass, sAMAccountName" 

Working with Container Objects (Domains and OUs)

When working with container objects, you must always remember that the combination of the search base and the LDAP filter defines the result of the operation: either you export only container objects of the specified type, or you export an entire container.

Compare, for example, the following two commands. The first command exports all OU objects from the current domain (remember the default values for the omitted l, d, and p parameters):

  ldifde -f ExportedOUs.ldf -r "objectCategory=OrganizationalUnit" -v 

The second command exports an entire subtree, i.e., all objects (of any type), from the specified OU:

 ldifde  -f ExportedOU.ldf -d "OU=Staff,  DC=net, DC=dom" -v 

Extending the Schema

LDIFDE is the tool recommended by Microsoft for extending the schema (however, using CSVDE is also possible). (The requirements of the schema extension are described in Chapter 16, "Active Directory Service Interfaces (ADSI).") Remember that you must generate the base OID for your own attributes and classes before executing a similar command. The following is an example of an LDIF import file, which creates a string attribute with stringAttribute LDAP display name:

 dn:  CN=String Attribute, CN=Schema, CN=Configuration, DC=net,  DC=dom changetype: add attributeID: 1.2.840.113556.1.4. ... .1 attributeSyntax:  2.5.5.12 cn: String Attribute isSingleValued: TRUE objectCategory:  CN=Attribute-Schema, CN=Schema, CN=Configuration, DC=net, DC=dom objectClass:  attributeSchema oMSyntax: 64 

A successful command output is similar to the following (netdc1.net.dom is the name of the DC that is the schema master):

 C:\>ldifde -i -f AddStrAttr.ldf Connecting to  "netdc1.net.dom" Logging in as current user using SSPI Importing directory from file  "AddStrAttr.ldf" Loading entries.. 1 entry modified successfully.  The command has completed successfully 

Modifying Attribute Values. Deleting Objects

Only the LDIFDE utility can be used for batch modifying Active Directory objects from a command file. (Remember also the DsMod.exe utility!) To change (or set) one or more attribute values of an object (or a number of objects) use the following procedure:

  1. Export the necessary object(s) to a file. Use the appropriate filters. You may export all attributes or specific ones only. This step is optional — you may create the import file manually from scratch.

  2. Edit the export file. Delete the entries for unnecessary (unchanged) attributes. Change changetype from add to modify. Replace each attribute entry with the following lines:

     replace: <attributeName> <attributeName>:   <newValue> 

    If the second line is omitted, the attribute value will be cleared. The "" (minus) character must follow the lines for each attribute (including the last one). An empty line must precede each attribute's distinguished name (excluding the first one). Let us illustrate these requirements with an example. The sample import file is used for modifying attributes of two user objects (the comments in bold square brackets are not really included in the file!).

     dn: CN=user3, OU=Staff,   DC=net, DC=dom changetype: modify   replace: description description: A test user   - replace: scriptPath scriptPath:   Users\Logons.vbs - [This empty line is   mandatory] dn: CN=user4, OU=Staff, DC=net, DC=dom   changetype: modify replace: description   description: A user - [All "-" characters are   mandatory] 
  3. Import the edited file. The import is performed until the first error, but you can safely repeat it as many times as you wish while correcting errors.

By modifying attribute values, you can also change membership in a group(s). To add a user to a group, use lines similar to the following:

 dn: CN=GroupName, OU=Staff,  DC=net, DC=dom changetype: modify  replace: member member: CN=user2, OU=Staff,  DC=net, DC=dom 
Note 

If LDIFDE.exe does not meet your specific needs, write a custom script (see Chapter 17, "Scripting Administrative Tasks"). This (if you are familiar with ADSI scripting) will not take more time than editing a file. In addition, the scripts are much more flexible as well as reusable. For example, you need to re-do the export and/or edit the export-import file each time a user is added (deleted), whereas the same script can modify the specified attributes for any number of users in a container.

To delete a leaf object, it is sufficient to include the following two lines into the import file:

 dn: CN=user2, OU=Staff, DC=net,  DC=dom changetype: delete 

You cannot delete a container if it has child objects. The LDAP protocol, actually, allows you to delete a subtree (see the Ldp.exe tool description earlier in this chapter), but LDIFDE does not permit one to perform such an operation.

CSV Directory Exchange Utility (Sys)

CSVDE uses the Comma-Separated Value (CSV) file format (with a .csv extension). Files in this format can easily be viewed (imported) or prepared (edited and exported) by using various applications, including Microsoft Excel. The first line in such files contains the names of attributes, separated by a comma. The next lines contain the values of attributes, one line per object. An example of such a file is shown in the next section.

Working with Unicode String Values

Let us discuss the problem of Unicode support in an example with the CSVDE utility. The following command exports the minimal set of OUs' attributes that allow you to import the OU structure to another domain:

  csvde -f ExportedOUs.csv -r "(objectCategory=OrganizationalUnit)" -1  "objectClass, ou" -v -u  

Note 

If all attributes are to be exported (no l parameter used), add the m parameter to the command.

On the screen, the command produces an output (thanks to the verbose mode) similar to the following:

 Connecting to "(null)" Logging  in as current user using SSPI Exporting directory to file ExportedOUs.csv  Searching for entries ... Writing out entries Exporting entry: "OU=Domain  Controllers, DC=net, DC=dom" ... Exporting entry: "OU=epcoHaΠ, DC=net,  DC=dom" Export Completed. Post-processing in progress... 7 entries exported The  command has completed successfully 

Notice the non-Latin string in an OU's name (OU=epcoHaΠ,). If the u parameter has not been specified, the command results in an error (which is also written to the csv.err file):

 Error writing  to file. This error happens when the entry cannot be written, it can be caused  by writing a Unicode value to a non-unicode file. An error has occurred in the  program 

Here is the exported CSV-file produced by the command (the first line contains the attributes' names):

 DN,  objectClass, ou "OU=Domain Controllers, DC=net, DC=dom", organizationalUnit,  Domain Controllers ... "OU=OU=epcoHaΠ, DC=net, DC=dom", organizationalUnit,  X'd09fd0b5d180d18 1d0bed0bdd0b0d0bb'  

Notice that the last line contains a coded value for the ou attribute.

Caution 

If you create an import file with non-Latin Unicode values from scratch, do not forget to save it in Unicode format (not in ANSI) and use the -u parameter when importing the file.

Exporting Information for Successive Import

As mentioned before, some attributes that are present or incorrectly (inconsistently) specified in an import file may cause an error. Here are two frequently encountered errors that are reported on in import operations:

 Add error on  line 2: Unwilling To Perform The server side error is "The modification was not  permitted for security reasons." 0 entries modified successfully. An error has  occurred in the program 

The following error specifies that you want to import an attribute(s) that only the system can change:

 Add error on  line 3: Constraint Violation The server side error is "Access to the attribute  is not permitted because the attribute is owned by the Security Accounts  Manager (SAM)." 

If you encounter such an error, use the m parameter for export, and if the error still exists, check the import file for consistency. Try to get rid of "unnecessary" attributes when doing export. Let us look at a situation where you yourself produce a critical error by using the c parameter.

The scenario is the following. Suppose that you want to copy an entire OU from one domain (net.dom) to another (subdom.net.dom) and rename the OU at the same time. You use the c OU=Personnel OU=Staff, DC=subdom parameter to change the source DN OU=Personnel,DC=net,DC=dom to the destination DN OU=Staff,DC=subdom,DC=net,DC=dom. The problem is that the ou attribute will not be changed by such a replace operation, and will remain the same. As a result, an inconsistency in the dn and ou attributes has occurred. You can only solve the problem by omitting the ou attribute when exporting. The sIDHistory attribute presented in the import file will also prevent you from successfully importing. The following command meets all requirements and may perform the desired action:

  csvde -f Subtree.csv -d  OU=Personnel,DC=net,DC=dom -c OU=Personnel  OU=Staff,DC=subdom -o ou, sidhistory -m -v 

If the OU being copied contains computer accounts, you can copy them by using the following command (or add the primaryGroupID attribute in the list of omitted attributes in the previous command):

  csvde -f Comp.csv -d OU=Personnel,DC=net,DC=dom -r "objectCategory=Computer" -c  OU=Personnel OU=Staff, DC=subdom -o primaryGroupID -m -v 

Caution 

Note that the memberOf attribute is not exported, so you may need to verify (and reestablish) all group memberships of the imported accounts. To add users to a group(s), you can use the AddUsers.exe command from Windows 2000 Resource Kit or Windows .NET system utility DsMod.exe (see Chapter 8, "Common Administrative Tasks").



Windows  .NET Domains & Active Directory
Windows .NET Server 2003 Domains & Active Directory
ISBN: 1931769001
EAN: 2147483647
Year: 2002
Pages: 154

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net