The Upgrade tool, which is bundled with Application Server 8.2, replicates the configuration of a previously installed server in the target installation. The Upgrade tool assists in upgrading the configuration, applications, and certificate data from an earlier version of the Application Server to Application Server 8.2. To view a list of the older Application Server versions from which you can upgrade, refer Table 2–1
This chapter discusses the following topics:
The following table shows supported Sun Java System Application Server upgrades. In this table, PE indicates Platform Edition and EE indicates Enterprise Edition.
Table 2–1 Supported Upgrade Paths
Source Installation |
8.2 Platform Edition |
8.2 Enterprise Edition |
---|---|---|
7.X PE |
Not supported |
Supported |
7.XSE |
- |
Supported |
7.XEE |
- |
Supported |
8.0PE |
Supported |
Supported |
8.1PE |
Supported |
Supported |
8.1EE |
- |
Supported |
8.2PE |
- |
Supported |
Upgrading from 8.1 SE to 8.2 EE only involves installing the HADB packages. You do not need to use the upgrade tool .
The Upgrade tool can be launched by issuing the asupgrade command or by choosing the Upgrade option in the Application Server Installer.
You can use the tool through the command-line interface (CLI) or the GUI.
To use the Upgrade tool in GUI mode, issue the asupgrade command with no options.
To run the Upgrade tool in CLI mode, invoke the asupgrade command with the --c/--console option. You can run the upgrade CLI in the interactive or non-interactive mode. If you supply all required arguments when invoking asupgrade on the console, the upgrade is performed in non-interactive mode and no further input is required. For a complete list of asupgrade options, refer Table 2–2. If you invoke the tool only with the --c/--console option, the tool enters the interactive CLI mode, where the user is asked for a series of inputs.
The following are important terms related to the upgrade process:
Source Server: the installation from which you are upgrading to the new version.
Domains Root : the directory where the domains are created. This directory, by default, is the location specified as AS_DEF_DOMAINS_PATH in asenv.conf
Domain Directory or domain-dir: the directory (within the Domains Root) corresponding to a specific domain. All the configuration and other data pertaining to the domain exists in this directory.
Install Root: the directory where the Application Server is installed.
Administration User Name: Name of the user who administers the server. This term refers to the admin user of the Application Server installation from which you want to upgrade.
Password: Administration user’s password to access the Domain Administration Server (DAS)(8-character minimum) of the Application Server installation from which you want to upgrade.
Master Password: SSL certificate database password used in operations such as Domain Administration Server startup. This term refers to the master password of the Application Server installation from which you want to upgrade.
The Upgrade Tool migrates the configuration, deployed applications, and certificate databases from an earlier version of the Application Server to the current version. The Upgrade Tool does not upgrade the binaries of the Application Server. The installer is responsible for upgrading the binaries. Database migrations or conversions are also beyond the scope of this upgrade process.
Only those instances that do not use Sun Java System Web Server-specific features are upgraded seamlessly. Configuration files related to HTTP path, CGI bin, SHTML, and NSAPI plug-ins are not be upgraded.
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.
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.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, and deployed again manually. For information on migrating applications using the Migration Tool, refer Chapter 6, Migrating from Application Server 6.x/7.x.
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.
While upgrading a configuration containing clusters inApplication Server 7.x, specify one or more cluster files or the clinstance.conf files. In Application Server 8.x, the clusters are defined in the domain.xml file and there is no need to specify separate clusters. Another notable difference is that in Application Server 8.x, all the instances within a cluster reside within the same domain and therefore, in the same domain.xml file. In Application Server 7.x, the instance forming a cluster could span more than one domain.
The Upgrade tool transfers certificates from the source certificate database to the target. The tool supports conversion of JKS certificates to NSS certificates. The tool transfers security policies, password files from standard, file-based realms, and custom realm classes. Refer Before You Upgrade for specific requirements for providing passwords for the certificate databases.
An upgrade log records the upgrade activity. The upgrade log file is named as the upgrade.log and is created in the domains root where the upgrade is carried out.
If an upgrade in progress is cancelled, the configuration before the upgrade was started is restored.
The following are the three scenarios in which an upgrade is performed:
Side-by-side Upgrade: The source server and the target server are installed on the same machine , but under different install locations. You can choose to perform this type of upgrade if you wish to have the configuration corresponding to these installations on the same machine in different locations.
In-place Upgrade: The target server is installed in the same installation location as the source server. You can choose to perform this type of upgrade if you wish to install the configuration (that is, the domains ) in the same location as before. In this scenario, you install the binaries in the same location as the existing binaries using the installer. After installation, if you select the Upgrade checkbox during installation, the installer invokes the upgrade tool , pre-populating it with the source domains directory and target server directory. In this type of upgrade, you provide the source domains root and all the domains under this domains root are upgraded. If you have created multiple domains roots that are customized, you need to specify each of these domains root for upgrading the domains under them.
You need to perform the following steps before upgrade in each of the following scenarios:
Upgrading from Application Server 7.x: You can perform only a side-by-side upgrade, which involves installing the source application server installation and the target installation on the same machine, under different install locations. Before upgrade, you need to:
Upgrading from Application Server 8.x EE: You can perform a side-by-side upgrade or an in-place upgrade. Before upgrade, you need to check if any of the keystore or certificate databases have any other password other than changeit. You need to change all those passwords to changeit. You can use the keytool utility for the JKS databases and the certutil utility for the NSS databases.
Failure to change the keystore or certificate database passwords could result in the Upgrade Tool certificate transfer process being aborted abnormally.
After the upgrade, if you wish to restore the values of the keystore or certificate database passwords, you can do so manually by using the keytool and certutil utilities.
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] [--domain domain_name] [--adminuser admin_user] [--adminpassword admin_password] [--masterpassword master_password] [--targetnsspwdfile targetNSS_password_filepath] [--nsspwdfile NSS_password_filepath] [--jkspwdfile JKS_password_filepath] [--capwdfile CA_password_filepath] [--clinstancefiles 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 2–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 or -? |
--help |
Displays the arguments for launching the upgrade utility. |
-t |
--target |
The domains root directory of the Application Server 8.2 EE installation. |
-s |
--source |
The installation directory when source is Application Server 7.x. Domains root directory when the source is Application Server 8.x and an in-place upgrade is done. Domain directory domain-dir when the source is Application Server 8.x and a side-by-side upgrade is done. |
-d |
--domain |
The domain name for the migrated certificates. |
-a |
--adminuser |
The user name of the admin user |
-w |
--adminpassword |
The admin password |
-m |
--masterpassword |
Master password |
-n |
--nsspwdfile |
The path to the NSS password file. This file is a plain text file that contains only the password |
-e |
--targetnsspwdfile |
The path to the target NSS password file. This file is a plain text file that contains only the password |
-j |
--jkspwdfile |
The path to the JKS password file. This file is a plain text file that contains only the password |
-p |
--capwdfile |
The path to the CA certificate password file. This file is a plain text file that contains only the password. |
-i |
--clinstancefiles |
The path to the cluster file, if the source installation is Application Server 7.x. 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 EE with Prompts for Certificate Migration.
This example shows how to perform a side-by-side upgrade of a Sun Java SystemApplication Server 7 installation to Sun Java System Application Server 8.2. This command prompts you to migrate certificates. If you reply no, certificates are not migrated.
asupgrade --source /home/sunas7 --target /home/sjsas8.2/domains
Example 2: Upgrading an Application Server 7.1 EE Installation with Clusters and NSS Certificates to Application Server 8.2 EE
This example shows how to upgrade (side-by-side) a Sun Java System Application Server 7.1 EE installation with a cluster to Sun Java System Application Server 8.2 EE. NSS certificates will be migrated, as will the clinstance.conf cluster file.
asupgrade --source /home/sjsas7.1 --target /home/sjsas8.2/domains --domain domain1 --nsspwdfile /home/sjsas7.1/nsspassword.txt --targetnsspwdfile /home/sjsas8.2/nsspassword.txt --clinstancefiles /home/sjsas7.1/config/clinstance.conf
After upgrade, node agents for all remote instances are created on the target DAS. These node agents have to copied to the respective host systems and started. For more information, refer To Upgrade a Node Agent from Application Server 7.x EE
Example 3: Upgrading an Application Server 8.1 EE Installation (in-place) with Clusters and NSS Certificates to Application Server 8.2 EE
This example shows how to perform an in-place upgrade of a Sun Java System Application Server 8.1 EE installation with a cluster to Sun Java System Application Server 8.2 EE. NSS certificates will be migrated, as will the clinstance.conf cluster file.
asupgrade --source /home/sjsas8.1/domains --target /home/sjsas8.2/domains --domain domain1 --nsspwdfile /home/sjsas8.1/nsspassword.txt --targetnsspwdfile /home/sjsas8.2/nsspassword.txt --clinstancefiles /home/sjsas8.1/config/clinstance.conf
After upgrade, node agents for all remote instances are created on the target DAS. These node agents have to copied to the respective host systems and started. For more information, refer To Upgrade a Node Agent from Application Server 8.1 EE
Example 4: Upgrading an Application Server 8.1 EE Installation (side—by—side) with Clusters and NSS Certificates to Application Server 8.2 EE
This example shows how to perform a side-by-side upgrade of a Sun Java System Application Server 8.1 EE installation with a cluster to Sun Java System Application Server 8.2 EE. NSS certificates will be migrated, as will the clinstance.conf cluster file.
asupgrade --source /home/sjsas8.1/domains/domain1 --target /home/sjsas8.2/domains --domain domain1 --nsspwdfile /home/sjsas8.1/nsspassword.txt --targetnsspwdfile /home/sjsas8.2/nsspassword.txt --clinstancefiles /home/sjsas8.1/config/clinstance.conf
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.
In the Source Installation Directory field, enter the location of the existing installation from which to import the configuration.
Provide the appropriate value for the Source Installation Directory field depending on the version of your older installation of Application Server and the type of upgrade you want to perform. Valid values for this are:
Enter the install root of the Application Server 7.x, if you are upgrading from Application Server 7.x. Example: /home/sunappserver7.1 for Solaris/Linux users or C:\ProgramFiles\SunAppserver7.1 for Windows users. You can only perform a side-by-side upgrade if you are upgrading from Application Server 7.x.
Enter the domains root if you are performing an in-place upgrade from Application Server 8.x. Example: /home/sunappserver7.1/domains for Solaris/Linux users or C:\ProgramFiles\SunAppserver7.1\domains for Windows users.
Enter the domain directory if you are performing a side—by-side upgrade from Application Server 8.x. Example: /home/sunappserver7.1/domains/domain1 for Solaris/Linux users or C:\ProgramFiles\SunAppserver7.1\domains\domain1 for Windows users.
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 is the directory to which the Application Server software was just installed. If the Upgrade tool was not invoked through the installer or if you are upgrading from Application server 7.x, you need to provide the domains root of the Application Server 8.2 EE installation as the input to this field. Example: /home/sunappserver8.2/domains for Solaris/Linux users or C:\ProgramFiles\SunAppserver8.2\domains for Windows users.
If you are upgrading from Application Server 7.x, you need to enter the admin user name, admin password, and master password that you used for theApplication Server 7.x installation. If you have created a domain when you installed the target server (Application Server 8.2), you need to have used the same admin credentials as that was used for Application Server 7.x. If you have multiple Application Server 7.x domains, all of them need to have the same admin credentials. If you are upgrading Application Server 8.x, you need to enter the following values: admin user as admin, admin password as adminadmin, and master password as changeit. If you enter other values, the Upgrade tool ignores those values and assigns the default values to the admin credentials.
Refer Before You Upgrade to know what you need to before you upgrade.
If you are upgrading a Application Server 7.x Enterprise Edition installation with clusters and no security certificates, click the Next button and continue with step 9 to enter the cluster files information. If you are upgrading Application Server 8.x Enterprise Edition to Application Server 8.2 Enterprise Edition, click the Next button to proceed with the upgrade. The Upgrade tool automatically detects any clusters in the source installation. If security certificates need to be transformed, continue with step 4.
If the source installation has security certificates that must be transferred, check the Transfer Security Certificates checkbox, press the Next button.
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 steps 6 and 7 until all the domains that have certificates to be transferred have been added. Click Next button when done.
If you are upgrading a Sun Java System Application Server 7.1 Enterprise Edition installation with clusters to Sun Java System Application Server 8.2 Enterprise Edition, the Transfer Cluster Configurations screen will be displayed. Click 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.
Repeat step 9 until all the cluster configuration files that need to be migrated have been added. Press the Next button.
Repeat this process until all the cluster configuration files that need to be migrated have been added, and press the Next button.
The Upgrade Results panel is displayed showing the status of the upgrade operation.
Click the Finish button to close the Upgrade Tool when the upgrade process is complete.
The Application Server's Upgrade Tool captures cluster details from the clinstance.conf file, the cluster configuration file. If more than one cluster has been defined for the Application Server 7.x, multiple .conf files could exist prior to the upgrade. The configuration files could have any name, but all would have the .conf file extension. If clusters will be included in an upgrade, consider the following points when you are defining clinstance.conf files. Instance names in the clinstance.conf file must be unique. For example, in Application Server 7.x, machine A could have server1 and server2 participating in a cluster. Machine B could also have a server1 participating in the same cluster. Typically, the clinstance.conf file would include server1 and server2 of machine A and server1 of machine B. Application Server 8.1 requires that instance names in a cluster be unique. Therefore, before you upgrade, in the clinstance.conffile, you would need to rename server1 of machine B to a unique name, such as server3or server1ofmachineB.
You do not have to rename the server1 instance itself in machine B. You only need to rename the server in the clinstance.conf file.
The expectation is that instances participating in the cluster are homogeneous, in the sense that they would have same type of resources and same applications deployed in them. When the upgrade process runs, the instance that is marked as the master instance is picked up for transferring the configuration. If there is no instance marked as the master instance, one of the instances is randomly picked up and used for transferring the configuration. A cluster is created in the DAS, along with instances defined in the clinstance.conf file. All these instances participating in this cluster share the same configuration named cluster_name-config, where the cluster_name is cluster_0 for the first cluster, cluster_1 for the next cluster, and so on. Each instance in the cluster has HTTP and IIOP ports set in their system properties. The HTTP port is the port defined in the clinstance.conf file as the instance port. IIOP ports are selected from the iiop-cluster configuration in the server.xml file.
When you are upgrading Application Server 8.x EE to Application Server 8.2 EE, the upgrade tool automatically detects clusters, if any, on the source installation. There is no need to specify the configuration files, in this case.
Server instances that participate in the cluster and that run on a machine that does not have DAS running on it, are created with a node agent named <host-name>-<domain-name>, where the host-name is the name given in the clinstance.conf file for that particular instance and the domain-name is the name to which this cluster belongs.
After the upgrade process has been completed on the DAS, install Application Server 8.2 on the other machines where clustered instances need to run.
Copy the node-agent directory from DAS machine to client machine underinstall-dir/nodeagents/. For example, if your DAS is installed on HostA and client machine name is HostB, the upgrade process would have created a node agent named HostB_<domain_name> as the node agent for HostB. Therefore, copyHostB_<domain_name> from HostA<AS82_install_dir>/nodeagents/HostB_<domain_name> directory to HostB<AS82_install_dir>/nodeagents. After copying, delete the copied node agent directory under HostA.
Start the DAS.
Start the node agent named HostB_<domain_name> on HostB. The node agent with rendezvous with the DAS and the remote instances are created in HostBand the deployed applications are copied over.
If you are performing an in-place upgrade , you do not have to upgrade the node agents. The same node-agent directory can be used with the upgraded binaries. If you are performing a side-by-side upgrade , perform the following steps:
Install Application Server 8.2 EE on Machine B in /opt/SUNWappserver8.2 with the default node agent.
Perform a side-by-side upgrade from the install location of Application Server 8.1 EE.
Install Application Server 8.2 EE on Machine B which has a node agent with remote instances referring to a DAS on machine A. You must install only the node gent on Machine B.
After upgrade, verify the nodeagent.properties file
in Machine A and Machine B for the agent.adminPort property . This file must reflect the same value
as that of the jmx-connector
port in the corresponding node-agent element of the domain.xml file.
If not, edit the nodeagent.properties file accordingly.
Start the DAS on Machine A.
Start the default node agent on Machine A. It starts up with the instance, instance1. The cluster1 cluster is partially started after this step.
On Machine B, start up the default node agent of that remote instance.
You can check the upgraded elements by running the asadmin commands,list-node-agents(1), list-clusters(1), list-instances(1).
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
To Migrate Additional HTTP and IIOP Listeners Defined on the Source Server to the Target EE Server
Eliminating Problems Encountered When A Single Domain has Multiple Certificate Database Passwords
If you have installed Application Server 8.2 and an older Application Server 8.1 in two separate locations, you might want to use the --domaindir option on domains created with the previous version of Application Server without actually upgrading the domains to the latest version. In this scenario, you need to update the startserv and stopserv scripts to ensure that the domains use the latest binaries of Application Server. Change the scripts to point to the asenv.conf file from the latest location.
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:
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.
If additional HTTP listeners or IIOP listeners have been defined in the source server, the IIOP ports must be manually updated for the target EE servers before any clustered instances are started. For example, MyHttpListener was defined as an additional HTTP listener in server1, which is part of the cluster. The other instances in the cluster also have the same HTTP listener, because server instances are symmetrical in a cluster. In the target configuration named <cluster_name>-config, this listener must be added with its port set to a system property, {myHttpListener_HTTP_LISTENER_PORT}. In the target server, each server instance in this cluster that uses this configuration would have system property named myHttpListener_HTTP_LISTENER_PORT. The value of this property for all server instances is set to the port value in the source server, server1. These system properties for these server instances must be manually updated with nonconflicting port numbers before the server is started.
If additional HTTP listeners have been defined in the source server, those listeners need to be added to the target server after the upgrade:
Start the Admin Console.
Expand Configuration and select the appropriate <server>-config configuration.
Expand HTTP Service.
Expand Virtual Servers.
Select <server>.
In the right hand pane, add the additional HTTP listener name(s) to the HTTP Listeners field.
Click Save when done.
After upgrading the source server to Application Server 8.2 EE, start the domain. Start the node agent, which, by default, starts the server instances. Start the Admin Console and verify that these servers are started. If any of the servers are not running, in the install_dir/nodeagents/node-agent-name/server_name/logs/server.log file, check for failures that are caused by port conflicts. If there any failures due to port conflicts, use the Admin Console and modify the port numbers so there are no more conflicts. Stop and restart the node agent and servers.
While upgrading from Application Server 7.x SE or EE , a port conflict occurs if one of the instances in 7.x servers is the same as the default ports assigned to the default domain created by Application Serve 8.2 installation. Refer the following list for the values of the ports assigned by default when a domain is created in Application Server 8.2 EE If these conditions exist, start the Admin Console after the upgrade and change the port for the server-config's listener to a nonconflicting port number.
The default ports in Application Server 8.2 EE are:
8080 for HTTP Instance (DAS instance)
7676 for JMS
3700 for IIOP
8181 for HTTP_SSL.
3820 for IIOP_SSL
3920 for IIOP_MUTUALAUTH
8686 for JMX_ADMIN
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 that of 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. Reset the passwords after the upgrade has been completed.
While upgrading from Application Server 7.1 EE to Application Server 8.2 EE, during a side-by-side upgrade, you will not be able to point your new 8.2 load balancer plug-in to the old 7.1 web server installation, if the load balancer plug-in is colocated with other Application server components on a single system. You need to install web server again and point the 8.2 load balancer plug-in installation to the instance belonging to the new installation.
If you have performed a side-by-side upgrade from Application Server 7.x with (MQ and HADB) to Application Server 8.2 EE, do not uninstall the older version — Application Server 7.x. The uninstall process removes shared components, such as JAF, JavaMail, and MQ libraries. The missing shared components will cause the Application Server 8.2 EE installation to malfunction. If you want to uninstall Application Server 7.x, remove SUNWas* packages that belong to Application Server 7.x by running the pkgrm command, and do not run the uninstall script. If you have already uninstalled Application Server 7.x using the uninstall script, copy the shared components manually by running the pkgadd command.
The tool does not update the runtime binaries of the server. The Upgrade tool upgrades the configuration information and deployed applications of a previously installed server. You need to use the Application Server Installer to install the server binary packages. The first step in the upgrade process is to use the Installer to install the target server binaries.
You cannot perform an upgrade if the source and target server file systems, specifically the domain root file system, are not accessible from the same machine. Currently, most of the upgrade is file based. To perform the upgrade, the user who runs the upgrade needs to have Read permissions for the source and target directories and Write permission for the target directory.