The VMware Knowledge Base provides support solutions, error messages and troubleshooting guides
Search the VMware Knowledge Base (KB)
View by Article ID
Installing EM4J with Apache Tomcat (2011244)
Purpose
This article provides steps to run Apache Tomcat with Elastic Memory for Java (EM4J) version 1.2.
Note: Before proceeding with the steps in this article, be sure to review the requirements for running EM4J with Apache Tomcat. For more information, see Using EM4J with Apache Tomcat (2011243).
Resolution
Downloading the Helper Scripts
Download em4j-for-tomcat.zip (attached to this article) and extract the contents to your computer. The archive contains four files:
copy-em4j-to-tomcat.sh
logging-fragment.properties
setenv.sh
readme.txt
These files are explained later in this document. If you require any additional clarification, see the readme.txt file included in the archive.
Installing Apache Tomcat
If you have not already done so, install Apache Tomcat 6.0.x or 7.0.x. VMware recommends using a version at or greater than 6.0.35 or 7.0.23.
Note the path to your Tomcat installation as this is required later.
Installing EM4J
The downloaded archive contains the script copy-em4j-to-tomcat.sh. This is an automated script that copies the EM4J components from an existing tc Server 2.8 installation and installs them into your Apache Tomcat instance.
Note: When run, the copy-em4j-to-tomcat.sh script modifies your existing Tomcat installation; create a backup of your Tomcat instance prior to running the script.
These steps guide you through configuring and running this script:
Open a terminal and cd to the directory where you extracted the copy-em4j-to-tomcat.sh script.
If necessary, set the execute permission on the copy script:
chmod a+x copy-em4j-to-tomcat.sh
Edit the copy-em4j-to-tomcat.sh script. Instructions for editing the script are included as comments in the script.
You must edit these two variables:
TCS_HOME: Set to the full path that identifies your existing tc Server 2.8.x installation.
CATALINA_HOME: Set to the full path that identifies your Apache Tomcat installation.
Run the copy-em4j-to-tomcat.sh script. The script attempts to verify that TCS_HOME and CATALINA_HOME point to valid tc Server and Apache Tomcat installations. If any errors are generated during the script run, ensure that you have correctly configured the script in step three.
When the copy-em4j-to-tomcat.sh script has run, in addition to installing EM4J, it also installs a new bin/setenv.sh script and modifies the conf/logging.properties file. Review both of these files to examine the settings that were added.
Note: When the script runs, it backs up and overwrites the bin/setenv.sh script. You are responsible for manually migrating any settings from the original (now bin/setenv.sh.original) script to the current (bin/setenv.sh) script.
Before starting Apache Tomcat
Before you start Apache Tomcat:
Open the bin/setenv.sh file in your Apache Tomcat installation.
Ensure there is enough maximum heap specified with the -Xmx argument to accommodate application data and balloon objects.
Ensure that the remote JMX options, particularly the JMX port, are set appropriately for your Tomcat server. The EM4J CGC, if configured, uses this remote JMX port to report Java memory balloon metrics.
Enabling EM4J in the virtual machine
After EM4J is installed, you must enable its use at the virtual machine level.
To enable EM4J at the virtual machine level:
Shut down the virtual machine.
Modify the virtual machine's configuration (the .vmx properties) and add the sched.mem.pshare.guestHintsSyncEnable property, and set it to true.
Note: You cannot add the sched.mem.pshare.guestHintsSyncEnable property while the virtual machine is running.
At this point, EM4J is installed. You can now start the Apache Tomcat server. If everything is working correctly, your applications are accessible and you see these three lines in your logs/catalina.out file:
EM4J agent starting... EM4J is now running on a supported version of ESX EM4J 1.2.0 agent initialized
If you experience problems during start-up, review the logs directory for hints at the issue.
