Your company here — click to reach over 10,000 unique daily visitors

ch-run-oci - Man Page

OCI wrapper for "ch-run"


$ ch-run-oci OPERATION [ARG ...]



This command is experimental. Features may be incomplete and/or buggy. The quality of code is not yet up to the usual Charliecloud standards, and error handling is poor. Please report any issues you find, so we can fix them!

Open Containers Initiative (OCI) wrapper for ch-run(1). You probably don’t want to run this command directly; it is intended to interface with other software that expects an OCI runtime. The current goal is to support completely unprivileged image building (e.g. buildah --runtime=ch-run-oci) rather than general OCI container running.

Support of the OCI runtime specification is only partial. This is for two reasons. First, it’s an experimental and incomplete feature. More importantly, the philosophy and goals of OCI differ significantly from those of Charliecloud. Key differences include:

For these reasons, ch-run-oci is a bit of a kludge, and much of what it does is provide scaffolding to satisfy OCI requirements.

Which OCI features are and are not supported is provided in the rest of this man page, and technical analysis and discussion are in the Contributor’s Guide.

This command supports OCI version 1.0.0 only and fails with an error if other versions are offered.


All OCI operations are accepted, but some are no-ops or merely scaffolding to satisfy the caller. For comparison, see also:


$ ch-run-oci create --bundle DIR --pid-file FILE [--no-new-keyring] CONTAINER_ID

Create a container. Charliecloud does not have separate create and start phases, so this operation only sets up OCI-related scaffolding.


--bundle DIR

Directory containing the OCI bundle. This must be /tmp/buildahYYY, where YYY matches CONTAINER_ID below.

--pid-file FILE

Filename to write the “container” process PID to. Note that for Charliecloud, the process given is fake; see above. This must be DIR/pid, where DIR is given by --bundle.


Ignored. (Charliecloud does not implement session keyrings.)


String to use as the container ID. This must be buildah-buildahYYY, where YYY matches DIR above.

Unsupported arguments:

--console-socket PATH

UNIX socket to pass pseudoterminal file descriptor. Charliecloud does not support pseudoterminals; fail with an error if this argument is given. For Buildah, redirect its input from /dev/null to prevent it from requesting a pseudoterminal.


$ ch-run-oci delete CONTAINER_ID

Clean up the OCI-related scaffolding for specified container.


$ ch-run-oci kill CONTAINER_ID



$ ch-run-oci start CONTAINER_ID

Eexecute the user command specified at create time in a Charliecloud container.


$ ch-run-oci state CONTAINER_ID

Print the state of the given container on standard output as an OCI compliant JSON document.

Unsupported Oci Features

As noted above, various OCI features are not supported by Charliecloud. We have tried to guess which features would be essential to callers; ch-run-oci fails with an error if these are requested. Otherwise, the request is simply ignored.

We are interested in hearing about scientific-computing use cases for unsupported features, so we can add support for things that are needed.

Our goal is for this man page to be comprehensive: every OCI runtime feature should either work or be listed as unsupported.

Unsupported features that are an error:

Unsupported features that are ignored:

Environment Variables


If set, append log chatter to this file, rather than standard error. This is useful for debugging situations where standard error is consumed or lost.

Also sets verbose mode if not already set (equivalent to --verbose).


If set, prepend PID and timestamp to logged chatter.


If set, save xattrs in the build cache and restore them when rebuilding from the cache (equivalent to --xattrs).


If set to the name of a command (e.g., create), sleep indefinitely when that command is invoked. The purpose here is to halt a build so it can be examined and debugged.

Reporting Bugs

If Charliecloud was obtained from your Linux distribution, use your distribution’s bug reporting procedures.

Otherwise, report bugs to: https://github.com/hpc/charliecloud/issues

See Also


Full documentation at: <https://hpc.github.io/charliecloud>

Referenced By


2024-03-22 00:00 UTC 0.36 Charliecloud