5.2 Debugging LDIF Files

If you have problems with an LDIF file, consider the following:

5.2.1 Enabling Forward References

You might occasionally encounter LDIF files in which a record to add one entry comes before a record to add its parents. When this happens, an error is generated because the new entry’s parent does not exist when the LDAP server attempts to add the entry.

To solve this problem, simply enable the use of forward references. When you enable the creation of forward references and an entry is going to be created before its parent exists, a placeholder called a forward reference is created for the entry’s parent to allow the entry to be successfully created. If a later operation creates the parent, the forward reference is changed into a normal entry.

It is possible that one or more forward references will remain after your LDIF import is complete (if, for example, the LDIF file never created the parent for an entry). In this case, the forward reference will appear as an Unknown object in iManager. Although you can search on a forward reference entry, you cannot read attributes (except objectClass) from the forward reference entry because it does not have any attributes or attribute values. However, all LDAP operations will work normally on the real object entries located below the forward reference.

Identifying Forward Reference Entries

Forward reference entries have an object class of Unknown and also have their internal NDS EF_REFERENCE entry flag set. In iManager, entries with an object class of Unknown are represented by a round yellow icon with a question mark in the center. You can use LDAP to search for objects with an Unknown object class, although there is currently no way to access the entry flag settings through LDAP to be sure that they are forward reference entries.

Changing Forward Reference Entries into Normal Objects

You can change a forward reference entry into an normal object by simply creating it (using, for example, an LDIF file or an LDAP client request). When you ask eDirectory to create an entry that already exists as a forward reference, eDirectory transforms the existing forward reference entry into the object you asked it to create.

Using the NetIQ eDirectory Import Convert Export Wizard

To enable forward references during an LDIF import:

  1. In NetIQ iManager, click the Roles and Tasks button Roles and Tasks button.

  2. Click eDirectory Maintenance > Import Convert Export Wizard.

  3. Click Import Data from File on Disk, then click Next.

  4. Select LDIF as the type of file you want to import.

  5. Specify the name of the file containing the data you want to import, specify the appropriate options, then click Next.

  6. Specify the LDAP server where the data will be imported.

  7. Add the appropriate options, as described in the following table:

    Option

    Description

    Server DNS name/IP address

    DNS name or IP address of the destination LDAP server

    Port

    Integer port number of the destination LDAP server

    DER File

    Name of the DER file containing a server key used for SSL authentication

    Login method

    Authenticated Login or Anonymous Login (for the entry specified in the User DN field)

    User DN

    Distinguished name of the entry that should be used when binding to the server-specified bind operation

    Password

    Password attribute of the entry specified in the User DN field

  8. Under Advanced Settings, click Allow Forward References.

  9. Click Next, then click Finish.

To enable forward references during a data-to-data server migration:

  1. In NetIQ iManager, click the Roles and Tasks button Roles and Tasks button.

  2. Click eDirectory Maintenance > Import Convert Export Wizard.

  3. Click Migrate Data Between Servers, then click Next.

  4. Specify the LDAP server holding the entries you want to migrate.

  5. Add the appropriate options, as described in the following table:

    Option

    Description

    Server DNS name/IP address

    DNS name or IP address of the source LDAP server

    Port

    Integer port number of the source LDAP server

    DER file

    Name of the DER file containing a server key used for SSL authentication

    Login method

    Authenticated Login or Anonymous Login (for the entry specified in the User DN field)

    User DN

    Distinguished name of the entry that should be used when binding to the server-specified bind operation

    Password

    Password attribute of the entry specified in the User DN field

  6. Under Advanced Settings, click Allow Forward References.

  7. Click Next.

  8. Specify the search criteria (described below) for the entries you want to migrate:

    Option

    Description

    Base DN

    Base distinguished name for the search request

    If this field is left empty, the base DN defaults to " " (empty string).

    Scope

    Scope of the search request

    Filter

    RFC 2254-compliant search filter

    The default is objectclass=*.

    Attributes

    Attributes you want returned for each search entry

  9. Click Next.

  10. Specify the LDAP server where the data will be migrated.

  11. Click Next, then click Finish.

    NOTE:Ensure that the schema is consistent across LDAP Services.

Using the NetIQ Import Conversion Export Utility Command Line Interface

To enable forward references in the command line interface, use the ‑F LDAP destination handler option.

For more information, see LDIF Destination Handler Options in the NetIQ eDirectory 8.8 SP8 Administration Guide.

5.2.2 Checking the Syntax of LDIF Files

You can check the syntax of an LDIF file before you process the records in the file by using the Display Operations But Do Not Perform LDIF source handler option.

The LDIF source handler always checks the syntax of the records in an LDIF file as it processes them. Using this option disables the processing of the records and lets you verify the syntax.

Using the NetIQ eDirectory Import Convert Export Wizard

  1. In NetIQ iManager, click the Roles and Tasks button Roles and Tasks button.

  2. Click eDirectory Maintenance > Import Convert Export Wizard.

  3. Click Import Data from File on Disk, then click Next.

  4. Select LDIF as the type of file you want to import.

  5. Specify the name of the file containing the data you want to import, specify the appropriate options.

  6. Under Advanced Settings, click Display Operations But Do Not Perform, then click Next.

  7. Specify the LDAP server where the data will be imported.

  8. Add the appropriate options, as described in the following table:

    Option

    Description

    Server DNS name/IP address

    DNS name or IP address of the destination LDAP server

    Port

    Integer port number of the destination LDAP server

    DER File

    Name of the DER file containing a server key used for SSL authentication

    Login method

    Authenticated Login or Anonymous Login (for the entry specified in the User DN field)

    User DN

    Distinguished name of the entry that should be used when binding to the server-specified bind operation

    Password

    Password attribute of the entry specified in the User DN field

  9. Click Next, then click Finish.

Using the NetIQ Import Conversion Export Utility Command Line Interface

To check the syntax of an LDIF file in the command line interface, use the ‑n LDIF source handler option.

For more information, see LDIF Source Handler Options in the NetIQ eDirectory 8.8 SP8 Administration Guide.

5.2.3 Resolving the LDIF Error File

The NetIQ Import Conversion Export utility automatically creates an LDIF file listing any records that failed processing by the destination handler. You can edit the LDIF error file generated by the utility, fix the errors in the command line utility, then reapply it to the server to finish an import or data migration that contained failed records.

To configure error log options in the command line utility, use the ‑l general option.

For more information, see General Options in the NetIQ eDirectory 8.8 SP8 Administration Guide.

5.2.4 Using LDAP SDK Debugging Flags

To understand some LDIF problems, you might need to see how the LDAP client SDK is functioning. You can set the following debugging flags for the LDAP source handler, the LDAP destination handler, or both.

Value

Description

0x0001

Trace LDAP function calls.

0x0002

Print information about packets.

0x0004

Print information about arguments.

0x0008

Print connections information.

0x0010

Print BER encoding and decoding information.

0x0020

Print search filter information.

0x0040

Print configuration information.

0x0080

Print ACL information.

0x0100

Print statistical information.

0x0200

Print additional statistical information.

0x0400

Print shell information.

0x0800

Print parsing information.

0xFFFF (-1 Decimal)

Enable all debugging options.

To enable this functionality, use the ‑e option for the LDAP source and LDAP destination handlers. The integer value you give for the -e option is a bitmask that enables various types of debugging information in the LDAP SDK.

For more information, seeLDAP Source Handler Options and LDAP Destination Handler Options in the NetIQ eDirectory 8.8 SP8 Administration Guide.