Home

C-Troll is split into two applications, the Tray, which is an application that has to be running on every computer that should be able to start an application. The second application is C-Troll which is the controlling application to a number of Tray applications.

The C-Troll application will create JSON messages that are sent to the Tray applications that will instruct the Tray to execute a specific command. The most common commands are to start or to exit a program. Nodes controlled by C-Troll are organized as clusters, in which a node can belong to any number of clusters.

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.

C-Troll

The C-Troll application loads a configuration with a fixed name of config.json from the current working directory. This JSON file is mandatory and has to contain three keys that specify paths. All three paths are relative to the current working directory and thus the location of the config.json file. The applicationPath specifies the location from which application configurations are loaded. The clusterPath specifies the location from which the cluster information are loaded. Finally, the nodePath specifies the location from which the information about nodes are loaded. If any of these three folders does not exist, the program will exit with a failure. The parsing of all three directories follow the same logic. Every file with the .json extension will be automatically added, even if they are in subdirectories.

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.

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 is currently unused.

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.

Old C-Troll

Config

• applicationPath (string)
• clusterPath (string)
• listeningPort (int)

Application

Files named: <id>.json, where id is the application id.

• name (string)
• executable (string)
• baseDirectory (string)
• commandlineParameters (string)
• currentWorkingDirectory (string)
• tags (array of strings)
• configuration (map from id (string) to object)
  • name
  • commandlineParamters
• clusters (array of strings, clusterId's)

Cluster

Files named: <id>.json, where id is the cluster id.

• name (string)
• enabled (bool)
• nodes (map from id (string) to object)
  • name (string)
  • ip (string)
  • port (string)

Messages

This document describes the stucture of messages being passed between the three parts of C-Troll (GUI, Core & Tray)

Core to Tray

TrayCommand

Used to start / stop processes.

• id (int)
• command (string: "Start" / "Kill" / "Exit")
• executable (string)
• baseDirectory (string)
• currentWorkingDirectory (string)
• commandlineParameter (string)
• environmentVariables (string NAME,VALUE;NAME,VALUE)

Tray to Core

TrayProcessLogMessage

Sent whenever the tray receives a log message from any running process.

• processId (int, The process identifier)
• stdOutLog (string)
• stdErrorLog (string)

TrayProcessStatus

Sent whenever a process started or terminated.

• processId (int, The process identifier)
• status (string, "Running", "NormalExit", "CrashExit", "FailedToStart", "TimedOut", "WriteError", "ReadError", "UnknownError")

Core to GUI

GuiInit

Sent whenever there is new information about applications/clusters.

• applications (array)
  • id (string)
  • name (string)
  • tags (array of strings)
  • configurations (array of objects)
    • id
    • name
    • clusters (array of strings)
• clusters (array)
  • id (string)
  • name (string)
  • enabled (bool)
  • nodes (array of objects)
    • id
    • name
• processes (array of objects)
  • id (int)
  • applicationId (string)
  • configurationId (string)
  • clusterId (string)
  • time
  • nodeStatusHistory - status (string, "Starting", "Running", "NormalExit", "CrashExit", "FailedToStart", "TimedOut", "WriteError", "ReadError", "UnknownError") - time (double) - node (string)
  • clusterStatus (string, "Starting", "Running", "Exit", "PartialExit", "CrashExit")
  • clusterStatusTime (double)

GuiProcessStatus

• processId (int)
• applicationId (string)
• clusterId (string)
• nodeStatus (map from node id) (usually just one node)
  • time (double)
  • (string, "Starting", "Running", "NormalExit", "CrashExit", "FailedToStart", "TimedOut", "WriteError", "ReadError", "UnknownError")
• clusterStatus (string, "Starting", "Running", "Exit", "PartialExit", "CrashExit")

GuiProcessLogMessage

• time (double)
• processId (int)
• applicationId (string)
• clusterId (string)
• message (string)
• node (string, node id)
• type (string, "stdout" or "stderr")

GuiProcessLogMessageHistory

• time
• processId (int)
• applicationId (string)
• clusterId (string)
• logMessages (map from nodeId)
  • message (string)
  • time (double)
  • type (string, "stdout" or "stderr")

GUI to Core

GuiStartCommand

• applicationId
• configuration (string)

GuiProcessCommand

• processId
• command (string, "Restart" or "Stop")

GuiReloadConfigCommand

(no parameters)