Skip to main content
Version: 25.3.0

Portal On-boarding Process

Requirements​

The Waratek Agent must be installed in order to onboard it. See the relevant Waratek Agent Installation Guide for more information.

The following filesystem permissions are required:

  • read and write permission to the Portal installation directories;
  • read and write permissions to the rules file as well as the rules file parent directory. The rules file location is set by the value of the com.waratek.rules.local property defined in the waratek.properties file.

If the Waratek Agent is behind a firewall then TCP connections need to be configured from the Agent to agent-api-2.waratek.com.

If the Agent is running on an older JDK that does not support TLS version 1.2 by default then additional domains may be required.

On-boarding Steps​

Step 1: Setup Agent Properties File​

  1. Open (or create if it does not already exist) the waratek.properties file;

  2. Ensure the file contains the following waratek.properties:

    com.waratek.ControllerHost=<Address of the Portal>
    com.waratek.OrgId=<Your organization ID>
    com.waratek.accessKey=<An access key>
    com.waratek.secretKey=<A secret key>
    com.waratek.rules.local=<full/path/to/rules.armr>
    com.waratek.log.file=<full/path/to/rules.log>
    com.waratek.rules.autoreload=true

The waratek.properties file may contain additional, optional, waratek.properties.

This feature automatically assigns an Agent to an application in the Portal without any manual intervention. The user does not need to assign the agent to the application.

  1. In the Portal, navigate to “Applications” ---> [An Application Page] ---> “Configure”;
  2. Copy the on-boarding key;
  3. Paste the on-boarding key as the value of the com.waratek.ControllerKey property in the waratek.properties file.

Step 3: Launch the Agent and Assign it to an Application​

Launch the Waratek Agent.

  1. If automatic on-boarding is enabled, the agent will be automatically assigned to the specified application;

  2. If automatic on-boarding is not enabled, the Agents assigned to an Application as follows:

    1. In the Portal navigate to “Applications” ---> [An Application Page] ---> “Agents”;
    2. Click the “Unassigned Agents” dropdown menu;
    3. Select the checkbox for the Agent that was launched;
    4. Click the “Assign” button.

Successful On-boarding​

Successful on-boarding results in the Agent credentials persisting in the instance.waratek.properties file. For example:

########################################################
# THIS WAS GENERATED BY THE CONTROLLER - DO NOT MODIFY #
com.waratek.NodeId=ENC(DYIImFBaaL3QP+uauK6Y5Q==)
com.waratek.NodePassword=ENC(sBq6EmmsBOGd9K2iafh9+Uud3MlryAY4IOtOMEjhr7c=)
########################################################

If an agent is ungracefully shutdown, which could happen during a DOS type of attack against an application, the agent might not send the very latest events to the Portal. Please check the local log file for the events when necessary.

Connecting Agents via Proxy​

It is necessary to create rules in your firewall to allow each new agent to talk to the Portal. Rather than doing this on a per-agent basis, a single rule in the firewall is much easier to manage and is more secure.

To achieve this you need to have each agent connect to a proxy that sits within your network. The agent requests are then proxied to the Portal, allowing a single firewall rule to be created for the proxy. Waratek Agent supports an on-premise proxy for agents to connect to the Portal. The requirements for a successful connection are:

  • SSL using a CA-signed certificate
  • TLS 1.2
  • The proxy must set the X-Forwarded-For header
  • The proxy must set the X-WTK-Proxy header to the hostname of the proxy.

Any proxy tool which supports these requirements may be used. See below for an example Nginx configuration extract:

http {
// ... other settings go here

server {
listen 443;
ssl on;
ssl_certificate "/path/to/fullchain.pem";
ssl_certificate_key "/path/to/privkey.pem";
location / {
proxy_pass https://agent-api-2.waratek.com/;
proxy_ssl_server_name on;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-WTK-Proxy wrtk-proxy.myorg.com;
}

Specifying a custom port number​

The agent connects to the Portal using port 443 by default. If the agent is connecting to the Portal via a proxy, the port number can be set using the following property;

com.waratek.ControllerPort=<port number>

The com.waratek.ControllerPort property is supported only on Java Agent v25.0.0+

If com.waratek.ControllerPort is not specified, the default value is 443

Specifying insecure Agent-Portal communication​

The following property is supported only on Java Agent v25.0.0+, for agents connecting to the Portal:

com.waratek.ControllerSecure=<true|false>

If the agent is connecting to the Portal via a proxy, and the proxy is not configured for SSL communication, then com.waratek.ControllerSecure can be set to false

If com.waratek.ControllerSecure is not specified, the default value is true