xcp Application deployment on tcserver Cluster

Transcription

1 White Paper xcp Application deployment on tcserver Cluster Abstract This white paper explains how to install and configure tcserver cluster to support High Availability and Load Balancing and enable one way SSL communication. January 2014

2 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 trademark 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 h

3 Table of Contents Executive summary... 4 Audience... 5 Terminology... 5 PRE-REQUSITE... 5 Installing and configuring TC Server Cluster... 5 TC Server installation on First Host... 5 TC Server installation on second Host... 6 Enabling Clustering on both the TC Server instances... 6 Network Considerations... 7 Configuring tcserver Instances for xcp... 7 Installing and Configuring Apache WebServer as LoadBalancer for TCServer Cluster Deployment of xcp Application on TC Server Cluster Configuring xcp Designer to deploy xcp application xcp application deployment using xms Tools Enabling SSL on tcserver Cluster Enabling SSL on Primary Node Enabling SSL ON Apache HTTP WebServer Conclusion

4 Executive summary Clustering refers to grouping together one or more Server instances so that they appear to work as a single server A tcserver cluster provides you with the following features: High Availability The primary purpose of high availability (HA) clusters is to provide uninterrupted access to data, even if a server loses network or connectivity, or fails completely, or if the application running on the server fails. Without clustering, if a server running a particular application crashes, the application will be unavailable until the crashed server is fixed Session replication When a client, typically using a browser, connects to a tc Server instance, tc Server creates a session Object that it uses to manage all subsequent interaction between itself and that client. Typical web applications use the HttpSession object to temporarily store user specific information like shopping cart items, security credentials, etc. If the tc 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 tc Server instance crashes, any of the other tc 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 tc 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 tc Server instances. Load balancing attempts to direct requests to the tc Server with the smallest load at that point in time. The load balancer can also detect when a tc Server has failed, in which case it stops directing requests to it until the tc Server restarts, adding to the high availability of tc Server This white paper covers the following points: Creating tcserver instances Adding tcserver instances to cluster Configuring Apache HTTP webserver as Load Balancer 4

5 Deploying xcp application on the tcserver cluster environment Configuring SSL for xcp Application deployed on tc server cluster Audience This white paper is intended for EMC support personnel, professional services, customers, partners, internal developers and engineers who wants to setup TCServer 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 1. Install supported JDK and set the JAVA path in all application server Nodes 2. TCServer installed on both the machines Installing and configuring TC Server Cluster In this section we have provided detailed instructions for load balance and Failover simultaneously to set up a tc Runtime cluster. In the guide, we have taken a scenario to setup 2 node distributed cluster environment TC Server installation on First Host Installing TC server involves creating an instance and registering it as a service. Below are the steps to achieve this: Open command prompt, Navigate to the <TcServer_Home>location and execute the below command tcruntime-instance.bat create <primary_instance-name> Navigate to the primary_instance folder <TcServer_Home>\<primary_instance-name>\bin and execute the below command tcruntime-ctl.bat install (This command will install the instance as a service) 5

6 Start the primary_instance server from<tcserver_home>\<primary_instance-name>\bin by executing the below command tcruntime-ctl.bat start tcruntime-ctl.bat status (To check the status of the instance) Access the tcserver home page with 8080 port. (This url will open the welcome page for tcserver) TC Server installation on second Host Installing TcServer in the second machine involves below steps: Open command prompt, Navigate to the <TcServer_Home>location and execute the below command tcruntime-instance.bat create <secondary_instance-name> Navigate to the primary_instance folder <TcServer_Home>\<secondary_instance-name>\bin and execute the below command tcruntime-ctl.bat install (This command will install the instance as a service) Start the primary_instance server from<tcserver_home>\<secondary_instance-name>\bin by executing the below command tcruntime-ctl.bat start tcruntime-ctl.bat status (To check the status of the instance) Access the tcserver home page with 8080 port. (This url will open the welcome page for tcserver) Enabling Clustering on both the TC Server instances 1. For each tc Server instance that will be a member of the cluster, update its CATALINA_BASE/conf/server.xml by adding a <Cluster> child-element of the <Engine> element, as shown in the following example.. <Cluster classname="org.apache.catalina.ha.tcp.simpletcpcluster"> <Channel classname="org.apache.catalina.tribes.group.groupchannel"> <Membership classname="org.apache.catalina.tribes.membership.mcastservice"address=" " port="45564" /> </Channel> </Cluster> Note: You should provide unique multicast address and port for each cluster to ensure proper session distribution among all the nodes 2. Add jvmroute= instance_name in <Engine> element as below 6

7 <Engine defaulthost="localhost" name="catalina" jvmroute="primary_instance"> 3. 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/> You can also add the <Cluster> element to the <Host> element of the server.xml file, thus enabling clustering in all virtual hosts of the tc Runtime instance. When you add the <Cluster> element inside the <Engine> element, the cluster appends the host name of each session manager to the manager's name so that two contexts that have the same name but are part of two different hosts are distinguishable. 4. Configure your Web application to be distributable, that is, suitable for running in a distributed environment such as a tc Runtime cluster. You can specify this element in the CATALINA_BASE/conf/context.xml file if you want to make ALL Web applications of a particular tc Runtime instance distributable. For example: <?xml version="1.0" encoding="iso "?> <Context distributable="true" >... </Context > Network Considerations Be sure that multicast is working on each computer that hosts members of the tc Runtime cluster. If the computers that host your tc Runtime cluster also host other applications that use multicast communications, be sure that the other applications do not use the same multicast address and port as the tc Runtime cluster. This precaution eliminates unnecessary processing of irrelevant messages by the tc Runtime cluster. Configuring tcserver Instances for xcp 1. After creating an instance on tc Server,stop the tcserver instance if running 2. Create and copy the dfc.properties file for the application to reference the repository, as follows: a. Create a Customconf folder at the root of the application server instance: <application_server_home>\<server_instance>\customconf. b. Copy the dfc.properties file from the %Documentum%\Config folder on the Content Server to 7

8 the above location. 3. Open the dfc.properties file in <application_server_home>\<server_instance>\customconf and add the following parameter: dfc.session.allow_trusted_login = false Save your changes. 4. Include the dfc.properties folder location in the Java Classpath. For example, edit <application_server_home>\<server_instance>\conf\wrapper.conf as shown in the following code sample: # Java Classpath... wrapper.java.classpath.$$=<application_server_home>\<server_instance>\ Customconf Where $$ is the next sequential number. 5. Extract the bam-server WAR file you downloaded and open bam-server.properties. Perform the following steps: a. Remove the comment symbol (#) from the following lines and enter values for your environment: # 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. b. If you deploy BAM in SSL mode, locate the bam.server.protocol property and change it to https. c. If the bam.server.protocol property is not available, type bam.server.protocol = https and save your changes. d. Copy the bam-server.properties file to the Customconf folder on the application server instance. For example, <application_server_home>\<server_instance>\customconf. 8. Open wrapper.conf located in <application_server_home>\<server_instance>\conf and specify the following Java memory settings: a. If the following parameters are available, place a comment symbol (#) before each parameter: #wrapper.java.additional.$$="-xmx512m" #wrapper.java.additional.$$="-xss256k" b. Add the following parameters and save your changes: wrapper.java.additional.$$="-xmx2048m" 8

9 wrapper.java.additional.$$="-xss1024k" wrapper.java.additional.$$="-xx:maxpermsize=512m" 9. Open web.xml and in the JSP servlet, disable pooling by adding the enablepooling parameter with a value of false. For example, edit <application_server_home>\<server_instance>\conf\web.xml as shown in the following code sample: <servlet> <servlet-name>jsp</servlet-name> <servlet-class>org.apache.jasper.servlet.jspservlet</servlet-class> <init-param> <param-name>fork</param-name> <param-value>false</param-value> </init-param> <init-param> <param-name>enablepooling</param-name> <param-value>false</param-value> </init-param> <init-param> <param-name>xpoweredby</param-name> <param-value>false</param-value> </init-param> <load-on-startup>3</load-on-startup> </servlet> Open the file in a browser to check for well-formed XML. 10. Create a user for the instance. xcp Designer uses this user to deploy the xcp application For example, edit <application_server_home>\<server_instance>\conf\tomcat-users.xml and add a user name and password as shown in the following code sample: <?xmlversion="1.0"?> <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. 11. Edit the <application_server_home>\<server_instance>\conf\context.xml file and set the Context xml node to the following: <Context antijarlocking="true" antiresourcelocking="true"> This step enables you to deploy or undeploy web applications remotely on the application server. Open the file in a browser to check for well-formed XML. 12. Start the tcserver service. Check the wrapper file in the logs folder to verify that the service is starting. Validate the installation by opening the following URL in a browser: 9

10 13. 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 b. 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 14. If you are using tc Server Standard Edition, deploy the Application Manager to the application server instance: a. Download the xms-tools.zip file to your local system. b. Extract the xms-tools.zip file to a folder. This extraction places a manager.war file in that folder. c. Copy the manager.war file to the \<application_server_home>\<server_instance>\webapps folder. If you are using tc Server Developer Edition, the Application Manager is available in the application server by default. 15. Verify that the Application Manager is running by opening the following URL in a browser: Log in using the user credentials you created for the application instance. Note: If you are using the manager.war file provided in the xms-tools.zip file for xcp deployment, you cannot access the Tomcat manager user interface using the above URL. In this case, deploy an application to verify if the Application Manager is running correctly. Also, view the application server logs to check for any errors. If there are no errors, the manager.war is deployed correctly. Installing and Configuring Apache WebServer as LoadBalancer for TCServer Cluster There have been a number of connectors developed to enable Apache httpd to communicate with tcserver that have used a variety of protocols. In this guide, we ll cover majorly used connector mod_proxy_http. 1. Install Apache webserver 2. Navigate to $Apache_HOME\conf\httpd.conf Uncomment the following modules required for enabling load balancing in httpd.conf file. LoadModule proxy_ajp_module modules/mod_proxy_ajp.so LoadModule proxy_balancer_module modules/mod_proxy_balancer.so 10

11 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 3. 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 . 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 Order Deny,Allow Deny from all Allow from <IP-range> </Location> <Proxy balancer://mycluster > BalancerMember route=<primary tc Server Instance name> loadfactor=1 BalancerMember route= <Secondary tc Server Instance name> loadfactor=1 </Proxy> ProxyPass /balancer-manager! 11

12 ProxyPass / balancer://mycluster/ lbmethod=byrequests ProxyPass /<Application-Contextname> balancer://my-balancer/< Application-Contextname> ProxyPassReverse /<Application-Contextname> ProxyPassReverse /<Application-Contextname> 3. 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. 4. After deploying the xcp application(steps given in the succeeding section), Check that the Load Balancer redirects the request through Apache WebServer to the appropriate back-end tcserver instances in the cluster and xcp login page is displayed when we access Documentum xcp using the following URL: Access the following URL from the client machine. You should be able to see the xcp Application login page NOTE: You should add all the TC server cluster instances as a balancer member in the above configuration. Deployment of xcp Application on TC Server Cluster Pre-requisites: Prerequisites for deploying an xcp Application are The xms Agent installed The xcp Environment is registered in the xms Agent For detailed instructions on how to register the environment in xms Agent, Please refer to the xcp Deployment guide 12

13 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 xms-provisioned environment 1. Open xcp Designer. 2. Click on the preference button in xcp Designer as shown in Figure 19. Figure 1: Configuring xcp Designer 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 20. Figure 2: Adding Deployment Environment from xcp Designer 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. 13

14 Figure 3: Testing Connection for Deployed Environment 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 22. Figure 4:Navigate to specify Data Policy 14

15 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. Figure 5: Selecting Data Policy 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. 15

16 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. Figure 6: Running deploy-xcp-application command 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 tcserver Cluster 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 also assumed that you know how to get a certificate from a trusted certificate authority or how to generate your own. The main focus 16

17 in this section is how to update the TC 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 tc Server, the SSL encryption and certificate authentication is terminated at the web server. Communication between the Apache web server and TC server is then trusted and in clear text. Enabling SSL on Primary Node Below are the basics steps for securing the TC 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 TCServer application server by executing the below command through command line. It can be created by using the java keytool utlity. From <Java_home>\binkeytool.exe -genkey -alias apphostkey -keyalg RSA -keystore apphost.keystore (Here, alias name is apphostkey and keystore name is apphost.keystore. User can choose anything for these names.) Note: Keystore can be created from any java like Documentum bundled java (<Documentum>/ java64) or any external java. 2. This command will prompt for some details mentioned below. Type the full hostname of the APPHOST 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]: apphostmachine.dnsname.com What is the name of your organizational unit? [Unknown]: emc 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 17

18 What is the two-letter country code for this unit? [Unknown]: US Is CN= acsmachine.dnsname.com, OU=emc, O=emc, L=Pleasanton, ST=CA, C=US correct? [no]: yes Enter key password for <apphostkey> (RETURN if same as keystore password): 3. Modify server.xml in APPHOST to enable SSL and server to use HTTPS protocol. Uncomment the below lines in <TOMCAT_HOME>\conf\server.xml <Connector protocol="http/1.1" SSLEnabled="true" port="8443" address="${jboss.bind.address}" scheme="https" secure="true" clientauth="false" keystorefile="${jboss.server.home.dir}/conf/apphost.keystore" keystorepass="password" sslprotocol = "TLS" ciphers="tls_rsa_with_aes_128_cbc_sha"/> Give the path for apphost.keystore file created in step2 for keystorefile attribute. Give the keystore password for keystorepass attribute which is set in step2 during keystore creation. 4. Restart APPHOST. 5. Generate the APPHOST certificate by exporting apphost.keystore. Use the below command through command line. From <java_home>/bin keytool.exe -export -alias apphostkey -file apphost.cer -keystore apphost.keystore 6. Repeat the above steps if we have multiple nodes of APPHOST 7. Import APPHOST certificate (exported in step6) 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\apphost.cer" -keystore "<java>/jre/lib/security/cacerts" It will prompt for keystore password. Give the default password for java truststore cacerts that is changeit. 8. Access APPHOST url with https protocol and SSL port. 18

19 NOTE :You should repeat the above steps for all the TC server instance to enable SSL on TC server cluster. 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 following 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=CServer.SERVER.LAB/ST=CA/L=Pleasanton/C=US - config "C:\$APACHE_HOME\conf\openssl.cnf" Above command will generate a webserver.key and webserver.crt 4. Navigate to C:\$APACHE_HOME\conf\extra and do the following changes in httpdssl.conf Enable SSL engine and proxy engine # SSL Engine Switch: 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 server.key and cerver.crt path to the one created in step3. 19

20 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 . 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 Order Deny,Allow Deny from all Allow from <IP-range> </Location> <Proxy balancer://mycluster > BalancerMember route=<primary tc Server Instance name> loadfactor=1 BalancerMember route= <Secondary tc Server Instance name> loadfactor=1 </Proxy> ProxyPass /balancer-manager! ProxyPass / balancer://mycluster/ lbmethod=byrequests 20

21 ProxyPass /<Application-Contextname> balancer://my-balancer/< Application-Contextname> ProxyPassReverse /<Application-Contextname> ProxyPassReverse /<Application-Contextname> 6. 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 Conclusion This document can be used as a quick reference guide for setting up xcp application deployment on tcserver Cluster environment to support High Availability and Load Balancing 21