Sun Java System Application Server Platform Edition 8.2 Upgrade and Migration Guide

Chapter 3 Upgrading an Application Server Installation

You can upgrade to Application Server 8.2 from Application Server 7.x or an Application Server 8/8.1 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 Application Server upgrades. In this table, PE indicates Platform Edition and EE indicates Enterprise Edition.

Table 3–1 Supported Upgrade Paths


Source Installation	8.2 Platform Edition
7.XSE	-
8.0PE	Supported
8.1PE	Supported
8.2PE	—

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 GUI (Upgrade Wizard), for completing the upgrade. If you issue the asupgrade command with no options, the Upgrade Wizard GUI is displayed. If you use theasupgrade command in command-line mode and if you do not supply all of the required information, an interviewer requests information for the required options you 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 is 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 Web Server-specific features are upgraded seamlessly. Configuration files related to HTTP path, CGI bin, SHTML, and NSAPI plug-ins are not be upgraded.

Enterprise Application Archive (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.2.

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.2_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 Application Server 8.2.
`-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.2 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.2

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

This example shows how to upgrade a Application Server 7 installation to Application Server 8.2. This command prompts you to migrate certificates. If you reply no, then no certificates are migrated.

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

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

This example shows how to upgrade a Application Server 7 PE installation toApplication Server 8.2 PE. The NSS certificates from the 7.0 PE source server are converted to JKS and CA certificates in the8.2 PE target server.

asupgrade --adminuser admin --passwordfile password.txt 
--source /home/sjsas7.0 
--target /home/sjsas8.2 
--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.2 PE

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

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

Upgrading Through the Wizard

The Upgrade wizard provides a 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 automatically displays after the installation completes.

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 Application Server 7 or Application Server 8/8.1 .

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 the source installation has security certificates that must be transferred, check the Transfer Security Certificates checkbox, press the Next button, and 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.

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 Upgrade Problems

This section addresses the following issues that could occur during an upgrade to Application Server 8.2.

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