JBoss Community Archive (Read Only)

JBoss Server Migration Tool

Migrating from WildFly 9 to JBoss EAP 7.0

Overview

This document describes how to use the JBoss Server Migration Tool to migrate from WildFly 9 to JBoss EAP 7.0. 

~/jboss-server-migration $ ./server-migration.sh --source ../wildfly-9 --target ../jboss-eap-7.0

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

Retrieving servers...
20:40:31,067 INFO  [org.jboss.migration.core.logger] (main) SOURCE server name: WildFly, version: 9.0.2.Final.
20:40:31,079 INFO  [org.jboss.migration.core.logger] (main) TARGET server name: JBoss EAP, version: 7.0.0.GA.

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-9/standalone/data/content/22/caa450a9ba3b84eaf5a15b6da418b92ce6c98e/content migrated.
03:25:28,267 INFO  [org.jboss.migration.core.task.ServerMigrationTask#7] (main) Resource with path /wildfly-9/standalone/data/content/23/b62a37ba8a4830622bfcdb960280577cc6796e/content migrated.
03:25:28,268 INFO  [org.jboss.migration.core.task.ServerMigrationTask#8] (main) Resource with path /wildfly-9/standalone/data/content/40/8bcb8a4480739d370ebf70fbcabb33c1508c50/content migrated.
03:25:28,269 INFO  [org.jboss.migration.core.task.ServerMigrationTask#9] (main) Resource with path /wildfly-9/standalone/data/content/88/96c992d1b9866945a5015b72f8d254d3d5c132/content migrated.
03:25:28,270 INFO  [org.jboss.migration.core.task.ServerMigrationTask#10] (main) Resource with path /wildfly-9/standalone/data/content/ea/69fbffdf08b320c09ad1acc7d31deba5a7787b/content migrated.
03:25:28,271 INFO  [org.jboss.migration.core.task.ServerMigrationTask#11] (main) Resource with path /wildfly-9/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-9/standalone/configuration/standalone-full-ha.xml
04:02:08,389 INFO  [org.jboss.migration.core.ServerMigrationTask#3] (main) /wildfly-9/standalone/configuration/standalone-full.xml
04:02:08,389 INFO  [org.jboss.migration.core.ServerMigrationTask#3] (main) /wildfly-9/standalone/configuration/standalone-ha.xml
04:02:08,390 INFO  [org.jboss.migration.core.ServerMigrationTask#3] (main) /wildfly-9/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-9/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

  • Migrate messaging Subsystem

  • Update undertow Subsystem

  • Add batch-jberet Subsystem

  • Add singleton Subsystem

  • Setup Private Interface

  • Migrate Compatible Security Realms

  • Migrate Deployments

Remove Unsupported Subsystems

The following WildFly 9 subsystems are not supported by JBoss EAP 7:

  • batch (configuration namepace: urn:jboss:domain:batch:*, extension module: org.wildfly.extension.batch)

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.batch]
19:01:26,806 INFO  [org.jboss.migration.core.task.ServerMigrationTask#14] (main) Removed the following unsupported subsystems: [urn:jboss:domain:batch: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.

Migrate messaging Subsystem

The messaging subsystem is deprecated on EAP 7, and the tool migrates its configuration to the EAP 7 subsystem that replaces it, named messaging-activemq.

The legacy subsystem migration is done without any interaction with the user, and any issue with the legacy subsystem configuration, e.g. missing functionality, results in a warning shown in the migration console and log(s). A successful migration of the legacy subsystem configuration is indicated by the following messages: 

04:02:15,770 INFO  [org.jboss.migration.core.ServerMigrationTask#18] (main) Migrating subsystem messaging configurations...
04:02:16,153 INFO  [org.jboss.migration.core.ServerMigrationTask#19] (main) Subsystem config /subsystem=messaging migrated.
04:02:16,170 INFO  [org.jboss.migration.core.ServerMigrationTask#20] (main) Extension org.jboss.as.messaging removed.
04:02:16,170 INFO  [org.jboss.migration.core.ServerMigrationTask#18] (main) Subsystem messaging configurations migrated.

Please note that the Migration Environment may be configured to skip messaging's subsystem migration, by setting environment property named subsystem.messaging.migrate.skip as true.

Update undertow Subsystem

The tool updates Undertow's subsystem configuration(s), to better match EAP 7 default standalone config files, more specifically:

  • sets default Server response header

  • sets default X-Powered-By response header 

21:18:50,666 INFO  [org.jboss.migration.core.task.ServerMigrationTask#32] (main) Response header 'server-header' set as 'Server: JBoss-EAP/7' in Undertow's config /subsystem=undertow
21:18:50,709 INFO  [org.jboss.migration.core.task.ServerMigrationTask#33] (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 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 batch-jberet Subsystem

The JBoss EAP 7 batch-jberet subsystem provides support for [https://jcp.org/en/jsr/detail?id=352|JSR 352], Batch Applications for the Java EE 7 Platform. Its default configuration is automatically added to the migrated configuration file unless the environment property named subsystem.batch-jberet.add.skip is set.

The subsystem and related extension are added without any interaction required by the user. The migration console and logs display the following messages to indicate it was added. 

04:02:16,891 INFO  [org.jboss.migration.core.ServerMigrationTask#41] (main) Extension org.wildfly.extension.batch.jberet added.
04:02:16,905 INFO  [org.jboss.migration.core.ServerMigrationTask#42] (main) Subsystem config /subsystem=batch-jberet added.

Add singleton Subsystem

The singleton is a EAP 7 subsystem which, as the name indicates, provides the singleton functionality. Its default configuration is automatically added to the migrated configuration file, unless the environment property named subsystem.singleton.add.skip is set.

Please note that such subsystem, and related extension, is added without any interaction with the user, the migration console and log(s) will only indicate it was added, an example: 

04:02:17,022 INFO  [org.jboss.migration.core.ServerMigrationTask#50] (main) Extension org.wildfly.extension.clustering.singleton added.
04:02:17,041 INFO  [org.jboss.migration.core.ServerMigrationTask#51] (main) Subsystem config /subsystem=singleton added.

Setup Private Interface

JBoss EAP 7 default configurations uses a new private interface on all jgroups socket bindings, and the tool automatically updates any migrated configuration with jgroups socket-bindings, to follow same setup.

The following messages in the console indicates this configuration update: 

14:18:54,292 INFO  [org.jboss.migration.core.task.ServerMigrationTask#134] (main) Interface private added.
14:18:54,305 INFO  [org.jboss.migration.core.task.ServerMigrationTask#135] (main) Socket binding /socket-binding-group=standard-sockets/socket-binding=jgroups-mping interface set to private
14:18:54,324 INFO  [org.jboss.migration.core.task.ServerMigrationTask#135] (main) Socket binding /socket-binding-group=standard-sockets/socket-binding=jgroups-tcp interface set to private
14:18:54,342 INFO  [org.jboss.migration.core.task.ServerMigrationTask#135] (main) Socket binding /socket-binding-group=standard-sockets/socket-binding=jgroups-tcp-fd interface set to private
14:18:54,357 INFO  [org.jboss.migration.core.task.ServerMigrationTask#135] (main) Socket binding /socket-binding-group=standard-sockets/socket-binding=jgroups-udp interface set to private
14:18:54,371 INFO  [org.jboss.migration.core.task.ServerMigrationTask#135] (main) Socket binding /socket-binding-group=standard-sockets/socket-binding=jgroups-udp-fd interface set to private

The Migration Environment may be configured to skip adding the private, by setting environment property named interface.private.setup.skip as true.

Migrate Compatible Security Realms

JBoss EAP 7 Security Realms configuration is fully compatible with the EAP 6 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-9/standalone/configuration/mgmt-users.properties migrated.
14:18:54,422 INFO  [org.jboss.migration.core.task.ServerMigrationTask#141] (main) Resource with path /wildfly-9/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-9/standalone/configuration/application-users.properties migrated.
14:18:54,425 INFO  [org.jboss.migration.core.task.ServerMigrationTask#142] (main) Resource with path /wildfly-9/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

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-9/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-9/domain/data/content/22/caa450a9ba3b84eaf5a15b6da418b92ce6c98e/content migrated.
03:25:41,986 INFO  [org.jboss.migration.core.task.ServerMigrationTask#399] (main) Resource with path /wildfly-9/domain/data/content/23/b62a37ba8a4830622bfcdb960280577cc6796e/content migrated.
03:25:41,987 INFO  [org.jboss.migration.core.task.ServerMigrationTask#400] (main) Resource with path /wildfly-9/domain/data/content/40/8bcb8a4480739d370ebf70fbcabb33c1508c50/content migrated.
03:25:41,987 INFO  [org.jboss.migration.core.task.ServerMigrationTask#401] (main) Resource with path /wildfly-9/domain/data/content/88/96c992d1b9866945a5015b72f8d254d3d5c132/content migrated.
03:25:41,988 INFO  [org.jboss.migration.core.task.ServerMigrationTask#402] (main) Resource with path /wildfly-9/domain/data/content/ea/69fbffdf08b320c09ad1acc7d31deba5a7787b/content migrated.
03:25:41,989 INFO  [org.jboss.migration.core.task.ServerMigrationTask#403] (main) Resource with path /wildfly-9/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-9/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-9/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-9/domain/configuration/host-master.xml
07:20:57,750 INFO  [org.jboss.migration.core.ServerMigrationTask#457] (main) /wildfly-9/domain/configuration/host-slave.xml
07:20:57,750 INFO  [org.jboss.migration.core.ServerMigrationTask#457] (main) /wildfly-9/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-9/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

  • Migrate messaging Subsystem

  • Update undertow Subsystem

  • Add batch-jberet Subsystem

  • Add singleton Subsystem

  • Update Unsecure Interface

  • Setup Private Interface

  • Remove Permgen Attributes From JVMs

  • Migrate Deployments

Remove Unsupported Subsystems

The following WildFly 9 subsystems are not supported by JBoss EAP 7:

  • batch (configuration namepace: urn:jboss:domain:batch:*, extension module: org.wildfly.extension.batch)

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.batch]
19:01:26,806 INFO  [org.jboss.migration.core.task.ServerMigrationTask#14] (main) Removed the following unsupported subsystems: [urn:jboss:domain:batch: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.

Migrate messaging Subsystem

The messaging subsystem is deprecated on EAP 7, and the tool migrates its configurations to the EAP 7 subsystem that replaces it, named messaging-activemq.

The legacy subsystem migration is done without any interaction with the user, and any issue with the legacy subsystem configuration, e.g. missing functionality, results in a warning shown in the migration console and log(s). A successful migration of the legacy subsystem configurations is indicated by the following messages: 

07:20:53,796 INFO  [org.jboss.migration.core.ServerMigrationTask#343] (main) Migrating subsystem messaging configurations...
07:20:53,902 INFO  [org.jboss.migration.core.ServerMigrationTask#344] (main) Subsystem config /profile=full-ha/subsystem=messaging migrated.
07:20:53,983 INFO  [org.jboss.migration.core.ServerMigrationTask#347] (main) Subsystem config /profile=full/subsystem=messaging migrated.
07:20:54,009 INFO  [org.jboss.migration.core.ServerMigrationTask#348] (main) Extension org.jboss.as.messaging removed.
07:20:54,009 INFO  [org.jboss.migration.core.ServerMigrationTask#343] (main) Subsystem messaging configurations migrated.

Please note that the Migration Environment may be configured to skip messaging's subsystem migration, by setting environment property named subsystem.messaging.migrate.skip as true.

Update undertow Subsystem

The tool updates Undertow's subsystem configuration(s), to better match EAP 7 default standalone config files, more specifically:

  • sets default Server response header

  • sets default X-Powered-By response header 

00:42:37,516 INFO  [org.jboss.migration.core.task.ServerMigrationTask#244] (main) Response header 'server-header' set as 'Server: JBoss-EAP/7' in Undertow's config /profile=default/subsystem=undertow
00:42:37,548 INFO  [org.jboss.migration.core.task.ServerMigrationTask#245] (main) Response header 'x-powered-by-header' set as 'X-Powered-By: Undertow/1' in Undertow's config /profile=default/subsystem=undertow
00:42:37,599 INFO  [org.jboss.migration.core.task.ServerMigrationTask#247] (main) Response header 'server-header' set as 'Server: JBoss-EAP/7' in Undertow's config /profile=ha/subsystem=undertow
00:42:37,630 INFO  [org.jboss.migration.core.task.ServerMigrationTask#248] (main) Response header 'x-powered-by-header' set as 'X-Powered-By: Undertow/1' in Undertow's config /profile=ha/subsystem=undertow
00:42:37,674 INFO  [org.jboss.migration.core.task.ServerMigrationTask#250] (main) Response header 'server-header' set as 'Server: JBoss-EAP/7' in Undertow's config /profile=full/subsystem=undertow
00:42:37,704 INFO  [org.jboss.migration.core.task.ServerMigrationTask#251] (main) Response header 'x-powered-by-header' set as 'X-Powered-By: Undertow/1' in Undertow's config /profile=full/subsystem=undertow
00:42:37,770 INFO  [org.jboss.migration.core.task.ServerMigrationTask#253] (main) Response header 'server-header' set as 'Server: JBoss-EAP/7' in Undertow's config /profile=full-ha/subsystem=undertow
00:42:37,802 INFO  [org.jboss.migration.core.task.ServerMigrationTask#254] (main) Response header 'x-powered-by-header' set as 'X-Powered-By: Undertow/1' in Undertow's config /profile=full-ha/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 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 batch-jberet Subsystem

The JBoss EAP 7 batch-jberet subsystem provides support for [https://jcp.org/en/jsr/detail?id=352|JSR 352], Batch Applications for the Java EE 7 Platform. Its default configuration is automatically added to all profiles in the migrated configuration file unless the environment property named subsystem.batch-jberet.add.skip is set.

The subsystem and related extension are added without any interaction required by the user. The migration console and logs display the following messages to indicate it was added. 

07:20:56,479 INFO  [org.jboss.migration.core.ServerMigrationTask#408] (main) Extension org.wildfly.extension.batch.jberet added.
07:20:56,507 INFO  [org.jboss.migration.core.ServerMigrationTask#409] (main) Subsystem config /profile=full-ha/subsystem=batch-jberet added.
07:20:56,528 INFO  [org.jboss.migration.core.ServerMigrationTask#410] (main) Subsystem config /profile=default/subsystem=batch-jberet added.
07:20:56,557 INFO  [org.jboss.migration.core.ServerMigrationTask#411] (main) Subsystem config /profile=ha/subsystem=batch-jberet added.
07:20:56,579 INFO  [org.jboss.migration.core.ServerMigrationTask#412] (main) Subsystem config /profile=full/subsystem=batch-jberet added.

Add singleton Subsystem

The singleton is a EAP 7 subsystem which, as the name indicates, provides the singleton functionality. Its default configuration is automatically added to all profiles in the migrated configuration file, unless the environment property named subsystem.singleton.add.skip is set.

Please note that such subsystem, and related extension, is added without any interaction with the user, the migration console and log(s) will only indicate it was added, an example: 

07:20:56,948 INFO  [org.jboss.migration.core.ServerMigrationTask#426] (main) Extension org.wildfly.extension.clustering.singleton added.
07:20:56,982 INFO  [org.jboss.migration.core.ServerMigrationTask#427] (main) Subsystem config /profile=full-ha/subsystem=singleton added.
07:20:57,011 INFO  [org.jboss.migration.core.ServerMigrationTask#428] (main) Subsystem config /profile=default/subsystem=singleton added.
07:20:57,038 INFO  [org.jboss.migration.core.ServerMigrationTask#429] (main) Subsystem config /profile=ha/subsystem=singleton added.
07:20:57,058 INFO  [org.jboss.migration.core.ServerMigrationTask#430] (main) Subsystem config /profile=full/subsystem=singleton added.

Update Unsecure Interface

The tool updates the unsecure interface configuration to match JBoss EAP 7 default configurations.

The configuration changes are fully automated, and the following messages, in the migration console and log(s), indicate that such changes were done as expected: 

07:20:57,083 INFO  [org.jboss.migration.core.ServerMigrationTask#432] (main) Interface unsecure inet address value set as ${jboss.bind.address.unsecure:127.0.0.1}.

The Migration Environment may be configured to skip the Unsecure interface update, by setting environment property named interface.unsecure.update.skip as true.

Setup Private Interface

JBoss EAP 7 default configurations uses a new private interface on all jgroups socket bindings, and the tool automatically updates any migrated configuration with jgroups socket-bindings, to follow same setup.

The following messages in the console indicates this configuration update: 

07:20:57,102 INFO  [org.jboss.migration.core.ServerMigrationTask#434] (main) Interface private added.
07:20:57,121 INFO  [org.jboss.migration.core.ServerMigrationTask#436] (main) Socket binding /socket-binding-group=full-ha-sockets/socket-binding=jgroups-mping interface set to private
07:20:57,140 INFO  [org.jboss.migration.core.ServerMigrationTask#436] (main) Socket binding /socket-binding-group=full-ha-sockets/socket-binding=jgroups-tcp interface set to private
07:20:57,159 INFO  [org.jboss.migration.core.ServerMigrationTask#436] (main) Socket binding /socket-binding-group=full-ha-sockets/socket-binding=jgroups-tcp-fd interface set to private
07:20:57,181 INFO  [org.jboss.migration.core.ServerMigrationTask#436] (main) Socket binding /socket-binding-group=full-ha-sockets/socket-binding=jgroups-udp interface set to private
07:20:57,202 INFO  [org.jboss.migration.core.ServerMigrationTask#436] (main) Socket binding /socket-binding-group=full-ha-sockets/socket-binding=jgroups-udp-fd interface set to private
07:20:57,223 INFO  [org.jboss.migration.core.ServerMigrationTask#438] (main) Socket binding /socket-binding-group=ha-sockets/socket-binding=jgroups-mping interface set to private
07:20:57,244 INFO  [org.jboss.migration.core.ServerMigrationTask#438] (main) Socket binding /socket-binding-group=ha-sockets/socket-binding=jgroups-tcp interface set to private
07:20:57,262 INFO  [org.jboss.migration.core.ServerMigrationTask#438] (main) Socket binding /socket-binding-group=ha-sockets/socket-binding=jgroups-tcp-fd interface set to private
07:20:57,281 INFO  [org.jboss.migration.core.ServerMigrationTask#438] (main) Socket binding /socket-binding-group=ha-sockets/socket-binding=jgroups-udp interface set to private
07:20:57,300 INFO  [org.jboss.migration.core.ServerMigrationTask#438] (main) Socket binding /socket-binding-group=ha-sockets/socket-binding=jgroups-udp-fd interface set to private

The Migration Environment may be configured to skip adding the private, by setting environment property named interface.private.setup.skip as true.

Remove Permgen Attributes From JVMs

The usage of Permgen attributes in JVM configurations is deprecated, and the tool removes these from all JVM configurations, for all server groups. 

07:20:57,629 INFO  [org.jboss.migration.core.ServerMigrationTask#453] (main) Removal of permgen attributes from JVM configs starting...
07:20:57,695 INFO  [org.jboss.migration.core.ServerMigrationTask#454] (main) Permgen removed from JVM /server-group=main-server-group/jvm=default
07:20:57,731 INFO  [org.jboss.migration.core.ServerMigrationTask#455] (main) Permgen removed from JVM /server-group=other-server-group/jvm=default
07:20:57,731 INFO  [org.jboss.migration.core.ServerMigrationTask#453] (main) Removal of permgen attributes from JVM configs done.

The Migration Environment may be configured to skip adding this configuration update, by setting environment property named jvms.remove-permgen-attributes.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.

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

  • Remove Unsecure Interface

  • Remove Permgen Attributes from JVMs

  • Migrate Compatible Security Realms

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.

Remove Unsecure Interface

The tool removes the unsecure interface configuration from all host configurations, to match JBoss EAP 7 default configurations.

The configuration changes are fully automated, and the following messages, in the migration console and log(s), indicate that such changes were done as expected: 

02:30:41,015 INFO  [org.jboss.migration.core.ServerMigrationTask#480] (main) Interface unsecure removed.

The Migration Environment may be configured to skip the Unsecure interface update, by setting environment property named interface.unsecure.remove.skip as true.

Remove Permgen Attributes from JVMs

The usage of Permgen attributes in JVM configurations is deprecated, and the tool removes these from all JVM configurations, for all server groups. 

02:30:41,016 INFO  [org.jboss.migration.core.ServerMigrationTask#483] (main) Removal of permgen attributes from JVM configs starting...
02:30:41,050 INFO  [org.jboss.migration.core.ServerMigrationTask#484] (main) Permgen removed from JVM /host=eduardos-mini.lan/jvm=default
02:30:41,050 INFO  [org.jboss.migration.core.ServerMigrationTask#483] (main) Removal of permgen attributes from JVM configs done.

The Migration Environment may be configured to skip adding this configuration update, by setting environment property named jvms.remove-permgen-attributes.skip as true.

Migrate Compatible Security Realms

EAP 7 Security Realms configuration is fully compatible with the EAP 6 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

JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-11 11:38:39 UTC, last content change 2017-02-25 03:12:10 UTC.