Configuration

Configuration

Tray

The Tray application loads a configuration file with a fixed name of config-tray.json from the current working directory. This file is optional and if it does not exist, a default one will be created automatically. The specification for this configuration file is:

port [ 0 < number < 65535 ]

This specifies the port at which network connections are received. On some operating systems, choosing a port < 1024 will require the application to run with elevated privileges.

secret optional [ string ]

This value is a secret string that has to be sent by the C-Troll application in order to authenticate itself. If the wrong string is send, any command is ignored. The default value for this is the empty string, which disables authentication.

showWindow optional [ boolean ]

If this value is set to true, the window of the Tray will be shown. Otherwise, the default, the application will automatically be minimized to a tray application

logRotation [ object ]

If this value is present, a regular log rotation is performed in which the created log file is purged and optionally backed up before. This object has two optional keys frequency [ integer ] which specifies the frequency of log rotations in hours and keepPrevious [ boolean ] that determines whether the previous logs should be backed up or not. The log backups follow the naming scheme log_tray_{date}-{index}.txt where the date is the date at which the log rotation was performed and an optional index for the case when there are more than one log rotations per day.

C-Troll

config.json

The C-Troll application loads a configuration with a fixed name of config.json from the current working directory.

applicationPath [ string ]

Specifies the location relative to the current working directory from which application configurations are loaded. Every file with the .json extension will be automatically added, even if they are in subdirectories.

clusterPath [ string ]

Specifies the location relative to the current working directory from which the cluster information are loaded. Every file with the .json extension will be automatically added, even if they are in subdirectories.

nodePath [ string ]

Specifies the location relative to the current working directory from which the information about nodes are loaded. Every file with the .json extension will be automatically added, even if they are in subdirectories.

removalTimeout [ integer ]

Specifies the timeout (in milliseconds) after which a successfully finished process is removed from the process list. The default value for this is 15000 ms or 15 seconds

logRotation [ object ]

If this value is present, a regular log rotation is performed in which the created log file is purged and optionally backed up before. This object has two optional keys frequency [ integer ] which specifies the frequency of log rotations in hours and keepPrevious [ boolean ] that determines whether the previous logs should be backed up or not. The log backups follow the naming scheme log_core_{date}-{index}.txt where the date is the date at which the log rotation was performed and an optional index for the case when there are more than one log rotations per day.

tagColors [ array ]

This array specifies the colors used for tags in C-Troll. Each object must have a r, g, and b key that specifies the colors in RGB space, where each value must be between 0 and 255. Each object can also have an optional tag entry that is a string which specifies if this color applies to a specific tag used in an application. The order of colors that are used for all tags that are not specified is undefined but will remain the same as long as no tags are added. The default colors are a subset of the colors from here.

Nodes

Each node file specifies the information about a single node (i.e., computer) that can be controlled by the C-Troll applications. The configuration file has the following specifications:

name [ string ]

The name of this node. This name is used both internally as well as human-readable name. The node names of all nodes that are loaded in C-Troll have to be unique. If there are two or more nodes that share a common name, the loading of the configuration file will fail.

ip [ string ]

The IPv4 or IPv6 address of the node.

port [ 0 < number < 65535 ]

The port at which the node is available.

secret optional [ string ]

The optional secret string that is used to authenticate communication with the Tray application. The value specified in here has to be the same as specified in the config-tray.json configuration of the node.

Clusters

Each cluster specifies a group of nodes that are controlled as a unit. The cluster is the atomic unit at which commands in C-Troll are operated, so if, for example, a single node needs to be controlled, it has to be managed as a cluster that contains only the one node.

name [ string ]

The name of the cluster. The name is used both internally as well as a human-readable name of the cluster. The names of all clusters that are loaded in C-Troll have to be unique. If there are two or more clusters that share a common name, the loading of the configuration file will fail.

enabled optional [ boolean }

This value specifies whether the cluster that is described in this configuration file is active or not. If this value is set to false, it is the same behavior as if this configuration file doesn't exist in the first place. The default value for this is true.

nodes [ list of strings ]

This is a list of all of the names of nodes that belong to this cluster. Each value in this list have to correspond to the Node::name also loaded in these configuration files. If a value specifies a name that does not belong to any node, the loading of the configuration file fails.

Applications

Each file specifies a single application that can be started on a number of clusters with different configurations. Clusters and configurations are orthogonal to each other, meaning that it is assumed that every configuration can run on every cluster. If this is not desired, consider creating two files instead.

name [ string ]

The name of the application that will appear both internally as well as a human-readable name. The name for each application has to be unique among all applications loaded such that no two applications shall have the same name or the loading of the configuration files will fail.

executable [ string ]

The path to the executable that will be executed with this application. This path needs to be the same on all nodes of the cluster for which this application is executed. Furthermore, it is recommended, but not required, for this path to be an absolute path in the file system.

commandlineParameters optional [ string ]

These are command-line parameters that are passed to the executable regardless of which configuration is chosen. The default value for this parameter is the empty string, which will cause no additional command-line parameters to be passed to the executable.

workingDirectory optional [ string ]

This value specifies the current working directory from which the executable will be executed. If this value is not set, the location of the executable will be used instead.

tags optional [ list of strings ]

This lists a number of tags that are associated to this application. There is no limit on which tags can be used on applications and C-Troll will automatically group applications based on the list of tags that are used among all applications. The only limitation here is that the empty string is not allowed as a tag.

clusters [ list of strings ]

This specifies the list of clusters on which this application can be started. Each value in this list has to correspond to a Cluster::name also loaded by the configuration files. If a value in this list does not correspond to the name of a cluster, the loading of the configuration files will fail.

shouldForwardMessages optional [ boolean ]

This value controls whether child processes on the trays should forward their StdOut and StdErr message pipes to the C-Troll application. Messages are being transmitted whenever they arrive at the Tray, i.e., when the stream is flushed by the child process.

delay optional [ number ]

This value specifies a delay in milliseconds that the C-Troll application should wait between starting each node in a cluster. The default value is the same as specifying 0 meaning that no waiting occurs.

configurations optional [ list of objects ]

Configurations are optional ways of starting the application with specific command-line parameters. Each value of this list has to specify two parameters; name specifies the name of the configuration that is used internally as well as for the human-readable string. All configurations for a specific application have to be unique. The parameters are the command-line parameters that are passed to the executable if this configuration is started.

Communication

Communication between C-Troll and the Tray applications happens through the passing of JSON messages. The fundamental structure for each of these messages is that they need to have a type key that specifies what type of message is contained in this package and a version number so that we can ensure that the protocol has not changed if either one of the two applications is updated. Each message type has a fixed sender and a recipient. What follows is a list of all message types that are used for communication between C-Troll and the Tray applications.

ProcessStatusMessage

Sender: Tray

Receiver: C-Troll

This message is sent whenever the Tray detects a change about a process that is running on the local machine. These changes most commonly are whether a process was started, when it started running, whether it closed successfully, or if it was terminated. This message type informs C-Troll about this local change.

processId [ int ]

This is the process id that was used to originally start the process (see CommandMessage). This number was given to the Tray by the C-Troll application.

status [ "Starting", "Running", "NormalExit", "CrashExit", "FailedToStart", "TimedOut", "WriteError", "ReadError", or "UnknownError" ]

This field contains the new status that this process entered. It is this transition that triggered the sending on this message type in the first place. The "Starting" status is sent when the process has been started but is not yet running. The "Running" status is sent when the application properly starts executing. "FailedToStart" is sent if the application could not be started correctly for whatever reason; common reasons might be that a resources needed at load time was not present, the executable's file was not found, or the Tray application has insufficient privileges to start the program. The "NormalExit" status is sent if the application closed gracefully. The "CrashExit" status is used if the process was terminated for whatever reason. "TimedOut", "WriteError", "ReadError", and "UnknownError" should at the moment never be sent as a status message and are reserved for future functionalities.

StartCommandMessage

Sender: C-Troll

Receiver: Tray

This message is sent from C-Troll to the Tray applications as a command to start a new process.

executable [ string ]

This is the name of the executable that is to be started with this process id.

forwardOutErr [ boolean ]

This value specifies whether the child process should forward its StdOut and StdErr messages to the C-Troll application

id [ integer ]

This is the ID that the Tray application has to use whenever it is communicating information about this process. This ID is also used by C-Troll when signalling to Exit or Kill this process.

secret [ string ]

If the receiving Tray application requires a secret to authenticate a valid message, this string has to be the same as the string defined in the config-tray.json configuration file for the Tray, if it is not, an InvalidAuthMessage is returned to the C-Troll. If the Tray was configured without a secret message, the value for this key must be empty.

commandlineArguments [ string ]

These are all of the commandline arguments that should be passed to the executable when starting the process.

workingDirectory [ string ]

This is the working directory from which the application should be started

ExitCommandMessage

Sender: C-Troll

Receiver: Tray

This message is sent from C-Troll to the Tray applications as a command to stop a running process.

id [ integer ]

The id of the process that is to be terminated.

secret [ string ]

If the receiving Tray application requires a secret to authenticate a valid message, this string has to be the same as the string defined in the config-tray.json configuration file for the Tray, if it is not, an InvalidAuthMessage is returned to the C-Troll. If the Tray was configured without a secret message, the value for this key must be empty.

InvalidAuthMessage

Sender: Tray

Receiver: C-Troll

This message is sent when the Tray received a CommandMessage that did not have the correct secret, this message is sent back to the C-Troll application.

KillAllMessage

Sender: C-Troll Receiver: Tray

This message is sent by C-Troll to the Tray to command the Tray to kill all processes that are currently running. This message can be used if bugs have arisen that caused the C-Troll's and the Tray's state to diverge. For example if C-Troll thinks a process is no longer running and thus has no UI option to stop a process.

secret [ string ]

If the receiving Tray application requires a secret to authenticate a valid message, this string has to be the same as the string defined in the config-tray.json configuration file for the Tray, if it is not, an InvalidAuthMessage is returned to the C-Troll. If the Tray was configured without a secret message, the value for this key must be empty.

TrayStatusMessage

Sender: Tray

Receiver: C-Troll

This message is sent whenever there is a new initial C-Troll connection to the Tray. This message will inform the C-Troll about the current state of the Tray. Currently, only the list of process id's that are running on the Tray are sent back to C-Troll.

runningProcesses [ list of integers ]

A list of all process id's that are currently running on this Tray.

Encryption

In the Tray application's configuration file, the secret key can be used to enable encrypted traffic for that particular Tray. If a Tray specifies a secret, then the C-Troll's Node configuration for that particular Tray must contain a secret configuration as well. If either the Tray or the C-Troll's Node has a secret key specified, the application encrypts and decrypts all incoming traffic using the secret as a password. The details of the encryption algorithm exists here, but the short version is that it is by no means to be considered a cryptographically safe encryption.

The secret between each Tray and C-Troll can be different (or some of the _Tray_s might not use a secret at all).

Example

config-tray.json for Tray #1

{
  "port": 5000,
  "secret": "super-secret-password"
}

config-tray.json for Tray #2

{
  "port": 5001,
  "secret": ""
}

Node configuration node1.json for _C-Troll:

{
  "name": "Home",
  "ip": "localhost",
  "port": 5000,
  "secret": "super-secret-password"
}

Node configuration node2.json for _C-Troll:

{
  "name": "Home",
  "ip": "localhost",
  "port": 5001
}

In this example, all traffic going both ways between C-Troll and Tray #1 is encrypted using the super-secret-password, whereas the traffic between C-Troll and Tray #2 is not encrypted.