Ubuntu Manpage: ch-run-oci - OCI wrapper for "ch-run"

Provided by: charliecloud-runtime_0.26-1_amd64

NAME

       ch-run-oci - OCI wrapper for "ch-run"

SYNOPSIS

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

DESCRIPTION

NOTE:
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:

• OCI is designed to run services, while Charliecloud is designed to run scientific applications.

• OCI containers are persistent things with a complex lifecycle, while Charliecloud containers are
simply UNIX processes.

• OCI expects support for a variety of namespaces, while Charliecloud supports user and mount, no more
and no less.

• OCI expects runtimes to maintain a supervisor process in addition to user processes; Charliecloud
has no need for this.

• OCI expects runtimes to maintain state throughout the container lifecycle in a location independent
from the caller.

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.

OPERATIONS

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

• OCI runtime and lifecycle spec

• The runc man pages

create
$ 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.

Arguments:

--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.

--no-new-keyring
Ignored. (Charliecloud does not implement session keyrings.)

CONTAINER_ID
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.

delete
$ ch-run-oci delete CONTAINER_ID

Clean up the OCI-related scaffolding for specified container.

kill
$ ch-run-oci kill CONTAINER_ID

No-op.

start
$ ch-run-oci start CONTAINER_ID

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

state
$ 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:

          • Pseudoterminals

          • Hooks (prestart, poststart, and prestop)

          • Annotations

          • Joining existing namespaces

          • Intel Resource Director Technology (RDT)

       Unsupported features that are ignored:

          • Mounts other than the root filesystem (we do use --no-home)

          • User/group mappings beyond one user mapped to EUID and one group mapped to EGID

          • Disabling prctl(PR_SET_NO_NEW_PRIVS)

          • Root filesystem propagation mode

          • sysctl directives

          • masked and read-only paths (remaining unprivileged protects you)

          • Capabilities

          • rlimits

          • Devices (all devices are inherited from the host)

          • cgroups

          • seccomp

          • SELinux

          • AppArmor

          • Container hostname setting

ENVIRONMENT VARIABLES

       CH_LOG_FILE
              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).

       CH_LOG_FESTOON
              If set, prepend PID and timestamp to logged chatter.

       CH_RUN_OCI_HANG
          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

COPYRIGHT

       2014–2021, Triad National Security, LLC

0.26                                          2022-01-30 10:06 UTC                                 CH-RUN-OCI(1)