Chapter 5. Configuring the JBoss Server Migration Tool

5.1. Configuring the JBoss Server Migration Tool Properties

You use properties to configure the JBoss Server Migration Tool logging and reporting output and to determine which components and configurations you want to migrate. You can configure these properties using a combination of the following methods.

5.1.1. Configure the JBoss Server Migration Tool Using the Tool Properties

You can configure the JBoss Server Migration Tool using the environment.properties file located in the EAP_HOME/migration/configuration/ directory. This standard Java properties file provides the default values for all of the valid properties that can be configured when migrating to the target server. To change a default value, remove the # comment character that precedes the property and set it to the value you need.

5.1.2. Configure the JBoss Server Migration Tool Using User Properties

If you prefer, you can create a standard Java properties file that defines JBoss Server Migration Tool configuration properties and pass its path on the command line using the --environment or -e argument. This path can be an absolute path or a path relative to the current directory. 

$ EAP_HOME/bin/jboss-server-migration.sh --source EAP_PREVIOUS_HOME --environment path/to/my-server-migration.properties

Properties defined in files passed on the command line using the --environment or -e argument override the ones defined in the EAP_HOME/migration/configuration/environment.properties file.

5.1.3. Configure the JBoss Server Migration Tool Using System Properties

You can configure the JBoss Server Migration Tool by passing system properties on the command line using the following syntax. 

$ EAP_HOME/bin/jboss-server-migration.sh --source EAP_PREVIOUS_HOME -Djboss.server.migration.PROPERTY_NAME=PROPERTY_VALUE

The system property name should be specified as jboss.server.migration. concatenated with the environment property name. The following example demonstrates how to specify the name of the XML report as migration-report.xml when starting the JBoss Server Migration Tool. 

$ EAP_HOME/bin/jboss-server-migration.sh --source EAP_PREVIOUS_HOME  -Djboss.server.migration.report.xml.fileName=migration-report.xml

Environment properties specified on the command line override both user configuration properties and tool configuration properties.

Warning

Configuring the JBoss Server Migration Tool by passing system properties on the command line does not currently work for the following properties.

  • report.html.fileName
  • report.html.maxTaskPathSizeToDisplaySubtasks
  • report.html.templateFileName
  • report.summary.maxTaskPathSizeToDisplaySubtasks
  • report.xml.fileName

This is a known issue that should be addressed in the next version of JBoss EAP. For more information about this issue, see JBEAP-12901.

5.2. Configuring Logging for JBoss Server Migration Tool

The JBoss Server Migration Tool uses the JBoss Logging framework to log the progress of the migration. Results are written to the console and also to a file named migration.log, which is located in the EAP_HOME/migration/logs/ directory. This log file is created if it does not already exist, and its content is overwritten on each subsequent execution of the tool.

The logging configuration is provided by the EAP_HOME/migration/logging.properties file. You can modify this configuration file or you can specify an alternative logging configuration file by using the logging.configuration system property on the command line. 

$ EAP_HOME/bin/jboss-server-migration.sh --source EAP_PREVIOUS_HOME -Dlogging.configuration=file:EAP_PREVIOUS_HOME/migration/configuration/my-alternate-logging.properties

5.3. Configuring Modules Migration

The JBoss Server Migration Tool can migrate any module installed in the source server as long as that module is not already installed on the target server. Module migration can be done explicitly by request, or implicitly because another module or migrated server configuration depends on it.

5.3.1. Modules Environment Properties

You can control whether a module should be migrated or not by using the modules.includes and modules.excludes environment properties. The syntax for a module ID is name:slot. The :slot is optional and if it is not specified defaults to main.

  • A module whose ID is referenced by the modules.excludes environment property is never migrated.
  • A module whose ID is referenced by the modules.includes environment property is always migrated, unless it is referenced by the modules.excludes environment property.

5.3.2. Configuring Modules Properties

The environment properties used to migrate modules can be configured in any of the following ways:

  • You can configure the properties in the tool’s EAP_HOME/migration/configuration/environment.properties file. 

    modules.includes=com.example.moduleA,com.example.moduleB
modules.excludes=com.example.moduleC

  • You can include the above properties in your own custom properties file, and then pass the properties file name on the command line using the --environment argument. 

    $ EAP_HOME/bin/jboss-server-migration.sh --source EAP_PREVIOUS_HOME --environment PATH_TO_MY_PROPERTIES_FILE

  • You can pass the information on the command line using a system property. The environment property names must be prefixed with jboss.server.migration., for example: 

    $ EAP_HOME/bin/jboss-server-migration.sh --source EAP_PREVIOUS_HOME -Djboss.server.migration.modules.includes="com.example.moduleA" -Djboss.server.migration.modules.excludes="com.example.moduleC,com.example.moduleD"
Warning

The JBoss Server Migration Tool does not verify that the source module is compatible with the target server. An incompatible migrated module can cause the target server to malfunction or not work at all. A module can be incompatible due to a dependency on a module that is installed on both the source and target servers, but includes or exposes different resources on each one.

5.4. Configuring Reporting for JBoss Server Migration Tool

5.4.1. Configuring the Task Summary Log

You can customize the generation of the Task Summary using the following environment property.

Property NameTypeProperty Description and Default Value

report.summary.maxTaskPathSizeToDisplaySubtasks

Integer

Include migrated subtasks in the summary where the level is less than or equal to the specified integer.

Defaults to 5.

5.4.2. Configuring the HTML Report

You can customize the HTML report using the following environment properties.

Property NameTypeProperty Description and Default Value

report.html.fileName

String

The name of the HTML report file. If not set, the report is not generated.

Defaults to EAP_HOME/migration/reports/migration-report.html.

report.html.maxTaskPathSizeToDisplaySubtasks

Integer

Include migrated subtasks in the summary where the level is less than or equal to the specified integer.

Defaults to 4.

report.html.templateFileName

String

The HTML report template file name.

Defaults to migration-report-template.html.

5.4.3. Configuring the XML Report

You can customize the XML report using the following environment properties.

Property NameTypeProperty Description and Default Value

report.xml.fileName

String

The name of the XML report file. If not set, the report is not generated.

Defaults to EAP_HOME/migration/reports/migration-report.xml.

5.5. Configuring the Migration of the Standalone Server Configuration

You can configure the JBoss Server Migration Tool to skip the migration of a standalone server entirely, to provide the configuration file names that you want to migrate, or to provide alternate paths for the source or target server’s base and configuration directories.

You can customize the migration of the standalone server configuration using the following environment properties.

Table 5.1. Standalone Server Migration Environment Properties

Property NameProperty Description

standalone.skip

If set to true, the tool skips the entire standalone server migration.

server.source.standalone.serverDir

Defines an alternative path for the source server’s standalone directory, which defaults to the source server’s EAP_HOME/standalone/ directory.

server.source.standalone.configDir

Defines an alternative path for the source server’s standalone configuration directory, which defaults to the source server’s EAP_HOME/standalone/configuration/ directory.

server.source.standalone.configFiles

A comma-delimited list of the source server’s standalone configurations to be migrated.

server.target.standalone.serverDir

Defines an alternative path for the target server’s standalone directory, which defaults to the target server’s EAP_HOME/standalone/ directory.

server.target.standalone.configDir

Defines an alternative path for the target server’s standalone configuration directory, which defaults to the target server’s EAP_HOME/standalone/configuration/ directory.

For information about how to configure the JBoss Server Migration Tool using these properties, see Configuring the JBoss Server Migration Tool.

5.6. Configuring the Migration of a Managed Domain Configuration

You can configure the JBoss Server Migration Tool to skip the migration of a managed domain entirely, to provide the configuration file names that you want to migrate, or to provide alternate paths for the source or target server’s base and configuration directories.

You can customize the migration of the managed domain configuration using the following environment properties.

Table 5.2. Managed Domain Migration Environment Properties

Property NameProperty Description

domain.skip

If set to true, the tool skips the entire managed domain migration.

server.source.domain.domainDir

Defines an alternative path for the source server’s managed domain directory, which defaults to the source server’s EAP_HOME/domain/ directory.

server.source.domain.configDir

Defines an alternative path for the source server’s managed domain configuration directory, which defaults to the source server’s EAP_HOME/domain/configuration/ directory.

server.source.domain.domainConfigFiles

A comma-delimited list of the source server’s managed domain configuration files that are to be migrated.

server.source.domain.hostConfigFiles

A comma-delimited list of the source server’s host configuration files that are to be migrated.

server.target.domain.domainDir

Defines an alternative path for the target server’s managed domain directory, which defaults to the target server’s EAP_HOME/domain/ directory.

server.target.domain.configDir

Defines an alternative path for the target server’s managed domain configuration directory, which defaults to the target server’s EAP_HOME/domain/configuration/ directory.

For information about how to configure the JBoss Server Migration Tool using these properties, see Configuring the JBoss Server Migration Tool.

5.7. Configure the Migration Tasks Performed by the JBoss Server Migration Tool

By default, the JBoss Server Migration Tool automatically migrates all components and subsystems for each standalone server, managed domain, and host configuration you choose to migrate. You can customize the execution of specific tasks and subtasks performed by the tool using environment properties. For example, you can configure the tool to skip the removal of unsupported subsystems or to skip the migration of deployments. The tasks performed by the tool are dependent upon the type of server configuration and the version of the source server from which you are migrating.

Information about how to configure environment properties to customize the tasks performed by the JBoss Server Migration Tool can be found in the following sections.