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 MIGRATION_TOOL_HOME/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.

$ MIGRATION_TOOL_HOME/bin/jboss-server-migration.sh --source EAP_PREVIOUS_HOME --target EAP_NEW_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 MIGRATION_TOOL_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.

$ MIGRATION_TOOL_HOME/bin/jboss-server-migration.sh --source EAP_PREVIOUS_HOME --target EAP_NEW_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.

$ MIGRATION_TOOL_HOME/bin/jboss-server-migration.sh --source EAP_PREVIOUS_HOME --target EAP_NEW_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.

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 MIGRATION_TOOL_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 MIGRATION_TOOL_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.

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

5.3. Configuring module 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. Module 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 module 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 MIGRATION_TOOL_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.
```
$ MIGRATION_TOOL_HOME/bin/jboss-server-migration.sh --source EAP_PREVIOUS_HOME --target EAP_NEW_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:

$ MIGRATION_TOOL_HOME/bin/jboss-server-migration.sh --source EAP_PREVIOUS_HOME --target EAP_NEW_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

You can configure the following reports for the JBoss Server Migration Tool:

Task Summary log
HTML report
XML report

5.4.1. Configuring the Task Summary log

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

Table 5.1. Task Summary 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`.

5.4.2. Configuring the HTML report

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

Table 5.2. HTML report 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 `MIGRATION_TOOL_HOME/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.

Table 5.3. XML report 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 `MIGRATION_TOOL_HOME/reports/migration-report.xml`.

5.5. Configuring migration for a 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.4. Standalone server migration environment properties
Property name	Property 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_NEW_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_NEW_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_NEW_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_NEW_HOME/standalone/configuration/` directory.

Additional resources

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.5. Managed domain migration environment properties
Property name	Property 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_NEW_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_NEW_HOME/domain/configuration/` directory.
server.source.domain.domainConfigFiles	A comma-delimited list of the source server’s managed domain configurations 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_NEW_HOME/domain/configuration/` 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_NEW_HOME/domain/configuration/` directory.

Additional resources

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.

Ce contenu n'est pas disponible dans la langue sélectionnée.