Configuration Options for CRS in JVM

Table of Contents

Configuration Options
- CRS Arguments
- Using Tags
  - Applying Tags
  - Recommended Tagging Practice
Where to Specify Arguments

Need help?

Schedule a consultation with an Azul performance expert.

Talk about OpenJDK?

Discuss with the community on the Foojay Forum.

Connected Runtime Services (CRS) is the component inside the JVM that runs your applications. CRS collects the dependency information of your application, and sends it via the Forwarder to Azul Vulnerability Detection.

Configuration Options

CRS can be controlled with the following command line arguments or environment variables.

Command line Environment Variable Options

Command line	Environment Variable	Options
`-XX:AzCRSMode`	-	`on`, `auto`, `off`
`-XX:AzCRSArguments`	`AZ_CRS_ARGUMENTS`	See description below
`-Dcom.azul.crs.instance.tags`	`CRS_TAGS`	See description below

-XX:AzCRSMode

on, auto, off

-XX:AzCRSArguments

AZ_CRS_ARGUMENTS

See description below

-Dcom.azul.crs.instance.tags

CRS_TAGS

See description below

CRS Arguments

CRS Arguments are specified in a comma-separated value format.

 -XX:AzCRSArguments=expression1,expression2,expression3,...

OR

export AZ_CRS_ARGUMENTS=expression1,expression2,expression3,...

Each expression is either <propertyName>=<value>, or just <propertyName> for Boolean properties. These are the available properties:

Argument Default Description

Argument	Default	Description
UnlockExperimentalCRS	true	This is a special boolean argument only to be specified in the `AZ_CRS_ARGUMENTS` environment variable if CRS is enabled via environment (i.e. no `-XX:+UnlockExperimentalVMOptions` and `-XX:AzCRSMode` VM flags are passed). Without this flag `AZ_CRS_ARGUMENTS=enable` alone will not start CRS.
enable	true	Applied after the AzCRSMode, this offers a way to disable CRS for those who cannot adjust the command line. Set to `false` to disable.
tags	null	A semi-colon-separated list of tags to apply to the runtime. For searching and grouping.
delayInitiation	2000	Number of milliseconds to delay the CRS start. The default enables integration with major Java frameworks. Lower to 0 for short-lived microservices.
delayTermination	0	Number of milliseconds to hold a JVM alive at its end, providing time to complete analysis of loaded code. Raise the value to provide time to analyze short-lived microservices. The provided value will be used as a maximum, if CRS takes less time (down to 0), the delay will not use the fully defined duration.
log	ERROR	The level of logging for CRS. Options are (case insensitive): `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR`, `OFF`. The use of the `TRACE` level is discouraged, since the size of the output will be enormous.
keystore	null	If set, this keystore will be used to authenticate the JVM with the Forwarder. Set this to a Java Keystore file if you are using self-signed certificates.
props	~/.az_crs/config.properties	Location of a properties file to configure CRS.
api.url	null	This is the base URL of your Forwarder instance. If null, your runtime will perform a DNS-based lookup to locate its Forwarder. If no Forwarder is specified anywhere, CRS will be effectively disabled.
inventory.environment.allow	AZ_CRS_*	Prefixes of environment variables that CRS may collect.
inventory.environment.deny	null	After environment variables are allowed, deny any sensitive keys.
inventory.system.properties.allow	null	Prefixes of system properties that CRS may collect.
inventory.system.properties.deny	null	After system properties are allowed, deny any sensitive properties.
printParameters	false	Print the value of all CRS arguments.
heartbeat	4	Number of seconds for your JVM to keep its long-lasting connection to the Forwarder open. Raising this may improve Java 11+ through its HTTP2 connections but may cause timeout/new connections with Java 8 HTTP 1.1.

UnlockExperimentalCRS

true

This is a special boolean argument only to be specified in the AZ_CRS_ARGUMENTS environment variable if CRS is enabled via environment (i.e. no -XX:+UnlockExperimentalVMOptions and -XX:AzCRSMode VM flags are passed).

Without this flag AZ_CRS_ARGUMENTS=enable alone will not start CRS.

enable

true

Applied after the AzCRSMode, this offers a way to disable CRS for those who cannot adjust the command line. Set to false to disable.

Using Tags

A tag is a user-defined key-value pair that is associated with an instance. Tags are used to search, categorize, and organize instances logically in the Azul Vulnerability Detection Web UI. Unlike instance IDs, tags are not unique. You can add the same tag to multiple instances as well as add multiple tags to one instance.

Applying Tags

Tag keys must begin with a letter. Both key and value may contain lower and upper case letters, and numbers. These additional characters are also allowed:

 ALLOWED_KEY_EXTRA_CHARS = "-_."
ALLOWED_VALUE_EXTRA_CHARS = "-_. :/@" <-- Includes space

Note	Tags can be provided both as environment variable and in command line options. When using both, the result will be combined. It’s recommended to use environment variables as it allows AZ_CRS_ARGUMENTS to be mostly the same for each JVM.

A few examples as command line argument or environment variable:

 -Dcom.azul.crs.instance.tags="system-prop.tag_1=system prop/[email protected]; system_prop_tag.2=system prop:value/2"

OR

export CRS_TAGS="env.tag-1=value:1; env_Tag_2=value 2"

Recommended Tagging Practice

It is important that you properly tag your instances. As a general rule, tagging should reflect the way you categorize your Java applications. For example, you can use "west-coast", "east-coast", and so on to distinguish between different availability zones/locations.

Note	Some instance properties are detected automatically. For example, you don’t have to tag Java versions, because it’s detected by CRS.

Where to Specify Arguments

To configure your instances, you can choose to use one of the three options:

JVM command line arguments
The AZ_CRS_ARGUMENTS environment variable
A .properties file

The connected runtime looks for the configuration parameters in the order described above. You can use a combination of these options. If you set a parameter in several ways, for example via both the environment variable and configuration file, the JVM uses the value that comes first in the order given above.

In addition, the Forwarder address can be configured via DNS records. See Service discovery via DNS.

Command Line Arguments

Pass configuration parameters to the CRS (Connected Runtime Service) in the Azul JVM by using the -XX:AzCRSArguments command line argument:

Minimal command that sets the api.url parameter via JVM arguments.:

 java -XX:+UnlockExperimentalVMOptions \
    -XX:AzCRSMode=on \
    -XX:AzCRSArguments=api.url={forwarder_endpoint} \
    MyApp

A more extended example via JVM arguments:

 java -XX:+UnlockExperimentalVMOptions \
    -XX:AzCRSMode=on \
    -XX:AzCRSArguments=api.url={forwarder_endpoint},log=DEBUG,delayTermination=120000,delayInitiation=0 \
    -Dcom.azul.crs.instance.tags={tags} \
    MyApp

Environment Variable

Prime and Zulu Core distributions use a dedicated environment variable that can be controlled for all processes. When the environment variable is present, it will automatically apply to any new JVM. Substitute your forwarder_endpoint.

Starting with environment variables and optional arguments:

 export CRS_TAGS={tags}
export AZ_CRS_ARGUMENTS=UnlockExperimentalCRS,enable,api.url={forwarder_endpoint},log=DEBUG,delayTermination=120000,delayInitiation=0
java MyApp

Properties File

A third way to set the CRS parameters is to use a local .properties file. There are two default locations where CRS looks for the properties file, and you can specify a custom properties file as a command line argument. CRS looks for the properties file in the following order:

the file provided via the -XX:AzCRSArguments=props=/path/to/config.properties argument
~/.az_crs/config.properties in the user’s home directory
$JRE/lib/crs.properties, where $JRE is the directory where the JRE is located