Configuration Migration

The Migration Toolkit for Application Binaries can generate server configuration files that contain the migrated configuration. To generate the configuration from the command line, specify the binaryInputPath parameter and the --generateConfig action. The binaryInputPath parameter is an absolute or relative path to an .ear or .war file or to a directory that contains .ear and .war files.

Run commands from the wamt directory in your Migration Toolkit for Application Binaries installation. For a complete list of supported options for the --generateConfig action, run the following command: 

java -jar binaryAppScanner.jar --help --generateConfig

To generate a configuration file using the tool, run the following command:

java -jar binaryAppScanner.jar /myApp.ear --generateConfig

Specify a directory for the binaryInputPath to generate multiple server configuration files for multiple applications. The following command generates a configuration file in the current directory for each .war and .ear file located in the /myAppsDirectory directory: 

java -jar binaryAppScanner.jar /myAppsDirectory --generateConfig

To save the configuration output file to a directory, specify the --output parameter without a file name. For example, the following command writes the configuration output file with the default name in the specified directory. When migrating to Liberty the configuration will be saved to a server.xml file in the specified location. When migrating between WebSphere traditional versions a wsadmin script will be written in the specified location. 

java -jar binaryAppScanner.jar /myApp.ear --generateConfig --output=/GeneratedConfigOutput

When migrating from WebSphere traditional or a competitive application server to Liberty, a feature list is generated that contains the required features for each application. You may specify the --output parameter with a file name extension .xml. For example, the following command writes the server.xml with the specified name to the specified location. 

java -jar binaryAppScanner.jar /myApp.ear --generateConfig --output=/GenerateConfigOutput/NamedServer.xml
Figure 1. Liberty Configuration
Liberty Configuration

When migrating to Liberty, you may specify the --targetJavaEE option to affect which Java EE level of the Liberty features are included in the feature list. If you do not specify the --targetJavaEE option, the server.xml will include the latest available features version that support each of the scanned applications. The following command provides the Java EE 8 version of the liberty features detected in your application. 

java -jar binaryAppScanner.jar /myApp.ear --generateConfig --targetJavaEE=ee8

Migration from WebSphere traditional

When migrating from WebSphere traditional, additional configuration is generated if the binaryInputPath of the deployed application is found under the WebSphere traditional installation or a backup directory generated by the WASPreUpgrade command. The additional configuration is generated in a server.xml file for Liberty target servers and in a wsadmin script for WebSphere traditional target servers. 

java -jar binaryAppScanner.jar /myApp.ear --generateConfig --output=/GeneratedConfigOutput

To save the wsadmin script to a specific file, specify the --output parameter with a file name extension .py. For example, the following command writes the wsadmin script with the specified name to the specified location. 

java -jar binaryAppScanner.jar /myApp.ear --generateConfig --sourceAppServer=was80 --targetAppServer=was90 --output=/GenerateConfigOutput/NamedScript.py

All sensitive data, such as passwords, are replaced with variables in the generated configuration. When migrating to Liberty, if the configuration includes any sensitive data, a separate myApp_server_sensitiveData.xml file is generated with the sensitive data variables. When migrating to WebSphere traditional, the variables are defined at the top of the wsadmin script. The variable values are left blank unless the --includeSensitiveData option is provided, in which case the variable values is set to the WebSphere traditional values. 

java -jar binaryAppScanner.jar /myApp.ear --generateConfig --includeSensitiveData

If the application archive specified by the binaryInputPath parameter is located in a WebSphere traditional configuration, then the binary scanner will automatically produce the associated configuration. If the application archive is not located in a WebSphere traditional configuration, then use the --configLocation option to specify the location of the WebSphere traditional profile where the application is deployed. 

java -jar binaryAppScanner.jar /myApp.ear --generateConfig --configLocation=/wasinstallroot/profiles/profileName

When migrating from WebSphere traditional to Liberty, values of certain configuration elements that often differ between environments are replaced with variables to allow for easy substitution.

For best results with generated Liberty configuration, use the newest release of Liberty.

The following WebSphere traditional configuration is generated when migrating to Liberty and WebSphere traditional base edition.

  • JDBC - Supports Oracle, DB2 Universal, DB2 Using IBM JCC, Derby, Derby Network Server Using Derby Client, Microsoft SQL Server, and User-Defined JDBC Providers.
  • JMS - Connection factories, topics, queues and destinations are migrated. Remote connections are converted to local connections. Provider endpoint settings are not migrated.
  • Service Integration Bus - Creates the Service Integration Bus and messaging engines with filestores. Datastores will be converted to filestores.
  • JCA Authentication Alias - Authentication aliases specified in security domains are not migrated.
  • JNDI String Name Space Bindings
  • JVM Options
  • Session Management
  • LDAP Security - Supports federated and standalone LDAP repositories.
  • Security Role Bindings

The following WebSphere traditional configuration is generated only when migrating to Liberty.

  • Session Persistence to a Database
  • TLS/SSL - The resolved TLS/SSL configuration available to the application as well as any TLS/SSL configurations referenced by other migrated configuration and any active dynamic outbound configurations are migrated. For convenience, the keystore and truststore files themselves are copied to the output directory when --includeSensitiveData is specified.
  • Transactions
  • Transaction Recovery

Unresolvable Feature List

When the binary scanner attempts to generate a feature list during --generateConfig, --all, or --ta scans, sometimes the feature list is unresolvable. This happens when conflicting APIs are detected within the same application. Due to feature incompatibilities, the binary scanner cannot generate a final feature list.

Some Java EE 6 and Java EE 7 features are compatible with each other, but later levels of the Java EE and Jakarta EE specifications do not allow feature compatibility between specification levels. If you are using MicroProfile features, ensure the versions selected are compatible with the Java EE or Jakarta EE features in the list. For more information, see Liberty Features.

In some cases, application-required APIs might be provided by the application, and it is possible to remove the feature providing the API from the feature list. The inventory report gives insights on the APIs included in the application.

For cluster migration, view the messages within the server.xml to determine the conflicting features. These messages can help you determine which features are incompatible. If the feature list is unresolvable while generating configuration for a single application, you can set the --debug parameter to get more information on which features are having trouble resolving with one another. The information provided by --debug should be similar to the messages provided by starting a Liberty server configured with the same features listed in the server.xml. Starting a Liberty server with the unresolvable feature list can provide useful information for debugging a valid feature list.