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

Chapter 3 Upgrading an Application Server Installation

You can upgrade to Application Server 9 Platform Edition from 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 Application Server upgrades, where PE indicates Platform Edition and EE indicates Enterprise Edition.

Table 3–1 Supported Upgrade Paths

Source Installation  

9 Platform Edition  


Not supported 


Not applicable 


Not applicable 



8.0 EE 

Not applicable 

8.1 PE 


8.1 EE  

Not applicable 

8.2 PE  


8.2 EE 

Not applicable 

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 an Upgrade Wizard, for completing the upgrade. If you issue the asupgrade command with no options, the Upgrade Wizard 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 8.x environment do not require any modification to run on Application Server 9.

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.

Upgrading Through the Command Line

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

[--console ] 
[--version ] 
[--help ] 
[--source applicationserver_8.x_installation] 
[--target applicationserver_9_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] 

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  




Launches the upgrade command line utility. 



The version of the Upgrade tool. 



Displays the arguments for launching the upgrade utility. 



The installation directory for Application Server 8.2. 



The username of the administrator. 



The password for the adminuser. Although this option can be used, the recommended way to transmit passwords is by using the -passwordfile option.



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. 



The path to the file that contains the adminpassword and masterpassword. Content of this file should be in the following format:





The domain name for the migrated certificates. 



The path to the NSS password file. 



The path to the target NSS password file. 



The path to the JKS password file. 



The path to the CA certificate password file. 

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

Example: Upgrading an Application Server 8.0 installation to Application Server 9 with Prompts for Certificate Migration.

This example shows how to upgrade an Application Server 8.0 installation to Application Server 9. 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/sunas8.1 --target /home/sjsas9

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

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

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

Upgrading Through the Wizard

The Upgrade wizard provides a GUI, however, 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:

ProcedureTo Use the Upgrade Wizard

  1. 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 8.0, Application Server 8.1, or Application Server 8.2.

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

  3. 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 Transfer Security Certificates screen displays.

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

    The Add Domain dialog displays.

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

  6. Click the OK button when done.

    The Transfer Security Certificates screen will be displayed again.

  7. Repeat steps 4 through 6 until all the domains that have certificates to be transferred have been added.

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

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

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

Correcting Potential Upgrade Problems

This section addresses issues that could occur during an upgrade to Application Server 9 and explains how you can correct them.

To Transfer JVM Options

When you upgrade from a previous version of the application server, transfer of the previous configuration is required. Since the target configuration files may have new parameters and new preconfigured features, copying the old configuration files to the new server installation is not possible. The values of the old configurations must be transferred to the Application Server 9 configuration format.

The following JVM options are not transferred from the source to the target installation:

The options that are not transferred are listed down in the upgrade log. The user can manually change such attributes, in the configuration file, if needed.

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

  1. Start the Admin Console.

  2. Expand Configuration.

  3. Expand HTTP Service.

  4. Expand Virtual Servers.

  5. Select <server>.

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

  7. Click Save when done.