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

Commands:
MIGRATION_TOOL_HOME/bin/jboss-server-migration.sh --source EAP_PREVIOUS_HOME --target EAP_NEW_HOME --environment path/to/my-server-migration.properties
MIGRATION_TOOL_HOME/bin/jboss-server-migration.sh --source EAP_PREVIOUS_HOME --target EAP_NEW_HOME -Djboss.server.migration. PROPERTY_NAME = PROPERTY_VALUE
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
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
modules.includes=com.example.moduleA,com.example.moduleB modules.excludes=com.example.moduleC
MIGRATION_TOOL_HOME/bin/jboss-server-migration.sh --source EAP_PREVIOUS_HOME --target EAP_NEW_HOME --environment PATH_TO_MY_PROPERTIES_FILE
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"