How to configure Caldera REST API? (Debugging)

This guide is for experienced users who may need to modify the Caldera REST API's configuration JSON file in rare cases, such as debugging or unexpected behavior.

While manual changes are usually unnecessary, this article explains how to safely edit and validate the file when required.

Configuration file location

It is possible to configure the Caldera REST API through a JSON configuration file placed at the following location by default:

You can specify a different file location by setting:

• The CONF environment variable (case insensitive), eg. CONF=./my-conf.json ./Odin
• The --conf CLI argument (case insensitive), eg. ./Odin --conf=./my-conf.json

Configuration file properties

That file can contain the following properties:

• serverHost: (string) The address on which the REST API will accept connections, defaulting to "0.0.0.0" (ie. all network interfaces).

• serverPort: (number) The port on which the REST API will listen, defaulting to 12340.

• loggerLevel: (string) The log level from which the REST API will output the log, defaulting to "info". The possible log levels are (ordered by criticality ascending): "trace", "debug", "info", "warn", "error", "fatal".

• loggerPrettify: (boolean) Whether or not to prettify output logs, defaulting to false. When not prettified, outputs are JSON-formatted.

• services: (array | null) List of registered services, defaulting to null meaning discovered local services.
  

    Info

  Starting with V2, the Caldera REST API no longer searches for local services by default, leaving the service list empty until the user adds one via the API (POST /v1/services).

  
  Each service has the following properties:
  

    Warning

  To modify the service list, it is recommended to use the API routes (POST /v1/services) rather than editing the configuration file directly.

  • type: (string) Service type, amongst "calderarip", "primecenter", ...

  • host: (string) Service address.

  • port: (number) Service port.

  • license: (string) License ID used to communicate with the service (only relevant for PrimeCenter or DTX products).

As for the path to the configuration file, each of those properties can be overridden by:

• Environment variables (case insensitive), eg. SERVERHOST=127.0.0.1 SERVERPORT=12350 LOGGERLEVEL=trace LOGGERPRETTIFY=true SERVICES=[] ./caldera-rest-api
• CLI Arguments (case insensitive), eg. ./Odin --serverHost=127.0.0.1 --serverPort=12350 --loggerLevel=trace --loggerPrettify=true --services=[]

Start Caldera REST API for debugging

You may start the application from a Command Line Interface (CLI) of your Operating System. Here are the locations of the binary files: