Migrate v4 Hyperic Server and Database to v5

Topics marked with * relate to features available only in vFabric Hyperic.

About this page...
This page has instructions for upgrading the Hyperic Server and database to 5.0.

About the 5.0 Upgrade

This page has instructions for upgrading Hyperic Server 4.6.0 and later to 5.0 and migrating the Hyperic database to vPostgreSQL 9.1.3.  

Note: If you wish to upgrade a 4.2, 4.3, or 4.4 Hyperic Server and database to 5.0, you must first upgrade the Hyperic Server to 4.6.0 or later. Download locations:

The database migration supports export from Hyperic databases running on:

  • PostgreSQL 8.2.5 and 8.3

  • MySQL 5.0.x and 5.1.x

  • Oracle 10g and 11g

The Hyperic 5.0 installer contains a migration package for performing the upgrade. The migration package, hq-migrate-5.0.zip is in InstallerHome/installer/bin. It contains a migration script, hq-migrate/bin/hq-migrate.sh (or .bat). 

By default, the migration utility exports your monitoring configuration (alert definitions, resource groups, escalation schemes, and so on) and metric data. If desired, you can run the script with an option that causes only the monitoring configuration data to be exported.

Prerequisites

You run the migration utility on both the vFabric Hyperic 4.6 (or later) host and the vFabric 5.0 host. Each system must have:

  • 64-bit Java 1.6 JRE

  • 6 to 7 GB of free disk space

    • The migration process creates a directory structure on the 4.x host for the exported data, and archives the directory tree. The target host also requires the free disk space, as you will copy the export archive to that platform and unpack it there.

  • For large deployments, 8GB of RAM.

Upgrade Process Alternatives

The migration process consists of exporting data from your existing Hyperic deployment and importing it into your 5.0 installation. You can perform the import and export as two separate steps as described below in Two-Step Migration Procedure, or in some environments, as a single step, as described in One-Step-Migration.

Regardless of whether you perform the migration in one step or two, you can supply command arguments at the command line, or in a properties file. The Two-Step Migration Procedure and One-Step-Migration procedures have instructions for supplying arguments at the command line. For information about defining the arguments in a properties file, see Specify Migration Options in a Properties File.

Before performing the migration procedure, review Migration Defaults and Options below, which describes migration behavior, required and optional command options, and default settings.

Two-Step Migration Procedure

Note: In this procedure "two-step" refers the fact that export and import processes are separate steps.

The two-step upgrade process consists of these steps:

  1. Install Hyperic 5.0 and vPostgreSQL

  2. Export Data from Hyperic 4.x

  3. Import Data to Hyperic 5.0

Step 1: Install vFabric Hyperic 5.0 Server and vPostgreSQL

In this step, you install the Hyperic 5.0 Server and database. As noted above in Account Permission Requirements, install the Hyperic Server under the same account that you will run the import process.

If you plan to run the components in VMs, follow the instructions on Install Hyperic vApp.

Otherwise, following the instructions on Set Up Hyperic Database and then run the Hyperic installer in -full mode, following the instructions on Run Hyperic Installer.

Configure Sizing Profile at Server Installation

When you run the Hyperic installer in -full mode, you are prompted to select a sizing profile. (Sizing profiles are described in About Sizing Profiles in vFabric Hyperic. For large scale environments, be sure to select "large" at the time you install the Hyperic Server.

After installing the database and Hyperic Server, proceed to Step 2.

Step 2: Export Existing Database and Server Configuration

  1. Shut down the 4.6 (or later) Hyperic Server

    • Note that if the server is running when you execute the migration script, the migration process will will stop the Hyperic Server.

  2. Copy the migration package, hq-migration-5.0.zip from the Hyperic 5.0 installer to the 4.x Hyperic Server host.

    • The package is located in the installer/bin directory of the 5.0 installer home directory.

  3. On the Hyperic 4.x host, unpack hq-migration-5.0.zip.

    • The expanded package has this directory structure:

      hq-migration-5.0
           logs
           lib
           data
           bin

      The root of the unpacked migration package directory structure, hq-migration-5.0 in the directory tree above, is referred to henceforth as MigrationHome.

  4. To export all configuration and metric data, run the following command in a command shell:

    ./hq-migrate.sh hq-export -Dhqserver.install.path=PathToServerHome
    • where PathToServerHome is the full path to the Hyperic Server installation directory, or the path relative to MigrationHome.

    • if you want to export configuration data only, not metric data, add -DconfigOnly=true to the command line.

    • The script reads your pre-5.0 Hyperic Server's hq-server.conf file, connects to your existing Hyperic database, exports the database, and creates a tarball with key artifacts and the database dump, in hq-migration-export-HqVersion.tgz.

      • The archive is written to the import staging directory, migration_home/tmp/export-data by default, or the value of staging.dir if specified.

      • Export log files install.log and install.log.verbose are written to the logs directory.

One-Step Migration Procedure

Note: In this procedure "one-step" refers the fact that export and import processes a single step.

Define JAVA_HOME

Before running the one-step migration procedure, set the JAVA_HOME environment variable to point to the JRE that the target (5.0) Hyperic Server runs in.

In the process described in Migration Procedure above, you run the migration in two steps — first you export data from your previous Hyperic Server installation, then you import that data into your Hypric 5.0 environment.

If both the source and destination directories and databases are accessible from a single machine, either because they physically reside there, or are mounted on your file system, you can perform a one-step-migration, in which you initiate export and import with a single command.

As noted above in Account Permission Requirements execute the migration process under the same user account used to install the Hyperic 5.0 Server. Note also the database user requirements described in Step 3: Import Server Configuration and Database.

After performimg Step 1: Install vFabric Hyperic 5.0 Server and vPostgreSQL you can run a one-step-migration, supplying arguments at the command line, with a command in this form:

./hq-migrate.sh -Dsource.hqserver.install.path=SourceServerHome
-Dtarget.hqserver.install.path=TargetServerHome

Note: Enter the command on a single line.

Migration Defaults and Options

The tables in the section summarize migration options and arguments.

Note: For help at the command line, enter:

./hq-migrate.sh usage

Summary of Required and Optional Command Arguments

This table documents lists the required and optional arguments for each hq-migrate.sh (or .bat) command. (See the table in the following section for argument definitions and defaults.)

Command

Required

Optional

hq-export

hqserver.install.path
staging.dir

configOnly
setup.file
scale

hq-import

export.archive.path
hqserver.install.path

staging.dir
setup.file
target.database.user
target.database.password
quiet

one-step-migration

source.hqserver.install.path
target.hqserver.install.path
staging.dir

setup.file

usage

none

none

Command Argument Definitions

This table defines the arguments supported by hq-migrate.sh (or .bat) commands.

Argument

Description

Default Behavior

configOnly

This optional argument can be used with both hq-export and hq-import.

When used with hq-export, {configOnly}} causes export of monitoring configuration settings (resource groups, alert definitions, escalations, and in vFabric Hyperic, roles) only.

When used with hq-import, configOnly causes only monitoring configuration settings to be imported, even if the export archive includes metric data.

Both metrics and configuration setting are exported.

export.archive.path

This required hq-import argument points to the archive that contains the data exported from your Hyperic 4.x installation.

Specify the full path to the archive, or the path relative to MigrationHome.

On Windows platforms, either use Unix-style path separators or escape Windows-style path separators, as shown in the examples in Key Tips above.

 

hqserver.install.path

This required hq-export and hq-import argument points to the Hyperic Server that is the target of the export or import operation.

Specify the full path to the Hyperic Server installation directory, or the path relative to MigrationHome.

On Windows platforms, either use Unix-style path separators or escape Windows-style path separators, as shown in the examples in Key Tips above.

 

quiet

This optional argument applies to the hq-import command only.

It causes the import process to run without pauses.

If not specified, there is a pause after each major task in the process is completed.

scale

This optional hq-export argument indicates that the scale of the Hyperic environment environment is "large", causing the Hyperic Server and database to be configured accordingly. Note that use of this argument requires that the Hyperic 5.0 is configured with the "large" sizing profile.

For more information about sizing profiles, see About Sizing Profiles in vFabric Hyperic.

 

setup.file

This optional argument is supported by all three migration commands. If you choose to configure the migration process in a properties file, instead of at the command line, use this property to specify the file location.

If you do not use a properties file you must supply command options at the command line.
Command arguments specified at the command line must be prefixed with -D.

source.hqserver.install.path

This required one-step-migration command argument points to the 4.x Hyperic Server installation directory.

On Windows platforms, either use Unix-style path separators or escape Windows-style path separators, as shown in the examples in Key Tips above.

none

staging.dir

This optional hq-export and hq-import argument specifies the directory that the migration utility will use as a working directory for manipulating export and import data.

The directory name may include the string export-data; if it does not, the export procedure will append the string to the name you specify. If the path specified does not exist at the time of export, it will be created.

On Windows platforms, either use Unix-style path separators or escape Windows-style path separators, as shown in the examples in Key Tips above.

By default the staging directory is migration_home/tmp/export-data.

target.hqserver.install.path

This required one-step-migration command argument points to the 5.0 Hyperic Server installation directory.

On Windows platforms, either use Unix-style path separators or escape Windows-style path separators, as shown in the examples in Key Tips above.

 

target.database.password

This hq-import command option is required if the database user in hq-server.conf is not a super user.

The import will fail if is the user account running it is not defined as a superuser.

By default, the database password defined in hq-server.conf is used.

target.database.user

This hq-import command option is required if the database user in hq-server.conf is not a super user.

By default, the database user defined in hq-server.conf is used.

Optional Migration Execution Parameters

It is possible to configure certain export execution parameters in the migrate.xml file, in the /data directory in the root of the migration utility directory tree. The export execution parameters are defined in the table below.

Parameter

Description

Default

queryTimeoutSecs

How long before a query times out

2,000 seconds

no.exporter.batchSize

Controls how many rows are exported per batch.

Depends on whether or not the scale argument is specified:

  • if scale=true not specified, batch size is 5,000.

  • if scale=true is specified, batch size is 10,000.

no.exporter.Workers

Number of export threads

Depends on whether or not the scale argument is specified:

  • if scale=true not specified, 5

  • if scale=true is specified, batch size is 12.

no.importer.batchSize

Controls how many rows are imported per batch.

Depends on whether or not the scale argument is specified:

  • if scale=true not specified, batch size is 5,000.

  • if scale=true is specified, batch size is 10,000.

no.importer.Workers

Number of import threads

Depends on whether or not the scale argument is specified:

  • if scale=true not specified, 5

  • if scale=true is specified, batch size is 12.

disabled

For troubleshooting.

 

noOfPartitions

The export process partitions some data tables so that instead of a single thread exporting all records serially, multiple threads export different chunks of a table in parallel. This behavior is configured for selected tables in migrate.xml with the noOfPartitions parameter.

See migrate.xml for default values.

Export Process Artifacts

Exported Data Files

The export process creates a subdirectory in the staging directory (MigrationHome/export-data by default) for each table that it exports. The export process populates this directory, which has the same name as the table — for example EAM_PLATFORM — with files that contain the data from the table. The export data for a table is is split among files based on the value of the batchsize parameter in hq-migrate.xml (1,000 by default), and for big tables, the value of the noOfPartitions parameter for the table (10, by default), also in hq-migrate.xml.

Hence, the export files for a table for which partitioning is not configured will contain a 1,000 rows of data (except for the final file in the set).

The export files for a table for which partitioning is configured, will contain data from a single partition of 1,000 rows. The naming convention for the export files is:

TABLE_NAME_BATCH_NO._PARTITION_NO.out

where:

  • BATCH_NO indicates the batch sequence number. For the first export file written for a table, BATCH_NO is "0", for the next file, BATCH_NO is "1".

  • PARTITION_NO is the partition sequence number.

    • Given a file for which partitioning is configured, PARTITION_NO is 0 for the first partition, "1", for the next. For example, EAM_MEASUREMENT_DATA_1D_0._0.out, EAM_MEASUREMENT_DATA_1D_0._1.out and so on.

    • Given a file for which partitioning is not configured, PARTITION_NO is always 0. For example, EAM_PLATFORM_0_0, EAM_PLATFORM_1_0.out, EAM_PLATFORM_2_0.out, and so on.

Export Metadata

In addition to the data files, the export process creates file for each table it exports, named TableName.metadata, where TableName is the name of the table, for example EAM_PLATFORM.metadata. The file is written to the directory that contains the export data files for that table, for example MigrationHome/export-data/EAM_PLATFORM.metadata. The metadata file contain the total number of exported records and the column order in which the data was exported; the file is not compressed and is and is human-readable.

Log Files

The export process directs its output to three targets:

  • console — By default, the trace level is info. You can alter the level by specifying one of these commandline arguments: -verbose or debug.

    • On Unix-like platforms, that output is colorized.

  • hq-install.log — this file contains the same information that is output to the console, and its trace level is controlled by the same arguments.

  • hq-install.log.verbose — Provides debug level tracing.