Configuration in Java

You can adjust Sqreen settings according to your needs. This section lists the possible configuration options you have with the Sqreen Java agent.

Configuration sources

The Sqreen agent reads its configuration from different places. This is the order of precedence:

  • Environment variables
  • Java system properties in the JVM command line
  • A Java properties file
  • Default configuration options

You can store the properties file in:

  • Your application top level directory
  • In a custom place set by SQREEN_CONFIG_FILE environment variable:
export SQREEN_CONFIG_FILE=/custom/path/

Configuration variables

Find your organization token by going to Account Settings > Tokens in your Sqreen dashboard, or ( 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.

The Sqreen Java agent requires the SQREEN_TOKEN variable. The other settings are optional.

When using an organization-wide token, you must provide the application name (SQREEN_APP_NAME) for Sqreen to identify the application. If not set, application name will be generated automatically from webapp context path.

Env variable name Role Properties key name Default value
SQREEN_TOKEN The Sqreen token. This identifies the agent to Sqreen backend servers token Empty
SQREEN_APP_NAME The application name as displayed within the Sqreen dashboard app_name webapp context path
SQREEN_CONFIG_FILE Custom location for the JSON based config Empty
SQREEN_LOG_LOCATION Specify a custom file to write Sqreen logs log_location log/sqreen.log
SQREEN_LOG_LEVEL Sqreen logging level log_level WARN
SQREEN_PROXY A URI to set http proxy, see below for syntax proxy Empty (no proxy)
SQREEN_IP_HEADER Specify the header to use to find the real IP address of a client ip_header Empty
SQREEN_STRIP_SENSITIVE_DATA Remove sensitive data before sending them to Sqreen BackEnd strip_sensitive_data 1
SQREEN_STRIP_SENSITIVE_KEYS Comma separated list of keys to strip, refer to dedicated section below for details strip_sensitive_keys see here for default values
SQREEN_STRIP_SENSITIVE_REGEX Regular expression used for value stripping, refer to dedicated section below for details strip_sensitive_regex see here for default values
SQREEN_DISABLE Prevents Sqreen agent from starting. Any value in this environment variable will disable Sqreen. disable false (Sqreen is enabled)
SQREEN_IGNORED_PACKAGES_PREFIXES Comma-separated list of class/packages prefixes to ignore ignored_packages_prefixes usage

Java properties configuration

To use a Java properties file for configuration, you need to provide the configuration file through either:

  • A Java system property in your JVM arguments.
  • An environment variable

You should use this configuration format if you want to configure more than one web application running in the same application server. Sqreen identifies applications by their context path.

Here is a sample configuration with two applications:

# This is the default token
# This will be the default application name, all web-applications deployed
# will be grouped in this application unless explicitly set
app_name=Default app

# --- App 1

# Configuration for an application deployed on /app1 context
# All attributes that start with the app1. prefix are used

# --- App 2

# No token, so this app uses the default token
# This app has disabled sensitive data stripping
# No app_name, thus this app will use the default app name

System properties sample configuration

Add system properties as JVM arguments using the -Dkey=value syntax. Always use the sqreen prefix to avoid conflicts.

-Dsqreen.app_name=My Awesome App

Using a proxy

If you use an HTTP Proxy, use the following syntax where proxy-host is the hostname and 3128 the proxy port:


If you proxy uses authentication, provide user credentials in the proxy URI, for example with bob and secret123 as username / password.


Personally identifying information scrubbing

Personally identifying information (PII) Scrubbing lists default scrubbing values.

Changing the sensitive keys configuration overrides defaults, meaning you need to append your extra keys to the list of predefined keys. This also applies to sensitive regex.

As an example, if you want to:

  • Scrub two parameters, user_id and user_private_token.
  • Scrub values that contain a known pattern 0000-0000-0000 defined by regex [0-9]{4}-[0-9]{4}-[0-9]{4}

You have to use this configuration:

# we just append our extra parameter names to the default list
# regex here is enclosed in single quotes to prevent shell interpolation.
# The default value here is a common pattern for credit cards
# our pattern is defined using the [0-9]{4}-[0-9]{4}-[0-9]{4} regular expression.
# we just have to combine it with | to the default value for credit cards (?:\d[ -]*?){13,16}
-Dsqreen.strip_sensitive_regex='(?:\d[ -]*?){13,16}|[0-9]{4}-[0-9]{4}-[0-9]{4}'

Custom truststore

Relevant only for versions prior to 1.4.0

From version 1.4.0 and later, an embedded keystore with known root Certificate Authority certificates is used as a transparent fallback. Updating to the latest version of the agent is recommended.

HTTPS/TLS communication between the agent and Sqreen's servers uses the Sqreen agent's certificate. It depends on a root Certificate Authority (CA) certificate to be trusted by JVMs.

The terms keystore and truststore refer to the storage of keys and certificates. The difference is that keystore is for (private) key storage, and truststore for trusted certificates. You can split these two variants into distinct files, but are both managed using the keytool command line utility.

DigiCert provides the Sqreen root CA certificate. Most OpenJDK/Oracle Hotspot JVMs trust it by default. In some cases you need to explicitly import it in the Java keystore:

  • Some Docker images ship with a minimal keystore.
  • When using a custom keystore where default CAs certificates are absent.
  • Some containers (like Websphere) explicitly use a minimal keystore.

In those cases, you must import our root certificate into your truststore.

Download the root CA certificate here, and use the following command snippet to import it into your keystore:

curl -o /tmp/rootca.crt
keytool -import -alias sqreen_digicert_root_ca -file /tmp/rootca.crt -keystore /path/to/your/keystore

Where /path/to/your/keystore is the location of your keystore.

It prompts you to enter a keystore password. changeit is the default.


  • The default truststore password is WebAS.
  • The truststore filename is trust.p12 and is set per-profile.
  • The truststore uses PKCS12 format, so you have to add -storetype PKCS12 to the keytool command.
  • If using IBM J9 JVM, you have to use the keytool version shipped with it. You can't use the Oracle or OpenJDK versions.

Security manager

Java provides an execution sandbox through the SecurityManager class. This feature can sandbox browser Applets, RMI and also some application servers like Websphere.

When used, this feature requires you to explicitly grant rights to the Sqreen agent.

Configure this feature through policy files.

Assuming that sqreen.jar is in /path/to/sqreen, add these lines to your policy file:

// Allow Sqreen
grant codeBase "file:/path/to/sqreen/sqreen.jar" {


The policy file is server.policy and is set per-profile.

Limited cryptography

Some countries limit the use of cryptography, meaning some JVMs ship by default with restrictions on key lengths.

The Sqreen SSL/TLS certificate requires 4096 bits keys, so you have to use the unrestricted policy. If you can't, please contact us.

Refer to your JVM vendor manual for reference on how to install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy.

Advanced parameters

Ignore packages & classes

Sqreen agent needs to build a list of all the relevant classes that need instrumentation. While this process is usually very fast, there are some known cases where it can create performance issues, especially when large libraries with signed packages are being used.

When this happens, the workaround is to use the ignored_packages_prefixes property to make Sqreen agent ignore those classes. This property should contain a comma-separated list of classes names and packages to ignore.