Configuration

config.yaml

The default configuration file for cumin is expected to be found at /etc/cumin/config.yaml. Its path can be changed in the CLI via the command-line switch --config PATH. A commented example configuration is available in the source code at doc/examples/config.yaml and included here below:

# Cumin main configuration
#
# By default Cumin load the configuration from /etc/cumin/config.yaml, but it can be overriden by command line argument
#
transport: clustershell  # Default transport to use, can be overriden by command line argument
log_file: logs/cumin.log  # Absolute or relative path for the log file
# If set, use this backend to parse the query first and only if it fails, fallback to parse it with the general
# multi-query grammar [optional]
default_backend: direct

# Environment variables that will be defined [optional]
environment:
    ENV_VARIABLE: env_value

# Backend-specific configurations [optional]
puppetdb:
    host: puppetdb.local
    port: 443
    api_version: 4  # Supported versions are v3 and v4. If not specified, v4 will be used.
    urllib3_disable_warnings:  # List of Python urllib3 exceptions to ignore
        - SubjectAltNameWarning

openstack:
    auth_url: http://keystone.local:5000
    username: observer  # Keystone API user's username
    password: observer_password  # Keystone API user's password
    domain_suffix: openstack.local  # OpenStack managed domain, to be added to all hostnames
    nova_api_version: 2.12
    timeout: 2  # Used for both Keystone and Nova API calls
    # Default query parameters. The ones set by default anyway are: status: ACTIVE and vm_state: ACTIVE [optional]
    query_params:
        project: project_name  # Parameter name: parameter value

# Transport-specific configuration
clustershell:
    ssh_options:  # SSH options passed to ClusterShell [optional]
        - 'some_option'
    fanout: 16  # Max size of the sliding window of concurrent workers active at any given time [optional, default: 64]

# Plugins-specific configuration
plugins:
    backends:  # External backends. Each module must define GRAMMAR_PREFIX and query_class, and be in Python PATH
        - external.backend.module

The example file is also shipped, depending on the installation method, to:

  • $VENV_PATH/share/doc/cumin/examples/config.yaml when installed in a Python virtualenv via pip.
  • /usr/local/share/doc/cumin/examples/config.yaml when installed globally via pip.
  • /usr/share/doc/cumin/examples/config.yaml when installed via the Debian package.

aliases.yaml

Cumin will also automatically load any aliases defined in a aliases.yaml file, if present in the same directory of the main configuration file. An aliases example file is available in the source code at doc/examples/aliases.yaml and included here below:

# Cumin aliases configuration
#
# Cumin looks for an aliases.yaml file in the same directory of the loaded main configuration file.
# Aliases are resolved recursively at runtime, hence they can be nested.
# Aliases must use the global grammar and defined in the form:
#     alias_name: query_string
#
alias_direct: D{host1 or host2}  # Use the direct backend
alias_puppetdb: P{R:Class = My::Class}  # Use the PuppetDB backend
alias_openstack: O{project:project_name}  # Use the OpenStack backend
alias_complex: A:alias_direct and (A:alias_puppetdb and not D{host3})  # Mix aliases and backend grammars

The file is also shipped in the same directory of the example configuration file, see config.yaml.