Sun ONE Web Server 6.1 Installation and Migration Guide

This chapter contains migration information to help you understand the changes that take place when you migrate your Sun ONE Web Server from version 6.0 to 6.1.

Migration Overview

You can migrate the following Sun ONE Web Server 6.0 information to work with Sun ONE Web Server 6.1.

Migrating Settings and Data

To migrate settings and data from a 6.0 server to the Sun ONE Web Server 6.1 product, follow these steps:


Caution	Shut down all server instances before migrating.

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

Click Migrate Server.

Migrate Server Page
Figure showing the Migrate Server page.

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 ONE 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.

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

Select a Server to Migrate
Figure showing the installed servers which can be migrated using the Migrate server page.

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

Specify the migration parameters
Figure showing the Migration Parameters page.

The sections on the form that you see depend upon which features your 6.0 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..

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

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.

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

What Does Not Get Migrated

Overview of Changes in Sun ONE Web Server 6.1

When you migrate information from Sun ONE Web Server 6.0 to Sun ONE Web Server 6.1, changes are made in the following areas, listed alphabetically:

Cgistub Directory

The migration process does not migrate the CGIstub directory. If you configured CGI settings for an instance on your previous server, you would need to manually copy the CGIstub directory to the appropriate location after migrating to Sun ONE Web Server 6.1.

Command Line Scripts

If you’ve made modifications to your start or stop scripts in your 6.0 server, those changes will not be carried forward by the migration program. This applies to the reconfig, restart, and rotate scripts also.

The following table lists the command line scripts that are available in Sun ONE Web Server 6.1, and also, points you to further documentation sources for more information:


Command Line Script	Description	For more information, see:
start, startsvr.bat	Starts a server instance. Each server instance has its own start script	Sun ONE Web Server 6.1 Administrator’s Guide
stop, stopsvr.bat	Stops a server instance. Each server instance has its own stop script	Sun ONE Web Server 6.1 Administrator’s Guide
restart	Restarts a server instance	Sun ONE Web Server 6.1 Administrator’s Guide
reconfig	Dynamically reconfigures the server without restarting it.	Sun ONE Web Server 6.1 Administrator’s Guide
rotate	Rotates logs.	Sun ONE Web Server 6.1 Administrator’s Guide
HttpServerAdmin	Provides command line utilities for virtual server administration	Sun ONE Web Server 6.1 Administrator’s Guide

Configuration Files

The following table provides a summary listing of the configuration files in Sun ONE Web Server 6.1; it describes the changes introduced in the current release, and points you to further documentation sources:


Configuration File	Description	For more information, see:
ACL files: generated-https-server-id.acl genwork-https-server-id.acl	Location: install-dir/httpacl/ These provide access control lists to protect server resources May reference databases defined in dbswitch.conf File names are specified in server.xml During migration, ACL files from the old server-root/httpacl directory are copied to the new server-root/httpacl directory with the new instance name. Non-default ACL files listed in the <ACLFILE> element of the server.xml file and that are present in the old server-root/httpacl directory are copied to the new server-root/httpacl directory.	Access Control Programmer’s Guide
certmap.conf	Location: server_root/bin/https/install/misc/ Configures how a client certificate is mapped to an LDAP entry Not migrated. 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.	Sun ONE Web Server 6.1 Administrator’s Configuration File Reference
dbswitch.conf	Location: server_root/userdb/ Provides a list of authentication databases, and is used to check group membership for access control Unchanged from Web Server 6.0	Sun ONE Web Server 6.1 Administrator’s Configuration File Reference
magnus.conf	Location: server-id/config Defines server plug-ins library initialization and server parameters Copied, during migration, into the new server root directory. During migration, Sun ONE Web Server 6.1 loads built-in load module functions from the new installation directory while custom modules continue to be loaded from the old installation directory. Some magnus.conf directives that were supported in Web Server 6.0 are deprecated in 6.1.	Sun ONE Web Server 6.1 Administrator’s Configuration File Reference, for a description of supported and deprecated directives. Sun ONE Web Server 6.1 NSAPI Programmer’s Guide, for a description of the Init directives.
mime.types	Location: install-dir/config/ Contains mappings between MIME (Multipurpose Internet Mail Extensions) types and file extensions During migration, the mime.types file of the old instance in the /config directory is migrated into the new server-root/server-instance/config directory. Non-default mime.types (mime1.types, mime2.types, and so on) present in old server- instance/config directory and that are listed in the MIME element of server.xml are migrated into the new server-instance/config directory.	Sun ONE Web Server 6.1 Administrator’s Configuration File Reference
nsfc.conf	Location: server_root/https-admserv/config/ Sets file cache parameters. Unchanged from Web Server 6.0	Sun ONE Web Server 6.1 Administrator’s Configuration File Reference
obj.conf	Location: install-dir/config/ Contains instructions for the server about how to handle HTTP requests from clients and service web server content such as native server plugins and CGI programs. Configured per virtual server class and named in the format <vs-name>.obj.conf New directives and functions added in Web Server 6.1 to configure filters and WebDAV Search, JSP092, and Webpub objects are not migrated.	Sun ONE Web Server 6.1 NSAPI Programmer’s Guide
server.xml	Location: instance-dir/config/ Contains most of the server configuration. During migration, the server.xml file created in the new Web Server 6.1 instance contains information from the following files: - old server.xml file - web-apps.xml - start-jvm - jvm12.conf	Sun ONE Web Server 6.1 Administrator’s Configuration File Reference
*.clfilter obj.conf.clfilter magnus.conf.clfilter server.xml.clfilter	Location: instance-dir/config/ Legacy .clfilter files, for example, web-apps.xml.clfilter are not migrated.	Sun ONE Web Server 6.1 Administrator’s Guide
secmod.db	Imported certificates and keys for external hardware accelerators are stored in the secmod.db file, which is generated when the PKCs#11module is installed. Overwritten during migration	Sun ONE Web Server 6.1 Administrator’s Guide
access log error log	Server log files record your server’s activity. During migration, new access logs are created. Error logs in 6.0 server-instance/logs directory is copied to the server-instance/logs in 6.1.	Sun ONE Web Server 6.1 Administrator’s Guide

Configuration Files Removed in Sun ONE Web Server 6.1

The following configuration files are no longer supported and are removed during migration:

Connection Groups Settings

Every listen socket in Sun ONE Web Server 6.0 had at least one connection group associated with it. When you created a listen socket, a connection group was also created, which contained the default virtual server you specified for the listen socket.

In Sun ONE Web Server 6.1, the connection group functionality has been dropped. The virtual server is now directly bound to a listen socket. During migration therefore, each connection group is migrated to an LS (listen socket) element. Each LS element contains attributes derived from both the connection group’s and the listen socket’s attributes.

Cron Control

Cron file names have been changed in Sun ONE Web Server 6.1. The Web Server 6.0 file ns-cron.conf, is called schedulerd.conf in Sun ONE Web Server 6.1, and the version 6.0 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 not migrated to Sun ONE Web Server 6.1during migration. If you need to preserve these, please copy the cron settings for the migrated instance to the cron files.

Java Migration

Unlike in the 6.0 release, Java in Sun ONE Web Server 6.1, is enabled by default. Further, in Sun ONE Web Server 6.1, you can enable and configure Java for every instance of the server, unlike in the previous 6.0 release which supported an installation-wide configuration of the JDK.

During migration you can choose to install either the JDK that is bundled with Sun ONE Web Server 6.1 (JDK 1.4.1_03) or install a custom JDK. If you install the server with a custom JDK, the javahome setting of the migrated instance would refer to the custom JDK path (taken from the javahome setting of the Administration Server). Otherwise the javahome setting would point to /bin/https/jdk.

Sun ONE Web Server 6.1 supports the Java Development Kit (JDK) version 1.4 and above. It does not support a standalone Java Runtime Environment (JRE).

In the Sun ONE Web Server 6.0 and Service Pack releases, JDK configuration data was stored in the start-jvm and jvm.conf files. In Sun ONE Web Server 6.1 this data is stored in the server.xml file.

The JAVA element in the new server.xml file contains the JDK configuration information copied from the start-jvm file of the migrated instance.

The JVMOPTIONS element in the new server.xml file contains the JVM options information from the jvm12.conf file of the migrated instance.

If the previous version of your server was configured to use JDK 1.4.1 or above, the NSES_JDK path from the server’s start-jvm file is copied into the Sun ONE Web Server 6.1 server.xml file, otherwise, the JDK path points to server-root/bin/https/jdk, which is the default JDK path in Sun ONE Web Server 6.1.

For imformation about the mapping of the start-jvm and jvm12.conf files with the server.xml file in Sun ONE Web Server 6.1, refer to the Sun ONE Web Server 6.1 Administrator’s Configuration File Reference.

Java Server Pages

Sun ONE Web Server 6.1 supports Java Server Pages (JSP) 1.2 specification. The JSP092 object representing JSP version 0.92 is no longer supported in Sun ONE Web Server 6.1 and is deleted during migration.

Style examples using JSP 1.2 can be found in the following directory: server_root/plugins/servlets/examples/web-apps/.

Legacy 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 proprietory 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 ONE Web Server 6.1 no longer supports 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.x legacy-style servlets to the web applications structure in Sun ONE Web Server 6.1 , the Sun ONE Web Server 6.1 Programmer’s Guide to Web Applications.

Search Migration

Because the search engine used in Sun ONE Web Server 6.0 has been replaced by a new search engine in Sun ONE Web Server 6.1, existing search collections and indexes are not migrated during the migration process. To use the Search functionality in Sun ONE Web Server 6.1, you will have to create and configure new search collections and indexes. For more details, see the Sun ONE Web Server 6.1 Administrator’s Guide.

Security

Sun ONE Web Server provides new flat file authentication and closer integration of native access control with web application security constraints. However, core authentication and authorization support is the same as in the version 6.0 release.

Sun ONE Web Server 6.1, apart from providing ACL-based authentication, also leverages the security model defined in the J2EE 1.3 Specification to provide several features that help you develop and deploy secure Java Web applications. The J2EE/Servlet-based access control infrastructure relies on the use of security realms.

In Sun ONE Web Server 6.1, authentication is performed by Java security realms which are configured through AUTHREALM entries in the server.xml file. Authorization is performed by access control rules in the deployment descriptor file, web.xml, in case any such rules have been set.

For more information about security-related features in Sun ONE Web Server 6.1, see the Sun ONE Web Server 6.1 Administrator’s Guide and the Sun ONE Web Server 6.1 Programmer’s Guide.

Session Managers

The Simple Session Manager and JDBC Session Manager that were deprecated in the version 6.0 release of Sun ONE Web Server are no longer supported in the 6.1 release.

The following API functions of the Sun ONE Web Server 6.1 session manager API are not implemented in Sun ONE Web Server 6.1:

For more information about Session Managers, see the Sun ONE Web Server 6.1 Programmer’s Guide to Web Applications.

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. Preferably, these links should not transverse any symbolic links.

Web Applications

In the 6.0 version of the Web Server, information pertaining to web applications was stored in the server.xml file and the web-apps.xml file. The web-apps.xml file is not supported in Sun ONE Web Server 6.1, and web application data is now stored in the following files:

The VS (virtual server) element in the server.xml file in Sun ONE Web Server 6.1 now contains a WEBAPP (web application) element for every web application it hosts. The attributes of the WEBAPP element are consistent with the mechanism used in Web Server 6.0 to configure web applications and are dynamically reconfigurable, that is, they don’t require a server restart in order for changes to be applied to the server instance.

For every web application, the deployment descriptor file, sun-web.xml, is created in the <web-application>/WEB-INF directory. The deployment descriptor file is based on the schema file, sun-web-app_2_3-1.dtd, which is compliant with the Servlet 2.3 specification. This schema file is also located in the <web-application>/WEB-INF directory.

In the 6.0 version of the Web Server, if you used the web-apps.xml file to tune certain server parameters, for example, reap interval (which specifies the number of seconds between checks for expired sessions), now, in Sun ONE Web Server 6.1, you would perform an identical function using the sun-web.xml deployment descriptor. Example:

For more information on the deployment descriptor files supported in Sun ONE Web Server 6.1, see the Sun ONE Web Server 6.1 Programmer’s Guide to Web Applications.

Web Publishing Using WebDAV

Sun ONE Web Server 6.1 introduces a new feature, web publishing through WebDAV (Web Distributed Authoring and Versioning), a protocol that enables in-place collaborative web publishing.

WebDAV functionality is configured by extending the VS element in the server.xml file to include two new elements, DAV and DAVCOLLECTION.

New functions have been added to the obj.conf file to support WebDAV functionality as an NSAPI plug-in.

For more information on the WebDAV feature, see the Sun ONE Web Server 6.1 Administrator’s Guide. For more information on WebDAV functions in the obj.conf file, see the Sun ONE Web Server 6.1 NSAPI Programmer’s Guide. For more information on WebDAV-related elements in the server.xml file, see the Sun ONE Web Server 6.1 Administrator’s Configuration File Reference.

Chapter 5 Migrating from Version 6.0 to 6.1