Migrating from version 8.3.x to 9.0

The following procedure enables you to migrate from a BMC Atrium Discovery version 8.3.x appliance (32 or 64 bit) to a new version 9.0 appliance. This migration consists of creating a backup of the 8.3.x appliance and restoring it on the 9.0 appliance. The 9.0 appliance detects that the data comes from an 8.3.x appliance and then makes the changes required to bring the data into the new model and then re-indexes the datastore. It requires the following major steps:

Install a BMC Atrium Discovery version 9.0 appliance

Installing a BMC Atrium Discovery version 9.0 appliance is described in Installing BMC Atrium Discovery for an appliance running on a hardware platform, and in Installing the virtual appliance for a virtual appliance.

If you are using a multi-disk configuration, use the disk configuration utility to specify the correct disk usage before migrating data to the new installation.

Download the migration script from the version 9.0 appliance

On the BMC Atrium Discovery version 9.0 appliance:

1. From the Appliance section of the Administration tab, click Backup & Restore.
   The Appliance Backup page is displayed. At the bottom of the page is a link to an archive containing the migration script.
   

2. Download the migration script and copy it to the version 8.3 appliance. You can do this in one operation using wget from a command line on the version 8.3 appliance. In the following example, the version 9.0 appliance is called 90appliance and the 8.3 appliance is called 83appliance. Enter:

   [tideway@83appliance ~]$ wget http://90appliance.bmc.com/addm_8_3_migration.sh.gz
   --2012-08-20 10:22:46--  http://90appliance.bmc.com/addm_8_3_migration.sh
   Resolving 90appliance... 192.168.1.101
   Connecting to 90appliance.bmc.com|192.168.1.101|:80... connected.
   HTTP request sent, awaiting response... 200 OK
   Length: 27650 (27K) [application/x-gzip]
   Saving to: `addm_8_3_migration.sh.gz'
   
   100%[======================================>] 27,650      --.-K/s   in 0s
   
   2012-08-20 10:22:46 (429 MB/s) - `addm_8_3_migration.sh.gz' saved [27650/27650]
   
   [tideway@83appliance ~]$
   

3. Extract the migration script from the downloaded archive. Enter:

   [tideway@83appliance ~]$ gunzip addm_8_3_migration.sh.gz
   [tideway@83appliance ~]$ sh addm_8_3_migration.sh --extract
   ADDM 8.3.x Migration Script Archive
   ===================================
   This script extracts the ADDM 8.3.x migration utility into a directory called
   addm_8_3_migration which it creates. Once you have run this script, change into
   the addm_8_3_migration directory where you can run the migration utility. The
   migration utility creates a backup of an ADDM 8.3.x appliance which can be
   restored on a 9.0 appliance.
   ...
   

Run the migration script on the 8.3.x appliance

This step also includes moving the migration data to the 9.0 appliance. This is recommended as it does not require sufficient free disk space for the back up on the 8.3.x appliance. You must run the migration script as root.

$TIDEWAY/bin/tw_restore --verify-only --backup-ssh
    --backup-dir=/usr/tideway/var/backup
    --remote-user=tideway --remote-password=password
    --host=de-32.bmc.com
    --username system

1. Change to the root user the su command. Enter:

   [tideway@83appliance ~]$ su
   Password:
   [root@83appliance tideway]# 

2. Change into the addm_8_3_migrationdirectory and run the migration utility. The example here shows the utility being used to migrate the data over SSH to the backup directory on the version 9.0 appliance.

   [root@83appliance tideway]# cd addm_8_3_migration
   [root@83appliance addm_8_3_migration]# ./tw_addm_8_3_migration --backup-ssh
   --backup-dir=/usr/tideway/var/backup --host=90appliance.bmc.com --remote-user=tideway

3. You are prompted for a password. The password required is that of the BMC Atrium Discovery system user of the local (8.3) host.

   Local ADDM appliance password for user system: <system user password>

4. When the system user password has been accepted, the SSH backup commences. Enter the password of the user specified in the --remote-user option above. In this example, this is the tidewayuser.

   Starting remote backup (SSH)
   Remote password: <tideway user password>
   Task: Stopping Services
   ...
   Successfully created archive addm_cmdb_sync.tgz
   Successfully created archive addm_export_adapters.tgz
   ...
   Backup datastore Data: Time left 2 mins 15 secs, Processed: 84%
   ...
   Task: Starting Services
   

   The backup of the the 8.3.x appliance has now been created in the /usr/tideway/var/backup directory of the 9.0 appliance.

Additional notes on backing up to a Windows share

If you undertake the backup to a Windows share, you also have to enter the BMC Atrium Discovery system user password at the initial prompt. Then you must enter the password of the remote user on the Windows share. Parts of example sessions are shown below. The commands are entered on a single line, but are shown over multiple lines to make them easier to read.

[root@83appliance addm_8_3_migration]# ./tw_addm_8_3_migration --backup-smb
     --host=137.72.95.127 --share=tideway --backup-dir=tmp
     --remote-user=tideway
Password: <system user password>
Starting remote backup (Windows share)
Remote Password: <tideway user password for Windows share>
Task: Stopping Services
...

[root@83appliance addm_8_3_migration]# ./tw_addm_8_3_migration --backup-smb
     --unc-path='\\hostname\sharename\directoryname'
     --remote-user="mydomain/username" --remote-password="changeme"
Password: <system user password>
Starting remote backup (Windows share)
Task: Stopping Services
...

If you do backup to a Windows share, then you will have to transfer the backup from the share to the /usr/tideway/var/backup directory of the 9.0 appliance.

Command line options for the tw_addm_8_3_migration utility

The following table details the command line options available for the tw_addm_8_3_migration utility. Common command line options are shown in Using command line utilities.

Restore the migrated data on the 9.0 appliance

For a local restore, the backup must be present on the 9.0 appliance in the /usr/tideway/var/backup directory and can be restored using the backup and restore.

1. From the Appliance section of the Administration tab, click Backup & Restore.
   The Appliance Backup page is displayed.
2. Click the Restore Backup tab.
3. Select Preserve Identity to preserve the identity and the HTTPS configuration of the current (9.0) appliance rather than take on the identity of the backed up (8.3) appliance. Clear the check box to use the identity from the backup.
4. Choose On Appliance from Backup type
5. Click Shutdown & Restore to start the restore operation.
   You are requested for confirmation.
6. When the system starts, it still has some migration tasks to complete. One of these is to re-import the version 9.0 taxonomy, after which the services must be restarted. When this is complete, the appliance is running BMC Atrium Discovery version 9.0 with your migrated data.
7. When you first log in to the appliance UI after migrating, you are presented with a details window showing the post migration task list. This may include custom patterns which require changes in order to work correctly with the new network model introduced in version 9.0. These should be reviewed in the same way as during an upgrade.
   

Post migration steps

After migration there are a number of additional steps required. As well as the notes on this page you should refer to the postmigrate_9.0_TODO.log written out by the process. This contains tailored advice of the tasks that must be completed on that particular appliance and these must be completed for correct future behavior.

Converting disabled regex/wildcard specified credentials

Regex specified credentials are disabled in the migration as they are unsuitable for use with IPv6. Here are some examples of how to convert them:

Check Windows proxy compatibility

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

Update Certificate Authority file

When upgrading to a 9.0.x version which is earlier than 9.0 SP3, you will be unable to connect to a consolidation appliance or discover using a Windows proxy unless you update the default CA certificate. If you have installed your own keys, or are upgrading to 9.0 SP3, you do not need to do this.
To update the Certificate Authority file:

1. Copy the CA certificate from the /usr/tideway/data/installed/keys directory to the /usr/tideway/etcdirectory.

   [tideway@appliance01 ~]$ cp /usr/tideway/data/installed/keys/ca_01.pem /usr/tideway/etc/ca_01.pem
   cp: overwrite `/usr/tideway/etc/ca_01.pem'? y
   [tideway@dhcp-137-72-95-238 ~]$

2. Restart the tideway service.

   [tideway@appliance01 ~]$ sudo service tideway restart

Deactivate existing TKU and activate new TKU

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

Review patterns flagged by the migration

The migration flags any pattern modules that refer to the old network model and therefore need changes to continue to work correctly. Flagged TKU patterns are addressed by activating the new TKU. However, flagged custom patterns require manual review to decide what changes are required.

The Pattern management page lists pattern modules flagged by the migration. If no modules are listed then no action is required. Any listed modules show the errors and/or warnings generated by the migration when patterns were compiled. Note that depending on the severity of the compile messages, pattern modules may be left enabled or disabled. However, all messages should be reviewed to avoid future issues with your patterns. Pattern modules and packages should be updated in the usual way for your environment; either by editing via the user interface or by uploading a new version.

Any pattern packages that you do not wish to update immediately can be deactivated and will no longer be listed. Alternatively, any pattern packages that are no longer required can be deleted.

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 a migration, the appliance configuration will have changed significantly. You should view the baseline page after an appliance migration 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 a newer version of BMC Atrium Discovery.

Export mapping sets

While migrating, 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.