Configs#

cijoe configuration files are plain-text files written in TOML and with suffix .toml. cijoe itself has few configurable items, thus, the content of a cijoe configuration file is often mostly filled with with items used by Scripts.

Providing a configuation file to the cijoe command-line tool is required. The configuration file can be empty, nevertheless, one must be provided, the reason being that with cijoe, the core interface of run(), put(), and get() is re-targetable. That is, when configured to do so, run() executes commands on a target machine that is not the initiator.

Often, tasks performed by cijoe can be, if not destructive, modifying the target system in one way of the other. The default is for the initator and the target to be the same system, and therefore, to avoid accidents like invoking a destructive workflow and forgetting to supply a configuration file, providing a configuration file in the command line tool is required.

cijoe specific keys#

You can put whatever information about the target machine that you need in the configuration file. However, there are a couple of cijoe specific keys that you should avoid using for other things than the intended purpose:

SSH Transport Configuration
Shell Configuration
Workflow Configuration

cijoe abides by the convention that configuration values are grouped under a relevant key. Thus, the those for cijoe itself are all stored under the cijoe key, such as:

[cijoe.transport]
...

[cijoe.run]
...

[cijoe.workflow]
...

Transport Configuration#

cijoe uses paramiko as the ssh implementation. Consequently, the values you set here are the ones used for the call to connect().

Authentication setup is straightforward and supports either username and password login or key-based login. You can configure it as follows:

[cijoe.transport.ssh]
hostname     = "foo"
port         = 22
username     = "bar"

# either
password     = "baz"

# or
key_filename = "path/to/private_key"
passphrase   = "baz"

Configuring multiple transports#

When executing scripts over an ssh connection, cijoe connects to the first transport defined under the cijoe.transport key. If you need to connect to multiple different transports, you can define them under different keys, for example:

[cijoe.transport.machineA]
hostname = "machineA"
port = 22
username = "foo"
password = "bar"

[cijoe.transport.machineB]
hostname = "machineB"
port = 22
username = "foo"
key_filename = "path/to/private_key"

To execute commands on a specific transport, use the transport_name parameter of cijoe.run(...), for example:

cijoe.run("hostname")                             # will run on machineA
cijoe.run("hostname", transport_name="machineB")  # will run on machineB

Shell Configuration#

`cijoe.run.env`#

It is possible to set up environment variables for the target system. All calls to cijoe.run(...) will be given the environment variables defined by this configuration option.

Example:

cijoe.run.env = PATH=/usr/local/bin:/usr/bin, LANG=en_US.UTF-8

In this example, any command run through cijoe.run(...) will use the specified PATH and LANG variables.

`cijoe.run.shell`#

cijoe assumes that the default shell of the target machine follows the POSIX standard for the Shell Command Language. If not, for example if the target machine is a Windows machine using PowerShell, you can set the default shell of the target with the cijoe.run.shell key.

Defining the shell is important in cases where environment variables are declared through cijoe as the syntax for this is different in various shell languages.

In the table below, you can see the keys associated with different shells in cijoe.

Windows PowerShell	`pwsh`
Windows Command Shell	`cmd`
C Shell	`csh`

Workflow Configuration#

When a workflow is processed, each step is executed in sequence. It can be advantageous to fail fast, meaning the workflow stops processing further steps once a failure occurs in any step.

This is possible via the cijoe configuration option: cijoe.workflow.fail_fast which you can set in your configuration-file:

[cijoe.workflow]
# Change this to true to stop processing additional workflow steps when a step fails
fail_fast=false

[example]
message="Hello, world!"

By default cijoe functionality, then this can also be controlled environment variable:

CIJOE_WORKFLOW_FAIL_FAST=true

Environment Variable Override#

Any configuration option specified in a configuration file can be overridden by an environment variable. This behavior follows a specific naming convention for environment variables, as outlined below.

For a configuration file entry such as:

[foo.bar]
baz = false

You can override this option with an environment variable named:

FOO_BAR_BAZ=true

In summary:

Convert the configuration path and name to uppercase.
Replace any dots (.) with underscores (_).

Defining Multiple Configuration Files#

You can run cijoe with multiple configuration files by specifying the --config/-c argument multiple times to the CLI.

cijoe -c path/to/config1.toml -c path/to/config2.toml ...

This allows you to reuse parts of your configuration across runs, reducing redundancy.

Although the TOML specification states that defining the same key multiple times is invalid, cijoe permits it across configuration files. Files are processed in the order they appear in the command, so later files override conflicting keys from earlier ones.