Using the mmigrate utility

You can migrate your KB by using the mmigrate utility.

This section shows how to launch the mmigrate utility manually.

About the mmigrate utility

The mmigrate utility is a BMC component that automatically migrates older KBs to the latest, standard KB formats in the current release. It is launched from a computer that has the latest version of the Integration Service. 

The mmigrate utility performs the following operations:

1. Copies the customer cell into the target cell's KB, which becomes the new KB.
2. Copies the latest standard KB or reference directory over the new KB, skipping top-level configuration files.
3. Updates configuration files (.conf) as described below.
4. Merges the .mrl and .baroc files from the old KB and the new default KB to the new target KB. 

You can execute the mmigrate utility to migrate configuration and KB data from earlier versions to the latest versions of TrueSight Infrastructure Management.

The mmigrate utility is located in the <installation directory>\Windows or Linux\MigrateKB\server\bin directory. 

How mmigrate works

There are at least four KBs involved in running the mmigrate utility:

• The new KB, which is the target or destination KB, and it is the result of the migration. It is the only KB that is altered.
• The existing KB, which the mmigrate utility is trying to migrate
• The reference KB, which we are merging. It is the new default KB installed with TrueSight Infrastructure Management.
• The ancestor KBs, which are precompiled and are within mmigrate  itself. They are the common ancestors to both the customer KB and the reference KB. The mmigrate utility will by default compare every existing, potentially customized KB definition with every released definition of the same name, so the mmigrate utility might look at several ancestors.

Usage options

When running the mmigrate command, determine the type of cell you are creating, the old cell directory, and the new cell directory that contains the result of the migration. 

The syntax of the mmigrate command is as follows:

mmigrate [-option] [type] custom_kb_directory output_directory

where,

• custom_kb_directory is the existing KB directory under the \etc directory, which will be copied to the Integration Service computer.

• output_directory is the directory to which the KB is migrated. You must provide this parameter. 

• type indicates the type of cell you are creating. The type of cell determines how the ServiceModelEnabled and POMEnabled variables are set in the mcell.conf file. You must provide this parameter. The supported types are as follows:
  
  • -aa administrative (Admin)
  • -ae BMC Event Manager (BEM)
  • -as Service Impact Manager (SIM)

  • -ap embedded PNET (PPM) 

    Notes

    • If your existing KB is of 8.6.xx or 9.0.xx version, the type is embedded cell (PPM).
    • If you specify the -aa cell type, you merge with the Admin cell, the KB of which resides at installationDirectory\pw\server\etc\admin. For all other types, you find the KB you are merging with at installationDirectory\pw\server\etc\default\standard.
• The optional arguments for the mmigrate command are listed as follows:
  • -h displays the online help for the command.

  • -v sets the verbosity level of the mmigrate messages. In the order of severity, the options are VERBOSE, INFORM, WARNING, ERROR, and FATAL.

    • -v option without a following descriptor sets the trace level to VERBOSE

    • INFORM is the default level, which does not require the -v option.

    • -v WARNING

    • -v ERROR

    • -v FATAL

    The specified level and the next higher severity levels are printed. For example, if you specify -v WARNING, then WARNING, ERROR, and FATAL messages are printed. FATAL messages are never filtered.

  • -z prints the version number of the command and exits.

After running mmigrate

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

Impact of cell type selection on mcell.conf 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

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
  • EventDBKeepClosed >= 3d
  • EventDBSize >= 330k
  • ServerHostName >= Name of host system
  • 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 stanzas look as follows: 

 Before/after comparison: 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

Requirements for .load files

The .load files must reference all the customized KB source files that you want the mmigrate utility to merge in the new output directory.

After the mmigrate utility is run, it merges the contents of both the customer load lists and reference load lists in generated .load files, in the following order:

1. Standard files are placed in the order as in the reference KB
2. Customer files are placed in the order as in the customer .load file

 Resolving 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 merge as follows:

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.

Related topic

Migrating the configuration of Infrastructure Management cells