Previous Contents Index Next
Sun ONE Web Server 6.1 Installation and Migration Guide

> ## Chapter 5
> Migrating from Version 6.0 to 6.1

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

> This chapter contains the following information:

> - Migration Overview
> - Migrating Settings and Data
> - What Does Not Get Migrated
> - Overview of Changes in Sun ONE Web Server 6.1

> Note | If you have the Sun Java™ Enterprise System 1 installed on your system and you want to upgrade the Sun ONE Web Server 6.1 that is part of Sun Java Enterprise System 1 to Sun ONE Web Server 6.1 SP2, you must use the Java Enterprise System (JES) installer to perform the upgrade. Do not use the separate component installer included with Sun ONE Web Server 6.1 SP2.

> ##

> Migration Overview

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

> - Document roots
> - Configuration styles information
> - Virtual server settings
> - Access Control List (ACL) information
> - Secure Socket Layer (SSL) information
> - Certificates and keys
> - NSAPI information
> - JavaServer Pages (JSPs)
> - Server Side HTML (SHTML)
> - Simple Network Management Protocol (SNMP) settings (the snmp.conf file)
> - The file cache tuning configuration settings (the nsfc.conf file)

> ##

> Migrating Settings and Data

> Caution | Shut down all server instances before migrating.

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

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

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

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

> Select a Server to Migrate

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

> Specify the migration parameters

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

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

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

> The migration process does not migrate the following:

> - 4.x-style legacy servlets

> See Legacy Servlets for more information.

> - Search collections and indexes

> See Search Migration for more information.

> - Command Line scripts

> See Command Line Scripts for more information.

> - Cron-control settings

> See Cron Control for more information.

> - Certificate mappings

> See certmap.conf for more information.

> - Some configuration files

> See the sections Configuration Files and Configuration Files Removed in Sun ONE Web Server 6.1 for more information.

> - Simple Session Manager and JDBC Session Manager

> See Session Managers for more information.

> - Connection Group settings in server.xml

> See Connection Groups Settings for more information.

> - CGIstub directory

> See Cgistub Directory for more information.

> ##

> 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
> - Command Line Scripts
> - Configuration Files
> - Connection Groups Settings
> - Cron Control
> - Java Migration
> - Java Server Pages
> - Legacy Servlets
> - Search Migration
> - Security
> - Session Managers
> - Symbolic Links in Configuration Files (UNIX and Linux)
> - Web Applications
> - Web Publishing Using WebDAV

> ### 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/userdb/ 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:

> - rules.properties
> - context.properties
> - servlet.properties
> - start-jvm
> - jvm12.conf
> - web-apps.xml
> - web-apps.xml.clfilter
> - webpub.conf
> - webpub.conf.clfilter

> ### 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 information 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

> Sun ONE Web Server 6.1 supports the Servlet 2.3 specification.

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

> Sun ONE Web Server 6.1 provides the following session management options:

> - StandardManager, the default session manager
> - PersistentManager, a provided session manager that uses a persistent data store
> - IWSSessionManager, a provided session manager that allows backward compatibility with any custom session managers you may created using Sun ONE Web Server 6.0.
> - MMapSessionManager (UNIX Only), a provided persistent memory map (mmap) file based session manager that works in both single process and multi-process mode

> 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:

> - Form-based logins. Form-based login for single sign on is no longer supported. The following are therefore deprecated:
> - GetHandleFormLoginSession
> - SetHandleFormLoginSession
> - The update method. The update method which followed a call to the HttpRequest methods, inputstream, in version 6.0 of the Web server is now deprecated.
> - Session manager monitoring mechanism. Sun ONE Web Server 6.1 does not provide support for monitoring session manager statistics. The following are therefore deprecated:
> - getContext
> - getMaxSession
> - getSessionCount
> - getSessionReapCount
> - SimpleSessionManager and JdbcSessionManager. Web Server 6.0 provided deprecated support to the SimpleSessionManager and JdbcSessionManager options, and implemented the same functionality through iWSSessionManager and JdbcStore, respectively. The SimpleSessionManager and JdbcSessionManager options are not supported 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:

> - server.xml
> - web.xml
> - sun-web.xml
> - obj.conf

> 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:

> In Web Server 6.0:

> <init-param>

> <param-name>reapInterval</param-name>

> <param-value>180</param-value>

> </init-param>

> In Web Server 6.1:

> <sun-web-app>

> ...

> <session-config>

> <session-manager>

> <manager-properties>

> <property name=”reapIntervalSeconds” value=”180”/>

> </manager-properties>

> </session-manager>

> ...

> </session-config>

> ...

> </sun-web-app>

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

> Previous Contents Index Next

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.