# Migrating from WildFly 10.0 to JBoss EAP 7.2

version 1.9.0.Final, 2020-06-18T18:13:38Z

## 1. Overview

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

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

    Retrieving servers...
    INFO SOURCE server name: WildFly, version: 10.0.0.Final.
    INFO TARGET server name: JBoss EAP, version: 7.2.0.GA.

    Server migration starting...

The server migration from WildFly 10.0 to JBoss EAP 7.2 includes:

- Modules Migration

- Standalone Server Migration

- Managed Domain Migration

## 2. Modules Migration

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

The migration of source server’s module can be done explicitly, i.e. by user demand, or implicitly, because a migrated module or server configuration depends on it.

You can specify which modules should be migrated or not, by using the `modules.includes` and `modules.excludes` environment properties:

- A module whose ID is referenced by the `modules.excludes` environment property is never migrated.

- A module whose ID is referenced by the `modules.includes` environment property is always migrated, unless it referenced by the `modules.excludes` environment property.

Important | The syntax for a module ID is name:slot; The slot is optional, and if it is not specified, defaults to main.

As an example, to migrate modules `com.example.moduleA` and `com.example.moduleB`, and do not migrate module `com.example.moduleC`:

- You can 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 properties in your own custom properties file, and then pass the file on the command line using the `--environment` argument.

- You can pass the information on the command line using a system property. The environment property names must be prefixed with `jboss.server.migration.`:

      -Djboss.server.migration.modules.includes="com.example.moduleA,com.example.moduleB" -Djboss.server.migration.modules.excludes="com.example.moduleC"

Warning | The JBoss Server Migration Tool does not verify that the source server’s module is compatible with the target server, and the migration of an incompatible module may cause the target server to malfunction, or not work at all.

## 3. Standalone Server Migration

### 3.1. Standalone Configuration Processing Overview

When tasked to migrate standalone server configurations, the JBoss Server Migration Tool migrates the configuration files and related content from the source server to the target server. This migration task is optional.

If you run the migration tool in `interactive` mode, which is the default, you are are prompted to confirm its execution.

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

- If you reply with yes or y, the standalone server migration proceeds.

- If you reply with no or n, the standalone server migration is skipped.

If you choose to proceed, the tool starts by migrating the source standalone server’s content. Because both the source and target servers use a similar cyphered content repository to store data that is referenced by standalone server configurations, such as deployments and deployment overlays, migration of this data merely consists of finding and copying the content from the source server to the target server.

     INFO  --- Migrating standalone server...

     INFO  Source's standalone content migrated.

Next, the tool scans the source server for standalone server configurations files and prints the results in the console.

     INFO  Source's standalone configurations found: [standalone-full-ha.xml, standalone-full.xml, standalone-ha.xml, standalone.xml]

If you run the migration tool in `non-interactive` mode, the JBoss Server Migration Tool migrates all listed configuration files.

If you run the migration tool in `interactive` mode, which is the default, you are presented with the following prompt.

    Migrate all configurations?
    yes/no?

- If you reply yes, all listed configuration files are migrated.

- If you reply no, you receive a prompt asking to confirm the migration, for each listed configuration file:

      Migrate configuration standalone-full-ha.xml ?
      yes/no? y

### 3.2. Customizing the Migration of the Standalone Configuration

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

Property Name | Property Description
--- | ---
`standalone.skip` | If set to `true`, the tool skips the entire standalone server migration.
`server.source.standalone.serverDir` | Defines an alternative path for the source’s standalone server directory. Please note that a non absolute path is considered relative to the source server’s base directory, and if not defined this property defaults to "standalone".
`server.source.standalone.configDir` | Defines an alternative path for the source’s standalone server configuration directory. Please note that a non absolute path is considered relative to the source’s standalone server directory, and if not defined this property defaults to "configuration".
`server.source.standalone.configFiles` | Specifies the file names of the source standalone server configurations to be migrated.
`server.target.standalone.serverDir` | Defines an alternative path for the target’s standalone server directory. Please note that a non absolute path is considered relative to the target server’s base directory, and if not defined this property defaults to "standalone".
`server.target.standalone.configDir` | Defines an alternative path for the target’s standalone server configuration directory. Please note that a non absolute path is considered relative to the target’s standalone server directory, and if not defined this property defaults to "configuration".

The environment configuration can be customized in one of the following ways:

- You can 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 include the above properties in your own custom properties file, and then pass the file on the command line using the `--environment` argument.

- You can pass the information on the command line using a system property. The environment property names must be prefixed with `jboss.server.migration.`, for example:

      -Djboss.server.migration.server.source.standalone.serverDir="standalone"

### 3.3. Standalone Configuration File Migration

When migrating the standalone server configuration, the JBoss Server Migration Tool first copies the source configuration files to the target server. It then updates the configuration to not only work correctly in the target server, but also to take advantage of the target server’s new functionality.

#### 3.3.1. Remove Unsupported Subsystems

All subsystems, and related extensions, which are not supported by JBoss EAP 7.2, are automatically removed from a migrated configuration.

Note | A subsystem installed in WildFly 10.0 by the user, is also considered as unsupported by JBoss EAP 7.2, and by default will not be migrated.

The console logs the configuration namespaces, and extension modules, of unsupported subsystems removed from the server configuration being migrated:

     INFO  Unsupported extensions removed: [com.example.extension1]
     INFO  Unsupported subsystems removed: [urn:example:domain:subsystem1:1.0]

It is possible to override the default behaviour and indicate subsystems and extensions which should always, or never, be migrated, by configuring the following environment properties:

Property Name | Property Description
--- | ---
`extensions.excludes` | A list with the module names of extensions that should never be migrated.
`extensions.includes` | A list with the module names of extensions that should always be migrated.
`subsystems.excludes` | A list with the XML Namespaces, without the version part, of subsystems that should never be migrated.
`subsystems.includes` | A list with the XML Namespaces, without the version part, of subsystems that should always be migrated.

The environment configuration can be customized in one of the following ways:

- You can configure the properties in the tool’s `config/environment.properties` file:

      extensions.excludes=com.example.extension1
      extensions.includes=com.example.extension2,com.example.extension3
      subsystems.excludes=urn:example:domain:subsystem1
      subsystems.includes=urn:example:domain:subsystem2,urn:example:domain:subsystem3

- You can include the above properties in your own custom properties file, and then pass the file on the command line using the `--environment` argument.

- You can pass the information on the command line using a system property. The environment property names must be prefixed with `jboss.server.migration.`, for example:

      -Djboss.server.migration.extensions.excludes="com.example.extension1" -Djboss.server.migration.subsystems.excludes="urn:example:domain:subsystem1"

#### 3.3.2. Migrate Referenced Modules

A migrated configuration may reference and depend on a module that is not installed on the target server. The tool automatically migrates the referenced modules, and their dependent modules as well.

A module is migrated when it is 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 an Object Factory module

- A `messaging` subsystem configuration, as JMS Bridge module

- A `vault` configuration

- An extension not installed in the target server

The console logs a message noting the module ID for any module that is migrated, for example:

    INFO  Module cmtool.security-realms:main migrated.
    INFO  Module cmtool.datasources:main migrated.
    INFO  Module cmtool.ee1:main migrated.
    INFO  Module cmtool.ee2:main migrated.
    INFO  Module cmtool.naming:main migrated.

Tip | It is possible to exclude the migration of specific modules by specifying the id(s) in the environment property named `modules.excludes`.

#### 3.3.3. Migrate Referenced Paths

A migrated configuration may reference paths, i.e. files and directories, which may need to be migrated to the target server.

A referenced path is migrated only if it’s not an absolute path, and such migration consists in copying the resource to such path, but relative to the migrated configuration, in the target server.

The tools automatically migrates the following paths references:

- `Vault` keystore and encrypted file’s directory.

The console logs a message noting the migrations of paths:

     INFO  Referenced paths migrated.

If you prefer, you can configure the environment properties to customize the migration of referenced paths.

Property Name | Property Description
--- | ---
`paths.migrate-paths-requested-by-configuration.vault.skip` | If set to `true`, the tool skips the migration of `Vault` referenced paths.

#### 3.3.4. Update the infinispan Subsystem

The JBoss Server Migration Tool makes the following updates to the infinispan subsystem configuration to better match the JBoss EAP 7.2 default configurations.

- Fixes the module name in the `hibernate` cache configuration.

- Adds `concurrent` cache to the `web` cache container, which is present in the JBoss EAP 7.2 default configuration.

By default, the tool automatically updates any infinispan subsystem configuration to include these changes. If you prefer, you can configure the environment properties to customize the process of updating the infinispan subsystem configuration.

Property Name | Property Description
--- | ---
`subsystem.infinispan.update.skip` | If set to `true`, the tool skips the update of the infinispan subsystem.
`subsystem.infinispan.update.fix-hibernate-cache-module-name.skip` | If set to `true`, the tool does not fix the module name in the `hibernate` cache configuration.
`subsystem.infinispan.update.update-infinispan-web-cache.skip` | If set to `true`, the tool does not adds `concurrent` cache to the `web` cache container.

Upon successful migration of a undertow subsystem configuration, you should see the following message in the console:

     INFO  Subsystem undertow updated.

#### 3.3.5. Update the JGroups Subsystem

The JBoss Server Migration Tool does the following updates to any jgroups subsystem configuration found while migrating a server configuration:

- Replaces protocol `FRAG2` with `FRAG3`.

If you prefer, you can set the `subsystem.jgroups.update.skip` environment property to `true` to skip automatic update of the jgroups subsystem configuration.

Upon successful migration of the jgroups subsystem configuration, you should see the following message in the console:

     INFO  Subsystem jgroups updated.

#### 3.3.6. Update the undertow Subsystem

The JBoss Server Migration Tool applies the following changes to undertow subsystem configurations.

- Sets the default `HTTPS` listener.

- Adds support for `HTTP2`.

- Removes the `Server` response header.

- Removes the `X-Powered-By` response header.

- Sets the default `HTTP Invoker`.

By default, the tool automatically updates any undertow subsystem configuration to include these changes. If you prefer, you can configure the environment properties to customize the process of updating the undertow subsystem configuration.

Property Name | Property Description
--- | ---
`subsystem.undertow.update.skip` | If set to `true`, the tool skips the update of the undertow subsystem.
`subsystem.undertow.update.add-undertow-https-listener.skip` | If set to `true`, the tool does not sets the default `HTTPS` listener.
`subsystem.undertow.update.enable-http2.skip` | If set to `true`, the tool does not add support for `HTTP2`.
`subsystem.undertow.update.remove-response-header.server-header.skip` | If set to `true`, the tool does not removes the `Server` response header.
`subsystem.undertow.update.remove-response-header.x-powered-by-header.skip` | If set to `true`, the tool does not removes the `X-Powered-By` response header.
`subsystem.undertow.update.add-http-invoker.skip` | If set to `true`, the tool does not sets the default `HTTP Invoker`.

Upon successful migration of a undertow subsystem configuration, you should see the following message in the console:

     INFO  Subsystem undertow updated.

#### 3.3.7. Add the core-management Subsystem

The JBoss EAP 7.2 core-management subsystem provides WildFly Core management-related resources, which previously were configured on its kernel, for instance the server configuration’s changes history feature.

Its default configuration is automatically added to the migrated configuration file, unless the environment property named `subsystem.core-management.add.skip` is set to `true`.

The subsystem and related extension are added without any interaction required by the user. Upon successful addition of the core-management subsystem configuration, you should see the following messages in the console:

     INFO  Subsystem core-management added.

#### 3.3.8. Add the discovery Subsystem

TODO

Its default configuration is automatically added to the migrated configuration file, unless the environment property named `subsystem.discovery.add.skip` is set to `true`.

The subsystem and related extension are added without any interaction required by the user. Upon successful addition of the discovery subsystem configuration, you should see the following messages in the console:

     INFO  Subsystem discovery added.

#### 3.3.9. Add the ee-security Subsystem

TODO

Its default configuration is automatically added to the migrated configuration file, unless the environment property named `subsystem.ee-security.add.skip` is set to `true`.

The subsystem and related extension are added without any interaction required by the user. Upon successful addition of the ee-security subsystem configuration, you should see the following messages in the console:

     INFO  Subsystem ee-security added.

#### 3.3.10. Add the elytron Subsystem

The JBoss EAP 7.2 elytron subsystem provides Elytron, a new security framework, which will completely replace the combination of PicketBox and JAAS as the unified client and server security mechanism.

Its default configuration is automatically added to the migrated configuration file, unless the environment property named `subsystem.elytron.add.skip` is set to `true`.

The subsystem and related extension are added without any interaction required by the user. Upon successful addition of the elytron subsystem configuration, you should see the following messages in the console:

     INFO  Subsystem elytron added.

#### 3.3.11. Add the microprofile-config-smallrye Subsystem

The JBoss EAP 7.2 microprofile-config-smallrye subsystem provides support for Eclipse MicroProfile Config.

Its default configuration is automatically added to the migrated configuration file, unless the environment property named `subsystem.microprofile-config-smallrye.add.skip` is set to `true`.

The subsystem and related extension are added without any interaction required by the user. Upon successful addition of the microprofile-config-smallrye subsystem configuration, you should see the following messages in the console:

     INFO  Subsystem microprofile-config-smallrye added.

#### 3.3.12. Add the microprofile-health-smallrye Subsystem

The JBoss EAP 7.2 microprofile-health-smallrye subsystem provides support for Eclipse MicroProfile Health.

Its default configuration is automatically added to the migrated configuration file, unless the environment property named `subsystem.microprofile-health-smallrye.add.skip` is set to `true`.

The subsystem and related extension are added without any interaction required by the user. Upon successful addition of the microprofile-health-smallrye subsystem configuration, you should see the following messages in the console:

     INFO  Subsystem microprofile-health-smallrye added.

#### 3.3.13. Add the microprofile-opentracing-smallrye Subsystem

The JBoss EAP 7.2 microprofile-opentracing-smallrye subsystem provides support for Eclipse MicroProfile OpenTracing.

Its default configuration is automatically added to the migrated configuration file, unless the environment property named `subsystem.microprofile-opentracing-smallrye.add.skip` is set to `true`.

The subsystem and related extension are added without any interaction required by the user. Upon successful addition of the microprofile-opentracing-smallrye subsystem configuration, you should see the following messages in the console:

     INFO  Subsystem microprofile-opentracing-smallrye added.

#### 3.3.14. Add Socket Binding Multicast Address Expressions

The JBoss EAP 7.2 default configurations uses value expressions in the `multicast-address` attribute of `modcluster` socket bindings, and the migration tool automatically adds such value expressions to migrated configurations.

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

    INFO  Socket binding's multicast address expressions added.

Note | 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`.

#### 3.3.15. Migrate Compatible Security Realms

Because the JBoss EAP 7.2 security realms configuration is fully compatible with the WildFly 10.0 security realms configuration, they require no update by the JBoss Server Migration Tool. However, if the properties files are not referenced using an absolute path, the tool copies them to the path expected by the migrated configuration file.

This process is fully automated and requires no interaction by the user. To skip the security realms migration, set the `security-realms.migrate-properties.skip` environment property to `true`.

Upon successful migration of the security realms configuration, you should see the following messages in the console:

    INFO  Security realms migrated.

#### 3.3.16. Add default SSL Server Identity to ApplicationRealm

JBoss EAP 7.2 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 configuration update:

    INFO  Security realm ApplicationRealm SSL server identity configured.

Note | 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`.

#### 3.3.17. Migrate Deployments

The JBoss Server Migration Tool, when migrating a configuration, may also migrate:

- Deployments it references, also known as persistent deployments.

- Deployments found in directories monitored by its deployment scanners.

- Deployment Overlays it references.

Warning | The migration of a deployment or deployment overlay merely consists of installing related file resources on the target server, and possibly updating the migrated configuration. The tool will not assert if these resources are compatible with the target server, which means that a migrated deployment might not work as expected, or might not work at all. Red Hat recommends that you use Red Hat Application Migration Toolkit to analyze a deployment with respect to compatibility among different JBoss servers.

Note | If you run the migration tool in `non-interactive` mode, by default the JBoss Server Migration Tool will not migrate any deployments and overlays. To migrate deployments the environment property `deployments.migrate-deployments.skip` should be set as `false`.

##### Migrate Persistent Deployments

When migrating a configuration, the tool searches for references to deployments persisted in the source server, and prints the names of the deployments found in the console, e.g.:

    INFO  Persistent deployments found: [cmtool-helloworld3.war, cmtool-helloworld4.war, cmtool-helloworld2.war, cmtool-helloworld1.war]

If you run the migration tool in `interactive` mode, you then see the following prompt:

    This tool is not able to assert if persistent deployments found are compatible with the target server, skip persistent deployments migration?
    yes/no?

- If you reply yes, or y, the all deployment references are removed from the migrated configuration, i.e. the deployments will not be migration.

- If you reply no, or n, you receive an additional prompt asking if all deployments should be the migrated:

      Migrate all persistent deployments found?
      yes/no?

  - If you reply yes, or y, all deployments are migrated.

  - If you reply no, or n, you receive a prompt asking to confirm the migration for each referenced deployment:

        Migrate persistent deployment 'cmtool-helloworld3.war'?
        yes/no?

    - If you reply yes, or y, the deployment is migrated.

    - If you reply no, or n, the deployment reference is removed from the migrated configuration, i.e. the deployment is not migrated.

          INFO  Persistent deployment cmtool-helloworld3.war migrated.

If you run the migration tool in `non-interactive` mode, the JBoss Server Migration Tool will migrate or not migrate `all` persistent deployments, depending on the environment configuration. Persistent deployments are migrated only if none of the following environment properties is set as `true`:

- deployments.migrate-deployments.skip

- deployments.migrate-persistent-deployments.skip

##### Migrate Deployment Scanner Deployments

Deployment scanners monitor a directory for new files and manage their deployment automatically or through special deployment marker files, and the migration tool, when migrating the server configuration, first searches for any configured deployment scanners, and then for each scanner found, searches its monitored directories for deployments marked as `deployed`.

A list with the names of deployments found are printed to the console, for instance:

    INFO  Non-persistent deployments found in /wildfly/standalone/deployments: [cmtool-helloworld5.war, cmtool-helloworld6.war]

If you run the migration tool in `interactive` mode, you then see the following prompt:

    This tool is not able to assert if the non-persistent deployments found are compatible with the target server, skip scanner's deployments migration?
    yes/no?

- If you reply yes, or y, all deployments are not migrated.

- If you reply no, or n, you receive an additional prompt asking if all deployments should be the migrated:

      Migrate all non-persistent deployments found?
      yes/no?

  - If you reply yes, or y, all deployments are migrated.

        INFO  Non-persistent deployment cmtool-helloworld5.war migrated.
        INFO  Non-persistent deployment cmtool-helloworld6.war migrated.

  - If you reply no, or n, you receive a prompt asking to confirm the migration for each deployment:

        Migrate non-persistent deployment cmtool-helloworld5.war?
        yes/no?

    - If you reply no, or n, the deployment is not migrated.

    - If you reply yes, or y, the deployment is migrated.

      INFO  Non-persistent deployment cmtool-helloworld5.war migrated.

If you run the migration tool in `non-interactive` mode, the JBoss Server Migration Tool will migrate or not migrate `all` deployments found, depending on the environment configuration. Persistent deployments are migrated only if none of the following environment properties is set as `true`:

- deployments.migrate-deployments.skip

- deployments.migrate-deployment-scanner-deployments.skip

##### Migrate Deployment Overlays

The migration of deployment overlays is a fully automated process. The migration tool searches for deployment overlays referenced in the standalone server configuration. It then migrates those that are linked to deployments that were migrated.

The migration tool prints a message to the console for each deployment overlay that is migrated.

    INFO  Deployment overlay overlay1 migrated.
    INFO  Deployment overlay overlay2 migrated.

## 4. Managed Domain Migration

### 4.1. Managed Domain Processing Overview

When tasked to migrate managed domains, the JBoss Server Migration Tool migrates the domain and host configuration files and their related domain content from the source server to the target server. This migration task is optional.

If you run the migration tool in `interactive` mode, which is the default, you are prompted to confirm its execution.

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

- If you reply with yes or y, the domain migration proceeds.

- If you reply with no or n, the domain migration is skipped.

If you choose to proceed, the tool begins migrating the domain content of the source server. A cyphered repository used to store data, such as deployments and deployment overlays, that are referenced by the source server’s domain and host configurations. Because the source and target servers use a similar content repository, the migration of this data merely consists of finding and copying the content between the servers.

     INFO  --- Migrating managed domain...

     INFO  Source's domain content migrated.

Next, the migration tool scans the source server for domain configuration files and prints the results in the console.

     INFO  Source's domain configurations found: [cmtool-domain.xml, domain.xml]

If you run the migration tool `non-interactive` mode, the JBoss Server Migration Tool migrates all listed domain configuration files.

If you run the migration tool in `interactive` mode, which is the default, you are presented with the following prompt.

    Migrate all configurations?
    yes/no?

- If you reply with yes, all listed configuration files are migrated.

- If you reply with no, you are prompted to confirm the migration for each listed configuration file:

      Migrate configuration cmtool-domain.xml ?
      yes/no? y

Next, the migration tool scans the source server for host configurations files and prints the results in the console.

     INFO  Source's host configurations found: [host-master.xml, host-slave.xml, host.xml]

If you run the migration tool in `non-interactive` mode, the JBoss Server Migration Tool migrates all listed host configuration files.

If you run the migration tool in `interactive` mode, which is the default, you are presented with the following prompt.

    Migrate all configurations?
    yes/no?

- If you reply with yes, all listed configuration files are migrated.

- If you reply with no, you are prompted to confirm the migration for each listed configuration file:

      Migrate configuration host-master.xml ?
      yes/no? y

### 4.2. Customizing the Migration of the Managed Domain Configuration

Managed domain migration can be customized by configuring the following environment properties:

Property Name | Property Description
--- | ---
`domain.skip` | If set to `true`, the tool skips the entire domain migration.
`server.source.domain.domainDir` | Defines an alternative path for the source server’s domain directory. Please note that a non absolute path is considered relative to the source server’s base directory, and if not defined this property defaults to "domain".
`server.source.domain.configDir` | Defines an alternative path for the source server’s domain configuration directory. Please note that a non absolute path is considered relative to the source server’s domain directory, and if not defined this property defaults to "configuration".
`server.source.domain.hostConfigFiles` | Specifies a comma delimited list of the file names of the source server host configurations that are to be migrated.
`server.target.domain.domainDir` | Defines an alternative path for the target server’s domain directory. Please note that a non absolute path is considered relative to the target server’s base directory, and if not defined this property defaults to "domain".
`server.target.domain.configDir` | Defines an alternative path for the target server’s domain configuration directory. Please note that a non absolute path is considered relative to the target server’s domain directory, and if not defined this property defaults to "configuration".

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

- You can configure the tool’s `config/environment.properties` 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 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. In this case, all environment property names should be prefixed with `jboss.server.migration.`.

### 4.3. Domain Configuration File Migration

When migrating the domain configuration, the JBoss Server Migration Tool first copies the source configuration files to the target server. It then updates the configuration to not only work correctly in the target server, but also to take advantage of the target server’s new functionality.

#### 4.3.1. Remove Unsupported Subsystems

All subsystems, and related extensions, which are not supported by JBoss EAP 7.2, are automatically removed from a migrated configuration.

Note | A subsystem installed in WildFly 10.0 by the user, is also considered as unsupported by JBoss EAP 7.2, and by default will not be migrated.

The console logs the configuration namespaces, and extension modules, of unsupported subsystems removed from the server configuration being migrated:

     INFO  Unsupported extensions removed: [com.example.extension1]
     INFO  Unsupported subsystems removed: [urn:example:domain:subsystem1:1.0]

It is possible to override the default behaviour and indicate subsystems and extensions which should always, or never, be migrated, by configuring the following environment properties:

Property Name | Property Description
--- | ---
`extensions.excludes` | A list with the module names of extensions that should never be migrated.
`extensions.includes` | A list with the module names of extensions that should always be migrated.
`subsystems.excludes` | A list with the XML Namespaces, without the version part, of subsystems that should never be migrated.
`subsystems.includes` | A list with the XML Namespaces, without the version part, of subsystems that should always be migrated.

The environment configuration can be customized in one of the following ways:

- You can configure the properties in the tool’s `config/environment.properties` file:

      extensions.excludes=com.example.extension1
      extensions.includes=com.example.extension2,com.example.extension3
      subsystems.excludes=urn:example:domain:subsystem1
      subsystems.includes=urn:example:domain:subsystem2,urn:example:domain:subsystem3

- You can include the above properties in your own custom properties file, and then pass the file on the command line using the `--environment` argument.

- You can pass the information on the command line using a system property. The environment property names must be prefixed with `jboss.server.migration.`, for example:

      -Djboss.server.migration.extensions.excludes="com.example.extension1" -Djboss.server.migration.subsystems.excludes="urn:example:domain:subsystem1"

#### 4.3.2. Migrate Referenced Modules

A migrated configuration may reference and depend on a module that is not installed on the target server. The tool automatically migrates the referenced modules, and their dependent modules as well.

A module is migrated when it is 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 an Object Factory module

- A `messaging` subsystem configuration, as JMS Bridge module

- A `vault` configuration

- An extension not installed in the target server

The console logs a message noting the module ID for any module that is migrated, for example:

    INFO  Module cmtool.security-realms:main migrated.
    INFO  Module cmtool.datasources:main migrated.
    INFO  Module cmtool.ee1:main migrated.
    INFO  Module cmtool.ee2:main migrated.
    INFO  Module cmtool.naming:main migrated.

Tip | It is possible to exclude the migration of specific modules by specifying the id(s) in the environment property named `modules.excludes`.

#### 4.3.3. Migrate Referenced Paths

A migrated configuration may reference paths, i.e. files and directories, which may need to be migrated to the target server.

A referenced path is migrated only if it’s not an absolute path, and such migration consists in copying the resource to such path, but relative to the migrated configuration, in the target server.

The tools automatically migrates the following paths references:

- `Vault` keystore and encrypted file’s directory.

The console logs a message noting the migrations of paths:

     INFO  Referenced paths migrated.

If you prefer, you can configure the environment properties to customize the migration of referenced paths.

Property Name | Property Description
--- | ---
`paths.migrate-paths-requested-by-configuration.vault.skip` | If set to `true`, the tool skips the migration of `Vault` referenced paths.

#### 4.3.4. Update the infinispan Subsystem

The JBoss Server Migration Tool makes the following updates to the infinispan subsystem configuration to better match the JBoss EAP 7.2 default configurations.

- Fixes the module name in the `hibernate` cache configuration.

- Adds `concurrent` cache to the `web` cache container, which is present in the JBoss EAP 7.2 default configuration.

By default, the tool automatically updates any infinispan subsystem configuration to include these changes. If you prefer, you can configure the environment properties to customize the process of updating the infinispan subsystem configuration.

Property Name | Property Description
--- | ---
`subsystem.infinispan.update.skip` | If set to `true`, the tool skips the update of the infinispan subsystem.
`subsystem.infinispan.update.fix-hibernate-cache-module-name.skip` | If set to `true`, the tool does not fix the module name in the `hibernate` cache configuration.
`subsystem.infinispan.update.update-infinispan-web-cache.skip` | If set to `true`, the tool does not adds `concurrent` cache to the `web` cache container.

Upon successful migration of a undertow subsystem configuration, you should see the following message in the console:

     INFO  Subsystem undertow updated.

#### 4.3.5. Update the JGroups Subsystem

The JBoss Server Migration Tool does the following updates to any jgroups subsystem configuration found while migrating a server configuration:

- Replaces protocol `FRAG2` with `FRAG3`.

If you prefer, you can set the `subsystem.jgroups.update.skip` environment property to `true` to skip automatic update of the jgroups subsystem configuration.

Upon successful migration of the jgroups subsystem configuration, you should see the following message in the console:

     INFO  Subsystem jgroups updated.

#### 4.3.6. Update the undertow Subsystem

The JBoss Server Migration Tool applies the following changes to undertow subsystem configurations.

- Sets the default `HTTPS` listener.

- Adds support for `HTTP2`.

- Removes the `Server` response header.

- Removes the `X-Powered-By` response header.

- Sets the default `HTTP Invoker`.

By default, the tool automatically updates any undertow subsystem configuration to include these changes. If you prefer, you can configure the environment properties to customize the process of updating the undertow subsystem configuration.

Property Name | Property Description
--- | ---
`subsystem.undertow.update.skip` | If set to `true`, the tool skips the update of the undertow subsystem.
`subsystem.undertow.update.add-undertow-https-listener.skip` | If set to `true`, the tool does not sets the default `HTTPS` listener.
`subsystem.undertow.update.enable-http2.skip` | If set to `true`, the tool does not add support for `HTTP2`.
`subsystem.undertow.update.remove-response-header.server-header.skip` | If set to `true`, the tool does not removes the `Server` response header.
`subsystem.undertow.update.remove-response-header.x-powered-by-header.skip` | If set to `true`, the tool does not removes the `X-Powered-By` response header.
`subsystem.undertow.update.add-http-invoker.skip` | If set to `true`, the tool does not sets the default `HTTP Invoker`.

Upon successful migration of a undertow subsystem configuration, you should see the following message in the console:

     INFO  Subsystem undertow updated.

#### 4.3.7. Add the core-management Subsystem

The JBoss EAP 7.2 core-management subsystem provides WildFly Core management-related resources, which previously were configured on its kernel, for instance the server configuration’s changes history feature.

Its default configuration is automatically added to the migrated configuration file, unless the environment property named `subsystem.core-management.add.skip` is set to `true`.

The subsystem and related extension are added without any interaction required by the user. Upon successful addition of the core-management subsystem configuration, you should see the following messages in the console:

     INFO  Subsystem core-management added.

#### 4.3.8. Add the discovery Subsystem

TODO

Its default configuration is automatically added to the migrated configuration file, unless the environment property named `subsystem.discovery.add.skip` is set to `true`.

The subsystem and related extension are added without any interaction required by the user. Upon successful addition of the discovery subsystem configuration, you should see the following messages in the console:

     INFO  Subsystem discovery added.

#### 4.3.9. Add the ee-security Subsystem

TODO

Its default configuration is automatically added to the migrated configuration file, unless the environment property named `subsystem.ee-security.add.skip` is set to `true`.

The subsystem and related extension are added without any interaction required by the user. Upon successful addition of the ee-security subsystem configuration, you should see the following messages in the console:

     INFO  Subsystem ee-security added.

#### 4.3.10. Add the elytron Subsystem

The JBoss EAP 7.2 elytron subsystem provides Elytron, a new security framework, which will completely replace the combination of PicketBox and JAAS as the unified client and server security mechanism.

Its default configuration is automatically added to the migrated configuration file, unless the environment property named `subsystem.elytron.add.skip` is set to `true`.

The subsystem and related extension are added without any interaction required by the user. Upon successful addition of the elytron subsystem configuration, you should see the following messages in the console:

     INFO  Subsystem elytron added.

#### 4.3.11. Add the microprofile-config-smallrye Subsystem

The JBoss EAP 7.2 microprofile-config-smallrye subsystem provides support for Eclipse MicroProfile Config.

Its default configuration is automatically added to the migrated configuration file, unless the environment property named `subsystem.microprofile-config-smallrye.add.skip` is set to `true`.

The subsystem and related extension are added without any interaction required by the user. Upon successful addition of the microprofile-config-smallrye subsystem configuration, you should see the following messages in the console:

     INFO  Subsystem microprofile-config-smallrye added.

#### 4.3.12. Add the microprofile-opentracing-smallrye Subsystem

The JBoss EAP 7.2 microprofile-opentracing-smallrye subsystem provides support for Eclipse MicroProfile OpenTracing.

Its default configuration is automatically added to the migrated configuration file, unless the environment property named `subsystem.microprofile-opentracing-smallrye.add.skip` is set to `true`.

The subsystem and related extension are added without any interaction required by the user. Upon successful addition of the microprofile-opentracing-smallrye subsystem configuration, you should see the following messages in the console:

     INFO  Subsystem microprofile-opentracing-smallrye added.

#### 4.3.13. Add Socket Binding Multicast Address Expressions

The JBoss EAP 7.2 default configurations uses value expressions in the `multicast-address` attribute of `modcluster` socket bindings, and the migration tool automatically adds such value expressions to migrated configurations.

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

    INFO  Socket binding's multicast address expressions added.

Note | 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`.

#### 4.3.14. Add Load Balancer Profile

JBoss EAP 7.2 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.

    INFO  Profile load-balancer added.

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

#### 4.3.15. Add Host Excludes

A JBoss EAP 7.2 domain controller may have functionality that is not supported by hosts running on older version, and it’s through its "host-excludes" configuration that such functionality is filtered.

The JBoss Migration Tool, when migrating a domain controller configuration, will add/replace the source’s "host-excludes" configuration, with the target’s one.

The configuration changes are fully automated, and upon successful completion of the configuration, you should see the following messages in the console:

      INFO  Host-excludes configuration added.

#### 4.3.16. Migrate Deployments

The JBoss Server Migration Tool, when migrating a configuration, may also migrate:

- Deployments it references, also known as persistent deployments.

- Deployment Overlays it references.

Warning | The migration of a deployment or deployment overlay merely consists of installing related file resources on the target server, and possibly updating the migrated configuration. The tool will not assert if these resources are compatible with the target server, which means that a migrated deployment might not work as expected, or might not work at all. Red Hat recommends that you use Red Hat Application Migration Toolkit to analyze a deployment with respect to compatibility among different JBoss servers.

Note | If you run the migration tool in `non-interactive` mode, by default the JBoss Server Migration Tool will not migrate any deployments and overlays. To migrate deployments the environment property `deployments.migrate-deployments.skip` should be set as `false`.

##### Migrate Persistent Deployments

When migrating a configuration, the tool searches for references to deployments persisted in the source server, and prints the names of the deployments found in the console, e.g.:

    INFO  Persistent deployments found: [cmtool-helloworld3.war, cmtool-helloworld4.war, cmtool-helloworld2.war, cmtool-helloworld1.war]

If you run the migration tool in `interactive` mode, you then see the following prompt:

    This tool is not able to assert if persistent deployments found are compatible with the target server, skip persistent deployments migration?
    yes/no?

- If you reply yes, or y, the all deployment references are removed from the migrated configuration, i.e. the deployments will not be migration.

- If you reply no, or n, you receive an additional prompt asking if all deployments should be the migrated:

      Migrate all persistent deployments found?
      yes/no?

  - If you reply yes, or y, all deployments are migrated.

  - If you reply no, or n, you receive a prompt asking to confirm the migration for each referenced deployment:

        Migrate persistent deployment 'cmtool-helloworld3.war'?
        yes/no?

    - If you reply yes, or y, the deployment is migrated.

    - If you reply no, or n, the deployment reference is removed from the migrated configuration, i.e. the deployment is not migrated.

          INFO  Persistent deployment cmtool-helloworld3.war migrated.

If you run the migration tool in `non-interactive` mode, the JBoss Server Migration Tool will migrate or not migrate `all` persistent deployments, depending on the environment configuration. Persistent deployments are migrated only if none of the following environment properties is set as `true`:

- deployments.migrate-deployments.skip

- deployments.migrate-persistent-deployments.skip

##### Migrate Deployment Overlays

The migration of deployment overlays is a fully automated process. The migration tool searches for deployment overlays referenced in the standalone server configuration. It then migrates those that are linked to deployments that were migrated.

The migration tool prints a message to the console for each deployment overlay that is migrated.

    INFO  Deployment overlay overlay1 migrated.
    INFO  Deployment overlay overlay2 migrated.

### 4.4. Host Configuration File Migration

When migrating the host configuration, the JBoss Server Migration Tool first copies the source configuration files to the target server. It then updates the configuration to not only work correctly in the target server, but also to take advantage of the target server’s new functionality.

#### 4.4.1. Migrate Referenced Modules

A migrated configuration may reference and depend on a module that is not installed on the target server. The tool automatically migrates the referenced modules, and their dependent modules as well.

A module is migrated when it is referenced by:

- A `security-realm` configuration, as plug-in(s) module

The console logs a message noting the module ID for any module that is migrated, for example:

    INFO  Module cmtool.security-realms:main migrated.

Tip | It is possible to exclude the migration of specific modules by specifying the id(s) in the environment property named `modules.excludes`.

#### 4.4.2. Migrate Referenced Paths

A migrated configuration may reference paths, i.e. files and directories, which may need to be migrated to the target server.

A referenced path is migrated only if it’s not an absolute path, and such migration consists in copying the resource to such path, but relative to the migrated configuration, in the target server.

The tools automatically migrates the following paths references:

- `Vault` keystore and encrypted file’s directory.

The console logs a message noting the migrations of paths:

     INFO  Referenced paths migrated.

If you prefer, you can configure the environment properties to customize the migration of referenced paths.

Property Name | Property Description
--- | ---
`paths.migrate-paths-requested-by-configuration.vault.skip` | If set to `true`, the tool skips the migration of `Vault` referenced paths.

#### 4.4.3. Add the core-management Subsystem

The JBoss EAP 7.2 core-management subsystem provides WildFly Core management-related resources, which previously were configured on its kernel, for instance the server configuration’s changes history feature.

Its default configuration is automatically added to the migrated configuration file, unless the environment property named `subsystem.core-management.add.skip` is set to `true`.

The subsystem and related extension are added without any interaction required by the user. Upon successful addition of the core-management subsystem configuration, you should see the following messages in the console:

     INFO  Subsystem core-management added.

#### 4.4.4. Add the elytron Subsystem

The JBoss EAP 7.2 elytron subsystem provides Elytron, a new security framework, which will completely replace the combination of PicketBox and JAAS as the unified client and server security mechanism.

Its default configuration is automatically added to the migrated configuration file, unless the environment property named `subsystem.elytron.add.skip` is set to `true`.

The subsystem and related extension are added without any interaction required by the user. Upon successful addition of the elytron subsystem configuration, you should see the following messages in the console:

     INFO  Subsystem elytron added.

#### 4.4.5. Migrate Compatible Security Realms

Because the JBoss EAP 7.2 security realms configuration is fully compatible with the WildFly 10.0 security realms configuration, they require no update by the JBoss Server Migration Tool. However, if the properties files are not referenced using an absolute path, the tool copies them to the path expected by the migrated configuration file.

This process is fully automated and requires no interaction by the user. To skip the security realms migration, set the `security-realms.migrate-properties.skip` environment property to `true`.

Upon successful migration of the security realms configuration, you should see the following messages in the console:

    INFO  Security realms migrated.

#### 4.4.6. Add default SSL Server Identity to ApplicationRealm

JBoss EAP 7.2 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 configuration update:

    INFO  Security realm ApplicationRealm SSL server identity configured.

Note | 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`.