Using the mmigrate utility

The mmigrate utility is used to migrate the cell KB from an earlier version to the latest version of the TrueSight Infrastructure Management. You must run the mmigrate utility to retain the customizations in the cell KB files and the mcell.conf file present in the <TrueSight Infrastructure Management Install Directory>\pw\server\etc\cellName directory. For example, if you plan to upgrade from TrueSight Infrastructure Management 10.7.00.003 to 11.3.04, and if TrueSight Infrastructure Management 10.7.00.003 cell KB contains customizations, you must run the mmigrate utility to migrate the cell KB to retain these customizations.

The following section explains how to run the mmigrate utility, and also describes the sequence that is used to merge cell KB .load files. 

To run the mmigrate utility

There are at least four cell KB files referenced when you run the mmigrate utility:

• customer KB: The cell KB in the existing TrueSight Infrastructure Management version. The mmigrate utility will migrate the cell KB from this version to the latest version.
• latest KB: It is the default KB installed with the latest version of TrueSight Infrastructure Management. 
• merged KB: This is the target or destination KB that contains the content merged from both the customer KB and the latest KB. It is the only KB directory that is modified in the migration process.
• ancestor KB: This is a precompiled KB bundled with the mmigrate utility. By default, the mmigrate utility compares every customized KB definition with the latest definition with the same name. The mmigrate utility might look at several ancestors.

The mmigrate utility performs the following operations:

1. Copies the customer KB and the latest KB to a merged KB.
2. Copies the latest standard KB directory over the merged KB skipping top-level configuration files.
3. Updates configuration files (.conf).
4. Merges the .mrl and .baroc files from the customer KB and the latest KB to the merged KB.

You can run the mmigrate before upgrade or after the upgrade.

Pre-upgrade:

Before you run mmigrate, ensure that the MCELL_HOME environment variable points to the following directory:

• (Windows) <TrueSight Infrastructure Management Download location>\MigrateKB\Server
• (Linux) <TrueSight Infrastructure Management Download location>/MigrateKB/server

Post-upgrade:

Before you run mmigrate, ensure that the MCELL_HOME environment variable points to the following directory:

• (Windows)<TrueSight Infrastructure Management Install directory>\pw\server
• (Linux)<TrueSight Infrastructure Management Install directory>/pw/server

Syntax

The syntax for mmigrate utility is as shown in the following code block:

mmigrate [-option] [type] <custom_kb_directory> <output_directory>

Where:

Example

The following example illustrates the use of various options available in the mmigrate command line utility:

mmigrate -v -ap "C:\TrueSight\pw\server\etc\custom_cell" "C:\migrated_cell_kb\custom_cell"

To merge the kb\data folder

After you run the mmigrate utility, the customer's original kb\data folder is backed up as kb\data.orig. 

Compare and merge the.load file present at data\.load in the following scenarios: 

• If you have added any new file other than the out-of-the-box files in the data folder. For example, if you have added a new file test.baroc, then the utility will copy the test.baroc file to the kb\data directory, but will not add its entry in kb\data\.load. Check and compare such changes and update the kb\data\.load file.
• If you have modified the .load file, compare and merge the content of the file kb\data.orig\.load with kb\data\.load

To compile the cell KB

After running the mmigrate utility, ensure that you run the  mccomp command to compile the cell KB.

To understand the configuration file updates

When executed, the mmigrate utility modifies the following parameter values to ensure that they meet the specified minimum constraints in the indicated configuration files under the installationDirectory\pw\server\etc folder.

• mclient.conf
  • ConnectionSetupTimeOut >= 20 seconds

  • TraceFileSize >= 5 MB

    Note

    For the TraceFileSize parameter, the value 0 (zero) indicates no limit to the size of the trace file. For example, if the value of the TraceFileSize parameter is 0, it is considered an infinite file size and thus meets the constraint of >= 5 MB.

• mcell.conf
  • EventDBCleanupDurationLimit <= 10 seconds
  • StateBuildSize >= 10 MB
  • TraceFileSize >= 5MB
• smmgr.conf
  • TraceFileSize >= 5MB
• statbld.conf
  • TraceFileSize >= 5MB

For example, if the mmigrate utility discovers that the ConnectionSetupTimeOut parameter value is less than 20 seconds, it updates the value to meet the minimum value of 20 seconds. 

When it alters a parameter value, the mmigrate utility maintains the original value as a comment prefixed with # was:. For example, if you execute the mmigrate utility with the -ap option and it alters the EventDBKeepClosed, EventDBSize, StateBuildSize, and TraceFileSize parameter values to meet the minimum constraints in the mcell.conf file, the configurations are as follows: 

 mmigrate impact on configuration files

BEFORE:
***************************************************
EventDBKeepClosed=2d
EventDBSize=100000
StateBuildSize=1000
TraceFileSize=1M

##############

CellDuplicateMode=0
ServiceModelDirectFeed=Yes
ServiceModelPublish=Yes

AFTER:
***************************************************
EventDBKeepClosed=3d # must be at least 3d
# was: EventDBKeepClosed=2d
EventDBSize=330k # must be at least 330k
# was: EventDBSize=100000
StateBuildSize=10M # must be at least 10M
# was: StateBuildSize=1000
TraceFileSize=5M # must be at least 5M
# was: TraceFileSize=1M

##############

CellDuplicateMode=0
ServiceModelDirectFeed=Yes
ServiceModelPublish=Yes
POMEnabled=Yes
ServiceModelEnabled=Yes

Impact of cell type selection on the mcell.conf configuration file variables

The table below lists the values that your mmigrate cell type selection assigns to the ServiceModelEnabled and POMEnabled variables in the mcell.conf file.

Cell type impact on mcell.conf variables

To resolve the conflicts in the mmigrate process

Conflicts identified by the mmigrate utility are marked in the following way:

<<<<<<< your source file name
your definition
=======
BMC definition
>>>>>>> BMC source file name

For example, we have three files:

• The ancestor KB has the following definition:

  MC_PUBLISH_DATA_CLASS : BMC_Application ISA BMC_ApplicationSystem
  DEFINES {
  ApplicationType : ApplicationType;
  };
  END
  

• Your KB definition (yours):

  MC_PUBLISH_DATA_CLASS : BMC_Application ISA BMC_ApplicationSystem
  DEFINES {
  ApplicationType : ApplicationType;
  ApplicationEntityName : STRING;
  };
  END
  

• My KB definition (mine):

  MC_PUBLISH_DATA_CLASS : BMC_Application ISA BMC_ApplicationSystem
  DEFINES {
  ApplicationType : ApplicationType;
  ApplicationInstanceCount : INTEGER;
  };
  END
  

The conflict will appear in the merged file as shown in the following example:

MC_PUBLISH_DATA_CLASS : BMC_Application ISA BMC_ApplicationSystem
DEFINES {
ApplicationType : ApplicationType;
<<<<<<< yours
ApplicationEntityName : STRING;
=======
ApplicationInstanceCount : INTEGER;
>>>>>>> mine
};
END

Open the file containing the conflicts, and review the conflicting definitions shown by the conflict markers. Select one of the conflicting definitions or replace it with something else. Save and close the file, and then recompile.

To merge .load files

When you upgrade TrueSight Infrastructure Management, run the mmigrate utility to migrate the data. The utility merges the content from the <customer KB> .load files and <latest KB> .load files to the <merged KB> .load files as explained in the following section: 

1. Sequence of all the customized files added in <customer KB> .load files will be retained as is in the newly created <merged KB> .load files.
2. Sequence of the newly added files in <latest KB> .load files will be retained as is in the <merged KB> .load files.
3. In case of a conflict, for example, the <customer KB>.load files and <latest KB>.load files have unique entries at same position in their respective .load files, priority will be given to newly added entry in the <latest KB> .load files.

Note: The .load files must have entries of all the <customer KB> source files that you want the mmigrate utility to merge in the new output directory.

The following table explains .load file sequencing with examples:

Related topic

Migrating the configuration of Infrastructure Management cells