7.1 NetIQ Import Conversion Export Utility

Add Schema from a File

ICE can compare the schema in the source and destination. The source is a file or LDAP Server, and the destination is an LDAP server. The source schema file can be in either the LDIF or SCH format.

If you want to only compare the schema and not add the additional schema to the destination server, select the Do Not Add but Compare option. In this case, the additional schema is not added to the destination server but the differences between the schema are available to you as a link at the end of the operation.

Add Schema from a Server

The source and destination are LDAP servers.

If you want to only compare the schema and not add the additional schema to the destination server, select the Do Not Add but Compare option. In this case, the additional schema is not added to the destination server, but the differences between the schema are available to you as a link at the end of the operation.

ice general_options
-S[LDIF | LDAP | DELIM | LOAD | SCH] source_options
-D[LDIF | LDAP | DELIM] destination_options

ice -C schema_options
-S[LDIF | LDAP] source_options
-D[LDIF | LDAP] destination_options

General Options

General options affect the overall processing of the NetIQ Import Conversion Export engine.

Schema Options

The schema options let you use the schema cache to perform schema compare and update operations.

Source Handler Options

The source handler option (-S) determines the source of the import data. Only one of the following can be specified on the command line.

Destination Handler Options

The destination handler option (-D) specifies the destination of the export data. Only one of the following can be specified on the command line.

LDIF Source Handler Options

The LDIF source handler reads data from an LDIF file, then sends it to the NetIQ Import Conversion Export engine.

LDIF Destination Handler Options

The LDIF destination handler receives data from the NetIQ Import Conversion Export engine and writes it to an LDIF file.

LDAP Source Handler Options

The LDAP source handler reads data from an LDAP server by sending a search request to the server. It then sends the search entries it receives from the search operation to the NetIQ Import Conversion Export engine.

LDAP Destination Handler Options

The LDAP destination handler receives data from the NetIQ Import Conversion Export engine and sends it to an LDAP server in the form of update operations to be performed by the server.

For information about hashed password in an LDIF file, see Hashed Password Representation in LDIF Files.

DELIM Source Handler Options

The DELIM source handler reads data from a comma-delimited data file, then sends it to the destination handler.

DELIM Destination Handler Options

The DELIM destination handler receives data from the source handler and writes it to a comma-delimited data file.

SCH Source Handler Options

The SCH handler reads data from a legacy NDS or eDirectory schema file (files with a *.sch extension), then sends it to the NetIQ Import Conversion Export engine. You can use this handler to implement schema-related operations on an LDAP Server, such as extensions using a *.sch file as input.

The SCH handler is a source handler only. You can use it to import *.sch files into an LDAP server, but you cannot export *.sch files.

The options supported by the SCH handler are shown in the following table.

LOAD Source Handler Options

The DirLoad handler generates eDirectory information from commands in a template. This template file is specified with the -f argument and contains the attribute specification information and the program control information.

See the following sample attribute specification file:

givenname: $R(first)
initial: $R(initial)
sn: $R(last)
dn:cn=$A(givenname,%.1s)$A(initial,%.1s)$A(sn),ou=dev,ou=ds,o=novell
objectclass: inetorgperson
telephonenumber: 1-800-$N(1-999,%03d)-$C(%04d)
title: $R(titles)
locality: Our location

The format of the attribute specification file resembles an LDIF file, but allows some powerful constructs to be used to specify additional details and relationships between the attributes.

Syntax: $C[(<format)]

The optional <format specifies a print format that is to be applied to the value. Note that if no format is specified, the parenthesis cannot be used either:

$C
$C(%d) 
$C(%04d)

The plain $C inserts the current numeric value into an attribute value. This is the same as $C(%d) because “%d” is the default format that the program uses if none was specified. The numeric value is incremented after each object, so if you use $C multiple times in the attribute specification, the value is the same within a single object. The starting value can be specified in the settings file by using the !COUNTER=value syntax.

$N(<low-<high[,<format])]

<low and <high specify the lower and upper bounds, respectively, that are used as a random number is generated. The optional <format specifies a print format that is to be applied to a value from the list.

$N(1-999) 
$N(1-999,%d) 
$N(1-999,%03d)

$R(<filename[,<format])]

The <filename specifies a file that contains a list of values. This can be an absolute or relative path to a file. Several files containing the lists are included with this package. The values are expected to be separated by a newline character.

The optional <format specifies a print format that is to be applied to a value from the list.

$A(givenname)
$A(givenname,%s) 
$A(givenname,%.1s)

It is important to note that no forward references are allowed. Any attribute whose value you are going to use must precede the current attribute in the attribute specification file. In the example below, the cn as part of the DN is constructed from givenname, initial, and sn. Therefore, these attributes must precede the DN in the settings file.

givenname: $R(first)
initial: $R(initial)
sn: $R(last) dn:o=novell,ou=dev,ou=ds,cn=$A(givenname,%.1s)$A(initial,%.1s)$A(sn)

The DN receives special handling in the LDIF file: no matter what the location of DN is in the settings, it will be written first (as per LDIF syntax) to the LDIF file. All other attributes are written in the order they appear.

!COUNTER=300
!OBJECTCOUNT=2
!CYCLE=title
!UNICYCLE=first,last
!CYCLE=ou,BLOCK=10

Performing an LDIF Import

To perform an LDIF import, combine the LDIF source and LDAP destination handlers, for example:

ice -S LDIF -f entries.ldif -D LDAP ‑s server1.acme.com -p 389 -d cn=admin,c=us -w secret

This command reads LDIF data from entries.ldif and sends it to the LDAP server server1.acme.com at port 389 using the identity cn=admin,c=us, and the password “secret.”

Performing an LDIF Export

To perform an LDIF export, combine the LDAP source and LDIF destination handlers. For example:

ice -S LDAP -s server1.acme.com -p 389 -d cn=admin,c=us ‑w password -F objectClass=* -c sub -D LDIF ‑f server1.ldif

This command performs a subtree search for all objects in the server server1.acme.com at port 389 using the identity cn=admin,c=us and the password “password” and outputs the data in LDIF format to server1.ldif.

Performing a Comma-Delimited Import

To perform a comma-delimited import, use a command similar to the following:

ice -S DELIM -f/tmp/in.csv -F /tmp/order.csv -ncn -lo=acme -D LDAP -s server1.acme.com -p389 -d cn=admin,c=us -w secret

This command reads comma-delimited values from the /tmp/in.csv file and reads the attribute order from the /tmp/order.csv file. For each attribute entry in in.csv, the attribute type is specified in order.csv. For example, if in.csv contains

pat,pat,engineer,john

then order.csv would contain

dn,cn,title,sn

The information in order.csv could be input directly using the -t option.

The data is then sent to the LDAP server server1.acme.com at port 389 using the identity cn=admin,c=us, and password “secret”.

This example specifies that cn should become the new DN for this object using the -n option, and this object was added to the organization container acme using the -l option.

Comma-delimited files generated using NetIQ Import Conversion Export utility have the template used for generating them in the first line. To specify that first line in the delimited file is the template, use the -k option. If -F or -t is used with -k, the template specified should be consistent with that in the delimited file, where both have exactly the same attributes. However, the number of occurrences and the order of appearance of each attribute can differ. In the above example, in.csv contains

dn,cn,title,title,title,sn in the first line. The following templates are consistent and can be used with -t or -F when -k is used:

dn,cn,title,sn (number of repetitions of attribute title differs)

dn,sn,title,cn (order of attributes differ)

However, the following are not consistent with the template in in.csv and hence cannot be specified with -t or -F when -k is used:

dn,cn,title,sn,objectclass (new attribute objectclass)

dn,cn,title (missing attribute sn)

Performing a Comma-Delimited Export

To perform a comma-delimited export, use a command similar to the following:

ice -S LDAP -s server1.acme.com -p 389 -d cn=admin,c=us ‑w password -F objectClass=* -c sub -D DELIM -f /tmp/server1.csv -F order.csv

This command performs a subtree search for all objects in the server server1.acme.com at port 389 using the identity cn=admin,c=us and the password “password” and outputs the data in comma-delimited format to the /tmp/server1.csv file.

If any attribute in the order.csv has multiple values, /tmp/server1.csv, the number of columns for this attribute equals maximum number of values for the attribute. If an attribute repeats in order.csv, the number of columns for this attribute equals the number of times the attribute repeats.

For example, if order.csv contains dn,sn,objectclass, and objectclass has 4 values, whereas dn and sn have only 1 value for all the entries exported, dn and sn would have 1 column each, whereas objectclass would have 4 columns. If you want only 2 values for objectclass to be output to the delimited file, order.csv should contain dn,sn,objectclass,objectclass.

In both cases the attributes are written to the /tmp/server1.csv in the first line. In the first case, /tmp/server1.csv would have dn,sn,objectclass,objectclass,objectclass,objectclasss in the first line of /tmp/server1.csv, and in the second case, it would have dn,sn,objectclass,objectclass.

To prevent the first line to be treated as a sequence of attributes during a subsequent import, use the -k option. See Performing a Comma-Delimited Import for more information.

Performing a Data Migration between LDAP Servers

To perform a data migration between LDAP servers, combine the LDAP source and LDAP destination handlers. For example:

ice -S LDAP -s server1.acme.com -p 389 -d cn=admin,c=us ‑w password -F objectClass=* -c sub -D LDAP ‑s server2.acme.com -p 389 -d cn=admin,c=us -w secret

This command performs a subtree search for all objects in the server server1.acme.com at port 389 using the identity cn=admin,c=us and the password “password” and sends it to the LDAP server server2.acme.com at port 389 using the identity cn=admin,c=us and the password “secret.”

Performing a Schema Import

To perform a schema file import, use a command similar to the following:

ice -S SCH -f $HOME/myfile.sch -D LDAP -s myserver -d cn=admin,o=novell -w passwd

This command reads schema data from myfile.sch and sends it to the LDAP server myserver using the identity cn=admin,o=novell and the password “passwd.”

Performing a LOAD File Import

To perform a LOAD file import, use a command similar to the following:

ice -S LOAD -f attrs -D LDIF -f new.ldf

In this example, the contents of the attribute file attrs is as follows:

#===================================================================== 

#  DirLoad 1.00
#=====================================================================

!COUNTER=300 

!OBJECTCOUNT=2
#-----------------------------------------------------------------------

#  ATTRIBUTE TEMPLATE
# --------------------------------------------------------------------

objectclass: inetorgperson 

givenname: $R(first) 

initials: $R(initial) 

sn: $R(last) 

dn: cn=$A(givenname,%.1s)$A(initial,%.1s)$A(sn),ou=$R(ou),ou=dev,o=novell,

telephonenumber: 1-800-$N(1-999,%03d)-$C(%04d) 

title: $R(titles)

Running the previous command from a command prompt produces the following LDIF file:

version: 1

dn: cn=JohnBBill,ou=ds,ou=dev,o=novell 

changetype: add 

objectclass: inetorgperson 

givenname: John 

initials: B 

sn: Bill 

telephonenumber: 1-800-290-0300 

title: Amigo 

dn: cn=BobJAmy,ou=ds,ou=dev,o=novell 

changetype: add 

objectclass: inetorgperson 

givenname: Bob 

initials: J 

sn: Amy 

telephonenumber: 1-800-486-0301 

title: Pomo

Running the following command from a command prompt sends the data to an LDAP server via the LDAP Handler:

ice -S LOAD -f attrs -D LDAP -s www.novell.com -d cn=admin,o=novell -w admin

If the previous template file is used, but the following command is used, all of the records that were added with the above command will be deleted.

ice -S LOAD -f attrs -r -D LDAP -s www.novell.com -d cn=admin,o=novell -w admin

If you want to use -m to modify, the following is an example of how to modify records:

# ====================================================================== 

#  DirLoad 1.00

# ====================================================================== !COUNTER=300

!OBJECTCOUNT=2

#---------------------------------------------------------------------- 

#  ATTRIBUTE TEMPLATE

# ---------------------------------------------------------------------- 

dn: cn=$R(first),%.1s)($R(initial),%.1s)$R(last),ou=$R(ou),ou=dev,o=novell

delete: givenname

add: givenname

givenname: test1 

replace: givenname

givenname: test2 

givenname: test3

If the following command is used where the attrs file contains the data above:

ice -S LOAD -f attrs -m -D LDIF -f new.ldf

then the results would be the following LDIF data:

version: 1 

dn: cn=BillTSmith,ou=ds,ou=dev,o=novell 

changetype: modify

delete: givenname

-

add: givenname

givenname: test1

-

replace: givenname

givenname: test2 

givenname: test3 

-

dn: cn=JohnAWilliams,ou=ldap,ou=dev,o=novell 

changetype: modify

delete: givenname

-

add: givenname

givenname: test1

-

replace: givenname

givenname: test2 

givenname: test3 

-

Performing an LDIF Export from LDAP server having encrypted attributes

To perform an LDIF export from LDAP server having encrypted attributes, combine the LDAP source and LDIF destination handlers along with the scheme and password for encryption, for example:

ice -S LDAP -s server1.acme.com -p 636 -L cert-server1.der -d cn=admin,c=us -w password -F objectClass=* -c sub -D LDIF -f server1.ldif -e des -E secret

Performing an LDIF Import having encrypted attributes

To perform an LDIF import of a file having attributes encrypted by ICE previously, combine the LDIF source with the scheme and password used previously for exporting the file and LDAP destination handlers, for example:

ice -S LDIF -f server1.ldif -e des -E secret -D LDAP -s server2.acme.com -p 636 -L cert-server2.der -d cn=admin,c=us -w password

Schema Mapping Rules

The <attr-name-map> element is the top-level element for the schema mapping rules. Mapping rules determine how the import schema interacts with the export schema. They associate specified import class definitions and attributes with corresponding definitions in the export schema.

Mapping rules can be set up for attribute names or class names.

The following is the formal DTD definition of schema mapping rules:

<!ELEMENT attr-name-map (attr-name | class-name)*>

<!ELEMENT attr-name (nds-name, app-name)>
<!ATTLIST attr-name 
          class-name    CDATA    #IMPLIED>

<!ELEMENT class-name (nds-name, app-name)>

<!ELEMENT nds-name (#PCDATA)>

<!ELEMENT app-name (#PCDATA)>

You can have multiple mapping elements in the file. Each element is processed in the order that it appears in the file. If you map the same class or attribute more than once, the first mapping takes precedence.

The following examples illustrate how to create a schema mapping rule.

<attr-name-map>
   <attr-name class-name="inetOrgPperson">
      <nds-name>surname</nds-name>
      <app-name>sn</app-name>
   </attr-name>
</attr-name-map>

<attr-name-map>
   <class-name>
      <nds-name>inetOrgPerson</nds-name>
      <app-name>User</app-name>
   </class-name>
</attr-name-map>

<attr-name-map>
   <attr-name>
      <nds-name>surname</nds-name>
      <app-name>sn</app-name>
   </attr-name>
   <class-name>
      <nds-name>inetOrgPerson</nds-name>
      <app-name>User</app-name>
   </class-name>
</attr-name-map>

ice -o -sfile://sr1.xml -SLDIF -f1entry.ldf -c -DLDIF 
-foutt1.ldf

Create Rules

Create rules specify the conditions for creating a new entry in the destination directory. They support the following elements:

The following is the formal DTD definition for create rules:

<!ELEMENT create-rules (create-rule)*>

<!ELEMENT create-rule (match-attr*, 
                       required-attr*, 
                       template?) >
<!ATTLIST create-rule 
          class-name    CDATA   #IMPLIED
          description   CDATA   #IMPLIED>

<!ELEMENT match-attr    (value)+ >
<!ATTLIST match-attr
          attr-name      CDATA    #REQUIRED>

<!ELEMENT required-attr (value)*>
<!ATTLIST required-attr 
          attr-name     CDATA   #REQUIRED>

<!ELEMENT template EMPTY>
<!ATTLIST template
          template-dn   CDATA   #REQUIRED>

You can have multiple create rule elements in the file. Each rule is processed in the order that it appears in the file. If a record does not match any of the rules, that record is skipped and the skipping does not generate an error.

The following examples illustrate how to format create rules.

<create-rules>
   <create-rule class-name="inetOrgPerson">
      <required-attr attr-name="givenName"/>
      <required-attr attr-name="surname"/>
      <required-attr attr-name="L">
         <value>Provo</value>
      </required-attr>
   </create-rule>
</create-rules>

<create-rules>
   <create-rule>
      <required-attr attr-name="givenName"/>
      <required-attr attr-name="Surname"/>
      <required-attr attr-name="L">
         <value>Provo</value>
      </required-attr>
   </create-rule>
</create-rules>

<create-rules>
   <create-rule>
      <match-attr attr-name="uid">
         <value>cn=ratuid</value>
      </match-attr>
      <required-attr attr-name="L">
         <value>Provo</value>
      </required-attr>
   </create-rule>
</create-rules>

ice -o -cfile://cr1.xml -SLDIF -f1entry.ldf -c -DLDIF 
-foutt1.ldf

Placement Rules

Placement rules determine where an entry is created in the destination directory. They support the following conditions for determining whether the rule should be used to place an entry:

The last element in the rule specifies where to place the entry. The placement rule can use zero or more of the following:

The following is the formal DTD definition for the placement rule:

<!ELEMENT placement-rules (placement-rule*)>
<!ATTLIST placement-rules
          src-dn-format    (%dn-format;)   "slash"
          dest-dn-format   (%dn-format;)   "slash"
          src-dn-delims    CDATA           #IMPLIED
          dest-dn-delims   CDATA           #IMPLIED>

<!ELEMENT placement-rule (match-class*,
                          match-path*,
                          match-attr*,
                          placement)>
<!ATTLIST placement-rule
          description      CDATA            #IMPLIED>

<!ELEMENT match-class      EMPTY>
<!ATTLIST match-class
          class-name       CDATA            #REQUIRED>

<!ELEMENT match-path       EMPTY>
<!ATTLIST match-path
          prefix           CDATA            #REQUIRED>

<!ELEMENT match-attr       (value)+ >
<!ATTLIST match-attr
          attr-name        CDATA            #REQUIRED>

<!ELEMENT placement        (#PCDATA | 
                           copy-name | 
                           copy-attr | 
                           copy-path | 
                           copy-path-suffix)* >

You can have multiple placement-rule elements in the file. Each rule is processed in the order that it appears in the file. If a record does not match any of the rules, that record is skipped and the skipping does not generate an error.

The following examples illustrate how to format placement rules. The scr-dn-format="ldap" and dest-dn-format="ldap" attributes set the rule so that the name space for the DN in the source and destination is LDAP format.

The NetIQ Import Conversion Export utility supports source and destination names only in LDAP format.

<placement-rules src-dn-format="ldap" dest-dn-format="ldap">
    <placement-rule> 
       <match-class class-name="inetOrgPerson"></match-class>
       <placement>cn=<copy-name/>,o=test</placement> 
    </placement-rule> 
 </placement-rules>

With this rule, a record with a base class of inetOrgPerson and with the following DN:

dn: cn=Kim Jones, ou=English, ou=Humanities, o=UofZ

would have the following DN in the destination directory:

dn: cn=Kim Jones, o=test

<placement-rules src-dn-format="ldap" dest-dn-format="ldap">
    <placement-rule> 
       <match-attr attr-name="sn"></match-attr> 
       <placement>cn=<copy-name/>,o=test</placement> 
    </placement-rule> 
 </placement-rules>

With this rule, a record with the following dn and sn attribute:

dn: cn=Kim Jones, ou=English, ou=Humanities, o=UofZ
sn: Jones

would have the following DN in the destination directory:

dn: cn=Kim Jones, o=test

<placement-rules src-dn-format="ldap" dest-dn-format="ldap">
  <placement-rule> 
    <match-attr attr-name="sn"></match-attr> 
    <placement>cn=<copy-attr attr-name="sn"/>,o=test</placement>
  </placement-rule> 
</placement-rules>

With this rule, a record with the following dn and sn attribute:

dn: cn=Kim Jones, ou=English, ou=Humanities, o=UofZ
sn: Jones

would have the following DN in the destination directory:

dn: cn=Jones, o=test

<placement-rules src-dn-format="ldap" dest-dn-format="ldap">
    <placement-rule> 
       <match-attr attr-name="sn"></match-attr> 
       <placement><copy-path/></placement> 
    </placement-rule> 
 </placement-rules>

<placement-rules src-dn-format="ldap" dest-dn-format="ldap">
    <placement-rule> 
       <match-attr attr-name="sn"></match-attr> 
       <placement><copy-path-suffix/>,o=test</placement> 
    </placement-rule> 
 </placement-rules>

With this rule, a record with the following dn and sn attribute:

dn: cn=Kim Jones, ou=English, ou=Humanities, o=UofZ
sn: Jones

would have the following DN in the destination directory:

dn: cn=Kim Jones, ou=English, ou=Humanities, o=UofZ, o=test

<placement-rules>
 <placement-rule>
  <match-path prefix="o=engineering"/>
  <placement><copy-path-suffix/>o=neworg</placement>
 </placement-rule>
</placement-rules>

For example:

dn: cn=bob,o=engineering

becomes

dn: cn=bob,o=neworg

ice -o -pfile://pr1.xml -SLDIF -f1entry.ldf -c -DLDIF 
-foutt1.ldf