Complete Contents
About This Guide
Chapter 1 Before You Install
Chapter 2 Installing iPlanet Web Server
Chapter 3 Troubleshooting Installation
Chapter 4 Migrating and Upgrading
Previous Contents Index Bookshelf


Chapter 4 Migrating and Upgrading

This chapter contains information on migrating your configuration settings and data from Enterprise Server 3.6 to iPlanet Web Server 4.1, and upgrading from iPlanet Web Server 4.0 to iPlanet Web Server 4.1.

This chapter contains the following sections:


Migrating from a Pre-3.6 Enterprise Server
The migration program included in iPlanet Web Server handles the following situations:

If you have a pre-3.6 version of Netscape Enterprise or FastTrack Server installed, you must first migrate from that version to Enterprise 3.6. You can get a copy of Enterprise Server 3.6 at the following URL:

http://iplanet.com/downloads/index.html

Instructions for migrating from an earlier release to 3.6 are at the following URL (a link within the Netscape Enterprise Server 3.6 release notes):

http://home.netscape.com/eng/server/webserver/3.0/es36upg.htm

Once you have migrated to Enterprise Server 3.6, you can migrate to 4.1. For more information, see "Migrating from Enterprise Server 3.6".


Migrating from Enterprise Server 3.6
The iPlanet Web Server 4.1 migration process migrates the following information from Netscape Enterprise Server 3.6:

Obsolete Features
The following Netscape Enterprise Server 3.6 features are not supported in iPlanet Web Server 4.1:

Data and settings are not migrated for these features.

Obsolete obj.conf Directives
The following directives are not used with iPlanet Web Server 4.1. If the migration program finds them in your 3.6 server's obj.conf file, it does not carry them forward to the 4.1 server.

Start and Stop Scripts
If you've made modifications to your start or stop scripts in your 3.6 server, those changes will not be carried forward by the migration program.

Symbolic Links in Configuration Files (Unix and Linux)
Symbolic or relative links in server configuration files may cause problems when upgrading. Make sure that server configuration files that contain absolute references to files under the server root always reference the path to the server root in the same way, and preferably without traversing any symbolic links.

Post-Migration on Windows NT
Because Enterprise Server 3.6 and iPlanet Web Server 4.1 cannot coexist on the same system, once you have migrated Enterprise Server 3.6 you should remove it from any system that also contains iPlanet Web Server 4.1.

Migrating Settings and Data

Warning. Shut down all server instances before migrating.

To migrate settings and data from a 3.6 server to the 4.1 server, follow these steps:

  1. In the Administration Server page, click the Servers tab.

  2. Click Migrate Server.

  3. Enter the server root of the server from which you want to migrate and click Search.

    4. iPlanet Web Server detects whether there are servers installed in the directory you specified and displays the servers you can migrate in a section of the page called "Installed Servers."

  4. Choose a server from the drop-down list and click Migrate.

    5. A new window appears showing the migration parameters.

  5. Fill in the form.

    6. The sections on the form that you see depend upon which features your 3.6 Enterprise Server is using and which 4.1 components you installed. The following sections of parameters are possible:

  6. Click Migrate.

    7. The Migrate Server_name page appears. It shows the results of the migration, including the parameters successfully migrated and the parameters that you need to migrate manually. It also shows any features of your 3.6 server that are not supported in 4.1.

  7. Click Configure Migrated Server to configure your migrated server instance in the Server Manger, or click Close to close the migration window.
The Migrate Server Page
When you migrate, you see a page (Migrate Server_name) that logs all the migration information, including all errors encountered. The following is an example of this page.

Figure 4.1    Migration information

 As shown in this example, you receive warnings for the features you used in Netscape Enterprise Server 3.6 that are not supported in iPlanet Web Server 4.1. The migration program does not migrate entries in obj.conf that are for obsolete features.

If you get fatal errors while migrating, the migration continues. The results page shows what errors occurred an you can use this information to troubleshoot.

Migrating the Administration Server
You can only migrate individual server instances. You cannot migrate your administration server. After you have migrated your Enterprise Server instances, you need to set up features such as distributed administration and clusters again in your 4.1 Administration Server.

When you migrate an Enterprise Server instance, you have the option of migrating user and group information, which spans multiple server instances. Once you have migrated user and group information or set up your 4.1 environment, you do not need to migrate users and groups again. The user and group information is in the /server_root/userdb/server_name.ldif file.

You can also migrate keys and certificates.

Migrating User and Group Information
In Enterprise Server 3.6, you had the option of maintaining user and group information in or in a local database or in a Directory Server.

Migrating from a Local Database

If you used a local database for your user and group information, follow these steps:

  1. During the migration process, choose to export your local database to an LDIF file.

  2. In your 4.x Directory Server, use the file ldif2ldap to add DN information to your exported file. The ldif2ldap file is in your Directory Server instance folder. To run it on Windows NT, type:

    3. ldif2ldap.bat filename

    where filename is the name of the exported LDIF file.

    On Unix, type:

    ./ldif2ldap filename

  3. Open Directory Server in Netscape Console. From the Configuration tab, right-click on the Database item and choose Import. Browse to your converted file.

  4. In the Administration Server, on the Global Settings tab, use the Configure Directory Service page to point to the Directory Server where you imported your database information.
Migrating from Directory Server

If you used the Directory Server, you do not need to do anything during the migration process to migrate users and groups. After migrating, in the Administration Server, on the Global Settings tab, use the Configure Directory Service page to point to a Directory Server. You must use a 4.1 or 4.11 Directory Server.

Migrating ACLs
iPlanet Web Server 4.1 has a new default ACL called es-internal. It controls who can change files internal to iPlanet Web Server, for example, help files, onscreen icons, and so on. This new default ACL is added when you migrate.

If you had ACLs set up in your administration server 3.6 for distributed administration, these ACLs are not migrated. You must add them manually to your new Administration Server.

Migrating Certificates
Keys and certificates are migrated as part of the migration process only if your server has security enabled. You can also migrate keys and certificates by themselves using the Security tabs in the Administration Server page and the Server Manager page.

During the migration process, you can migrate the certificates from either the individual server instance or from the administration server.

The way iPlanet Web Server 4.1 uses and manages certificates has changed from Enterprise Server 3.6. Enterprise Server 3.6 used an alias to refer to a certificate and key pair. Multiple server instances could use to a single alias. The administration server managed all the aliases and the certificates in them.

In iPlanet Web Server 4.1, each server instance (including the Administration Server) has its own certificate/key pair, which is now called a trust database. You manage the trust database from the Server Manager's Security tab. The trust database includes the server certificate and all the included Certificate Authorities. The certificate and key database files are now named after the server instance that uses them. If multiple Enterprise Server 3.6 instances use the same alias, when you migrate each instance you can choose to migrate the certificate and key pair. The migrated certificate and key pair are named for the iPlanet Web Server 4.1 instance each time you migrate.

The migration not only migrates the certificate, it migrates the whole trust database associated with the server instance. All the Certificate Authorities (CAs) in your 3.6 database are migrated to the 4.1 database. If they duplicate 4.1 CAs, use the 3.6 CA until it expires; then use the 4.1 CA. Do not attempt to delete duplicate CAs.

When you migrate certificates from Enterprise Server 3.6 to iPlanet Web Server 4.1 make sure that the Administration Server user for 4.1 has read and write permissions on the Enterprise Server 3.6 database files. The files are alias-cert.db and alias-key.db, located in the 3.6_server_root/alias directory.

For more information on using certificates with iPlanet Web Server, see the iPlanet Web Server Administrator's Guide.

Note. If you are migrating an SSL-enabled server, you will have to manually start the migrated server because you have to specify a password when starting it.

Migrating Web Publishing
If you had web publishing turned on in Enterprise Server 3.6 server, the configuration files are migrated automatically as part of the migration process.

To successfully migrate web publishing data, you must choose the following options on the Migration Parameters page:

Migrating Netshare
If you had Netshare turned on in Enterprise Server 3.6, you migrate the configuration files automatically as part of the migration process.

To successfully migrate Netshare directories and environment, on the Migration Parameters page you must choose to use your old document root. Otherwise your Netshare data is not carried forward.

Migrating Search Collections
You need to choose which search collections, if any, you want to migrate. The Migration Parameters page has checkboxes for you to select the collections you want to migrate. If you don't migrate a collection when you migrate the server, you cannot go back and migrate it in the future.

If you choose to use your old document root, the search collections you migrated work automatically. If you choose to use a new document root instead of your old one, you may need to recreate some of your collections before they will work.

Note that multiformat collections are not supported in iPlanet Web Server 4.1.

Migrating Search Pattern Files
You have the option of migrating the search pattern files. You should only do this if you have customized the default pattern files. In addition, if you want to migrate the old pattern files to the new server and you are using the advanced search applet, you need to change your migrated pattern files so that they call the search applet properly.

In Netscape Enterprise Server 3.6, the applet files were called applet.zip and searchapplet.zip. In iPlanet Web Server 4.1, the applet files are called SearchApplet.jar and SearchAppletIE.jar. Change references to the old applet files to the new applet files.

Migrating Applications
After migrating your server settings and data, you may also need to make changes to your applications so that they run on iPlanet Web Server 4.1.

Migrating Server-Side JavaScript Applications
iPlanet Web Server 4.1 supports JavaScript 1.4. For information about the changes between JavaScript 1.2 and 1.4, see the "New Features" section in the document Core JavaScript Reference v1.4 at:

http://developer.iplanet.com/docs/manuals/javascript.html

You must recompile and reregister server-side JavaScript applications before running them in 4.1. The migration will not pick up the entries from your old jsa.conf automatically. Remember also that Server-Side JavaScript is turned off by default. You must turn it on again in your migrated server.

Migrating NSAPI Applications
Most NSAPI programs you used with Enterprise Server 3.6 will work in iPlanet Web Server 4.1 without being recompiled.Some undocumented data structures have been moved out of nsapi.h and are no longer public. Going forward, if your plugins use any of these data structures, you should re-write them to use accessor functions. The data structures that are now private are defined in nsapi_pvt.h, which is shipped with the build for informational purposes only.

For more information on these data structures and the new accessor functions, see the Programmer's Guide to iPlanet Web Server 4.1.

Migrating Java Servlets
After you've migrated your server, Java servlets that ran in Enterprise Server 3.6 should run in 4.1 without being recompiled. The migration leaves 3.6 servlets in their original directory. The migrated servlets run in compatibility mode, which may make them a little slower than other 4.1 servlets.

Also, if your 3.6 servlet referenced any additional files, you need to add the path to these files to your JVM classpath. To update the classpath, use the Configure JVM Attributes page, which you can find in the Server Manager on the Servlets tab.

Note. When you install the Java subcomponent, the configuration files that are installed include a set of files that end in .default (for example, rules.properties.default). These files contain the default values for the Java configuration files. During migration, the Java configuration files are not changed from the previous version. If you want to update the old files to the new settings, refer to the .default files. You can also refer to the .default files in the future if you want to revert to the iPlanet Web Server 4.1 default settings.

Server-side Java Applets (HttpApplets)
Server-side Java applets (HttpApplets) are no longer supported. Instead use Java servlets. You will need to rewrite your server-side Java applets as servlets and reinstall them.

Web Application Interface
Enterprise Server 3.0 provided an API, called the Web Application Interface (WAI), to extend server functionality. With iPlanet Web Server 4.1, developers are encouraged to use industry-standard Java servlets for any future applications they develop. WAI is still supported, but iPlanet Web Server 4.1 focuses on supporting Java servlet development.

By default, the WAI component is not installed when you install the server. You must manually select it for installation. If you did not select WAI when you installed iPlanet Web Server 4.1, you can run the installer again and install just the WAI component.

In addition, iPlanet Web Server no longer includes an Object Request Broker (ORB) as part of the release. If you want to continue using WAI, you must obtain the ORB yourself. To get the Visibroker 3.3 for C++ ORB, or the Visibroker 3.4 for Java ORB, contact Inprise at the following URL:

http://www.inprise.com/visibroker/download

If you are migrating from Netscape Enterprise Server 3.6, you must still get an updated version of the ORB. The ORB shipped with Enterprise Server 3.6 is an earlier version which is no longer supported.

Warning. You must install the ORB before migrating your Enterprise Server. If you do not, you will get an error message when you try to start your migrated server instance.


Upgrading From iPlanet Web Server 4.0
If you are upgrading from iPlanet Web Server 4.0 to iPlanet Web Server 4.1, you must install your 4.1 server in the same directory that your 4.0 server was installed in. The upgrade happens automatically during installation. You cannot use the Migration Page in the Administration Server to upgrade from 4.0 to 4.1.

Upgrade retains your server settings and document root.

iPlanet Web Server 4.1 Changes
When you upgrade from iPlanet Web Server 4.0 to iPlanet Web Server 4.1, the following changes are made:

Upgrading Windows NT
To upgrade, follow these steps:

  1. Shut down your existing servers.

  2. Run the iPlanet Web Server installer for 4.1.

  3. When you install subcomponents, you must install all the subcomponents you installed for 4.0, otherwise they are not upgraded properly and may not work. You can install additional subcomponents as well.

  4. When prompted for the installation directory, choose the directory where your 4.0 server was installed.

  5. Answer the rest of the installation prompts.

    6. Before installing the software, the installer displays a message that it has detected an upgrade, and that in addition to installing the components you selected, it will also upgrade any components that have been previously installed.

  6. Press any key to continue.

    7. You do not need to answer any more installation prompts. The installer installs the software.

  7. Go to the Control Panel and choose Services.

  8. Start the iPlanet Web Server and Administration Server services.

  9. When you access the Administration Server, you need to click Save and Apply and Load Configuration Changes.
Upgrading Unix
To upgrade, follow these steps:

  1. Shut down your existing servers.

  2. Run the iPlanet Web Server installer for 4.1.

  3. When you install subcomponents, you must install all the subcomponents you installed for 4.0, otherwise they are not upgraded properly and may not work. You can install additional subcomponents as well.

  4. When prompted for the installation directory, choose the directory where your 4.0 server was installed.

  5. Answer the rest of the installation prompts.

    6. Before installing the software, the installer displays a message that it has detected an upgrade, and that in addition to installing the components you selected, it will also upgrade any components that have been previously installed.

    To cancel the upgrade at this point, press CTRL-c.

  6. Press any key to continue.

    7. You do not need to answer any more installation prompts. The installer installs the software.

  7. Go to the https-admserv directory under your server root directory and start the Administration Server by typing ./start. You can also type ./startconsole in the server root directory.

    8. If you have a Netscape console installed, startconsole starts the console. If you do not have a console installed, it starts the Administration Server and launches a browser to the Administration Server administration pages.

  8. When you access the Administration Server, you need to click Save and Apply and Load Configuration Changes.
Upgrade Issues
The following sections contain information about how upgrading from iPlanet Web Server 4.0 to iPlanet Web Server 4.1 affects certain features.

Java Server Pages
iPlanet Web Server 4.0 JSPs were written in JSP 0.92. The iPlanet Web Server 4.1 JSPs are written in JSP 1.1. Any JSPs you have written in 0.92 will still work on iPlanet Web Server 4.1 as long as they are in a designated legacy directory.

To designate a directory as a legacy directory, on the Servlets tab, choose Legacy JSP Directory. Use this page to designate your legacy directories.

JSPs written in JSP 1.1 can reside in any directory that the server can serve from.

The samples are divided into two folders. The old JSP samples are now in the server_root/plugins/samples/servlets/jsp.092 directory. The new JSP 1.1 samples are in server_root/plugins/samples/servlets/jsp.10.

Java Servlets
iPlanet Web Server now recognizes servlets in a package without requiring you to register each servlet in the package and map the virtual paths. For more information, see the Programmer's Guide to Servlets in iPlanet Web Server.

Java Configuration Files
When you install the Java subcomponent, the configuration files that are installed include a set of files that end in .default (for example, rules.properties.default). These files contain the default values for the Java configuration files. During migration, the Java configuration files are not changed from the previous version. If you want to update the old files to the new settings, refer to the .default files. You can also refer to the .default files in the future if you want to revert to the iPlanet Web Server 4.1 default settings.

WAI Subcomponent and Express Installation
If you installed the WAI subcomponent with your iPlanet Web Server 4.0, do not use Express installation when you upgrade to iPlanet Web Server 4.1. Your WAI files will not be updated, because the Express installation doesn't install WAI.

 

© Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.