The Upgrade tool, which is bundled with Application Server 9.1, 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 9.1. 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 |
9.1 |
---|---|
7.X PE |
Not supported |
7.XSE |
Not supported |
7.XEE |
Not supported |
8.0PE |
Supported (Upgrade from 8.0 PE domain to 9.1 developer domain is supported) |
8.1PE |
Supported (Upgrade from 8.1 PE domain to 9.1 developer domain is supported) |
8.1EE |
Supported (Upgrade from 8.1 EE domain to 9.1 enterprise domain is supported) |
8.2PE |
Supported (Upgrade from 8.2 PE domain to 9.1 developer domain is supported) |
8.2EE |
Supported (Upgrade from 8.2 EE domain to 9.1 enterprise domain is supported) |
9.0PE |
Supported (Upgrade from 9.0 PE domain to 9.1 developer domain is supported) |
Only the enterprise profile supports upgrades from Application Server Enterprise Edition 8.x.
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.
Ensure that the -c/--console option is the first option in the command line, if you want to run asupgrade in CLI mode.
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 the asenv.conf file (on Solaris) or the asenv.bat file (on Windows).
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 you stop all server instances, node agents, and domains (in that order) in the source server (the server from which you are upgrading) and the target server (the server to which you are upgrading).
Application archives (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.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, and deployed again manually.
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.
In Application Server 8.x, the clusters are defined in the domain.xml file and there is no need to specify clusters separately. 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.
The Upgrade tool transfers certificates from the source certificate database to the target. The tool transfers security policies, password files from standard, file-based realms, and custom realm classes.
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.
After you have upgrade a domain, you can see a file whose name is in the following format: upgradedTo<releasenumber>. For example, a domain that has been upgrade to 9.1 will have a file called upgradeTo91 in its config folder.
If an upgrade in progress is cancelled, the configuration before the upgrade was started is restored.
You can cancel the upgrade process only if you are running the Upgrade Tool in GUI mode.
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.
Inline Upgrade: You can use the start-domain command to upgrade domains of Application Server 8.x or 9.0 to Application Server 9.1. This type of upgrade works only if you are performing an in-place upgrade of binaries.
This section provides the following procedures :
If you have Application Server 8.x installed as part of Java ES 5 or Java ES 5 Update 1, you can use the following upgrade procedure to upgrade to Application Server 9.1, which is distributed with Java ES 5 Update 1 as an optional download.
Java ES 5 users can use the following procedure to upgrade from Application Server 8.x Enterprise Edition to Application Server 9.1
Stop all instances, node agents, and domains running on Application Server 8.x.
Start the Application Server 9.1 installer . For instructions on how to install Application Server 9.1, see Installing Application Server 9.1 in Sun Java System Application Server 9.1 Installation Guide.
For Solaris or Linux, choose the same installation directory as that of the Application Server 8.x installation. For Windows, choose a different installation directory and not the Application Server 8.x installation directory.
The installer updates the required shared components. The installer also created a new domain (domain1) in as-install/appserver/domains/domain1on Solaris, as-install/domains/domain1 on Linux, and as-install\domains\domain1 on Windows.
Start the Upgrade tool. When prompted for source , provide the 8.x domain directory. When prompted for the target, provide the 9.1 domains root directory.
This tool is located in the as-install/appserver/bin directory on Solaris, as-install/bin directory on Linux, and as-install\bin directory on Windows.
See Upgrading your Application Server for the syntax and usage of the Upgrade tool or asupgrade command.
Application Server 9.1 is not supported with Java ES 5 and needs the Java ES 5 Update 1 Portal Server. Portal Server for Java ES 5 Update 1 is not supported on Windows.
Java ES users can use this procedure to upgrade Service Registry domains.
Upgrade Service Registry.
See the Java ES Upgrade guide on docs.sun.com for instructions.
Install Application Server 9.1. For instructions on how to install Application Server 9.1, see Installing Application Server 9.1 in Sun Java System Application Server 9.1 Installation Guide.
Run the following commands:
cd <service_registry_install_dir>/install
On Solaris, <service_registry_install_dir> is /opt/SUNWsrvc-registry, by default. On Linux, the default install location is /opt/sun/srvc-registry.
<Ant-base_dir>/ant -f build-install.xml appserver.deploy.as9
Where <Ant-base_dir> is /usr/sfw/bin on Solaris and /opt/sun/share/bin on Linux.
Run the Upgrade Tool to upgrade the Service Registry domain.
Provide <service_registry_domainbase>/domains/registry as input for the Source Server field (--source option).
Provide <Application_Server9.1_install_dir>/domains as input for the Target Server field (--target option).
For instructions on how to run the Upgrade Tool, see Upgrading your Application Server.
For upgrading your Application Server installation you can choose:
Use the following procedures to upgrade your existing clusters and node agents:
You can run the upgrade utility from the command line using the following syntax:
asupgrade [--console ] [--version ] [--help ] [--source applicationserver_8.x_installation_domaindirectory] [--target applicationserver_9.1_installation] [--passwordfile passwords.txt]
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 or -V |
--version |
The version of the Upgrade Tool. |
-h |
--help |
Displays the arguments for launching the upgrade utility. |
-t |
--target |
The domains directory of the Application Server 9.1 installation. |
-s |
--source |
The installation directory of the older Application Server installation. |
-a |
--adminuser |
The admin user for the source server. |
-f |
--passwordfile |
The file containing the admin password and the master password. |
For a more detailed usage summary of the asupgrade command, see asupgrade(1M).
The following examples show how to use the asupgrade command-line utility to upgrade an existing application server installation to Application Server 9.1.
This example shows how to perform a side-by-side upgrade of a Sun Java SystemApplication Server 8.x installation to Sun Java System Application Server 9.1.
asupgrade --source /home/sunas8.2/domains/domain1 --target /home/sjsas9.1/domains
After upgrade, node agents for all remote instances are created on the target DAS. These node agents have to be copied to the respective host systems and started.
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. Enter the domain directory.
For example, <install-root>/domains/domain1
In the Target Installation Directory field, enter the location of the Application Server installation to which to transfer the configuration. Provide the domains root directory of the target Application Server installation as the input to this field.
Provide the admin user name, the admin password, and master password of the source application server. The target domain is created with these credentials.
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.
When you are upgrading Application Server 8.x EE to Application Server 9.1, the upgrade tool automatically detects clusters, if any, on the source installation.
If you are performing an upgrade from Application Server 8.x EE to Application Server 9.1, in which all the node agents run on a single machine, the upgrade tool automatically detects node agents, if any, on the source installation. The user need not take any special action. If you are performing an upgrade from Application Server 8.x EE to Application Server 9.1, in which remote node agents are running on other machines use the following steps to perform the upgrade.
Install Application Server 9.1 on Machine A.
Perform the upgrade from Application Server 8.x EE to Application Server 9.1.
Install Application Server 9.1 on Machine B without the DAS but with the Node Agent feature.
Machine A is the primary machine. It runs the DAS. Machine B is a secondary machine, which is not running the DAS. Machine B runs remote node agents that are configured to communicate with Machine A.
If you are performing an in-place upgrade:
On Machine A, start each node agent using the start-node-agent command with the --syncinstances option. This option resynchronizes all associated instances. Example: asadmin start-node-agent --user admin --syncinstances nodeagent1
On Machine B, start each node agent using the start-node-agent command with the --syncinstances option. This option resynchronizes all associated instances
If you are performing an side—by—side upgrade:
Check the value of the agent.adminPort property in thenodeagent.properties file before starting the node agent for the first time. Perform this check on the nodeagent.properties files on both Machine A and Machine B. The value of agent.adminPort property must reflect the same value as the jmx-connector port defined in the domain.xml file on Machine A. Edit the agent.adminPort property in the nodeagent.properties files on Machine A and Machine B, as required.
If you are using non-default ports, you must check the value of the agent.bind.status property in nodeagent.properties file on Machine B, before starting the node agent for the first time. If the agent.bind.status property in nodeagent.properties file is BOUND, change it to UNBOUND.
On Machine A, start each node agent using the start-node-agent command. Do not use the --syncinstances option.
On Machine B, start each node agent using the start-node-agent command. Do not use the --syncinstances option.
For information on how to resolve problems with starting the upgraded node agent, see Node Agent Startup Failure.
This section addresses the following issues that could occur during an upgrade to Application Server 9.1:
Problems Encountered When A Single Domain has Multiple Certificate Database Passwords
Migration of Additional HTTP Listeners Defined on the Source Server to the Target Server
Migration of Additional HTTP and IIOP Listeners Defined on the Source Server to the Target Server
The default admin port in Application Server 9.1 is 4848 and in Application Server 8.x EE, the default admin port is 4849. When you upgrade from Application Server 8.x EE, you could run into problem while trying to start the default node agent that exists in the target, due to the port clash.
To resolve this problem, edit the das.properties file before starting the target domain or node agent. Change the agent.das.port property to the admin port value in the upgraded domain.xml, which is 4849.
Upgrade tool leaves the node agent in a rendezvous false state. If the agent.bind.status property in nodeagent.properties file is BOUND, change it to UNBOUND. The node agent starts up successfully after making these changes.
The datasource class used for a jdbc-connection-pool resource named __TimerPool has changed from org.apache.derby.jdbc.EmbeddedXADataSource in Application Server 8.x EE to org.apache.derby.jdbc.ClientDataSource in Application Server 9.1. This change requires a addition of two property elements, User and Password to the jdbc-connection-pool element in the domain.xml file. Edit the Application Server 9.1 domain.xml file and add the appropriate user name and password. Example:
<property name="User" value="APP"/> <property name="Password" value="APP"/>
You have deployed applications that use client JARs in Application Server 8.x. You upgrade your existing installation to Application Server 9.1. You could run into problems while trying to run these applications (that were deployed in Application Server 8.x) in Application Server 9.1.
To solve this problem, perform the following steps:
After upgrade, start Application Server 9.1.
Use the asadmin get-client-stubs command to transfer the missing client stubs to a local directory. See get-client-stubs(1).
Run the appclient pointing to the client JAR files in the local directory.
You have deployed applications that use JavaDB databases in Application Server 8.x. You upgrade your existing installation to Application Server 9.1. You run the asadmin start-database command and successfully start JavaDB. In this scenario, you could run into problems while trying to run these applications (that were deployed in Application Server 8.x) in Application Server 9.1 because the instance directory of JavaDB in Application Server 9.1 has changed.
To solve this problem, perform the following steps:
After upgrade, start Application Server 9.1.
Use the asadmin start-database command with --dbhome option pointing to older (Application Server 8.x) version of JavaDB. Example asadmin start-database --dbhome /home/johnsmith/appserver8.2/databases
Deploy the migrated applications.
Upgrade tool does not transfer java-config attributes, classpath-suffix, classpath-prefix, java-home, server-classpath, because the information provided can be implementation specific.
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.1 configuration format.
The following JVM options are not transferred from the source to the target installation:
Dorg.xml.sax.driver
Dcom.sun.jdo.api.persistence.model.multipleClassLoaders
Djava.util.logging.manager
Dcom.sun.aas.imqLib
Dcom.sun.aas.imqBin
Dcom.sun.aas.webServicesLib
Dcom.sun.aas.configRoot 8. Xmx<...>m
The options that are not transferred are listed down in the upgrade log. The user can manually change such attributes in the configuration file.
After upgrading the source server to Application Server 9.1, start the domain and then the node agent, which, by default, starts the server instances. If you have upgraded from Application Server 8.x EE, you might face problems while attempting to start the node agent. The domain, clusters, and instances have admin port set to 4849 and the node agent points to 4848. You need to manually modify the admin port to which the node agent points. To change the node agent port, edit the agent.das.port property in the install_dir/nodeagents/node-agent-name/server_name/config/das.properties file.
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.
The default ports in Application Server 9.1 are:
4848 for admin port
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 8uses 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 8.x EE to Application Server 9.1, during a side-by-side upgrade, you will not be able to point your new 9.1 load balancer plug-in to the old 8.x 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 9.1 load balancer plug-in installation to the instance belonging to the new installation.
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.
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.
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.