Preparing to upgrade

This section provides information about the steps you need to follow before performing an upgrade.

Whether you are upgrading and migrating customizations or simply upgrading, you must first back up the current installation. If the .kml file or any of the .km files for the new version of BMC PATROL for Apache Tomcat and Generic Java Server KM has a different file name from the previous version, you must remove those files from the list of KMs that are preloaded on the PATROL Agent.

Related Topic

Upgrading

Before you begin

Full parameter path usage

The default setting for BMC PATROL for Apache Tomcat and Generic Java Server KM version 3.1.00, and later, is to display the full parameter path in the PATROL console. In previous releases, a hash key format was used to abbreviate long parameter paths.

Parameters path examples

Parameter path examples.png

This change can impact your upgrade plans. The parameter history can be lost as a result of the upgrade because the parameter path can change during the upgrade from the shortened hash key format to the full parameter path. If a hash key was used for the parameter path in the earlier KM version, this is the parameter path that the KM stored in the monitored environment's database. When this parameter path changes to the full parameter path, the KM uses the new path to identify the parameter in the monitored environment's database, and the old hash key path is unused.

After the KM version upgrade begins, the first monitored environment that is encountered will determine if the parameter's full path or a hash key format is used in the PATROL console.

To configure the KM to use the hash key format click here...
  1. In the PATROL console, select a monitored environment and choose KM Commands > KM Administration > Define JVM Arguments.
  2. In the Java Home Details dialog box, enter the following JVM argument:
    -DLongInstnaceMapping=false
  3. Click OK.

To back up the current installation

If you plan to migrate your customizations, determine whether you can migrate from a previous version of BMC PATROL for Apache Tomcat and Generic Java Server KM.

Back up your customizations so that you can restore the current installation if you want to roll back your upgrade.

  1. Shut down any PATROL Agents, consoles, and related services that are currently running.
  2. Ensure that no one is accessing any PATROL files or directories.
  3. Perform a full backup of the directories where PATROL files are typically stored. These directories are listed in the following tables:

Windows

Executables and data

PATROL_HOME for agent and console installation directories

Console customizations

PATROL_CACHE for the console working cache

UNIX and Linux

Executables and data

PATROL_HOME/.. for agent and console installation directories

Console customizations

PATROL_CACHE for the console working cache

Automatic migration of console and agent customizations

Only customizations to Knowledge Modules must be migrated. Whether you choose to save and migrate your KM customizations or not, the customizations you have made to the following components are preserved and incorporated into the new version automatically:

  • Agents - Stored in the agent configuration file
  • Consoles - Stored in the console cache files

 

Note

Customized Knowledge Modules and PSL files are also stored in the cache but they are not automatically preserved and incorporated.

Migrating customizations with the PATROL Configuration Manager

BMC recommends that if you have customized KMs that these customizations should be migrated to the PATROL Configuration Manager rulesets. PATROL Configuration Manager rulesets allow you to manage customizations to KMs, depending on the type of customization.

  1. If you have localized parameters or global parameters that have customized poll times or thresholds, use the AS_CHANGESPRING KM to migrate these customizations into PATROL Configuration Manager rulesets.
  2. If you have created custom recovery actions, follow these steps:
    • Ensure that you have made a record of your customizations and have backed up the customized files in the PATROL_HOME and PATROL_CACHE directories.
    • Uninstall the old version of BMC PATROL for Apache Tomcat and Generic Java Server.
    • Install the new version of BMC PATROL for Apache Tomcat and Generic Java Server KM as described in the Performing the installation section.
    • Ensure that you have made a record of your custom recovery actions.
    • Use the Recovery Action Event Management commands as described in the PATROL Configuration Manager User Guide to migrate your custom recovery actions to the PATROL Configuration Manager.

Determining the location of PATROL

During the installation process, the PATROL Installation Utility records where it installs PATROL components in environment variables. To function properly, various components of the PATROL product, such as the migration tools, require the information stored in these variables. Two important variables are PATROL_HOME and PATROL_CACHE. 

Throughout this section, all references to PATROL_HOME represent %PATROL_HOME% if you are using Windows and $PATROL_HOME if you are using UNIX. All references to PATROL_CACHE represent %PATROL_CACHE% if you are using Windows and $HOME/patrol if you are using UNIX.

Default values for PATROL location variables

If you do not specify a location for the PATROL installation, the installer uses the following preprogrammed default locations and stores these locations in environment variables.

Default Values for PATROL Location Variables

Variable

Windows Default Value

UNIX Default Value

PATROL_HOME

C:\Program Files\BMC Software\Patrol3

/opt/bmc/Patrol3

PATROL_CACHE

%HOMEDRIVE%%HOMEPATH%\Patrol33

$HOME/Patrol33

Viewing environment variables set by PATROL

To view the value of PATROL_HOME, PATROL_CACHE and other environment variables, perform the appropriate procedure for your operating system:

Microsoft Windows

Using the Control Panel tools

  1. From the Start Menu, select Start > Settings > Control Panel.
  2. Open the Systemapplication.
  3. Select the Environmenttab.
  4. Scroll through theSystem Variable list box to view the variables.
    Note: The System application displays PATROL_CACHE only if it is set to a value other than its default value. Using the PATROL Environment Probe.
  5. From the Start Menu, select Start > Programs > BMC PATROL > PATROL Environment Probe.
  6. Scroll to the variables that you want to view.

UNIX using Bourne or Korn Shell

  1. At the shell command prompt, type export and press ENTER. 
  2. The shell displays a list of environment variables and their values. Note: If PATROL_HOME is not set, run patrolrc.sh.

UNIX using C Shell

  1. At the shell command prompt, type setenv and press ENTER. 
  2. The shell displays a list of environment variables and their values. Note: If PATROL_HOME is not set, run patrolrc.sh.

Creating an installation package of the merged BMC PATROL for Apache Tomcat and Generic Java Server

After you have migrated and merged your customizations, you must create an installation package that can be used with the installation utility to install locally on one computer or with Distribution Server, to install remotely on multiple computers.

  1. Copy the entire contents of the BMC PATROL for Apache Tomcat and Generic Java Server files to a temporary directory on a hard drive on a server. You can delete this temporary directory after you have successfully created an installable image.
  2. Navigate to the packaged_results directory for the merged package and open the .ppf file with a text editor. Write down the file name in the first line of the .ppf file. This file name is the name of the directory that you will look for in the Products directory of the CD image.

  3. Rename the packaged_results directory with the file name that you found in the .ppf file in the previous step.

    Example

    If pokckm/8.5.00/030107-233044 was listed in the first line of the .ppf file, you would use pokckm as the directory name.

  4. Copy the renamed directory to the Products directory of the temporary directory that you used in Step 1. You will be replacing the files there with the merged files that contain your customizations.

  5. Copy the upgrade BMC PATROL for Apache Tomcat and Generic Java Server files to the server that you will use to install BMC PATROL for Apache Tomcat and Generic Java Server.

    Note

    • Remove the files in the PATROL_CACHE directory by following the instructions in Removing files from the PATROL_CACHE directories.
    • Install BMC PATROL for Apache Tomcat and Generic Java Server from the target server by following the instructions in  Installing for the first time .

Removing files from the PATROL_CACHE directories

Before you install, you must remove the current BMC PATROL for Apache Tomcat and Generic Java Server files from the  PATROL_CACHE  directory for the console. If you do not, old product files in  PATROL_CACHE  are loaded instead of the newly installed files from  PATROL_HOME . You may wish to create a backup copy of the files elsewhere on your system before deleting the files. 

Delete files with the following naming patterns from  PATROL_CACHE\knowledge and  PATROL_CACHE\psl:

  • TCT*
  • GJS*


 

 

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*