Page tree
Skip to end of metadata
Go to start of metadata

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.
    Shows the link to the migration script on the BMC Atrium Discovery Backup and restore page.
  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
    --2012-08-20 10:22:46--
    Resolving 90appliance...
    Connecting to||:80... connected.
    HTTP request sent, awaiting response... 200 OK
    Length: 27650 (27K) [application/x-gzip]
    Saving to: `'
    100%[======================================>] 27,650      --.-K/s   in 0s
    2012-08-20 10:22:46 (429 MB/s) - `' saved [27650/27650]
    [tideway@83appliance ~]$
  3. Extract the migration script from the downloaded archive. Enter:

    [tideway@83appliance ~]$ gunzip
    [tideway@83appliance ~]$ 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.

For large 8.3.x appliance datastores, the backup verification stage of the migration might take rather long. If you would like to complete the migration faster, consider using --no-verification option for the tw_addm_8_3_migration command. In this case, verification stage is omitted, however you can later, at a more convenient time, verify the backup manually using the tw_restore utility. Before you start manual verification, make sure that the original 8.3.x appliance is healthy and accessible.
Use the following command for manual backup verification:

$TIDEWAY/bin/tw_restore --verify-only --backup-ssh
    --remote-user=tideway --remote-password=password
    --username system
  1. Change to the root user the su command. Enter:

    [tideway@83appliance ~]$ su
    [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 --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= --share=tideway --backup-dir=tmp
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
     --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.

Command Line Option



Backup directory (required for remote backups)


Create a backup stored locally on appliance. The backup is written to the $TIDEWAY/var/backup directory. No other configuration is required. Only one local backup can be stored.


Create a backup stored on a Windows share.


Create a backup stored on a ssh enabled remote system.


Exclude vault from the backup.

-H, --host=HOST

The hostname or IP address of the remote server onto which to write the backup (SSH).


Do not verify the backup after it is created.


Notes about the backup action.


Overwrite an existing backup (Local only).


Passphrase to open the vault.

-P, --port=PORT

The port to which to connect (SSH).


The corresponding password (SSH and Windows share).


The username to use to connect to the remote server (SSH and Windows share). Windows domain usernames (mydomain/myusername) must be enclosed in double quotes (").

-S, --share=SHARE

Remote Windows share.


The host, share, and directory name into which to write the backup on a Windows share. Backups are written into a subdirectory called YYYY-MM-DD_hhmmss_addm_backup inside the specified directory. Path syntax is \\hostname\sharename\directoryname, where hostname is the name of the Windows host, sharename is the name of the Windows share, and directoryname is the name of the directory into which to write the backup. UNC paths must be enclosed in single quotes (').

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.

Restoring data may take a long time

Restoring migrated data takes longer than restoring backed up data as the model must be migrated and the datastore re-indexed.

  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.
    Shows the post migration task list on the details window.

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:

Old format

New format


137.72.94.*, 137.72.95.*

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.


Ensure that you deactivate the version 8.3 TKUs rather than deleting them. Deletion of the TKUs results in deletion of the associated nodes.

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.
  • No labels


  1. --no-verification

    Do not verify the backup after it is created.

    I'm wondering if this option saves you time when you what you want is just push the data and avoid the:

    Verify addm_datastore_data (Task: 34/34): Processed: 82%

    Is this what the --no-verification switch does?

    1. Hi Eulise,

      Saving time is the idea behind the option. However, you do risk not discovering a corrupted backup that won't restore. The time saved in that case would probably seem insignificant.

      I spoke to the developer who wrote this code and he says that you could possibly reduce the total time taken by up to 25%, but it depends on the system, the data, and the network.

      I hope this helps.


  2. Many SAs and scripters are more familiar with "curl -O" than the inferior "wget" (both are available on appliances).  Better in every respect (other than recursive fetches, which is inapplicable here).  Ref.