Upgrading to Version 8.1

The upgrade script upgrades the appliance to version 8.1 from any of the following versions:

7.3
7.3.0.1
7.3.1
7.3.1.1
7.3.1.2
8.0
8.0.1

Note
If you are upgrading from an earlier 7.X version you will first need to upgrade to one of the versions listed above.

It is a shell script that contains all of the required packages and binaries.

To run the upgrade you must be logged in as the root user with the root user environment.

You will also need to supply the credentials of a user with sufficient permissions to re-import the taxonomy and compile patterns.
The script does the following:

Displays a message stating the prerequisites for the upgrade.
Extracts archived files.
Configures System for Upgrade.
Upgrades Operating System, ADDM, and dependencies.
- Performs a Database Snapshot - optional. Where a snapshot is created, it can only be restored to an appliance running the pre-upgrade version.
- Upgrades ADDM and dependencies.
- Uploads, but does not activate, the latest Pattern Packages available at release.
- Performs Post Installation Configuration.

Changes to OS Configuration Files
If you have made changes to operating system configuration files on the appliance, these changes may be overwritten by the upgrade process. After the upgrade has completed, you must check any configuration files you have previously modified and reapply the changes as required.

Changes to Export Mapping Files
If you have made changes to export mapping files in default mapping sets, these changes will be overwritten by the upgrade process. You should make copies of any mapping files that you have modified. If you are customizing mapping files, you should create a new mapping set to contain them rather than modifying a supplied set.

Upgrade Script Options

The upgrade script has the following options:

Option	Description
`--no-snapshot`	Do not create a database snapshot before upgrading the BMC Atrium Discovery application. If created, a snapshot takes place after the operating system is upgraded, but before the BMC Atrium Discovery application is upgraded.
`--extract`	Extract the files from the archive contained in the script. This does not perform the upgrade. A manual upgrade is not supported.
`--tmpdir dirname`	Specify a directory in which to store temporary files. The default is `/tmp/twf.upgrade` *Note:* This directory needs at least 942MB.
`--no-clean`	Do not delete the temporary files extracted from the archive after the upgrade has been performed. The temporary files will be owned by the root user.
`--auto`	Automatic mode. Selecting this option means that all questions are automatically answered. Please note that invalid credentials provided will mean that a manual taxonomy import and pattern recompile will be necessary. Details and more information available in the log file on completion.
`--upgrade-discovery-scripts`	Upgrades the discovery scripts to their latest versions. Any local modifications will be lost. If this option is not specified, the scripts will not be modified, and must be updated manually using the Administration > Discovery Platforms UI after the upgrade is complete.
`--username`	BMC Atrium Discovery UI user. Only valid in automatic mode.
`--password`	BMC Atrium Discovery UI user password. Only valid in automatic mode. *Note:* If your password contains any special characters you must escape them with a backslash character, e.g. instead of $ use \$.
`--verbose`	Provide comprehensive messaging. This information is also logged in the file `/usr/tideway/log/upgrade_Vn.log`. See Messages in the Upgrade Log for notes on messages that may be logged.
`--help`	Displays a help message on the usage and options. The script then exits.

If you do not want to use the upgrade script to upgrade your appliance you should contact Customer Support.

Operating System and Architecture

The script is operating system and architecture specific. Download the one appropriate to your operating system and architecture. This is one of:

addm-Vn-nnnnn-upgrade.ga.rhel5.i386.sh.gz
addm-Vn-nnnnn-upgrade.ga.rhel5.x86_64.sh.gz

In the following procedure, the filename is referred to as addm-Vn-nnnnn-upgrade.ga.rhel5.<arch>.sh.gz. Replace <arch> with i386 or x86_64 in the commands as appropriate.

The Upgrade Procedure

Custom taxonomy files
If you have custom taxonomy files that update node summary lists using the before or after mode you must move these to a temporary location before starting the upgrade procedure. Failure to do this will cause the upgrade to fail. See defect 12803 on the known defects page or contact support for more details.

Delete the contents of the /var/spool/clientmqueue directory. Enter the following commands:

[root@localhost tmp]# cd /var/spool/clientmqueue
[root@localhost clientmqueue]# rm –f *
[root@localhost clientmqueue]# cd /tmp

Copy the addm-Vn-nnnnn-upgrade.ga.rhel5.<arch>.sh.gz file to a temporary directory, such as /tmp.

Unzip the archive file using the following command:

[root@localhost tmp]# gunzip -v addm-Vn-nnnnn-upgrade.ga.rhel5.<arch>.sh.gz

As the root user, run the upgrade script. Enter:

[root@localhost tmp]# sh addm-Vn-nnnnn-upgrade.ga.rhel5.<arch>.sh

The following message is displayed:

  Welcome to the BMC Atrium Discovery and Dependency Mapping Appliance 8.1 upgrade
  
  The script will perform the following (unless selected otherwise, see --help):
    - perform upgrade requirement checks
    - extract the relevant files from the archive into the selected directory
    - perform an ADDM snapshot
    - upgrade the Operating System, ADDM and all dependencies
    - perform any post installation steps
  
  To complete the upgrade, the script requires the following to complete:
    - ADDM credentials (taxonomy import, pattern compiling, discovery
          script modification) - you will be prompted for these during the
          ADDM upgrade.
  
  During the starting and stopping of httpd services you may see some
    output. This is expected and required to handle various
    Apache security configuration options.
  
  Please note that you need to be the root user for the upgrade!
  
   Do you have everything you need to complete the upgrade (yes/no)?

Enter yes if you have all that you need to perform the upgrade. Answering no aborts the installation.
The script checks that all system requirements are fulfilled and asks for credentials for the upgrade.

Performing upgrade requirements checks ... 

ADDM application (UI) credentials are required for upgrade.
Please use an ADDM application user with sufficient privileges,
for example the "system" user.

  Please enter ADDM user (Default: system):
  Please enter password for system:

Stopping services ... 
Stopping httpd: [ OK ] 

Services stop complete. 
Starting services ... 
Starting httpd: [ OK ] 

Services start complete. 
Checks complete.

Then the upgrade itself is commenced, beginning with extracting the files from the archive.

Starting Upgrade on Fri Dec 4 15:43:41 GMT 2009 ... 
------------------------------------------------------ 
STAGE 1: Archive Extraction. 
------------------------------------------------------

If the temporary directory does not exist you are asked whether it should be created. If it does exist you are asked whether you want to use it. Answering no aborts the installation.

Temporary directory /tmp/twf.upgrade does not exist, create it (yes/no)? yes 
Starting extraction ... 
Archive extracted. 
Unpacking Archive ... 
Archive unpacked. 
The default dashboard has been replaced. The original dashboard
was saved as /usr/tideway/etc/dashboards/cc95d72c949e9f7a09f0ac1103533e2e.dash.old
Extraction complete.

The upgrade then tests that the RPM will install correctly against the current system.

------------------------------------------------------ 
STAGE 2: RPM Upgrade Tests. 
------------------------------------------------------ 
Starting RPM upgrade test ... this may take a while, please be patient! 
Tests complete.

The next part of the upgrade is configuring the system, for example applying patches.

--------------------------------------------------------------- 
STAGE 3: Configure System for Upgrade 
--------------------------------------------------------------- 
Starting configuration ... 
Stopping services ... 
Stopping httpd: [ OK ] 

Services stop complete. 
Configuration complete.

The upgrade script now upgrades the operating system, the BMC Atrium Discovery application, and any dependencies.
```
------------------------------------------------------ 
STAGE 4: Upgrade Operating System, ADDM and dependencies 
------------------------------------------------------
```
Upgrading the operating system and BMC Atrium Discovery application may take a long time. If you are not running in verbose mode, you can monitor progress by checking the log file using the following command:
```
$ tail -f /usr/tideway/log/upgrade-Vn.log
```
During the operating system upgrade, some SELinux error messages are logged, these can be ignored. See Messages in the Upgrade Log for notes on messages that may be logged. Part of this stage is to create a snapshot unless you specified otherwise.
```
User requested to skip snapshot. 
Starting RPM Upgrade ... this may take a while, please be patient! 
Packages successfully upgraded.
  WARNING: One or more of the export mapping sets have changed in the new version of ADDM. Please see the log file and release notes for more details.
```

The BMC Atrium Discovery application has now been upgraded, but a number of configuration steps need to take place, for example re-importing the taxonomy and recompiling patterns.

--------------------------------------------------------------- 
STAGE 5: Post Installation Configuration. 
--------------------------------------------------------------- 
Starting services ... 
Services start complete. 
    Starting Security service: [  OK  ]

    Starting Model service: [  OK  ]

Importing the taxonomy ... 
Import taxonomy complete. 
Checking if to update traversal limit...
No need to update traversal limit
Stopping services ... 
Services stop complete. 
Starting services ... 
Starting httpd: [ OK ] 

Services start complete. 
Recompiling patterns ... 
Recompile complete. 
Old discovery scripts saved as /usr/tideway/etc/discovery-scripts-backup.xml.
Upgrade of discovery scripts complete.
Restarting the firewall to enable any changes.
Some hardware reference data is already present in your datastore, 
the upgrade will not install its own version. 
Restarting the firewall to enable any changes.

If you have asked to upgrade the discovery scripts, a back-up of the current scripts are first saved to /usr/tideway/etc/discovery-scripts-backup.xml. If this fails for any reason, you are asked to confirm whether you still want to upgrade the scripts.

The software upgrade process is now complete. If any further steps are required, in this case rebooting the system after a kernel upgrade, you are informed now, before the script exits.
The appliance is now running BMC Atrium Discovery version 8.1.

---------------------------------------------------------------
STAGE 6: Post Upgrade Task Summary
---------------------------------------------------------------
The Kernel has been upgraded. The system MUST be rebooted.

The default dashboard has been replaced. The original dashboard was saved as /usr/tideway/etc/dashboards/cc95d72c949e9f7a09f0ac1103533e2e.dash.old
  
WARNING: One or more of the export mapping sets have changed in the new version of ADDM. Please see the log file and release notes for more details.

Task summary can be found in /usr/tideway/log/postupgrade_8.1_TODO.log
--------------------------------------------------------------- 
Upgrade complete - Fri Dec 4 15:43:51 GMT 2009 ...

Reboot the appliance. Enter the following command:
```
{root@localhost tmp]# reboot
```

Messages in the Upgrade Log

During the upgrade the firewall (iptables) is restarted. When a kernel upgrade is part of the upgrade, the firewall is unable to restart as there is a mismatch between the running kernel's version and the kernel on disk. The firewall logs a FATAL message, but as this is entirely expected, the upgrade script wraps it in an information message:
2009-04-12 15:43:50: INFO: FATAL: Could not load /lib/modules/2.6.18-53.1.14.el5 /modules.dep: No such file or directory
This is expected behavior and does not indicate a problem with the upgrade.

During the upgrade, the following error may be reported:
Traceback (most recent call last):
File "./export_platforms.py", line 66, in <module>
File "./export_platforms.py", line 36, in main
File "./configuration.py", line 1465, in processCommandLine
File "./configuration.py", line 1432, in initialiseSystemAPIs
File "./configuration.py", line 1496, in initNaming
File "./naming.py", line 42, in init
File "/usr/tideway/lib/python2.6/site-packages/omniORB/CORBA.py", line 798, in _narrow
return _omnipy.narrow(self, repoId, 1)
omniORB.CORBA.TRANSIENT: CORBA.TRANSIENT(omniORB.TRANSIENT_ConnectFailed, CORBA.COMPLETED_NO)

This is a known issue (defect 12589) and can be ignored - this does not indicate a problem with the upgrade.

Deactivate Existing TKU

The upgrade installs a new TKU package (TKU-CORE-2009-11-1) but does not activate it. Any TKU Package that you have installed must be deactivated before activating the TKU-CORE-2009-11-1. Information on activating and deactivating TPL packages is available here.

Hardware Reference Data

The upgrade installs Hardware Reference Data (TKU-HRD-2009-11-1) unless you have already have a previous version installed.

Minimum slave version

The upgrade modifies the minimum slave version if it is older than 7.1. If it has already been configured to be 7.1 or later, it is not modified. The minimum slave release is also updated if it is not 0.0 and is too old. Check the discovery slave compatibility matrix to determine whether you need to upgrade discovery slaves.

Slave configuration file baseline check

The slave configuration file baseline check now checks the configuration file of all attached slaves, rather than just the local configuration file. As a result, after upgrade this check will display the error "FAILED: Expected results are missing" until it is re-baselined.

Clearing Browser Caches

After upgrading you should clear the cache of any client browsers or force a refresh (CTRL+F5 in most browsers).

Baseline Changes

The baseline tool tracks changes to the system configuration from a known baseline. After an upgrade, the appliance configuration will have changed significantly. You should view the baseline page after an appliance upgrade and examine the changes made to the system. When you understand the changes that have been made, you can rebaseline the appliance so that the tool can check for changes from the configuration after upgrading to the new version.

BMC Software