| Sun ONE Application Server 7 Installation Guide |
Chapter 5
Upgrading the Sun ONE Application Server SoftwareThis chapter contains instructions for upgrading an existing installation of the Sun™ Open Net Environment (Sun ONE) Application Server software to the Update release.
The following topics are addressed here:
Preparing to UpgradeThe Sun ONE Application Server upgrade program allows you to upgrade an existing Sun ONE Application Server 7 installation without needing to re-install the complete product. The upgrade functionality works for package-based installations as well as tar or zip installations, relying on operating system-specific mechanisms wherever necessary.
This section addresses the following topics:
Upgrade Components
The Sun ONE Application Server 7 upgrade is bundled as part of the full installation. The files needed for the upgrade are present in the ‘upgrade‘ directory in the full installation.
Requirements and Restrictions
- Access privileges
- On Solaris—Perl and pkgadd utilities must be present in the PATH environment variable.
- On Linux—Perl and rpm utilities must be present in the PATH environment variable.
- On Microsoft Windows—Perl must be installed on the system. A free Perl distribution for Windows can be found here:
http://www.activestate.com/Products/ActivePerl/
- Admin Server and instances—The Admin Server and application server instances cannot be running while the upgrade is in progress. If they are running, they will be stopped by the upgrade program.
- Configuration files—Your Sun ONE Application Server configuration files must not be modified during upgrade. If they are, those modifications will be overwritten when the configuration files are copied back to their installation locations.
- JDK—The upgrade program will not upgrade any existing Java Developers Kit (JDK). This is assumed to be a shared resource and as such it is a customer responsibility to upgrade this software if needed.
- NSS/NSPR packages—For an upgrade, the presence of Netscape Security Services (NSS) and Netscape Portable Runtime (NSPR) packages is assumed as part of your existing Sun ONE Application Server. If the NSS/NSPR packages are not present, you should not proceed with the upgrade. Your Sun ONE Application Server is either not installed, or it is corrupted. In either case, you will have to fully install the Sun ONE Application Server software.
- Do not modify the following files while the upgrade process is running:
- Interrupting an upgrade—If you need to interrupt an upgrade, you can do so and then restart where you left off. However, until you have completed the upgrade, the server instance you are upgrading is in an inconsistent state, so it is important that you complete any upgrade you have started.
How the Upgrade Program WorksThe upgrade program is a Perl script that uses a package list file to determine the parameters of your upgrade. A list of packages that need to be upgraded is contained in the package-list file.
The upgrade process consists of three phases: backup, installation, and reconfiguration. Log files are provided for monitoring and troubleshooting the upgrade process through these phases.
This section discusses the following topics:
Backup Phase
For Microsoft Windows and evaluation installations, at the start of the upgrade process, the upgrade program copies your Sun ONE Application Server configuration files to a separate location so they will not be affected by the upgrade process. In the reconfiguration phase at the end of the upgrade, these files are copied back to their original locations.
For Solaris package-based installations, the class action scripts take care of copying the configuration files.
For Linux RPM-based installations copying the configuration files to a separate location is not necessary due to the nature of the post-install mechanism.
The backup directory is located under the directory where you uncompressed and expanded the upgrade files.
Installation Phase
During the installation phase, the upgrade program verifies that there is enough disk space available to do an upgrade of the relevant packages and then installs the upgrade components on the system.
If the installation phase fails, invoking the upgrade script will restart the installation after the last fully-installed package. The upgrade program refers to the audit file to see where the upgrade process was interrupted, and restarts appropriately. For example, if three out of five packages are already installed and an error occurs during installation of the fourth package, a restart would initiate a complete installation of the fourth package.
Reconfiguration Phase
In the reconfiguration phase, your original Sun ONE Application Server configuration files are copied back to the relevant installation location. This is relevant only on Microsoft Windows and evaluation installations.
It is up to you to prevent others from modifying the Sun ONE Application Server configuration files during upgrade; the upgrade program has no mechanism for preventing this.
Log Files
The events, errors, and status of the upgrade program are logged to the following files:
Upgrade Log File
Upgrade events and errors are captured in the upgrade.log, file during the active upgrade process. For commonly-encountered errors, the most likely action needed is included in this file for your convenience.
Audit File
An audit file,upgrade_state, is used to maintain the state of the upgrade, which might be needed if failure occurs and the upgrade process is restarted. Using the audit file, the upgrade process can recover by restarting the upgrade after the last fully-installed component.
The audit file is located under the directory where you uncompress and expand the upgrade files.
Upgrading the Sun ONE Application ServerThis section provides instructions for upgrading Sun ONE Application Server installations.
- Verify that you have reviewed the information discussed in "Requirements and Restrictions".
- Navigate to the directory where you unpacked the installation files.
- Invoke the upgrade script as follows:
./upgrade
Note
On Microsoft Windows—You can navigate using Microsoft Windows Explorer to the directory where you unzipped the files and run perl upgrade to start the upgrade process.
- The upgrade program verifies the profile (version number, package-based or not) of your currently-installed Sun ONE Application Server. If it is not correct for the upgrade you selected, an error message displays.
- The upgrade program determines if you have enough free space to perform the upgrade. If you do not, an error message displays.
- The upgrade program detects any running Sun ONE Application Server processes and stops them before continuing to upgrade.
- The upgrade program presents you with queries appropriate to the type of upgrade you selected.
Respond to the prompts as appropriate for your site.
- After the upgrade is complete, start the Admin Server and the application server instances. Instructions can be found in the Sun ONE Application Administrator’s Guide.
- Verify that the upgrade succeeded by running the asadmin version command. You should see the new upgraded version of the Sun ONE Application Server.
TroubleshootingThis section discusses possible problems that can occur during the upgrade process, and provides some suggested solutions.
To Restart or Interrupt an Upgrade
- Restarting and upgrade—To restart the upgrade process for any reason, remove the upgrade_state file in the directory where the upgrade script is located and restart the upgrade.
- Interrupting an upgrade—If you need to interrupt an upgrade, you can do so and then restart where you left off. However, until you have completed the upgrade, the server instance you are upgrading is in an inconsistent state, so it is important that you complete any upgrade you have started.
Error Situations
- If the errors are system-specific—For example, if package-based installation consistently fails, examine the package installation logs.
- If the errors are specific to the location being specified for backup—Check your access permissions for the directory specified.
- If the errors are specific to the user ID (in the case of tarball installations)— Check your permissions for the installation directory and the backup directory.
- If the errors occur during the backup phase—The upgrade script can be restarted. The most likely error in this phase is related to space limitations. After resolving any problems, you can restart the upgrade program where it left off.
- If errors occur during the reconfiguration phase—Problems are usually caused by a system crash or other interruption. After resolving any problems, you can restart the upgrade program where it left off.
