Install the Java agent

Install the Java agent on your system.


Quickstart

Installing the Sqreen Java agent allows you to monitor the security of your application and block attacks in realtime, and takes less than a minute:

  • Sign up to Sqreen to create your account.
  • Pick your first application name and language. The name of the application can be the name of the repository, or anything that helps you identify the app in your Sqreen dashboard.
  • Follow the procedure detailed below.

Standard Java application

The Sqreen Java agent requires you to change your JVM settings.

Download the agent:

curl https://download.sqreen.com/java/sqreen.jar -o sqreen.jar

Add the path to the agent and your Sqreen token and application name to the JVM startup command.

-javaagent:/path/to/sqreen.jar
-Dsqreen.token=<your Sqreen token>
-Dsqreen.app_name=<your application name>

Then start the application as usual.

Multiple agents

If there is more than one agent configured (-javaagent parameters), make sure Sqreen is the last in the command line.

Find your organization token by going to Account Settings > Tokens in your Sqreen dashboard, or (https://my.sqreen.com/profile/organization/tokens). Your token has the prefix org_.

To help Sqreen identify the application when you use an organization token, you also need to set a unique application name.

Application tokens deprecated

Application tokens are unique to an application. Organization tokens are available throughout the organization your account belongs to.

While Sqreen will continue to support application tokens for backward compatibility in the short term, they are now deprecated, and we encourage you to convert your applications to use organization tokens as soon as possible.

Follow this how-to to migrate applications using an application token.

Install the agent in a non-production environment

Typically you install the Sqreen agent in your production environment, but you can create several applications using your Sqreen dashboard, and specify the environment (development, staging, production). Use a unique Sqreen token for each of your applications.

-javaagent:/path/to/sqreen.jar
-Dsqreen.token=org_xxxxx
-Dsqreen.app_name='My Awesome App (dev)'

Basic configuration

Instead of using a system property value (-D parameter), you can use the SQREEN_TOKEN and SQREEN_APP_NAME environment variables to set up your application:

export SQREEN_TOKEN=org_xxxxx
export SQREEN_APP_NAME='My Awesome app'

The Sqreen Java agent provides flexible configuration settings. Refer to Configuration of the Java agent for more detailed information.

Uninstall the agent

To uninstall Sqreen agent, remove the -javaagent parameter from the JVM command.

Installing behind a proxy

If your host requires a proxy to connect to Sqreen, the installation procedure is slightly different.

Replace proxy and port with your proxy hostname and port.

Check connectivity

curl -I --proxy proxy:port https://back.sqreen.com/

This should output something like:

HTTP/2 404
date: Tue, 04 Sep 2018 15:19:08 GMT
content-type: application/json
content-length: 37
server: nginx

Download the agent

curl --proxy proxy:port https://download.sqreen.com/java/sqreen.jar -o sqreen.jar

Configure the agent

Add the path to the agent, your Sqreen token and your proxy configuration to the JVM startup command. You can also store these in a configuration file.

-javaagent:/path/to/sqreen.jar
-Dsqreen.token=<your Sqreen token>
-Dsqreen.app_name=<your application name>
-Dsqreen.proxy=http://proxy:3128/

Then start the application as usual.

Installing the Java agent on application servers

Most application servers use the JAVA_OPTS environment variable to set JVM settings.

You can also use the administration console provided with your application server. Refer to your application server documentation to see how to properly change JVM settings.

Download the agent

curl https://download.sqreen.com/java/sqreen.jar -o sqreen.jar

Set the JAVA_OPTS environment variable and make sure it resolves each time the Java server restarts:

export JAVA_OPTS="${JAVA_OPTS} -javaagent:/path/to/sqreen.jar"
export JAVA_OPTS="${JAVA_OPTS} -Dsqreen.token=<your Sqreen token>"

Then launch the application server as usual.

Advanced configuration

You have to use advanced configuration if you server is using any of the following:

Uninstall the agent

To uninstall the Sqreen agent, remove the JAVA_OPTS export (or the equivalent for you application server).

Notes

Use different Sqreen Applications for different environments

We recommend you to use different Sqreen applications on your different environments: production, staging and development.