AWS Elastic Beanstalk

Amazon Web Services (AWS) is a secure cloud services platform that provides a reliable, scalable and affordable computing platform solution. By using AWS, Contrast users can maximize the security of their applications.

Contrast works with the following AWS systems:

  • AWS Elastic Beanstalk
  • Amazon EC2
  • Amazon RDS

Before You Start

Complete the following tasks before proceeding with the Configuration instructions:

Configuration

Step one

  • In your WAR file, add the contrast.jar file to WEB-INF/lib/.

  • Repackage and deploy your new WAR file as a new application, or an update to a previous application.

  • Locate and connect to the underlying EC2 instance. Once connected, use the following command to find the path to contrast.jar file. (Substitute /opt as appropriate.)

sudo find /opt -name "contrast.jar"

Step two

Pass the -javaagent flag to JVM in Elastic Beanstalk by completing the following steps.

  • In the AWS console, open Elastic Beanstalk.
  • Choose a region.
  • Choose your application.
  • In the left navigation, select Configurations.
  • Open Software Configuration.
  • In the JVM command line options: field, enter -javaagent:/full/path/to/contrast.jar.
  • Select Apply to save.
  • Elastic Beanstalk updates your environment.

For more information about AWS and Java, go to the AWS documentation.

Axis

Before You Start

Download and install the Java agent from Contrast before proceeding with the Configuration instructions.

Configuration

If you run Axis2 from axis2server.bat (or .sh), Contrast recommends that you create a new startup script: startup-with-contrast.bat. This new script makes it easy to start up your server with or without Contrast.

It should enable the Contrast JVM parameters and call the startup script, as shown in the following example. Of course, you need to substitute the path to contrast.jar and the Axis2 server for your environment.

set PROGRAM_PARAMS="$PROGRAM_PARAMS -javaagent:${DOWNLOADS}\contrast.jar"
call ${AXIS_DIR} \bin\startup.bat

Cloud Foundry

Contrast offers a variety of Cloud Foundry integrations for your applications using the default Java buildpack. You can use the buildpack on its own as a low level of integration by creating a user-provided service and binding the service to your application. The service broker allows you to define multiple service plans, and allows you to generate service instances in order to bind to applications.

For Pivotal Cloud Foundry (PCF) customers, Contrast offers a Pivotal tile. This tile automates the BOSH deployment and configuration of the Contrast service broker.

Requirements

To instrument an application in a Cloud Foundry environment, your application must use one of the following buildpacks:

Note: If you're using the offline version of the buildpack, you won't be able to override the version of the agent being used by the application; the dependencies are already bundled inside the buildpack.

If you're using a buildpack that predates (and doesn't include) Contrast Security framework support, you can add framework support with minimal effort; however, you must make the appropriate changes to your forked buildpack.

Contrast Security Framework Support

The Contrast Security agent framework takes care of automatically downloading the latest Contrast agent and creating a configuration file. The buildpack detect script prints tags to standard output.

Detection CriterionExistence of a single bound Contrast service. The existence of an Contrast service defined by the VCAP_SERVICES payload containing a service name, label or tag with contrast-security as a substring.

User-Provided Service

When binding Contrast Security using a user-provided service, it must have a name or tag that includes contrast-security. The credential payload must contain the following entries:

Name Description
api_key Your user's API key
service_key Your user's service key
teamserver_url The base URL to which your user has access and the URL to which the agent will report (e.g., https://app.contrastsecurity.com)
username The account name to use when downloading the agent

Configuration

For general information on configuring the buildpack, including how to specify configuration values through environment variables, refer to the Configuration and Extension section of the Cloud Foundry Java Buildpack documentation.

An example of creating a user-provided service and binding it to an application:

cf create-user-provided-service contrast-security-service -p "teamserver_url, username, api_key, service_key"
cf bind-service spring-music contrast-security-service
cf restage spring-music

You can configure the framework by modifying the [config/contrast_security_agent.yml][] file in the buildpack fork. The framework uses the Repository utility support and supports the version syntax defined there.

Name Description
repository_root The URL of the Contrast Security repository index
version The version of the Contrast agent to use

To specify a version of the Java agent to use, set the JBP_CONFIG_CONTRASTSECURITYAGENT environment variable and specify a version listed in the index.

JBP_CONFIG_CONTRASTSECURITYAGENT`: version: 3.5.6_606

Contrast Service Broker

The Contrast service broker allows Cloud Foundry users to easily bind services to their application and use the Contrast Java agent.

Prerequisites

Any applications that you want to use with the service broker should employ the default Java buildpack to download and run the agent.

cf push YOUR_APP_NAME_GOES_HERE

Set up generic Cloud Foundry

Contact Contrast's Customer Support team for access to the service broker source code, and then complete the following steps.

  • Deploy the service broker application:
cf push contrast-security-service-broker

The service broker now appears in your Cloud Foundry console. The service broker doesn't offer any plans by default. Plans are configurable via the CONTRAST_SERVICE_PLANS environment variable. If using Pivotal, you can also use the Pivotal Ops Manager to set the environment variables. If using Bluemix, you can click on the application, select Runtime and then Environment Variables to set the value.

  • Refer to the following example to set the value through the command line:
    cf set-env contrast-security-service-broker CONTRAST_SERVICE_PLANS
    " {
            "ServicePlan1": {
                 "name":"ServicePlan1",
                 "teamserver_url":"https://yourteamserverurl.com",
                 "username":"your_username",
                 "org_uuid":"00000000-1111-2222-3333-000000000000",
                 "api_key":"your_api_key",
                 "service_key":"your_service_key"
             },
             "AnotherServicePlan":{
                 "name":"AnotherServicePlan",
                 "teamserver_url":"https://yourteamserverurl.com",
                 "username":"your_username",
                 "org_uuid":"00000000-1111-2222-3333-000000000001",
                 "api_key":"your_api_key",
                 "service_key":"some_other_service_key"
                 }
             } "
  • If running the agent on Bluemix, you must use single quotes to set the CONTRAST_SERVICE_PLANS environment variable because Bluemix doesn't recognize double quotes. Example:
    cf set-env contrast-security-service-broker CONTRAST_SERVICE_PLANS
    " {
            'ServicePlan1': {
                 'name':'ServicePlan1',
                 'teamserver_url':'https://yourteamserverurl.com',
                 'username':'your_username',
                 'org_uuid':'00000000-1111-2222-3333-000000000000',
                 'api_key':'your_api_key',
                 'service_key':'your_service_key'
             },
             'AnotherServicePlan':{
                 'name':'AnotherServicePlan',
                 'teamserver_url':'https://yourteamserverurl.com',
                 'username':'your_username',
                 'org_uuid':'00000000-1111-2222-3333-000000000000',
                 'api_key':'your_api_key',
                 'service_key':'some_other_service_key'
                 }
             } "
  • After modifying the environment variable, restage your application:
cf restage contrast-security-service-broker
  • The application also requires an environment variable for a username and a password:
cf set-env contrast-security-service-broker SECURITY_USER_NAME aSecureUsername
cf set-env contrast-security-service-broker SECURITY_USER_PASSWORD aSecurePassword
  • Create a service broker instance. (At least one service plan must be defined.) You must use the username and password configured above.
cf create-service-broker contrast-security-service-broker USER_NAME PASSWORD
<URL of your application>
  • If running on Bluemix, add --space-scoped at the end of the command. Example:
cf create-service-broker contrast-security-service-broker USER_NAME PASSWORD
<URL of your application> --space-scoped
  • All service brokers start off as private; you need to make it public:
cf enable-service-access contrast-security-service-broker
  • Now that the service broker is working, create a service instance and bind it to the application. To create a service instance, run the following command:
cf create-service contrast-security-service-broker ServicePlan1 <name_of_service>
  • To bind it to your application, run the following command:
cf bind-service <app_name> <name_of_service>

You should see the agent start up with your application and also see it in your Contrast UI.

Contrast Service Broker Tile

Prerequisites

  • Pivotal Apps Manager and Ops Manager installation
  • Active Contrast account
  • Any application that you want to use with Contrast must use the default Java buildpack; or, you must copy the Contrast framework support and configuration into your custom buildpack.

Details

A service broker allows Cloud Foundry applications to bind to services and consume the services easily from the App Manager UI or the command line. The Contrast service broker enables you to use one or more Contrast accounts, and is deployed as a Java application on Cloud Foundry. The broker exposes the Contrast service on the Cloud Foundry marketplace, which allows users to directly create a service instance and bind it to their applications from the Pivotal Apps Manager Console or the command line.

Once deployed, this title creates one organization, contrast-security-service-broker-org. The memory requirement is 512MB.

Use Contrast with Java Applications on PCF

The Contrast integration with PCF allows you to easily deploy applications with Contrast on the PCF platform. The following instructions walk you through the process to deploy a Java application that has a Contrast agent installed, and demonstrate the steps to get up and running with PCF and the Contrast Java buildpack.

Set up an application with the Contrast build pack

To push an application that uses the Contrast buildpack to PCF, use the Cloud Foundry-provided Spring Music application as an example. You can clone, build and push the sample application using the following commands:

git clone https://github.com/cloudfoundry-samples/spring-music.git
cd spring-music
./gradlew assemble
cf push spring-music

Add The Contrast Service Broker Tile

Step 1: Ops manager configuration

The first step of integrating Contrast with your PCF is installing the Contrast tile.

  • Download the Contrast server broker tile for PCF from the Pivotal Network.

  • Once you've stored the file locally, navigate to your Pivotal Ops Manager instance.

  • In the Ops Manager, click on the Import a Product button and select the contrast-security-service-broker-#.#.#.pivotal tile that you downloaded or created in the previous step.

Note: If the file you downloaded is automatically given a .zip extension, rename it to contrast-security-service-broker-#.#.#.pivotal.

Service plan

The tile requires some configuration before you can deploy it. The service broker does not offer any service plans by default, and requires that you configure at least one service before it will allow you to deploy the tile.

  • To add a service plan, go to the Service Plans tab within the Contrast tile and click the Add button.

  • You can now see 10 form fields:
Parameter Description
TeamServer URL to your Contrast application instance
TeamServer Service Key Service Key shown in Organization Settings
TeamServer API Key API Key shown in Organization Settings
Organization UUID The organization to which the application will belong
Username Contrast username
Plan Name Name of the plan as it will appear in Apps Manager
Proxy Host The hostname of a proxy for the service broker to communicate with Contrast
Proxy Port The proxy port
Proxy Username The proxy username if it requires authentication
Plan Password The proxy password
  • Once you're finished defining a plan, click the Save button. If you want some applications to belong to different organizations, define any other plans you may need.

  • Once you define your plans, return to the Ops Manager dashboard and select the Apply Changes button.

This may take some time to deploy.

Step 2: Apps Manager instructions

Now that you've successfully deployed the service broker, you can create services to bind the credentials to an application.

  • Navigate to your Pivotal Apps Manager instance and go to the Marketplace tab, where a Contrast service broker option is present.

  • Click the Contrast service broker option to see the available plans. (These are the same plans that you entered in the Ops Manager.)

  • Click the Select this Plan button to choose the plan you want to bind to an application.

  • On the next screen, specify an instance name of the plan. (This doesn't effect the service broker; you can name it anything you like.)

  • Under the Bind to App dropdown, select the application to which you want to bind this service.

Now that you bound your service instance to an application, you can restage the application. The latest Java agent will be retrieved from Contrast and run on your application.

Set environment variables for Contrast

If you want to override Java agent properties, such as the application name, you can use environment variables through the Pivotal UI or the Cloud Foundry command line.

  • Command line example:
cf set-env APP-NAME JAVA_OPTS " -Dcontrast.appname.override=PivotalSpringApp
-Dcontrast.server=PivotalServerName "
  • Pivotal Apps Manager example:

Desktop or Standalone Applications

Before You Start

Download and install the Java agent from Contrast before proceeding with the Configuration instructions.

Configuration

The process to run the Java agent on a desktop or standalone application very similar to the standard process for a web application. The significant difference is that you must also pass a name in the contrast.appname system property under which to collect vulnerabilities:

-Dcontrast.appname=AcmeDesktopApp -javaagent:<path>/contrast.jar

DropWizard

Before You Start

Download and install the Java agent from Contrast before proceeding with the Configuration instructions.

Configuration

To run the Java agent with your standalone or fat JAR Dropwizard application, use the following code sample:

java -javaagent:/path/to/contrast.jar -Dcontrast.appname="AppNameToReportUnder" -jar /path/to/your/app.jar server /path/to/your/appconfig.yml

The Java agent can't accurately count library usage if your project was configured to shade dependencies into your application's JAR. Instead, the Java agent will report a list of JARs based on the information gathered from the pom.properties files provided with the included libraries.

GlassFish

Before You Start

Download and install the Java agent from Contrast before proceeding with the Configuration instructions.

Configure GlassFish

If you launch GlassFish yourself, you must add Contrast's JVM parameter to the domain.xml file in your domain directory, ${GLASSFISH_DIR}\domains\domain1.

<!-- Within the your profile's "java-config" element, add the following lines: -->
<jvm-options>-javaagent:${DOWNLOADS}\contrast.jar</jvm-options>

Of course, you need to substitute the path to contrast.jar and the GlassFish server for your environment.

Run Contrast on GlassFish with IntelliJ

The following instructions walk you through the process to add the Contrast Java agent to an application using the IntelliJ IDE running GlassFish.

Configuration

  • In the menu bar, click the Start/Run icon next to the GlassFish service.
  • Wait for the server to finish launching.

  • Navigate to the GlassFish Server Administration Console (usually http://localhost:4848/).
  • After the console has finished loading, select Configurations > server-config.
  • Select JVM Settings.

  • Select the tab for Profiler.
  • Add the name "Contrast".
  • Add the following JVM options:
-javaagent:${DOWNLOADS}/contrast.jar
  • Select Save.

  • Click on the Start/Run icon next to the GlassFish service from the top menu bar and select Restart Server.

A Contrast startup message should appear in the GlassFish server log console. (Allow one to two extra minutes for server startup.)

After GlassFish has finished the startup process, IntelliJ will open a new web browser.

  • Navigate to your application, and allow an extra minute for it to start up.

Run Contrast on GlassFish with NetBeans

The following instructions walk you through the process to add the Contrast Java agent to an application using NetBeans running GlassFish.

Configuration

Step one: GlassFish

  • Select the Services tab.
  • Under Servers, right click on the GlassFish Server and select Start.
  • Wait for the server to finish launching.

  • Navigate to the GlassFish Server Administration Console (usually http://localhost:4848/).
  • After the console has finished loading, select Configurations > server-config.
  • Select JVM Settings.

  • Select the tab for JVM Options.
  • Add the following JVM options:
-javaagent:${DOWNLOADS}/contrast.jar
  • Select Save.

Step two: NetBeans

  • In NetBeans, right click on the GlassFish Server and select Stop.

  • After the server has finished shutting down, right click on the project and select Run.

A Contrast startup message should appear in the GlassFish server log console. (Allow one to two extra minutes for server startup.)

After GlassFish has finished the startup process, NetBeans will switch to the HTTP Server Monitor mode and open a new web browser.

  • Navigate to your application, and allow an extra minute for it to start up.

Google App Engine

To add the Contrast agent in your Google App Engine environment, complete the steps in the following Configuration instructions.

Note: Contrast only works in your locally deployed (dev/test) instance of App Engine. The the locally deployed instance of App Engine supports the Java instrumentation libraries required by Contrast; but, Google App Engine cloud doesn't.

Before You Start

Download and install the Java agent from Contrast before proceeding with the Configuration instructions.

Configuration

If you're using Maven to deploy your application, you need to edit your pom.xml file under <build>/<plugins>/<plugin> with a groupid of <groupId>com.google.appengine</groupId> and artifactid of <artifactId>appengine-maven-plugin</artifactId>.

  • Add the following block:
<configuration>
  <jvmFlags>
    <jvmFlag>-javaagent:/path_to_contrast/contrast.jar</jvmFlag>
    <jvmFlag>-Dcontrast.rootapp=NAMEOFYOURAPP</jvmFlag>
  </jvmFlags>
</configuration>
  • The result should be similar to:
<plugin>
  <groupId>com.google.appengine</groupId>
  <artifactId>appengine-maven-plugin</artifactId>
  <version>1.9.0</version>
  <configuration>
    <jvmFlags>
      <jvmFlag>-javaagent:/path_to_contrast/contrast.jar</jvmFlag>
      <jvmFlag>-Dcontrast.rootapp=NAMEOFYOURAPP</jvmFlag>
    </jvmFlags>
  </configuration>
</plugin>

Note: If you don't provide the -Dcontrast.rootapp jvmFlag, Contrast will refer to your application by the name ROOT.

  • Once this is done, you can run:
mvn clean install
mvn appengine:devserver

Now your application will launch with the Contrast agent monitoring the application.

IntelliJ

Use the following instructions to add the Contrast agent to an application using IntelliJ IDE's supported application servers.

Before You Start

Download and install the Java agent from Contrast before proceeding with the Configuration instructions.

Configuration

  • Click on Run in the application toolbar, and then click on the Edit Configuration menu item from the dropdown.

  • Select the IntelliJ Server configuration instance.
  • Select the Server tab, and enter the Contrast launcher string in VM Options: -javaagent:${DOWNLOADS}/contrast.jar -noverify.

  • Click Apply and then OK.
  • Start the Server.
  • A Contrast startup message should appear in the Server console. (Allow one to two extra minutes for server startup.)

  • Navigate to your application and allow an extra minute for it to start up.

More Information

Running Contrast on GlassFish with IntelliJ

JBoss 5+

Before You Start

Download and install the Java agent from Contrast before proceeding with the following instructions.

Run JBoss from "run.bat" or "standalone.bat"

If you run JBoss from domain.bat, standalone.bat, or run.bat with a .conf file, Contrast recommends modifying the configuration file. It should enable the Contrast JVM parameters and then return to the start up script.

To do this, append the following line to the end of your .conf file:

set JAVA_OPTS=-javaagent:{path-to-jboss-direcotry}\contrast.jar %JAVA_OPTS%

Of course, you need to substitute the path to contrast.jar and your JBoss server directory for your environment.

Run JBoss in Domain Mode

If you're running JBoss 6 EAP or JBoss 7.x in Domain mode using domain.bat or domain.sh, you must add the -javaagent switch to the JVM options in $JBOSS_HOME/domain/configuration/domain.xml.

An example file snippet:

<server-group ...>
  <jvm name="default">
    <jvm-options>
      <option value="-javaagent:/path/to/contrast.jar"/>
    </jvm-options>
  </jvm>
...
</server-group>

More Information

Jetty

Before You Start

Download and install the Java agent from Contrast before proceeding with the following instructions.

Configuration

To add the Contrast agent on Jetty, add the following lines to your ${JETTY_DIR}\start.ini file:

-javaagent:${DOWNLOADS}/contrast.jar*

Of course, you need to substitute the path to contrast.jar and the server for your environment.

Run on Jetty

  • Set your MAVEN_OPTS environment variable to contain Contrast's JVM parameters: -javaagent:${DOWNLOADS}/contrast.jar
  • Run your jetty:run or other Maven target normally.
  • A Contrast startup message should appear in the console. (Allow one to two extra minutes for server startup).
  • Navigate to your application, and allow an extra minute for it to start up.

More Information

Not using jetty.ini? Run Contrast from other Jetty launchers.

Karaf

Before You Start

Download and install the Java agent from Contrast before proceeding with the Configuration instructions.

Configuration

  • Add a KARAF_OPTS environment variable containing the -javaagent flag before starting the container:
$ export KARAF_OPTS=-javaagent:/path/to/contrast.jar
  • Next, run the Karaf server like normal. A Contrast startup message should appear in the standard output before the Karaf shell output.

  • Navigate to your application, and allow an extra minute for it to start up.

Additional System Properties

Many Karaf users may want to use two extra system properties when running Contrast:

  • Use contrast.classpath.libs to tell Contrast to use the standard classpath libraries instead of libraries found in /WEB-INF/lib.
  • Use contrast.appname to name your application.

If you add these flags, it results in an export like the following:

$ export KARAF_OPTS="-Dcontrast.appname=MyKarafApp -Dcontrast.classpath.libs=true -javaagent:/path/to/contrast.jar"

Maven Apache Tomcat

Use the following instructions to add Contrast to an application using the Apache Maven Tomcat plugin.

Before You Start

Download and install the Java agent from Contrast before proceeding with the Configuration instructions.

Configuration

  • If you're forking your JVM, set your MAVEN_OPTS environment variable to contain Contrast's JVM parameters.

    • On Windows:
    set MAVEN_OPTS=-javaagent:C:\Path\To\contrast.jar
    mvn -Dmaven.tomcat.port=8181 clean package tomcat7:run-war
    
    • On Linux:
    export MAVEN_OPTS="-javaagent:/path/to/contrast.jar"
    mvn -Dmaven.tomcat.port=8181 clean package tomcat7:run-war
    
  • If you are not forking your JVM, set the mvn command to use the following JVM parameters like a normal process would:

    -javaagent:/path/to/contrast.jar
    
  • Run with the tomcat7:run-war or other Maven goal normally.

Note: Library analytics won't be collected if you choose a goal besides run-war.

  • A Contrast startup message should appear in the Console. (Allow one to two extra minutes for server startup.)
  • Navigate to your application, and allow an extra minute for it to start up.

Maven Cargo Plugin

Before You Start

Download and install the Java agent from Contrast before proceeding with the Configuration instructions.

Configuration

  • Add a <cargo.jvmargs> property to the <properties> section of <configuration> in your pom.xml:
<build>
  <plugins>
    <plugin>
      <groupId>org.codehaus.cargo</groupId>
      <artifactId>cargo-maven2-plugin</artifactId>
      <version>1.7.3</version>
      <configuration>
        <container>
          <containerId>jetty9x</containerId>
          [...]
        </container>
        <configuration>
          <properties>
            <cargo.jvmargs>-javaagent:${DOWNLOADS}/contrast.jar</cargo.jvmargs>
          </properties>
        </configuration>
        [...]
      </configuration>
    </plugin>
  </plugins>
</build>
  • Run your Maven target or Cargo unit test as usual.
  • A Contrast startup message should appear in the console before your server messages appear. (Allow one or two extra minutes for server startup.)
  • Navigate to your application, and allow an extra minute for startup.

More Information

For more information on adding JVM arguments to Cargo container, see the Cargo documentation.

For a complete example of using Contrast with Maven and the cargo-maven2-plugin, see the article to Add the Agent to a Maven Project.

NetBeans

Use the following instructions to add Contrast to an application using the NetBeans IDE with JBoss.

Before You Start

Download and install the Java agent from Contrast before proceeding with the Configuration instructions.

Configuration

  • Open the NetBeans project.
  • Select Tools > Servers.
  • Select the server to which you want to add Contrast (e.g., JBoss), and click on the Platform tab.

  • Add Contrast's JVM options to the VM Options field: -javaagent:${DOWNLOADS}/contrast.jar

  • Select Run > Run Main Project, or right-click on the project and select Run.

  • A Contrast startup message should appear in the Server console. (Allow one to two extra minutes for server startup.)

  • Navigate to your application, and allow an extra minute for it to start up.

More Information

Run Contrast on GlassFish with NetBeans

Play

Before You Start

Download and install the Java agent from Contrast before proceeding with the following instructions.

Run Contrast from the Command Line

Play makes the process to add JVM options to the application's JVM a little different than standard Java options syntax. For Play to pass the options properly, they must be prepended with -J. As a result, you must add the following line to your Play startup command. Of course, you'll have to substitute the path to contrast.jar and the server for your environment.

-J-javaagent:${DOWNLOADS}/contrast.jar

Run Contrast from a Script

If you run Play from a script calling the Play activator, amend the command as shown:

activator -J-javaagent:${DOWNLOADS}/contrast.jar ${YOUR_JVM_OPTIONS} ${YOUR_PLAY_OPTIONS} run

Run Contrast with JAVA_OPTS

Older versions of Play have a known defect where they don't properly pass through the -J options. To work around this, Contrast recommends that you set JAVA_OPTS in the command line before calling activator:

JAVA_OPTS="-javaagent:${DOWNLOADS}/contrast.jar $JAVA_OPTS" ./activator run

Tomcat

Before You Start

Download and install the Java agent from Contrast before proceeding with the following instructions.

Run Contrast from "startup.bat"

If you run Tomcat from startup.bat, Contrast suggests creating a new startup script, startup-with-contrast.bat. If you run Tomcat from startup.sh, the new startup script is startup-with-contrast.sh. This should enable the Contrast JVM parameters and call the startup script.

  • For Windows, use startup-with-contrast.bat:
set CATALINA_OPTS="%CATALINA_OPTS% -javaagent:${DOWNLOADS}\contrast.jar"
call ${TOMCAT_DIR} \bin\startup.bat
  • For Unix, use startup-with-contrast.sh:
export CATALINA_OPTS="$CATALINA_OPTS -javaagent:${DOWNLOADS}/contrast.jar"
${TOMCAT_DIR}/bin/startup.sh

Of course, you need to substitute the path to contrast.jar and your Tomcat server for your environment. This new script will make it easy to start up your server with or without Contrast.

Run Contrast from "setenv.bat"

Alternatively, if you have a setenv.bat or setenv.sh file as recommended by Tomcat, add the -javaagent configuration in that file in CATALINA_OPTS.

Run Contrast on the Tomcat service in Windows

If you run Tomcat as a service, you must open the Tomcat service manager to change the JVM options to add the agent.

  • To start, double click the Tomcat icon in the System tray (or right click and select Configure).

  • If the icon isn't there, you might have to start it manually by running tomcat7w.exe in the Tomcat bin directory.

  • Switch to the Java tab to see where you need to add the -javaagent flag.

More Information

Not using startup scripts or the Windows service? Here's how to run Contrast from other Tomcat launchers:

Vert.x

Support of the Vert.x framework within the Java agent is based on the Contrast Netty implementation, specifically the ability to follow key data events through Vert.x's messaging system.

Before You Start

Download and install the Java agent from Contrast before proceeding with the configuration instructions.

Configure Vert.x Applications with the Java Agent

The simplest approach for configuring the Contrast Java agent with a Vert.x web application is to package the web application as a standalone or fat JAR.

  • Include the following plugin in the POM.xml file:
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-shade-plugin</artifactId>
    <version>2.3</version>
    <executions>
        <execution>
            <phase>package</phase>
            <goals>
                <goal>shade</goal>
            </goals>
            <configuration>
                <transformers>
                    <transformer
                        implementation="org.apache.maven.plugins.shade.resource.
                        ManifestResourceTransformer">
                        <manifestEntries>
                            <Main-Class>io.vertx.core.Starter</Main-Class>
                            <!-- change the Main-Verticle property to match 
                            the name if your main Verticle class-->
                            <Main-Verticle>com.contrastsecurity.examples.
                            vertx.ApplicationMainVerticle</Main-Verticle>
                        </manifestEntries>
                    </transformer>
                </transformers>
                <artifactSet />
            </configuration>
        </execution>
    </executions>
</plugin>
  • Once the standalone JAR is assembled, include -javaagent:/PATH/TO/YOUR/contrast.jar as one of the JVM arguments:
java -javaagent:/PATH/TO/YOUR/contrast.jar <other_options> 
-jar /PATH/TO/YOUR/application.jar

Alternative Configuration

Alternatively, you can configure the Java agent as a JVM_OPT in the vertx script file.

  • You must include the paths to the application's dependencies in the vertx script's CLASSPATH property:
JVM_OPTS="-XX:+UseBiasedLocking -XX:BiasedLockingStartupDelay=0 
-javaagent:/PATH/TO/YOUR/contrast.jar"
  • Once this is configured, launch the web application via the command vertx run passing the path to the main Verticle as a parameter:
vertx run /PATH/TO/YOUR/src/MainVerticle.java

The Vert.x application is unlikely to have a /WEB-INF/web.xml file from which the Java agent can identify the application name. In this case, you can define the application name with the -Dcontrast.appname=AppName property when launching the Vert.x application with Contrast enabled.

java -javaagent:/PATH/TO/YOUR/contrast.jar 
-Dcontrast.appname="<Name_to_show_in_Contrast>" <other options> 
-jar /PATH/TO/YOUR/application.jar

WebLogic

Before You Start

Download and install the Java agent from Contrast before proceeding with the Configuration instructions.

Configuration

Unix

If you launch WebLogic yourself, you must add Contrast's JVM parameter to the startWebLogic file in your installation's bin directory. For UNIX-based operating systems, the path to this file looks like:

/path/to/appserver/userprojects/domains/base_domain/bin/startWebLogic.sh
  • In this file, add the Contrast engine as a -javaagent to the JAVA_OPTIONS environment variable before the Java execution step:
export JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:/path/to/contrast.jar"

Windows

For Windows systems, the path looks like:

C:\Oracle\Middleware\userprojects\domains\base_domain\bin\startWebLogic.bat
  • At the beginning of the file, add the Contrast engine as a -javaagent to the JAVA_OPTIONS environment variable:
set JAVA_OPTIONS="%JAVA_OPTIONS%" -javaagent:"C:\path\to\contrast.jar"

Of course, you need to substitute the path to contrast.jar and your WebLogic server for your environment.

WebSphere

Before You Start

Download and install the Java agent from Contrast before proceeding with the following instructions.

Add Contrast with WebSphere

If you launch WebSphere yourself, you must add Contrast's JVM parameter to the server.xml file in your cell directory:

${WEBSPHERE_DIR}\AppServer\profiles\AppSrv01\config\cells\<CellName>\nodes\<NodeName>\servers\server1\server.xml

<jvmEntries genericJvmArguments="-javaagent:${DOWNLOADS}/contrast.jar -Xshareclasses:none -Xmx512m">
   ...
</jvmEntries>

Of course, you need to substitute the path to contrast.jar and your WebSphere server for your environment.

Add Contrast with the WebSphere Administration Console

You can also add Contrast through the WebSphere administration console. The following instructions from the Websphere support site are for WebSphere 8.0/8.5. These instructions are also available on the Websphere support site for other versions.

Application Server

  1. In the Administration Console, select Servers
  2. Expand Server Type and select WebSphere application servers
  3. Click on the name of your server
  4. Expand Java and Process Management and select Process Definition.
  5. Under the Additional Properties section, click Java Virtual Machine.
  6. Scroll down and locate the textbox for Generic JVM arguments.

Node Agent

  1. In the Administration Console, select System Administration
  2. Select Node agents
  3. Choose which nodeagent to edit
  4. In the Server Infrastructure section, expand Java and Process Management and select Process Definition.
  5. Under the Additional Properties section, click Java Virtual Machine.
  6. Scroll down and locate the textbox for Generic JVM arguments.

Deployment Manager

  1. In the Administration Console, select System Administration
  2. Select Deployment manager
  3. In the Server Infrastructure section, expand Java and Process Management and select Process Definition.
  4. Under the Additional Properties section, click Java Virtual Machine.
  5. Scroll down and locate the textbox for Generic JVM arguments.
  6. Add this text to the Generic JVM arguments, as noted in the screenshot below:
-javaagent:${DOWNLOADS}/contrast.jar -Xshareclasses:none

Notes:

  • IBM J9 doesn't allow the Java Instrumentation API to alter core Java classes when using the Shared Classes feature. You must disable this feature by specifying -Xshareclasses:none in your JVM parameters, as shown above.
  • Similarly, if -Dcom.ibm.oti.shared.enabled=true is set, you may also run into problems in older J9 JREs.