Sun logo      Previous      Contents      Index      Next     

Sun ONE Meta-Directory 5.1.1 Installation Guide

Chapter 5
Upgrading to Meta-Directory 5.1.1

Sun ONE Meta-Directory 5.1.1 provides a utility that can be used to upgrade from Sun ONE Meta-Directory 5.1 or iPlanet Meta-Directory 5.0 and 5.0SP1 (including 5.0SP1 Patch 1 and 5.0SP1 Patch2).

This chapter contains these sections:

Its recommended that all of the subsequent sections must be reviewed before you execute the upgrade tool.

Upgrade Overview

This section describes the script that is used to upgrade to Meta-Directory 5.1.1. The upgrade script (upgrade.bat on Windows and upgrade.sh on Solaris) is shipped with the Meta-Directory 5.1.1 software and is available along with the setup binary. Once you decompress the software program, the script must be executed from that location itself. It will not run if it is copied and executed from a different location.

The script uses nsPerl 5.8.2 and PerLDAP 1.4.1 which are installed with the Sun ONE Directory Server and with Meta-Directory 5.1.1. The script copies these components to a temporary location (specified by the user), decompresses the files, sets the environment, and then executes another script (upgrade.pl) which performs the upgrade related operations.

Note

Do not run the upgrade.pl script directly, use only upgrade.sh (Solaris) or upgrade.bat (Windows) for any upgrade related operations.

The upgrade script requires a command-line decompress utility to decompress the required binaries. It will prompt for the complete path of this utility to decompress nsperl582.zip file. If you want to perform this step manually, (for example, on Windows if you only have WinZip which is a GUI based utility), you should decompress the files manually and skip this part during the upgrade process.

When you run the script it displays a message “If you want to skip this unzipping part”, type No if you have a command-line decompression utility and want the script to perform the operation. In this case, it first prompts for a new location where it copies the binaries. Make sure its a new location that can be created (appropriate permissions to create a directory in the should be available).

Caution

If the directory exists, the script fails.

The scripts then decompresses the required binaries, sets the environment, and continues with the upgrade process.

If you choose to skip the decompression part of the upgrade process, then you must do the following:

  1. From the location where Meta-Directory software is decompressed, copy nsperl/nsperl582.zip to a temporary location.
  2. Change the directory to the temporary location and decompress the above files.
  3. Specify this temporary location when prompted by the upgrade script.

Using the Upgrade Script

This section describes the set of arguments and the options to use to perform the upgrade process. The upgrade process involves running the script twice. First, the script is executed to perform a backup of all the Meta-Directory configuration and server instances. This is run with -U option (upgrade). Then, with the -R option to restore the configuration.

Usage:

upgrade.sh -<U|R> [-h <directory server hostname>] -p <port> -D <Directory Manager> -w <password>

Table 5-1 describes the options used:

Table 5-1  List of options and their description

Option

Description

- U

Upgrade.
Used the first time the script is run for upgrade. This retrieves all the Meta-Directory configuration and stores it in the LDIF files, and then deletes the existing configuration. Once the script is executed with this option, Meta-Directory does not run.

The administrator can now uninstall the existing Meta-Directory (5.0/5.0SP1/5.1), and then install Sun ONE Meta-Directory 5.1.1. See Chapter 6, "Uninstalling Meta-Directory," for issues related to the uninstallation process.

- R

Restore.
Used to restore the original Meta-Directory configuration that was created in the backup process. This ensures that the original configuration is restored with the enhancements provided in Meta-Directory 5.1.1.

- h

Valid host name (for example, restaurants. madisonparc.com) on which the Directory Server that contains the configuration is running (optional), else, the default would be the localhost.

- p

Port on which the directory server listens (mandatory), no default

- D

Directory Manager DN. For example, cn=Directory Manager. (mandatory)

- w

Directory Managers’ password (mandatory)

For example:

./upgrade.sh -U -h ldap_host -p 389 -D cn=Directory Manager -w dmanager

Note

  • Part of the Meta-Directory configuration is created by the Configuration Administrator. Thus, during the restore operation, the tool also prompts for the Configuration Administrator information and the password.
  • For a Universal Connector instance, if the configuration files such as; task.cfg, template.pl, and so on are located in the configuration directory (for example, $NETSITE_ROOT/utc-CV2/config) of the connector, these files are automatically backed up. However, if they are located elsewhere, then you must manually backup the files and copy them back to the same location after the restore process.

Step by Step Upgrade Example

This section describes the procedure of a typical upgrade process to Sun ONE Meta-Directory 5.1.1.

Before you run the upgrade utility, these conditions must be satisfied:

    To perform the upgrade procedure
  1. Start the Archive process. Run the script with -U option, as described:
    1. Change directory to the location where Meta-Directory software is decompressed.
    2. Type the following command. (Replace the arguments as required.)

      3. $ ./upgrade.sh -U -h metadirectory.example.com -p 389 -D cn=Directory Manager -w dmanager

    3. A message informing about the requirement of a command-line decompression program is displayed. It prompts you to either skip decompression or continue.
      • Type y to manually decompress the binaries, and then press Return. Once complete, goto Step f.

        • - Or -

      • Type n to use a command-line decompression program and allow the script to decompress, and then press Return. Once complete, goto Step d.
    4. The script prompts for a temporary location to copy and decompress the binaries. Enter a new location (make sure it does not exist).
    5. The script prompts for the complete path of the decompression program. Enter the complete path where the program is located. The script then copies the binaries to the temporary location and decompresses the binaries. Once complete, goto Step h.
    6. Create a temporary folder and copy nsperl/nsperl582.zip and perldap/perldap141.zip to this location.
    7. Decompress these binaries.

      8. Note

      You may allow the upgrade script to overwrite any file if it exists. This may occur when attempting to decompress the nsperl582.zip and perldap141.zip files.

    8. The script prompts for the location where you have already decompressed the binaries. Enter the location and press Return.
    9. The script sets the environment and executes the upgrade.pl perl script.
    10. Specify the location of the backup directory or press Enter to accept the default. Make sure that you have write permissions for this location. The script backs up the Meta-Directory configuration to this directory as LDIF files. If the directory exists, an error ‘File Exists’ message is displayed.

      11. The archive process detects the servers installed, backs up all the configuration data in the LDIF files located in the backup directory, and also deletes the existing configuration.

  2. Uninstall existing Sun ONE Meta-Directory 5.0/5.1. If the Directory Server and Meta-Directory are installed in the same server root, make sure that you deselect all the Directory Server components. Also, restart the machine (on Windows only) when the uninstallation is completed. This ensures that the correct DLLs are always loaded. The following is the sequence of components to be deselected on Windows:
    • Server Core Components
    • Administration Services
    • Sun ONE Directory Server
    • nsperl
    • PerLDAP
  3. If you are using Netscape or iPlanet Directory 4.x or 5.0, upgrade to Sun ONE Directory Server 5.1 or later now. Follow the instructions in Directory Server documentation for that.

    4. The following is recommended when upgrading from prior Directory Server versions to Directory Server 5.2:

    • On Windows, if iPlanet Directory Server is installed and you are attempting to upgrade to Directory Server 5.2, then first, ensure that you stop all the Directory Servers that are currently running and then install Directory Server 5.2; else, the Directory Server 5.2 installation fails and the ‘libnspr4.dll Access Denied’ message is displayed.
    • On Windows with the above case of upgrading existing Directory Server to Directory Server 5.2, nsldap*.dll in SYSTEM32 directory must be removed or renamed; else, the Directory Server 5.2 installation fails and message ‘nsldap32v50.dll Access denied’ is displayed. Restarting the system does not help and you need to manually rename or remove the offending DLLs to be able to complete the installation.
    • Upgrading to Directory Server 5.2 from prior Directory Server versions would require you to manually enable the retro-changelog plug-in, since this does not migrated. If this is not completed, Meta-Directory servers do not start after the upgrade process is completed.
    • For information on upgrading Directory Server, see Chapter 2 of the Sun ONE Directory Server 5.2 Installation and Tuning Guide. Also, you may need to see, Chapter 6 of the Sun ONE Directory Server 5.2 Reference Manual.
    • On a distributed platform the ds jar cannot be downloaded to the Sun ONE console.
    • While installing Sun ONE Directory Server 5.1 or later, use the same parameters of the previous Directory Server. This includes the same LDAP port number, Administration Domain, Configuration Admin ID, and Directory Manager ID.

      • Note

      The Sun ONE Directory 5.2 upgrade process requires that you to configure the new server on a different port. Once the upgrade/migrate process is completed. You may change the new server port to the original one.

    • Having the same port also means that you cannot have both previous and the new Directory Server instances running at the same time. Hence, stop the previous Directory Server instance prior to installing Directory Server 5.1/5.2 and running the upgrade script.
    • Run the upgrade script as described the Directory Server Installation Guide about upgrade to Sun ONE Directory Server 5.1/5.2. Once the Directory Server is upgraded, you may proceed with the Meta-Directory upgrade process.
    • You may leave the previous Directory Server at its original place. However, do not start the previous Directory Server or run the previous uninstallation program. This could result in permanent loss of configuration and data.
    • On Windows, disable the NT Services for the previous Directory Server instance and Administration Server to ensure that they do not get started when the machine is restarted.

      • Caution

      Make sure that you select and install the same set of components that was previously installed.

      • For Windows: Restart the machine after Meta-Directory 5.1.1 has been installed, if the standard process does not prompt for a restart.
      • For Solaris: Unset LD_LIBRARY_PATH before running the installation setup for Meta-Directory 5.1.1, else, the default configuration may not be created.

  4. Restore the original configuration by running the script again with the -R option.
    1. Change directory to the location where Meta-Directory software is decompressed.
    2. Type the following command. (Replace the arguments as required.)
      $ ./upgrade -R -h metadirectory.example.com -p 389 -D cn=Directory Manager -w dmanager

      3. Follow Step c through Step i as described in archive process.

    3. Specify the backup directory location or press Return to accept the default. Make sure it is the same location that was created during the backup step and that you have write permissions on it. The tool creates new configuration files in the backup directory, with each file prefixed with ?new_?. For example, for the Join Engine (join-engine.ldif) new_join-engine.ldif is created. These LDIF files and other files such as: jvm configuration and request scripts are used to reinstall as a new configuration.
    4. Provide the configuration admin ID when prompted or press Return to accept the default. Enter the password.
    5. The tool restores the Meta-Directory configuration and all the servers instances. On Windows, it creates the Windows NT service registry entries for the servers to run.
  5. To verify a successful upgrade, you should start all the server instances from the Meta-Directory Console and flow sample data appropriately.

Post Upgrade Configuration

After completing the upgrade operation, you must copy the file system directory

If the Perl layer of the UTC connector is not customized and the location of your template.pl file is in the NETSITE_ROOT/utc-<name> directory, then do the following.

After the upgrade operation, when you restore the NETSITE_ROOT/utc-<name> directory, the connector still uses the old template.pl and the three *.pm files. (You would have had backed up the NETSITE_ROOT/utc-<name> directory, before the upgrade.)

Copy the new files (4) from NETSITE/bin/utc50/install/templates/universalparser to the correct location in the NETSITE_ROOT/utc-<name> directory.

In case of the Active Directory and Exchange connector, do the following:

  1. Create a dummy instance of the connector, with the same parameters except for View Name and View ID. Do not start this connector.
  2. Goto NETSITE_ROOT/adc-<name>/config or NETSITE_ROOT/exc-<name>/config directory.
  3. Copy all the files from this directory to the actual connector’s config directory.
  4. Remove the duty connector.

Known Issues and Limitations

Troubleshooting

The following section contains information on troubleshooting problems that may occur when upgrading from prior versions of Meta-Directory to version 5.1.1.

Problem 1

“When upgrading from Meta-Directory 5.1 to Meta-Directory 5.1.1, the operation does not complete if the Oracle Connector View has large number of entries (more than 500K)”

Workaround

Perform the following procedure to upgrade to Meta-Directory 5.1.1

  1. Stop the Join Engine and all the connectors that are running.
  2. Disable the Retro-Changelog plug-in and then restart the Directory Server. Ensure that you execute this step to speedup the data backup and restore process.
  3. Backup cn=proxy views,ou=5,ou=meta-directory,ou=globalpreferences,ou=<admin-domain>,o=netscaperoot tree. The Export Databases command from Directory Server Console can be used to backup this subtree.
    1. Select the appropriate Directory Server instance from the main console window and click Open to start the Directory Server Console.
    2. From the Task tab, click Export Databases to display the Export Databases dialog box.
    3. Select the sub-tree and navigate to the tree mentioned above. Enter the ldif file location in the ‘LDIF File’ field (this will be used to backup the data).
    4. Click OK which would start data backup in the specified LDIF file.
  4. Delete the subtree cn=proxy views,ou=5,ou=meta-directory,ou=global preferences,ou=<admin-domain>,o=netscaperoot (see Step 3) from the Directory Server using ldapsearch and ldapdelete commands from the command-line prompt.

    5. Usage:

    ldapsearch -h <hostname> -p <port number> -D "cn=Directory Manager" -w <password> -b "o=NetscapeRoot" "(cn:dn:=Proxy Views)" | grep "^dn:" | sed -e ’s/dn: <.*>/\1/’ | ldapdelete -h <hostname> -p <port number> -D "cn=Directory Manager" -w <password>

    Replace the hostname, port number and bind password as per your configuration. Make sure that entire subtree including cn=Proxy Views is deleted from the directory.

  5. Run the upgrade.sh or upgrade.bat file as applicable using -U option. This backs up and deletes the Meta-Directory configuration from the Directory server.
  6. Uninstall the existing Meta-Directory. On Windows, ensure that you restart the system.
  7. Install Meta Directory 5.1.1.
  8. Run the upgrade.sh or upgrade.bat file as applicable using -R option. This restores the prior Meta-Directory configuration.
  9. Restore the data back from the ldif file that was created (see Step 3). You can use Import Databases command from the Directory server Console.

    10. This command is available in the same location where export databases command is found in Step 3.

  10. Enable the Retro-Changelog plug-in and then restart the Directory Server.
    Now you are ready to start working on with Meta Directory.

    This is a time estimate (sample) that is required to manually upgrade to Meta-Directory 5.1.1 if the Oracle Connector has 500K data (when the Retro-Changelog plug-in was disabled).
    Backup time: 5 Min.
    Data deletion time: 240 Min. (at 2100 entries per minute)
    Upgrade with -U option = 5 Min.
    Uninstallation of old meta = 10 Min.
    Installation of new meta = 20 Min.
    Upgrade with -R option = 5 Min.
    Restoring data from ldif file = 200 min (at 2500 entries per minute)
    Total time required to upgrade to Meta-Directory 5.1.1: 485 min (approximately, 8 hours). Note that 90% of the time is taken only to backup and restore the proxy view data.

Problem 2

“Upgrade.pl file fails to upgrade to Meta-Directory 5.1.1 when the configuration (NetscapeRoot) is shared”

Workaround

Perform the following upgrade procedure.



Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.