Red Hat Summit Red Hat SummitSupportConsoleDéveloppeursCommencer un essaiContact

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

Chapter 6. Migrating JBoss EAP 6.4 Configurations to JBoss EAP 7.4

By default, the JBoss Server Migration Tool performs the following tasks when migrating a standalone server configuration from JBoss EAP 6.4 to JBoss EAP 7.4.

6.1.1. Remove Unsupported Subsystems
Copier lien

The following JBoss EAP 6.4 subsystems are not supported by JBoss EAP 7.4 :

Expand
Subsystem NameConfiguration NamespaceExtension Module

cmp

urn:jboss:domain:cmp:*

org.jboss.as.cmp

configadmin

urn:jboss:domain:configadmin:*

org.jboss.as.configadmin

jaxr

urn:jboss:domain:jaxr:*

org.jboss.as.jaxr

osgi

urn:jboss:domain:osgi:*

org.jboss.as.osgi

threads

urn:jboss:domain:threads:*

org.jboss.as.threads

The JBoss Server Migration Tool removes all unsupported subsystem configurations and extensions from migrated server configurations. The tool logs each subsystem and extension to its log file and to the console as it is removed.

To skip removal of the unsupported subsystems, set the subsystems.remove-unsupported-subsystems.skip environment property to true.

You can override the default behavior of the JBoss Server Migration Tool and specify which subsystems and extensions should be included or excluded during the migration using the following environment properties.

Expand
Property NameProperty Description

extensions.excludes

A list of module names of extensions that should never be migrated, for example, com.example.extension1,com.example.extension3.

extensions.includes

A list of module names of extensions that should always be migrated, for example, com.example.extension2,com.example.extension4.

subsystems.excludes

A list of subsystem namespaces, stripped of the version, that should never be migrated, for example, urn:jboss:domain:logging, urn:jboss:domain:ejb3.

subsystems.includes

A list of subsystem namespaces, stripped of the version, that should always be migrated, for example, urn:jboss:domain:security, urn:jboss:domain:ee.

6.1.2. Migrate Referenced Modules
Copier lien

A configuration that is migrated from a source server to a target server might reference or depend on a module that is not installed on the target server. The JBoss Server Migration Tool detects this and automatically migrates the referenced modules, plus their dependent modules, from the source server to the target server.

A module referenced by a standalone server configuration is migrated using the following process.

  • A module referenced by a security realm configuration is migrated as a plug-in module.
  • A module referenced by the datasource subsystem configuration is migrated as a datasource driver module.
  • A module referenced by the ee subsystem configuration is migrated as a global module.
  • A module referenced by the naming subsystem configuration is migrated as an object factory module.
  • A module referenced by the messaging subsystem configuration is migrated as a Jakarta Messaging bridge module.
  • A module referenced by a vault configuration is migrated to the new configuration.
  • Any extension that is not installed on the target configuration is migrated to the target server configuration.

The console logs a message noting the module ID for any module that is migrated. It is possible to exclude the migration of specific modules by specifying the module ID in the modules.excludes environment property. See Configuring the Migration of Modules for more information.

6.1.3. Migrate Referenced Paths
Copier lien

A configuration that is migrated from a source server to a target server might reference or depend on file paths and directories that must also be migrated to the target server. The JBoss Server Migration Tool does not migrate absolute path references. It only migrates files or directories that are configured as relative to the source configuration. The console logs a message noting each path that is migrated.

The JBoss Server Migration Tool automatically migrates the following path references:

  • Vault keystore and encrypted file’s directory.

To skip the migration of referenced paths, set the paths.migrate-paths-requested-by-configuration.vault.skip environment property to true.

6.1.4. Migrate the Jacorb Subsystem
Copier lien

The jacorb subsystem is deprecated in JBoss EAP 7.4 and is replaced by the iiop-openjdk subsystem. By default, the JBoss Server Migration Tool automatically migrates the jacorb subsystem configuration to its replacement iiop-openjdk subsystem configuration and logs the results to its log file and to the console.

To skip the automatic migration to the iiop-openjdk subsystem configuration, set the subsystem.jacorb.migrate.skip environment property value to true.

6.1.5. Migrate the Web Subsystem
Copier lien

The web subsystem is deprecated in JBoss EAP 7.4 and is replaced by the undertow subsystem. By default, the JBoss Server Migration Tool automatically migrates the web subsystem configuration to its replacement undertow subsystem configuration and logs the results to its log file and to the console.

To skip automatic migration of the web subsystem, set the subsystem.web.migrate.skip environment property value to true.

6.1.6. Migrate the Messaging Subsystem
Copier lien

The messaging subsystem is deprecated in JBoss EAP 7.4 and is replaced by the messaging-activemq subsystem. The JBoss Server Migration Tool automatically migrates the messaging subsystem configuration to its replacement messaging-activemq subsystem configuration and logs the results to its log file and to the console.

To skip automatic migration of the messaging subsystem, set the subsystem.messaging.migrate.skip environment property value to true.

6.1.7. Update the Infinispan Subsystem
Copier lien

The JBoss Server Migration Tool updates the infinispan subsystem configuration to better align with the default JBoss EAP 7.4 configurations.

  • It adds the Jakarta Enterprise Beans cache container, which is present in the JBoss EAP 7.4 default configuration, to configurations where it is not already included.
  • It adds the server cache container, which is present in the JBoss EAP 7.4 default configuration.
  • It updates the module name in the Hibernate cache container configuration.
  • It adds the concurrent cache to the web cache container, which is present in the JBoss EAP 7.4 default configuration.

The JBoss Server Migration Tool automatically updates the infinispan subsystem configuration and logs the results to its log file and to the console.

You can customize the update of the infinispan system by setting the following environment properties.

Expand
Property NameProperty Description

subsystem.infinispan.update.skip

If set to true, skip the update of the infinispan subsystem.

subsystem.infinispan.update.add-infinispan-ejb-cache.skip

If set to true, do not add the Jakarta Enterprise Beans cache container.

subsystem.infinispan.update.add-infinispan-server-cache.skip

If set to true, do not add the server cache container.

subsystem.infinispan.update.fix-hibernate-cache-module-name.skip

If set to true, do not update the module name in the Hibernate cache container configuration.

subsystem.infinispan.update-infinispan-web-cache

If set to true, do not add the concurrent cache to the web cache container configuration.

6.1.8. Update the EE Subsystem
Copier lien

The JBoss Server Migration Tool updates the ee subsystem to configure the Jakarta EE features supported in JBoss EAP 7.4.

  • It configures instances of Jakarta EE concurrency utilities, such as container-managed executors, that are present in the JBoss EAP 7.4 default configuration and logs the results to its log file and to the console.

  • It defines the default resources, such as the default datasource, that are present in default JBoss EAP 6.4 configuration. If the resources are not found, the tool lists all available resources in the configuration, and then provides a prompt to select a resource from the list or to provide the Java Naming and Directory Interface address of the resource that should be set as the default.

    Note

    Java Naming and Directory Interface names that are specified are assumed to be valid. Java Naming and Directory Interface names are not validated by the tool.

The JBoss Server Migration Tool automatically updates the ee subsystem configuration and logs the results to its log file and to the console.

You can customize the update of the ee system by setting the following environment properties.

Expand
Property NameProperty Description

subsystem.ee.update.skip

If set to true, skip the update of the ee subsystem.

subsystem.ee.update.setup-ee-concurrency-utilities.skip

If set to true, do not add the default instances of concurrency utilities.

subsystem.ee.update.setup-javaee7-default-bindings.skip

If set to true, do not set up Jakarta EE default resources.

subsystem.ee.update.setup-javaee7-default-bindings.defaultDataSourceName

Specifies the name of the default datasource to look for in the source configuration.

subsystem.ee.update.setup-javaee7-default-bindings.defaultDataSourceJndiName

Specifies the Java Naming and Directory Interface name for the default datasource.

subsystem.ee.update.setup-javaee7-default-bindings.defaultJmsConnectionFactoryName

Specifies the name of the default Jakarta Messaging connection factory.

subsystem.ee.update.setup-javaee7-default-bindings.defaultJmsConnectionFactoryJndiName

Specifies the Java Naming and Directory Interface name for the default Jakarta Messaging connection factory.

Configuring Concurrency Utilities in the EE Subsystem

If you choose to configure the Jakarta EE concurrency utilities, then the tool automatically configures the instances that are present in the default JBoss EAP 7.4 configurations and logs the results to its log file and to the console. 

INFO  [ServerMigrationTask#49] Default ContextService added to EE subsystem configuration.
INFO  [ServerMigrationTask#49] Default ManagedThreadFactory added to EE subsystem configuration.
INFO  [ServerMigrationTask#49] Default ManagedExecutorService added to EE subsystem configuration.
INFO  [ServerMigrationTask#49] Default ManagedScheduledExecutorService added to EE subsystem configuration.
Copy to Clipboard Toggle word wrap

Configuring Default Resources in the EE Subsystem

When defining the Jakarta EE default resources the tool automatically selects those that are present in the default JBoss EAP 7.4 configuration. 

INFO  [ServerMigrationTask#50] Java EE Default Datasource configured with Java Naming and Directory Interface and name java:jboss/datasources/ExampleDS.
Copy to Clipboard Toggle word wrap

If no default resource is found, the tool lists all resources that are available in the configuration, and then provides a prompt to select the default resource or to provide the Java Naming and Directory Interface address of the resource that should be set as the default.

The following is an example of the interaction that occurs when migrating a configuration file with an ExampleDS datasource. 

INFO  [ServerMigrationTask#22] Default datasource not found.
0. ExampleDS
1. Unconfigured data source, I want to enter the Java Naming and Directory Interface name...
Please select Java EE's Default Datasource: (0): 0
INFO  [ServerMigrationTask#22] Java EE Default Datasource configured with Java Naming and Directory Interface name java:jboss/datasources/ExampleDS.

Save this Java EE Default Datasource Java Naming and Directory Interface name and use it when migrating other config files?
yes/no? y
Copy to Clipboard Toggle word wrap
Note

If you run the JBoss Server Migration Tool in non-interactive mode and the expected JBoss EAP 6.4 default resources, such as the default Jakarta Messaging connection factory, are not available, the tool does not configure those resources.

6.1.9. Update the Jakarta Enterprise Beans Subsystem
Copier lien

The JBoss Server Migration Tool makes the following updates to the Jakarta Enterprise Beans subsystem to better align with the default JBoss EAP 7.4 configurations.

  • It updates the remote service configuration to reference the HTTP connector.
  • It configures the default-sfsb-passivation-disabled-cache attribute to use the default-sfsb-cache.
  • It replaces the legacy passivation store and cache configurations with the JBoss EAP 7.4 default values.

The JBoss Server Migration Tool automatically updates the Jakarta Enterprise Beans subsystem configuration and logs the results to its log file and to the console.

Upon successful update of the Jakarta Enterprise Beans subsystem configuration, the JBoss Server Migration Tool logs the results to its log file and to the console. 

 INFO  Subsystem ejb3 updated.
Copy to Clipboard Toggle word wrap

You can customize the update of the Jakarta Enterprise Beans subsystem by setting the following environment properties.

Expand
Property NameProperty Description

subsystem.ejb3.update.skip

If set to true, skip the update of the Jakarta Enterprise Beans subsystem.

subsystem.ejb3.update.add-infinispan-passivation-store-and-distributable-cache.skip

If set to true, do not replace the passivation-store and cache configurations.

subsystem.ejb3.update.setup-default-sfsb-passivation-disabled-cache.skip

If set to true, do not update the default-sfsb-passivation-disabled-cache configuration.

subsystem.ejb3.update.activate-ejb3-remoting-http-connector.skip

If set to true, do not update the ejb3 subsystem remoting configuration.

6.1.10. Update the JGroups Subsystem
Copier lien

The JBoss Server Migration Tool updates the jgroups subsystem to align with the JBoss EAP 7.4 configurations.

  • It replaces the MERGE2 protocol with MERGE3.
  • It replaces the FD protocol with FD_ALL.
  • It replaces the pbcast.NAKACK protocol with pbcast.NAKACK2.
  • It replaces the UNICAST2 protocol with UNICAST3.
  • It removes the RSVP protocol.
  • It replaces the FRAG2 protocol with the FRAG3 protocol.

Upon successful migration of the jgroups subsystem configuration, the JBoss Server Migration Tool logs the results to its log file and to the console. 

 INFO  Subsystem jgroups updated.
Copy to Clipboard Toggle word wrap

To skip the automatic migration of the jgroups subsystem, set the subsystem.jgroups.update.skip environment property to true.

6.1.11. Update the Remoting Subsystem
Copier lien

JBoss EAP 7.4 includes an HTTP connector that replaces all legacy remoting protocols and ports using a single port. The JBoss Server Migration Tool automatically updates the remoting subsystem to use the HTTP connector.

To skip the automatic update of the remoting subsystem configuration, set the subsystem.remoting.update.skip environment property to true.

6.1.12. Update the Transactions Subsystem
Copier lien

The JBoss Server Migration Tool updates the transactions subsystem with the configuration changes required by the JBoss EAP 7.4 server.

The JBoss Server Migration Tool removes the path and relative-to attributes from the transactions subsystem and replaces them with the equivalent object-store-path and object-store-relative-to attributes.

To skip the automatic update of the transactions subsystem configuration, set the subsystem.transactions.update-xml-object-store-paths.skip environment property to true.

6.1.13. Update the Undertow Subsystem
Copier lien

In addition to migrating the web subsystem for JBoss EAP 7.4, the JBoss Server Migration Tool updates its replacement undertow subsystem to add the features it supports.

  • It sets the default HTTP listener redirect socket.
  • It adds support for Jakarta WebSockets.
  • It sets the default HTTPS listener.
  • It adds support for HTTP2.
  • It removes the Server response header.
  • It removes the X-Powered-By response header.
  • It sets the default HTTP Invoker.

The JBoss Server Migration Tool automatically updates the undertow subsystem configuration and logs the results to its log file and to the console.

Upon successful migration of the undertow subsystem configuration, the JBoss Server Migration Tool logs the results to its log file and to the console. 

 INFO  Subsystem undertow updated.
Copy to Clipboard Toggle word wrap

You can customize the update of the undertow system by setting the following environment properties.

Expand
Property NameProperty Description

subsystem.undertow.update.skip

If set to true, skip the update of the undertow subsystem.

subsystem.undertow.update.set-default-http-listener-redirect-socket.skip

If set to true, do not set the default HTTP listener redirect socket.

subsystem.undertow.update.add-undertow-websockets.skip

If set to true, do not add support for WebSockets.

subsystem.undertow.update.add-undertow-https-listener.skip

If set to true, do not set the default HTTPS listener.

subsystem.undertow.update.enable-http2.skip

If set to true, do not add support for HTTP2.

subsystem.undertow.update.add-response-header.server-header.skip

If set to true, do not set the default Server response header.

subsystem.undertow.update.add-response-header.x-powered-by-header.skip

If set to true, do not set the default X-Powered-By response header.

subsystem.undertow.update.add-http-invoker.skip

If set to true, do not set the default HTTP Invoker.

6.1.14. Update the Messaging-ActiveMQ Subsystem
Copier lien

In addition to migrating the messaging subsystem for JBoss EAP 7.4, the JBoss Server Migration Tool updates its replacement messaging-activemq subsystem to add the new features it supports.

  • It adds the default HTTP connector and acceptor to enable the HTTP-based remote messaging clients.

The JBoss Server Migration Tool automatically updates the messaging-activemq subsystem configuration and logs the results to its log file and to the console.

To skip the automatic update of the messaging-activemq subsystem, set the subsystem.messaging-activemq.update.skip environment property to true.

6.1.15. Add the Batch JBeret Subsystem
Copier lien

The JBoss EAP 7.4 batch-jberet subsystem provides support for the Jakarta Batch 1.0 specification. The JBoss Server Migration Tool automatically adds the default batch-jberet subsystem configuration to the migrated configuration.

To skip the addition of the batch-jberet subsystem configuration, set the subsystem.batch-jberet.add.skip environment property to true.

6.1.16. Add the Core Management Subsystem
Copier lien

The JBoss EAP 7.4 core-management subsystem provides management-related resources, which were previously configured in the management core service. Examples of these resources include the ability to view a history of configuration changes made to the server and the ability to monitor for server lifecycle events. The JBoss Server Migration Tool automatically adds the default core-management subsystem configuration to the migrated configuration file.

To skip the addition of the core-management subsystem configuration, set the subsystem.core-management.add.skip environment property to true.

6.1.17. Add the Discovery Subsystem
Copier lien

The JBoss Server Migration Tool automatically adds the default discovery subsystem configuration to the migrated configuration file.

To skip the addition of the discovery subsystem configuration, set the subsystem.discovery.add.skip environment property to true.

6.1.18. Add the EE Security Subsystem
Copier lien

The JBoss EAP 7.4 ee-security subsystem provides support and compliance for Jakarta Security. The JBoss Server Migration Tool automatically adds the default ee-security subsystem configuration to the migrated configuration file.

To skip the addition of the ee-security subsystem configuration, set the subsystem.ee-security.add.skip environment property to true.

6.1.19. Add the Elytron Subsystem
Copier lien

The JBoss EAP 7.4 elytron subsystem provides a single unified security framework that can manage and configure access for both standalone servers and managed domains. It can also be used to configure security access for applications deployed to JBoss EAP servers. The JBoss Server Migration Tool automatically adds the default elytron subsystem configuration to the migrated configuration file.

To skip the addition of the elytron subsystem configuration, set the subsystem.elytron.add.skip environment property to true.

6.1.20. Add the health subsystem
Copier lien

The JBoss EAP 7.4 health subsystem provides support for a server’s health functionality. The JBoss Server Migration Tool automatically adds the default health subsystem configuration to the migrated configuration file.

To skip the addition of the health subsystem configuration, set the subsystem.health.add.skip environment property to true.

After you add the health subsystem to JBoss EAP 7.4, you’ll see the following message in your web console: 

INFO  Subsystem health added.
Copy to Clipboard Toggle word wrap

6.1.21. Add the metrics subsystem
Copier lien

The JBoss EAP 7.4 metrics subsystem provides support for a server’s metric functionality. The JBoss Server Migration Tool automatically adds the default metrics subsystem configuration to the migrated configuration file.

To skip the addition of the metrics subsystem configuration, set the subsystem.metrics.add.skip environment property to true.

After you add the metrics subsystem to JBoss EAP 7.4, you’ll see the following message in your web console: 

INFO  Subsystem metrics added.
Copy to Clipboard Toggle word wrap

6.1.22. Add the Request Controller Subsystem
Copier lien

The JBoss EAP 7.4 request-controller subsystem provides congestion control and graceful shutdown functionality. The JBoss Server Migration Tool automatically adds the default request-controller subsystem configuration to the migrated configuration file.

To skip the addition of the request-controller subsystem configuration, set the subsystem.request-controller.add.skip environment property to true.

6.1.23. Add the Security Manager Subsystem
Copier lien

The JBoss EAP 7.4 security-manager subsystem provides support for Jakarta Security permissions. The JBoss Server Migration Tool automatically adds the default security-manager subsystem configuration to the migrated configuration file.

To skip the addition of the security-manager subsystem configuration, set the subsystem.security-manager.add.skip environment property to true.

6.1.24. Add the Singleton Subsystem
Copier lien

The JBoss EAP 7.4 singleton subsystem provides singleton functionality. The JBoss Server Migration Tool automatically adds the default singleton subsystem configuration to the migrated configuration file.

To skip the addition of the singleton subsystem configuration, set the subsystem.singleton.add.skip environment property to true.

6.1.25. Set Up HTTP Upgrade Management
Copier lien

The addition of Undertow in JBoss EAP 7.4 added HTTP Upgrade, which allows for multiple protocols to be multiplexed over a single port. This means a management client can make an initial connection over HTTP, but then send a request to upgrade that connection to another protocol. The JBoss Server Migration Tool automatically updates the configuration to support HTTP Upgrade management.

To skip configuration of HTTP Upgrade management, set the management.setup-http-upgrade.skip environment property to true.

6.1.26. Set Up the Private Interface
Copier lien

The JBoss EAP 7.4 default configuration uses a private interface on all jgroups socket bindings. The JBoss Server Migration Tool automatically updates the migrated jgroups socket bindings to use same configuration.

To skip the configuration of the private interface, set the interface.private.setup.skip environment property to true.

6.1.27. Add Socket Binding Port Expressions
Copier lien

The JBoss EAP 7.4 default configurations use value expressions for the port attribute of the following socket bindings:

  • ajp
  • http
  • https

The JBoss Server Migration Tool automatically adds these value expressions to the migrated server configurations.

To skip update of the socket binding port expressions, set the socket-bindings.add-port-expressions.skip environment property to true.

6.1.28. Add Socket Binding Multicast Address Expressions
Copier lien

The JBoss EAP 7.4 default configuration uses value expressions in the multicast-address attribute of mod_cluster socket bindings. The JBoss Server Migration Tool automatically adds these value expressions to the migrated configuration files.

To skip the addition of these expressions, set the socket-bindings.multicast-address.add-expressions.skip environment property to true.

6.1.29. Migrate Compatible Security Realms
Copier lien

Because the JBoss EAP 7.4 security realm configurations are fully compatible with the JBoss EAP 6.4 security realm configurations, they require no update by the JBoss Server Migration Tool. However, if the application-users.properties, application-roles.properties, mgmt-users.properties, and mgmt-groups.properties files are not referenced using an absolute path, the tool copies them to the path expected by the migrated configuration file.

To skip the security realms migration, set the security-realms.migrate-properties.skip environment property to true.

The JBoss EAP 7.4 default configuration includes an SSL server identity for the default ApplicationRealm security realm. The JBoss Server Migration Tool automatically adds this identity to the migrated configuration files.

To skip the addition of this identity, set the security-realm.ApplicationRealm.add-ssl-server-identity.skip environment property to true.

6.1.31. Migrate Deployments
Copier lien

The JBoss Server Migration Tool can migrate the following types of standalone server deployment configurations.

The migration of a deployment consists of installing related file resources on the target server, and possibly updating the migrated configuration.

The JBoss Server Migration Tool is preconfigured to skip deployments by default when running in non-interactive mode. To enable migration of deployments, set the deployments.migrate-deployments.skip environment property to false.

Important

Be aware that when you run the JBoss Server Migration Tool in interactive mode and enter invalid input, the resulting behavior depends on the value of the deployments.migrate-deployments environment property.

  • If deployments.migrate-deployments.skip is set to false and you enter invalid input, the tool will try to migrate the deployments.
  • If deployments.migrate-deployments.skip is set to true and you enter invalid input, the tool will skip the deployments migration.

To enable the migration of specific types of deployments, see the following sections.

Warning

The JBoss Server Migration Tool does not determine whether deployed resources are compatible with the target server. This means that applications or resources might not deploy, might not work as expected, or might not work at all. Also be aware that artifacts such as JBoss EAP 6.4 *-jms.xml configuration files are copied without modification and can cause the JBoss EAP server to boot with errors.

Red Hat recommends that you use the Migration Toolkit for Applications (MTA) to analyze deployments to determine compatibility among different JBoss EAP servers. For more information, see Product Documentation for Migration Toolkit for Applications.

6.1.31.1. Migrate Persistent Deployments
Copier lien

To enable migration of persistent deployments when running in non-interactive mode, set the deployments.migrate-persistent-deployments.skip environment property to false.

The JBoss Server Migration Tool searches for any persistent deployment references and lists them to the console. 

INFO  [ServerMigrationTask#67] Persistent deployments found: [cmtool-helloworld3.war, cmtool-helloworld4.war, cmtool-helloworld2.war, cmtool-helloworld1.war]
Copy to Clipboard Toggle word wrap

The processing workflow then depends on whether you are running the tool in interactive mode or in non-interactive mode, as described below.

Migrating Persistent Deployments in Non-interactive Mode

If you run the tool in non-interactive mode, the tool uses the preconfigured properties to determine whether to migrate the persistent deployments. Persistent deployments are migrated only if both the deployments.migrate-deployments.skip and deployments.migrate-persistent-deployments.skip properties are set to false.

Migrating Persistent Deployments in Interactive Mode

If you run the tool in interactive mode, the JBoss Server Migration Tool prompts you for each deployment using the following workflow.

  1. After printing the persistent deployments it finds to the console, you 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?
    Copy to Clipboard Toggle word wrap
    • Respond with yes to skip migration of persistent deployments. All deployment references are removed from the migrated configuration and you end this part of the migration process.
    • Respond with no to continue with the migration.

  2. If you choose to continue, you see the following prompt. 

    Migrate all persistent deployments found?
yes/no?
    Copy to Clipboard Toggle word wrap
    • Respond with yes to automatically migrate all deployments and end this part of the migration process.
    • Respond with no to continue with the migration.

  3. If you choose to continue, you receive a prompt asking to confirm the migration for each referenced deployment. 

    Migrate persistent deployment 'helloworld01.war'?
yes/no?
    Copy to Clipboard Toggle word wrap
    • Respond with yes to migrate the deployment.

    • Respond with no to remove the deployment from the migrated configuration. 

      INFO  [ServerMigrationTask#68] Removed persistent deployment from configuration /deployment=helloworld01.war
      Copy to Clipboard Toggle word wrap

6.1.31.2. Migrate Deployment Scanner Deployments
Copier lien

Deployment scanners, which are only used in standalone server configurations, monitor a directory for new files and manage their deployment automatically or through special deployment marker files.

To enable migration of deployments that are located in directories watched by a deployment scanner when running in non-interactive mode, set the deployments.migrate-deployment-scanner-deployments.skip environment property to false.

When migrating a standalone server configuration, the JBoss Server Migration Tool first searches for any configured deployment scanners. For each scanner found, it searches its monitored directories for deployments marked as deployed and prints the results to the console.

The processing workflow then depends on whether you are running the tool in interactive mode or in non-interactive mode, as described below.

Migrating Deployment Scanner Deployments in Non-interactive Mode

If you run the tool in non-interactive mode, the tool uses the preconfigured properties to determine whether to migrate the deployment scanner deployments. Deployment scanner deployments are migrated only if both the deployments.migrate-deployments.skip and deployments.migrate-deployment-scanner-deployments.skip properties are set to false.

Migrating Deployment Scanner Deployments in Interactive Mode

If you run the tool in interactive mode, the JBoss Server Migration Tool prompts you for each deployment using the following workflow.

  1. After printing the deployment scanner deployments it finds to the console, you see the following prompt. 

    This tool is not able to assert if the scanner's deployments found are compatible with the target server, skip scanner's deployments migration?
yes/no?
    Copy to Clipboard Toggle word wrap
    • Respond with yes to skip migration of deployment scanner deployments. All deployment references are removed from the migrated configuration and you end this part of the migration process.
    • Respond with no to continue with the migration.

  2. If you choose to continue, you see the following prompt. 

    Migrate all scanner's deployments found?
yes/no?
    Copy to Clipboard Toggle word wrap
    • Respond with yes to automatically migrate all deployments and end this part of the migration process.
    • Respond with no to continue with the migration.

  3. If you choose to continue, you receive a prompt asking to confirm the migration for each referenced deployment. 

    Migrate scanner's deployment 'helloworld02.war'?
yes/no?
    Copy to Clipboard Toggle word wrap
    • Respond with yes to migrate the deployment.

    • Respond with no to remove the deployment from the migrated configuration. 

      INFO  [ServerMigrationTask#69] Resource with path EAP_HOME/standalone/deployments/helloworld02.war migrated.
      Copy to Clipboard Toggle word wrap

6.1.31.3. Migrate Deployment Overlays
Copier lien

The migration of deployment overlays is a fully automated process. If you have enabled migration of deployments by setting the deployments.migrate-deployments.skip environment property to false, the JBoss Server Migration Tool searches for deployment overlays referenced in the standalone server configuration that are linked to migrated deployments. It automatically migrates those that are found, removes those that are not referenced, and logs the results to its log file and to the console.

Warning

When you use the JBoss Server Migration Tool, migrate your domain controller before you migrate your hosts to ensure your domain controller must use the later version of EAP when compared to the version used by hosts. For example, a domain controller running on EAP 7.3 cannot handle a host running on EAP 7.4.

Review Configure a JBoss EAP 7.x Domain Controller to Administer JBoss EAP 6 Instances in the Configuration Guide for JBoss EAP. Pay particular attention to the section entitled Prevent the JBoss EAP 6 Instances from Receiving JBoss EAP 7 Updates.

For more information and to learn about the supported configurations, see Managing Multiple JBoss EAP Versions in the Configuration Guide for JBoss EAP.

By default, the JBoss Server Migration Tool performs the following tasks when migrating a managed domain configuration from JBoss EAP 6.4 to JBoss EAP 7.4

6.2.1. Remove Unsupported Subsystems
Copier lien

The following JBoss EAP 6.4 subsystems are not supported by JBoss EAP 7.4 :

Expand
Subsystem NameConfiguration NamespaceExtension Module

cmp

urn:jboss:domain:cmp:*

org.jboss.as.cmp

configadmin

urn:jboss:domain:configadmin:*

org.jboss.as.configadmin

jaxr

urn:jboss:domain:jaxr:*

org.jboss.as.jaxr

osgi

urn:jboss:domain:osgi:*

org.jboss.as.osgi

threads

urn:jboss:domain:threads:*

org.jboss.as.threads

The JBoss Server Migration Tool removes all unsupported subsystem configurations and extensions from migrated server configurations. The tool logs each subsystem and extension to its log file and to the console as it is removed.

To skip removal of the unsupported subsystems, set the subsystems.remove-unsupported-subsystems.skip environment property to true.

You can override the default behavior of the JBoss Server Migration Tool and specify which subsystems and extensions should be included or excluded during the migration using the following environment properties.

Expand
Property NameProperty Description

extensions.excludes

A list of module names of extensions that should never be migrated, for example, com.example.extension1,com.example.extension3.

extensions.includes

A list of module names of extensions that should always be migrated, for example, com.example.extension2,com.example.extension4.

subsystems.excludes

A list of subsystem namespaces, stripped of the version, that should never be migrated, for example, urn:jboss:domain:logging, urn:jboss:domain:ejb3.

subsystems.includes

A list of subsystem namespaces, stripped of the version, that should always be migrated, for example, urn:jboss:domain:security, urn:jboss:domain:ee.

6.2.2. Migrate Referenced Modules
Copier lien

A configuration that is migrated from a source server to a target server might reference or depend on a module that is not installed on the target server. The JBoss Server Migration Tool detects this and automatically migrates the referenced modules, plus their dependent modules, from the source server to the target server.

A module referenced by a managed domain configuration is migrated using the following process.

  • A module referenced by a security realm configuration is migrated as a plug-in module.
  • A module referenced by the datasource subsystem configuration is migrated as a datasource driver module.
  • A module referenced by the ee subsystem configuration is migrated as a global module.
  • A module referenced by the naming subsystem configuration is migrated as an object factory module.
  • A module referenced by the messaging subsystem configuration is migrated as a Jakarta Messaging bridge module.
  • A module referenced by a vault configuration is migrated to the new configuration.
  • Any extension that is not installed on the target configuration is migrated to the target server configuration.

The console logs a message noting the module ID for any module that is migrated. It is possible to exclude the migration of specific modules by specifying the module ID in the modules.excludes environment property. See Configuring the Migration of Modules for more information.

6.2.3. Migrate Referenced Paths
Copier lien

A configuration that is migrated from a source server to a target server might reference or depend on file paths and directories that must also be migrated to the target server. The JBoss Server Migration Tool does not migrate absolute path references. It only migrates files or directories that are configured as relative to the source configuration. The console logs a message noting each path that is migrated.

The JBoss Server Migration Tool automatically migrates the following path references:

  • Vault keystore and encrypted file’s directory.

To skip the migration of referenced paths, set the paths.migrate-paths-requested-by-configuration.vault.skip environment property to true.

6.2.4. Migrate the Jacorb Subsystem
Copier lien

The jacorb subsystem is deprecated in JBoss EAP 7.4 and is replaced by the iiop-openjdk subsystem. By default, the JBoss Server Migration Tool automatically migrates the jacorb subsystem configuration to its replacement iiop-openjdk subsystem configuration and logs the results to its log file and to the console.

To skip the automatic migration to the iiop-openjdk subsystem configuration, set the subsystem.jacorb.migrate.skip environment property value to true.

6.2.5. Migrate the Web Subsystem
Copier lien

The web subsystem is deprecated in JBoss EAP 7.4 and is replaced by the undertow subsystem. By default, the JBoss Server Migration Tool automatically migrates the web subsystem configuration to its replacement undertow subsystem configuration and logs the results to its log file and to the console.

To skip automatic migration of the web subsystem, set the subsystem.web.migrate.skip environment property value to true.

6.2.6. Migrate the Messaging Subsystem
Copier lien

The messaging subsystem is deprecated in JBoss EAP 7.4 and is replaced by the messaging-activemq subsystem. The JBoss Server Migration Tool automatically migrates the messaging subsystem configuration to its replacement messaging-activemq subsystem configuration and logs the results to its log file and to the console.

To skip automatic migration of the messaging subsystem, set the subsystem.messaging.migrate.skip environment property value to true.

6.2.7. Update the Infinispan Subsystem
Copier lien

The JBoss Server Migration Tool updates the infinispan subsystem configuration to better align with the default JBoss EAP 7.4 configurations.

  • It adds the Jakarta Enterprise Beans cache container, which is present in the JBoss EAP 7.4 default configuration, to configurations where it is not already included.
  • It adds the server cache container, which is present in the JBoss EAP 7.4 default configuration.
  • It updates the module name in the Hibernate cache container configuration.
  • It adds the concurrent cache to the web cache container, which is present in the JBoss EAP 7.4 default configuration.

The JBoss Server Migration Tool automatically updates the infinispan subsystem configuration and logs the results to its log file and to the console.

You can customize the update of the infinispan system by setting the following environment properties.

Expand
Property NameProperty Description

subsystem.infinispan.update.skip

If set to true, skip the update of the infinispan subsystem.

subsystem.infinispan.update.add-infinispan-ejb-cache.skip

If set to true, do not add the Jakarta Enterprise Beans cache container.

subsystem.infinispan.update.add-infinispan-server-cache.skip

If set to true, do not add the server cache container.

subsystem.infinispan.update.fix-hibernate-cache-module-name.skip

If set to true, do not update the module name in the Hibernate cache container configuration.

subsystem.infinispan.update-infinispan-web-cache

If set to true, do not add the concurrent cache to the web cache container configuration.

6.2.8. Update the EE Subsystem
Copier lien

The JBoss Server Migration Tool updates the ee subsystem to configure the Jakarta EE features supported in JBoss EAP 7.4.

  • It configures instances of Jakarta EE concurrency utilities, such as container-managed executors, that are present in the JBoss EAP 7.4 default configuration and logs the results to its log file and to the console.

  • It defines the default resources, such as the default datasource, that are present in default JBoss EAP 6.4 configuration. If the resources are not found, the tool lists all available resources in the configuration, and then provides a prompt to select a resource from the list or to provide the Java Naming and Directory Interface address of the resource that should be set as the default.

    Note

    Java Naming and Directory Interface names that are specified are assumed to be valid. Java Naming and Directory Interface names are not validated by the tool.

The JBoss Server Migration Tool automatically updates the ee subsystem configuration and logs the results to its log file and to the console.

You can customize the update of the ee system by setting the following environment properties.

Expand
Property NameProperty Description

subsystem.ee.update.skip

If set to true, skip the update of the ee subsystem.

subsystem.ee.update.setup-ee-concurrency-utilities.skip

If set to true, do not add the default instances of concurrency utilities.

subsystem.ee.update.setup-javaee7-default-bindings.skip

If set to true, do not set up Jakarta EE default resources.

subsystem.ee.update.setup-javaee7-default-bindings.defaultDataSourceName

Specifies the name of the default datasource to look for in the source configuration.

subsystem.ee.update.setup-javaee7-default-bindings.defaultDataSourceJndiName

Specifies the Java Naming and Directory Interface name for the default datasource.

subsystem.ee.update.setup-javaee7-default-bindings.defaultJmsConnectionFactoryName

Specifies the name of the default Jakarta Messaging connection factory.

subsystem.ee.update.setup-javaee7-default-bindings.defaultJmsConnectionFactoryJndiName

Specifies the Java Naming and Directory Interface name for the default Jakarta Messaging connection factory.

Configuring Concurrency Utilities in the EE Subsystem

If you choose to configure the Jakarta EE concurrency utilities, then the tool automatically configures the instances that are present in the default JBoss EAP 7.4 configurations and logs the results to its log file and to the console. 

INFO  [ServerMigrationTask#49] Default ContextService added to EE subsystem configuration.
INFO  [ServerMigrationTask#49] Default ManagedThreadFactory added to EE subsystem configuration.
INFO  [ServerMigrationTask#49] Default ManagedExecutorService added to EE subsystem configuration.
INFO  [ServerMigrationTask#49] Default ManagedScheduledExecutorService added to EE subsystem configuration.
Copy to Clipboard Toggle word wrap

Configuring Default Resources in the EE Subsystem

When defining the Jakarta EE default resources the tool automatically selects those that are present in the default JBoss EAP 7.4 configuration. 

INFO  [ServerMigrationTask#50] Java EE Default Datasource configured with Java Naming and Directory Interface and name java:jboss/datasources/ExampleDS.
Copy to Clipboard Toggle word wrap

If no default resource is found, the tool lists all resources that are available in the configuration, and then provides a prompt to select the default resource or to provide the Java Naming and Directory Interface address of the resource that should be set as the default.

The following is an example of the interaction that occurs when migrating a configuration file with an ExampleDS datasource. 

INFO  [ServerMigrationTask#22] Default datasource not found.
0. ExampleDS
1. Unconfigured data source, I want to enter the Java Naming and Directory Interface name...
Please select Java EE's Default Datasource: (0): 0
INFO  [ServerMigrationTask#22] Java EE Default Datasource configured with Java Naming and Directory Interface name java:jboss/datasources/ExampleDS.

Save this Java EE Default Datasource Java Naming and Directory Interface name and use it when migrating other config files?
yes/no? y
Copy to Clipboard Toggle word wrap
Note

If you run the JBoss Server Migration Tool in non-interactive mode and the expected JBoss EAP 6.4 default resources, such as the default Jakarta Messaging connection factory, are not available, the tool does not configure those resources.

6.2.9. Update the Jakarta Enterprise Beans Subsystem
Copier lien

The JBoss Server Migration Tool makes the following updates to the Jakarta Enterprise Beans subsystem to better align with the default JBoss EAP 7.4 configurations.

  • It updates the remote service configuration to reference the HTTP connector.
  • It configures the default-sfsb-passivation-disabled-cache attribute to use the default-sfsb-cache.
  • It replaces the legacy passivation store and cache configurations with the JBoss EAP 7.4 default values.

The JBoss Server Migration Tool automatically updates the Jakarta Enterprise Beans subsystem configuration and logs the results to its log file and to the console.

Upon successful update of the Jakarta Enterprise Beans subsystem configuration, the JBoss Server Migration Tool logs the results to its log file and to the console. 

 INFO  Subsystem ejb3 updated.
Copy to Clipboard Toggle word wrap

You can customize the update of the Jakarta Enterprise Beans subsystem by setting the following environment properties.

Expand
Property NameProperty Description

subsystem.ejb3.update.skip

If set to true, skip the update of the Jakarta Enterprise Beans subsystem.

subsystem.ejb3.update.add-infinispan-passivation-store-and-distributable-cache.skip

If set to true, do not replace the passivation-store and cache configurations.

subsystem.ejb3.update.setup-default-sfsb-passivation-disabled-cache.skip

If set to true, do not update the default-sfsb-passivation-disabled-cache configuration.

subsystem.ejb3.update.activate-ejb3-remoting-http-connector.skip

If set to true, do not update the ejb3 subsystem remoting configuration.

6.2.10. Update the JGroups Subsystem
Copier lien

The JBoss Server Migration Tool updates the jgroups subsystem to align with the JBoss EAP 7.4 configurations.

  • It replaces the MERGE2 protocol with MERGE3.
  • It replaces the FD protocol with FD_ALL.
  • It replaces the pbcast.NAKACK protocol with pbcast.NAKACK2.
  • It replaces the UNICAST2 protocol with UNICAST3.
  • It removes the RSVP protocol.
  • It replaces the FRAG2 protocol with the FRAG3 protocol.

Upon successful migration of the jgroups subsystem configuration, the JBoss Server Migration Tool logs the results to its log file and to the console. 

 INFO  Subsystem jgroups updated.
Copy to Clipboard Toggle word wrap

To skip the automatic migration of the jgroups subsystem, set the subsystem.jgroups.update.skip environment property to true.

6.2.11. Update the Remoting Subsystem
Copier lien

JBoss EAP 7.4 includes an HTTP connector that replaces all legacy remoting protocols and ports using a single port. The JBoss Server Migration Tool automatically updates the remoting subsystem to use the HTTP connector.

To skip the automatic update of the remoting subsystem configuration, set the subsystem.remoting.update.skip environment property to true.

6.2.12. Update the Transactions Subsystem
Copier lien

The JBoss Server Migration Tool updates the transactions subsystem with the configuration changes required by the JBoss EAP 7.4 server.

The JBoss Server Migration Tool removes the path and relative-to attributes from the transactions subsystem and replaces them with the equivalent object-store-path and object-store-relative-to attributes.

To skip the automatic update of the transactions subsystem configuration, set the subsystem.transactions.update-xml-object-store-paths.skip environment property to true.

6.2.13. Update the Undertow Subsystem
Copier lien

In addition to migrating the web subsystem for JBoss EAP 7.4, the JBoss Server Migration Tool updates its replacement undertow subsystem to add the features it supports.

  • It sets the default HTTP listener redirect socket.
  • It adds support for Jakarta WebSockets.
  • It sets the default HTTPS listener.
  • It adds support for HTTP2.
  • It removes the Server response header.
  • It removes the X-Powered-By response header.
  • It sets the default HTTP Invoker.

The JBoss Server Migration Tool automatically updates the undertow subsystem configuration and logs the results to its log file and to the console.

Upon successful migration of the undertow subsystem configuration, the JBoss Server Migration Tool logs the results to its log file and to the console. 

 INFO  Subsystem undertow updated.
Copy to Clipboard Toggle word wrap

You can customize the update of the undertow system by setting the following environment properties.

Expand
Property NameProperty Description

subsystem.undertow.update.skip

If set to true, skip the update of the undertow subsystem.

subsystem.undertow.update.set-default-http-listener-redirect-socket.skip

If set to true, do not set the default HTTP listener redirect socket.

subsystem.undertow.update.add-undertow-websockets.skip

If set to true, do not add support for WebSockets.

subsystem.undertow.update.add-undertow-https-listener.skip

If set to true, do not set the default HTTPS listener.

subsystem.undertow.update.enable-http2.skip

If set to true, do not add support for HTTP2.

subsystem.undertow.update.add-response-header.server-header.skip

If set to true, do not set the default Server response header.

subsystem.undertow.update.add-response-header.x-powered-by-header.skip

If set to true, do not set the default X-Powered-By response header.

subsystem.undertow.update.add-http-invoker.skip

If set to true, do not set the default HTTP Invoker.

6.2.14. Update the Messaging-ActiveMQ Subsystem
Copier lien

In addition to migrating the messaging subsystem for JBoss EAP 7.4, the JBoss Server Migration Tool updates its replacement messaging-activemq subsystem to add the new features it supports.

  • It adds the default HTTP connector and acceptor to enable the HTTP-based remote messaging clients.

The JBoss Server Migration Tool automatically updates the messaging-activemq subsystem configuration and logs the results to its log file and to the console.

To skip the automatic update of the messaging-activemq subsystem, set the subsystem.messaging-activemq.update.skip environment property to true.

6.2.15. Add the Batch JBeret Subsystem
Copier lien

The JBoss EAP 7.4 batch-jberet subsystem provides support for the Jakarta Batch 1.0 specification. The JBoss Server Migration Tool automatically adds the default batch-jberet subsystem configuration to the migrated configuration.

To skip the addition of the batch-jberet subsystem configuration, set the subsystem.batch-jberet.add.skip environment property to true.

6.2.16. Add the Core Management Subsystem
Copier lien

The JBoss EAP 7.4 core-management subsystem provides management-related resources, which were previously configured in the management core service. Examples of these resources include the ability to view a history of configuration changes made to the server and the ability to monitor for server lifecycle events. The JBoss Server Migration Tool automatically adds the default core-management subsystem configuration to the migrated configuration file.

To skip the addition of the core-management subsystem configuration, set the subsystem.core-management.add.skip environment property to true.

6.2.17. Add the Discovery Subsystem
Copier lien

The JBoss Server Migration Tool automatically adds the default discovery subsystem configuration to the migrated configuration file.

To skip the addition of the discovery subsystem configuration, set the subsystem.discovery.add.skip environment property to true.

6.2.18. Add the EE Security Subsystem
Copier lien

The JBoss EAP 7.4 ee-security subsystem provides support and compliance for Jakarta Security. The JBoss Server Migration Tool automatically adds the default ee-security subsystem configuration to the migrated configuration file.

To skip the addition of the ee-security subsystem configuration, set the subsystem.ee-security.add.skip environment property to true.

6.2.19. Add the Elytron Subsystem
Copier lien

The JBoss EAP 7.4 elytron subsystem provides a single unified security framework that can manage and configure access for both standalone servers and managed domains. It can also be used to configure security access for applications deployed to JBoss EAP servers. The JBoss Server Migration Tool automatically adds the default elytron subsystem configuration to the migrated configuration file.

To skip the addition of the elytron subsystem configuration, set the subsystem.elytron.add.skip environment property to true.

6.2.20. Add the Request Controller Subsystem
Copier lien

The JBoss EAP 7.4 request-controller subsystem provides congestion control and graceful shutdown functionality. The JBoss Server Migration Tool automatically adds the default request-controller subsystem configuration to the migrated configuration file.

To skip the addition of the request-controller subsystem configuration, set the subsystem.request-controller.add.skip environment property to true.

6.2.21. Add the Security Manager Subsystem
Copier lien

The JBoss EAP 7.4 security-manager subsystem provides support for Jakarta Security permissions. The JBoss Server Migration Tool automatically adds the default security-manager subsystem configuration to the migrated configuration file.

To skip the addition of the security-manager subsystem configuration, set the subsystem.security-manager.add.skip environment property to true.

6.2.22. Add the Singleton Subsystem
Copier lien

The JBoss EAP 7.4 singleton subsystem provides singleton functionality. The JBoss Server Migration Tool automatically adds the default singleton subsystem configuration to the migrated configuration file.

To skip the addition of the singleton subsystem configuration, set the subsystem.singleton.add.skip environment property to true.

6.2.23. Update the Unsecure Interface
Copier lien

The JBoss Server Migration Tool automatically updates the unsecure interface configuration to align with the JBoss EAP 7.4 default configuration.

To skip configuration of the unsecure interface, set the interface.unsecure.update.skip environment property to true.

6.2.24. Set Up the Private Interface
Copier lien

The JBoss EAP 7.4 default configuration uses a private interface on all jgroups socket bindings. The JBoss Server Migration Tool automatically updates the migrated jgroups socket bindings to use same configuration.

To skip the configuration of the private interface, set the interface.private.setup.skip environment property to true.

6.2.25. Add Socket Binding Port Expressions
Copier lien

The JBoss EAP 7.4 default configurations use value expressions for the port attribute of the following socket bindings:

  • ajp
  • http
  • https

The JBoss Server Migration Tool automatically adds these value expressions to the migrated server configurations.

To skip update of the socket binding port expressions, set the socket-bindings.add-port-expressions.skip environment property to true.

6.2.26. Add Socket Binding Multicast Address Expressions
Copier lien

The JBoss EAP 7.4 default configuration uses value expressions in the multicast-address attribute of mod_cluster socket bindings. The JBoss Server Migration Tool automatically adds these value expressions to the migrated configuration files.

To skip the addition of these expressions, set the socket-bindings.multicast-address.add-expressions.skip environment property to true.

6.2.27. Add the Load Balancer Profile
Copier lien

JBoss EAP 7.4 includes a default profile specifically tailored for hosts that serve as load balancers. The JBoss Server Migration Tool automatically adds and configures this profile to all migrated managed domain configurations.

To skip the addition of this profile, set the profile.load-balancer.add.skip environment property to true.

6.2.28. Add Host Excludes
Copier lien

The JBoss EAP 7.4 domain controller can potentially include functionality that is not supported by hosts running on older versions of the server. The host-exclude configuration specifies the resources that should be hidden from those older versions.

When migrating a domain controller configuration, the JBoss Server Migration Tool adds to or replaces the source server’s host-exclude configuration with the configuration of the target JBoss EAP 7.4 server.

The JBoss Server Migration Tool automatically updates the host-exclude configuration and logs the results to its log file and to the console. 

  INFO  Host-excludes configuration added.
Copy to Clipboard Toggle word wrap

The usage of PermGen attributes in JVM configurations is deprecated in JBoss EAP 7. The JBoss Server Migration Tool automatically removes them from all JVM configurations for all server groups.

To skip removal of the PermGen attributes, set the jvms.remove-permgen-attributes.skip environment property value to true.

6.2.30. Migrate Deployments
Copier lien

The JBoss Server Migration Tool can migrate the following types of managed domain deployment configurations.

The migration of a deployment consists of installing related file resources on the target server, and possibly updating the migrated configuration.

The JBoss Server Migration Tool is preconfigured to skip deployments by default when running in non-interactive mode. To enable migration of deployments, set the deployments.migrate-deployments.skip environment property to false.

Important

Be aware that when you run the JBoss Server Migration Tool in interactive mode and enter invalid input, the resulting behavior depends on the value of the deployments.migrate-deployments environment property.

  • If deployments.migrate-deployments.skip is set to false and you enter invalid input, the tool will try to migrate the deployments.
  • If deployments.migrate-deployments.skip is set to true and you enter invalid input, the tool will skip the deployments migration.

To enable the migration of specific types of deployments, see the following sections.

Warning

The JBoss Server Migration Tool does not determine whether deployed resources are compatible with the target server. This means that applications or resources might not deploy, might not work as expected, or might not work at all. Also be aware that artifacts such as JBoss EAP 6.4 *-jms.xml configuration files are copied without modification and can cause the JBoss EAP server to boot with errors.

Red Hat recommends that you use the Migration Toolkit for Applications (MTA) to analyze deployments to determine compatibility among different JBoss EAP servers. For more information, see Product Documentation for Migration Toolkit for Applications.

6.2.30.1. Migrate Persistent Deployments
Copier lien

To enable migration of persistent deployments when running in non-interactive mode, set the deployments.migrate-persistent-deployments.skip environment property to false.

The JBoss Server Migration Tool searches for any persistent deployment references and lists them to the console. 

INFO  [ServerMigrationTask#67] Persistent deployments found: [cmtool-helloworld3.war, cmtool-helloworld4.war, cmtool-helloworld2.war, cmtool-helloworld1.war]
Copy to Clipboard Toggle word wrap

The processing workflow then depends on whether you are running the tool in interactive mode or in non-interactive mode, as described below.

Migrating Persistent Deployments in Non-interactive Mode

If you run the tool in non-interactive mode, the tool uses the preconfigured properties to determine whether to migrate the persistent deployments. Persistent deployments are migrated only if both the deployments.migrate-deployments.skip and deployments.migrate-persistent-deployments.skip properties are set to false.

Migrating Persistent Deployments in Interactive Mode

If you run the tool in interactive mode, the JBoss Server Migration Tool prompts you for each deployment using the following workflow.

  1. After printing the persistent deployments it finds to the console, you 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?
    Copy to Clipboard Toggle word wrap
    • Respond with yes to skip migration of persistent deployments. All deployment references are removed from the migrated configuration and you end this part of the migration process.
    • Respond with no to continue with the migration.

  2. If you choose to continue, you see the following prompt. 

    Migrate all persistent deployments found?
yes/no?
    Copy to Clipboard Toggle word wrap
    • Respond with yes to automatically migrate all deployments and end this part of the migration process.
    • Respond with no to continue with the migration.

  3. If you choose to continue, you receive a prompt asking to confirm the migration for each referenced deployment. 

    Migrate persistent deployment 'helloworld01.war'?
yes/no?
    Copy to Clipboard Toggle word wrap
    • Respond with yes to migrate the deployment.

    • Respond with no to remove the deployment from the migrated configuration. 

      INFO  [ServerMigrationTask#68] Removed persistent deployment from configuration /deployment=helloworld01.war
      Copy to Clipboard Toggle word wrap

6.2.30.2. Migrate Deployment Overlays
Copier lien

The migration of deployment overlays is a fully automated process. If you have enabled migration of deployments by setting the deployments.migrate-deployments.skip environment property to false, the JBoss Server Migration Tool searches for deployment overlays referenced in the standalone server configuration that are linked to migrated deployments. It automatically migrates those that are found, removes those that are not referenced, and logs the results to its log file and to the console.

By default, the JBoss Server Migration Tool performs the following tasks when migrating a host server configuration from JBoss EAP 6.4 to JBoss EAP 7.4.

6.3.1. Migrate Referenced Modules
Copier lien

A configuration that is migrated from a source server to a target server might reference or depend on a module that is not installed on the target server. The JBoss Server Migration Tool detects this and automatically migrates the referenced modules, plus their dependent modules, from the source server to the target server.

A module referenced by a host server configuration is migrated using the following process.

  • A module referenced by a security realm configuration is migrated as a plug-in module.

The console logs a message noting the module ID for any module that is migrated. It is possible to exclude the migration of specific modules by specifying the module ID in the modules.excludes environment property. See Configuring the Migration of Modules for more information.

6.3.2. Migrate Referenced Paths
Copier lien

A configuration that is migrated from a source server to a target server might reference or depend on file paths and directories that must also be migrated to the target server. The JBoss Server Migration Tool does not migrate absolute path references. It only migrates files or directories that are configured as relative to the source configuration. The console logs a message noting each path that is migrated.

The JBoss Server Migration Tool automatically migrates the following path references:

  • Vault keystore and encrypted file’s directory.

To skip the migration of referenced paths, set the paths.migrate-paths-requested-by-configuration.vault.skip environment property to true.

6.3.3. Add the Core Management Subsystem
Copier lien

The JBoss EAP 7.4 core-management subsystem provides management-related resources, which were previously configured in the management core service. Examples of these resources include the ability to view a history of configuration changes made to the server and the ability to monitor for server lifecycle events. The JBoss Server Migration Tool automatically adds the default core-management subsystem configuration to the migrated configuration file.

To skip the addition of the core-management subsystem configuration, set the subsystem.core-management.add.skip environment property to true.

6.3.4. Add the Elytron Subsystem
Copier lien

The JBoss EAP 7.4 elytron subsystem provides a single unified security framework that can manage and configure access for both standalone servers and managed domains. It can also be used to configure security access for applications deployed to JBoss EAP servers. The JBoss Server Migration Tool automatically adds the default elytron subsystem configuration to the migrated configuration file.

To skip the addition of the elytron subsystem configuration, set the subsystem.elytron.add.skip environment property to true.

6.3.5. Add the JMX Subsystem to the Host Configuration
Copier lien

The JBoss EAP 7.4 jmx subsystem provides the ability to manage and monitor systems. The JBoss Server Migration Tool automatically adds this subsystem to the migrated configuration file.

To skip the addition of the jmx subsystem configuration, set the subsystem.jmx.add.skip environment property to true.

6.3.6. Remove the unsecure Interface
Copier lien

The JBoss Server Migration Tool automatically removes the unsecure interface configuration to align with the JBoss EAP 7.4 default configuration.

To skip removal of the unsecure interface, set the interface.unsecure.remove.skip environment property to true.

6.3.7. Set Up HTTP Upgrade Management
Copier lien

The addition of Undertow in JBoss EAP 7.4 added HTTP Upgrade, which allows for multiple protocols to be multiplexed over a single port. This means a management client can make an initial connection over HTTP, but then send a request to upgrade that connection to another protocol. The JBoss Server Migration Tool automatically updates the configuration to support HTTP Upgrade management.

To skip configuration of HTTP Upgrade management, set the management.setup-http-upgrade.skip environment property to true.

The usage of PermGen attributes in JVM configurations is deprecated in JBoss EAP 7. The JBoss Server Migration Tool automatically removes them from all JVM configurations for all server groups.

To skip removal of the PermGen attributes, set the jvms.remove-permgen-attributes.skip environment property value to true.

6.3.9. Migrate Compatible Security Realms
Copier lien

Because the JBoss EAP 7.4 security realm configurations are fully compatible with the JBoss EAP 6.4 security realm configurations, they require no update by the JBoss Server Migration Tool. However, if the application-users.properties, application-roles.properties, mgmt-users.properties, and mgmt-groups.properties files are not referenced using an absolute path, the tool copies them to the path expected by the migrated configuration file.

To skip the security realms migration, set the security-realms.migrate-properties.skip environment property to true.

The JBoss EAP 7.4 default configuration includes an SSL server identity for the default ApplicationRealm security realm. The JBoss Server Migration Tool automatically adds this identity to the migrated configuration files.

To skip the addition of this identity, set the security-realm.ApplicationRealm.add-ssl-server-identity.skip environment property to true.

Retour au début
Red Hat logoGithubredditYoutubeTwitter

Apprendre

Essayez, achetez et vendez

Communautés

À propos de la documentation Red Hat

Nous aidons les utilisateurs de Red Hat à innover et à atteindre leurs objectifs grâce à nos produits et services avec un contenu auquel ils peuvent faire confiance. Découvrez nos récentes mises à jour.

Rendre l’open source plus inclusif

Red Hat s'engage à remplacer le langage problématique dans notre code, notre documentation et nos propriétés Web. Pour plus de détails, consultez le Blog Red Hat.

À propos de Red Hat

Nous proposons des solutions renforcées qui facilitent le travail des entreprises sur plusieurs plates-formes et environnements, du centre de données central à la périphérie du réseau.

Theme

© 2025 Red Hat