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

The properties file can be located in:

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

export SQREEN_CONFIG_FILE=/custom/path/config.properties

Configuration variables

You can configure the Sqreen agent using environment variables or a properties file. The SQREEN_TOKEN is required. The other settings are optional. Here are the settings you can change:

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_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 in the form http://host:port, socks://host:port or direct:///. Forces the usage of a different proxy server (or no proxy at all) from the JVM's defaults 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)

Java properties configuration

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

  • A Java system property -Dsqreen.config_file=config.properties in your JVM arguments.
  • An environment variable SQREEN_CONFIG_FILE=config.properties.

You should use this configuration format if you want to configure multiple web applications running in the same application server. Applications are identified by their context path.

Here is a sample configuration with two applications:

# This is the default token
token=my_secret_token

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

app2.contextPath=/app2
# No token, so this app uses the default token
# This app has disabled sensitive data stripping
app2.strip_sensitive_data=false

System properties sample configuration

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

-Dsqreen.token=my_secret_token
-Dsqreen.log_location=log/sqreen.log
-Dsqreen.log_level=WARN
-Dsqreen.disable=false

Using a Proxy

When using an HTTP Proxy, where proxy-host is your proxy hostname and 3128 your proxy port:

-Dsqreen.proxy=http://proxy-host:3128/

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 parameters that are named 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
-Dsqreen.strip_sensitive_keys=password,secret,passwd,authorization,api_key,apikey,access_token,user_id,user_private_token
# 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

The Sqreen agent's certificate is used for HTTPS/TLS communication between the agent and Sqreen's servers. 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 intended 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. It is trusted by default by most OpenJDK/Oracle Hotspot JVMs. However, in a few cases an explicit import in Java keystore is required:

  • 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 https://dl.cacerts.digicert.com/DigiCertHighAssuranceEVRootCA.crt -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. You will be prompted for a keystore password, by default changeit is used.

For Websphere

  • 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 is used to 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.

Configuration of this feature is done through policy files.

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

// Allow Sqreen
grant codeBase "file:/path/to/sqreen/sqreen.jar" {
  permission java.security.AllPermission;
};

For Websphere

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

Limited cryptography

In some countries, usage of cryptography is limited, therefore some JVMs are shipped 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.