1. GlassFish Server Upgrade Compatibility Issues
2. Upgrading an Installation of Application Server or GlassFish Server
Summary of Upgrade Tools and Procedures
Summary of Tools for Performing an Upgrade
Update Tool and the pkg Utility
Summary of Procedure for Upgrading With Upgrade Tool
Summary of Procedure for Upgrading With Update Tool
Summary of Procedure for Upgrading With the Software Update Notifier
Summary of Procedure for Upgrading With the pkg Utility
Supported Releases for Upgrade to GlassFish Server 3.1
Upgrading From Version 8.x or Older Product Releases
Upgrading GlassFish Server Inside a Closed Network
Performing a Side-By-Side Upgrade With Upgrade Tool
Migration of Deployed Applications
Performing an In-Place Upgrade With the Update Center Tools
To Upgrade Using the Update Tool GUI
To Upgrade Using the Software Update Notifier
To Upgrade From the Command Line Using the pkg Utility
Upgrading Installations That Use NSS Cryptographic Tokens
To Perform Post-Upgrade Configuration
To Upgrade PKCS#11 Hardware Tokens
Upgrading Clusters and Node Agent Configurations
Overview of Cluster and Node Agent Upgrade Procedures
To Correct the Configuration of a Node After an Upgrade
Correcting Potential Upgrade Problems
Cluster Profile Security Setting
Cluster Profile Upgrade on Windows
This section explains how to use Upgrade Tool to perform a side-by-side upgrade to GlassFish Server 3.1 from any compatible older product release.
The following topics are addressed here:
The Upgrade Tool upgrades your domain configurations and deployed applications. When you use the Upgrade Tool, the source server and the target server are normally installed on the same machine, but under different install locations. Both server file systems must be accessible from the system on which you perform the upgrade.
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.
You can perform an upgrade using Upgrade Tool in the following ways:
The Upgrade Tool migrates the configurations and deployed applications from an earlier version of Sun Java System Application Server or Sun GlassFishEnterprise Server to the current version. Database migrations or conversions are not part of this upgrade process.
Briefly, the Upgrade Tool performs the following steps:
Copies the older source domain directory to the new target domains directory.
Calls the asadmin start-domain --upgrade command to migrate the source configurations to the new target GlassFish Server installation.
Sends all asadmin command output to the screen and to the upgrade.log file, and sends all server output to the server.log file.
Additional Upgrade Tool functions are explained in the following sections:
Application archives (EAR files) and component archives (JAR, WAR, and RAR files) that are deployed in the source server do not require any modification to run on Oracle GlassFish Server 3.1. Components that may have incompatibilities are deployed on GlassFish Server 3.1 with the compatibility property set to v2 and will run without change on GlassFish Server 3.1. You may, however, want to consider modifying the applications to conform to Java EE 6 requirements.
The Java EE 6 platform specification imposes stricter requirements than Java EE 5 did on which JAR files can be visible to various modules within an EAR file. In particular, application clients must not have access to EJB JAR files or other JAR files in the EAR file unless they use a Class-Path header in the manifest file, or unless references use the standard Java SE mechanisms (extensions, for example), or use the Java EE library-directory mechanism. Setting the library-directory property to v2 removes these Java EE 6 restrictions.
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 deployed manually on the target server by the user.
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 unchanged, without any attempt to reconfigure the incorrect configurations.
When upgrading from a clustered configuration, the older cluster information is retained in a new domain.xml file in the GlassFish Server 3.1 installation directories. However, it is still necessary to manually re-create the server instances that are contained in the clusters. This procedure is explained in Upgrading Clusters and Node Agent Configurations.
An upgrade log records the upgrade activity. The upgrade log file is named upgrade.log and is created in the working directory from which the Upgrade Tool is run. Additional information is recorded in the server log of the upgraded domain.
You can also use the asadmin version subcommand after starting the upgraded domain to verify the new GlassFish Server product version; for example:
asadmin> version Version = Oracle GlassFish Server 3.1 (build 42) Command version executed successfully.
This procedure explains how to use the Upgrade Tool command line to upgrade to GlassFish Server 3.1 from any supported older product release. See Supported Releases for Upgrade to GlassFish Server 3.1 for a list of supported releases.
Before You Begin
Ensure that the domains on the source server from which you are upgrading are stopped before proceeding.
See Installing GlassFish Server From a Self-Extracting Bundle in Oracle GlassFish Server 3.1 Installation Guide for instructions.
Custom and third-party libraries should normally be located in the domain-dir/lib directory. This step is only necessary for custom or third-party libraries that may be located in the nonstandard as-install/lib directory.
Note - Use the Upgrade Tool that is located in the target GlassFish Server 3.1 installation, not the older source installation.
as-install-parent/glassfish/bin/asupgrade -c
as-install-parent\glassfish\bin\asupgrade.bat -c
The -c option starts Upgrade Tool in console mode. If -c is omitted, Upgrade Tool starts in GUI mode, which is described in To Upgrade Using the Upgrade Tool Wizard.
If you start Upgrade Tool with only the -c option, the tool enters interactive CLI mode in which you are asked to supply the needed options. If you prefer to enter all options directly from the command line, you can use the following syntax:
asupgrade [-c|--console] [-V|--version] [-h|--help] [-s|--source source-domain-directory] [-t|--target target-domain-directory] [-f|--passwordfile password-file]
Explanations of these options are provided at the end of this procedure.
If a name used for an older domain that you are upgrading already exists in the new target domains directory, Upgrade Tool will ask if you want to rename the new directory so the old directory can be copied to the new installation.
If you type y in response, the directory is renamed domain-name.original. If that name already exists, the directory will be renamed domain-name.orginal.0. For example, if the old domain directory is named domain1, it will be renamed domain1.original, or if that name already exists, domain1.original.0.
If you type n, you are prompted to specify a different directory name or quit.
The domain is upgraded and the results are output to the console.
This output is also written to the output.log file for later review.
If there are any SEVERE or WARNING messages in the server.log file, the upgrade output will say "Possible error encountered during upgrade. See server log after upgrade process completes."
asadmin start-domain domain-name
Log in to the Administration Console with the user name and password you used in the older server.
Note - GlassFish Server 3.1 does not support NSS authentication. If you are upgrading from a Enterprise Profile configuration that uses NSS authentication, follow the procedure in Upgrading Installations That Use NSS Cryptographic Tokens.
Example 2-1 Using the asupgrade Command Line
The following example shows how to use the asupgrade command-line utility in non-interactive mode to upgrade an existing Sun GlassFish Enterprise Server v2.1 installation to GlassFish Server 3.1. The following command should be entered on a single line.
asupgrade -c -s /home/glassfish/domains/domain1 -f /root/mypassword -t /home/glassfish3/glassfish/domains
Listed below are the asupgrade command—line options, including the short form, the long form, and a description of each option.
|
Next Steps
If your older installation was configured with the Load Balancer Plug-in, you will need to download the latest version of the Plug-in Installer and configure it for use with GlassFish Server 3.1. For more information, see Chapter 7, Configuring Web Servers for HTTP Load Balancing, in Oracle GlassFish Server 3.1-3.1.1 High Availability Administration Guide.
Browse to the URL http://localhost:8080 to view the domain-dir/docroot/index.html file. This file is brought over during the upgrade. You may want to copy the default GlassFish Server 3.1 file from the domain1.original/docroot directory and customize it for your GlassFish Server 3.1 installation.
To register your installation of GlassFish Server from the Administration Console, select the Registration item from the Common Tasks page. For step-by-step instructions on the registration process, click the Help button on the Administration Console.
This procedure explains how to use the graphical Upgrade Tool Wizard to upgrade to GlassFish Server 3.1 from any supported older product release. See Supported Releases for Upgrade to GlassFish Server 3.1 for a list of supported releases.
Before You Begin
Ensure that the source domains from which you are upgrading are stopped before proceeding.
See Installing GlassFish Server From a Self-Extracting Bundle in Oracle GlassFish Server 3.1 Installation Guide for instructions.
Custom and third-party libraries should normally be located in the domain-dir/lib directory. This step is only necessary for custom or third-party libraries that may be located in the nonstandard as-install/lib directory.
Note - Use the Upgrade Tool that is located in the target GlassFish Server 3.1 installation, not the older source installation.
as-install-parent/glassfish/bin/asupgrade
as-install-parent\glassfish\bin\asupgrade.bat
Tip - You may find it faster to run the asupgrade command with the -s source-domain-directory option, which will prefill the Source Domain Directory field in the next step.
For example, you might type c:\glassfish\domains\domain1.
The default is the full path name of the domains directory of your GlassFish Server 3.1 installation (for example, c:\glassfish3\glassfish\domains).
The domain will be upgraded using these credentials. If you do not specify a password here, the default master password is used.
Note - GlassFish Server 3.1 does not support NSS authentication. If you are upgrading from a Enterprise Profile configuration that uses NSS authentication, follow the procedure in Upgrading Installations That Use NSS Cryptographic Tokens.
If a name used for an older domain that you are upgrading already exists in the new target domains directory, Upgrade Tool will ask if you want to rename the new directory so the old directory can be copied to the new installation.
If you click OK in response, the directory is renamed domain-name.original. If that name already exists, the directory will be renamed domain-name.orginal.0. For example, if the old domain directory is named domain1, it will be renamed domain1.original, or if that name already exists, domain1.original.0.
If you click No, you brought back to the main screen.
The domain is upgraded and the Upgrade Results page displays the status of the upgrade operation.
If there are any SEVERE or WARNING messages in the server.log file, the upgrade output will say "Possible error encountered during upgrade. See server log after upgrade process completes."
asadmin start-domain domain-name
Next Steps
If your older installation was configured with the Load Balancer Plug-in, you will need to download the latest version of the Plug-in Installer and configure it for use with GlassFish Server 3.1. For more information, see Chapter 7, Configuring Web Servers for HTTP Load Balancing, in Oracle GlassFish Server 3.1-3.1.1 High Availability Administration Guide.
Browse to the URL http://localhost:8080 to view the domain-dir/docroot/index.html file. This file is brought over during the upgrade. You may want to copy the default GlassFish Server 3.1 file from the domain1.original/docroot directory and customize it for your GlassFish Server 3.1 installation.
To register your installation of GlassFish Server from the Administration Console, select the Registration item from the Common Tasks page. For step-by-step instructions on the registration process, click the Help button on the Administration Console.