1CH-RUN-OCI(1) Charliecloud CH-RUN-OCI(1)
2
6 ch-run-oci - OCI wrapper for "ch-run"
7
9 $ ch-run-oci OPERATION [ARG ...]
10
12 NOTE:
13 This command is experimental. Features may be incomplete and/or
14 buggy. The quality of code is not yet up to the usual Charliecloud
15 standards, and error handling is poor. Please report any issues you
16 find, so we can fix them!
17 Open Containers Initiative (OCI) wrapper for ch-run(1). You probably
19 don’t want to run this command directly; it is intended to interface
20 with other software that expects an OCI runtime. The current goal is to
21 support completely unprivileged image building (e.g. buildah --run‐
22 time=ch-run-oci) rather than general OCI container running.
23 Support of the OCI runtime specification is only partial. This is for
25 two reasons. First, it’s an experimental and incomplete feature. More
26 importantly, the philosophy and goals of OCI differ significantly from
27 those of Charliecloud. Key differences include:
28 • OCI is designed to run services, while Charliecloud is designed to
30 run scientific applications.
31 • OCI containers are persistent things with a complex lifecycle,
33 while Charliecloud containers are simply UNIX processes.
34 • OCI expects support for a variety of namespaces, while Char‐
36 liecloud supports user and mount, no more and no less.
37 • OCI expects runtimes to maintain a supervisor process in addition
39 to user processes; Charliecloud has no need for this.
40 • OCI expects runtimes to maintain state throughout the container
42 lifecycle in a location independent from the caller.
43 For these reasons, ch-run-oci is a bit of a kludge, and much of what it
45 does is provide scaffolding to satisfy OCI requirements.
46 Which OCI features are and are not supported is provided in the rest of
48 this man page, and technical analysis and discussion are in the Con‐
49 tributor’s Guide.
50 This command supports OCI version 1.0.0 only and fails with an error if
52 other versions are offered.
53
55 All OCI operations are accepted, but some are no-ops or merely scaf‐
56 folding to satisfy the caller. For comparison, see also:
57 • OCI runtime and lifecycle spec
59 • The runc man pages
61 create
63 $ ch-run-oci create --bundle DIR --pid-file FILE [--no-new-keyring] CONTAINER_ID
64 Create a container. Charliecloud does not have separate create and
66 start phases, so this operation only sets up OCI-related scaffolding.
67 Arguments:
69 --bundle DIR
71 Directory containing the OCI bundle. This must be /tmp/buil‐
72 dahYYY, where YYY matches CONTAINER_ID below.
73 --pid-file FILE
75 Filename to write the “container” process PID to. Note that
76 for Charliecloud, the process given is fake; see above. This
77 must be DIR/pid, where DIR is given by --bundle.
78 --no-new-keyring
80 Ignored. (Charliecloud does not implement session keyrings.)
81 CONTAINER_ID
83 String to use as the container ID. This must be buildah-buil‐
84 dahYYY, where YYY matches DIR above.
85 Unsupported arguments:
87 --console-socket PATH
89 UNIX socket to pass pseudoterminal file descriptor. Char‐
90 liecloud does not support pseudoterminals; fail with an error
91 if this argument is given. For Buildah, redirect its input
92 from /dev/null to prevent it from requesting a pseudotermi‐
93 nal.
94 delete
96 $ ch-run-oci delete CONTAINER_ID
97 Clean up the OCI-related scaffolding for specified container.
99 kill
101 $ ch-run-oci kill CONTAINER_ID
102 No-op.
104 start
106 $ ch-run-oci start CONTAINER_ID
107 Eexecute the user command specified at create time in a Charliecloud
109 container.
110 state
112 $ ch-run-oci state CONTAINER_ID
113 Print the state of the given container on standard output as an OCI
115 compliant JSON document.
116
118 As noted above, various OCI features are not supported by Charliecloud.
119 We have tried to guess which features would be essential to callers;
120 ch-run-oci fails with an error if these are requested. Otherwise, the
121 request is simply ignored.
122 We are interested in hearing about scientific-computing use cases for
124 unsupported features, so we can add support for things that are needed.
125 Our goal is for this man page to be comprehensive: every OCI runtime
127 feature should either work or be listed as unsupported.
128 Unsupported features that are an error:
130 • Pseudoterminals
132 • Hooks (prestart, poststart, and prestop)
134 • Annotations
136 • Joining existing namespaces
138 • Intel Resource Director Technology (RDT)
140 Unsupported features that are ignored:
142 • Mounts other than the root filesystem (we do use --no-home)
144 • User/group mappings beyond one user mapped to EUID and one group
146 mapped to EGID
147 • Disabling prctl(PR_SET_NO_NEW_PRIVS)
149 • Root filesystem propagation mode
151 • sysctl directives
153 • masked and read-only paths (remaining unprivileged protects you)
155 • Capabilities
157 • rlimits
159 • Devices (all devices are inherited from the host)
161 • cgroups
163 • seccomp
165 • SELinux
167 • AppArmor
169 • Container hostname setting
171
173 CH_LOG_FILE
174 If set, append log chatter to this file, rather than standard
175 error. This is useful for debugging situations where standard
176 error is consumed or lost.
177 Also sets verbose mode if not already set (equivalent to --ver‐
179 bose).
180 CH_LOG_FESTOON
182 If set, prepend PID and timestamp to logged chatter.
183 CH_RUN_OCI_HANG
185 If set to the name of a command (e.g., create), sleep indefinitely
186 when that command is invoked. The purpose here is to halt a build so
187 it can be examined and debugged.
188
190 If Charliecloud was obtained from your Linux distribution, use your
191 distribution’s bug reporting procedures.
192 Otherwise, report bugs to: https://github.com/hpc/charliecloud/issues
194
196 charliecloud(7)
197 Full documentation at: <https://hpc.github.io/charliecloud>
199
201 2014–2021, Triad National Security, LLC
2020.26 2022-07-20 00:00 UTC CH-RUN-OCI(1)