Options

Run modes

cmt has no long-running mode by default - every invocation resolves its config, runs the checks once, and exits. There are three ways to schedule that:

# crontab, one line
* * * * * /usr/local/bin/cmt --cron >> /var/log/cmt.log 2>&1

# or the built-in loop, under systemd/supervision
cmt daemon

Daemon mode

cmt daemon loops in-process: fetch config, run the checks, ship the results, sleep until the next tick. Reach for it when you need an interval an OS scheduler can’t express - anything under a minute. For a plain once-a-minute fleet, cmt --cron from cron is simpler.

Three global: fields drive it:

global:
  interval: 30s
  conf_refresh_interval: 5m
  max_daemon_loops: 1440

Running it under a supervisor

A second cmt daemon exits 0 immediately when one is already running - it takes a non-blocking lock on daemon.lock in the cmt directory. That is deliberate: you can let a scheduler fire cmt daemon on a fixed tick purely as a restart-if-dead check, and it costs nothing while the real daemon is alive.

# systemd
[Service]
ExecStart=/usr/local/bin/cmt daemon
Restart=always

# or crontab - a no-op while the daemon runs, a restart after a recycle/crash
* * * * * /usr/local/bin/cmt daemon >> /var/log/cmt.log 2>&1

Supervision is expected, not optional: the daemon exits on purpose after max_daemon_loops ticks. Recycling a fresh process on a schedule keeps a slow leak in any one check from growing without bound.

The lock only ever blocks another daemon. An ad hoc cmt, cmt checkconfig or cmt doc still runs normally while a daemon is active.

Good to know

• Ticks are spread across the fleet automatically. Each host offsets its tick within the interval based on its own node/group, so hosts don’t all report on the same second. The offset is stable - a restarted daemon returns to the same slot.
• A failed config refresh is not fatal: the daemon logs it and keeps running on the last config it had.
• SIGINT/SIGTERM stop it cleanly between ticks, so systemctl stop never interrupts a check mid-run.
• Per-check frequency: is honoured (daemon implies --cron), so a 5m check on a 30s tick still runs every 5 minutes.

Reporting and preview

• --report - invoke every non-cli output and persist hysteresis state. cli always runs regardless.
• --dryrun - build each output’s payload but skip the actual send (only meaningful for an output already invoked via --report/--cron).
• --debug - print each output’s payload before sending, exactly as it goes on the wire, then the backend’s response (status and body). Combine with -v/--verbose for an indented copy of each.

cmt --report --dryrun --debug     # preview every output's payload, send nothing
cmt --report --debug              # payload + what the backend answered
cmt --report --debug --verbose    # ... and an indented copy of each

Reading the response is worth it even on success: elasticsearch reports per-document failures inside an otherwise-OK answer.

Ad hoc filters

• -c, --check <name> - run only the check with this name.
• -m, --module <name> - run only checks of this module.
• --output <name> - ship results only to the output with this name (still gated by --report/--cron unless it’s cli).
• -l, --long - long/detailed cli output instead of the default one-line-per-check summary.
• --single - sequential mode (equivalent to --parallel 1).

Config-fetch control

Only relevant once global.url/client_id are set (see Configuration):

• default - fetch; fall back to the on-disk cache (remote.json) within max_conf_age on failure.
• --refresh-conf - force a fresh fetch; error out instead of falling back to the cache.
• --cached-conf - skip the network entirely, use the last cached config (errors out if nothing was ever cached).

Identity/connection flags

--url, --client_id, --client_secret, --node, --timeout, --ssl_skipverify, --parallel mirror the matching global.* config fields (see Configuration) - useful for a one-off override without editing conf.yml.

Other commands

• cmt checkconfig - print the merged effective config (secrets redacted) and exit.
• cmt listmodules - list registered check modules.
• cmt doc [topic|module] - built-in reference for global/outputs/checks, or one module’s conf: fields.
• cmt available <module> - list real-world targets a module could check on this host (e.g. running processes, mountpoints), for modules where that’s meaningful.
• cmt version - print the version.

Run cmt --help (or cmt <command> --help) for the exhaustive, current list.