Configuration

Generate a first conf

Running cmt with no config file yet present creates a starter conf.yml under the cmt directory (~/.cavaliba/cmt/ by default, or --conf) with sane local defaults - see Setup.

cmt                 # creates conf.yml if missing, then runs it
cmt checkconfig      # print the merged effective config (secrets redacted) and exit

Precedence

CLI flags > environment variables > local config file > built-in defaults, then - if global.url/global.client_id are set - a remote fetch is merged in on top (see below).

• Env vars use the CAVALIBA_CMT_ prefix (e.g. CAVALIBA_CMT_URL, CAVALIBA_CMT_CLIENT_ID, CAVALIBA_CMT_TIMEOUT).
• conf.d/*.yml (next to conf.yml, same directory) is merged in too when global.load_confd is true (the default) - handy for splitting checks across files.

Built-in doc

The full field reference ships inside the binary, always in sync with the running version:

cmt doc global      # global: section - identity, policy, behavioral defaults
cmt doc outputs      # outputs: section, one block per registered type
cmt doc checks       # fields common to every check (enable, frequency, tags, ...)
cmt doc cpu          # a specific module's conf fields + output items
cmt doc              # list every available topic/module

Example

version: "1"

global:
  url: http://localhost:8000/
  client_id: ""
  client_secret: ""
  node: ""                  # default: hostname
  group: ""                 # default: nogroup
  env: na                   # deployment label: na/dev/test/qual/staging/prod ...
  timeout: 20s
  parallel: 64

outputs:
  - name: cli
    type: cli
    format: short

checks:
  - module: cpu
    name: cpu
    conf:
      threshold: 90

  - module: http
    name: www_cavaliba
    conf:
      url: https://www.cavaliba.com/
      http_code: 200
      pattern: cavaliba

See Outputs and Modules for every output type and check module, each with its own conf fields and a runnable example.

Merging with a remote source (app_cmt)

Set global.url and global.client_id to switch from standalone to remote-managed: cmt then calls GET {url}api/cmt/ for its effective config, authenticating with X-Cavaliba-Key: {client_id} {client_secret} {client_subidentity} (client_subidentity defaults to the hostname).

The fetched outputs:/checks: are merged onto the local ones by name: a fetched entry whose name matches a local one replaces it entirely; any other fetched entry is appended; any local entry the remote side doesn’t mention is left untouched. This is what lets you author a complete local checks:/outputs: list and use the remote source only to push narrow, per-entry overrides - e.g. enable: no for one check during a maintenance window - instead of mirroring every entry’s full definition server-side (see CMT / app_cmt).

A handful of global fields can also be overridden remotely, only when the remote value is non-zero/non-empty: interval, alert_delay, max_daemon_loops, conf_refresh_interval, max_conf_age, timeout, parallel, business_hours, tags, fieldmap. Everything else in global (url, client_id/client_secret, client_subidentity, node, group, env, ssl_skipverify, load_confd, allowed_modules/ denied_modules) is always local, never taken from the server.

A failed fetch falls back to the on-disk cache (remote.json, in the cmt directory) within global.max_conf_age; see --refresh-conf/ --cached-conf in Options to force one behavior or the other for a single run.

Fields common to every check

Beyond a module’s own conf: fields (see Modules), every check supports:

• enable: - a bool, or a timerange string (bh, hrange HH:MM:SS HH:MM:SS, after ..., …) evaluated against global.business_hours.
• conf.severity_max - cap this check’s severity.
• conf.alert_delay - override global.alert_delay for this check.
• conf.frequency - minimum time between runs (--cron-only).
• conf.reverse_severity - invert the alerting condition.
• conf.root_required - only run with elevated privileges.
• conf.tags - space-separated key/key=value tokens, merged with global.tags.

Run cmt doc checks for the full reference.