1CH-RUN-OCI(1)                    Charliecloud                    CH-RUN-OCI(1)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

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
18       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
24       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
29          • OCI is designed to run services, while Charliecloud is designed to
30            run scientific applications.
31
32          • OCI containers are persistent things  with  a  complex  lifecycle,
33            while Charliecloud containers are simply UNIX processes.
34
35          • OCI  expects  support  for  a  variety  of namespaces, while Char‐
36            liecloud supports user and mount, no more and no less.
37
38          • OCI expects runtimes to maintain a supervisor process in  addition
39            to user processes; Charliecloud has no need for this.
40
41          • OCI  expects  runtimes  to maintain state throughout the container
42            lifecycle in a location independent from the caller.
43
44       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
47       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
51       This command supports OCI version 1.0.0 only and fails with an error if
52       other versions are offered.
53

OPERATIONS

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
58OCI runtime and lifecycle spec
59
60       • The runc man pages
61
62   create
63          $ ch-run-oci create --bundle DIR --pid-file FILE [--no-new-keyring] CONTAINER_ID
64
65       Create  a  container.  Charliecloud  does  not have separate create and
66       start phases, so this operation only sets up OCI-related scaffolding.
67
68       Arguments:
69
70          --bundle DIR
71                 Directory containing the OCI bundle. This must be  /tmp/buil‐
72                 dahYYY, where YYY matches CONTAINER_ID below.
73
74          --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
79          --no-new-keyring
80                 Ignored. (Charliecloud does not implement session keyrings.)
81
82          CONTAINER_ID
83                 String to use as the container ID. This must be buildah-buil‐
84                 dahYYY, where YYY matches DIR above.
85
86       Unsupported arguments:
87
88          --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
95   delete
96          $ ch-run-oci delete CONTAINER_ID
97
98       Clean up the OCI-related scaffolding for specified container.
99
100   kill
101          $ ch-run-oci kill CONTAINER_ID
102
103       No-op.
104
105   start
106          $ ch-run-oci start CONTAINER_ID
107
108       Eexecute the user command specified at create time  in  a  Charliecloud
109       container.
110
111   state
112          $ ch-run-oci state CONTAINER_ID
113
114       Print  the  state  of  the given container on standard output as an OCI
115       compliant JSON document.
116

UNSUPPORTED OCI FEATURES

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
123       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
126       Our goal is for this man page to be comprehensive:  every  OCI  runtime
127       feature should either work or be listed as unsupported.
128
129       Unsupported features that are an error:
130
131          • Pseudoterminals
132
133          • Hooks (prestart, poststart, and prestop)
134
135          • Annotations
136
137          • Joining existing namespaces
138
139          • Intel Resource Director Technology (RDT)
140
141       Unsupported features that are ignored:
142
143          • Mounts other than the root filesystem (we do use --no-home)
144
145          • User/group  mappings  beyond one user mapped to EUID and one group
146            mapped to EGID
147
148          • Disabling prctl(PR_SET_NO_NEW_PRIVS)
149
150          • Root filesystem propagation mode
151
152sysctl directives
153
154          • masked and read-only paths (remaining unprivileged protects you)
155
156          • Capabilities
157
158          • rlimits
159
160          • Devices (all devices are inherited from the host)
161
162          • cgroups
163
164          • seccomp
165
166          • SELinux
167
168          • AppArmor
169
170          • Container hostname setting
171

ENVIRONMENT VARIABLES

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
178              Also sets verbose mode if not already set (equivalent to  --ver‐
179              bose).
180
181       CH_LOG_FESTOON
182              If set, prepend PID and timestamp to logged chatter.
183
184       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

REPORTING BUGS

190       If  Charliecloud  was  obtained  from your Linux distribution, use your
191       distribution’s bug reporting procedures.
192
193       Otherwise, report bugs to: <https://github.com/hpc/charliecloud/issues>
194

SEE ALSO

196       charliecloud(7)
197
198       Full documentation at: <https://hpc.github.io/charliecloud>
199
201       2014–2021, Triad National Security, LLC
202
203
204
205
2060.25                         2021-09-20 00:00 UTC                CH-RUN-OCI(1)
Impressum