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
58       · OCI 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
152          · sysctl 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_RUN_OCI_LOGFILE
174          If set, send log chatter to this file. We use a side channel because
175          standard  error  and standard output may be arbitrarily messed up by
176          the caller.
177
178       CH_RUN_OCI_HANG
179          If set to the name of a command (e.g., create),  sleep  indefinitely
180          when that command is invoked. The purpose here is to halt a build so
181          it can be examined and debugged.
182

REPORTING BUGS

184       If Charliecloud was obtained from your  Linux  distribution,  use  your
185       distribution’s bug reporting procedures.
186
187       Otherwise, report bugs to: <https://github.com/hpc/charliecloud/issues>
188

SEE ALSO

190       charliecloud(1)
191
192       Full documentation at: <https://hpc.github.io/charliecloud>
193
195       2014–2018, Los Alamos National Security, LLC
196
197
198
199
200                  2020-01-28 00:00 Coordinated Universal Time    CH-RUN-OCI(1)
Impressum