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.
- You can configure the properties file defined within the tool.
- You can pass user properties on the command line.
- You can configure system environment variables.
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.
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.excludesenvironment property is never migrated. -
A module whose ID is referenced by the
modules.includesenvironment property is always migrated, unless it is referenced by themodules.excludesenvironment 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.propertiesfile.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
--environmentargument.$ 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"
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 Name | Type | Property 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.4.2. Configuring the HTML Report
You can customize the HTML report using the following environment properties.
| Property Name | Type | Property 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 |
| report.html.maxTaskPathSizeToDisplaySubtasks | Integer | Include migrated subtasks in the summary where the level is less than or equal to the specified integer.
Defaults to |
| report.html.templateFileName | String | The HTML report template file name.
Defaults to |
5.4.3. Configuring the XML Report
You can customize the XML report using the following environment properties.
| Property Name | Type | Property 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 |
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.
| Property Name | Property Description |
|---|---|
| standalone.skip |
If set to |
| server.source.standalone.serverDir |
Defines an alternative path for the source server’s standalone directory, which defaults to the source server’s |
| server.source.standalone.configDir |
Defines an alternative path for the source server’s standalone configuration directory, which defaults to the source server’s |
| 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 |
| server.target.standalone.configDir |
Defines an alternative path for the target server’s standalone configuration directory, which defaults to the target server’s |
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.
| Property Name | Property Description |
|---|---|
| domain.skip |
If set to |
| server.source.domain.domainDir |
Defines an alternative path for the source server’s managed domain directory, which defaults to the source server’s |
| server.source.domain.configDir |
Defines an alternative path for the source server’s managed domain configuration directory, which defaults to the source server’s |
| 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 |
| server.target.domain.configDir |
Defines an alternative path for the target server’s managed domain configuration directory, which defaults to the target server’s |
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.
