Install manually on a Tomcat server

This section describes 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. Open ...\Program Files\IBM\AppScan Standard\Glass box

    The absolute path will depend on where you installed AppScan.

  2. Locate GB_Java_Manual_Setup.zip and copy it to your web server.
  3. Extract the contents of this folder to your preferred location on the web server.
  4. Define a username and password for the agent (use only English ASCII characters):
    • Linux server: Run AgentCredentials.sh <username> <password>
      Note: AgentCredentials.sh must have execution permissions.
    • Windows server: Run AgentCredentials.bat <username> <password>
  5. Deploy GBootStrap web application.
    • Preferred method:
      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
    • Alternative method:
      1. Copy the file GBootStrap.war from the glass box folder you extracted
      2. Paste it into the \webapps folder, default location:
        C:\apache-tomcat-[version]\webapps
  6. Shut down Tomcat.
  7. Configure Tomcat to always use the glass box agent by doing one of the following:
    • 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>/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>/gbAgent.jar
      3. Save and close the file.

      Windows server:

      1. In the Tomcat folder (usually located in <path_to_Tomcat_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>/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.
  8. Restart Tomcat.