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 11.3.04 to 11.3.07, and if TrueSight Infrastructure Management 11.3.04 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
• To merge the kb\data folder
• To compile the cell KB
• To understand the configuration file updates
• To resolve the conflicts in the mmigrate process
• To merge .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 bundled 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 must run the mmigrate before upgrade.

Pre-upgrade:

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

• 
  
  • (Windows) <TrueSight Infrastructure Management downloaded build location>\MigrateKB\server
  • (Linux) <TrueSight Infrastructure Management downloaded build location>/MigrateKB/server

After setting MCELL_HOME variable, run the mmigrate utility in the same command window from the following location:

• 
  
  • (Windows) <TrueSight Infrastructure Management downloaded build location>\MigrateKB\server\bin
  • (Linux) <TrueSight Infrastructure Management downloaded build location>/MigrateKB/server/bin
    
    

Post-upgrade:

You can run mmigrate post upgradation only for custom cells ( manually created using mcrtcell CLI option).

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

• 
  
  • (Windows) <TrueSight Infrastructure Management downloaded build location>\MigrateKB\server
  • (Linux) <TrueSight Infrastructure Management downloaded build location>/MigrateKB/server

After setting MCELL_HOME variable, run the mmigrate utility in the same command window from the following location:

• 
  
  • (Windows) <TrueSight Infrastructure Management downloaded build location>\MigrateKB\server\bin
  • (Linux) <TrueSight Infrastructure Management downloaded build location>/MigrateKB/server/bin

Syntax

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

Where:

Example

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

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

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.

To resolve the conflicts in the mmigrate process

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

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:

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