Configuration and CLI contract

1.3.3 compatibility contract: local YAML configuration, container selection, commands and exit codes. The choices introduced in 0.0.80 remain in force.

Configuration and precedence

Use -c FILE, otherwise MONIT_DOCKER_CONFFILE, otherwise /etc/monit-docker/monit-docker.yml. An existing file takes precedence over inline MONIT_DOCKER_CONFIG; a read or parse error does not trigger fallback. If no source exists, historical monitoring commands use empty configuration, while check-config, run and scenario return 110.

The root is a YAML mapping: {} is valid, an empty document or list is not. Sections are general, vars, clients, serve, cron, stats, monit, ctn-groups, dir-groups, conditions, commands and scenarios. All modes validate the entire configuration, including dormant entries, before Docker access. Unknown sections/fields and invalid values return 110. general supplies template context, not CLI defaults.

Section imports contain entries without another section wrapper. Relative imports resolve from the main configuration directory; later imports override earlier ones, and local entries replace imported entries as a whole. State and audit paths remain relative to the working directory. Mako templates execute trusted code, even during offline validation.

An explicitly named unknown client is rejected, even with --client-from-env. For a known name, --client-from-env takes precedence. Otherwise use --client NAME or the first configured client. With no clients, the historical runtime uses the Docker environment and defaults to the local socket.

Direct command settings

Each command reads its own section. Explicit CLI flags take precedence. Repeated rule or resource flags replace the corresponding YAML list. An explicit monit --rsc selects observation even if YAML configures an action. Use --dry-run to preview rules for one invocation.

stats:
  rsc: [cpu_percent, mem_usage]
  output: json
serve:
  interval: 60
  status_token_file: /run/secrets/status

Container selection

• Name, ID, image and label patterns are alternatives (OR). Status filters apply in addition.
• --ctn-group accepts exact group names; the union of their patterns intersects the union of direct patterns when supplied.
• Ordinary patterns are case-sensitive globs matching the whole value. A leading ~ selects a Python regular expression matched from the start; use $ for the end.
• Labels match values, not keys or key=value. Images match tags. Legacy 12-character alphanumeric IDs gain a trailing wildcard.
• Commas never split selectors. Repeat options: --name web --name api. Patterns such as ~worker-[0-9]{1,3}$ remain intact.
• No selector means all containers allowed by the status filter; no match returns 114. Container order is not guaranteed.

Commands and outputs

Global options precede the subcommand; command-specific options follow it. Quote selectors and rules so the shell does not expand them.

monit-docker -c config.yml --name 'web-*' stats --rsc status
monit-docker -c config.yml check-config --output json
monit-docker -c config.yml run web-guard --dry-run

Rules report JSON decisions with container_id, rule, command and status. No matching rule can still mean success. The first failed action stops later actions and containers. Dry runs read real Docker data and may write simulated journal events and create a state lock.

Scenarios and access validation

Names match [a-z0-9][a-z0-9-]{0,63}. Mode defaults to cron; stats and serve are also supported. Choose explicit select or all: true, exclusively. Group and direct patterns intersect; status is an additional filter. Global target/client overrides are rejected; scenario audit and event-window fields override inherited values.

Boolean fields require actual booleans. Numeric fields accept the documented numeric types or numeric strings, then apply the CLI bounds. Unknown and wrong-mode fields are rejected. Configuration is rendered once and passed to the runner. See named scenarios for the field matrix.

Since 0.0.77, fs_readable, fs_writable and fs_executable resources in stats/serve scenarios require an explicit directory-group access identity during offline validation. Previously, inspection could succeed although collection could not. Disk, inode and mount-mode resources do not require it. Access probes still need Python 3 in the target Linux container.

Important defaults

• Automatic cooldown: 300 seconds; maximum automatic restart attempts: 3 per container until rearm.
• Trigger delay: 0; a positive delay requires a positive maximum observation gap, greater than the interval in serve mode.
• Listener: 127.0.0.1:9808; interval: 30 seconds; stale threshold: max(90, 3 × interval).
• Docker event window: 300 seconds, allowed range 1..86400.
• Audit retention: five files of at most 5 MiB each by default; minimum configured file limit 65536 bytes, 1..100 retained files.

The complete versioned reference lists all options, bounds, environment defaults, action syntax and precedence rules.

Exit codes

A single monit --rsc status query returns running 0, created 10, paused 20, restarting 30, removing 40, exited 50, dead 60. Health returns healthy 0, starting 10, unhealthy 20, none 30, unknown 115. Ordinary percentage queries return a truncated integer capped to 0..100; raw measurements remain uncapped. These early returns describe the first selected container. Exec status propagation can return 1..255 and overlap other codes.

Approved compatibility choices

Shared strict validation, rejection of unknown clients, group/direct intersection and literal commas are in force. Chained comparisons follow Python: 10 < cpu_percent < 90 means 10 < cpu_percent and cpu_percent < 90. Review older rules before upgrading: selected containers and executed actions can change.

Patterns are limited to 4096 characters; each regex comparison has a 50 ms limit. Invalid or timed-out patterns fail explicitly. This is not a whole-cycle deadline.

The explicit tui command opens the read-only terminal interface. CLI and cron commands never activate curses automatically. See the release notes for migration details.

Internal Python classes, diagnostics, implicit abbreviations and Docker ordering are not stable interfaces. Changes follow the deprecation policy.