xcp Application Deployment On Tomcat Cluster

xcp Application Deployment On Tomcat Cluster Abstract This white paper explains how to install and configure tomcat cluster to support High Availability and Load Balancing and enable one way SSL with xcp. January 2014 EMC WHITE PAPER 1

Copyright 2014 EMC Corporation. All Rights Reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. The information in this publication is provided as is. EMC Corporation makes no representations or warranties of any kind with respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a particular purpose. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. VMware is registered trademarks of VMware, Inc. in the United States and/or other jurisdictions. All other trademarks used herein are the property of their respective owners. Part Number h12687 2

Table of Contents Executive summary... 4 Audience... 5 Terminology... 5 Pre-Requisite... 5 Installing and configuring tomcat server cluster... 5 Installing and configuring tomcat instances in cluster... 6 Configuring tomcat cluster instances for deployment of xcp application... 7 Configuring Apache HTTP webserver as LB for Tomcat cluster 11 Deployment of xcp application on tomcat cluster... 13 Pre-requisites:... 13 Configuring xcp Designer to deploy xcp application... 13 xcp application deployment using xms Tools... 16 Enabling SSL on tomcat server cluster instances... 17 Enabling SSL on primary tomcat instance... 18 Enabling SSL on Apache HTTP webserver... 20 Conclusion... 23 References... 23 3

Executive summary This white paper covers the following points: Setting up tomcat instances in cluster Configuring Apache HTTP webserver as Load Balancer Deploying xcp application on the tomcat cluster environment Enabling SSL for xcp Application deployed on tomcat server cluster Session replication When a client, typically using a browser, connects to a tomcat Server instance, tomcat Server creates a session Object that it uses to manage all subsequent interaction between itself and that client. Typical web applications use the Http Session object to temporarily store user specific information like shopping cart items, security credentials, etc. If the tomcat Server instance is part of a cluster, the session is automatically copied to each member of the cluster group, and is updated each time the session is modified, such as when the user adds a new item to their shopping cart. This means that if the first tomcat Server instance crashes, any of the other tomcat Server instances in the group can immediately take over the session without interruption, completely hiding the server crash from the client who continues to work as if nothing had happened. This greatly increases the usability of Web applications. Context attribute replication A context represents a Web application that is deployed to a tomcat Server instance. In the same way that client sessions can be replicated, the Web application context itself can also be replicated to all members of a cluster group Load Balancing You might also want to configure a load balancer in front of the cluster so as to split up the incoming requests between multiple tomcat Server instances. Load balancing attempts to direct requests to the tomcat Server with the smallest load at that point in time. The load balancer can also detect when a tomcat Server has failed, in which case it stops directing requests to it until the tomcat Server restarts, adding to the high availability of tomcat Server 4

Audience This white paper is intended for EMC support personnel, professional services, customers, partners, internal developers and engineers who wants to setup tomcat cluster environment and deploy an xcp application. It is organized in a set of steps that are easy to follow. Whenever required, a reference to other published guide is provided in order to avoid the duplication of information. Terminology Special terms, abbreviations and acronyms that may appear in this guide are defined below. CS CONTENT SERVER XCP XCELERATED COMPOSITION PLATFORM SSL SECURE SOCKET LAYER HA HIGH AVAILABILITY LB LOAD BALANCER Pre-Requisite Install JDK and set the Java path in all application server nodes. Installing and configuring tomcat server cluster Cluster consists of a set of physical or virtual machines that work together to achieve high availability and reduce down time. Load balancing is a method to distribute load evenly across multiple nodes and failover is the technique to switch over automatically when one node fails to a second node which is setup as redundant or standby. Tomcat load balancing means that subsequent client requests are distributed among two or more Tomcat in order to share the load. Failover of Tomcat means that if one Tomcat instance serving the request goes down, the requests are switched to second Tomcat instance in the cluster ensuring High Availability. In the current load balance setup we will provide instruction for load balance and Failover simultaneously. 5

Installing and configuring tomcat instances in cluster 1. Install Primary tomcat instance on Machine1 2. Install secondary tomcat instance on Machine2 Note: You can install and configure multiple tomcat instances based on your requirement. For each tomcat instance that will be member of cluster update its Server.xml file present inside $CATALINA_HOME\conf as below <Engine name="catalina" defaulthost="localhost" jvmroute="worker1" <Cluster classname="org.apache.catalina.ha.tcp.simpletcpcluster" channelsendoptions="8"> <Manager classname="org.apache.catalina.ha.session.deltamanager" expiresessionsonshutdown="false" notifylistenersonreplication="true"/> <Channel classname="org.apache.catalina.tribes.group.groupchannel"> <Membership classname="org.apache.catalina.tribes.membership.mcastservice" address="228.0.0.5" port="45123" frequency="500" droptime="3000"/> <Receiver classname="org.apache.catalina.tribes.transport.nio.nioreceiver" address="auto" port="4000" autobind="100" selectortimeout="5000" maxthreads="6"/> <Sender classname="org.apache.catalina.tribes.transport.replicationtransmitter"> <Transport classname="org.apache.catalina.tribes.transport.nio.pooledparallelsender "/> </Sender> <Interceptor classname="org.apache.catalina.tribes.group.interceptors.tcpfailuredetec tor"/> <Interceptor classname="org.apache.catalina.tribes.group.interceptors.messagedispatch 15Interceptor"/> 6

</Channel> <Valve classname="org.apache.catalina.ha.tcp.replicationvalve" filter=".*\.gif;.*\.js;.*\.jpg;.*\.png;.*\.css;.*\.txt;"/> <ClusterListener classname="org.apache.catalina.ha.session.clustersessionlistener"/> </Cluster> Configuring tomcat cluster instances for deployment of xcp application 1. Create and copy the dfc.properties file for the application to reference the repository as follows: Create a Customconf folder at the root of the application server instance: <application_server_home>\customconf Copy the dfc.properties file from the c:\documentum\config folder from the Content Server to the above location 2. Open the dfc.properties file in <application_server_home>\customconf and add the following parameter: dfc.session.allow_trusted_login = false Save your changes. 3. Include the dfc.properties folder location in the Java Classpath. For example, edit <application_server_home>\bin\setclasspath.bat and add the entry as shown in the following code sample: # Java Classpath... set "CLASSPATH=%CLASSPATH%<app_server_home>\Customconf" 4. When configuring the xcp application host, perform the following steps: a. Extract the bam-server.war file you downloaded and open bamserver.properties. b. Remove the comment symbol (#) from the following lines and enter values for your environment: 7

# bam.server.host=localhost # bam.server.port=8010 # bam.server.context=bam-server If you deploy the BAM Server in a clustered environment, specify the IP address and port details of the load balancer for BAM. c. If you deploy BAM in SSL mode, locate the bam.server.protocol property and change it to https. d. If the bam.server.protocol property is not available, type bam.server.protocol = https and save your changes. e. Copy the bam-server.properties file to the Customconf folder in the application server home directory. In this case, <application_server_home>\customconf. 5. In Catalina.bat located in <application_server_home>\bin, set the JAVA_OPTS parameter by adding the following lines: set JAVA_OPTS=-Xms1024m -Xmx2048m -XX:MaxPermSize=512m - XX:+UseParallelOldGC -Xdebug -Xnoagent - Xrunjdwp:transport=dt_socket,server=y,suspend=n -Dbam.properties=<application_server_home>\bam\bam.properties - Dlog4j.configuration=file:///<application_server_home>\bam\log4j.prop erties 6. Open web.xml located under <application_server_home>\conf and disable the enablepooling element by adding the below entries <init-param> <param-name>enablepooling</param-name> <param-value>false</param-value> </init-param> 7. Create a user for the Tomcat instance. This user uses xcp Designer to deploy the xcp application. For example, edit <application_server_home>\conf\tomcatusers.xml and add a user name and password as shown in the following code sample: <?xmlversion="1.0"?> 8

<tomcat-users> <user name="user_name" password="password" roles="admin-gui, managergui,manager-script" /> </tomcat-users> Open the file in a browser to check for well-formed XML 8. Edit the <application_server_home>\conf\context.xml file and set the Context xml node to the following: <Context antijarlocking="true" antiresourcelocking="true"> This step allows you to remotely deploy or undeploy web applications on the application server. Open the file in a browser to check for well-formed XML 9. Add the xcp runtime library to the application server instance by following the below steps a. Download the Documentum xcp ZIP file from EMC Online Support https://support.emc.com. b. On the application server on which you intend to deploy the xcp application: For Tomcat, stop the application server. c. Extract the contents of the zip file to the application server lib folder. The following example shows the path to the folder in a tc Server application server instance: <application_server_home>\<server_instance>\lib The following example shows the path to the folder in the Tomcat application server home: <application_server_home>\lib 10. For Tomcat, ensure that your application server instance has UTF-8 set for URI encoding. If it does not, edit the server.xml file as follows: <Connector port="8080" URIEncoding="UTF-8" protocol="http/1.1" connectiontimeout="2000/> 11. Deploy the Application Manager to the application server instance. Below are the steps: Download the xms-tools.zip file to your local system. Extract the xms-tools.zip file to a folder. This extraction places a manager.war file in that folder 9

Copy the manager.war file to the <application_server_home>\webapps folder Note: For a clustered environment with multiple tomcat instances, repeat the above steps on each tomcat nodes. 12. For a clustered environment with multiple Tomcat nodes, modify clustering configuration in server.xml to support FarmWarDeployer capability. a. Within the <Host> element, add a <Cluster> element. b. Within the <Cluster> element, add a <Deployer> element. c. Within the <Deployer> element, set attributes exactly as follows: classname="org.apache.catalina.ha.deploy.farmwardeployer" watchenabled="true" d. Specify unique values for three additional <Deployer> attributes: Attribute Description tempdir- Specify a temporary folder for the system to store uploaded xcp applications. watchdir- Specify the folder for the system to copy the xcp war file in a cluster node. deploydir- Specify the \<application_server_home>\webapps folder. These folders are mandatory for the FarmWarDeployer class. The following is an example configuration: <Host > <Cluster > <Deployer classname="org.apache.catalina.ha.deploy.farmwardeployer" tempdir="c:/temp/war-temp" deploydir="c:/tcserver/apphost/webapps" watchdir="c:/temp/war-listen" watchenabled="true" /> </Cluster> </Host> 10

Configuring Apache HTTP webserver as LB for Tomcat cluster There have been a number of connectors developed to enable Apache httpd to communicate with Tomcat that have used a variety of protocols. In this guide, we ll cover majorly used connector mod_jk Configuring load balancing between Apache HTTP Server and tomcat Server using mod_jk Mod_jk is the Apache HTTPD module that will be used to provide our cluster with its load balancing and proxy capabilities. It uses the AJP protocol to facilitate fast communication between Tomcat servers and the Apache Web Server that will receive the client requests This Section provides information on configuring the Apache HTTP Server and tomcat Server using mod_jk load balancing. It also provides information on using sticky sessions to send all requests associated with a particular session to the same tomcat Server worker. Below are the steps to configure Apache HTTP server as LB: 1. Install Apache webserver. 2. Download and install mod_jk. 3. We'll have to set up the mod_jk module in Apache HTTPD's configuration files. This configuration is a two step process, and can be a little confusing, as mod_jk does not separate its proxy capabilities from its load balancing capabilities. First, let's configure the module itself. This is done by adding a few lines to the main Apache HTTPD configuration file, httpd.conf. Take a look at this example configuration 4. Copy mod_jk inside $APACHE_HOME\modules 5. In httpd.conf file add the below lines to include mod_jk.conf which calls mod_jk module Include conf/mod_jk.conf 6. Edit httpd.conf and uncomment the below required modules if commented LoadModule proxy_ajp_module modules/mod_proxy_ajp.so LoadModule proxy_balancer_module modules/mod_proxy_balancer.so LoadModule proxy_connect_module modules/mod_proxy_connect.so LoadModule proxy_ftp_module modules/mod_proxy_ftp.so LoadModule proxy_http_module modules/mod_proxy_http.so 11

7. Create workers.properties file in the conf folder present inside $APACHE_HOME and add the below configurations to it: # Define list of workers that will be used for mapping requests worker.list=loadbalancer # Set properties for loadbalancer (ajp13 ) worker.loadbalancer.type=lb worker.loadbalancer.balance_workers=worker1,worker2 #worker.loadbalancer.sticky_session=true worker.loadbalancer.method=b worker.loadbalancer.sticky_session=1 #worker.loadbalancer.sticky_session=jsessionid jsessionid # Set properties for worker1 (AppServer1) worker.worker1.type=ajp13 worker.worker1.host=appserver1 hostname/ip worker.worker1.port=8009 worker.worker1.lbfactor=1 #worker.worker1.cachesize=10 #worker.worker1.cache_timeout=600 #worker.worker1.socket_keepalive=1 #worker.worker1.recycle_timeout=300 #worker.worker1.redirect=worker2 #worker.worker1.activation=act # Set properties for worker2 (AppServer2) worker.worker2.type=ajp13 worker.worker2.host= AppServer2/ip worker.worker2.port=8010 worker.worker2.lbfactor=1 #worker.worker2.cachesize=10 #worker.worker2.cache_timeout=600 #worker.worker2.socket_keepalive=1 #worker.worker2.recycle_timeout=300 #worker.worker2.activation=active 12

NOTE: Worker1 and worker 2 are the application server instances which will be used as a worker for serving the user requests. You should add more application server nodes as per requirement. 8. Add the below lines in mod_jk.conf file #Add below lines to add mod_jk module LoadModule jk_module modules/mod_jk.so # Update this path to match your conf directory location (put workers.properties next to httpd.conf) JkWorkersFile conf/workers.properties # Update this path to match your logs directory location (put mod_jk.log next to access_log) JkLogFile logs/mod_jk.log # Set the jk log level [debug/error/info] JkLogLevel debug # Select the log format JkLogStampFormat "[%a %b %d %H:%M:%S %Y] " # JkOptions indicate to send SSL KEY SIZE, #JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories # JkRequestLogFormat set the request format JkRequestLogFormat "%w %V %T" # Send everything for context /portal to worker named loadbalancer (ajp13) JkMount /xcp_application_name* loadbalancer Deployment of xcp application on tomcat cluster Pre-requisites: Prerequisites for deploying an xcp Application are The xms Agent installed The xcp Environment is registered For detailed instructions on how to register the environment in xms Agent, Please refer to the xcp Deployment guide Configuring xcp Designer to deploy xcp application The following configurations have to be done on xcp Designer to deploy xcp application in a manually-provisioned environment or xmsprovisioned environment. 13

1. Open xcp Designer 2. Click on the preference button in xcp Designer as shown in Figure 1 3. In the preferences dialog box on Deployment Environments screen click on Add button located on right hand side to add your xms Agent as shown in Figure 2 4. In the "Add Deployment Environment" screen, enter the environment name and the xms Agent details deployed. Click on the "Test Connection" button as shown in Figure 21 to check if you can connect to xms Agent with the specified details. If this validation succeeds you will see a notification saying "Connection valid". Click on Finish button. 14

Note: Default password of xms Agent in xms-provisioned environment is adminpass1 5. Click on the Run Configurations option on the left pane in preferences, and click add button to specify the data policy as shown in Figure 15

6. In run configuration dialog box specify the run name and the datapolicy for the deployment as per the mode. If the mode is production the data policy maintain should be used. For Development mode the default data policy can be used. 7. On successful addition of xms Agent in preference, user can create and deploy application to xms Agent. Please refer to the EMC Documentum xcelerated Composition Platform Deployment Guide for more details on deploying an application using xcp Designer. xcp application deployment using xms Tools User can deploy xcp applications using xms Tools through CLI. Usually this option is used in Production mode or when we deploy xcp application into clustered environments. Do the following to deploy an xcp application: Prerequisites for CLI deployment For deploying xcp application in CLI mode, the user should have the WAR file and the configuration xml file. Please refer to the EMC Documentum xcelerated Composition Platform Deployment Guide for details of generating the war file of the xcp application. 1. Go to <xms tools-home>\config folder, Open xms-server.properties file and make sure that the xms Server host and port are pointing to the desired xms Agent. 2. Go to <xms tools-home>\bin and double-click on xms.bat file. 3. On the prompt, enter the admin password for xms Agent. (The default password of xms-provisioned xms Agent is adminpass1 ). 4. On the xms console run the "deploy-xcp-application" command as illustrated in Figure 24 to deploy xcp application. 16

Note: The default data policy is Maintain if the mode is production. In the command mentioned above the environment name is optional only when xms Server is used as xms Agent. If there are any service endpoint related errors while deploying, user can edit the registered environment to make the necessary changes. "Modifying or adding endpoints to environment" sections has the details Enabling SSL on tomcat server cluster instances Servers and browsers rely on the Secure Sockets Layer (SSL) protocol to help users protect their data during transfer by creating a uniquely encrypted channel for private communications over the public Internet. Each SSL Certificate consists of a key pair as well as verified identification information. When a client points to a secured server, the server shares the public key with the client to establish an encryption method and a unique session key. The client confirms that it recognizes and trusts the issuer of the SSL Certificate. This process is known as the SSL handshake and it begins a secure session that protects message privacy and message integrity. If the application is to be accessed ion secured mode below steps need to be followed to enable the SSL on Application Server and Web server. It is assumed that you understand basic SSL concepts such as certificates, public and private keys, keystores, and truststores. It is 17

also assumed that you know how to get a certificate from a trusted certificate authority or how to generate your own. The main focus in this section is how to update the Tomcat Server configuration so that the server uses your certificate Typically, when an Apache web server is used to load balance requests to one or more tomcat Server, the SSL encryption and certificate authentication is terminated at the web server. Communication between the Apache web server and Tomcat server is then trusted and in clear text Enabling SSL on primary tomcat instance Below are the basics steps for securing the Tomcat Server when connecting to it over HTTPS. NOTE: Self signed certificate is required only if you do not have CA certificate from a trusted certificate authority (CA) such as VeriSign. Generate Certificate: 1. Create a keystore for Primary server by executing the below command through command line. It can be created by using Java keytool utility. keytool.exe -genkey -alias AS1 -keyalg RSA -keystore AS1.keystore This command will prompt for some details mentioned below. Type the full hostname of the ACS server machine for common name (first and last name). Give other details accordingly. Enter keystore password: Re-enter new password: What is your first and last name? [Unknown]: AS1.iig.com What is the name of your organizational unit? [Unknown]: IIG What is the name of your organization? [Unknown]: EMC What is the name of your City or Locality? [Unknown]: Pleasanton What is the name of your State or Province? [Unknown]: CA What is the two-letter country code for this unit? [Unknown]: US 18

Is CN= acsmachine.dnsname.com, OU=emc, O=emc, L=Pleasanton, ST=CA, C=US correct? [no]: yes Enter key password for <AS1> (RETURN if same as keystore password): (Here, alias name is AS1 and keystore name is AS1.keystore. User can choose anything for these names.) Note: Keystore can be created using Documentum/xcp supported java version. For machine name use fully configured domain name. 2. Modify server.xml to enable SSL and server to use HTTPS protocol. Uncomment the below line or add if not present in $APPLICATION_SERVER_HOME\conf\server.xml <Connector port="8443" protocol="http/1.1" SSLEnabled="true" maxthreads="150" scheme="https" secure="true" clientauth="false" sslprotocol="tls" keystorefile="c:/certificate/as1" keystorepass="changeit"/> When using JSSE configuration, APR library loader needs to be commented: <Listener classname="org.apache.catalina.core.aprlifecyclelistener" SSLEngine="on" /> NOTE : In the above xml code modify the keystorefile, KeystorePass and keyalias and provide the one which you have given while creating keystore. You should repeat the above steps for all the tomcat server nodes/instance to enable SSL on tomcat server cluster. 3. Restart APPHOST. 4. Generate the APPHOST certificate by using AS1.keystore. Use the below command through command line. From <java_home>/bin keytool.exe export alias AS1cert file AS1.cer keystore apphost.keystore 5. Repeat the above steps if we have multiple nodes of tomcat instances 6. Import appserver certificate (exported in step4) into running java in the client machine by using the below command through command line. keytool.exe -import -noprompt -trustcacerts -alias apphostcert -file "C:\certificate\AS1.cer" -keystore "<java>/jre/lib/security/cacerts" 19

It will prompt for keystore password. Give the default password for java truststore cacerts that is changeit 7. Access APPHOST url with https protocol and SSL port https://<appserver.dnsname.com>:port/<xcp-application-name> NOTE: You should repeat the above steps for all the tomcat server instances in the cluster to enable SSL. Enabling SSL on Apache HTTP webserver 1. Install Apache webserver using openssl installer. 2. Navigate to C:\$APACHE_HOME\conf and do the following changes in httpd.conf Uncomment the following modules if commented LoadModule ssl_module modules/mod_ssl.so LoadModule proxy_ajp_module modules/mod_proxy_ajp.so LoadModule proxy_balancer_module modules/mod_proxy_balancer.so LoadModule proxy_connect_module modules/mod_proxy_connect.so LoadModule proxy_ftp_module modules/mod_proxy_ftp.so LoadModule proxy_http_module modules/mod_proxy_http.so Uncomment the below lines Include conf/extra/httpd-ssl.conf 3. Generate a certificate and their respective key for webserver using the below command Navigate to C:\$APACHE_HOME\bin and execute the below command using command line openssl req -new -x509 -days 365 -sha1 -newkey rsa:1024 -nodes - keyout webserver.key -out webserver.crt -subj /O=EMC/OU=Documentum/CN=LB.SERVER.LAB/ST=CA/L=Pleasanton/C=US -config "C:\$APACHE_HOME\conf\openssl.cnf" Above command will generate a LB.key and LB.crt 4. Navigate to C:\$APACHE_HOME\conf\extra and do the following changes in httpd-ssl.conf Enable SSL engine and proxy engine # SSL Engine Switch: 20

SSLEngine on # Enable/Disable SSL for this virtual host. SSLProxyEngine on Search for virtual tag and verify the below configurations is proper or not # General setup for the virtual host DocumentRoot "C:/ Apache2.2/htdocs" ServerName WebServer.SERVER.LAB:443 ServerAdmin admin@server.lab ErrorLog "C:/ Apache2.2/logs/error.log" TransferLog "C:/ Apache2.2/logs/access.log" Modify the LB.key and cerverlb.crt path. 5. Add the following lines in the httpd.conf file <IfModule mod_proxy.c> # set ProxyRequests off since we're only using the ProxyPass and ProxyPassReverse # directives. this keeps the server secure from # spammers trying to use your proxy to send email. ProxyRequests Off <Proxy *> AddDefaultCharset off Order deny,allow Allow from all #Allow from.example.com </Proxy> # Enable/disable the handling of HTTP/1.1 "Via:" headers. # ("Full" adds the server version; "Block" removes all outgoing Via: headers) # Set to one of: Off On Full Block ProxyVia On </IfModule> <Location /balancer-manager> SetHandler balancer-manager 21

Order Deny,Allow Deny from all Allow from <IP-range> </Location> <Proxy balancer://mycluster > BalancerMember https://<appserver1_machine_hostname>:<ssl-port> route=<primary tomcat Server Instance name> loadfactor=1 BalancerMember https://<appserver2_machine_hostname>:<ssl-port> route= <Secondary tomcat Server Instance name> loadfactor=1 </Proxy> ProxyPass /balancer-manager! ProxyPass / balancer://mycluster/ lbmethod=byrequests ProxyPass /<Application-Contextname> balancer://my-balancer/< Application-Contextname> ProxyPassReverse /<Application-Contextname> https://<appserver1_machine_hostname>:<ssl-port>/<application- Contextname> ProxyPassReverse /<Application-Contextname> https://<appserver2_machine_hostname>:<ssl-port>/<application- Contextname> 6. If you want to preserve the Host header sent by the client, add the below configurations to the httpd.conf file ProxyPreserveHost on Restart the Apache HTTP server for changes to take effect. 7. Restart the Apache server for changes to take effect.access the following URL from the client machine. You should be able to see the Client_Application login page https://webserver-macname:<ssl-port>/client_application 22

Conclusion This document can be used as a quick reference guide for setting up tomcat Cluster environment to support High Availability and Load Balancing References http://tomcat.apache.org/tomcat-6.0-doc/cluster-howto.html http://httpd.apache.org/docs/2.2/mod/mod_proxy_balancer.html http://tomcat.apache.org/tomcat-3.3-doc/mod_jk-howto.html 23