| 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.
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 Update 1 upgrade is distributed as a compressed archive which contains the setup file, a README file, configuration files used by the upgrade program, log files, and the Sun ONE Application Server packages to be upgraded.
Requirements and Restrictions
- Access privileges
- 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.
- Upgrade locations—If you did not install to default locations during your previous installation, you will need to edit the config_01 file to specify the correct locations.
- 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.
- Unzip utilities must be present in the PATH environment variable (distributed as packages to Solaris 8 and 9). A free distribution for Windows can be found here:
- On Solaris, the pkgadd utility must be present in the PATH environment variable.
- Perl (at least 5.0.0) must be installed on the system (distributed as a package to Solaris 8 and 9). A free Perl distribution for Windows can be found here:
- JDK and Sun ONE Message Queue—The upgrade program will not upgrade any existing JavaTM Developers Kit (JDK) or Sun ONE Message Queue software. These are assumed to be shared resources 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.
- JDK and Sun ONE Message Queue—The upgrade program will not upgrade any existing Java Developers Kit (JDK) or Sun ONE Message Queue software. These are assumed to be shared resources, and as such it is a customer’s responsibility to upgrade this software if needed. For convenience, the latest supported version of Sun ONE Message Queue is available in the /imq directory of the Sun ONE Application Server 7, Update 1 download archive. Instructions are contained in the README available in that directory.
How the Upgrade Program WorksThe upgrade program is a Perl script that uses an input file and a package list file to determine the parameters of your upgrade. For a package-based installation, a list of packages that need to be upgraded is contained in the package-list file.
The following topics are discussed in this section:
Upgrade Input File
The config_01 file contains the locations that the upgrade program will need to upgrade your Sun ONE Application Server software. The entries in the config_01 file specify the following locations:
- ASINSTDIR— Sun ONE Application Server installation directory. This is where the Sun ONE Application Server binaries are located.
- ASCONFDIR—Sun ONE Application Server configuration files directory. This is where the domains.bin, appserv.lic, and asenv.conf files are located.
- ASDOMAINSDIR—Sun ONE Application Server domains directory. This is where folder domains are located.
- ASLOCALE—Sun ONE Application Server locale. If you are not sure about this location, check AS_LOCALE in your ASCONFDIR/asenv.conf file.
- ASJAVADIR—Location of the JDK directory used by Sun ONE Application Server.
If you selected the default installation locations during your initial installation, the locations in the input file will be correct and you do not need to edit the file.
If you did not accept the default installation locations, you will need to edit the input file.
Example Default Input File
config_01
BASEDIR = /opt
ASINSTDIR = /opt/SUNWappserver7
ASCONFDIR = /etc/opt/SUNWappserver7
ASDOMAINSDIR = /var/opt/SUNWappserver7
ASLOCALE = en_US
ASJAVADIR = /usr/j2sepackage-list
SUNWasacmo
SUNWasro
SUNWasaco
SUNWjaxp
SUNWxrpcrt
SUNWaso
.version
7.0.0_01Upgrade Process
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,.audit_upgrade, 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:
At the download site, you will see a number of available archives. For example, the Sun ONE Application Server 7, Update 1 archive is version 7.0.0_01.
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 archive to the target machine (XX indicates the version).
- Uncompress and expand the upgrade release archive. You will see the following upgrade components:
- If the default installation locations were not accepted during installation, edit the config_01 input file to contain the following entries. If you accepted the default locations, you can skip this step. In other words, this file must reflect the your actual locations.
ASINSTDIR=/opt/SUNWappserver7
ASCONFDIR=/etc/opt/SUNWappserver7
ASDOMAINSDIR=/var/opt/SUNappserver7
ASLOCALE=en_US
ASJAVADIR=/usr/j2se- Invoke the upgrade script as follows:
./setup
- 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.
- The upgrade components will be installed in the locations specified in the upgrade input file.
- After the upgrade is complete, start the Admin Server and the application server instances. Instructions can be found in “Starting and Stopping the Server” on page 95.
- 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 .audit_upgrade 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.
