Upgrading to version 8.3

The upgrade script upgrades the appliance to BMC Atrium Discovery version 8.3 from the following supported versions:

8.2
8.2.01
8.2.02
8.2.03

There is no upgrade path from BMC Atrium Discovery version 7.5 to version 8.3. Rather, you need to migrate your data to a new installation of BMC Atrium Discovery version 8.3.

Note

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

What you need to proceed with this upgrade

You must be logged in as the root user with the root user environment.
The tideway services must be running when you run the upgrade.
The credentials of a UI user with sufficient permissions to re-import the taxonomy and compile patterns.
The upgrade script. Download the one appropriate to your architecture from the BMC Electronic Product Distribution (EPD) site. This is one of:
- 32 bit: ADDM_Upgrade_32_Vn_nnnnnn_ga.sh.gz
- 64 bit: ADDM_Upgrade_64_Vn_nnnnnn_ga.sh.gz
  Where <arch> with 32 or 64, and Vn_nnnnnn_ga is the version number. For example, ADDM_Upgrade_64_8.3_249314_ga.sh.gz.

Warnings

Required appliance specification increased

The required appliance specification has been increased to support the greater discovery capabilities of BMC Atrium Discovery version 8.3. Before upgrading you must ensure that the appliance you are upgrading meets the specification. See the appliance sizing guidelines for more information.

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.

Database upgrade

This upgrade performs an upgrade of the BMC Atrium Discovery database. It is highly recommended that you do not skip running a snapshot. Where a snapshot is created, it can only be restored to an appliance running the pre-upgrade version.

Upgrade considerations

Retaining the set timezone

When you run the upgrade, the timezone you have specified will be overwritten and returned to Europe/London unless you have updated the variable ZONE in /etc/sysconfig/clock. See Localizing the appliance for information on how to do this.

For users with multiple appliances

You may have a number of appliances, for example one or more appliances consolidating to a central consolidated appliance. When a system uses consolidation, the recommended approach is to stop discovery on scanning appliances, ensure that all consolidation operations are complete, and then upgrade all appliances before restarting discovery on the scanning appliances.

Consolidating appliances must always be upgraded first. An 8.3 consolidating appliance can accept data from an 8.2 scanning appliance. An 8.2 consolidating appliance cannot accept data from an 8.3 scanning appliance.

For users of CMDB Sync

Where an upgrade makes changes to syncmapping files (see Default CDM Mapping and Syncmapping block), the initial CMDB syncs after upgrade may cause longer reconciliation times. Examples of such changes are key changes or attribute changes on a CMDB CI.

Proxy ordering in upgraded appliances

To allow you to better scale your Windows discovery capabilities, Windows Proxy Pools have been added. These allow you to group sets of Windows proxies together, across which the system will distribute discovery requests in order to load balance.

While the pools themselves can be ordered, the proxies in them cannot. Consequently it is not possible to preserve the ordering that has been configured in pre-version 8.3 systems. If you need to preserve certain aspects of the ordering of your existing proxies, you should make a note of what you want to preserve before starting the upgrade.

The following ordering and distribution of proxies occurs automatically during the upgrade.

All Workgroup proxies are put into their own pool.
AD proxies are grouped by domain and IP restriction list. AD proxies with the same domain and restriction lists are placed in the same pool.
Credential proxies are grouped by IP restriction list.

VMware ESX/ESXi host identity changes and access method change

If a VMware ESX/ESXi host is discovered using ssh in the pre-upgrade version of BMC Atrium Discovery, its identity may change post upgrade. The discovery scripts now obtain more information which changes the os_class/os_type from UNIX/ESX Linux to Other/VMware ESX, and because the host's UUID and architecture is now discovered. However, the last_access_method remains ssh, so the new VMware ESX/ESXi discovery capabilities are not used. You can workaround this by following the following procedure:

Configure the new VMware ESX/ESXi discovery.
Cause the ssh discovery to fail and discover using the VMware ESX/ESXi discovery by:
1. Changing the username of the ssh credential used.
2. Scanning just those VMware ESX/ESXi hosts.
3. Reverting the ssh credential username.

Miscellaneous upgrade items

The following items are also affected by the upgrade:

Edge connectivity: Edge connectivity replaces Topology mapping introduced in BMC Atrium Discovery 8.2. If you have used Topology mapping, you can decide whether to retain it or try Edge connectivity. This is described in Edge connectivity in upgraded appliances.
Tomcat providers: where Tomcat discovery using JMX has been configured, the Tomcat providers are disabled. Tomcat discovery now uses configuration files.
Sensitive data filters: these have been updated and extended to retrieved files. If you have created custom filters for command line information then the upgrade makes no changes to these. If you have not created custom filters then the new defaults are installed.
SQL and JDBC credentials: where SQL and JDBC credentials are in use, their existing properties files continue to be used and updated properties files are installed but not used. Where such credentials are unused, the old properties files are replaced with the latest.
tw_options: where the values of BOGUS_SERIAL_FILTER and BOGUS_HOSTID_FILTER are the defaults, then they are upgraded to new defaults. If they are non-default, then they are not changed and a warning is written to the upgrade log.
Windows proxy configuration: Windows proxy configuration information previously held in the discovery.conf file is now moved to the vault.
New Runtime Environment node: the Runtime Environment Node replaces the Java SI. The upgrade attempts to find all patterns that trigger on the Java SI (their primary inference is on the Java SI) and writes them to the upgrade log. These patterns will no longer trigger as Java SIs are no longer created. You must modify these patterns to trigger on Runtime Environment Nodes.

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 `/usr/tideway/tmp/twf.upgrade` *Note:* This directory needs at least 2237MB.
`--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. See Managing the discovery platform scripts for more information.
`--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.

In the following procedure, the filename is referred to as ADDM_Upgrade_<arch>_Vn_nnnnn_ga.sh.gz. Replace <arch> with 32 or 64, and Vn_nnnnnn_ga with the version number, in the commands as appropriate. For example, ADDM_Upgrade_64_8.3_249314_ga.sh.gz.

The upgrade procedure

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

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

Copy the ADDM_Upgrade_<arch>_Vn_nnnnn_ga.sh.gz file to a temporary directory, such as /tmp.

Unzip the archive file using the following command:

[root@localhost tmp]# gunzip -v ADDM_Upgrade_<arch>_Vn_nnnnn_ga.sh.gz

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

[root@localhost tmp]# sh ADDM_Upgrade_<arch>_Vn_nnnnn_ga.sh

The following message is displayed:

  Welcome to the BMC Atrium Discovery and Dependency Mapping Appliance 8.3 upgrade
  
  The Release Notes for this version contain vital information for any user wishing to
  upgrade their appliance. Please ensure that you have read them prior to continuing.
  The Release Notes are available online:
  
  http://discovery.bmc.com/docs/83/Release+Notes
  
  Points to note:
    - The Appliance sizing guidelines have been revised in this release
    http://discovery.bmc.com/docs/83/Sizing+guidelines
    - It is important that you perform the post-upgrade tasks listed in
    the Post Upgrade Task Summary.
  
  To complete the upgrade you will need:
    - To execute this script as the root user
    - ADDM credentials for a user with admin privileges
    - If enabled, the passphrase with which the vault is protected
  
  
   Have you read the Release Notes, and 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.

Performing upgrade requirements checks ... 
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 Mon Oct 10 09:36:36 BST 2011
------------------------------------------------------ 
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 /usr/tideway/tmp/twf.upgrade does not exist, create it (yes/no)? yes 
Starting extraction ... 
Archive extracted. 
Unpacking Archive ... 
Archive unpacked. 
Unpacking Archive ... 
Archive unpacked. 
Renaming current dashboard to: /usr/tideway/etc/dashboards/297ab12da921ab324c1089485edb46c4.dash.old
The default dashboard has been replaced. The original dashboard
was saved as /usr/tideway/etc/dashboards/297ab12da921ab324c1089485edb46c4.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, BMC Atrium Discovery, and any dependencies.

------------------------------------------------------ 
STAGE 4: Upgrade Operating System, ADDM and dependencies 
------------------------------------------------------

Upgrading the operating system and the 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_V.n.log

During the operating system upgrade, some SELinux error messages are logged, these can be ignored. See Messages in the Upgrade Logfor notes on messages that may be logged. Part of this stage is to create a snapshot unless you specified otherwise.

Starting services ...
Starting httpd: [ OK ]
Services start complete.
Running snapshot ...
Snapshot complete.
Stopping services ...
Stopping httpd: [ OK ] 
Services stop complete.
Performing DB checkpoint
DB has been checkpointed.
Starting RPM Upgrade ... this may take a while, please be patient!
Tripwire requires re-baselining because the new policy file differs from
the currently configured policy file. A copy of the policy file has been made to
/usr/tideway/etc/twpol.txt.custom. Please reapply the customisations to the new default policy file,
/usr/tideway/etc/twpol.txt, and re-baseline tripwire as per instructions outlined in the
Configuration Guide.
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  ]
ADDM credentials are required for post installation. 
Please enter ADDM user: system 
Please enter password for system: 
Please re-enter password for system: 
Credential test for user system successful. 
Exporting existing taxonomy to /usr/tideway/var/previous_taxonomy.xml ...
Export taxonomy complete.
Importing the taxonomy ... 
Import taxonomy complete. 
Set Discovery record mode to 1
Moving Windows Proxy details to vault...
Starting Vault service: [OK]
Starting Discovery service: [OK]
Moved Windows Proxy details
Stopping Discovery service: [OK]
Stopping Vault service: [OK]
Stopping Model service: [OK]
Stopping Security service: [OK]
Stopping services ...
Services stop complete.
Starting services ...
Starting httpd: [OK]
  Services start complete.
  User changed BOGUS_SERIAL_FILTER; not updating to new default value.
    New default value (?i)^(0+|X+|DELL|0?1234567890?|.{1,3}|unknown|(system\s*)?serial\s?number|not\s?available|0x.{1,3}|-1|UNK|none|NEW_STRING|To be filled by OEM|See IPMI FRU|not\s?specified|undefined, but settable)$
    You can update the value by running (as tideway user, with services running):
      /usr/tideway/bin/tw_options --username=<username> BOGUS_SERIAL_FILTER="<default>"
    with appropriate credentials (you will be prompted for password).
  User changed BOGUS_HOSTID_FILTER; not updating to new default value.
    New default value (?i)^(0+|X+|DELL|0?1234567890?|.{1,3}|unknown|(system\s*)?serial\s?number|not\s?available|0x.{1,3}|-1|UNK|none|NEW_STRING|To be filled by OEM|See IPMI FRU|not\s?specified|undefined, but settable)$
    You can update the value by running (as tideway user, with services running):
      /usr/tideway/bin/tw_options --username=<username> BOGUS_HOSTID_FILTER="<default>"
    with appropriate credentials (you will be prompted for password).
  Recompiling patterns ...
  Recompile complete.
Old discovery scripts saved as /usr/tideway/etc/discovery-scripts-backup.xml.
Upgrade of discovery scripts complete.
Upgrade of discovery sensitive data filters complete.
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.3.

---------------------------------------------------------------
STAGE 6: Post Upgrade Task Summary
---------------------------------------------------------------
The Kernel has been upgraded. The system MUST be rebooted.
  
  Tripwire requires re-baselining because the new policy file differs from
  the currently configured policy file. A copy of the policy file has been made to
  /usr/tideway/etc/twpol.txt.custom. Please reapply the customizations to the new default policy file,
  /usr/tideway/etc/twpol.txt, and re-baseline tripwire as per instructions outlined in the
  Configuration Guide.
  
  User changed BOGUS_SERIAL_FILTER; not updating to new default value.
  New default value (?i)^(0+|X+|DELL|0?1234567890?|.{1,3}|unknown|(systems*)?serials?number|nots?available|0x.{1,3}|-1|UNK|none|NEW_STRING|To be filled by OEM|See IPMI FRU|nots?specified|undefined, but settable)$
  You can update the value by running (as tideway user, with services running):
  /usr/tideway/bin/tw_options --username=<username> BOGUS_SERIAL_FILTER="<default>"
  with appropriate credentials (you will be prompted for password).
  
  User changed BOGUS_HOSTID_FILTER; not updating to new default value.
  New default value (?i)^(0+|X+|DELL|0?1234567890?|.{1,3}|unknown|(systems*)?serials?number|nots?available|0x.{1,3}|-1|UNK|none|NEW_STRING|To be filled by OEM|See IPMI FRU|nots?specified|undefined, but settable)$
  You can update the value by running (as tideway user, with services running):
  /usr/tideway/bin/tw_options --username=<username> BOGUS_HOSTID_FILTER="<default>"
  with appropriate credentials (you will be prompted for password).
  Task summary can be found in /usr/tideway/log/postupgrade_8.3.0.90_TODO.log
---------------------------------------------------------------
  Upgrade complete - Mon Oct 10 09:36:46 BST 2011

Reboot the appliance. Enter the following command:
```
{root@localhost tmp]# reboot
```
The software and operating system upgrade is now complete.

Post upgrade steps

After installation there are a number of additional steps required depending on the configuration of the pre-upgrade system. For example, if you have already used CMDB synchronization, you need to update the CMDB.

As well as the notes on this page you should refer to the postupgrade_8.3_TODO.log written out by the upgrade script at STAGE 6 above. This contains tailored advice of the tasks that must be completed on that particular appliance and these must be completed for correct future behavior.

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:
2011-07-25 09:36:46: 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.

Check Windows proxy compatibility

Check the Windows proxy compatibility matrix to determine whether you need to upgrade Windows proxies.

Deactivate existing TKU and activate new TKU

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

You must activate the new TKU package, unless a newer TKU package is already activated. To know about the latest available TKU, see the latest TKU documentation.

Package changes for CDM Mapping and Discovery Conditions

The CDM Mapping and Discovery Conditions packages have been amalgamated into a single package. Previously, the packages were called:

TKU-CDM-Mapping-ADDM-8.2.2.90+.zip
TKU-Discovery-Conditions-ADDM-8.2.2.90+.zip

The new package is called:

TKU-System-2011-09-1-ADDM-8.3+.zip

Windows proxy configuration file baseline check

The Windows proxy configuration file baseline check now checks the configuration file of all attached Windows proxies, 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 BMC Atrium Discovery version 8.3.

Maximum cache size

If you upgrade from a version that permits larger cache sizes than the current, the cache size label (see model maintenance settings) is displayed incorrectly.

Export mapping sets

While upgrading, the script will check to see if there is a newer version of each of the installed mapping sets. If a mapping set has changed since the last version, either by the user modifying it or BMC Software releasing a newer version, then a warning is displayed to the user. The original mapping is renamed by the script to append ".old" to the mapping set descriptor (the file ending with ".properties") and "_old" to the directory containing the mapping files. The user can either:

Ignore the warning if the export framework is not being used.
Compare the old mapping set to the new one and keep the new one (i.e. do nothing).
Compare the old mapping set to the new one and decide to keep the old one, in which case the user needs to manually delete the newer mapping descriptor and directory and rename the old ones (removing the .old and _old postfixes).
Compare the old mapping set to the new one and merge the changes. If the changes to the mapping set have been performed by BMC Software then these changes will be listed in the release notes and the user can apply these changes manually to their own copy of the mapping set.