Tomcat Config Migration

Transcription

1 WebSphere Application Server Tomcat Config Migration IBM WebSphere Application Server Migration Toolkit Version Tech Preview IBM Software Group, Application and Integration Middleware Software Copyright IBM Corp. 2013

2 2 Contents Contents Overview... 3 Support...4 Installing the migration tool...5 Running the migration tool for a Tomcat server... 7 Running the migration tool for an application Configuration migration details Troubleshooting Known issues...19 Copyright and trademarks...20

3 Overview 3 Overview The IBM WebSphere Application Server Migration Toolkit - Tomcat Config Migration Tech Preview assists in moving Apache Tomcat server configuration and application configuration to the WebSphere Application Server Liberty profile. This document explains how to install, configure, and use the tool to assist in the migration process. The tool migrates a subset of the Apache Tomcat server configuration and configuration within Java Platform, Enterprise Edition (Java EE) applications. This migration tool supports: Migrating from Apache Tomcat 7 Migrating to WebSphere Application Server V8.5.Next Beta Liberty Profile Migrating tomcat-users from conf/tomcat-users.xml Migrating HTTP/1.1 Connectors from conf/server.xml Migrating Standard Manager from conf/context.xml Migrating Resource configuration for Apache Derby and IBM DB2 from conf/server.xml, conf/context.xml, and the application META-INF/context.xml Migrating Resource configuration for IBM WebSphere MQ and Apache ActiveMQ from conf/server.xml, conf/ context.xml, and the application META-INF/context.xml Migrating security-constraints from the application WEB-INF/web.xml The tool was tested with the following versions of the before mentioned products: Apache Tomcat Apache ActiveMQ Apache Derby IBM DB IBM WebSphere MQ 7.0 WebSphere Application Server V8.5.Next Beta Liberty Profile WebSphere Application Server Developer Tools for Eclipse V9.0 Beta Eclipse for Java EE Developers (Juno SR2) Microsoft Windows 7 and Windows XP The WebSphere Application Server V8.5 Migration Guide is available with comprehensive information on migration topics related to WebSphere Application Server. It uses the WebSphere Application Migration Toolkit in its examples to migrate Java Platform, Enterprise Edition (Java EE) applications, and provides a wealth of information. The Tomcat Config Migration Tech Preview can be used to migrate the Tomcat server configuration and application configuration that previously had to be done manually.

4 4 Support Support The Tomcat Config Migration Tech Preview migrates a subset of the Apache Tomcat server configuration and application configuration to WebSphere Application Server V8.5.Next Beta Liberty Profile. Specific details on which configuration elements are migrated are documented in the section, Configuration migration details on page 13. The tool does not migrate all configuration. As you identify additional configuration that you would like migrated, provide that feedback through the Application Migration Tool forum, which is available to provide input and get questions answered. ( The tool is provided as-is. Refer to the forum for feedback and questions.

5 Installing the migration tool 5 Installing the migration tool The WebSphere Application Server Migration Toolkit provides tools as Eclipse features that you install into an existing Eclipse environment. The Tomcat Config Migration Tech Preview is supported on Eclipse for Java EE Developers (Juno SR2) available from Other prerequisites: Application Migration Tool - Apache Tomcat to WebSphere available from websphere/downloads/migtoolkit/ WebSphere Application Server V8.5.Next Beta Liberty Profile available from WebSphere Application Server Developer Tools for Eclipse V9.0 Beta available from To install this configuration migration tool, perform the following steps: 1. Download the Tomcat Config Migration Tech Preview repository and save it locally. The repository is available from the WASdev - WebSphere Application Server Developer Community site Navigate to Download > Early Access Releases. 2. Start Eclipse. 3. Install the Tomcat Config Migration Tech Preview in Eclipse. a) Select Help > Install New Software... to open the installation dialog to install the Configuration Migration Tool. b) Click Add to point to your downloaded update site file. c) In the Add Site window, enter the following information, which is shown in Figure 1: Tool installation. Name: Tomcat Config Migration Tool Location: Use the Archive button to find the compressed file you downloaded. Figure 1: Tool installation d) Click OK. 4. Complete the following actions in the Install window, which is shown in Figure 2: Select Plug-In. a) Select the check box for Configuration Migration Tool. b) Select the check box to Contact all update sites during install to find required software, and click Next. 5. Click Next on the Install Details panel. 6. On the Review Licenses panel, read the terms and accept the license agreements. Click Finish. The install status window shows the installation progress.

6 Figure 2: Select Plug-In 7. Restart the IDE when the Software Updates window is displayed. Figure 3: Restart dialog

7 Running the migration tool for a Tomcat server 7 Running the migration tool for a Tomcat server First the tool should be used to migrate the Apache Tomcat server configuration. Then the tool should be used to migrate application configuration. For migrating the server configuration, you can run the tool from several views. You can access the options in the Eclipse Run menu, in the explorer pop-up menus, and in the Servers pop-up menus. The following figure demonstrates the different ways you can run the server configuration migration using the tool. Please note that the Liberty profile server must already exist in Eclipse before running this tool. From the Eclipse menu: From the explorer pop-up menu: From the Servers pop-up menu: Figure 4: Options for running the tool to migrate server configuration To migrate the server configuration using the Run menu, complete the following steps: 1. Select Run > Tomcat Configuration Migration... to display the Tomcat server selection dialog.

8 8 Running the migration tool for a Tomcat server 2. In the Tomcat server selection dialog, browse to the location of the Tomcat server installation. Then, click OK. The Liberty server selection dialog appears. 3. In the Liberty server selection dialog, select the target Liberty profile server for the migration and click OK. A completion dialog appears containing information on the generated configuration, and the Liberty profile server workspace is refreshed.

9 Running the migration tool for a Tomcat server 9 The selected Liberty profile server now contains updated configuration. The server.xml contains an include of migratedconfig/server-updates-for-config.xml as shown below. The updated configuration includes the following files: server.xml migratedconfig/configmigration.log migratedconfig/context.xml migratedconfig/server.xml migratedconfig/server.xml.original migratedconfig/server-updates-for-config.xml Liberty profile server configuration file updated to include the migrated configuration file migratedconfig/ server-updates-for-config.xml Information on the migration. Configuration from the Tomcat context.xml Configuration from the Tomcat server.xml Copy of original Liberty server.xml before the migration. High level include file.

10 migratedconfig/users-and-roles.xml Configuration from Tomcat tomcatusers.xml

11 Running the migration tool for an application 11 Running the migration tool for an application After migrating the Apache Tomcat server configuration, the tool should be used to migrate application configuration. Please note that the application WAR file must already be imported into Eclipse before running this tool. Also, the application source (which can include Java source code, JavaServer Pages (JSP), and deployment descriptors) should have already been migrated using the Application Migration Tool Tomcat to WebSphere. For additional information on the Application Migration Tool Tomcat to WebSphere see migtoolkit/ To migrate the application configuration, complete the following steps: 1. Select the application project in the Explorer view. 2. Right-click and select Migrate Tomcat Configuration... The Liberty server selection dialog appears. 3. In the Liberty server selection dialog, select the target Liberty profile server for the migration and click OK. A completion dialog appears containing information on the generated configuration, and the Liberty profile server workspace is refreshed.

12 The selected Liberty profile server now contains updated configuration. The server.xml contains an include of serverupdates-for-application.xml as shown below. The updated configuration includes the following files: server.xml migratedconfig/[application-name]/configmigration.log migratedconfig/[application-name]/application-config-web.xml migratedconfig/[application-name]/server.xml.original Liberty profile server configuration file updated to include the migrated configuration file migratedconfig/ [application-name]/server-updates-forapplication.xml migratedconfig/[application-name]/application-configcontext.xml migratedconfig/[application-name]/server-updates-forapplication-config.xml Information on the migration. Configuration from the application META-INF/context.xml Configuration from the application WEB-INF/web.xml Copy of original Liberty server.xml before the migration. High level include file.

13 Configuration migration details 13 Configuration migration details Mapping of files, elements and attributes When using Tomcat, certain configuration required by an application can be located in the server.xml or context.xml located in the Tomcat conf directory. Additional configuration can be in the META-INF/context.xml or WEB-INF/ web.xml of the application. Without this tool, that configuration would have to be migrated manually to the Liberty profile server configuration. Details on which configuration elements are migrated by this tool are contained in the tables below. The following table documents the configuration elements migrated from conf/tomcat-users.xml. Tomcat Configuration Element (located in conf/ tomcat-users.xml) Liberty Configuration Element (generated in migratedconfig/users-androles.xml) List of migrated attributes (Tomcat attribute = Liberty attribute) tomcat-users/role basicregistry/group rolename = name tomcat-users/user basicregistry/user The following table documents the configuration elements migrated from conf/server.xml. username = name password = password (hash encoded using securityutility.bat) roles = group/ member[@name] (a group member is created for each role) Tomcat Configuration Element (located in conf/ server.xml) Service/Connector with type HTTP/1.1 and scheme attribute http Service/Connector with type HTTP/1.1 and scheme attribute https Liberty Configuration Element (generated in migratedconfig/server.xml) httpendpoint httpendpoint List of migrated attributes (Tomcat attribute = Liberty attribute) port = httpport redirectport = httpsport = host connectiontimeout = httpoptions/@persisttimeout maxthreads = socket.soreuseaddress = tcpoptions/@soreuseaddr port = httpsport = host connectiontimeout = httpoptions/@persisttimeout maxthreads =

14 14 Configuration migration details Tomcat Configuration Element (located in conf/ server.xml) Resource with driverclassname 'org.apache.derby.jdbc.embeddeddriver' Resource with driverclassname 'com.ibm.db2.jcc.db2driver' Liberty Configuration Element (generated in migratedconfig/server.xml) datasource datasource List of migrated attributes (Tomcat attribute = Liberty attribute) socket.soreuseaddress = tcpoptions/@soreuseaddr name = jndiname username = password = (xor encoded using securityutility.bat) url defaulttransactionisolation = isolationlevel maxactive = maxidle = maxwait = name = jndiname username = properties.db2.jcc/@user password = properties.db2.jcc/@password (xor encoded using securityutility.bat) url @portnumber defaulttransactionisolation = isolationlevel maxactive = maxidle =

15 Configuration migration details 15 Tomcat Configuration Element (located in conf/ server.xml) 'org.apache.activemq.activemqconnectionfactory' 'org.apache.activemq.command.activemqtopic' 'org.apache.activemq.command.activemqqueue' 'com.ibm.mq.jms.mqconnectionfactory' 'com.ibm.mq.jms.mqqueueconnectionfactory' 'com.ibm.mq.jms.mqtopicconnectionfactory' 'com.ibm.mq.jms.mqtopic' 'com.ibm.mq.jms.mqqueue' Liberty Configuration Element (generated in migratedconfig/server.xml) jmsconnectionfactory jmstopic jmsqueue jmsconnectionfactory jmsqueueconnectionfactory jmstopicconnectionfactory jmstopic jmsqueue List of migrated attributes (Tomcat attribute = Liberty attribute) maxwait = name = jndiname name = jndiname id = jndiname physicalname = name = jndiname id = jndiname physicalname = name = jndiname name = jndiname name = jndiname name = jndiname TOP or TOPIC = name = jndiname QU or QUEUE = The following table documents the configuration elements migrated from conf/context.xml. Tomcat Configuration Element (located in conf/ context.xml) Manager with classname 'org.apache.catalina.session.standardmanager' Liberty Configuration Element (generated in migratedconfig/ context.xml) httpsession List of migrated attributes (Tomcat attribute = Liberty attribute) maxactivesessions = maxinmemorysessioncount maxinactiveinterval = invalidationtimeout sessionidlength = idlength

16 16 Configuration migration details Tomcat Configuration Element (located in conf/ context.xml) Liberty Configuration Element (generated in migratedconfig/ context.xml) List of migrated attributes (Tomcat attribute = Liberty attribute) processexpiresfrequency = forceinvalidationmultiple Resource with driverclassname 'org.apache.derby.jdbc.embeddeddriver' Resource with driverclassname 'com.ibm.db2.jcc.db2driver' 'org.apache.activemq.activemqconnectionfactory' 'org.apache.activemq.command.activemqtopic' 'org.apache.activemq.command.activemqqueue' 'com.ibm.mq.jms.mqconnectionfactory' 'com.ibm.mq.jms.mqqueueconnectionfactory' 'com.ibm.mq.jms.mqtopicconnectionfactory' datasource datasource jmsconnectionfactory jmstopic jmsqueue jmsconnectionfactory jmsqueueconnectionfactory jmstopicconnectionfactory 'com.ibm.mq.jms.mqtopic' jmstopic 'com.ibm.mq.jms.mqqueue' jmsqueue The following table documents the configuration elements migrated from the application META-INF/context.xml. Tomcat Configuration Element (located in META-INF/context.xml of application) Resource with driverclassname 'org.apache.derby.jdbc.embeddeddriver' Liberty Configuration Element (generated in migratedconfig/ [application-name]/ application-configcontext.xml) datasource List of migrated attributes (Tomcat attribute = Liberty attribute)

17 Configuration migration details 17 Tomcat Configuration Element (located in META-INF/context.xml of application) Liberty Configuration Element (generated in migratedconfig/ [application-name]/ application-configcontext.xml) List of migrated attributes (Tomcat attribute = Liberty attribute) Resource with driverclassname 'com.ibm.db2.jcc.db2driver' 'org.apache.activemq.activemqconnectionfactory' 'org.apache.activemq.command.activemqtopic' 'org.apache.activemq.command.activemqqueue' 'com.ibm.mq.jms.mqconnectionfactory' 'com.ibm.mq.jms.mqqueueconnectionfactory' 'com.ibm.mq.jms.mqtopicconnectionfactory' datasource jmsconnectionfactory jmstopic jmsqueue jmsconnectionfactory jmsqueueconnectionfactory jmstopicconnectionfactory 'com.ibm.mq.jms.mqtopic' jmstopic 'com.ibm.mq.jms.mqqueue' jmsqueue The following table documents the configuration elements migrated from the application META-INF/web.xml. Tomcat Configuration Element (located in WEB- INF/web.xml of application) web-app/security-constraint/auth-constraint Liberty Configuration Element (generated in migratedconfig/ [application-name]/ application-config-web.xml) application/application-bnd/ security-role List of migrated attributes (Tomcat attribute = Liberty attribute) role-name = name Additional information on migration of JMS Resources In order to support the migration of JMS applications, Tomcat Resources related to WebSphere MQ and Apache ActiveMQ are migrated to the Embedded Liberty Messaging features and related configuration elements in the Liberty profile server. The applications must use JMS interfaces to function properly when configured to use the Liberty embedded messaging engine.

18 Additional information on migration of database Resources In order to support the migration of applications utilizing databases, Tomcat Resources related to IBM DB2 and Apache Derby are migrated to datasource configuration elements in the Liberty profile server. For Apache Derby, the generated configuration expects to find derby.jar in the ${shared.resource.dir} of the Liberty profile server. Either copy the jar file to that location, or modify the generated configuration to point to the location of the jar file. For IBM DB2, the generated configuration expects to find db2jcc4.jar and db2jcc_license_cu.jar in the ${shared.resource.dir} of the Liberty profile server. Either copy the jar file to that location, or modify the generated configuration to point to the location of the jar file.

19 Troubleshooting 19 Troubleshooting Known issues Problem migrating JMS applications When migrating certain JMS applications, a CoreException is received when publishing the application to the Liberty profile server. The migrated configuration files are still generated successfully, and the JMS application can be placed in the dropins folder of the Liberty server to workaround the publish exception. Liberty Server Selection dialog is empty The Liberty Server Selection dialog is populated with Liberty profile servers found in the Servers view of Eclipse. If no Liberty profile servers are present, the selection dialog will be empty. You need to Cancel the migration and add a Liberty profile server to Eclipse before proceeding. Application receives a SQLException The generated datasource configuration expects to find the necessary database jar files in {shared.resource.dir}. Either copy the relevant jar files into that directory, or change the datasource configuration in the Liberty profile server to point to a different location. Application receives a CWNEN0030E exception The following error appears in the Console: [ERROR ] CWNEN0030E: factory encountered a problem getting the object instance jndi_jms_base_qcf binding object. The exception message was: failed to resolve jndi_jms_base_qcf to javax.jms.queueconnectionfactory: javax.naming.namenotfoundexception: jndi_jms_base_qcf. To resolve this, select the Liberty profile server in the Servers view, right click and select Clean Server on Next Start. Then restart the Liberty profile server. User Input Required dialog appears during application configuration migration During application configuration migration, a User Input Required dialog appears stating that some required features are missing. The prompt asks if you want to add them to the configuration. You can safely select No. The migration tool will add all necessary features to the generated configuration.

20 20 Copyright and trademarks Copyright and trademarks Copyright IBM Corporation The information contained in this publication is provided for informational purposes only. While efforts were made to verify the completeness and accuracy of the information contained in this publication, it is provided AS IS without warranty of any kind, express or implied. In addition, this information is based on IBM's current product plans and strategy, which are subject to change by IBM without notice. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, this publication or any other materials. Nothing contained in this publication is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software. References in this publication to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. Product release dates and/or capabilities referenced in this presentation may change at any time at IBM's sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. Nothing contained in these materials is intended to, nor shall have the effect of, stating or implying that any activities undertaken by you will result in any specific sales, revenue growth, savings or other results. Performance is based on measurements and projections using standard IBM benchmarks in a controlled environment. The actual throughput or performance that any user will experience will vary depending upon many factors, including considerations such as the amount of multiprogramming in the user's job stream, the I/O configuration, the storage configuration, and the workload processed. Therefore, no assurance can be given that an individual user will achieve results similar to those stated here. IBM, the IBM logo, developerworks, Passport Advantage, Rational, and WebSphere are trademarks of International Business Machines Corporation in the United States, other countries or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates. Other product and service names might be trademarks of IBM or other companies.