1crun(1) General Commands Manual crun(1)
2
6 crun - a fast and lightweight OCI runtime
7
11 crun [global options] command [command options] [arguments...]
12
16 crun is a command line program for running Linux containers that follow
17 the Open Container Initiative (OCI) format.
18
22 create Create a container. The runtime detaches from the container
23 process once the container environment is created. It is necessary to
24 successively use start for starting the container.
25 delete Remove definition for a container.
28 exec Exec a command in a running container.
31 list List known containers.
34 kill Send the specified signal to the container init process. If no
37 signal is specified, SIGTERM is used.
38 ps Show the processes running in a container.
41 run Create and immediately start a container.
44 spec Generate a configuration file.
47 start Start a container that was previously created. A container can‐
50 not be started multiple times.
51 state Output the state of a container.
54 pause Pause all the processes in the container.
57 resume Resume the processes in the container.
60 update Update container resource constraints.
63
67 By default, when running as root user, crun saves its state under the
68 /run/crun directory. As unprivileged user, instead the XDG_RUNTIME_DIR
69 environment variable is honored, and the directory $XDG_RUN‐
70 TIME_DIR/crun is used. The global option --root overrides this set‐
71 ting.
72
76 --debug Produce verbose output.
77 --log=LOG-DESTINATION Define the destination for the error and warning
80 messages generated by crun. If the error happens late in the container
81 init process, when crun already stopped watching it, then it will be
82 printed to the container stderr.
83 It is specified in the form BACKEND:SPECIFIER.
86 These following backends are supported:
89 · file:PATH
92 · journald:IDENTIFIER
94 · syslog:IDENTIFIER
96 If no backend is specified, then file: is used by default.
100 --log-format=FORMAT Define the format of the log messages. It can
103 either be text, or json. The default is text.
104 --no-pivot Use chroot(2) instead of pivot_root(2) when creating the
107 container. This option is not safe, and should be avoided.
108 --root=DIR Defines where to store the state for crun containers.
111 --systemd-cgroup Use systemd for configuring cgroups. If not speci‐
114 fied, the cgroup is created directly using the cgroupfs backend.
115 --cgroup-manager=MANAGER Specify what cgroup manager must be used.
118 Permitted values are cgroupfs, systemd and disabled.
119 -?, --help Print a help list.
122 --usage Print a short usage message.
125 -V, --version Print program version
128
131 crun [global options] create [options] CONTAINER
132 --bundle=BUNDLE Path to the OCI bundle, by default it is the current
135 directory.
136 --console-socket=SOCKET Path to a UNIX socket that will receive the
139 master end of the tty for the container.
140 --no-new-keyring Keep the same session key
143 --preserve-fds=N Additional number of FDs to pass into the container.
146 --pid-file=PATH Path to the file that will contain the container
149 process PID.
150
153 crun [global options] run [options] CONTAINER
154 --bundle=BUNDLE Path to the OCI bundle, by default it is the current
157 directory.
158 --console-socket=SOCKET Path to a UNIX socket that will receive the
161 master end of the tty for the container.
162 --no-new-keyring Keep the same session key.
165 --preserve-fds=N Additional number of FDs to pass into the container.
168 --pid-file=PATH Path to the file that will contain the container
171 process PID.
172 --detach Detach the container process from the current session.
175
178 crun [global options] delete [options] CONTAINER
179 --force Delete the container even if it is still running.
182 --regex=REGEX Delete all the containers that satisfy the specified
185 regex.
186
189 crun [global options] exec [options] CONTAINER CMD
190 --console-socket=SOCKET Path to a UNIX socket that will receive the
193 master end of the tty for the container.
194 --cwd=PATH Set the working directory for the process to PATH.
197 --cap=CAP Specify an additional capability to add to the process.
200 --detach Detach the container process from the current session.
203 --env=ENV Specify an environment variable.
206 --preserve-fds=N Additional number of FDs to pass into the container.
209 --process=FILE Path to a file containing the process JSON configura‐
212 tion.
213 --pid-file=PATH Path to the file that will contain the new process PID.
216 -t --tty Allocate a pseudo TTY.
219 -u USERSPEC --user=USERSPEC Specify the user in the form UID[:GID].
222
225 crun [global options] list [options]
226 -q --quiet Show only the container ID.
229
232 crun [global options] kill [options] CONTAINER SIGNAL
233 --all Kill all the processes in the container.
236 --regex=REGEX Kill all the containers that satisfy the specified regex.
239
242 crun [global options] ps [options]
243 --format=FORMAT Specify the output format. It must be either table or
246 json. By default table is used.
247
250 crun [global options] spec [options]
251 --rootless Generate a config.json file that is usable by an unprivi‐
254 leged user.
255
258 crun [global options] update [options] CONTAINER
259 --blkio-weight=VALUE Specifies per cgroup weight.
262 --cpu-period=VALUE CPU CFS period to be used for hardcapping.
265 --cpu-quota=VALUE** CPU CFS hardcap limit.
268 --cpu-rt-period=VALUE CPU realtime period to be used for hardcapping.
271 --cpu-rt-runtime=VALUE CPU realtime hardcap limit.
274 --cpu-share=VALUE CPU shares.
277 --cpuset-cpus=VALUE CPU(s) to use.
280 --cpuset-mems=VALUE Memory node(s) to use.
283 --kernel-memory=VALUE Kernel memory limit.
286 --kernel-memory-tcp=VALUE Kernel memory limit for TCP buffer.
289 --memory=VALUE Memory limit.
292 --memory-reservation=VALUE Memory reservation or soft_limit.
295 --memory-swap=VALUE Total memory usage.
298 --pids-limit=VALUE Maximum number of pids allowed in the container.
301 -r, --resources=FILE Path to the file containing the resources to
304 update.
305
310 If the annotation run.oci.seccomp_fail_unknown_syscall is present, then
311 crun will fail when an unknown syscall is encountered in the seccomp
312 configuration.
313
316 If the annotation run.oci.keep_original_groups is present, then crun
317 will skip the setgroups syscall that is used to either set the addi‐
318 tional groups specified in the OCI configuration, or to reset the list
319 of additional groups if none is specified.
320
323 Specify the offset to be written to /proc/self/timens_offsets when cre‐
324 ating a time namespace.
325
328 If the tmpcopyup option is specified for a tmpfs, then the path that is
329 shadowed by the tmpfs mount is recursively copied up to the tmpfs
330 itself.
331
334 When running as user different than root, an user namespace is automat‐
335 ically created even if it is not specified in the config file. The
336 current user is mapped to the ID 0 in the container, and any additional
337 id specified in the files /etc/subuid and /etc/subgid is automatically
338 added starting with ID 1.
339
343 crun has some basic support for cgroup v2. Since the OCI spec is
344 designed for cgroup v1, in some cases there is need to convert from the
345 cgroup v1 configuration to cgroup v2.
346 These are the OCI resources currently supported with cgroup v2 and how
349 they are converted when needed from the cgroup v1 configuration.
350
353 ┌──────────┬────────────────────┬──────────────────┬──────────────────┐
354 │OCI (x) │ cgroup 2 value (y) │ conversion │ comment │
355 ├──────────┼────────────────────┼──────────────────┼──────────────────┤
356 │limit │ memory.max │ y = x │ swap │
357 ├──────────┼────────────────────┼──────────────────┼──────────────────┤
358 │ │ │ │ │
359 ├──────────┼────────────────────┼──────────────────┼──────────────────┤
360 │ │ │ │ │
362 ├─a─l─l─b─o─x─;───┼────────────────────┼──────────────────┼──────────────────┤
363 ├─l──l──l──l───┼────────────────────┼──────────────────┼──────────────────┤
364 ├─l──l──l──l──.─┼────────────────────┼──────────────────┼──────────────────┤
365 ├─O─C─I──(─x─)───┼───c─g─r─o─u─p──2──v─a─l─u─e──(─y─)┼───c─o─n─v─e─r─s─i─o─n──────┼───c─o─m─m─e─n─t─────────┤
366 ├─l─i─m─i─t─────┼──p─i─d─s─.─m─a─x───────────┼───y──=──x───────────┼───.─T─E─────────────┤
367 │ │ │ │ │
369 ├─a─l─l─b─o─x─;───┼────────────────────┼──────────────────┼──────────────────┤
370 ├─l──l──l──l───┼────────────────────┼──────────────────┼──────────────────┤
371 ├─l──l──l──l──.─┼────────────────────┼──────────────────┼──────────────────┤
372 ├─O─C─I──(─x─)───┼───c─g─r─o─u─p──2──v─a─l─u─e──(─y─)┼──y─c─o=─n─v(─e1─r─s+─i─o─n(─(─x───-─┼───c─o2─m)─m─e─n─t*───9─9─9─9─)──┤/
373 │shares │ cpu.weight │ 262142) │ │
374 │ │ │ │ │
375 ├──────────┼──c─o─n─v─e─r─t────────f─r─o─m─┼[─2─-─2─6─2─1─4─4─]───────t─o─┼[─1─-─1─0─0─0─0─]──────────┤
376 │ │ │ │ │
377 │ │ │ │ │
378 ├──────────┼────────────────────┼──────────────────┼──p─e─r─i─o─d──a─n─d──q─u─o─t─a─┤
379 │period │ cpu.max │ y = x │ are written │
380 │ │ │ │ together │
381 ├──────────┼────────────────────┼──────────────────┼──p─e─r─i─o─d──a─n─d──q─u─o─t─a─┤
382 │quota │ cpu.max │ y = x │ are written │
383 │ │ │ │ together │
384 └──────────┴────────────────────┴──────────────────┴──────────────────┘
385
387 ┌────────────────┬────────────────────┬──────────────────┬─────────┐
388 │OCI (x) │ cgroup 2 value (y) │ conversion │ comment │
389 ├────────────────┼────────────────────┼──────────────────┼─────────┤
390 │weight │ io.bfq.weight │ y = (1 + (x - │ │
391 │ │ │ 10) * 9999 / │ │
392 │ │ │ 990) │ │
393 ├────────────────┼────────────────────┼──────────────────┼─────────┤
394 │ │ convert linearly │ │ │
395 │ │ from [10-1000] to │ │ │
396 │ │ [1-10000] │ │ │
397 ├────────────────┼────────────────────┼──────────────────┼─────────┤
398 │weight_device │ io.bfq.weight │ y = (1 + (x - │ │
399 │ │ │ 10) * 9999 / │ │
400 │ │ │ 990) │ │
401 ├────────────────┼────────────────────┼──────────────────┼─────────┤
402 │ │ convert linearly │ │ │
403 │ │ from [10-1000] to │ │ │
404 │ │ [1-10000] │ │ │
405 ├────────────────┼────────────────────┼──────────────────┼─────────┤
406 │rbps │ io.max │ y=x │ wbps │
407 ├────────────────┼────────────────────┼──────────────────┼─────────┤
408 │ │ │ │ │
409 ├────────────────┼────────────────────┼──────────────────┼─────────┤
410 │ │ │ │ │
412 ├─a─l─l─b─o─x─;─────────┼────────────────────┼──────────────────┼─────────┤ l
413 ├l──l──l────────────┼────────────────────┼──────────────────┼─────────┤ l
414 ├l──l──l──.──────────┼────────────────────┼──────────────────┼─────────┤
415 ├─O─C─I──(─x─)─────────┼───c─g─r─o─u─p──2──v─a─l─u─e──(─y─)┼───c─o─n─v─e─r─s─i─o─n──────┼───c─o─m─m─e─n─t┤
416 ├─c─p─u─s────────────┼──c─p─u─s─e─t─.─c─p─u─s────────┼───y──=──x───────────┼───m─e─m─s───┤
417 │ │ │ │ │
419 ├─a─l─l─b─o─x─;─────────┼────────────────────┼──────────────────┼─────────┤ l
420 ├l──l──l────────────┼────────────────────┼──────────────────┼─────────┤ l
421 ├l──l──l──.──────────┼────────────────────┼──────────────────┼─────────┤
422 ├─O─C─I──(─x─)─────────┼───c─g─r─o─u─p──2──v─a─l─u─e──(─y─)┼───c─o─n─v─e─r─s─i─o─n──────┼───c─o─m─m─e─n─t┤
423 └─.─l─i─m─i─t─_─i─n─_─b─y─t─e─s─┴──h─u─g─e─t─l─b─.─.─m─a─x───────┴───y──=──x───────────┴───.─T─E────┘
424 User Commands crun(1)