Advanced Configuration in Java


Configuration variables

System property values override environment variables.

Sqreen agent can be configured using environment variables, system property value or a YAML configuration file. Here are the settings that can be customised:

Variable name Description YAML key name Default value
SQREEN_TOKEN Sqreen token. This identifies agent to Sqreen backend servers token Empty
SQREEN_LOG_LOCATION Specify a custom file to write Sqreen logs log_location ${java.io.tmpdir}/sqreen.log
SQREEN_LOG_LEVEL Sqreen logging level log_level WARN
SQREEN_DISABLE Prevents Sqreen agent from starting. Any value in this environment variable will disable Sqreen. disable false (Sqreen is enabled)

YAML sample configuration

sqreen:
    token: my_secret_token
    log_location: log/sqreen.log
    log_level: WARN
    disable: false

System property sample configuration

-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, Sqreen uses standard JVM system properties.

-Dhttp.proxyHost=<proxy host>
-Dhttp.proxyPort=<proxy port>

Custom truststore

Our certificate used for HTTPS/TLS communication between agent and our servers depends on a root Certificate Authority (CA) certificate to be trusted by JVMs.

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

Our root CA certificate is provided by DigiCert and is trusted by default by most OpenJDK/Oracle Hotspot JVMs. However, in few cases an explicit import in Java keystore is required :

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

In those cases, you will have to import our root certificate into your truststore.

Root CA certificate can be downloaded here. You can use the following command snippet to import 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 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 used PKCS12 format, thus 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 Oracle or OpenJDK version.

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 will require to explicitly grant rights to our agent.

Configuration of this feature is done through policy files.

Assuming that sqreen.jar is located in /path/to/sqreen, you will have to add those 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.

Our SSL/TLS certificate requires to be able to support 4096 bits keys, thus you will 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 Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy.