Tomcat

Variables %CATALINA_HOME% and $CATALINA_HOME used throughout this article refer to the root directory where Tomcat Application Server is installed in Windows and Linux operating systems respectively. Some sample values are provided below:

• %CATALINA_HOME% - D:\tomcat-7.0.85\
• $CATALINA_HOME - /opt/tomcat-7.0.85/

Windows

Auto Instrumentation

1. Application Deployment Folder
   1. Log in to the Virtual Machine where Tomcat is installed
   2. Utilize the below path as Application Deployment Folder
      %CATALINA_HOME%\webapps
   3. Example:D:\tomcat-7.0.85\webapps
2. Startup Script File Path
   1. Provide the below path as Startup Script File Path
      %CATALINA_HOME%\bin\setEnv.bat
   2. Example:D:\tomcat-7.0.85\bin\setEnv.bat

Manual Instrumentation

Supported Windows Version: The following configuration is tested on Windows 2016 Operating System. To manually configure Tomcat Server with VSP, follow the steps below:

Method 1: Script based startup:

1. Shut down Tomcat Server (if it is running) using the command:

   %CATALINA_HOME%\bin\shutdown.bat

2. Create a file setEnv.bat in the directory %CATALINA_HOME%\bin. Add content below to the file. Ensure that <AppCollectiveID> mentioned below is replaced with the App Collective ID in the CMS Application Configuration section

   @echo off
   ECHO.%JAVA_TOOL_OPTIONS%| FIND /I "instrumentation.jar">Nul || (
   set JAVA_TOOL_OPTIONS=%JAVA_TOOL_OPTIONS% -javaagent:"%VSP_HOME_WEB_MEM%"\iae-java\instrumentation.jar -Dvirsec_appcontextpath=<AppCollectiveID>
   )
   

3. Save the modified file setEnv.bat
4. Start the Tomcat Server using the command:

   %CATALINA_HOME%\bin\startup.bat

   
   

Method 2: Tomcat Services based Startup:

1. If the Tomcat Server is running, shut down the server using Windows Services
   Example Service Name:Apache_Tomcat-7
2. Navigate to the directory: %CATALINA_HOME%\bin
   Example:D:\tomcat-7.0.85\bin
3. Open command prompt
4. Right-click on properties and procure the value of Service Name
5. Edit the parameters of the service:
   1. In the Java tab, modify the parameters, Java Options to add the Service Name (obtained in Step 4)
   2. Add VSP JVM argument to Java Options as described below. Ensure that <AppCollectiveID> mentioned below is replaced with the App Collective ID in the CMS Application Configuration section
      Before Modification:

      -Dcatalina.home=D:\tomcat-7.0.85
      -Dcatalina.base=D:\tomcat-7.0.85
      -Dignore.endorsed.dirs=D:\tomcat-7.0.85\endorsed
      -Djava.io.tmpdir=D:\tomcat-7.0.85\temp
      -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
      -Djava.util.logging.config.file=D:\tomcat-7.0.85\conf\logging.properties
      

      After Modifications:

      -Dcatalina.home=D:\tomcat-7.0.85
      -Dcatalina.base=D:\tomcat-7.0.85
      -Dignore.endorsed.dirs=D:\tomcat-7.0.85\endorsed
      -Djava.io.tmpdir=D:\tomcat-7.0.85\temp
      -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
      -Djava.util.logging.config.file=D:\tomcat-7.0.85\conf\logging.properties
      -javaagent:c:\PROGRA~2\Virsec\virsec-web-mem\iae-java\instrumentation.jar 
      -Dvirsec_appcontextpath=<AppCollectiveID>
      

6. Start the Tomcat Server using Windows Services 
   Example Service Name: Apache_Tomcat-7

Linux

Auto Instrumentation

1. Application Deployment Folder
   1. Log in to the Virtual Machine where Tomcat is installed
   2. Utilize the below path as Application Deployment Folder
      $CATALINA_HOME/webapps
   3. Example:/opt/tomcat-7.0.85/webapps
2. Startup Script File Path
   1. Provide the below path as Startup Script File Path
      $CATALINA_HOME/bin/setenv.sht
   2. Example:/opt/tomcat-7.0.85/bin/setenv.sh

Manual Instrumentation

Supported Linux Version: The following configuration is tested on RHEL 7.5 Operating System. To manually configure Tomcat Server with VSP, follow the steps below:

1. Shut down the Tomcat Server (if it is running) using the script

   $CATALINA_HOME/bin/shutdown.sh

2. Create a file setenv.sh in the directory $CATALINA_HOME/bin. Add the below content to the file. Ensure that <AppCollectiveID> mentioned above is replaced with the App Collective ID in the CMS Application Configuration section

   export JAVA_TOOL_OPTIONS="$JAVA_TOOL_OPTIONS 
   -javaagent:/opt/virsec-web-mem/iae-java/instrumentation.jar 
   -DVSP_HOME_WEB_MEM=/opt/virsec-web-mem 
   -Dvirsec_appcontextpath="
   

3.  Start the Tomcat Server using any one of the below methods:
   1. Method 1: Using Startup Script

      $CATALINA_HOME/bin/startup.sh

   2. Method 2: Using init service:
      1. Example: systemctl start <tomcat-service-name>
      2. A sample tomcat.service script is provided below. Verify that the variable WorkingDirectory is present. If it is not, add it as depicted below:

         # Systemd unit file for tomcat
         [Unit]
         Description=Apache Tomcat Web Application Container
         After=syslog.target network.target
         
         [Service]
         Type=forking
         
         Environment=JAVA_HOME=/opt/jdk1.8.0_161
         Environment=CATALINA_PID=/opt/apache-tomcat-8.5.30/temp/tomcat.pid
         Environment=CATALINA_HOME=/opt/apache-tomcat-8.5.30
         Environment=CATALINA_BASE=/opt/apache-tomcat-8.5.30
         
         Environment='CATALINA_OPTS=-Xms512M -Xmx1024M -server -XX:+UseParallelGC'
         Environment='JAVA_OPTS=-Djava.awt.headless=true -Djava.security.egd=file:/dev/./urandom'
         
         WorkingDirectory=/opt/apache-tomcat-8.5.30
         ExecStart=/opt/apache-tomcat-8.5.30/bin/startup.sh
         ExecStop=/bin/kill -15 $MAINPID
         User=tomcat
         Group=tomcat
         
         [Install]
         WantedBy=multi-user.target