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 path to the configuration file can also be specified in a system environment variable called CTRAY_CONFIG. The specification for this configuration file is:

JSON schema file

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

logFile optional [ boolean ]

Determines whether the Tray application should write the log messages to a file at all or not

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

JSON schema file

config.json

The C-Troll application loads a configuration with a fixed name of config.json from the current working directory. The path to the configuration file can also be specified in a system environment variable called CTROLL_CONFIG.

applicationPath [ string ]

Specifies the location relative to the configuration file 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 configuration file 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 configuration file 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_ctroll_{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. The log files are stored in the same directory where the configuration files are located.

showShutdownButton optional [ boolean ]

If this is set to true, the cluster widgets will show the option to completely shut down the nodes in addition to restarting them.

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.

restGeneral [ object ]

If this object is specified, C-Troll will open a port that can be used for REST queries against the application. Connections from any computer are allowed to connect to this port (see restLoopback for an alternative). See Rest for more information about the type of commands that can be sent. The optional username and password [ string ] values are used to enforce a "basic HTTP authentication" for all API access functions. By default both username and password are empty which means that no authentication is used. Another optional parameter port [ int ] sets the port at which the REST API is accessible at, which defaults to 7000. Finally, if the allowCustomPrograms parameter is set to true (default is false), it is possible for the REST API to start arbitrary applications on the nodes. Only enable this if you are sure about the security of the network and that only trusted computers are able to send REST commands.

restLoopback [ object ]

If this object is specified, C-Troll will open a port that can be used for REST queries against the application. Connections from any computer are allowed to connect to this port (see restGeneral for an alternative). See Rest for more information about the type of commands that can be sent. The optional username and password [ string ] values are used to enforce a "basic HTTP authentication" for all API access functions. By default both username and password are empty which means that no authentication is used. Another optional parameter port [ int ] sets the port at which the REST API is accessible at, which defaults to 7000. Finally, if the allowCustomPrograms parameter is set to true (default is false), it is possible for the REST API to start arbitrary applications on the nodes. Only enable this if you are sure about the security of the network and that only trusted computers are able to send REST commands.

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:

JSON schema file

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.

description optional [ string ]

A human-readable description of the Node that is presented to the user as tooltips in the editor and the C-Troll applications

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.

JSON schema file

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.

description optional [ string ]

A human-readable description of the Cluster that is presented to the user as tooltips in the editor and the C-Troll applications

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.

Programs

Each file specifies a single program 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.

JSON schema file

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 objects]

This specifies the list of clusters on which this application can be started. Each object in this list must contain a name attribute that corresponds 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. An optional parameters string specifies any commandline arguments that are provided if the program is started on this cluster.

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.

enabled optional [ boolean ]

This signals to C-Troll whether the program configured is currently active or not. It is not possible start a disabled program and they will not show up in the list, behaving the same as if this configuration file does not exist.

description optional [ string ]

A human-readable description of the Program that is presented to the user as tooltips in the editor and the C-Troll applications

preStart optional [ string ]

A script that gets executed on the C-Troll computer before this program starts

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 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 optional parameters are the command-line parameters that are passed to the executable if this configuration is started. Lastly, the description parameter can be used as a human-readable description describing what the configuration can be used for