Install manually on a JBoss server or a JBoss Service server

This section describes how to manually install the glass box agent on a JBoss or JBoss Service 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:
    1. Log in to the JBoss Administration Console. The default location is http://<server_name>:<port_number>/admin-console/
    2. Click Applications > web Application WARs, then click Add a new resource.
    3. Type in the path to GBootStrap.war (found in the glass box folder you extracted), then click Continue.
    A message confirms that the resource was created successfully.
  6. Shut down the JBoss server/service.
  7. Supply the Java agent gbAgent.jar (found in the folder you extracted) as a JVM argument by doing one of the following:
    • Through the environmental variable: Configure JBoss's JVM through the JAVA_OPTS environmental variable (if it does not exist, create it), with the value:
      -javaagent:"<path_to_gbAgent.jar>/gbAgent.jar"
-Djava.net.preferIPv4Stack=true
-Djboss.modules.system.pkgs=com.ibm.glassbox.asm.agent,
		com.ibm.glassbox.agent,com.ibm.glassbox.logger,
		com.ibm.glassbox.jsp,org.jboss.byteman
    • Through batch/sh scripts: Pass arguments to the JVM running JBoss by editing the configuration files that are shipped with the server:

      Linux server:

      1. In the JBoss folder locate and open the appropriate file in an editor (usually located in /bin):
        • JBoss AS: run.sh
        • JBoss EAP Standalone: standalone.sh
        • JBoss EAP Managed Domain: domain.sh
      2. Locate a line that begins with JAVA_OPTS and add the following code below it:
        export JAVA_OPTS=$JAVA_OPTS "-javaagent:<path_to_gbAgent.jar>/gbAgent.jar"
-Djava.net.preferIPv4Stack=true
-Djboss.modules.system.pkgs=com.ibm.glassbox.asm.agent,
		com.ibm.glassbox.agent,
		com.ibm.glassbox.logger,
		com.ibm.glassbox.jsp,org.jboss.byteman
      3. Save and close the file.

      Windows server:

      1. In the JBoss folder locate and open the appropriate file in an editor (usually located in /bin):
        • JBoss AS: run.conf
        • JBoss EAP Standalone: standalone.conf
        • JBoss EAP Managed Domain: domain.conf
      2. Locate a line that begins with set JAVA_OPTS= and add the following line below it:
        set JAVA_OPTS=$JAVA_OPTS "-javaagent:<path_to_gbAgent.jar>\gbAgent.jar"
-Djava.net.preferIPv4Stack=true
-Djboss.modules.system.pkgs=com.ibm.glassbox.asm.agent,
		com.ibm.glassbox.agent,com.ibm.glassbox.logger,
		com.ibm.glassbox.jsp,org.jboss.byteman"
      3. Save and close the file.
    Important: Ensure that JAVA_OPTS is initialized only once, and prior to the lines above, so that other JAVA_OPTS assignments do not overwrite -javaagent.
    Note: To add arguments to JAVA_OPTS, use the %JAVA_OPTS% / $ JAVA_OPTS convention.
  8. Restart the JBoss server/service.