The host of Azul Vulnerability Detection, copied from the Web UI Forwarder setup screen.
Setting Up the Forwarder
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.
-
If you click on the name of the generated Forwarder, you will get the page with its details. Here, the pre-populated settings are provided. Make a copy of these to use in one of the following steps. 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.5/forwarder.jar
Configuring 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.
This is an overview of the available configuration options:
Environment | System | Properties |
---|---|---|
IC_HOST |
icHost |
ic.host |
CLOUD_CONNECTION_POOL_SIZE |
cloudConnectionPoolSize |
cloud.connection.poolSize |
Connection pool size used to manage connections between the Forwarder and Azul Vulnerability Detection. The default value is Example: |
||
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 value is |
||
FORWARDER_STATE_REPORT_PATH |
forwarderStateReportPath |
forwarder.state.reportPath |
File path used by the Forwarder to periodically store its state. Example: |
||
FORWARDER_STATE_CHECK_PERIOD |
forwarderStateCheckPeriod |
forwarder.state.checkPeriod |
Human-readable period specifying how often the state of the Forwarder should be checked and stored in the report path. It can be defined in the following formats:
Example: |
||
LOG_LEVEL |
logLevel |
log.level |
The default log level is By default, when errors are caught in the Forwarder, only error messages will be logged, without a stack trace. If you need to see the stack trace for debugging or troubleshooting purposes, use the Possible values (case-insensitive):
|
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.5",
"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:
{
"state": "RED",
"version": "1.0.5",
"uptime": "100610966",
"formattedUptime": "01d 03h 56m 50s",
"reasons": [
"CPU usage exceeded the RED threshold: usage=86%, threshold=85%",
"Heap memory usage (70%) has exceeded 65%"
],
"memory": {
"heap.max": "10485760",
"heap.used": "7361768",
"heap.committed": "10485760",
"heap.init": "10485760",
"nonHeap.max": "-1",
"nonHeap.used": "28254384",
"nonHeap.committed": "31522816",
"nonHeap.init": "7667712"
},
"cpu": {
"jvmCpuUsage": "86%",
"systemCpuUsage": "97%"
}
}
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 |