CONMON-V3(8)

📦 version 3.0.0~dev, in fedora 43, fedora 44

👑 CONMON-V3(8) — bestie edition 💖

okay so you're looking at conmon, the OCI container monitor used by Podman and CRI-O, and honestly? she's a tiny little icon who does SO much. this is conmon(8), and we're gonna get through her together, no cap. 🫶

✨ NAME ✨

conmon — OCI container monitor used by Podman and CRI-O

🌸 SYNOPSIS 🌸

conmon [OPTIONS] -c CID --runtime PATH

Create/run, exec into, or restore a container while handling logging, exit status reporting, and lifecycle integration for higher-level tools. she's giving multitasking queen 💅

🦋 DESCRIPTION 🦋

conmon is a small, feature-focused OCI container monitor used primarily by Podman and CRI-O. like, she's not trying to be everything, she's just extremely good at her job. 💖

What she actually does: she launches an OCI runtime (such as runc), keeps track of the container process, manages attach sockets, handles stdio, writes exit status files, and forwards container logs to a pluggable logging backend. iconic behavior, truly.

The same command-line interface supports multiple logical modes:

  • Create / run (default): start a container using an OCI bundle. 🎀
  • Exec: execute an additional process in an existing container. ✨
  • Restore: restore a container from a checkpoint. 🧚
  • Version: print the conmon version and exit. ⭐

The mode is selected using flags such as --exec, --restore, and --version — not by subcommands. she does not do subcommands, bestie, that's just not her vibe. 🙈

💅 OPTIONS 💅

Unless stated otherwise, boolean options are disabled by default and become enabled when specified. Options marked "(multiple)" may be given more than once. (yes, you can spam them, she's fine with it 🫶)

🌈 General options

  • --version — Print the conmon version and exit. that's it, that's the whole thing, she's done here 👑
  • --api-version=INT — Conmon API version to use. If omitted, defaults to 0. API version affects exec/attach behavior: attaching to an exec session (--exec-attach) is only allowed when --api-version is at least 1. so like, lowkey check your version before you try to attach. 😭
  • -c, --cid=STRING — Container ID. This uniquely identifies the container instance and is required for all modes other than --version. If missing, conmon fails with "Container ID not provided. Use --cid". 🚨
  • -u, --cuuid=STRING — Container UUID. Required for create/run and restore, and for exec with non-legacy API versions. It may be omitted only for legacy exec mode when --api-version is less than 1 and --exec is used. Otherwise conmon fails with "Container UUID not provided. Use --cuuid". 💀
  • -n, --name=STRING — Human-readable container name. This is used in logging metadata and may appear in log records depending on the configured log plugin. it's her government name fr fr 🎀
  • -b, --bundle=PATH — Location of the OCI bundle directory. If not specified, conmon defaults to the current working directory. The bundle is also used as the default location for the conmon debug log file (see ENVIRONMENT). 🦋
  • -r, --runtime=PATH — Path to the OCI runtime binary used to manage the container (for example, /usr/bin/runc). This option is required for all modes other than --version. The path must refer to an executable file; otherwise conmon fails with "Runtime path … is not valid". no executable, no entry, periodt. ✋
  • --runtime-arg=ARG (multiple) — Additional argument to pass to the runtime for all operations. Can be specified multiple times. Values may begin with -. yes you can pass something that starts with a dash, she said what she said 💅
  • --runtime-opt=ARG (multiple) — Additional options passed to the runtime for restore or exec operations. Can be specified multiple times. Values may begin with -. note: restore or exec only, she's specific like that ✨
  • --persist-dir=PATH — Persistent directory for the container. conmon writes exit status files here so higher-level tools can detect container exit using inotify or directory polling. the group chat of exit notifications 📬
  • --socket-dir-path=PATH — Directory where attach sockets for the container are created. If not specified, defaults to /var/run/crio. 🌸
  • --full-attach — Use the full path to the attach socket instead of truncating it based on --socket-dir-path. When specified, conmon ignores --socket-dir-path for the attach socket path computation. she said full length or nothing 💅
  • --sdnotify-socket=PATH — Path to the host's systemd sd-notify socket. When set, conmon relays sd-notify messages from the container to this socket. 🫶
  • --seccomp-notify-socket=PATH — Path to the socket on which the seccomp notification file descriptor is received. 🔥
  • --seccomp-notify-plugins=STRING — Comma-separated list or specification of plugins that manage seccomp notifications. The exact semantics are defined by the configured plugins. (so like, ask the plugins, not her 🙈)
  • --timeout, -T=SECONDS — Kill the container after the specified timeout in seconds. If unset or 0, conmon does not impose a timeout on the container. Negative values are rejected. she will not be doing negative time, that's not a thing 🚫
  • --sync — Keep the main conmon process as the direct parent of the container by only forking once. This is mainly useful for debugging or special integration scenarios. one fork and done, main character energy 👑
  • --syslog — Log to syslog. This is intended for use with the cgroupfs cgroup manager. It controls how conmon itself logs; it is distinct from the container log plugin configured via --log-path. two different logs bestie, do not confuse them 😭
  • -s, --systemd-cgroup — Enable systemd-based cgroup management instead of cgroupfs when launching or restoring a container. This is passed through as part of the runtime configuration. ✨
  • --no-new-keyring — Do not create a new session keyring for the container. 🔑🚫
  • --no-pivot — Disable pivot_root(2) and use alternative root switching mechanisms. 🌀
  • --replace-listen-pid — Replace an existing listen PID with the OCI runtime PID, when set. This is used by some higher-level integrations for PID tracking. 🎯
  • --stdin, -i — Open a pipe to pass standard input to the container. 📥
  • --terminal, -t — Allocate a pseudo-TTY for the container's stdin/stdout/stderr. she's getting a whole lil screen 🖥️✨

🎀 PID files and exit handling

  • --conmon-pidfile, -P=PATH — Write the PID of the conmon monitor process to the given file. 📝
  • --container-pidfile, -p=PATH — Write the PID of the initial process inside the container to the given file. If this option is not provided, conmon defaults to a file named pidfile-CID in the current working directory. 🫶
  • --pidfile=PATH (deprecated) — Deprecated PID file option kept for backward compatibility. Hidden from the built-in help output; prefer --conmon-pidfile or --container-pidfile instead. it's giving legacy, love her but she's retired 💀
  • --exit-dir=PATH — Path to the directory where exit files are written. These files allow higher-level tools such as Podman or CRI-O to detect container exit and read exit status. 📬
  • --exit-command=PATH — Path to an external program to execute when the container terminates. The exit command receives arguments from --exit-command-arg and runs after exit files are written. order matters bestie ✨
  • --exit-command-arg=ARG (multiple) — Additional argument to pass to the program specified by --exit-command. May be specified multiple times. Values may begin with -. 🎀
  • --exit-delay=SECONDS — Delay, in seconds, before invoking the exit command after container exit. The value must be greater than or equal to 0. ⏳

🔥 Logging options

  • --log-level=LEVEL — Set the minimum log level for conmon's own debug logging (separate from container logs, again, two different things 😤). The supported values follow the typical logging levels (for example, debug, info, warn, error); invalid values are treated according to the internal logger defaults. 🌈
  • -l, --log-path=SPEC (multiple) — Configure container logging destination and plugin. This option can be specified multiple times and is required unless --version is used. Each value has one of the following forms:
    • plugin:path — Use the given plugin and log to path. Dashes in the plugin name are normalized to underscores (for example, k8s-file becomes k8s_file). 🎀
    • journald — Use the journald logging plugin. 🦋
    • syslog — Use the syslog logging plugin (writes container output to the system syslog via openlog(3)/syslog(3)). Because openlog(3) configures a process-global destination, syslog may appear at most once among --log-path values; a second syslog entry is rejected. one syslog only, she's not doing duplicates 💅
    • passthrough — Use the passthrough logging plugin (no additional file path). ✨
    • path — Any other non-empty value is treated as a file path for the default file logging plugin. 📁

If no usable --log-path value is provided, conmon exits with:

Log driver not provided. Use --log-path

🚨

  • --log-size-max=BYTES — Maximum size in bytes of a single container log file before rotation or truncation is considered. If unset or 0, there is no size-based limit. Negative values (including -1, the historical CRI-O default) also mean unlimited. so -1 is not a tiny limit, she means no limit, do not get it twisted 😭
  • --log-global-size-max=BYTES — Maximum total size in bytes of all log files managed by the log plugin. If unset or 0, there is no global size limit. Negative values (including -1) also mean unlimited. 🧚
  • --log-tag=STRING — Additional tag to include in log records. 🏷️
  • --log-label=STRING (multiple) — Additional label to include in log records. Can be specified multiple times. 🎀
  • --log-allowlist-dir=PATH (multiple) — Allowed log directory. Can be specified multiple times. When set, the log plugin restricts log writes to the given directories. If omitted, no allowlist restriction is applied. 🔒
  • --no-container-partial-message — Do not set CONTAINER_PARTIAL_MESSAGE=true for partial log lines when using the journald log driver. If specified with a non-journald plugin, conmon logs a warning and the option has no effect. sorry bestie, wrong plugin, no effect 🙈
  • --no-sync-log — Do not manually call sync on logs after container shutdown. This can improve performance at the cost of potentially losing log records in the event of a sudden system failure. speed vs safety, your call 💀
  • --log-rotate — Enable log rotation instead of truncation when --log-size-max is reached. Rotation requires --log-max-files to be at least 1. 🌀
  • --log-max-files=N — Number of backup log files to keep when rotation is enabled. The default is
1

The value must be non-negative; values greater than INT32_MAX are rejected. If --log-rotate is specified and --log-max-files is 0, conmon exits with:

log-max-files must be at least 1 when log-rotate is enabled

🚨

okay that's the first chunk of her, and there's more coming so don't go anywhere 💖

✨ Exec and restore options ✨

okay bestie so these options pick and configure exec mode and restore mode, and here's the tea: you cannot just mix and match them however you want. They can't be combined arbitrarily. Periodt. 💅

  • -e, --exec — run a command into a container that's already running, instead of making a whole new container. When --exec is set:
    • --exec-process-spec is required.
    • --cuuid is required too, unless --api-version is less than 1 (that's the legacy exec API).
    • --restore must not be set.
  • --exec-process-spec=PATH — the path to the OCI process specification (usually a JSON file, iykyk) that describes the process you wanna execute inside the container. Required whenever --exec is used. If you forget it, conmon dips out with "Exec process spec path not provided. Use --exec-process-spec". 😭
  • --exec-attach — attach to an exec session. This one's only valid when --exec is also specified, and when --api-version is at least 1. Use it without --exec and conmon fails with "Attach can only be specified with exec". Use it with --api-version less than 1 and conmon fails with "Attach can only be specified for a non-legacy exec session". 🫠
  • --restore=PATH — restore a container from a previously created checkpoint at the path you give it. When --restore is used:
    • --exec must not be set (conmon straight up rejects configs that use both).
    • --cid, --cuuid, and --runtime are still required.
  • --restore-arg=ARG (deprecated, multiple) — an extra argument to pass to the restore command. It's deprecated and hidden from the built-in help, but it's still parsed for backward compatibility. Values may begin with -. 💀

🦋 Attach and I/O behavior 🦋

  • --leave-stdin-open — leave standard input open when the attached client disconnects, instead of closing the container's stdin.

👑 Mode selection summary 👑

conmon picks its internal command mode based on the options you hand it, bestie. Here's the vibe check:

  • Version mode
    • Selected when --version is specified.
    • Prints version information and exits immediately.
  • Restore mode
    • Selected when --restore is provided (and --exec is not).
    • Restores a container from the checkpoint path you specified.
  • Exec mode
    • Selected when --exec is set (and --restore is not).
    • Runs an additional process in an existing container using --exec-process-spec, optionally with --exec-attach.
  • Create / run mode
    • The default when neither --exec nor --restore nor --version is set.
    • Creates and runs a new container using the OCI bundle at --bundle (or the current working directory by default).

🌸 ENVIRONMENT 🌸

These environment variables affect conmon's own debug logging. Important: they do not control the container log plugin — that one is configured via --log-path and related CLI options. Two totally different things, don't get it twisted. ✨

  • CONMON_LOG_PATH — path to the debug log file for conmon itself. If it's not set, and --bundle is provided, conmon defaults to writing its debug log to BUNDLE/conmon-debug.log. If neither CONMON_LOG_PATH nor --bundle is set, then no debug log file path is configured at all. 🙈
  • CONMON_LOG_LEVEL — minimum log level for conmon's internal debug logging. If it's not set, or set to an invalid value, conmon defaults to a debug-level log filter.

💖 EXIT STATUS 💖

On success, conmon exits with the exit status of the container or the exec process, depending on which mode is active. On internal errors (invalid arguments, runtime failures, logging misconfiguration, and stuff like that), conmon prints an error message that looks exactly like this:

conmon: MESSAGE

and exits with an appropriate non-zero status code.

In all normal cases, conmon:

  • Writes exit files into the directory specified by --persist-dir and/or --exit-dir, so higher-level tools can detect container exit and read the exit status.
  • Flushes any buffered container log output in the configured log plugin before exiting.
  • Optionally runs the program specified by --exit-command, passing any --exit-command-arg values, after an optional --exit-delay.

🎀 EXAMPLES 🎀

Create and run a container using an OCI bundle in the current directory, logging to a file:

conmon \
  --cid mycid \
  --cuuid 123e4567-e89b-12d3-a456-426655440000 \
  --runtime /usr/bin/runc \
  --log-path /var/log/containers/mycid.log

Exec a process in a running container with attach, using API version 1 and a process spec:

conmon \
  --cid mycid \
  --cuuid 123e4567-e89b-12d3-a456-426655440000 \
  --runtime /usr/bin/runc \
  --api-version 1 \
  --exec \
  --exec-process-spec /run/mycid/exec-spec.json \
  --exec-attach \
  --log-path passthrough

Restore a container from a checkpoint with systemd cgroups enabled:

conmon \
  --cid mycid \
  --cuuid 123e4567-e89b-12d3-a456-426655440000 \
  --runtime /usr/bin/runc \
  --restore /var/lib/checkpoints/mycid \
  --systemd-cgroup \
  --log-path file:/var/log/containers/mycid.log

🌈 SEE ALSO 🌈

runc(8), podman(1), crio(8)

and that's the whole page bestie, we ate and left absolutely no crumbs 💅✨ the source and version info are chilling down in the footer along with the date, so if you ever need to know exactly which build of conmon(8) you're reading, that's where you look. now go monitor some containers, main character 🫶👑

📦 where this page comes from