Skip to main content
Version: 25.3.0

Portal Dedicated 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 Waratek Agent 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.

On-boarding Steps​

  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.ControllerPresent=<true|false>
    com.waratek.ControllerSecure=<true|false>
    com.waratek.ControllerHost=<IP address of the Portal Dedicated, i.e. 127.0.0.1>
    com.waratek.ControllerPort=8443
    com.waratek.rules.local=<full/path/to/jvc.rules>
    com.waratek.log.file=<full/path/to/armr.log>
    com.waratek.rules.autoreload=<true|false>

    # enables communication using self-signed SSL certificate:
    com.waratek.ControllerSSLCertificateValidation=<true|false>
    com.waratek.ElasticsearchPresent=<true|false>
    com.waratek.ElasticsearchSecure=<true|false>
    com.waratek.ElasticsearchHost=<IP address of the Elasticsearch e.g. 127.0.0.1>
    com.waratek.ElasticsearchPort=<e.g. 9200>
    com.waratek.ElasticsearchKey=<Password for accessing Elasticsearch from the Portal Dedicated which is in the readonlyrest.yml file. i.e. Testpass123>

  • com.waratek.ControllerSecure: OPTIONAL PROPERTY type of connection for the Waratek Agent connecting to the Portal Dedicated.

    • com.waratek.ControllerSecure=false for HTTP connection. Waratek Agent has the option of connecting via HTTP. The data will not be encrypted during transit and can be considered vulnerable with this configuration.
    • The default value is true if not specified and HTTPS connection will be used.

  • com.waratek.ElasticsearchSecure: OPTIONAL PROPERTY type of connection for the Waratek Agent connecting to the Elasticsearch.

    • com.waratek.ElasticsearchSecure=false for HTTP connection. Waratek Agent has the option of connecting via HTTP. The data will not be encrypted during transit and can be considered vulnerable with this configuration.
    • The default value is true if not specified and HTTPS connection will be used.

Java Agent communication supports the following versions of Elasticsearch:

  • Elasticsearch 7.x
  • Elasticsearch 8.x

Optional Flags​

Agent Name​

Agent naming may be set using the flag com.waratek.agent.name. In the Portal Dedicated UI, the value set will be displayed as the on-boarded agent’s name.

com.waratek.agent.name=<agent name>

Controller Unavailable Action​

The Agent checks if the Portal Dedicated and Elasticsearch are available while starting. The flag com.waratek.ControllerUnavailableAction can customize the Agent behavior. The following values can be used for the flag:

com.waratek.ControllerUnavailableAction= <FAIL | IGNORE | RETRY>

FAIL:

  • FAIL is the default value.
  • If Portal Dedicated is down, Agent will shut down JDK.
  • If ES is down, Agent will shut down JDK.

IGNORE:

  • If Portal Dedicated is down, JDK will start and Agent won’t communicate with Portal Dedicated and Elasticsearch.

  • If Portal Dedicated is up and Elasticsearch is down, Agent starts as normal.

    • Agent will buffer the events and send them to Elasticsearch when it becomes available.

RETRY:

  • If Portal Dedicated is down, Agent will start and re-try to communicate with Portal Dedicated later.

    • The events might be generated in the meantime. Instead of send the events to Elasticsearch, Agent will synchronize the events with Portal Dedicated when it becomes available. From that point, Agent will also send events from the buffer to Elasticsearch.

  • If Portal Dedicated is up and ES is down, Agent starts as normal.

    • Agent will buffer the events, and will send them to Elasticsearch when that becomes available.

Debug Transport File​

For debugging communication problems, the flag com.waratek.debug.transport.file can log Agent to Portal Dedicated communication errors into a file.

com.waratek.debug.transport.file=<full/relative path to a file>
  • If the flag points to an existing folder, the default log file name would be transport.debug.log.
  • The console output will print the communication errors as normal with the flag.

Configure Elasticsearch Connectivity by Username and Password​

  1. Replace the com.waratek.ElasticsearchKey property by the following two properties.

    com.waratek.ElasticsearchUsername=instance
    com.waratek.ElasticsearchPassword=Testpass123

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, encrypted, 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.

Handling situations where the Portal Dedicated is not available when the Agent is launching​

There are situations where the Portal Dedicated may not be available when the Waratek Agent is launching - and this could block the agent startup.

To avoid this situation a new flag is available to ensure the agent will launch even if the Portal Dedicated is offline/unavailable/un-contactable :

# the agent will start if the Portal Dedicated is not responsive
com.waratek.ControllerUnavailableAction=ignore

# the agent will NOT start if the Portal Dedicated is not responsive
com.waratek.ControllerUnavailableAction=fail

# the agent will start if the Portal Dedicated is not responsive - but will repeatedly attempt to connect in background
com.waratek.ControllerUnavailableAction=retry