xcp Application Deployment On Tomcat Cluster

(1)

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

xCP Application Deployment On

(2)

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.

(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

(5)

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.

(6)

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"/>

(7)

</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 server.war file you downloaded and open bam-server.properties.

b. Remove the comment symbol (#) from the following lines and enter values for your

(8)

# 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\tomcat-users.xml and add a user name and password as shown in the following code sample:

(9)

<tomcat-users>

<user name="USER_NAME" password="PASSWORD" roles="admin-gui, manager- gui,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

(10)

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>

(11)

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

(12)

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

(13)

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

(14)

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.

(15)

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

(16)

6. In run configuration dialog box specify the run name and the data-policy 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

(17)

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

(18)

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

(19)

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"

(20)

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

(21)

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 [email protected]

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

(22)

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

(23)

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