| Sun ONE Application Server 7 Installation Guide |
Chapter 6
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 7 software to the Update 2 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 distributed as a compressed archive which contains the setup file, a README file, configuration files used by the upgrade program, and the Sun ONE Application Server packages to be upgraded. Log files are generated during the upgrade process.
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
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.
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 installation location.
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 ServerSun ONE Application Server upgrade downloads are available at the following location:
http://wwws.sun.com/software/download/app_servers.html
At the download site, you will see a number of available archives. For example, the Sun ONE Application Server 7, Update 2 archive is version 7.0.0_02.
Perform the following steps to upgrade your Sun ONE Application Server software:
- Verify that you have reviewed the information discussed in "Requirements and Restrictions".
- Verify the presence of the Netscape Security Services (NSS) and Netscape Portable Runtime (NSPR) packages. Refer to "Solaris Patches Required" for information and guidelines on these packages.
- Download the compressed upgrade release Update 2 archive to the target machine.
- Uncompress and expand the upgrade release archive. The directory package contains the upgraded versions of the packages to be installed.
- Invoke the upgrade script as follows:
./setup
Note
On Microsoft Windows—You can navigate using Microsoft Windows Explorer to the directory where you unzipped the files and run perl setup 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 "Starting and Stopping the Server".
- 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 setup 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.
