Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Upgrade and Migration Guide

Chapter 3 Upgrading an Application Server Installation

You can upgrade to Sun Java System Application Server 8.1 (hereafter called Application Server) from Sun Java(TM) System Application Server 7.x (formerly Sun ONE(TM) Application Server 7.x) or a Sun Java System Application Server 8.x Platform Edition installation. Information that is transferred includes data about deployed applications, the file realm, security certificates, and other resource and server configuration settings. You can install your upgrade in a new location, or you can upgrade in place by overwriting your previous installation.

This chapter discusses the following topics:

Upgrade Overview

The following table shows supported Sun Java System Application Server upgrades, where PE indicates Platform Edition and EE indicates Enterprise Edition.

Table 3–1 Supported Upgrade Paths


Source Installation	8.1Platform Edition	8.1 Enterprise Edition
7.XPE	X	X
7.XSE		X
7.XEE		X
8.0PE	X	X
8.1PE		X

Note –

Before starting the upgrade process, make sure that both the source server (the server from which you are upgrading) and the target server (the server to which you are upgrading) are stopped.

The software provides two methods, a command-line utility (asupgrade) and a graphical user interface (Upgrade Wizard), for completing the upgrade. If you issue the asupgrade command with no options, the Upgrade Wizard GUI will be displayed. If the asupgrade command is used in command-line mode and all of the required information is not supplied, an interviewer will request information for any required options that were omitted. The Upgrade Wizard automatically detects the version of the specified source server installation.

If a domain contains information about a deployed application and the installed application components do not agree with the configuration information, the configuration will be migrated as is without any attempt to reconfigure the incorrect configurations.

During an upgrade, the configuration and deployed applications of a previous version of the Application Server are migrated; however, the runtime binaries of the server are not updated. Database migrations or conversions are also beyond the scope of this upgrade process.

Only those instances that do not use Sun Java SystemWeb Server-specific features will be upgraded seamlessly. Configuration files related to HTTP path, CGI bin, SHTML, and NSAPI plug-ins will not be upgraded.

Application archives (EAR files) and component archives (JAR, WAR, and RAR files) that are deployed in the Application Server 7.x/8.0 environment do not require any modification to run on Application Server 8.1.

Applications and components that are deployed in the source server are deployed on the target server during the upgrade. Applications that do not deploy successfully on the target server must be migrated using the Migration Tool or asmigrate command, then deployed again manually.

If the upgrade includes clusters, specify one or more cluster files. Upon successful upgrade, an upgrade report is generated listing successfully migrated items along with a list of the items that could not be migrated.

This chapter discusses the following topics:

Upgrading Through the Upgrade Utility

The upgrade utility is run from the command line using the following syntax:

asupgrade 
[--console ] 
[--version ] 
[--help ] 
[--source applicationserver_7.x/8.x_installation] 
[--target applicationserver_8.1_installation] 
--adminuser admin_user 
[--adminpassword admin_password] 
[--masterpassword changeit] 
[--passwordfile path_to_password_file] 
[--domain domain_name] 
[--nsspwdfile NSS_password_filepath] 
[--targetnsspwdfile target_NSS_password_filepath] 
[--jkspwdfile JKS_password_filepath] 
[--capwdfile CA_password_filepath] 
[--clinstancefile file1 [, file2, file3, ... filen]]

The following table describes the command options in greater detail, including the short form, the long form, and a description.

Table 3–2 asupgrade Utility Command Options


Short Form	Long Form	Description
-c	---console	Launches the upgrade command line utility.
-V	---version	The version of the Upgrade Tool.
-h	---help	Displays the arguments for launching the upgrade utility.
-t	---target	The installation directory for Sun Java System Application Server 8.1.
-a	---adminuser	The username of the administrator.
-w	---adminpassword	The password for the adminuser. Although this option can be used, the recommended way to transmit passwords is by using the -passwordfile option.
-m	--masterpassword	The master password that is created during installation. The default value is changeit. Although this option can be used, the recommended way to transmit passwords is by using the --passwordfile option. Note: This option is required only if your target server is Application Server 8.1 EE.
-f	--passwordfile	The path to the file that contains the adminpassword and masterpassword. Content of this file should be in the following format: AS_ADMIN_ADMINPASSWORD=adminpassword AS_ADMIN_MASTERPASSWORD=masterpassword
-d	--domain	The domain name for the migrated certificates.
-n	--nsspwdfile	The path to the NSS password file.
-e	--targetnsspwdfile	The path to the target NSS password file.
-j	--jkspwdfile	The path to the JKS password file.
-p	--capwdfile	The path to the CA certificate password file.
-i	--clinstancefile	The path to the cluster file. The default filename is $AS_INSTALL/conf/clinstance.conf.

The following examples show how to use the asupgrade command-line utility to upgrade an existing application server installation to Application Server 8.1.

Example 1: Upgrading an Application Server 7 Installation to Application Server 8.1 with Prompts for Certificate Migration.

This example shows how to upgrade a Sun Java SystemApplication Server 7 installation to Sun Java System Application Server 8.1. You will be prompted to migrate certificates. If you reply no, then no certificates will be migrated.

asupgrade --adminuser admin --passwordfile password.txt
 --source /home/sunas7 --target /home/sjsas8.1

Example 3: Upgrading an Application Server 7 PE Installation with NSS Certificates to Application Server 8.1 PE

This example shows how to upgrade a Sun Java System Application Server 7 PE installation to Sun Java System Application Server 8.1 PE. The NSS certificates from the 7.0 PE source server will be converted to JKS and CA certificates in the 8.1 PE target server.

asupgrade --adminuser admin --passwordfile password.txt 
--source /home/sjsas7.0 
--target /home/sjsas8.1 
--domain domain1 
--nsspwdfile /home/sjsas7.0/nsspassword.txt 
--jkspwdfile /home/sjsas7.0/jkspassword.txt 
--capwdfile /home/sjsas7.0/capassword.txt

Example 4: Upgrading an Application Server 8.0 PE Installation with JKS and CA Certificates to Application Server 8.1 PE

This example shows how to upgrade a Sun Java System Application Server 8.0 PE installation to Sun Java System Application Server 8.1 PE. JKS and CA certificates will be migrated.

asupgrade --adminuser admin --passwordfile password.txt 
--source /home/sjsas8.0 
--target /home/sjsas8.1 
--domain domain1 
--jkspwdfile /home/sjsas8.0/jkspassword.txt 
--capwdfile /home/sjsas8.1/capassword.txt

Upgrading Through the Wizard

The Upgrade wizard provides a graphical user interface (GUI). Using the wizard increases install time and space requirements. You can start the Upgrade wizard in GUI mode from the command line or from the desktop.

To start the wizard,

- On UNIX, change to the <install_dir>/bin directory and type asupgrade.

- On Windows, double-click the asupgrade icon in the <install_dir>/bin directory.

If the Upgrade checkbox was selected during the Application Server installation process, the Upgrade Wizard screen will automatically display after the installation completes.

From the Upgrade Wizard screen:

To Use the Upgrade Wizard

Steps

In the Source Installation Directory field, enter the location of the existing installation from which to import the configuration.

This installation can be Sun Java System Application Server 7 (formerly Sun ONE^TM Application Server 7) or Sun Java System Application Server 8.x .

In the Target Installation Directory field, enter the location of the Application Server installation to which to transfer the configuration.

If the upgrade wizard was started from the installation (the Upgrade from Previous Version checkbox was checked during the Application Server installation), the default value for this field will be the directory to which the Application Server software was just installed.

If you are upgrading Sun Java System Application Server 7.1 Enterprise Edition installation with clusters and no security certificates to Sun Java System Application Server 8.1 Enterprise Edition, press the Next button and continue with Upgrading Through the Wizard.

All other upgrades without certificates continue with Upgrading Through the Wizard. Continue with Step 4 if security certificates need to be transferred.

If the source installation has security certificates that must be transferred, check the Transfer Security Certificates checkbox, press the Next button, and the

The Transfer Security Certificates screen displays.

From the Transfer Security Certificates screen, press the Add Domain button to add domains with certificates to be transferred.

The Add Domain dialog displays.

From the Add Domain dialog, select the domain name that contains the security certificates to migrate and enter the appropriate passwords.

Click the OK button when done.

The Transfer Security Certificates screen will be displayed again.

Repeat Upgrading Through the Wizard and Upgrading Through the Wizard until all the domains that have certificates to be transferred have been added.

After all of the domains that contain certificates to be transferred have been added, press the Next button and

Continue with Upgrading Through the Wizard or with Upgrading Through the Wizard if cluster configuration information needs to be transferred.

If you are upgrading a Sun Java System Application Server 7.1 Enterprise Edition installation with clusters to Sun Java System Application Server 8.1 Enterprise Edition, the Transfer Cluster Configurations screen will be displayed. Press the Add Cluster button.

The Select clinstance.conf file dialog box will be displayed. Choose clinstance.conf file and click the Open button. The clinstance.conf file will be added to the list.

Enter the cluster file name, which contains the cluster configuration information to be migrated.

Repeat this process until all the cluster configuration files that need to be migrated have been added, then press the Next button.

The Upgrade Results screen displays, showing the status of the upgrade operation in the Results field.

Click the Finish button to close the Upgrade Tool when the upgrade process is complete.

Correcting Potential PE and Upgrade Problems

This section addresses the following issues that could occur during an upgrade to Application Server 8.1:

To Migrate Additional HTTP Listeners Defined on the Source Server to the Target PE Server

If additional HTTP listeners have been defined in the PE source server, those listeners need to be added to the PE target server after the upgrade:

Steps

Start the Admin Console.

Expand Configuration.

Expand HTTP Service.

Expand Virtual Servers.

Select <server>.

In the right hand pane, add the additional HTTP listener name to the HTTP Listeners field.

Click Save when done.

Eliminating Problems Encountered When A Single Domain has Multiple Certificate Database Passwords

If the upgrade includes certificates, provide the passwords for the source PKCS12 file and the target JKS keyfile for each domain that contains certificates to be migrated. Since Application Server 7 uses a different certificate store format (NSS) than Application Server 8 PE (JSSE), the migration keys and certificates are converted to the new format. Only one certificate database password per domain is supported. If multiple certificate database passwords are used in a single domain, make all of the passwords the same before starting the upgrade. Then reset the passwords after the upgrade has been completed.