Setting Up the Forwarder

Table of Contents

Configuration in the Web UI
- Adding a Forwarder
Configure Your Firewall
Setting up the Forwarder in Your Environment

Need help?

Schedule a consultation with an Azul performance expert.

Talk about OpenJDK?

Discuss with the community on the Foojay Forum.

Setting up a Forwarder involves steps both in the Azul Vulnerability Detection Web UI and on a machine within your environment. This step-by-step guide will help you in this process.

Configuration in the Web UI

Administrators must set up a Forwarder in the Azul Vulnerability Detection Web UI to connect it to their account. Forwarders are created on a per-Azul Vulnerability Detection basis and can be managed by administrators.

Visit the Web UI of your Azul Vulnerability Detection instance.

Adding a Forwarder

In the Setup section of the Web UI click "Forwarder".
In the "Forwarders list", click the "Add" button.
Fill in the fields to configure your Forwarder.
- Forwarder name: this is a free value. It is a name to manage your Forwarder more easily, not a domain name. If your organization uses multiple Forwarders, consider a naming convention that signifies usage.
- Forwarder’s Domain Names: a list of domain names that your JDKs will use to communicate with this Forwarder. The first entry will be your certificate’s Common Name (CN) and subsequent entries will be Server Alternative Names (SAN).
Click the "Add" button to store the new Forwarder.
The "Forwarder ID" and "Access key" will be shown. Also the pre-populated settings are provided. Make a copy of these to use in a following step. You can also download them as a ready-to-use properties file with the "Download as file" button.

Note

For security reasons, by default the Forwarder is not allowed to run as a server in a public domain to avoid unwanted behaviour like sending sensitive JVM data to the public internet and causing incorrect traffic on the domain.

If your environment requires the use of a public domain, you can request Azul support to change the configuration of your Azul Vulnerability Detection environment to add it as an approved domain.

Configure Your Firewall

The Forwarder will need to have access to the Azul Vulnerability Detection service, through the firewall of your system.

Only one rule needs to be added with outgoing access to:

The host address (API URL) of the Azul Vulnerability Detection service that has been set up for you by Azul. You can copy this from the Web UI Forwarder setup screen.
On port 443 (HTTPS).

Setting up the Forwarder in Your Environment

The remaining configuration of the Forwarder has to be done within your environment.

Server Requirements

The Forwarder can run on any server within your environment at a location where it can be reached by many JVMs and the Forwarder itself can reach Azul Vulnerability Detection. The only requirement is a Java runtime, version 8 or newer.

Downloading the Forwarder

The Forwarder application can be downloaded from the Azul repository:

 curl -O https://cdn.azul.com/forwarder/1.0.2/forwarder.jar

Configuration for the Forwarder

Three different possibilities are supported to configure the Forwarder, and the values defined in each of them have this priority:

System variables
Properties file
Environment variables

Some settings are the ones filled in or retrieved from the Web UI earlier, others are related to the created certificate. The settings will be used by the Forwarder to connect to Azul Vulnerability Detection. Once authenticated, the Forwarder will exchange this information with Azul Vulnerability Detection to receive cryptographic certificates that will be trusted by the JVM.

These values need to be specified:

Environment	System	Properties
IC_HOST	icHost	ic.host
The host of Azul Vulnerability Detection, copied from the Web UI Forwarder setup screen.
FORWARDER_ACCESS_KEY	forwarderAccessKey	forwarder.access.key
The Forwarder Access Key copied in the Azul Vulnerability Detection Web UI after adding the Forwarder. This Access Key will be used for authentication to Azul Vulnerability Detection.
FORWARDER_DOMAIN_NAMES	forwarderDomainNames	forwarder.domain.names
A comma-delimited list with he Forwarder Domain Names (all or subset of them) that were used to create the Forwarder in the Azul Vulnerability Detection Web UI. These Domain Names will be used as SN/SAN attributes when creating the certificates for the authorization phase between the Forwarder and Azul Vulnerability Detection. This list can contain IP addresses, but must contain at least one domain name.
FORWARDER_KEYSTORE_PATH	forwarderKeystorePath	forwarder.keystore.path
If no JKS file is found in the specified path, an empty keystore with the same name will be created. This keystore is used to store the auto-generated Forwarder certificates.
FORWARDER_KEYSTORE_PASSWORD	forwarderKeystorePassword	forwarder.keystore.password
FORWARDER_PORT	forwarderPort	forwarder.port
The Forwarder will listen on this port for incoming connections from VMs. The default is 443.
LOG_LEVEL	logLevel	log.level
The default log level is INFO. Possible values (case-insensitive): ALL, TRACE, DEBUG, INFO, WARN, ERROR, OFF

Environment

System

Properties

IC_HOST

icHost

ic.host

The host of Azul Vulnerability Detection, copied from the Web UI Forwarder setup screen.

FORWARDER_ACCESS_KEY

forwarderAccessKey

forwarder.access.key

The Forwarder Access Key copied in the Azul Vulnerability Detection Web UI after adding the Forwarder. This Access Key will be used for authentication to Azul Vulnerability Detection.

FORWARDER_DOMAIN_NAMES

forwarderDomainNames

forwarder.domain.names

A comma-delimited list with he Forwarder Domain Names (all or subset of them) that were used to create the Forwarder in the Azul Vulnerability Detection Web UI. These Domain Names will be used as SN/SAN attributes when creating the certificates for the authorization phase between the Forwarder and Azul Vulnerability Detection.

This list can contain IP addresses, but must contain at least one domain name.

FORWARDER_KEYSTORE_PATH

forwarderKeystorePath

forwarder.keystore.path

If no JKS file is found in the specified path, an empty keystore with the same name will be created. This keystore is used to store the auto-generated Forwarder certificates.

FORWARDER_KEYSTORE_PASSWORD

forwarderKeystorePassword

forwarder.keystore.password

FORWARDER_PORT

forwarderPort

forwarder.port

The Forwarder will listen on this port for incoming connections from VMs. The default is 443.

LOG_LEVEL

logLevel

log.level

The default log level is INFO.
Possible values (case-insensitive): ALL, TRACE, DEBUG, INFO, WARN, ERROR, OFF

Note	If you are concerned about the security of the password (FORWARDER_KEYSTORE_PASSWORD) and/or key (FORWARDER_ACCESS_KEY) values, using environment variables is the recommended approach.

Using Properties File

When you want to use a properties-file to configure the Forwarder, follow these steps.

Create a new file forwarder-settings.properties
```
 touch forwarder-settings.properties
```

Edit the file and add the following content, specifying all the required values as defined in the table above.

 ic.host = ${intelligence-cloud-api-host}
forwarder.access.key = ${forwarder-access-key}
forwarder.domain.names = <domain-names-from-web-ui>
forwarder.keystore.path = <path-to-keystore>/forwarder.jks
forwarder.keystore.password = <desired keystore password>
forwarder.port = 443

Start the Forwarder Application

Start the Forwarder application with the following command:

 $JAVA_HOME/bin/java -DforwarderSettings=forwarder-settings.properties -jar forwarder.jar

Checking the State of the Forwarder

Unsuccessful Start

If either the Forwarder Access Key or Common Name does not match, the Forwarder will display an appropriate error message and fail to start. Keep an eye on the output of the Forwarder to check if it could start successfully. These are some possible error messages while connecting:

 Failed to init certificate challenge: responseCode=403, responseContent={"message":"Forbidden"}
Failed to authorize forwarder, the application will be stopped.

Successful Start

A successful startup will contain these info messages:

 Forwarder certificate signed by IC issued successfully
Start forwarding *:443 to YOUR_AVD_HOST:443

Status Screen

Also after a successful startup, a status page is available at the address https://{FORWARDER_ENDPOINT}.

Status API

The health of the Forwarder can also be checked via an API on https://{FORWARDER_ENDPOINT}/forwarder/health, which will return, for example:

 {
  "version":"1.0.2",
  "state":"GREEN",
  "uptime":"327454123",
  "formattedUptime":"03d 18h 57m 34s"
}

Or more extended data can be retrieved by adding ?extended=true like this https://{FORWARDER_ENDPOINT}/forwarder/health?extended=true, resulting in, for example:

 {
  "version": "1.0.2",
  "state": "GREEN",
  "uptime": "327609892",
  "formattedUptime": "03d 19h 00m 09s",
  "memory": {
    "heap.max": "883884032",
    "heap.used": "29223168",
    "heap.committed": "62656512",
    "heap.init": "16777216",
    "nonHeap.max": "-1",
    "nonHeap.used": "52401248",
    "nonHeap.committed": "57409536",
    "nonHeap.init": "7667712"
  },
  "cpu": {
    "jvmCpuUsage": "0%",
    "systemCpuUsage": "4%"
  }
}

Forwarder State

The state of the Forwarder is shown in both the Status-page and the API as GREEN in normal state or one of the following:

Metrics	Details	Threshold	State
OperatingSystemMXBean#ProcessCpuLoad	"recent cpu usage" for the Java Virtual Machine process	50%	YELLOW
OperatingSystemMXBean#ProcessCpuLoad	"recent cpu usage" for the Java Virtual Machine process	85%	RED
MemoryMXBean#HeapMemoryUsage	[amount of used memory in bytes] / [maximum amount of memory in bytes that can be used for memory management]	65%	YELLOW
MemoryMXBean#HeapMemoryUsage	[amount of used memory in bytes] / [maximum amount of memory in bytes that can be used for memory management]	90%	RED

Metrics

Details

Threshold

State

OperatingSystemMXBean#ProcessCpuLoad

"recent cpu usage" for the Java Virtual Machine process

50%

YELLOW

OperatingSystemMXBean#ProcessCpuLoad

"recent cpu usage" for the Java Virtual Machine process

85%

RED

MemoryMXBean#HeapMemoryUsage

[amount of used memory in bytes] / [maximum amount of memory in bytes that can be used for memory management]

65%

YELLOW

MemoryMXBean#HeapMemoryUsage

[amount of used memory in bytes] / [maximum amount of memory in bytes that can be used for memory management]

90%

RED