Chapter 4. Reviewing the Results of JBoss Server Migration Tool Execution

4.1. Review the Migrated Configuration Files

When the migration is complete, review the migrated server configuration files in the EAP_HOME/standalone/configuration/ and EAP_HOME/domain/configuration/ directories.

  • Note that any original EAP_HOME target server configuration file names selected for migration are backed up and are now appended with .beforeMigration.
  • The EAP_HOME target server configuration file names not appended with .beforeMigration are now updated with the content migrated from the EAP_PREVIOUS_HOME source server configuration.
  • The original configuration files located in the EAP_PREVIOUS_HOME source server configuration directories remain untouched.
  • The logging.properties and standalone-load-balancer.xml files in the target configuration directories remain untouched.

If you choose to migrate all of the available configurations, you should see the following configuration files in the target server directories.

Example: List of Configuration Files on the Target Server

$ ls EAP_HOME/standalone/configuration/
application-roles.properties
application-roles.properties.beforeMigration
application-users.properties
application-users.properties.beforeMigration
logging.properties
mgmt-groups.properties
mgmt-groups.properties.beforeMigration
mgmt-users.properties
mgmt-users.properties.beforeMigration
standalone-full-ha.xml
standalone-full-ha.xml.beforeMigration
standalone-full.xml
standalone-full.xml.beforeMigration
standalone-ha.xml
standalone-ha.xml.beforeMigration
standalone-load-balancer.xml
standalone-osgi.xml
standalone-osgi.xml.beforeMigration
standalone.xml
standalone.xml.beforeMigration

$ ls EAP_HOME/domain/configuration/
application-roles.properties
application-roles.properties.beforeMigration
application-users.properties
application-users.properties.beforeMigration
domain.xml
domain.xml.beforeMigration
host-master.xml
host-master.xml.beforeMigration
host-slave.xml
host-slave.xml.beforeMigration
host.xml
host.xml.beforeMigration
logging.properties
mgmt-groups.properties
mgmt-groups.properties.beforeMigration
mgmt-users.properties
mgmt-users.properties.beforeMigration

4.2. Tracking Migration Task Execution

The JBoss Server Migration Tool begins each target server migration by executing a root task, which can then execute subtasks. Those subtasks can then also execute additional tasks and subtasks. As it executes, the tool tracks each migration task, along with any substasks, and saves the results in a tree structure that is later used to build the reports.

Each migration task is given a name, which consists of a task name concatenated with optional attributes using the following syntax.

TASK_NAME(ATTRIBUTE_1_NAME=ATTRIBUTE_1_VALUE,ATTRIBUTE_2_NAME=ATTRIBUTE_2_VALUE, ...​)

The name defines the task subject or type, and the attributes are used to distinguish between subtasks and sibling tasks. For example, all of the following are names to distinguish ejb3 subsystem update tasks.

subsystem.ejb3.update
subsystem.ejb3.update.activate-ejb3-remoting-http-connector(resource=/subsystem=ejb3)
subsystem.ejb3.update.setup-default-sfsb-passivation-disabled-cache(resource=/subsystem=ejb3)
subsystem.ejb3.update.add-infinispan-passivation-store-and-distributable-cache(resource=/subsystem=ejb3)

Since a migration task can be executed multiple times under different parent tasks, each task is stored in the tree using each of its parent task names, starting with root, separated by a > character. The task execution tree is used to build the migration reports.

A task execution can result in one of the following statuses.

StatusDescription

Success

The task executed successfully.

Skipped

The task skipped the execution, either because it was not needed or because it was configured to be skipped.

Fail

The task execution failed.

4.3. Review the Task Summary Log

The Task Summary is generated and printed to the migration console and to the JBoss Server Migration Tool log file. It provides a high-level overview of the migration results, by component and subtask, as a hierarchical list.

An example Task Summary report is located in the appendix of this guide.

See Configuring the Task Summary for options to configure the resulting output.

4.4. Review the JBoss Server Migration Tool Reports

The JBoss Server Migration Tool generates nicely formatted HTML and XML reports in the EAP_HOME/migration/reports/ directory. These reports provide a detailed analysis of the migration process and how the target server was configured during the migration. The default names for these reports are migration-report.html and migration-report.xml. Each of these names is configurable. For information about how to configure the reports, see Configuring Reporting for JBoss Server Migration Tool.

This section provides a brief overview of the content of these reports.

4.4.1. JBoss Server Migration Tool HTML Report

The HTML report consists of three sections.

Summary
This section provides the execution start time, information about the source and target servers, and the result of the migration.
Environment
This section lists the environment properties that were used for the migration.
Tasks

This section, which includes collapsible subsections, provides statistics and a map of the executed migration tasks. Each task is listed by its name and is color-coded according to the status of the completion of the task:

  • Green if it was successful.
  • Red if it failed.
  • Gray if it was skipped.

An example HTML report is located in the appendix of this guide.

See Configuring the HTML Report for options to configure the resulting output.

4.4.2. JBoss Server Migration Tool XML Report

The XML Report is a low level report that provides all of the migration data gathered by the tool. It is formatted in a way that it can be imported into and manipulated by third-party spreadsheet or other data manipulation tools.

An example XML report is located in the appendix of this guide.

See Configuring the XML Report for options to configure the resulting output.