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.

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.

Skip to section "Where to specify arguments" for a quick start.

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`	-	`auto`: Default value. CRS decides whether it needs to start in the main method, and excludes tools like `javap`, `javac` having a specific main method in `com.sun.tools`. `on`: Forces CRS to start, if all required configurations are available (e.g. endpoint), even for tools like `javap`, `javac`. `off`: Forces CRS to be disabled regardless of the `AzCRSArguments` CLI option, `AZ_CRS_ARGUMENTS` env variable, and `az_crs.properties` configuration file.
`-XX:AzCRSArguments`	`AZ_CRS_ARGUMENTS`	See description below
`-Dcom.azul.crs.instance.tags`	`CRS_TAGS`	See description below

-XX:AzCRSMode

auto: Default value. CRS decides whether it needs to start in the main method, and excludes tools like javap, javac having a specific main method in com.sun.tools.
on: Forces CRS to start, if all required configurations are available (e.g. endpoint), even for tools like javap, javac.
off: Forces CRS to be disabled regardless of the AzCRSArguments CLI option, AZ_CRS_ARGUMENTS env variable, and az_crs.properties configuration file.

-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
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 send the collected data to the Forwarder. Raise the value to provide time to 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.
notifyFirstCall	false	Enables the Code Inventory functionality at the method level. When set to `true`, it will send events of the first method execution to the Forwarder.
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. The Forwarder endpoint must be in URL format, e.g. `https://FORWARDER_IP:443`.
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.

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/value@1; 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 enable and configure your instances for CRS, you can choose to use one of these three options:

JVM command line arguments
The AZ_CRS_ARGUMENTS and CRS_TAGS environment variables
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:AzCRSMode=on \
    -XX:AzCRSArguments=api.url={forwarder_endpoint} \
    MyApp

A more extended example via JVM arguments:

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

Environment Variables

You can use dedicated environment variables to enable and control all JVM processes for Prime and Zulu Core distributions. When the environment variables are present, they will automatically apply to any newly started JVM, enabling CRS.

Substitute your forwarder_endpoint in the following example.

Starting with environment variables and optional arguments:

 export CRS_TAGS={tags}
export AZ_CRS_ARGUMENTS=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