Upgrading in a BMC PATROL Environment

 Preparing to 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 PATROL for Exchange Servers 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.

Before you begin

• If you plan to migrate your customizations, determine whether you can migrate from a previous version of PATROL for Exchange Servers. See the following table to determine whether migration is supported for your current version of PATROL for Exchange Servers.
• You should complete this process on a limited number of computers in the test environment first, test the merged KMs thoroughly, and then deploy them to your production environment.
• When upgrading, you must stop the PATROL Agent Service before running the installer.
• When upgrading, you must close the PATROL Console before running the installer.

If you have a previous version of PATROL for Exchange Servers installed on the target computer, you have two options for upgrading to the new version of PATROL for Exchange Servers.

• Upgrading without saving KM customizations
• Upgrading and preserving KM customizations

Automatic migration of console and agent customizations

Only customizations to KMs must be migrated.

Whether you choose to save and migrate your KM customizations or not, the customizations you have made to

• Agents—stored in the agent configuration file
• Consoles—stored in the console cache files

are preserved and incorporated into the new version automatically.

Determining whether you can migrate KM customizations

Before migrating customizations, you must determine whether or not your customizations to PATROL for Exchange Servers can be migrated to the new version of PATROL for Exchange Servers. See the following table to determine whether migration is supported for your current version of PATROL for Exchange Servers. If migration is supported, select one of the following installation procedures to migrate your customizations:

• Migrating customizations manually ( Migrating customizations manually)
• Migrating customizations using the PATROL Configuration Manager ( Migrating customizations using the PATROL Configuration Manager)

 Versions that you can migrate

Conditions for upgrading

Use the following table to help you choose an upgrade procedure.

   Choosing an upgrade procedure

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 PATROL Configuration Manager, require the information stored in these variables. Two important variables are PATROL_HOME and PATROL_CACHE.

Throughout this book, all references to PATROL_HOME represent %PATROL_HOME% in a Windows environment and $PATROL_HOME in a UNIX environment. All references to PATROL_CACHE represent %PATROL_CACHE% in a Windows environment and $HOME/patrol in a UNIX environment.

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

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 or shell:

Upgrading without saving KM customizations

If you do not want to save any customizations of .km files, PSL code, alarm thresholds, or events, you can simply install the new version of PATROL for Exchange Servers over your previous version after moving or deleting PATROL for Exchange Servers files from the PATROL_CACHE and PATROL_HOME directories. See First-time Microsoft Exchange Servers installation for instructions.

Upgrading and preserving KM customizations

If you want to upgrade to the new version of PATROL for Exchange Servers, and you want to preserve any customizations you have made to the .km files in the previous version of PATROL for Exchange Servers, you must either migrate your customizations manually or use the PATROL Configuration Manager.

Customizations made to PATROL for Exchange Servers can include changes to the parameter alarm ranges, states, or other parameter properties.

Migration of .km files with the PATROL Configuration Manager is automated, with the following exceptions:

• Modified PSL code, whether it is embedded in .km files or in .psl files
• New KMs that you created

After you install the new version of PATROL for Exchange Servers, use the PATROL Configuration Manager rules and rulesets to migrate your customizations into PATROL for Exchange Servers version 5.3.00.

To back up the current installation

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. Verify that the following processes are stopped: MSEXCHE2E.exe, MSEXCHRoundtrip.exe, MSEXCHMapidata.exe, MSEXCHInetE2E.exe, MSEXCHInetE2E_Receive.exe, and MSEXCHInetE2E_Send.exe. If the processes are not stopped, use the Task Manager to stop them.

Remove the following obsolete or changed .kmfiles from the list of preloaded KMs on each PATROL Agent:

 Obsolete Knowledge Module files

1. Ensure that no one is accessing any PATROL files or directories.

2. Perform a full backup of the directories where PATROL files are typically stored. These directories are listed in the following table:
   
   

   Executables and data	Directory
   Executables & Data	PATROL_HOME for agent and console installation directories on Windows
   	PATROL_HOME/.. for console installation directories on UNIX
   Console Customizations	PATROL_CACHE for the console working cache on Windows
   	PATROL_CACHE for the console working cache on UNIX

Migrating customizations manually

If you have only a few customizations, you might find manual migration easier than migrating using the PATROL Configuration Manager. If you have made customizations to the PATROL Script Language (PSL) code, you must manually migrate those customizations. This task contains a procedure for manually migrating each kind of customization.

Before you begin

You must move the current PATROL for Exchange Servers 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. 

Copy the PATROL for Exchange Servers files with the following naming patterns to a directory outside the PATROL installation and delete them from PATROL_CACHE\knowledge and PATROL_CACHE\psl:

• MSEXCH.km
• MSEXCH.psl

To migrate customizations to KM files manually

1. 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.
2. Uninstall the old version of PATROL for Exchange Servers as described in Uninstalling PATROL for Exchange Servers.
3. Install the new version of PATROL for Exchange Servers as described in the section Installing for the first time.
4. Identify and record the coding changes, which represent your customizations, in PATROL for Exchange Servers by comparing the content of the ASCII files in the newly installed PATROL for Exchange Servers version with the content of the customized ASCII files with the same name that is saved in the directory to which you moved the old version.
5. Incorporate your customizations to the new PATROL for Exchange Servers by performing the following steps:
   1. Restart the PATROL Console.
   2. Load the newly installed PATROL for Exchange Servers.
   3. Using a PATROL developer console, enter the customizations that you identified in step 4, one by one.

To migrate customized PSL code

Customizations made to PATROL Script Language (PSL) code are not automatically migrated. These customizations might be embedded in .km files or stored in separate .psl files. Migrate these customizations manually, using the following guidelines:

• If you modified .psl files that were shipped by BMC, you must manually re-edit the PSL code in the new KM by using a PATROL developer console to reapply your changes.
• If you modified PSL code embedded in a .km file, that code will be overwritten when you install a new version of the product. You must manually edit the new .km files by using a PATROL developer console to reapply your changes.
• If you created a new PSL file (not shipped by BMC) outside of a .km file, or if you created new PSL code (not shipped by BMC) and embedded it in a .km file that was shipped by BMC, use the pslsearch utility to search your .km, .psl, and .ctg files for terms that you might have used that have since been adopted by BMC as PSL keywords. Rename any terms that pslsearch identifies as matching existing keywords. Reapply your changes by using a PATROL developer console. For instructions about using the pslsearch utility, see the PATROL Migration Tools User Guide.

Migrating customizations using the PATROL Configuration Manager

Use the AS_CHANGESPRING KM, a component of the PATROL Configuration Manager, to migrate customizations to PATROL for Exchange Servers. The AS_CHANGESPRING KM identifies all of your customizations and creates a RuleSet equivalent to these customizations. Use this RuleSet to apply the customizations to the new version of PATROL for Exchange Servers.

For more information about creating and using RuleSets, see the PATROL Configuration Manager User Guide.