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

Installation

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

Running Contrast From "axis2server.bat" (or ".sh")

If you run Axis2 from axis2server.bat, we suggest creating a new startup script: startup-with-contrast.bat. It should enable the Contrast JVM parameters and call the startup script:

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

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

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 variant of the buildpack, you won't be able to override the version of the agent being used by the application because 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, it requires making 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.

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.

Tags are printed to standard output by the buildpack detect script.

User-Provided Service

When binding Contrast Security using a user-provided service, it must have a name or tag with contrast-security in it. 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 Configuration and Extension.

The framework can be configured by modifying the config/contrast_security_agent.yml file in the buildpack fork. The framework uses the Repository utility support and so it supports the version syntax defined there.

Name Description
repository_root The URL of the Contrast Security repository index (details).
version The version of Contrast Security to use. Candidate versions can be found in this listing.

If you would like to specify a specific version of the Java Agent to use, you can do so by setting the JBP_CONFIG_CONTRASTSECURITYAGENT environment variable and specifying a version listed here.

An example overriding it would like this: JBP_CONFIG_CONTRASTSECURITYAGENT: 'version: 3.5.6_606'

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

Contrast Service Broker

The Contrast service broker allows Cloud Foundry users to easily bind services to their application and make use of 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 cf)

Build service broker app:

git clone https://github.com/Contrast-Security-OSS/contrast-service-broker
cd contrast-service-broker
mvn clean package spring-boot:repackage -DskipTests=true

Deploy service broker app:

cf push contrast-security-service-broker -p /path/to/contrast-service-broker-<version>.jar

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. Please refer to the following example to set the value through the commandline:

    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:

  1. Pivotal Apps Manager and Ops Manager installation
  2. Active Contrast subscription
  3. Any application that needs to use Contrast must be using the default Java buildpack, or have copied 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 either from the Pivotal Apps Manager Console or the command line.

Once deployed, this title creates one organization:

  • contrast-security-service-broker-org: This organization is used for deploying the Contrast service broker application. Memory requirement = 512MB

Use Contrast with Java Applications on PCF

The Contrast integration with PCF allows you to easily deploy Contrast-monitored applications on the PCF platform. These instructions walk you through deploying a Java applicaton with a Contrast agent installed, and demonstrates 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 app that is using the Contrast buildpack to PCF, use the Cloud Foundry-provided spring music app 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.

The tile requires some configuration before we can deploy it.

The service broker does not offer any service plans by default and requires that at least one service plan be configured before it will allow the tile to be deployed. To add a service plan, go to the Service Plans tab within the Contrast tile and click the Add button.

You can now see six form fields.

Parameter Description
TeamServer URL to your Contrast application instance
TeamServer Service Key Service Key found in Organization Settings
TeamServer API Key API Key found 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


Once you're finished defining a plan, click the Save button. If you want some apps 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 we 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. Select the plan you want to bind to an application by clicking the Select this Plan button.

On the next screen, specify an instance name of the plan. (This doesn't effect the service broker, so 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 our 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 / Standalone App

The process is pretty much the same, but you have to also pass a name in the contrast.appname system property under which to collect vulnerabilities.

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

DropWizard

Getting Started

Here's an example of how to run the Java Agent with your standalone/fatjar Dropwizard application:

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

The Java Agent will not be able to 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

Configuring GlassFish

If you launch GlassFish yourself, you'll have to add Contrast's JVM parameter to the domain.xml file in your domain directory, i.e. ${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 will need to substitute the path to contrast.jar and the GlassFish server for your environment.


Running Contrast on GlassFish with IntelliJ

This document will outline the process for installing Contrast on an application using the IntelliJ IDE, running GlassFish. As a prerequisite, download the Contrast plugin (contrast.jar) from the Contrast site.

Instructions

  1. On the menu bar, click the Start/Run icon next to the GlassFish service
  2. Wait for the server to finish launching

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

  6. Select the tab for Profiler
  7. Add the Name Contrast
  8. Add the following JVM Options: -javaagent:${DOWNLOADS}/contrast.jar
  9. Select Save

  10. Click on the Start/Run icon next to the GlassFish service trom the top menu bar and select Restart Server
  11. A Contrast startup message should appear in the GlassFish server log Console (allow 1-2 minutes extra time for server startup).

  12. After GlassFish has finished the startup process, IntelliJ will open a new web browser.
  13. Navigate to your application, and allow an extra minute for it to start up.

Running Contrast on GlassFish with NetBeans

As a prerequisite, download the Contrast plugin (contrast.jar) from the Contrast site.

Instructions

  1. Select the Services Tab
  2. Under Servers right click on the GlassFish Server and select Start
  3. Wait for the server to finish launching

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


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

  10. In NetBeans, right click on the GlassFish Server and select Stop
  11. After the server has finished shutting down, right click on the project and select Run
  12. A Contrast startup message should appear in the GlassFish server log Console. (Allow 1-2 extra minutes for server startup.)

  13. After GlassFish has finished the startup process, NetBeans will switch to the HTTP Server Monitor mode and open a new web browser.
  14. Navigate to your application, and allow an extra minute for it to start up.

Google App Engine

Getting Started

To install the Contrast agent in your Google App Engine environment, please follow the following instructions.

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

Assuming you are using Maven to deploy your application as described here, 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>

to end up with something like:

<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 simply 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

This document will outline the process for installing Contrast on an application using IntelliJ IDE's supported application servers.

Prerequisites

Download the Contrast plugin (contrast.jar) from the Contrast site.

Instructions

  1. Click on Run in the application toolbar then click on the Edit Configuration menu item from the dropdown
  2. Select the IntelliJ Server configuration instance
  3. Select the Server tab and enter the Contrast launcher string in VM Options: -javaagent:${DOWNLOADS}/contrast.jar -noverify

  4. Hit Apply and then Ok
  5. Start the Server
  6. A Contrast startup message should appear in the Server console. (Allow 1-2 extra minutes for server startup.)

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

More Information

Running Contrast on GlassFish with IntelliJ

JBoss 5+

Running JBoss from run.bat or standalone.bat (or .sh)

Installing on JBoss is easy. If you run JBoss from domain.bat, standalone.bat, or run.bat with a .conf file, we suggest modifying the configuration file. It should enable the Contrast JVM parameters and then return to the start up script. To do this, simply 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'll have to substitute the path to contrast.jar and your JBoss server directory for your environment.

Running JBoss 6 EAP/JBoss 7.X in Domain Mode

If you're running in domain mode (using domain.bat or domain.sh), you'll have to add the -javaagent switch to the JVM options in $JBOSS_HOME/domain/configuration/domain.xml. Here's 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

Installation

Installing on Jetty is easy. Add the following lines to your ${JETTY_DIR}\start.ini file: -javaagent:${DOWNLOADS}/contrast.jar

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

Running on Jetty

  1. Download the Contrast plugin (contrast.jar) from the TeamServer.
  2. Set your MAVEN_OPTS environment variable to contain Contrast's JVM parameters: -javaagent:${DOWNLOADS}/contrast.jar
  3. Run your jetty:run or other Maven target normally.
  4. A Contrast startup message should appear in the Console (allow 1-2 minutes extra time for server startup).
  5. Navigate to your application, and allow an extra minute for it to start up.

More Information

Not using jetty.ini? Running Contrast from Other Jetty Launchers:

Karaf

Installing On Karaf

Add a KARAF_OPTS environment variable containing the -javaagent flag before starting the container:

$ export KARAF_OPTS=-javaagent:/path/to/contrast.jar

Afterwards, 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 will probably want to use two extra system properties when running Contrast:

  • contrast.classpath.libs, which tells Contrast to use the standard classpath libraries instead of libraries found in /WEB-INF/lib
  • contrast.appname, which allows you to name your application

Adding these flags will result in an export that looks more like the following:

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

Maven Apache Tomcat

This document will outline the process for installing Contrast on an application using the Apache Maven Tomcat plugin.

Prerequisites

Download the Contrast plugin (contrast.jar) from the TeamServer that you work with, either Contrast's SaaS deployment or your EOP installation.

Installation with MAVEN_OPTS

  1. If you are 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
    
  2. Run with the tomcat7:run-war or other Maven goal normally. Note that library analytics won't be collected if a goal besides run-war is chosen.

  3. A Contrast startup message should appear in the Console (allow 1-2 minutes extra time for server startup).
  4. Navigate to your application, and allow an extra minute for it to start up.

Maven Cargo Plugin

Prerequisites

Download the Contrast plugin (contrast.jar) from the Contrast site.

Instructions

  • Add a <cargo.jvmargs> property to the <properties> section of <configuration> in your pom.xml, like this: </configuration
<build>
  <plugins>
    <plugin>
      <groupId>org.codehaus.cargo.maven2</groupId>
      <artifactId>cargo-maven2-plugin</artifactId>
      <configuration>
        <container>
          <containerId>tomcat5x</containerId>
          [...]
        </container>
        <configuration>
          <properties>
            <cargo.jvmargs>-javaagent:${DOWNLOADS}/contrast.jar -noverify</cargo.jvmargs>
          </properties>
        </configuration>
        [...]
      </configuration>
    </plugin>
  </plugins>
</build>
  • Run your Maven target or Cargo unit test normally.
  • A Constart startup message should appear in the Console before your server messages appear. (Allow 1-2 extra minutes for server startup.)
  • Navigate to your application, and allow an extra minute for it to start up.

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

NetBeans

This document outlines the process for installing Contrast on an application using the NetBeans IDE with JBoss.

Prerequisites

Download the Contrast plugin (contrast.jar) from the Contrast site.

Instructions

  1. Open the NetBeans project
  2. Select Tools > Servers
  3. Select the server you wish to add Contrast to (in this example, JBoss), and click on the Platform tab

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

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

  6. A Contrast startup message should appear in the Server console (allow 1-2 minutes extra time for server startup)

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

More Information

Running Contrast on GlassFish with NetBeans

Play

Running Contrast From The Command Line With Activator

Play makes adding JVM options to the application's JVM a little different than standard Java options syntax. In order for Play to pass the option properly, they must be prepended with -J. As such, you'll need to add the following line to your Play startup command:

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

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

Running Contrast From A Script With Activator

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

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

Running Contrast With JAVA_OPTS

Older versions of Play have a known defect where they do not properly pass through the -J options. In order to work around this, it is recommended that you set JAVA_OPTS in the command line before calling activator:

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

Tomcat

Running Contrast from "startup.bat" (or ".sh")

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

For Windows startup-with-contrast.bat:

set CATALINA_OPTS="%CATALINA_OPTS% -javaagent:${DOWNLOADS}\contrast.jar"
call ${TOMCAT_DIR} \bin\startup.bat

For Unix startup-with-contrast.sh:

export CATALINA_OPTS="$CATALINA_OPTS -javaagent:${DOWNLOADS}/contrast.jar"
${TOMCAT_DIR}/bin/startup.sh

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

Of course, you'll have 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.

Running Contrast on the Tomcat service in Windows

If you run Tomcat from as a service, changing the JVM options to add the agent requires opening the Tomcat service manager. You can do this by double clicking the Tomcat icon in the System tray (or right clicking and hitting Configure.) If the icon is not there, you might have to start it manually by running tomcat7w.exe in the Tomcat bin directory.


Switching to the Java tab will show you 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

Getting Started With 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.

Configuring Vert.x Web Applications with the Java Agent

Recommendeded Approach:

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. This can be achieved by including 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, the Contrast Java Agent can be configured as a JVM_OPT in the "vertx" script file:

Note: the paths to the application's dependencies will need to be included 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 Contrast Java Agent can identify the application name. If this is the case, please define the application name via -Dcontrast.appname=AppName property when launching the Vert.x application with Contrast enabled. For example:

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

WebLogic

Getting Started on Unix

If you launch WebLogic yourself, you'll have to 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 this:

/path/to/appserver/userprojects/domains/base_domain/bin/startWebLogic.sh

In this file, before the Java execution step, add the Contrast engine as a -javaagent to the JAVA_OPTIONS environment variable:

export JAVA_OPTIONS="$JAVA_OPTIONS -javaagent:/path/to/contrast.jar"

Getting Started on Windows

For Windows systems, the path looks like this:

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'll have to substitute the path to contrast.jar and your WebLogic server for your environment.

WebSphere

Getting Started

If you launch WebSphere yourself, you'll have to add Contrast's JVM parameter to the server.xml file in your cell directory, i.e.

${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'll have to substitute the path to contrast.jar and your WebSphere server for your environment.

Installing Contrast through the WebSphere Administration Console

You can also install Contrast through the WebSphere administration console. These instructions are for WebSphere 8.0/8.5 - instructions for other versions are included in the link below.

The following steps are from the Websphere support site (includes documentation 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

Note: IBM J9 does not allow the Java Instrumentation API to alter core Java classes when using the Shared Classes feature, so this must be disabled 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.