COSC: Compose Processes With Screen

The cosc* scripts are a family of POSIX shell executables that manage a set of long running processes in a GNU-Screen session. Current version is 20180921.170040.

The configuration is stored in a directory: the root path can be itself configured with the $cosc_root environment variable (default value: /tmp/service_composer_config.d). One edits the configuration by calling cosc config {addjob,initialize,destroy,…}, and displays it with cosc config show.

The scripts are generated by an OCaml program which uses the Genspio EDSL/library. The code generator serves as one of the usage examples of the library, see its implementation.

The code generator can also be used to change a few parameters like the “name-prefix” (cosc here), or the default value of the configuration path (/tmp/service_composer_config.d). This can be useful to build custom/project-specific scripts that can remain independent from each other without setting an environment variable.

Installation

Simply copy cosc* to somewhere in your $PATH, the scripts depend on a reasonably valid version of /bin/sh and GNU Screen.

If you are using the code-generator, you can just point the --output-path option at the right directory.

Usage

The basic manual is obtained from the cosc man command. The, present, “README.md” version is the result of cosc man --extended.

Then, see cosc --help first, or for any sub-command try cosc <command> --help.

Screen Session Isolation

cosc isolates Screen sessions by using their session name.

The screen session name can be configured a 2 levels:

At script-generation time, one can set the default-value (with the option --screen-name).
At configuration time, one can overwrite the value with -S, see cosc config init --help.

If none of those two options is provided, cosc config init will generate a name, which is function of the root path and generation parameters and tries to ensure that the session is unique on the host.

Docker Image For the Generator

If you have opam, setting up the genspio repository is easy (only simple, pure OCaml dependencies), if not, or if you just like Docker™, the generator is available in the smondet/genspio-doc-dockerfiles:apps406 image, see:

docker run -it smondet/genspio-doc-dockerfiles:apps406 genspio-service-composer --help

Examples

The distribution comes with runnable examples, try cosc example --help. Here is the “basic” example:

# We setup the configuration root path:
export cosc_root=/tmp/example-basic.d
# Show the current configuration:
cosc config show
# OK, let's initialize configuration:
cosc config init
# Let's configure a few jobs:
cosc config addjob --name DMesg --no-log -c "watch -c -d -n 30 'dmesg -P'"
cosc config addjob --name Top --no-log -c top
cosc config addjob --name Dummy --interpreter 'bash -c' \
    -c 'while true ; do sleep 3 ; echo "$(date)" ; done'
# Show the updated configuration:
cosc config show
# Show the current status:
cosc status
# Start everything:
cosc start --all
# Show the updated status:
cosc status
# Stop everything:
cosc kill --all
# Show the updated (short) status:
cosc status --short
# Destroy the configuration:
cosc config destroy

Authors

Seb Mondet.

License

The code generator is covered by the Apache 2.0 license, the scripts are ISC licensed.

smondet/cosc