test

Sun Java System Web Server 6.1 SP12 Installation and Migration Guide

Chapter 6 Migrating from Web Server Version 4.1 to 6.1

This chapter contains migration information to help, when you migrate your Sun Java System Web Server from version 4.1 to 6.1.

This chapter contains the following information:

Migration Overview

You can migrate the following iPlanet Web Server 4.1 information to work with Sun Java System Web Server 6.1.

Note –

Direct migration from a version of iPlanet Web Server that is lower than 4.1 to Sun Java System Web Server 6.1 is not supported. You must first migrate your legacy server to iPlanet Web Server 4.1 and then to Sun Java System Web Server 6.1.

Note –

In general, when this document refers to iPlanet Web Server 4.1, the information applies to service pack releases as well, such as iPlanet Web Server 4.1, SP12.

Migrating Settings and Data

Caution – Caution –

Shut down all server instances before migrating.

ProcedureTo migrate settings and data from a 4.1 server to the 6.1 server

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

  2. Click Migrate Server.

    Figure 6–1 Migrate server page

    Migrate server page

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

    /usr/netscape/server4

    C:\netscape\server4

    Sun Java System Web Server detects whether there are server instances installed in the directory you specified and displays the servers you can migrate in a section of the page called “Installed Servers.” The Administration Server cannot be migrated.

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

    Figure 6–2 Select a Server to Migrate

    Select a server to migrate

  5. In the new Migration parameters window that is launched, specify the migration parameters.

    Figure 6–3 Specify the Migration Parameters

    Specify the Migration Parameters

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

    • General Migration Parameters

      • Document Root

      • Java

        For more information, see The Migration Parameters Page in the online help.

  6. Click Migrate.

    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 4.1 server that are not supported in 6.1.

    Figure 6–4 The Migrate server-name Page

    The Migrate server-name Page

    Note –

    During migration from a version 4.1 release, the Address directive from the magnus.conf file, which is deprecated in the Sun Java System Web Server 6.1 is also migrated. This leads to the following warning message at server startup: "Warning ( ): Address directive ignored." You can ignore this warning message.

  7. Click Configure Migrated Server to configure your migrated server instance in the Server Manager, or click Close to close the migration window.

The Migrate server-name Page

When you migrate, you see a page (Migrate server_name) that logs all the migration information, including all errors encountered. You receive warnings for the features you used in iPlanet Web Server 4.1 that are not supported in Sun Java System Web Server 6.1. The migration program does not migrate entries in obj.conf corresponding to obsolete features.

If you get fatal errors while migrating, the migration continues. The results page shows what errors occurred and 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 iPlanet Web Server instances, you need to set up features such as distributed administration and clusters again in your 6.1 Administration Server.

You can also migrate keys and certificates.

Migrating User and Group Information

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.

Migrating Virtual Servers

iPlanet Web Server 4.1 provided two methods for creating hardware virtual servers: the object method and the virtual method. Migration of hardware virtual server information depends on which method you used:

Migrating ACLs

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

Migrating Certificates

The migration process copies the database files in the 4.1_server_root/alias directory, such as key3.db and cert7.db, to the 6.1_server_root/alias directory.

In addition, the SSL parameters located in the magnus.conf file of 4.1 Server are automatically added to the 6.1 server.xml configuration file.

The ACL-related files, secmod.db and dbswitch.conf files are overwritten during migration.

For more information on using certificates with Sun Java System Web Server, see the Sun Java System Web Server 6.1 SP12 Administrator’s Guide.

Migrating Applications

After migrating your server settings and data, you need to make changes to your applications so that they run on Sun Java System Web Server 6.1.

Migrating NSAPI Applications

Most NSAPI programs you used with iPlanet Web Server 4.1 will work in Sun Java System Web Server 6.1 without being recompiled. Some undocumented data structures have been moved out of nsapi.h and are no longer public. 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.

Custom NSAPI plug-ins are not automatically copied to the new server directory. If you have custom plug-ins, make sure you copy your plug-ins to the upgraded path as shown in the magnus.conf of the new server.

For more information on these data structures and the new accessor functions, see the Sun Java System Web Server 6.1 SP12 NSAPI Programmer’s Guide.

Server-side Java Applets (HttpApplets)

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

What Does Not Get Migrated

The migration process does not migrate the following:

Summary of Migration-Related Changes

When you migrate information from iPlanet Web Server 4.1 to Sun Java System Web Server 6.1, the changes are made in the following areas:

Access and Error Logs

The access and error server log files records the activity of the Server. During migration, new access logs are created. Error logs from the 4.1server-instance/logs directory is copied to the server-instance/logs in Sun Java System Web Server 6.1.

Configuration Files

Certain directives found in the iPlanet Web Server 4.1 magnus.conf file are now located in the Sun Java System Web Server 6.1 server.xml file. During the migration process, these directives are automatically removed from the 6.1 server’s magnus.conf file and added to the server.xml file.

In addition, Init functions located in the iPlanet Web Server 4.1 obj.conf file are moved to the Sun Java System Web Server 6.1 magnus.conf file.

For a list of deprecated directives, see the Sun Java System Web Server 6.1 SP12 Administrator’s Configuration File Reference.

Note –

During migration, multi-line Init directives are compressed to single-line directives in the Sun Java System Web Server 6.1 magnus.conf file.

Java Server Pages

iPlanet Web Server 4.0 Java Server Pages (JSPs) were written in JSP 0.92. The iPlanet Web Server 4.1 and 6.0 JSPs are written in JSP 1.2. Version 0.92 is no longer supported in Sun Java System Web Server 6.1. JSPs must be rewritten according to the version 1.2 standard. In addition, Sun recommends that developers create JSPs as part of web applications. Style examples can be found in server_root/plugins/servlets/examples/web-apps.

JSPs written in JSP 1.2 that are part of a web application can reside in any directory that the server can serve from.

JSP 1.2 samples are in server_root/plugins/samples/servlets/jsp.10.

Java Servlets

Netscape Enterprise Server / iPlanet Web Server 4.0 and 4.1 supported the Java Servlet 2.1 specification. This specification did not include web applications. A deployment scheme was developed to make servlet deployment simpler. With the advent of Java Web Applications (.war files) and their deployment descriptors, it is no longer necessary to maintain a proprietary deployment system.

iPlanet Web Server 6.0 supported both types of deployment schemes, but the 4.x implementation referred to as legacy servlets was marked as deprecated. See Chapter 8: “Legacy Servlet and JSP Configuration” of the iPlanet Web Server, Enterprise Edition Programmer's Guide to Servlets.

Sun Java System Web Server 6.1 does not support Legacy Servlets. The legacy-style properties files for the server you want to migrate - servlet.properties, context.properties, and rules.properties - are removed during migration.

Because there is no one-to-one mapping for all of the features, legacy servlets cannot be migrated automatically.

For documentation and samples to help you migrate your 4.1 legacy-style servlets to the web applications structure, see the Sun Java System Web Server 6.1 SP12 Programmer’s Guide to Web Applications.

Cron Control

Cron file names have been changed in Sun Java System Web Server 6.1. The file ns-cron.conf is called schedulerd.conf in Sun Java System Web Server 6.1, and the file cron.conf is now called scheduler.conf. These are located in the https-admserv/config directory.

Cron settings from the previous version of your Web server are however not migrated to Sun Java System Web Server 6.1during migration. Copy the cron settings for the migrated instance to the cron files.

The certmap.conf File

The certificate mapping file, certmap.conf, is not migrated during the migration process. During migration you receive a message that you need to manually migrate existing entries in the certmap.conf of the server instance you want to migrate.

Simple Session Manager

Simple Session Manager and JDBC Session Manager are not supported by Sun Java System Web Server 6.1. For more details about session managers, see the Sun Java System Web Server 6.1 SP12 Programmer’s Guide to Web Applications.

If your iPlanet Web Server 4.1 web applications specified SimpleSessionManager, you should change the name of the class to IWSSessionManager. You then have the option of adding persistence. Persistence-type must be set to s1ws60. Other Init attributes such as timeOut and reapInterval are unchanged.

If your iPlanet Web Server 4.1 web application specified JDBCSessionManager, you should change the name of the class to IWSSessionManager and add the following attribute to the init-param element of the session manager: session-data-store=com.netscape.server.http.session.JdbcStore. Persistence-type must be set to s1ws60.

Other attributes such as provider and url remain unchanged.

The package name of the MMapSessionManager has been changed from com.netscape.server.http.session in the 4.1 version of the Web Server to com.iplanet.server.http.session in the 6.0 and 6.1versions.

Virtual Servers

In iPlanet Web Server 4.1, you could create multiple server instances using hardware and software virtual servers, but these instances were required to share the same configuration information. With Sun Java System Web Server 6.1, you can set up multiple classes of virtual servers. Each class has separate configuration information.

The settings for virtual servers are stored in the server.xml file, found in the server_root/server_ID/config directory. See the Sun Java System Web Server 6.1 SP12 Administrator’s Guide for more information on virtual servers.

Web Publishing

Sun Java System Web Server 6.1 does not support the iPlanet Web Server 4.1 Web Publishing feature. It provides a new feature called WebDAV that enables collaborative file sharing and authoring on the Web. See the Sun Java System Web Server 6.1 SP12 Administrator’s Guide for more information.

Search

Because the search engine used in iPlanet Web Server 4.1 has been replaced by a new search engine in Sun Java System Web Server 6.1, existing search collections and indexes are not migrated during the migration process. To use the Search functionality in Sun Java System Web Server 6.1, create and configure new search collections and indexes. For more information, see the Sun Java System Web Server 6.1 SP12 Administrator’s Guide.

Start and Stop Scripts

If you have made modifications to your start or stop scripts in your 4.1 server, those changes will not be carried forward by the migration program. This applies to the reconfig, restart, and rotate scripts as well.

Symbolic Links in Configuration Files (UNIX and Linux)

Symbolic or relative links in server configuration files might cause problems when upgrading. Ensure 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. These links should not transverse any symbolic links.

Server Side JavaScript (SSJS)/LiveWire

Data and settings are not migrated applications that use SSJS/Livewire.

See the Sun Java System Web Server 6.1 SP12 Programmer’s Guide to Web Applications for an appendix explaining how to convert SSJS applications to JSPs. In addition, you can find an example of a converted application in server_root/plugins/samples/servlets/jsp.10/hangman.