Migrating from WildFly 10.0 to Wildfly 10.1 - JBoss Server Migration Tool

Migrating from WildFly 10.0 to Wildfly 10.1

Overview

This document describes how to use the JBoss Server Migration Tool to migrate from WildFly 10.0 to Wildfly 10.1.

~/jboss-server-migration $ ./server-migration.sh --source ../wildfly-10.0 --target ../wildfly-10.1

----------------------------------------------------------
----  JBoss Server Migration Tool  -----------------------
----------------------------------------------------------

Retrieving servers...
20:40:31,067 INFO  [org.jboss.migration.core.logger] (main) SOURCE server name: WildFly, version: 10.0.0.Final.
20:40:31,079 INFO  [org.jboss.migration.core.logger] (main) TARGET server name: Wildfly, version: 10.1.0.Final.

Server migration starting...

The server migration consists of:

Modules Migration

The JBoss Server Migration tool is capable of migrating any Module installed in the source server, as long as such Module is not already installed on the target server.

The migration of a Module may be done explicitly, by user demand, or implicitly, cause another module, or server configuration migrated, depends on it.

The user who has fine control over which modules should be migrated or not, through the environment properties named modules.includes and modules.excludes:

a module which id is referenced by environment property modules.excludes will never be migrated
a module which id is referenced by environment property modules.includes will always be migrated, unless referenced by environment property modules.excludes
The syntax for a module's id is name:slot, yet the module's slot is optional, and if not specified defaults to main.

The configuration of the Modules Migration's environment properties which may be done in one of the following ways:

You may configure the properties in the tool's config/environment.properties file:

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

You can include the above property in your own custom properties file and pass the file on the command line using the --environment argument.
You can pass the information on the command line using a system property, in such case the environment property names should be prefixed with jboss.server.migration.:
```
-Djboss.server.migration.modules.includes="com.example.moduleA" -Djboss.server.migration.modules.excludes="com.example.moduleC,com.example.moduleD"
```

Please be warned that the tool, when migrating a module, does not asserts if the source's module is compatible with the target server, and it's possible that a migrated incompatible module may result in the target server malfunctioning, or not working at all. A module may be incompatible, for instance, due to a dependency on a module that both servers have installed, yet includes/exposes different resources.

Standalone Server Migration

The standalone server migration consists in migrating the source's standalone server content and configuration files, to the target server. This migration task is optional, and in case the tool is running in interactive mode a prompt will first ask to confirm its execution:

Migrate the source's standalone server?
yes/no?

If you say yes, or simply y, the standalone server migration will proceed.

If you say no, or simply n, the standalone server migration will be skipped.
In case the standalone server migration proceeds, the tool will start by migrating the source standalone server's content, a cyphered repository used to store data such as deployments and deployment overlays, referenced by standalone server configurations. Both servers use a similar content repository, thus the migration of such data merely consists of finding, and copying such content among servers.

03:25:28,264 INFO  [org.jboss.migration.core.task.ServerMigrationTask#5] (main) Migrating standalone content found: [22/caa450a9ba3b84eaf5a15b6da418b92ce6c98e/content, 23/b62a37ba8a4830622bfcdb960280577cc6796e/content, 40/8bcb8a4480739d370ebf70fbcabb33c1508c50/content, 88/96c992d1b9866945a5015b72f8d254d3d5c132/content, ea/69fbffdf08b320c09ad1acc7d31deba5a7787b/content, fc/8ec517e0b169fb27b61ff90f04de5dd8ca8d52/content]
03:25:28,266 INFO  [org.jboss.migration.core.task.ServerMigrationTask#6] (main) Resource with path /wildfly-10.0/standalone/data/content/22/caa450a9ba3b84eaf5a15b6da418b92ce6c98e/content migrated.
03:25:28,267 INFO  [org.jboss.migration.core.task.ServerMigrationTask#7] (main) Resource with path /wildfly-10.0/standalone/data/content/23/b62a37ba8a4830622bfcdb960280577cc6796e/content migrated.
03:25:28,268 INFO  [org.jboss.migration.core.task.ServerMigrationTask#8] (main) Resource with path /wildfly-10.0/standalone/data/content/40/8bcb8a4480739d370ebf70fbcabb33c1508c50/content migrated.
03:25:28,269 INFO  [org.jboss.migration.core.task.ServerMigrationTask#9] (main) Resource with path /wildfly-10.0/standalone/data/content/88/96c992d1b9866945a5015b72f8d254d3d5c132/content migrated.
03:25:28,270 INFO  [org.jboss.migration.core.task.ServerMigrationTask#10] (main) Resource with path /wildfly-10.0/standalone/data/content/ea/69fbffdf08b320c09ad1acc7d31deba5a7787b/content migrated.
03:25:28,271 INFO  [org.jboss.migration.core.task.ServerMigrationTask#11] (main) Resource with path /wildfly-10.0/standalone/data/content/fc/8ec517e0b169fb27b61ff90f04de5dd8ca8d52/content migrated.

Next, the tool will scan the source server for standalone server configurations files:

04:02:08,387 INFO  [org.jboss.migration.core.ServerMigrationTask#3] (main) Retrieving source's standalone configurations...
04:02:08,389 INFO  [org.jboss.migration.core.ServerMigrationTask#3] (main) /wildfly-10.0/standalone/configuration/standalone-full-ha.xml
04:02:08,389 INFO  [org.jboss.migration.core.ServerMigrationTask#3] (main) /wildfly-10.0/standalone/configuration/standalone-full.xml
04:02:08,389 INFO  [org.jboss.migration.core.ServerMigrationTask#3] (main) /wildfly-10.0/standalone/configuration/standalone-ha.xml
04:02:08,390 INFO  [org.jboss.migration.core.ServerMigrationTask#3] (main) /wildfly-10.0/standalone/configuration/standalone.xml

And if the tool is running in interactive mode you will then see the following prompt:

Migrate all configurations?
yes/no?

If you say yes, all listed configuration files are migrated.
If you say no, you receive a prompt asking to confirm the migration, for each listed configuration file:
```
Migrate configuration /wildfly-10.0/standalone/configuration/standalone.xml ?
yes/no? y
```

If you are running in non-interactive mode, the JBoss Server Migration tool will migrate all listed configuration files.

The standalone server migration may be customized, by configuring the following environment properties:

the property named standalone.skip, if defined as true, will skip the entire standalone server migration
the property named server.source.standalone.serverDir may be used to indicate an alternative path for the source’s standalone server directory, which defaults to the standalone directory, in the server’s base directory.
the property named server.source.standalone.configDir may be used to indicate an alternative path for the source’s standalone server configuration directory, which defaults to the configuration directory, in the server’s standalone directory.
the property named server.source.standalone.configFiles may be used to indicate the files names of the configurations to be migrated.
the property named server.target.standalone.serverDir may be used to indicate an alternative path for the target’s standalone server directory, which defaults to the standalone directory, in the server’s base directory.
the property named server.target.standalone.configDir may be used to indicate an alternative path for the target’s standalone server configuration directory, which defaults to the configuration directory, in the server’s standalone directory.

The environment configuration may be done in one of the following ways:

You may configure the properties in the tool's config/environment.properties file:

standalone.skip=false
server.source.standalone.serverDir=standalone
server.source.standalone.configDir=configuration
server.source.standalone.configFiles=standalone.xml,standalone-full.xml
server.target.standalone.serverDir=standalone
server.target.standalone.configDir=configuration

You can configure the above properties in your own custom properties file and pass the file on the command line using the --environment argument.
You can pass the information on the command line using system properties too, in such case all environment property names should be prefixed with jboss.server.migration..

Standalone Configuration File Migration

The migration of a standalone server configuration file consists of copying the source configuration file to the target server, and then apply the relevant changes for such configuration to work correctly in the target server, and also take advantage of the target’s server’s new functionality:

Remove Unsupported Subsystems
Migrate Referenced Modules
Update infinispan Subsystem
Update undertow Subsystem
Add Socket Binding Multicast Address Expressions
Migrate Compatible Security Realms
Add default SSL Server Identity to ApplicationRealm
Migrate Deployments

Remove Unsupported Subsystems

All unsupported subsystems configurations and extensions are removed from migrated server configurations.

The console indicates which unsupported subsystem configurations and extensions are removed from each server configuration:

19:01:26,806 INFO  [org.jboss.migration.core.task.ServerMigrationTask#14] (main) Removed the following unsupported extensions: [org.wildfly.extension.example]
19:01:26,806 INFO  [org.jboss.migration.core.task.ServerMigrationTask#14] (main) Removed the following unsupported subsystems: [urn:jboss:domain:example:1.0]

Migrate Referenced Modules

A migrated standalone server configuration may reference, i.e. depend on, modules which are not installed in the target server, and in such case(s) the tool automatically migrates the referenced module(s), from the source server. Beyond that, any module that a referenced module depends on, directly or not, and is not installed in the target server, is automatically migrated too.

A module will be migrated when referenced by:

a Security Realm configuration, as plug-in(s) module
a Datasource subsystem configuration, as datasource driver(s) module
an EE subsystem configuration, as a global module
a Naming subsystem configuration, as Object Factory module
a Messaging subsystem configuration, as JMS Bridge module

Whenever a module is migrated, a message indicating the module's id should be printed in the migration console/log, as exampled below:

03:25:31,205 INFO  [org.jboss.migration.core.task.ServerMigrationTask#18] (main) Module cmtool.security-realms:main migrated.
03:25:31,218 INFO  [org.jboss.migration.core.task.ServerMigrationTask#19] (main) Module cmtool.datasources:main migrated.
03:25:31,222 INFO  [org.jboss.migration.core.task.ServerMigrationTask#20] (main) Module cmtool.ee1:main migrated.
03:25:31,225 INFO  [org.jboss.migration.core.task.ServerMigrationTask#21] (main) Module cmtool.ee2:main migrated.
03:25:31,229 INFO  [org.jboss.migration.core.task.ServerMigrationTask#22] (main) Module cmtool.naming:main migrated.

It's possible to exclude the migration of specific module(s), by specifying the id(s) in the environment property named modules.excludes.

Update infinispan Subsystem

The infinispan subsystem configuration is updated to better match the Wildfly 10.1 default configurations:

adds default concurrent cache to the web container

The changes on the subsystem configuration are fully automated, the tool console and log(s) will merely indicate these changes were done, e.g.:

03:50:05,752 INFO  [org.jboss.migration.core.task.ServerMigrationTask#26] (main) Cache 'concurrent' added to cache container 'web'.

Please note that the Migration Environment may be configured to customise the process of updating the subsystem configuration:

fully skip the subsystem config update, by setting environment property named subsystem.infinispan.update.skip as true
don't add the default concurrent cache to the web container, by setting environment property named subsystem.infinispan.update.update-infinispan-web-cache.skip as true

Update undertow Subsystem

The migration tool updates Undertow subsystem configuration(s), to enable support for HTTP2, and better match Wildfly 10.1 default configuration files:

add default HTTPS Listener
enable HTTP2 support
sets default Server response header
sets default X-Powered-By response header

03:50:10,186 INFO  [org.jboss.migration.core.task.ServerMigrationTask#205] (main) Default HTTPS listener added to server '/subsystem=undertow/server=default-server', in Undertow's config /subsystem=undertow
03:50:10,208 INFO  [org.jboss.migration.core.task.ServerMigrationTask#206] (main) HTTP2 enabled for Undertow's HTTP Listener /subsystem=undertow/server=default-server/http-listener=default.
03:50:10,216 INFO  [org.jboss.migration.core.task.ServerMigrationTask#206] (main) HTTP2 enabled for Undertow's HTTPS Listener /subsystem=undertow/server=default-server/https-listener=https.
03:50:10,236 INFO  [org.jboss.migration.core.task.ServerMigrationTask#207] (main) Response header 'server-header' set as 'Server: WildFly/10' in Undertow's config /subsystem=undertow
03:50:10,259 INFO  [org.jboss.migration.core.task.ServerMigrationTask#208] (main) Response header 'x-powered-by-header' set as 'X-Powered-By: Undertow/1' in Undertow's config /subsystem=undertow

This additional update of the new subsystem configuration may be customised through the Migration Environment:

fully skip the subsystem config update, by setting environment property named subsystem.undertow.update.skip as true.
don't add the default HTTPS Listener, by setting environment property named subsystem.undertow.update.add-undertow-https-listener.skip as true.
don't enable HTTP2 support, by setting environment property named subsystem.undertow.update.enable-http2.skip as true.
don't set the default Server response header, by setting environment property named subsystem.undertow.update.add-response-header.server-header.skip as true.
don't set the default X-Powered-By response header, by setting environment property named subsystem.undertow.update.add-response-header.x-powered-by-header.skip as true.

Add Socket Binding Multicast Address Expressions

WildFly 10.1 default configurations uses value expressions in the multicast-address attribute of modcluster socket bindings, and the migration tool adds such value expressions to migrated configurations.

The following message(s) in the console indicates this configuration update:

03:50:07,991 INFO  [org.jboss.migration.core.task.ServerMigrationTask#98] (main) Socket binding /socket-binding-group=standard-sockets/socket-binding=modcluster multicast address value expression set as ${jboss.modcluster.multicast.adress:224.0.1.105}.

The Migration Environment may be configured to skip this specific task, by setting environment property named socket-bindings.multicast-address.add-expressions.skip as true.

Migrate Compatible Security Realms

WildFly 10.1 Security Realms configuration is fully compatible with the source server's Security Realms configuration, which means that no changes are required and done. As for any properties file referenced by such configuration, in case its path is not absolute then the tool will copy such file, to the path expected by the migrated config file.

The migration of Security Realms is fully automated, no user interaction is needed, and details about its execution are shown in the migration console and log(s):

14:18:54,418 INFO  [org.jboss.migration.core.task.ServerMigrationTask#140] (main) Migrating security realms...
14:18:54,422 INFO  [org.jboss.migration.core.task.ServerMigrationTask#141] (main) Resource with path /wildfly-10.0/standalone/configuration/mgmt-users.properties migrated.
14:18:54,422 INFO  [org.jboss.migration.core.task.ServerMigrationTask#141] (main) Resource with path /wildfly-10.0/standalone/configuration/mgmt-groups.properties migrated.
14:18:54,422 INFO  [org.jboss.migration.core.task.ServerMigrationTask#141] (main) Security realm /core-service=management/security-realm=ManagementRealm migrated.
14:18:54,424 INFO  [org.jboss.migration.core.task.ServerMigrationTask#142] (main) Resource with path /wildfly-10.0/standalone/configuration/application-users.properties migrated.
14:18:54,425 INFO  [org.jboss.migration.core.task.ServerMigrationTask#142] (main) Resource with path /wildfly-10.0/standalone/configuration/application-roles.properties migrated.
14:18:54,425 INFO  [org.jboss.migration.core.task.ServerMigrationTask#142] (main) Security realm /core-service=management/security-realm=ApplicationRealm migrated.

Please note that the Migration Environment may be configured to customise the process of migrating security realms:

fully skip the security realms migration, by setting environment property named security-realms.migrate-properties.skip as true

Add default SSL Server Identity to ApplicationRealm

WildFly 10.1 default configurations include a SSL Server Identity for the default Security Realm named ApplicationRealm, and the migration tool automatically updates migrated configurations to match such change.

The following message(s) printed on the migration console and log(s), indicates this update of ApplicationRealm configuration(s):

03:50:09,031 INFO  [org.jboss.migration.core.task.ServerMigrationTask#145] (main) SSL server identity added to security realm ApplicationRealm.

Please note that the Migration Environment may be configured to skip this configuration update, by setting environment property named security-realm.ApplicationRealm.add-ssl-server-identity.skip as true

Migrate Deployments

With respect to standalone server configuration's deployments, the migration tool is capable of migrating:

deployments it references, also known as persistent deployments
deployments found in directories monitored by its deployment scanners
deployment overlays it references

Please be warned that the migration of a deployment, or deployment overlay, merely consists in installing related file resources in the target server, and possibly update the migrated configuration. The tool will not assert if such resources are compatible with the target server, which means these may not deploy/work as expected, or not deploy/work at all! To analyse a deployment, with respect to compatibility among different JBoss servers, it is strongly recommended usage of JBoss Windup.

Migrate Persistent Deployments

When migrating a standalone server configuration, the migration tool will search for any persistent deployments it refers, and print the results in the migration console/log:

03:19:08,997 INFO  [org.jboss.migration.core.task.Task#74] (main) Persistent deployments found: [cmtool-helloworld3.war, cmtool-helloworld4.war, cmtool-helloworld2.war, cmtool-helloworld1.war]

And in interactive mode you will then see the following prompt:

Migrate all persistent deployments found?
yes/no? y

If you say yes, or y, all found deployments are migrated.
If you say no, or n, you receive a prompt asking to confirm the migration, for each listed deployment:
```
Migrate persistent deployment 'cmtool-helloworld3.war'?
yes/no?
```
If you say yes, or y, the deployment is migrated.
If you say no, or n, the deployment is removed from the standalone server configuration.

If you are running in non-interactive mode, the JBoss Server Migration tool will migrate all listed deployments.

Migrate Deployment Scanner Deployments

Deployment scanners provide the file system deployment functionality, by monitoring specific directories, and manage deployments files in these, automatically or through special deployment marker files.

The migration tool, when migrating a standalone server configuration, first searches for any configured deployment scanners, and then, for each scanner found, searches its monitored directories for deployments marked as deployed, and lists these in the console/log:

03:47:17,537 INFO  [org.jboss.migration.core.task.ServerMigrationTask#79] (main) Found deployment scanner 'default' watching directory '/wildfly-10.0/standalone/deployments', searching for deployments in it...
03:47:17,538 INFO  [org.jboss.migration.core.task.ServerMigrationTask#79] (main) Deployments found: [cmtool-helloworld5.war, cmtool-helloworld6.war]

And in interactive mode you will then see the following prompt:

Migrate all deployments found?
yes/no? y

If you say yes, or y, all found deployments are migrated.
If you say no, or n, you receive a prompt asking to confirm the migration, for each listed deployment:
```
Migrate deployment 'cmtool-helloworld5.war'?
yes/no?
```
If you say yes, or y, the deployment is migrated.
If you say no, or n, the deployment is not migrated.

If you are running in non-interactive mode, the JBoss Server Migration tool will migrate all listed deployments.

Migrate Deployment Overlays

The migration of deployment overlays is a fully automated process, the migration tool will search for deployment overlays referenced in the standalone server configuration, and migrates all that are linked to deployments which were migrated.

The migration console/log will list all deployment overlays found, if any, and print a message indicating the migration/removal of each:

04:27:00,550 INFO  [org.jboss.migration.core.task.ServerMigrationTask#79] (main) Deployment overlays found: [overlay4, overlay1, overlay2, overlay3]
04:27:00,555 INFO  [org.jboss.migration.core.task.ServerMigrationTask#79] (main) Migrating deployment overlay 'overlay4', it's linked to deployment cmtool-helloworld2.war
04:27:00,572 INFO  [org.jboss.migration.core.task.ServerMigrationTask#80] (main) Removed deployment overlay from configuration /deployment-overlay=overlay1
04:27:00,591 INFO  [org.jboss.migration.core.task.ServerMigrationTask#81] (main) Removed deployment overlay from configuration /deployment-overlay=overlay2
04:27:00,593 INFO  [org.jboss.migration.core.task.ServerMigrationTask#79] (main) Migrating deployment overlay 'overlay3', it's linked to deployment cmtool-helloworld2.war

Domain Migration

The domain migration consists in migrating the source server's domain content and domain/host configuration files, to the target server. This migration task is optional, and in case the tool is running in interactive mode a prompt will first ask to confirm its execution:

Migrate the source's managed domain?
yes/no?

If you say yes, or simply y, the domain migration will proceed.
If you say no, or simply n, the domain migration will be skipped.

In case the domain migration proceeds, the tool will start by migrating the source server's domain content, a cyphered repository used to store data such as deployments and deployment overlays, referenced by domain/host configurations. Both servers use a similar content repository, thus the migration of such data merely consists of finding, and copying such content among servers.

03:25:41,985 INFO  [org.jboss.migration.core.task.ServerMigrationTask#397] (main) Migrating domain content found: [22/caa450a9ba3b84eaf5a15b6da418b92ce6c98e/content, 23/b62a37ba8a4830622bfcdb960280577cc6796e/content, 40/8bcb8a4480739d370ebf70fbcabb33c1508c50/content, 88/96c992d1b9866945a5015b72f8d254d3d5c132/content, ea/69fbffdf08b320c09ad1acc7d31deba5a7787b/content, fc/8ec517e0b169fb27b61ff90f04de5dd8ca8d52/content]
03:25:41,986 INFO  [org.jboss.migration.core.task.ServerMigrationTask#398] (main) Resource with path /wildfly-10.0/domain/data/content/22/caa450a9ba3b84eaf5a15b6da418b92ce6c98e/content migrated.
03:25:41,986 INFO  [org.jboss.migration.core.task.ServerMigrationTask#399] (main) Resource with path /wildfly-10.0/domain/data/content/23/b62a37ba8a4830622bfcdb960280577cc6796e/content migrated.
03:25:41,987 INFO  [org.jboss.migration.core.task.ServerMigrationTask#400] (main) Resource with path /wildfly-10.0/domain/data/content/40/8bcb8a4480739d370ebf70fbcabb33c1508c50/content migrated.
03:25:41,987 INFO  [org.jboss.migration.core.task.ServerMigrationTask#401] (main) Resource with path /wildfly-10.0/domain/data/content/88/96c992d1b9866945a5015b72f8d254d3d5c132/content migrated.
03:25:41,988 INFO  [org.jboss.migration.core.task.ServerMigrationTask#402] (main) Resource with path /wildfly-10.0/domain/data/content/ea/69fbffdf08b320c09ad1acc7d31deba5a7787b/content migrated.
03:25:41,989 INFO  [org.jboss.migration.core.task.ServerMigrationTask#403] (main) Resource with path /wildfly-10.0/domain/data/content/fc/8ec517e0b169fb27b61ff90f04de5dd8ca8d52/content migrated.

Next, the tool will scan the source server for domain configurations files:

04:02:26,244 INFO  [org.jboss.migration.core.ServerMigrationTask#312] (main) Retrieving source's domain configurations...
04:02:26,244 INFO  [org.jboss.migration.core.ServerMigrationTask#312] (main) /wildfly-10.0/domain/configuration/domain.xml

And in interactive mode you will then see the following prompt:

Migrate all configurations?
yes/no?

If you say yes, all listed configuration files are migrated.
If you say no, you receive a prompt asking to confirm the migration, for each listed configuration file:
```
Migrate configuration /wildfly-10.0/domain/configuration/domain.xml ?
yes/no? y
```

If you are running in non-interactive mode, the JBoss Server Migration tool will migrate all listed domain configuration files.

Next, the tool will scan the source server for host configurations files:

07:20:57,749 INFO  [org.jboss.migration.core.ServerMigrationTask#457] (main) Retrieving source's host configurations...
07:20:57,750 INFO  [org.jboss.migration.core.ServerMigrationTask#457] (main) /wildfly-10.0/domain/configuration/host-master.xml
07:20:57,750 INFO  [org.jboss.migration.core.ServerMigrationTask#457] (main) /wildfly-10.0/domain/configuration/host-slave.xml
07:20:57,750 INFO  [org.jboss.migration.core.ServerMigrationTask#457] (main) /wildfly-10.0/domain/configuration/host.xml

And in interactive mode you will see the following prompt:

Migrate all configurations?
yes/no?

If you say yes, all listed configuration files are migrated.
If you say no, you receive a prompt asking to confirm the migration, for each listed configuration file:
```
Migrate configuration /wildfly-10.0/domain/configuration/host.xml ?
yes/no? y
```

If you are running in non-interactive mode, the JBoss Server Migration tool will migrate all listed host configuration files.

The domain migration may be customized, by configuring the migration environment:

the property named domain.skip, if defined as true, will skip the entire domain migration
the property named server.source.domain.domainDir may be used to indicate an alternative path for the source’s domain directory, which defaults to the domain directory, in the server’s base directory.
the property named server.source.domain.configDir may be used to indicate an alternative path for the source’s domain configuration directory, which defaults to the configuration directory, in the server’s domain directory.
the property named server.source.domain.domainConfigFiles may be used to indicate the files names of the domain configurations to be migrated.
the property named server.source.domain.hostConfigFiles may be used to indicate the files names of the host configurations to be migrated.
the property named server.target.domain.domainDir may be used to indicate an alternative path for the target’s domain directory, which defaults to the domain directory, in the server’s base directory.
the property named server.target.domain.configDir may be used to indicate an alternative path for the target’s domain configuration directory, which defaults to the configuration directory, in the server’s domain directory.

The environment configuration may be done in one of the following ways:

You may configure the properties in the tool's config/environment.properties file:

domain.skip=false
server.source.domain.domainDir=domain
server.source.domain.configDir=configuration
server.source.domain.domainConfigFiles=domain.xml
server.source.domain.hostConfigFiles=host-master.xml, host.xml
server.target.domain.domainDir=domain
server.target.domain.configDir=configuration

You can configure the above properties in your own custom properties file and pass the file on the command line using the --environment argument.
You can pass the information on the command line using system properties too, in such case all environment property names should be prefixed with jboss.server.migration..

Domain Configuration File Migration

The migration of a domain configuration file consists of copying the source configuration file to the target server, and then apply the relevant changes for such configuration to work correctly in the target server, and also take advantage of the target’s server’s new functionality:

Remove Unsupported Subsystems
Migrate Referenced Modules
Update infinispan Subsystem
Update undertow Subsystem
Add Socket Binding Multicast Address Expressions
Add Load Balancer Profile
Migrate Deployments

Remove Unsupported Subsystems

All unsupported subsystems configurations and extensions are removed from migrated server configurations.

The console indicates which unsupported subsystem configurations and extensions are removed from each server configuration:

19:01:26,806 INFO  [org.jboss.migration.core.task.ServerMigrationTask#14] (main) Removed the following unsupported extensions: [org.wildfly.extension.example]
19:01:26,806 INFO  [org.jboss.migration.core.task.ServerMigrationTask#14] (main) Removed the following unsupported subsystems: [urn:jboss:domain:example:1.0]

Migrate Referenced Modules

A migrated domain configuration may reference, i.e. depend on, modules which are not installed in the target server, and in such case(s) the tool automatically migrates the referenced module(s), from the source server. Beyond that, any module that a referenced module depends on, directly or not, and is not installed in the target server, is automatically migrated too.

A module will be migrated when referenced by:

a Datasource subsystem configuration, as datasource driver(s) module
an EE subsystem configuration, as a global module
a Naming subsystem configuration, as Object Factory module
a Messaging subsystem configuration, as JMS Bridge module

Whenever a module is migrated, a message indicating the module's id should be printed in the migration console/log, as exampled below:

03:25:31,218 INFO  [org.jboss.migration.core.task.ServerMigrationTask#19] (main) Module cmtool.datasources:main migrated.
03:25:31,222 INFO  [org.jboss.migration.core.task.ServerMigrationTask#20] (main) Module cmtool.ee1:main migrated.
03:25:31,225 INFO  [org.jboss.migration.core.task.ServerMigrationTask#21] (main) Module cmtool.ee2:main migrated.
03:25:31,229 INFO  [org.jboss.migration.core.task.ServerMigrationTask#22] (main) Module cmtool.naming:main migrated.

It's possible to exclude the migration of specific module(s), by specifying the id(s) in the environment property named modules.excludes.

Update infinispan Subsystem

The infinispan subsystem configurations are updated to better match the Wildfly 10.1 default configurations:

adds default concurrent cache to the web container

The changes on the subsystem configurations are fully automated, the tool console and log(s) will merely indicate these changes were done, e.g.:

03:50:12,061 INFO  [org.jboss.migration.core.task.ServerMigrationTask#255] (main) Cache 'concurrent' added to cache container 'web'.
03:50:12,366 INFO  [org.jboss.migration.core.task.ServerMigrationTask#258] (main) Cache 'concurrent' added to cache container 'web'.
03:50:12,605 INFO  [org.jboss.migration.core.task.ServerMigrationTask#261] (main) Cache 'concurrent' added to cache container 'web'.
03:50:12,827 INFO  [org.jboss.migration.core.task.ServerMigrationTask#264] (main) Cache 'concurrent' added to cache container 'web'.

Please note that the Migration Environment may be configured to customise the process of updating the subsystem configuration:

fully skip the subsystem config update, by setting environment property named subsystem.infinispan.update.skip as true
don't add the default concurrent cache to the web container, by setting environment property named subsystem.infinispan.update.update-infinispan-web-cache.skip as true

Update undertow Subsystem

The migration tool updates Undertow subsystem configuration(s), to enable support for HTTP2, and better match Wildfly 10.1 default configuration files:

add default HTTPS Listener
enable HTTP2 support
sets default Server response header
sets default X-Powered-By response header

03:50:12,928 INFO  [org.jboss.migration.core.task.ServerMigrationTask#267] (main) Default HTTPS listener added to server '/profile=ha/subsystem=undertow/server=default-server', in Undertow's config /profile=ha/subsystem=undertow
03:50:12,979 INFO  [org.jboss.migration.core.task.ServerMigrationTask#268] (main) HTTP2 enabled for Undertow's HTTP Listener /profile=ha/subsystem=undertow/server=default-server/http-listener=default.
03:50:13,011 INFO  [org.jboss.migration.core.task.ServerMigrationTask#268] (main) HTTP2 enabled for Undertow's HTTPS Listener /profile=ha/subsystem=undertow/server=default-server/https-listener=https.
03:50:13,058 INFO  [org.jboss.migration.core.task.ServerMigrationTask#269] (main) Response header 'server-header' set as 'Server: WildFly/10' in Undertow's config /profile=ha/subsystem=undertow
03:50:13,101 INFO  [org.jboss.migration.core.task.ServerMigrationTask#270] (main) Response header 'x-powered-by-header' set as 'X-Powered-By: Undertow/1' in Undertow's config /profile=ha/subsystem=undertow
03:50:13,214 INFO  [org.jboss.migration.core.task.ServerMigrationTask#272] (main) Default HTTPS listener added to server '/profile=full-ha/subsystem=undertow/server=default-server', in Undertow's config /profile=full-ha/subsystem=undertow
03:50:13,255 INFO  [org.jboss.migration.core.task.ServerMigrationTask#273] (main) HTTP2 enabled for Undertow's HTTP Listener /profile=full-ha/subsystem=undertow/server=default-server/http-listener=default.
03:50:13,285 INFO  [org.jboss.migration.core.task.ServerMigrationTask#273] (main) HTTP2 enabled for Undertow's HTTPS Listener /profile=full-ha/subsystem=undertow/server=default-server/https-listener=https.
03:50:13,327 INFO  [org.jboss.migration.core.task.ServerMigrationTask#274] (main) Response header 'server-header' set as 'Server: WildFly/10' in Undertow's config /profile=full-ha/subsystem=undertow
03:50:13,368 INFO  [org.jboss.migration.core.task.ServerMigrationTask#275] (main) Response header 'x-powered-by-header' set as 'X-Powered-By: Undertow/1' in Undertow's config /profile=full-ha/subsystem=undertow
03:50:13,456 INFO  [org.jboss.migration.core.task.ServerMigrationTask#277] (main) Default HTTPS listener added to server '/profile=full/subsystem=undertow/server=default-server', in Undertow's config /profile=full/subsystem=undertow
03:50:13,496 INFO  [org.jboss.migration.core.task.ServerMigrationTask#278] (main) HTTP2 enabled for Undertow's HTTP Listener /profile=full/subsystem=undertow/server=default-server/http-listener=default.
03:50:13,531 INFO  [org.jboss.migration.core.task.ServerMigrationTask#278] (main) HTTP2 enabled for Undertow's HTTPS Listener /profile=full/subsystem=undertow/server=default-server/https-listener=https.
03:50:13,574 INFO  [org.jboss.migration.core.task.ServerMigrationTask#279] (main) Response header 'server-header' set as 'Server: WildFly/10' in Undertow's config /profile=full/subsystem=undertow
03:50:13,614 INFO  [org.jboss.migration.core.task.ServerMigrationTask#280] (main) Response header 'x-powered-by-header' set as 'X-Powered-By: Undertow/1' in Undertow's config /profile=full/subsystem=undertow
03:50:13,698 INFO  [org.jboss.migration.core.task.ServerMigrationTask#282] (main) Default HTTPS listener added to server '/profile=default/subsystem=undertow/server=default-server', in Undertow's config /profile=default/subsystem=undertow
03:50:13,741 INFO  [org.jboss.migration.core.task.ServerMigrationTask#283] (main) HTTP2 enabled for Undertow's HTTP Listener /profile=default/subsystem=undertow/server=default-server/http-listener=default.
03:50:13,769 INFO  [org.jboss.migration.core.task.ServerMigrationTask#283] (main) HTTP2 enabled for Undertow's HTTPS Listener /profile=default/subsystem=undertow/server=default-server/https-listener=https.
03:50:13,814 INFO  [org.jboss.migration.core.task.ServerMigrationTask#284] (main) Response header 'server-header' set as 'Server: WildFly/10' in Undertow's config /profile=default/subsystem=undertow
03:50:13,871 INFO  [org.jboss.migration.core.task.ServerMigrationTask#285] (main) Response header 'x-powered-by-header' set as 'X-Powered-By: Undertow/1' in Undertow's config /profile=default/subsystem=undertow

This additional update of the new subsystem configuration may be customised through the Migration Environment:

fully skip the subsystem config update, by setting environment property named subsystem.undertow.update.skip as true.
don't add the default HTTPS Listener, by setting environment property named subsystem.undertow.update.add-undertow-https-listener.skip as true.
don't enable HTTP2 support, by setting environment property named subsystem.undertow.update.enable-http2.skip as true.
don't set the default Server response header, by setting environment property named subsystem.undertow.update.add-response-header.server-header.skip as true.
don't set the default X-Powered-By response header, by setting environment property named subsystem.undertow.update.add-response-header.x-powered-by-header.skip as true.

Add Socket Binding Multicast Address Expressions

The following message(s) in the console indicates this configuration update:

03:50:19,651 INFO  [org.jboss.migration.core.task.ServerMigrationTask#431] (main) Socket binding /socket-binding-group=full-ha-sockets/socket-binding=modcluster multicast address value expression set as ${jboss.modcluster.multicast.adress:224.0.1.105}.
03:50:19,673 INFO  [org.jboss.migration.core.task.ServerMigrationTask#432] (main) Socket binding /socket-binding-group=ha-sockets/socket-binding=modcluster multicast address value expression set as ${jboss.modcluster.multicast.adress:224.0.1.105}.

The Migration Environment may be configured to skip this specific task, by setting environment property named socket-bindings.multicast-address.add-expressions.skip as true.

Add Load Balancer Profile

WildFly 10.1 includes a new default profile, specially tailored for hosts servings as load balancers, and the migration tool automatically configures such profile in all migrated domain configurations.

03:50:15,308 INFO  [org.jboss.migration.core.task.ServerMigrationTask#332] (main) Adding profile load-balancer...
03:50:15,335 INFO  [org.jboss.migration.core.task.ServerMigrationTask#333] (main) Profile load-balancer created.
03:50:15,473 INFO  [org.jboss.migration.core.task.ServerMigrationTask#335] (main) Adding subsystem io configuration(s)...
03:50:15,474 INFO  [org.jboss.migration.core.task.ServerMigrationTask#336] (main) Extension org.wildfly.extension.io already exists in config.
03:50:15,582 INFO  [org.jboss.migration.core.task.ServerMigrationTask#337] (main) Subsystem config /profile=load-balancer/subsystem=io added.
03:50:15,582 INFO  [org.jboss.migration.core.task.ServerMigrationTask#338] (main) Adding subsystem undertow configuration(s)...
03:50:15,584 INFO  [org.jboss.migration.core.task.ServerMigrationTask#339] (main) Extension org.wildfly.extension.undertow already exists in config.
03:50:15,820 INFO  [org.jboss.migration.core.task.ServerMigrationTask#340] (main) Subsystem config /profile=load-balancer/subsystem=undertow added.
03:50:15,821 INFO  [org.jboss.migration.core.task.ServerMigrationTask#341] (main) Adding subsystem logging configuration(s)...
03:50:15,822 INFO  [org.jboss.migration.core.task.ServerMigrationTask#342] (main) Extension org.jboss.as.logging already exists in config.
03:50:16,048 INFO  [org.jboss.migration.core.task.ServerMigrationTask#343] (main) Subsystem config /profile=load-balancer/subsystem=logging added.
03:50:16,049 INFO  [org.jboss.migration.core.task.ServerMigrationTask#332] (main) Profile load-balancer added.

The Migration Environment may be configured to skip this particular configuration update, by setting environment property named profile.load-balancer.add.skip as true.

Migrate Deployments

With respect to domain configuration's deployments, the migration tool is capable of migrating the persistent deployments it references, and related deployment overlays as well.

Migrate Persistent Deployments

When migrating a domain configuration, the migration tool will search for any persistent deployments it refers, and print the results in the migration console/log:

03:19:08,997 INFO  [org.jboss.migration.core.task.Task#74] (main) Persistent deployments found: [cmtool-helloworld3.war, cmtool-helloworld4.war, cmtool-helloworld2.war, cmtool-helloworld1.war]

And in interactive mode you will then see the following prompt:

Migrate all persistent deployments found?
yes/no? y

If you say yes, or y, all found deployments are migrated.
If you say no, or n, you receive a prompt asking to confirm the migration, for each listed deployment:
```
Migrate persistent deployment 'cmtool-helloworld3.war'?
yes/no?
```
If you say yes, or y, the deployment is migrated.

If you say no, or n, all references to the deployment are removed.

04:31:43,562 INFO  [org.jboss.migration.core.task.ServerMigrationTask#555] (main) Removed persistent deployment from server group /deployment=cmtool-helloworld4.war
04:31:43,591 INFO  [org.jboss.migration.core.task.ServerMigrationTask#555] (main) Removed persistent deployment from configuration /deployment=cmtool-helloworld4.war

If you are running in non-interactive mode, the JBoss Server Migration tool will migrate all listed deployments.

Migrate Deployment Overlays

The migration of deployment overlays is a fully automated process, the migration tool will search for deployment overlays referenced in the domain configuration, and migrates all that are linked to deployments which were migrated.

The migration console/log will list all deployment overlays found, if any, and print a message indicating the migration/removal of each:

04:33:30,053 INFO  [org.jboss.migration.core.task.ServerMigrationTask#559] (main) Deployment overlays found: [overlay4, overlay1, overlay2, overlay3]
04:33:30,062 INFO  [org.jboss.migration.core.task.ServerMigrationTask#559] (main) Migrating deployment overlay 'overlay4', it's linked to deployment cmtool-helloworld2.war
04:33:30,098 INFO  [org.jboss.migration.core.task.ServerMigrationTask#560] (main) Removed deployment overlay from server group /deployment-overlay=overlay1
04:33:30,120 INFO  [org.jboss.migration.core.task.ServerMigrationTask#560] (main) Removed deployment overlay from server group /deployment-overlay=overlay1
04:33:30,148 INFO  [org.jboss.migration.core.task.ServerMigrationTask#560] (main) Removed deployment overlay from configuration /deployment-overlay=overlay1
04:33:30,175 INFO  [org.jboss.migration.core.task.ServerMigrationTask#561] (main) Removed deployment overlay from server group /deployment-overlay=overlay2
04:33:30,198 INFO  [org.jboss.migration.core.task.ServerMigrationTask#561] (main) Removed deployment overlay from configuration /deployment-overlay=overlay2
04:33:30,202 INFO  [org.jboss.migration.core.task.ServerMigrationTask#559] (main) Migrating deployment overlay 'overlay3', it's linked to deployment cmtool-helloworld2.war

Host Configuration File Migration

The migration of a host configuration file consists of copying the source configuration file to the target server, and then apply the relevant changes for such configuration to work correctly in the target server, and also take advantage of the target’s server’s new functionality:

Migrate Referenced Modules
Migrate Compatible Security Realms
Add default SSL Server Identity to ApplicationRealm

Migrate Referenced Modules

A migrated host configuration may reference, i.e. depend on, modules which are not installed in the target server, and in such case(s) the tool automatically migrates the referenced module(s), from the source server. Beyond that, any module that a referenced module depends on, directly or not, and is not installed in the target server, is automatically migrated too.

A module will be migrated when referenced by:

a Security Realm configuration, as plug-in(s) module

Whenever a module is migrated, a message indicating the module's id should be printed in the migration console/log, as exampled below:

03:25:31,205 INFO  [org.jboss.migration.core.task.ServerMigrationTask#18] (main) Module cmtool.security-realms:main migrated.

It's possible to exclude the migration of specific module(s), by specifying the id(s) in the environment property named modules.excludes.

Migrate Compatible Security Realms

Wildfly 10.1 Security Realms configuration is fully compatible with the source server's Security Realms configuration, which means that no changes are required and done. As for any properties file referenced by such configuration, in case its path is not absolute then the tool will copy such file, to the path expected by the migrated config file.

The migration of Security Realms is fully automated, no user interaction is needed, and details about its execution are shown in the migration console and log(s):

02:30:41,051 INFO  [org.jboss.migration.core.ServerMigrationTask#485] (main) Migrating security realms...
02:30:41,055 INFO  [org.jboss.migration.core.ServerMigrationTask#486] (main) Security realm ManagementRealm migrated.
02:30:41,059 INFO  [org.jboss.migration.core.ServerMigrationTask#487] (main) Security realm ApplicationRealm migrated.
02:30:41,059 INFO  [org.jboss.migration.core.ServerMigrationTask#485] (main) Security realms migration done.

Please note that the Migration Environment may be configured to customise the process of migrating security realms:

fully skip the security realms migration, by setting environment property named security-realms.migrate-properties.skip as true

Add default SSL Server Identity to ApplicationRealm

The following message(s) printed on the migration console and log(s), indicates this update of ApplicationRealm configuration(s):

03:50:21,610 INFO  [org.jboss.migration.core.task.ServerMigrationTask#494] (main) SSL server identity added to security realm ApplicationRealm.