1crun(1)                     General Commands Manual                    crun(1)
2
3
4

NAME

6       crun - a fast and lightweight OCI runtime
7
8
9

SYNOPSIS

11       crun [global options] command [command options] [arguments...]
12
13
14

DESCRIPTION

16       crun is a command line program for running Linux containers that follow
17       the Open Container Initiative (OCI) format.
18
19
20

COMMANDS

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
26
27       delete Remove definition for a container.
28
29
30       exec Exec a command in a running container.
31
32
33       list List known containers.
34
35
36       kill Send the specified signal to the container init  process.   If  no
37       signal is specified, SIGTERM is used.
38
39
40       ps Show the processes running in a container.
41
42
43       run Create and immediately start a container.
44
45
46       spec Generate a configuration file.
47
48
49       start  Start a container that was previously created.  A container can‐
50       not be started multiple times.
51
52
53       state Output the state of a container.
54
55
56       pause Pause all the processes in the container.
57
58
59       resume Resume the processes in the container.
60
61
62       update Update container resource constraints.
63
64
65       checkpoint Checkpoint a running container using CRIU
66
67
68       restore Restore a container from a checkpoint
69
70
71

STATE

73       By default, when running as root user, crun saves its state  under  the
74       /run/crun directory.  As unprivileged user, instead the XDG_RUNTIME_DIR
75       environment  variable  is  honored,   and   the   directory   $XDG_RUN‐
76       TIME_DIR/crun  is  used.   The global option --root overrides this set‐
77       ting.
78
79
80

GLOBAL OPTIONS

82       --debug Produce verbose output.
83
84
85       --log=LOG-DESTINATION Define the destination for the error and  warning
86       messages generated by crun.  If the error happens late in the container
87       init process, when crun already stopped watching it, then  it  will  be
88       printed to the container stderr.
89
90
91       It is specified in the form BACKEND:SPECIFIER.
92
93
94       These following backends are supported:
95
96
97              · file:PATH
98
99              · journald:IDENTIFIER
100
101              · syslog:IDENTIFIER
102
103
104
105       If no backend is specified, then file: is used by default.
106
107
108       --log-format=FORMAT  Define  the  format  of  the log messages.  It can
109       either be text, or json.  The default is text.
110
111
112       --no-pivot Use chroot(2) instead of  pivot_root(2)  when  creating  the
113       container.  This option is not safe, and should be avoided.
114
115
116       --root=DIR Defines where to store the state for crun containers.
117
118
119       --systemd-cgroup  Use  systemd  for configuring cgroups.  If not speci‐
120       fied, the cgroup is created directly using the cgroupfs backend.
121
122
123       --cgroup-manager=MANAGER Specify what  cgroup  manager  must  be  used.
124       Permitted values are cgroupfs, systemd and disabled.
125
126
127       -?, --help Print a help list.
128
129
130       --usage Print a short usage message.
131
132
133       -V, --version Print program version
134
135

CREATE OPTIONS

137       crun [global options] create [options] CONTAINER
138
139
140       --bundle=BUNDLE  Path  to  the OCI bundle, by default it is the current
141       directory.
142
143
144       --config=FILE Override the configuration  file  to  use.   The  default
145       value is config.json.
146
147
148       --console-socket=SOCKET  Path  to  a  UNIX socket that will receive the
149       ptmx end of the tty for the container.
150
151
152       --no-new-keyring Keep the same session key
153
154
155       --preserve-fds=N Additional number of FDs to pass into the container.
156
157
158       --pid-file=PATH Path to  the  file  that  will  contain  the  container
159       process PID.
160
161

RUN OPTIONS

163       crun [global options] run [options] CONTAINER
164
165
166       --bundle=BUNDLE  Path  to  the OCI bundle, by default it is the current
167       directory.
168
169
170       --config=FILE Override the configuration  file  to  use.   The  default
171       value is config.json.
172
173
174       --console-socket=SOCKET  Path  to  a  UNIX socket that will receive the
175       ptmx end of the tty for the container.
176
177
178       --no-new-keyring Keep the same session key.
179
180
181       --preserve-fds=N Additional number of FDs to pass into the container.
182
183
184       --pid-file=PATH Path to  the  file  that  will  contain  the  container
185       process PID.
186
187
188       --detach Detach the container process from the current session.
189
190

DELETE OPTIONS

192       crun [global options] delete [options] CONTAINER
193
194
195       --force Delete the container even if it is still running.
196
197
198       --regex=REGEX  Delete  all  the  containers  that satisfy the specified
199       regex.
200
201

EXEC OPTIONS

203       crun [global options] exec [options] CONTAINER CMD
204
205
206       --console-socket=SOCKET Path to a UNIX socket  that  will  receive  the
207       ptmx end of the tty for the container.
208
209
210       --cwd=PATH Set the working directory for the process to PATH.
211
212
213       --cap=CAP Specify an additional capability to add to the process.
214
215
216       --detach Detach the container process from the current session.
217
218
219       --env=ENV Specify an environment variable.
220
221
222       --preserve-fds=N Additional number of FDs to pass into the container.
223
224
225       --process=FILE  Path  to  a file containing the process JSON configura‐
226       tion.
227
228
229       --pid-file=PATH Path to the file that will contain the new process PID.
230
231
232       -t --tty Allocate a pseudo TTY.
233
234
235       -u USERSPEC --user=USERSPEC Specify the user in the form UID[:GID].
236
237

LIST OPTIONS

239       crun [global options] list [options]
240
241
242       -q --quiet Show only the container ID.
243
244

KILL OPTIONS

246       crun [global options] kill [options] CONTAINER SIGNAL
247
248
249       --all Kill all the processes in the container.
250
251
252       --regex=REGEX Kill all the containers that satisfy the specified regex.
253
254

PS OPTIONS

256       crun [global options] ps [options]
257
258
259       --format=FORMAT Specify the output format.  It must be either table  or
260       json.  By default table is used.
261
262

SPEC OPTIONS

264       crun [global options] spec [options]
265
266
267       --rootless  Generate  a  config.json file that is usable by an unprivi‐
268       leged user.
269
270

UPDATE OPTIONS

272       crun [global options] update [options] CONTAINER
273
274
275       --blkio-weight=VALUE Specifies per cgroup weight.
276
277
278       --cpu-period=VALUE CPU CFS period to be used for hardcapping.
279
280
281       --cpu-quota=VALUE** CPU CFS hardcap limit.
282
283
284       --cpu-rt-period=VALUE CPU realtime period to be used for hardcapping.
285
286
287       --cpu-rt-runtime=VALUE CPU realtime hardcap limit.
288
289
290       --cpu-share=VALUE CPU shares.
291
292
293       --cpuset-cpus=VALUE CPU(s) to use.
294
295
296       --cpuset-mems=VALUE Memory node(s) to use.
297
298
299       --kernel-memory=VALUE Kernel memory limit.
300
301
302       --kernel-memory-tcp=VALUE Kernel memory limit for TCP buffer.
303
304
305       --memory=VALUE Memory limit.
306
307
308       --memory-reservation=VALUE Memory reservation or soft_limit.
309
310
311       --memory-swap=VALUE Total memory usage.
312
313
314       --pids-limit=VALUE Maximum number of pids allowed in the container.
315
316
317       -r, --resources=FILE Path to  the  file  containing  the  resources  to
318       update.
319
320

CHECKPOINT OPTIONS

322       crun [global options] checkpoint [options] CONTAINER
323
324
325       --image-path=DIR Path for saving CRIU image files
326
327
328       --work-path=DIR Path for saving work files and logs
329
330
331       --leave-running Leave the process running after checkpointing
332
333
334       --tcp-established Allow open TCP connections
335
336
337       --ext-unix-sk Allow external UNIX sockets
338
339
340       --shell-job Allow shell jobs
341
342

RESTORE OPTIONS

344       crun [global options] restore [options] CONTAINER
345
346
347       -b DIR --bundle=DIR Container bundle directory (default ".")
348
349
350       --image-path=DIR Path for saving CRIU image files
351
352
353       --work-path=DIR Path for saving work files and logs
354
355
356       --tcp-established Allow open TCP connections
357
358
359       --ext-unix Allow external UNIX sockets
360
361
362       --shell-job Allow shell jobs
363
364
365       --detach Detach from the container's process
366
367
368       --pid-file=FILE Where to write the PID of the container
369
370
371

Extensions to OCI

run.oci.seccomp.receiver=PATH

374       If  the annotation run.oci.seccomp.receiver=PATH is specified, the sec‐
375       comp listener is sent to the UNIX socket  listening  on  the  specified
376       path.   It  can  also set with the RUN_OCI_SECCOMP_RECEIVER environment
377       variable.  It is an experimental feature, and the  annotation  will  be
378       removed  once  it is supported in the OCI runtime specs.  It must be an
379       absolute path.
380
381

run.oci.seccomp.plugins=PATH

383       If the annotation run.oci.seccomp.plugins=PLUGIN1[:PLUGIN2]... is spec‐
384       ified,  the  seccomp listener fd is handled through the specified plug‐
385       ins.  The plugin must either be an absolute path or a file name that is
386       looked  up  by  ldopen(3).   More information on how the lookup is per‐
387       formed are available on the ld.so(8) man page.
388
389

run.oci.seccomp_fail_unknown_syscall=1

391       If the annotation run.oci.seccomp_fail_unknown_syscall is present, then
392       crun  will  fail  when an unknown syscall is encountered in the seccomp
393       configuration.
394
395

run.oci.seccomp_bpf_data=PATH

397       If  the  annotation  run.oci.seccomp_bpf_data  is  present,  then  crun
398       ignores  the  seccomp section in the OCI configuration file and use the
399       specified data as the raw data to the  seccomp(SECCOMP_SET_MODE_FILTER)
400       syscall.  The data must be encoded in base64.
401
402
403       It  is an experimental feature, and the annotation will be removed once
404       it is supported in the OCI runtime specs.
405
406

run.oci.keep_original_groups=1

408       If the annotation run.oci.keep_original_groups is  present,  then  crun
409       will  skip  the  setgroups syscall that is used to either set the addi‐
410       tional groups specified in the OCI configuration, or to reset the  list
411       of additional groups if none is specified.
412
413

run.oci.systemd.force_cgroup_v1=/PATH

415       If  the  annotation  run.oci.systemd.force_cgroup_v1=/PATH  is present,
416       then crun will override the specified mount point /PATH with  a  cgroup
417       v1 mount made of a single hierarchy none,name=systemd.  It is useful to
418       run on a cgroup v2 system containers using older  versions  of  systemd
419       that lack support for cgroup v2.
420
421

run.oci.timens_offset=ID SEC NSEC

423       Specify the offset to be written to /proc/self/timens_offsets when cre‐
424       ating a time namespace.
425
426

run.oci.systemd.subgroup=SUBGROUP

428       Override the name for the systemd sub cgroup created under the  systemd
429       scope, so the final cgroup will be like:
430
431
432              /sys/fs/cgroup/$PATH/$SUBGROUP
433
434
435
436       When it is set to the empty string, a sub cgroup is not created.
437
438
439       If  not  specified, it defaults to container on cgroup v2, and to "" on
440       cgroup v1.
441
442
443       e.g.
444
445
446              /sys/fs/cgroup//system.slice/foo-352700.scope/container
447
448
449

run.oci.hooks.stdout=FILE

451       If the annotation run.oci.hooks.stdout is present, then crun will  open
452       the  specified  file  and  use it as the stdout for the hook processes.
453       The file is opened in append mode and  it  is  created  if  it  doesn't
454       already exist.
455
456

run.oci.hooks.stderr=FILE

458       If  the annotation run.oci.hooks.stderr is present, then crun will open
459       the specified file and use it as the stderr  for  the  hook  processes.
460       The  file  is  opened  in  append  mode and it is created if it doesn't
461       already exist.
462
463

run.oci.handler=HANDLER

465       It is an experimental feature.
466
467
468       If specified, run the specified handler for execing the container.  The
469       only  supported  value is krun.  When krun is specified, the libkrun.so
470       shared object is loaded and it is used to launch  the  container  using
471       libkrun.
472
473

tmpcopyup mount options

475       If the tmpcopyup option is specified for a tmpfs, then the path that is
476       shadowed by the tmpfs mount is  recursively  copied  up  to  the  tmpfs
477       itself.
478
479

Automatically create user namespace

481       When running as user different than root, an user namespace is automat‐
482       ically created even if it is not specified in  the  config  file.   The
483       current user is mapped to the ID 0 in the container, and any additional
484       id specified in the files /etc/subuid and /etc/subgid is  automatically
485       added starting with ID 1.
486
487

Intermediate user namespace

489       If  the  configuration  specifies a new user namespace made of a single
490       mapping to the root user, but either the UID or  the  GID  are  set  as
491       nonzero  then  crun automatically creates another user namespace to map
492       the root user to the specified UID and GID.
493
494
495       It enables running unprivileged containers with UID and  GID  different
496       than  zero, even when a single UID and GID are available, e.g. rootless
497       users on a system without newuidmap/newgidmap.
498
499
500

CGROUP v2

502       If the cgroup configuration found is for cgroup  v1,  crun  attempts  a
503       conversion when running on a cgroup v2 system.
504
505
506       These  are the OCI resources currently supported with cgroup v2 and how
507       they are converted when needed from the cgroup v1 configuration.
508
509

Memory controller

511       ┌────────────┬────────────────────┬────────────┬─────────┐
512OCI (x)     cgroup 2 value (y) conversion comment 
513       ├────────────┼────────────────────┼────────────┼─────────┤
514       │limit       │ memory.max         │ y = x      │ swap    │
515       ├────────────┼────────────────────┼────────────┼─────────┤
516       │reservation │ memory.low         │ y = x      │         │
517       └────────────┴────────────────────┴────────────┴─────────┘
518

PIDs controller

520       ┌────────┬────────────────────┬────────────┬─────────┐
521OCI (x) cgroup 2 value (y) conversion comment 
522       ├────────┼────────────────────┼────────────┼─────────┤
523       │limit   │ pids.max           │ y = x      │         │
524       └────────┴────────────────────┴────────────┴─────────┘
525

CPU controller

527       ┌────────┬────────────────────┬──────────────────┬──────────────────┐
528OCI (x) cgroup 2 value (y) conversion       comment          
529       ├────────┼────────────────────┼──────────────────┼──────────────────┤
530       │shares  │ cpu.weight         │ y = (1 +  ((x  - │                  │
531       │        │                    │ 2)   *  9999)  / │                  │
532       │        │                    │ 262142)          │                  │
533       ├────────┼────────────────────┼──────────────────┼──────────────────┤
534       │        │ convert       from │                  │                  │
535       │        │ [2-262144]      to │                  │                  │
536       │        │ [1-10000]          │                  │                  │
537       ├────────┼────────────────────┼──────────────────┼──────────────────┤
538       │period  │ cpu.max            │ y = x            │ period and quota │
539       │        │                    │                  │ are      written │
540       │        │                    │                  │ together         │
541       ├────────┼────────────────────┼──────────────────┼──────────────────┤
542       │quota   │ cpu.max            │ y = x            │ period and quota │
543       │        │                    │                  │ are      written │
544       │        │                    │                  │ together         │
545       ├────────┼────────────────────┼──────────────────┼──────────────────┤
546       │        │                    │                  │                  │
547       └────────┴────────────────────┴──────────────────┴──────────────────┘
548

blkio controller

550       ┌────────┬────────────────────┬────────────┬───────────────┐
551OCI (x) cgroup 2 value (y) conversion comment       
552       ├────────┼────────────────────┼────────────┼───────────────┤
553       │weight  │ io.bfq.weight      │ y = x      │ weight_device │
554       └────────┴────────────────────┴────────────┴───────────────┘
555

cpuset controller

557       ┌────────┬────────────────────┬────────────┬─────────┐
558OCI (x) cgroup 2 value (y) conversion comment 
559       ├────────┼────────────────────┼────────────┼─────────┤
560       │cpus    │ cpuset.cpus        │ y = x      │ mems    │
561       └────────┴────────────────────┴────────────┴─────────┘
562

hugetlb controller

564       ┌────────────────┬────────────────────┬────────────┬─────────┐
565OCI (x)         cgroup 2 value (y) conversion comment 
566       ├────────────────┼────────────────────┼────────────┼─────────┤
567       │.limit_in_bytes │ hugetlb..max       │ y = x      │         │
568       └────────────────┴────────────────────┴────────────┴─────────┘
569
570
571                                 User Commands                         crun(1)
Impressum