Chapter 2 Upgrading an Enterprise Server Installation

The Upgrade tool, which is bundled with Enterprise Server, 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 Enterprise Server to Enterprise Server v2.1.1. To view a list of the older versions from which you can upgrade, refer Table 2–1

This chapter discusses the following topics:

• Upgrade Overview

• Upgrade Scenarios

• Upgrading Enterprise Server Runtime Binaries

• Upgrading Configuration, Deployed Applications, and Certificate Databases

• Upgrading Node Agents

• Correcting Potential Upgrade Problems

Upgrade Overview

You can upgrade file-based installations or package-based installations to Enterprise Server v2.1.1. The following table shows supported Enterprise Server upgrade paths for file-based installations.

In this table, PE indicates Platform Edition and EE indicates Enterprise Edition.

Only the enterprise profile supports upgrades from Application Server Enterprise Edition 8.x.

The following table shows supported Enterprise Server upgrade paths for package-based installations.

Upgrade Tool Interfaces

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–3. 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. Do not run upgrades through the silent installation mode.

Upgrade Terminology

The following are important terms related to the upgrade process:

• Source Server: the installation from which you are upgrading to the new version.

• Target Server: the installation to which you are upgrading.

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

Upgrade Tool Functionality

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 GlassFish 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).

Migration of Deployed Applications

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 Enterprise Server.

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 deployed manually on the target server by the user1

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.

Upgrade of Clusters

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.

Transfer of Certificates and Realm Files

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.

Upgrade Verification

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 upgraded to 9.1 Update 1 will have a file called upgradeTo91 in its config folder.

Upgrade Rollback

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.

Upgrade Scenarios

The upgrade scenarios are as follows:

• Side-by-Side Upgrade

• In-Place Upgrade

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.

A side-by-side upgrade involves the following sequence of tasks

1. Upgrading Enterprise Server Runtime Binaries

2. Upgrading Configuration, Deployed Applications, and Certificate Databases.

3. To Upgrade Remote Node Agents (Side-by-side) (only if you have remote agents in the source application server).

   If all existing node agents (from the source application server installation) run on a single machine, the upgrade tool automatically detects node agents, if any, on the source installation.

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.

For an in-place upgrade from Sun Java System Application Server 9.1, 9.1 Update1, 9.1 Update 2 to Enterprise Server v2.1.1, do not use the asupgrade utility. It is sufficient to upgrade the runtime binaries by using the installer. After upgrading the binaries to Enterprise Server v2.1.1, start the domain with the asadmin start-domain command.

An in-place upgrade involves the following sequence of tasks:

1. Upgrading Enterprise Server Runtime Binaries

2. Upgrading Configuration, Deployed Applications, and Certificate Databases.

3. To Upgrade Remote Node Agents (In-place) (only if you have remote agents in the source application server).

   If all existing node agents (from the source application server installation) run on a single machine, the upgrade tool automatically detects node agents, if any, on the source installation.

Upgrading Enterprise Server Runtime Binaries

The Upgrade 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. Before you run the Upgrade tool to upgrade the configuration data, you need to upgrade the runtime binaries. You can upgrade the binaries in one of the following ways:

• Upgrading the Runtime Binaries of a File-Based Installation of Application Server

• Upgrading the Runtime Binaries of a Package-Based Installation of Application Server

Upgrading the Runtime Binaries of a File-Based Installation of Application Server

Use the Enterprise Server file-based installer to install the target application server binaries. You can install in-place (in the same location as your earlier installation) or side-by-side (in a different location). For instructions on how to use the file-based installer, see Sun GlassFish Enterprise Server v2.1.1 Installation Guide.

After installing the target application server binaries, run the asupgrade command for Upgrading Configuration, Deployed Applications, and Certificate Databases.

Upgrading the Runtime Binaries of a Package-Based Installation of Application Server

Patches for the Solaris operating system and the Linux operating system are available from the SunSolve^SM program site.

To Upgrade a Package-Based Installation of Application Server 9.1 Update 1

This procedure applies to package-based upgrades to Enterprise Server v2.1.1.

1. Stop all instances, node agents, clusters, and domains in the source application server.

2. Download the appropriate patch from the SunSolve program site.

   The patches are available at the following locations on SunSolve:

   • Sun GlassFish Enterprise Server v2.1.1 (Solaris SPARC, SVR4)

   • Sun GlassFish Enterprise Server v2.1.1 (Solaris x86, SVR4))

   • Sun GlassFish Enterprise Server v2.1.1 (Solaris x86, File-based)

   • Sun GlassFish Enterprise Server v2.1.1 (Linux, Package-based)

   • Sun GlassFish Enterprise Server v2.1.1 (Linux, File-based)

   • Sun GlassFish Enterprise Server v2.1.1 (AIX, File-based)

   • Sun GlassFish Enterprise Server v2.1.1 (Windows, File-based)

   • Sun GlassFish Enterprise Server v2.1.1 with HADB (Solaris SPARC, File-based)

   • Sun GlassFish Enterprise Server v2.1.1 with HADB (Solaris x86, File-based)

   • Sun GlassFish Enterprise Server v2.1.1 with HADB (Linux, File-based)

   • Sun GlassFish Enterprise Server v2.1.1 with HADB (Windows, File-based)

3. On the machine where the application server is installed, log in as root or become superuser.

4. Apply the patch.

   patchadd patch-id

   patch-id is the patch. For example, /var/sadm/spool/patch/128640-08-01

5. Start the server.

Next Steps

Run the asupgrade command for Upgrading Configuration, Deployed Applications, and Certificate Databases.

Then, log in to the Admin Console. You can register your installation of application server with Sun Connection from the Admin Console by clicking Common Tasks -> Registration. For detailed instructions for registering the Enterprise Server with Sun Connection, see TBDlink.

Upgrading Configuration, Deployed Applications, and Certificate Databases

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

Ensure that you have stopped all instances, node agents, clusters, and domains in the source Application Server before you start the upgrade process. Do not run the asupgrade utility if you are upgrading from Sun Java System Application Server 9.x.

For upgrading your installation you can choose:

• To Upgrade From the Command Line

• To Upgrade by Using the Upgrade Tool Wizard

To Upgrade From the Command Line

To run Upgrade Tool in command-line mode, use the -c option. You can run the upgrade tool in command-line mode using the following syntax:

asupgrade 
[--console ] 
[--version ] 
[--help ] 
[--source applicationserver_installation_domaindirectory] 
[--target enterpriseserver_v2.1.1_installation] 
[--adminuser enterpriseserver_v2.1.1_admin_user_name]
[--passwordfile passwords.txt]

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

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

This example shows how to perform a side-by-side upgrade of a Sun GlassFishApplication Server 8.x installation to Enterprise Server v2.1.1.

asupgrade -c --source /home/sunas8.2/domains/domain1 --target /home/sjsas9.1/domains

To Upgrade by Using the Upgrade Tool Wizard

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 Enterprise Server installation process, the Upgrade Wizard screen automatically displays after the installation completes.

1. 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, as-install/domains/domain1

2. In the Target Installation Directory field, enter the location of the Enterprise 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.

3. Provide the admin user name, the admin password, and master password of the source application server. The target domain is created with these credentials.

4. The Upgrade Results panel is displayed showing the status of the upgrade operation.

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

Next Steps

To upgrade node agents, see Upgrading Node Agents. After you complete the upgrade, start the Application Server using the asadmin start-domain command. Log on to the Admin Console. You can register your installation of application server from the Admin Console by clicking Common Tasks -> Registration. For step-by-step instructions on the registration process, click the Help button on the Admin Console.

Upgrading Node Agents

The upgrade tool automatically detects clusters, if any, on the source installation.

If all existing node agents (from the source application server installation) 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 have remote node agents running on other machines, use the following steps to perform the upgrade.

• To Upgrade Remote Node Agents (In-place)

• To Upgrade Remote Node Agents (Side-by-side)

To Upgrade Remote Node Agents (In-place)

1. Perform the upgrade to Enterprise Serverv2.1.1 on Machine A by Upgrading Enterprise Server Runtime Binaries and Upgrading Configuration, Deployed Applications, and Certificate Databases.

2. Install Enterprise Serverv2.1.1 on Machine B without the DAS but with the Node Agent feature.

   ---

   Note –

   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.

   ---

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

4. On Machine B, start each node agent using the start-node-agent command with the --syncinstances option. This option resynchronizes all associated instances

To Upgrade Remote Node Agents (Side-by-side)

1. Perform the upgrade to Enterprise Serverv2.1.1 on Machine A by Upgrading Enterprise Server Runtime Binaries and Upgrading Configuration, Deployed Applications, and Certificate Databases.

2. Install Enterprise Serverv2.1.1 on Machine B without the DAS but with the Node Agent feature.

   ---

   Note –

   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.

   ---

3. Check the value of the agent.das.port property in the das.properties file before starting the node agent for the first time. Perform this check on the das.properties file on Machine B. The value of the agent.das.port property must reflect the same value as the jmx-connector port defined in the domain.xml file on Machine A.

   There are two ways to determine this port number:

   • It is displayed as part of the message for the start-domain(1) command run on the DAS machine. Look for the following line in the command output of asadmin start-domain: [service:jmx:rmi:///jndi/rmi://comet:8686/jmxrmi] for domain management purposes. This line indicates that the JMX port number is 8686.

   • It is recorded in the domain's domain.xml file on the Machine A. Find the admin-service element with das-and-server attribute type. Look at the jmx-connector sub-element for this element and find the attribute port. The value of this attribute is the port number of the JMX port.

   Edit the agent.das.port property in thedas.properties file on Machine B, as required.

4. Check the value of the agent.bind.status property in the nodeagent.properties file before starting the node agent for the first time. Perform this check on the nodeagent.properties file on Machine B. The value of the agent.bind.status property must BOUND. Edit the agent.bind.status property in the nodeagent.properties files on Machine B, as required.

5. On Machine A, start each node agent using the start-node-agent command.

6. On Machine B, start each node agent using the start-node-agent command.

7. If you are using non-default admin ports, you must additionally perform the following steps:

   Before you perform these steps, ensure that you start the node agents so that the required configuration files are created. However, the startup of node agents will not be successful.

   1. Change directory to the node agents config directory (as-install/nodeagents/nodeagent-name/agent/config). Edit the das.properties file. The value of agent.das.port property is the admin port number of the DAS machine with which this node-agent communicates. Edit this value to match the value of the jmxrmi port number of the DAS machine.

      There are two ways to find the jmxrmi port number:

      • The DAS' start-domain command outout displays the jmxrmi value. Look for the following line: Standard JMX Clients (like JConsole) can connect to JMXServiceURL: [service:jmx:rmi:///jndi/rmi://comet:8696/jmxrmi] for domain management purposes. The jmxrmi port is 8696. Set agent.das.port to this value.

      • Search the domain.xml file in the appropriate domain on the DAS machine. Find element admin-service element with das-and-server attribute type. Look at the jmx-connector sub-element for this element and find the attribute port. The value of this attribute is the port number of the jmxrmi port. Update the property value, save, and exit the file

   2. Edit the nodeagent.properties file. If the agent.bind.status property is set to UNBOUND, change the value to BOUND. Save and exit the file.

8. Start the node agent. The --syncinstances=true option need not be used.

After You Upgrade

After you upgrade to Enterprise Serverv2.1.1, to ensure that the Admin Console works as expected, you need to perform the following steps.

To Remove Duplicate Admin GUI JAR Files

1. Navigate to as-install/lib/install/applications/admingui/adminGUI_war/WEB-INF/lib.

2. List the contents of the directory.

   On UNIX platforms, use the ls —l command.

3. Remove the following older JAR files: jsftemplating-dynafaces-0.1.jar and jsftemplating.jar

4. Rename the newer jsftemplating-dynafaces-0.1-1.0.jar and jsftemplating-1.2-SAILFIN.jar as jsftemplating-dynafaces-0.1.jar and jsftemplating.jar, respectively

5. Restart the domain and log into Admin Console.

Correcting Potential Upgrade Problems

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

• Cluster Profile Security Setting

• _TimerPool Resource

• Missing Client JAR Files

• Applications that Use JavaDB

• classpath-prefix and classpath-suffix Not Transferred

• JVM Options That are Not Transferred

• Port Conflicts

• Single Domain with Multiple Certificate Database Passwords

• Load balancer Plug-in Problems During Side-by-Side Upgrade

• Additional HTTP Listeners

• Additional HTTP and IIOP Listeners

Cluster Profile Security Setting

When you upgrade a cluster domain from Application Server 9.1/GlassFish v2 to Enterprise Serverv2.1.1, you could encounter problems because the security setting is incorrect for the admin-service whose type attribute is das-and server in the target domain.xml. The solution is to edit the domain.xml file in the corresponding upgraded domain and correct the setting of the security-enabled attribute. Look for the following statements in the domain.xml file.

<admin-service system-jmx-connector-name="system" type="das-and-server">
<|-- The JSR 160 "system-jmx-connector"-->
<jmx-connector accept-all="false" address="0.0.0.0"
auth-realm-name="admin-realm" enabled=true" name="system" port="8686"
protocol="rmi_jrmp" security-enabled="true">

Cluster Profile Upgrade on Windows

On Windows, when you upgrade cluster profile domains, you could encounter the following error:

Fatal error while backing up the domain directory

To resolve this error, look for and remove any hidden files in the source domain's directory and run Upgrade tool.

_TimerPool Resource

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 Update 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 Update 1 domain.xml file and add the appropriate user name and password. Example:

<property name="User" value="APP"/> <property name="Password" value="APP"/>

Missing Client JAR Files

You have deployed applications that use client JARs in Application Server 8.x. You upgrade your existing installation to Enterprise Serverv2.1.1. You could run into problems while trying to run these applications (that were deployed in Application Server 8.x) in Enterprise Serverv2.1.1.

To solve this problem, perform the following steps:

1. After upgrade, start Enterprise Serverv2.1.1.

2. Use the asadmin get-client-stubs command to transfer the missing client stubs to a local directory. See get-client-stubs(1).

3. Run the appclient pointing to the client JAR files in the local directory.

Applications that Use JavaDB

You have deployed applications that use JavaDB databases in Application Server 8.x. You upgrade your existing installation toEnterprise Serverv2.1.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 Enterprise Serverv2.1.1 because the instance directory of JavaDB in Enterprise Serverv2.1.1 has changed.

To solve this problem, perform the following steps:

1. After upgrade, start Enterprise Serverv2.1.1.

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

3. Deploy the migrated applications.

classpath-prefix and classpath-suffix Not Transferred

Upgrade tool may fail to transfer java-config attributes, classpath-suffix, classpath-prefix, java-home, or server-classpath, because the information provided can be implementation-specific. Certain attributes may be partially transferred.

JVM Options That are Not Transferred

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 Enterprise Serverv2.1.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.

Port Conflicts

After upgrading the source server to Enterprise Serverv2.1.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 Enterprise Server 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

Single Domain with 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 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.

Load balancer Plug-in Problems During Side-by-Side Upgrade

While upgrading from Application Server 8.x EE to Enterprise Serverv2.1.1, during a side-by-side upgrade, you will not be able to point your new 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 older load balancer plug-in installation to the instance belonging to the new installation.

Additional HTTP Listeners

If additional HTTP listeners have been defined in the source server, those listeners need to be added to the 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.

Additional HTTP and IIOP Listeners

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:

1. Start the Admin Console.

2. Expand Configuration and select the appropriate <server>-config configuration.

3. Expand HTTP Service.

4. Expand Virtual Servers.

5. Select <server>.

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

7. Click Save when done.