Install manually on a Tomcat server

Learn how to manually install the glass box agent on a Tomcat server.

About this task

When AppScan® is installed, the files needed for installing the server agent are saved in a dedicated folder on your machine. To perform this task you will need access to this folder, and to your application server.

Procedure

  1. On the Glass Box page of a content scan job, expand the Download glass box agent installer section.
  2. Extract the contents of Manual_Setup.zip to your preferred location on the web server.
  3. Define a username and password for the agent (only English characters and numbers can be used):
    • For a Linux™ server: Add execution permissions to AgentCredentials.sh, then run AgentCredentials.sh <username> <password>
    • For a Windows™ server: Run AgentCredentials.bat <username> <password>
  4. Deploy GBootStrap web application:
    1. Log in to Tomcat Manager. The default location is http://<server_name>:<port_number>/manager/html
    2. In Deploy table > War file to deploy, click Choose file
    3. Locate GBootStrap.war (in the glass box folder you extracted), and click Open
    4. Click Deploy and verify that GBootStrap has been added the applications list.
  5. Shut down Tomcat.
  6. Configure Tomcat to always use the glass box agent by doing one of the following actions:
    • Through the environmental variable: Configure Tomcat's JVM through the JAVA_OPTS environmental variables (if it does not exist, create it), with the value -javaagent:<path_to_gbAgent.jar>.
    • Though batch/sh scripts: Pass arguments to the JVM running Tomcat by editing the configuration scripts that are shipped with it:

      Linux server:

      1. In the Tomcat folder (usually located in <path_to_Tomcat_folder>/bin), open startup.sh
      2. Locate a line that begins with CATALINA_OPTS and add the following line below it:
        export CATALINA_OPTS = $CATALINA_OPTS -javaagent:<path_to_gbAgent.jar>
      3. Save and close the file.

      Windows server:

      1. In the Tomcat folder (usually located in <path_to_JBoss_folder>\bin), open startup.bat
      2. Locate a line that begins with set CATALINA_OPTS= and add the following line below it:
        set CATALINA_OPTS = %CATALINA_OPTS% -javaagent:<path_to_gbAgent.jar>
      3. Save and close the file.
    Important: Ensure that CATALINA_OPTS is initialized only once, and prior to the lines above, so that other CATALINA_OPTS assignments do not overwrite -javaagent.
    Note: To add arguments to CATALINA_OPTS, use the %CATALINA_OPTS% / $ CATALINA_OPTS convention.
  7. Restart Tomcat.