The caterva2.toml configuration file#

We’ve seen that the cat2-client program accepts some command-line options to tune its operation (check the --help option). This is even more important for services as we shall see in following sections. Thus, Caterva2 programs support getting some settings from a TOML configuration file.

Configuration File Search Path#

Caterva2 follows standard Unix/Linux conventions for locating configuration files. When looking for caterva2.toml (or caterva2-server.toml), the search order is:

  1. Command-line option: --conf <path> (if explicitly specified)

  2. Current directory: ./caterva2.toml

  3. Home directory: ~/.caterva2.toml

  4. System-wide (Unix/Linux only): /etc/caterva2.toml

The first existing file found in this order will be used. If no configuration file is found, the program will use default settings.

This approach is similar to how tools like git, vim, and ssh locate their configuration files, making it familiar to Unix/Linux users.

The configuration file may hold settings for different programs, with a separate section for each program. Thus, a program may check the file for its own settings, but also for those of other programs which may be of use to itself. This allows compact configurations in a single file. For instance, below is a sample configuration file for the server program and some client app:

# Example configuration for caterva2 clients in general
[default]
url = "https://cat2.cloud/demo"
username = ""
password = ""

[localuser]
url = "http://localhost:8000"
username = "user@example.com"
password = "foobar11"

See caterva2.sample.toml in Caterva2’s source for all possible settings and their purpose.