Running NColony¶

In this section, we assume everything to be running in an environment where “pip install ncolony” has taken place. This will usually be a virtualenv, which should be activated.

Running ncolony monitor¶

Create two directories: conf and messages. For simplicity, we will assume that they live in the root directory, / – /conf/ and /messages/.

twistd -n ncolony --messages /messages --config /conf

Of course, it is useless to run a monitor without any processes to monitor:

python -m ncolony ctl add my-cat-program --cmd cat

This will add the cat program as a monitored program. Because cat hangs forever reading from stdin, it will never die. It is important to note that it does not matter what order we run these in. In fact, if we now shut down (via CTRL-C) the ncolony monitor, and start it again, it will start the cat program again.

twistd Command-Line Options¶

A full set of twistd command-line options can be found in the twistd help (available via twistd --help).

twistd ncolony Command-Line Options¶

Option: –config DIR: Directory for configuration
Option: –messages DIR: Directory for messages
Option: –frequency SECONDS: Frequency of checking for updates [default: 10]
Option: –pid DIR: Directory of PID files
Option: -t SECONDS, –threshold SECONDS: How long a process has to live before the death is considered instant, in seconds. [default: 1]
Option: -k SECONDS, –killtime SECONDS: How long a process being killed has to get its affairs in order before it gets killed with an unmaskable signal. [default: 5]
Option: -m SECONDS, –minrestartdelay SECONDS: The minimum time (in seconds) to wait before attempting to restart a process [default: 1]
Option: -M SECONDS, –maxrestartdelay SECONDS: The maximum time (in seconds) to wait before attempting to restart a process [default: 3600]

python -m ctl Command-Line Options¶

The following must be given before the subcommand:

Option: –messages DIR: directory of NColony monitor messages
Option: –config DIR: directory of NColony monitor configuration

The following follow the subcommand:

restart-all: Takes no arguments
restart, remove: Only one positional argument – name of program

python -m ctl add Command-Line Options¶

Option: –cmd CMD: Name of executable
Option: –arg ARGS: Add an argument to the command
Option: –env NAME=VALUE: Add an environment variable
Option: –uid UID: Run as given user id (only useful if ncolony monitor is running as root)
Option: –gid GID: Run as given group id (only useful if ncolony monitor is running as root)
Option: –extras EXTRAS: a JSON-encoded dictionary with extra configuration parameters. Those are not used by the monitor itself, but are available to the running program (as the variable NCOLONY_CONFIG) and to other programs which scan the configuration directory.

For programmatic access, it is recommended to use the ncolony.ctllib module from a Python program instead of passing arguments to a python -m ncolony ctl subprocess.

Logging¶

The log of ncolony itself is configured by using the twistd log configuration. While ncolony will log processes’ stdout/err, it is highly encouraged to set logs for these. Ideally, ncolony logs should also show either catastrophic errors in processes, such that even the log could not be opened, or messages that are sent before the log is set.