Chapter 5 Migrating to Web Server 7.0

This chapter describes the migration of Web Server 6.0 and 6.1 configurations to Sun Java System Web Server 7.0.

This chapter contains the following sections:

• Migration Overview

• What Is and Is Not Migrated

• Files Requiring Manual Migration

• Configuration File Changes

• Other Migration-Related Changes

• Migrating From Web Server 6.0 and 6.1 to Web Server 7.0

• Verifying Migration

• Viewing the Migration Log File

• Creating a Server Instance from the Migrated Configuration

• Updating Your Sun Java Enterprise System Installation

Migration Overview

Sun Java System Web Server 7.0 enables you to migrate server instances from Web Server 6.0 and 6.1 to Web Server 7.0. For a general overview of this terminology and distinction, see New Administration Framework.

You must first migrate the Web Server 6.0 and 6.1 instance to create a Web Server 7.0 configuration. The Web Server 7.0 configuration is then used to create a Web Server 7.0 instance. Web Server 7.0 includes a new command-line interface for migration, so migration can now be performed either from the graphical interface or from the command line. See Migrating Using the Graphical Interface or Migrating Using the Command-Line Interface for specific procedures.

The server being migrated and the Web Server 7.0 Administration Server must reside on the same host. However, an instance can be created on an associated remote node.

Only Web Server 6.0 and 6.1 instances can be migrated. Direct migration from a Web Server version lower than 6.0 is not supported. Older versions such as iPlanet^TM Web Server 4.0 and Sun ONE Web Server 4.1 must first be migrated to Web Server 6.1, then to Web Server 7.0. After migrating from iPlanet Web Server 4.0 and Sun ONE Web Server 4.1, ensure that Web Server 6.1 works fine, then migrate to Web Server 7.0. For information about migrating from iPlanet Web Server 4.0 and Sun ONE Web Server 4.1, see the latest Sun Java System Web Server 6.1 Installation and Migration Guide and Release Notes at http://docs.sun.com/app/docs/prod/s1.websrv61#hic.

Detailed migration information is provided during and after the migration process in the migration log file. It lists the settings and configurations that were and were not migrated, warns about required manual changes, and indicates whether the migration succeeded or failed. For more information about this file, see Viewing the Migration Log File. Many but not all settings are migrated, as described in What Is and Is Not Migrated.

A configuration is created during the migration process. Following migration, the configuration is available in the install_dir/admin-server/config-store directory. As mentioned earlier, Web Server 7.0 server instances are created from these configurations using either the administration GUI or CLI. If a configuration exists with the same name, -x is added to config_name, where x is an integer.

What Is and Is Not Migrated

Many but not all settings are migrated. This section lists what is and is not migrated during migration.

What Is Migrated

The following are migrated by the migration tool:

• ACL Files

• Configuration files

• Scheduler settings

• Configuration settings for file cache tuning

• Key & cert databases and certificate mappings

• Listen socket settings

• Mime files

• NSAPI information

• SHTML settings

• SNMP settings

• SSL information

• User databases

• Virtual server settings

• Web applications (see Web Applications for more information)

• WebDAV settings, but not the physical collections and locks (see WebDAV for more information)

• Web Server 6.1 search collections informations. see Search for more information)

What Is Not Migrated

The following are not migrated by the migration tool:

• CGI directories

• Command-line scripts

• The docroot directory

• Legacy servlets

• Log files

• Simple Session Manager and Java^TM DataBase Connectivity (JDBC^TM) Session Manager

• User libraries

• WebDAV physical collections and locks

• Web Server 6.0 search configurations and collections. (see Search for more information)

Files Requiring Manual Migration

Command-line scripts are not migrated to Web Server 7.0. The default command-line scripts will be created, and you must make any necessary changes in the relevant Web Server 7.0 command-line scripts.

The following command-line scripts are not migrated:

• startsvr, startsvr.bat

• stopsvr, stopsvr.bat

• restart

• reconfig, reconfig.bat

Configuration File Changes

In previous releases, server configuration was spread over multiple files. In Web Server 7.0, server configuration has been consolidated for better manageability. Many changes have been made to consolidate instance-specific configuration files in the config directory and to simplify and enhance existing configuration files. In general, no new configuration files have been added, some configuration files have been removed, and significant changes have been made to files carried forward from previous releases, such as server.xml and magnus.conf.

Some configuration file changes are briefly mentioned here but are not described in detail. For complete information about configuration file changes in Web Server 7.0, see the Web Server 7.0 Administrator's Configuration File Reference.

Configuration Files Removed

The following configuration files have been removed in Web Server 7.0:

• dbswitch.conf

• nsfc.conf

• scheduler.conf

• schedulerd.conf

• snmp.conf

For more information, see File Layout Changes.

File Layout Changes

The following table lists file layout changes between Web Server 6.1 and 7.0. These changes are made automatically during migration.

For information about changes between Web Server 6.0 and 6.1, see the latest Sun Java System Web Server 6.1 Installation and Migration Guide and Release Notes at http://docs.sun.com/app/docs/prod/s1.websrv61#hic.

Other Migration-Related Changes

The following sections contain information on other migration-related changes when moving from Web Server 6.1 to Web Server 7.0. These changes are made automatically during migration.

Config Store Directory

As described in New Administration Framework, Web Server 7.0 makes it easier to manage Web Server configurations across hardware nodes in a server farm. This administration framework provides necessary services to graphical and command-line clients to manage server configurations, and to replicate configurations across nodes within data centers or server farms.

Do not edit any files under config-store directory. The files under this directory are created by Sun Java System Web Server for internal use.

Metadata for the configurations managed by the administration infrastructure is stored within a directory called config-store, under the root directory of the Administration Server instance. When a server is migrated, data is transferred and a configuration is created under config-store. Configuration files, applications, and other elements that are part of a configuration are stored in config-store, as are search collections if a different search collection index directory is not specified during migration (for more information, see Search). Web Server 7.0 instances are created from these configurations.

For more information about the config-store directory structure and about configuration files, see the Web Server 7.0 Administrator's Configuration File Reference. For more information about managing Web Server configurations in data centers and server farms, see the Sun Java System Web Server 7.0 Administrator’s Guide.

JNDI and JDBC

The following table lists changes related to Java Naming and Directory Interface (JNDI^TM) and JDBC.

Legacy Servlets

There are no changes to this functionality from Web Server 6.1 to Web Server 7.0.

Log Files

Log files are not migrated.

Search

When migrating search, necessary server.xml changes are made and the collections directory from the Web Server 6.1 server instance is moved to the search collection index directory specified during migration. If the directory is not specified, the search collection will not be migrated.

Also note the following considerations:

• The document root for search collections is not migrated and must be changed manually.

• Web Server 6.1 search collections are migrated, but Web Server 6.0 collections are not migrated.

The following table lists other changes related to search.

Security

The following table lists changes related to security.

Session Manager

There are no changes to this functionality from Web Server 6.1 to Web Server 7.0.

User Libraries

User libraries are not migrated. A warning message is recorded in the migration log file.

Web Applications

The following table lists changes related to web applications.

WebDAV

The following table lists changes related to WebDAV.

acl uri=/magnus-internal/";
deny (all) user="anyone";
allow (list) user="all";

Migrating From Web Server 6.0 and 6.1 to Web Server 7.0

This section describes how to migrate Web Server 6.0 and 6.1 to Web Server 7.0 using both the graphical and the command-line interfaces. Note the following considerations:

• The server being migrated and the Web Server 7.0 Administration Server must reside on the same host.

• Commit all pending configuration changes made to the Sun ONE Web Server 6.0 and 6.1 instance through the Administration Server console GUI before migrating the instance.

• Confirm that the existing Sun ONE Web Server 6.0 and 6.1 instance is working correctly before migrating the instance.

• Stop the server you are migrating before the migrating settings.

• If migrating from a Web Server version lower than 6.0, you must first migrate your legacy server to Web Server to 6.1, and then to Web Server 7.0. Direct migration from versions lower than 6.0 is not supported. After migrating from iPlanet Web Server 4.0 to 6.1, ensure that Web Server 6.1 works, then migrate to Web Server 7.0.

To Migrate From Non-Supported Linux Version

Sun Java System Web Server 7.0 supports Red Hat 3.0 Enterprise Server, Red Hat 4.0 Enterprise Server, and SUSE 9 Enterprise.

If you are using a non-supported Linux version, you must perform one of the following tasks to upgrade to the Sun Java System Web Server 7.0. You can perform the following task in Java ES environment as well.

1. Stop the Web Server 6.0 or 6.1 instances.

2. Upgrade the Linux operating system to one of the Sun Java System Web Server 7.0 supported Linux versions.

3. Migrate the Web Server 6.0 or 6.1 instances to Sun Java System Web Server 7.0.

   ---

   Note –

   You must upgrade the Linux operating system to one of the supported versions.

   ---

or

1. Archive the Web Server 6.0 or 6.1 installation directory, including all necessary resources like document root, libraries, and web applications.

2. Extract the archive to the system running Sun Java System Web Server 7.0.

3. Migrate the extracted Web Server 6.0 or 6.1 instances to Sun Java System Web Server 7.0.

   ---

   Note –

   Ensure that the directory structure is the same as in Web Server 6.0 or 6.1.

   ---

Resolving Service ID Conflicts on Windows

On Windows, creating an instance for any configuration registers a service-id with Windows services. If the service-id exists, there is a service-id conflict and the instance creation fails. For example, you might migrate a 6.0 or 6.1 instance named foo. If the foo service-id exists, the creation fails.

To avoid the conflict, during migration, change the configuration name using either the CLI or the Admin Console. Another option is to copy the configuration to a new configuration that uses a unique service-id. Use either the wadm> copy-config command, or the Copy button on the Admin Console Configurations page to copy the configuration.

Migrating Using the Graphical Interface

The following procedure describes how to migrate server instances using the graphical interface. There are two distinct phases to the migration process. You first migrate data from a 6.0 or 6.1 instance to create a Web Server 7.0 configuration, and then deploy that configuration on a node to create a Web Server 7.0 instance.

For detailed information about these and other tasks performed using the Administration Server console, see the Sun Java System Web Server 7.0 Administrator’s Guide.

To Migrate Using the Graphical Interface

1. Access the Administration Server console and click the Configurations tab.

2. In the Configuration Tasks table on the resulting Tasks screen, click Migrate Configuration.

   The Migrate Instances Wizard displays.

3. In the wizard:

   1. Supply the absolute path to the installation directory of the 6.0 or 6.1 Web Server you want to migrate, then click Next.

   2. The Instances selection screen appears.

   This wizard creates a configuration in the config-store directory of the Web Server 7.0 Administration Server. You will then use this configuration to create a server instance, as described in the following steps.

   ---

   Note –

   Before creating the instance from the migrated configuration, it is imperative that you review the migration log file and fix any issues. For information about accessing the migration log, see Viewing the Migration Log File.

   ---

4. In the Configuration Tasks table on the Tasks screen, click New Instance.

   The New Instance Wizard displays.

5. In the wizard:

   1. Select the configuration you migrated and click Next.

   2. Select the nodes on which to create an instance of the configuration and click Next.

      ---

      Note –

      If you want to migrate to another host than while creating an instance select the remote node.

      ---

   3. Verify the information on the summary page and click Finish.

6. Start the migrated server and ensure that the server is working properly.

Migrating Using the Command-Line Interface

The migrate-server command is used to migrate server instances and create Web Server 7.0 configurations using the administration command-line interface (CLI).

The wadm utility is located in install_dir/bin. For detailed information about using the administration CLI, see the man pages and the Sun Java System Web Server 7.0 CLI Reference Manual document. For basic information that will help you get started, also see Using the Administration Command-Line Interface in this document.

The migrate-server syntax is as follows:

wadm> migrate-server [--user=admin-user] [--passwordfile=admin-pswd-file][--host=admin-host][--port=admin-port][--no-ssl][--rcfile=rcfile][--echo][--no-prompt][--verbose][--search-collection-copy-path=directory][--log-dir=directory]([--all|[--config=newconfigname[--instance=instancename]) --server-root=path

The following examples demonstrate how to use the command-line interface to migrate one or several server instances.

Migrating a Single Instance

The following is an example of using the CLI to migrate a single instance from Sun ONE Web Server 6.0 or 6.1 to 7.0 using the same name for the migrated configuration as the 6.0 or 6.1 instance :

wadm> migrate-server [--user=admin-user] [--passwordfile=admin-pswd-file][--host=admin-host][--port=admin-port][--no-ssl][--rcfile=rcfile][--echo][--no-prompt][--verbose][--search-collection-copy-path=directory][[--log-dir=directory]([--all|[--config=newconfigname[--instance=instancename]) --server-root=path

--instance=instance_name
--server-root=6.xwebserver_install_root

where, for example, 6.xwebserver_install_root might be/opt/SUNWwbsvr and instance_name might be https-foo.com.

The following is an example of migrate a single instance from Sun ONE Web Server 6.0 or 6.1 to 7.0 using a different name from the 6.0 or 6.1 instance for the migrated configuration:

wadm> migrate-server [--user=admin-user] [--passwordfile=admin-pswd-file][--host=admin-host][--port=admin-port][--no-ssl][--rcfile=rcfile][--echo][--no-prompt][--verbose][--search-collection-copy-path=directory][[--log-dir=directory]([--all|[--config=newconfigname[--instance=instancename]) --server-root=path

--instance=instance_name
--config=new-foo
--server-root=6.xwebserver_install_root

where, for example, 6.x webserver_install_root might be/opt/SUNWwbsvr and instance_name might be https-foo.com.

The following is an example to migrate single instance from Sun ONE Web Server 6.0 or 6.1 to 7.0 using a different name from the 6.0 or 6.1 instance for the migrated configuration.

wadm> migrate-server [--user=admin-user] [--passwordfile=admin-pswd-file][--host=admin-host][--port=admin-port][--no-ssl][--rcfile=rcfile][--echo][--no-prompt][--verbose][--search-collection-copy-path=directory][[--log-dir=directory]([--all|[--config=newconfigname[--instance=instancename]) --server-root=path

--instance=instance_name
--config=new-foo
--server-root=6.xwebserver_install_root

where, for example, 6.x webserver_install_root might be/opt/SUNWwbsvr and instance_name might be https-foo.com.

The following is an example of migrate single instance from Sun ONE Web Server 6.0 or 6.1 to 7.0 using a different name from the 6.0 or 6.1 instance for the migrated configuration.

wadm> migrate-server [--user=admin-user] [--passwordfile=admin-pswd-file][--host=admin-host][--port=admin-port][--no-ssl][--rcfile=rcfile][--echo][--no-prompt][--verbose][--search-collection-copy-path=directory][--log-dir=directory]([--all|[--config=newconfigname[--instance=instancename]) --server-root=path

--instance=instance_name
--config=new-foo
--search-collection-copy-path=custom_path
--server-root=6.xwebserver_install_root

where, for example, 6.x webserver_install_root might be/opt/SUNWwbsvr and instance_name might be https-foo.com.

The following is an example of migrate single instance from Sun ONE Web Server 6.0 or 6.1 to 7.0 using a different name from the 6.0 or 6.1 instance for the migrated configuration. Specify a different log directory for migration logs:

wadm> migrate-server [--user=admin-user] [--passwordfile=admin-pswd-file][--host=admin-host][--port=admin-port][--no-ssl][--rcfile=rcfile][--echo][--no-prompt][--verbose][--search-collection-copy-path=directory][[--log-dir=directory]([--all|[--config=newconfigname[--instance=instancename]) --server-root=path

--instance=instance_name
--config=new-foo
--search-collection-copy-path=custom_path
--log-dir=log_path
--server-root=6.xwebserver_install_root

where, for example, 6.x webserver_install_root might be/opt/SUNWwbsvr and instance_name might be https-foo.com.

Migrating All Instances

The following is an example of using the CLI to migrate all instances from Sun ONE Web Server 6.0 or 6.1 to 7.0:

wadm> migrate-server [--user=admin-user] [--passwordfile=admin-pswd-file][--host=admin-host][--port=admin-port][--no-ssl][--rcfile=rcfile][--echo][--no-prompt][--verbose][--search-collection-copy-path=directory][[--log-dir=directory]([--all|[--config=newconfigname[--instance=instancename]) --server-root=path

-all=true
--server-root=6.xwebserver_install_root

where, for example, 6.x webserver_install_root might be/opt/SUNWwbsvr.

Verifying Migration

To verify migration:

• Review the task completion message, indicating whether migration did or did not take place.

• Review the migration log file, accessed as described in Viewing the Migration Log File. This file contains detailed information about the migration and any files or components that must be migrated manually.

  ---

  Note –

  It is imperative that you review this information and fix any issues before creating a server instance from the migrated configuration.

  ---

• Verify that the configuration was created.

• After reviewing the migration log and fixing any issues, deploy the migrated configuration onto a node and start the server. The server should start without any problems.

Viewing the Migration Log File

Detailed migration information is provided during and after the migration process, listing the settings and configurations that were and were not migrated, warning about changes that need to be made manually, and indicating whether the migration succeeded or failed. This information is recorded in the migration log file. The syntax for the migration log file is as follows:

MIGRATION_yyyymmddhhmmss.log

For example, if the log directory specified during installation (--logdir) is /ws7, and the migration process was started on 01/08/2006 at 11:16 PM, the following file is created under the /ws7 directory: MIGRATION_20060108111600.log. If no log directory was specified during installation, the file with the same name is created under the install_dir/admin-server/logs directory.

If you select the All Instances Migration option, all the instances migration log are stored in the same migration log file.

Creating a Server Instance from the Migrated Configuration

The create-instance command creates the Web Server instance from the configuration. So if migrate-server creates a configuration called foo, the create-instance command creates the instance https-foo using the configuration install_dir/admin-server/config-store/foo in the specified node. The syntax is create-instance --config=config_name host_name.domain_name.

The migrate-server CLI command removes the prefix https- from the old instance and uses that name as the configuration name, while the create-instance command adds the prefix https- to the configuration name and uses that name as the instance name.

Updating Your Sun Java Enterprise System Installation

Sun Java System Web Server can be purchased by itself (stand-alone) or as a component of Sun Java Enterprise System (Java ES). With the exception of this migration chapter, most of the information in this guide pertains only to the stand-alone Web Server. For information about upgrading Web Server from a previous Java ES release to Sun Java Enterprise System Web Server (Java ES Release 5), see the Sun Java Enterprise System Upgrade Guide in the Java ES system documentation at http://docs.sun.com/app/docs/prod/entsys#hic.