How to use the JBoss Migration tool to upgrade your servers

In this tutorial I will show you how you can use the JBoss Server Migration Tool to migrate automatically to the newest versions of WildFly or JBoss EAP.

The JBoss Server Migration Tool is a standalone Java application that can be used to automatically migrate JBoss EAP and WildFly server configurations with little or no interaction required.

First of all you need to download the JBoss Server Migration Tool ZIP archive from https://github.com/wildfly/wildfly-server-migration/releases. Simply unzip the archive into a directory of your choice. No further setup is needed.

To run the JBoss Server Migration Tool, open a shell and navigate to the root directory where you downloaded or built the tool, and run the the migration script. The following is the basic syntax to run tool.

$ jboss-server-migration.sh --source [sourceAS] --target [destinationAS]

The Server Migration Tool includes support for the following server migrations, as you can see it works both for the Community versions migration and the Enterprise version (JBoss EAP):

  • JBoss EAP 6.4 to 7.0
  • WildFly 8 to JBoss EAP 7.0
  • WildFly 9 to JBoss EAP 7.0
  • WildFly 8 to 10.1
  • WildFly 9 to 10.1
  • WildFly 10.0 to 10.1

For example, if the source server base directory relative path is ../jboss-eap-6.4 and the target server base directory relative path is ../jboss-eap-7.0, execute the following command to migrate the JBoss EAP 6 into the JBoss EAP 7 installation:

$ jboss-server-migration.sh --source ../jboss-eap-6.4 --target ../jboss-eap-7.0

Now let's check the outcome of the migration into the jboss-eap-7.0/configuration folder:

-rw-------. 1 francesco francesco   732 Aug 28 11:38 application-roles.properties
-rw-rw-r--. 1 francesco francesco   711 Apr 18  2016 application-roles.properties.beforeMigration
-rw-------. 1 francesco francesco  1020 Aug 28 11:38 application-users.properties
-rw-------. 1 francesco francesco   935 Apr 18  2016 application-users.properties.beforeMigration
-rw-rw-r--. 1 francesco francesco  2697 Apr 18  2016 logging.properties
-rw-------. 1 francesco francesco   680 Aug 28 11:38 mgmt-groups.properties
-rw-rw-r--. 1 francesco francesco   669 Apr 18  2016 mgmt-groups.properties.beforeMigration
-rw-------. 1 francesco francesco  1154 Aug 28 11:38 mgmt-users.properties
-rw-------. 1 francesco francesco  1112 Apr 18  2016 mgmt-users.properties.beforeMigration
-rw-rw-r--. 1 francesco francesco 29713 Aug 28 11:38 standalone-full-ha.xml
-rw-rw-r--. 1 francesco francesco 27275 Apr 18  2016 standalone-full-ha.xml.beforeMigration
-rw-rw-r--. 1 francesco francesco 24177 Aug 28 11:38 standalone-full.xml
-rw-rw-r--. 1 francesco francesco 23844 Apr 18  2016 standalone-full.xml.beforeMigration
-rw-rw-r--. 1 francesco francesco 24026 Apr 18  2016 standalone-ha.xml
-rw-rw-r--. 1 francesco francesco 20827 Apr 18  2016 standalone.xml

As you can see, by default, a backup of the original configuration has been created and renamed to ".beforeMigration". The other files are the configuration files upgraded from the jboss-eap-6.4 installation.

Migrating modules

So far we have checked what happened to the configuration. What about the modules which are contained in the source EAP ? The good news is that the tool automatically migrates the referenced module(s), from the source server. Beyond that, any module that a referenced module depends on, directly or not, and is not installed in the target server, is automatically migrated too.

A module will be migrated when referenced by:

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

So, supposing that our source EAP contained the custom module "com.acme", when the script is executed a message indicating the module's id should be printed in the migration console/log, as exampled below:

03:25:31,205 INFO  [org.jboss.migration.core.task.ServerMigrationTask#18] (main) Module com.acme:main migrated.

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

You can pass the information on the command line using a system property, in such case the environment property names should be prefixed with jboss.server.migration.:

-Djboss.server.migration.modules.includes="com.acme" -Djboss.server.migration.modules.excludes="com.dontmigrate"

Check the JBoss Migration Tool User Guide for more examples on how migrating your WildFly or EAP installations.

Follow us on Twitter