1podman-create(1) General Commands Manual podman-create(1)
2
3
4
6 podman-create - Create a new container
7
8
10 podman create [options] image [command [arg ...]]
11
12
13 podman container create [options] image [command [arg ...]]
14
15
17 Creates a writable container layer over the specified image and pre‐
18 pares it for running the specified command. The container ID is then
19 printed to STDOUT. This is similar to podman run -d except the con‐
20 tainer is never started. You can then use the podman start container
21 command to start the container at any point.
22
23
24 The initial status of the container created with podman create is 'cre‐
25 ated'.
26
27
28 Default settings for flags are defined in containers.conf. Most set‐
29 tings for remote connections use the server's containers.conf, except
30 when documented in man pages.
31
32
34 The image is specified using transport:path format. If no transport is
35 specified, the docker (container registry) transport will be used by
36 default. For remote Podman, including Mac and Windows (excluding WSL2)
37 machines, docker is the only allowed transport.
38
39
40 dir:path
41 An existing local directory path storing the manifest, layer tarballs
42 and signatures as individual files. This is a non-standardized format,
43 primarily useful for debugging or noninvasive container inspection.
44
45
46 $ podman save --format docker-dir fedora -o /tmp/fedora
47 $ podman create dir:/tmp/fedora echo hello
48
49
50
51 docker://docker-reference (Default)
52 An image reference stored in a remote container image registry. Ex‐
53 ample: "quay.io/podman/stable:latest". The reference can include a
54 path to a specific registry; if it does not, the registries listed in
55 registries.conf will be queried to find a matching image. By default,
56 credentials from podman login (stored at $XDG_RUNTIME_DIR/contain‐
57 ers/auth.json by default) will be used to authenticate; otherwise it
58 falls back to using credentials in $HOME/.docker/config.json.
59
60
61 $ podman create registry.fedoraproject.org/fedora:latest echo hello
62
63
64
65 docker-archive:path[:docker-reference] An image stored in the docker
66 save formatted file. docker-reference is only used when creating such a
67 file, and it must not contain a digest.
68
69
70 $ podman save --format docker-archive fedora -o /tmp/fedora
71 $ podman create docker-archive:/tmp/fedora echo hello
72
73
74
75 docker-daemon:docker-reference
76 An image in docker-reference format stored in the docker daemon in‐
77 ternal storage. The docker-reference can also be an image ID (docker-
78 daemon:algo:digest).
79
80
81 $ sudo docker pull fedora
82 $ sudo podman create docker-daemon:docker.io/library/fedora echo hello
83
84
85
86 oci-archive:path:tag
87 An image in a directory compliant with the "Open Container Image Lay‐
88 out Specification" at the specified path and specified with a tag.
89
90
91 $ podman save --format oci-archive fedora -o /tmp/fedora
92 $ podman create oci-archive:/tmp/fedora echo hello
93
94
95
97 --add-host=host:ip
98 Add a custom host-to-IP mapping (host:ip)
99
100
101 Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
102 tion can be set multiple times. Conflicts with the --no-hosts option.
103
104
105 --annotation=key=value
106 Add an annotation to the container. This option can be set multiple
107 times.
108
109
110 --arch=ARCH
111 Override the architecture, defaults to hosts, of the image to be
112 pulled. For example, arm. Unless overridden, subsequent lookups of the
113 same image in the local storage will match this architecture, regard‐
114 less of the host.
115
116
117 --attach, -a=stdin | stdout | stderr
118 Attach to STDIN, STDOUT or STDERR.
119
120
121 In foreground mode (the default when -d is not specified), podman run
122 can start the process in the container and attach the console to the
123 process's standard input, output, and error. It can even pretend to be
124 a TTY (this is what most command-line executables expect) and pass
125 along signals. The -a option can be set for each of stdin, stdout, and
126 stderr.
127
128
129 --authfile=path
130 Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
131 ers/auth.json, which is set using podman login. If the authorization
132 state is not found there, $HOME/.docker/config.json is checked, which
133 is set using docker login.
134
135
136 Note: There is also the option to override the default path of the au‐
137 thentication file by setting the REGISTRY_AUTH_FILE environment vari‐
138 able. This can be done with export REGISTRY_AUTH_FILE=path.
139
140
141 --blkio-weight=weight
142 Block IO relative weight. The weight is a value between 10 and 1000.
143
144
145 This option is not supported on cgroups V1 rootless systems.
146
147
148 --blkio-weight-device=device:weight
149 Block IO relative device weight.
150
151
152 --cap-add=capability
153 Add Linux capabilities.
154
155
156 --cap-drop=capability
157 Drop Linux capabilities.
158
159
160 --cgroup-conf=KEY=VALUE
161 When running on cgroup v2, specify the cgroup file to write to and its
162 value. For example --cgroup-conf=memory.high=1073741824 sets the mem‐
163 ory.high limit to 1GB.
164
165
166 --cgroup-parent=path
167 Path to cgroups under which the cgroup for the container will be cre‐
168 ated. If the path is not absolute, the path is considered to be rela‐
169 tive to the cgroups path of the init process. Cgroups will be created
170 if they do not already exist.
171
172
173 --cgroupns=mode
174 Set the cgroup namespace mode for the container.
175
176
177 • host: use the host's cgroup namespace inside the container.
178
179 • container:id: join the namespace of the specified container.
180
181 • private: create a new cgroup namespace.
182
183 • ns:path: join the namespace at the specified path.
184
185
186
187 If the host uses cgroups v1, the default is set to host. On cgroups v2,
188 the default is private.
189
190
191 --cgroups=how
192 Determines whether the container will create CGroups.
193
194
195 Default is enabled.
196
197
198 The enabled option will create a new cgroup under the cgroup-parent.
199 The disabled option will force the container to not create CGroups, and
200 thus conflicts with CGroup options (--cgroupns and --cgroup-parent).
201 The no-conmon option disables a new CGroup only for the conmon process.
202 The split option splits the current CGroup in two sub-cgroups: one for
203 conmon and one for the container payload. It is not possible to set
204 --cgroup-parent with split.
205
206
207 --chrootdirs=path
208 Path to a directory inside the container that should be treated as a
209 chroot directory. Any Podman managed file (e.g., /etc/resolv.conf,
210 /etc/hosts, etc/hostname) that is mounted into the root directory will
211 be mounted into that location as well. Multiple directories should be
212 separated with a comma.
213
214
215 --cidfile=file
216 Write the container ID to file.
217
218
219 --conmon-pidfile=file
220 Write the pid of the conmon process to a file. As conmon runs in a sep‐
221 arate process than Podman, this is necessary when using systemd to
222 restart Podman containers. (This option is not available with the re‐
223 mote Podman client, including Mac and Windows (excluding WSL2) ma‐
224 chines)
225
226
227 --cpu-period=limit
228 Set the CPU period for the Completely Fair Scheduler (CFS), which is a
229 duration in microseconds. Once the container's CPU quota is used up, it
230 will not be scheduled to run until the current period ends. Defaults to
231 100000 microseconds.
232
233
234 On some systems, changing the resource limits may not be allowed for
235 non-root users. For more details, see https://github.com/contain‐
236 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
237 source-limits-fails-with-a-permissions-error
238
239
240 This option is not supported on cgroups V1 rootless systems.
241
242
243 --cpu-quota=limit
244 Limit the CPU Completely Fair Scheduler (CFS) quota.
245
246
247 Limit the container's CPU usage. By default, containers run with the
248 full CPU resource. The limit is a number in microseconds. If a number
249 is provided, the container will be allowed to use that much CPU time
250 until the CPU period ends (controllable via --cpu-period).
251
252
253 On some systems, changing the resource limits may not be allowed for
254 non-root users. For more details, see https://github.com/contain‐
255 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
256 source-limits-fails-with-a-permissions-error
257
258
259 This option is not supported on cgroups V1 rootless systems.
260
261
262 --cpu-rt-period=microseconds
263 Limit the CPU real-time period in microseconds.
264
265
266 Limit the container's Real Time CPU usage. This option tells the kernel
267 to restrict the container's Real Time CPU usage to the period speci‐
268 fied.
269
270
271 This option is only supported on cgroups V1 rootful systems.
272
273
274 --cpu-rt-runtime=microseconds
275 Limit the CPU real-time runtime in microseconds.
276
277
278 Limit the containers Real Time CPU usage. This option tells the kernel
279 to limit the amount of time in a given CPU period Real Time tasks may
280 consume. Ex: Period of 1,000,000us and Runtime of 950,000us means that
281 this container could consume 95% of available CPU and leave the remain‐
282 ing 5% to normal priority tasks.
283
284
285 The sum of all runtimes across containers cannot exceed the amount al‐
286 lotted to the parent cgroup.
287
288
289 This option is only supported on cgroups V1 rootful systems.
290
291
292 --cpu-shares, -c=shares
293 CPU shares (relative weight).
294
295
296 By default, all containers get the same proportion of CPU cycles. This
297 proportion can be modified by changing the container's CPU share
298 weighting relative to the combined weight of all the running contain‐
299 ers. Default weight is 1024.
300
301
302 The proportion will only apply when CPU-intensive processes are run‐
303 ning. When tasks in one container are idle, other containers can use
304 the left-over CPU time. The actual amount of CPU time will vary depend‐
305 ing on the number of containers running on the system.
306
307
308 For example, consider three containers, one has a cpu-share of 1024 and
309 two others have a cpu-share setting of 512. When processes in all three
310 containers attempt to use 100% of CPU, the first container would re‐
311 ceive 50% of the total CPU time. If a fourth container is added with a
312 cpu-share of 1024, the first container only gets 33% of the CPU. The
313 remaining containers receive 16.5%, 16.5% and 33% of the CPU.
314
315
316 On a multi-core system, the shares of CPU time are distributed over all
317 CPU cores. Even if a container is limited to less than 100% of CPU
318 time, it can use 100% of each individual CPU core.
319
320
321 For example, consider a system with more than three cores. If the con‐
322 tainer C0 is started with --cpu-shares=512 running one process, and an‐
323 other container C1 with --cpu-shares=1024 running two processes, this
324 can result in the following division of CPU shares:
325
326
327 ┌────┬───────────┬─────┬──────────────┐
328 │PID │ container │ CPU │ CPU share │
329 ├────┼───────────┼─────┼──────────────┤
330 │100 │ C0 │ 0 │ 100% of CPU0 │
331 ├────┼───────────┼─────┼──────────────┤
332 │101 │ C1 │ 1 │ 100% of CPU1 │
333 ├────┼───────────┼─────┼──────────────┤
334 │102 │ C1 │ 2 │ 100% of CPU2 │
335 └────┴───────────┴─────┴──────────────┘
336
337 On some systems, changing the resource limits may not be allowed for
338 non-root users. For more details, see https://github.com/contain‐
339 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
340 source-limits-fails-with-a-permissions-error
341
342
343 This option is not supported on cgroups V1 rootless systems.
344
345
346 --cpus=number
347 Number of CPUs. The default is 0.0 which means no limit. This is short‐
348 hand for --cpu-period and --cpu-quota, so you may only set either
349 --cpus or --cpu-period and --cpu-quota.
350
351
352 On some systems, changing the CPU limits may not be allowed for non-
353 root users. For more details, see https://github.com/containers/pod‐
354 man/blob/main/troubleshooting.md#26-running-containers-with-resource-
355 limits-fails-with-a-permissions-error
356
357
358 This option is not supported on cgroups V1 rootless systems.
359
360
361 --cpuset-cpus=number
362 CPUs in which to allow execution. Can be specified as a comma-separated
363 list (e.g. 0,1), as a range (e.g. 0-3), or any combination thereof
364 (e.g. 0-3,7,11-15).
365
366
367 On some systems, changing the resource limits may not be allowed for
368 non-root users. For more details, see https://github.com/contain‐
369 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
370 source-limits-fails-with-a-permissions-error
371
372
373 This option is not supported on cgroups V1 rootless systems.
374
375
376 --cpuset-mems=nodes
377 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
378 tive on NUMA systems.
379
380
381 If there are four memory nodes on the system (0-3), use --cpuset-
382 mems=0,1 then processes in the container will only use memory from the
383 first two memory nodes.
384
385
386 On some systems, changing the resource limits may not be allowed for
387 non-root users. For more details, see https://github.com/contain‐
388 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
389 source-limits-fails-with-a-permissions-error
390
391
392 This option is not supported on cgroups V1 rootless systems.
393
394
395 --device=host-device[:container-device][:permissions]
396 Add a host device to the container. Optional permissions parameter can
397 be used to specify device permissions by combining r for read, w for
398 write, and m for mknod(2).
399
400
401 Example: --device=/dev/sdc:/dev/xvdc:rwm.
402
403
404 Note: if host-device is a symbolic link then it will be resolved first.
405 The container will only store the major and minor numbers of the host
406 device.
407
408
409 Podman may load kernel modules required for using the specified device.
410 The devices that Podman will load modules for when necessary are:
411 /dev/fuse.
412
413
414 In rootless mode, the new device is bind mounted in the container from
415 the host rather than Podman creating it within the container space. Be‐
416 cause the bind mount retains its SELinux label on SELinux systems, the
417 container can get permission denied when accessing the mounted device.
418 Modify SELinux settings to allow containers to use all device labels
419 via the following command:
420
421
422 $ sudo setsebool -P container_use_devices=true
423
424
425 Note: if the user only has access rights via a group, accessing the de‐
426 vice from inside a rootless container will fail. Use the --group-add
427 keep-groups flag to pass the user's supplementary group access into the
428 container.
429
430
431 --device-cgroup-rule="type major:minor mode"
432 Add a rule to the cgroup allowed devices list. The rule is expected to
433 be in the format specified in the Linux kernel documentation (Documen‐
434 tation/cgroup-v1/devices.txt):
435 - type: a (all), c (char), or b (block);
436 - major and minor: either a number, or * for all;
437 - mode: a composition of r (read), w (write), and m (mknod(2)).
438
439
440 --device-read-bps=path:rate
441 Limit read rate (in bytes per second) from a device (e.g. --device-
442 read-bps=/dev/sda:1mb).
443
444
445 On some systems, changing the resource limits may not be allowed for
446 non-root users. For more details, see https://github.com/contain‐
447 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
448 source-limits-fails-with-a-permissions-error
449
450
451 This option is not supported on cgroups V1 rootless systems.
452
453
454 --device-read-iops=path:rate
455 Limit read rate (in IO operations per second) from a device (e.g. --de‐
456 vice-read-iops=/dev/sda:1000).
457
458
459 On some systems, changing the resource limits may not be allowed for
460 non-root users. For more details, see https://github.com/contain‐
461 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
462 source-limits-fails-with-a-permissions-error
463
464
465 This option is not supported on cgroups V1 rootless systems.
466
467
468 --device-write-bps=path:rate
469 Limit write rate (in bytes per second) to a device (e.g. --device-
470 write-bps=/dev/sda:1mb).
471
472
473 On some systems, changing the resource limits may not be allowed for
474 non-root users. For more details, see https://github.com/contain‐
475 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
476 source-limits-fails-with-a-permissions-error
477
478
479 This option is not supported on cgroups V1 rootless systems.
480
481
482 --device-write-iops=path:rate
483 Limit write rate (in IO operations per second) to a device (e.g. --de‐
484 vice-write-iops=/dev/sda:1000).
485
486
487 On some systems, changing the resource limits may not be allowed for
488 non-root users. For more details, see https://github.com/contain‐
489 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
490 source-limits-fails-with-a-permissions-error
491
492
493 This option is not supported on cgroups V1 rootless systems.
494
495
496 --disable-content-trust
497 This is a Docker-specific option to disable image verification to a
498 container registry and is not supported by Podman. This option is a
499 NOOP and provided solely for scripting compatibility.
500
501
502 --dns=ipaddr
503 Set custom DNS servers.
504
505
506 This option can be used to override the DNS configuration passed to the
507 container. Typically this is necessary when the host DNS configuration
508 is invalid for the container (e.g., 127.0.0.1). When this is the case
509 the --dns flag is necessary for every run.
510
511
512 The special value none can be specified to disable creation of /etc/re‐
513 solv.conf in the container by Podman. The /etc/resolv.conf file in the
514 image will be used without changes.
515
516
517 This option cannot be combined with --network that is set to none or
518 container:id.
519
520
521 --dns-option=option
522 Set custom DNS options. Invalid if using --dns-option with --network
523 that is set to none or container:id.
524
525
526 --dns-search=domain
527 Set custom DNS search domains. Invalid if using --dns-search with
528 --network that is set to none or container:id. Use --dns-search=. if
529 you don't wish to set the search domain.
530
531
532 --entrypoint="command" | '["command", arg1 , ...]'
533 Overwrite the default ENTRYPOINT of the image.
534
535
536 This option allows you to overwrite the default entrypoint of the im‐
537 age.
538
539
540 The ENTRYPOINT of an image is similar to a COMMAND because it specifies
541 what executable to run when the container starts, but it is (purposely)
542 more difficult to override. The ENTRYPOINT gives a container its de‐
543 fault nature or behavior, so that when you set an ENTRYPOINT you can
544 run the container as if it were that binary, complete with default op‐
545 tions, and you can pass in more options via the COMMAND. But, sometimes
546 an operator may want to run something else inside the container, so you
547 can override the default ENTRYPOINT at runtime by using a --entrypoint
548 and a string to specify the new ENTRYPOINT.
549
550
551 You need to specify multi option commands in the form of a json string.
552
553
554 --env, -e=env
555 Set environment variables.
556
557
558 This option allows arbitrary environment variables that are available
559 for the process to be launched inside of the container. If an environ‐
560 ment variable is specified without a value, Podman will check the host
561 environment for a value and set the variable only if it is set on the
562 host. As a special case, if an environment variable ending in * is
563 specified without a value, Podman will search the host environment for
564 variables starting with the prefix and will add those variables to the
565 container.
566
567
568 See Environment ⟨#environment⟩ note below for precedence and examples.
569
570
571 --env-file=file
572 Read in a line-delimited file of environment variables.
573
574
575 See Environment ⟨#environment⟩ note below for precedence and examples.
576
577
578 --env-host
579 Use host environment inside of the container. See Environment note be‐
580 low for precedence. (This option is not available with the remote Pod‐
581 man client, including Mac and Windows (excluding WSL2) machines)
582
583
584 --env-merge=env
585 Preprocess default environment variables for the containers. For exam‐
586 ple if image contains environment variable hello=world user can prepro‐
587 cess it using --env-merge hello=${hello}-some so new value will be
588 hello=world-some.
589
590
591 --expose=port
592 Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up
593 port redirection on the host system.
594
595
596 --gidmap=container_gid:host_gid:amount
597 Run the container in a new user namespace using the supplied GID map‐
598 ping. This option conflicts with the --userns and --subgidname options.
599 This option provides a way to map host GIDs to container GIDs in the
600 same way as --uidmap maps host UIDs to container UIDs. For details see
601 --uidmap.
602
603
604 Note: the --gidmap flag cannot be called in conjunction with the --pod
605 flag as a gidmap cannot be set on the container level when in a pod.
606
607
608 --group-add=group | keep-groups
609 Assign additional groups to the primary user running within the con‐
610 tainer process.
611
612
613 • keep-groups is a special flag that tells Podman to keep the
614 supplementary group access.
615
616
617
618 Allows container to use the user's supplementary group access. If file
619 systems or devices are only accessible by the rootless user's group,
620 this flag tells the OCI runtime to pass the group access into the con‐
621 tainer. Currently only available with the crun OCI runtime. Note: keep-
622 groups is exclusive, you cannot add any other groups with this flag.
623 (Not available for remote commands, including Mac and Windows (exclud‐
624 ing WSL2) machines)
625
626
627 --health-cmd="command" | '["command", arg1 , ...]'
628 Set or alter a healthcheck command for a container. The command is a
629 command to be executed inside your container that determines your con‐
630 tainer health. The command is required for other healthcheck options to
631 be applied. A value of none disables existing healthchecks.
632
633
634 Multiple options can be passed in the form of a JSON array; otherwise,
635 the command will be interpreted as an argument to /bin/sh -c.
636
637
638 --health-interval=interval
639 Set an interval for the healthchecks. An interval of disable results in
640 no automatic timer setup. The default is 30s.
641
642
643 --health-on-failure=action
644 Action to take once the container transitions to an unhealthy state.
645 The default is none.
646
647
648 • none: Take no action.
649
650 • kill: Kill the container.
651
652 • restart: Restart the container. Do not combine the restart
653 action with the --restart flag. When running inside of a sys‐
654 temd unit, consider using the kill or stop action instead to
655 make use of systemd's restart policy.
656
657 • stop: Stop the container.
658
659
660
661 --health-retries=retries
662 The number of retries allowed before a healthcheck is considered to be
663 unhealthy. The default value is 3.
664
665
666 --health-start-period=period
667 The initialization time needed for a container to bootstrap. The value
668 can be expressed in time format like 2m3s. The default value is 0s.
669
670
671 --health-timeout=timeout
672 The maximum time allowed to complete the healthcheck before an interval
673 is considered failed. Like start-period, the value can be expressed in
674 a time format such as 1m22s. The default value is 30s.
675
676
677 --help
678 Print usage statement
679
680
681 --hostname, -h=name
682 Container host name
683
684
685 Sets the container host name that is available inside the container.
686 Can only be used with a private UTS namespace --uts=private (default).
687 If --pod is specified and the pod shares the UTS namespace (default)
688 the pod's hostname will be used.
689
690
691 --hostuser=name
692 Add a user account to /etc/passwd from the host to the container. The
693 Username or UID must exist on the host system.
694
695
696 --http-proxy
697 By default proxy environment variables are passed into the container if
698 set for the Podman process. This can be disabled by setting the value
699 to false. The environment variables passed in include http_proxy,
700 https_proxy, ftp_proxy, no_proxy, and also the upper case versions of
701 those. This option is only needed when the host system must use a proxy
702 but the container should not use any proxy. Proxy environment variables
703 specified for the container in any other way will override the values
704 that would have been passed through from the host. (Other ways to spec‐
705 ify the proxy for the container include passing the values with the
706 --env flag, or hard coding the proxy environment at container build
707 time.) (This option is not available with the remote Podman client,
708 including Mac and Windows (excluding WSL2) machines)
709
710
711 Defaults to true.
712
713
714 --image-volume=bind | tmpfs | ignore
715 Tells Podman how to handle the builtin image volumes. Default is bind.
716
717
718 • bind: An anonymous named volume will be created and mounted
719 into the container.
720
721 • tmpfs: The volume is mounted onto the container as a tmpfs,
722 which allows the users to create content that disappears when
723 the container is stopped.
724
725 • ignore: All volumes are just ignored and no action is taken.
726
727
728
729 --init
730 Run an init inside the container that forwards signals and reaps pro‐
731 cesses. The container-init binary is mounted at /run/podman-init.
732 Mounting over /run will hence break container execution.
733
734
735 --init-ctr=type
736 (Pods only). When using pods, create an init style container, which is
737 run after the infra container is started but before regular pod con‐
738 tainers are started. Init containers are useful for running setup op‐
739 erations for the pod's applications.
740
741
742 Valid values for init-ctr type are always or once. The always value
743 means the container will run with each and every pod start, whereas the
744 once value means the container will only run once when the pod is
745 started and then the container is removed.
746
747
748 Init containers are only run on pod start. Restarting a pod will not
749 execute any init containers should they be present. Furthermore, init
750 containers can only be created in a pod when that pod is not running.
751
752
753 --init-path=path
754 Path to the container-init binary.
755
756
757 --interactive, -i
758 When set to true, keep stdin open even if not attached. The default is
759 false.
760
761
762 --ip=ipv4
763 Specify a static IPv4 address for the container, for example
764 10.88.64.128. This option can only be used if the container is joined
765 to only a single network - i.e., --network=network-name is used at most
766 once - and if the container is not joining another container's network
767 namespace via --network=container:id. The address must be within the
768 network's IP address pool (default 10.88.0.0/16).
769
770
771 To specify multiple static IP addresses per container, set multiple
772 networks using the --network option with a static IP address specified
773 for each using the ip mode for that option.
774
775
776 --ip6=ipv6
777 Specify a static IPv6 address for the container, for example
778 fd46:db93:aa76:ac37::10. This option can only be used if the container
779 is joined to only a single network - i.e., --network=network-name is
780 used at most once - and if the container is not joining another con‐
781 tainer's network namespace via --network=container:id. The address
782 must be within the network's IPv6 address pool.
783
784
785 To specify multiple static IPv6 addresses per container, set multiple
786 networks using the --network option with a static IPv6 address speci‐
787 fied for each using the ip6 mode for that option.
788
789
790 --ipc=ipc
791 Set the IPC namespace mode for a container. The default is to create a
792 private IPC namespace.
793
794
795 • "": Use Podman's default, defined in containers.conf.
796
797 • container:id: reuses another container's shared memory, sema‐
798 phores, and message queues
799
800 • host: use the host's shared memory, semaphores, and message
801 queues inside the container. Note: the host mode gives the
802 container full access to local shared memory and is therefore
803 considered insecure.
804
805 • none: private IPC namespace, with /dev/shm not mounted.
806
807 • ns:path: path to an IPC namespace to join.
808
809 • private: private IPC namespace. = shareable: private IPC
810 namespace with a possibility to share it with other contain‐
811 ers.
812
813
814
815 --label, -l=key=value
816 Add metadata to a container.
817
818
819 --label-file=file
820 Read in a line-delimited file of labels.
821
822
823 --link-local-ip=ip
824 Not implemented.
825
826
827 --log-driver=driver
828 Logging driver for the container. Currently available options are k8s-
829 file, journald, none and passthrough, with json-file aliased to k8s-
830 file for scripting compatibility. (Default journald).
831
832
833 The podman info command below will display the default log-driver for
834 the system.
835
836
837 $ podman info --format '{{ .Host.LogDriver }}'
838 journald
839
840
841
842 The passthrough driver passes down the standard streams (stdin, stdout,
843 stderr) to the container. It is not allowed with the remote Podman
844 client, including Mac and Windows (excluding WSL2) machines, and on a
845 tty, since it is vulnerable to attacks via TIOCSTI.
846
847
848 --log-opt=name=value
849 Logging driver specific options.
850
851
852 Set custom logging configuration. The following *name*s are supported:
853
854
855 path: specify a path to the log file
856 (e.g. --log-opt path=/var/log/container/mycontainer.json);
857
858
859 max-size: specify a max size of the log file
860 (e.g. --log-opt max-size=10mb);
861
862
863 tag: specify a custom log tag for the container
864 (e.g. --log-opt tag="{{.ImageName}}". It supports the same keys as
865 podman inspect --format. This option is currently supported only by
866 the journald log driver.
867
868
869 --mac-address=address
870 Container network interface MAC address (e.g. 92:d0:c6:0a:29:33) This
871 option can only be used if the container is joined to only a single
872 network - i.e., --network=network-name is used at most once - and if
873 the container is not joining another container's network namespace via
874 --network=container:id.
875
876
877 Remember that the MAC address in an Ethernet network must be unique.
878 The IPv6 link-local address will be based on the device's MAC address
879 according to RFC4862.
880
881
882 To specify multiple static MAC addresses per container, set multiple
883 networks using the --network option with a static MAC address specified
884 for each using the mac mode for that option.
885
886
887 --memory, -m=number[unit]
888 Memory limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or
889 g (gibibytes).
890
891
892 Allows the memory available to a container to be constrained. If the
893 host supports swap memory, then the -m memory setting can be larger
894 than physical RAM. If a limit of 0 is specified (not using -m), the
895 container's memory is not limited. The actual limit may be rounded up
896 to a multiple of the operating system's page size (the value would be
897 very large, that's millions of trillions).
898
899
900 This option is not supported on cgroups V1 rootless systems.
901
902
903 --memory-reservation=number[unit]
904 Memory soft limit. A unit can be b (bytes), k (kibibytes), m
905 (mebibytes), or g (gibibytes).
906
907
908 After setting memory reservation, when the system detects memory con‐
909 tention or low memory, containers are forced to restrict their consump‐
910 tion to their reservation. So you should always set the value below
911 --memory, otherwise the hard limit will take precedence. By default,
912 memory reservation will be the same as memory limit.
913
914
915 This option is not supported on cgroups V1 rootless systems.
916
917
918 --memory-swap=number[unit]
919 A limit value equal to memory plus swap. A unit can be b (bytes), k
920 (kibibytes), m (mebibytes), or g (gibibytes).
921
922
923 Must be used with the -m (--memory) flag. The argument value should
924 always be larger than that of
925 -m (--memory) By default, it is set to double the value of --memory.
926
927
928 Set number to -1 to enable unlimited swap.
929
930
931 This option is not supported on cgroups V1 rootless systems.
932
933
934 --memory-swappiness=number
935 Tune a container's memory swappiness behavior. Accepts an integer be‐
936 tween 0 and 100.
937
938
939 This flag is only supported on cgroups V1 rootful systems.
940
941
942 --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
943 Attach a filesystem mount to the container
944
945
946 Current supported mount TYPEs are bind, volume, image, tmpfs and de‐
947 vpts. [1] ⟨#Footnote1⟩
948
949
950 e.g.
951
952 type=bind,source=/path/on/host,destination=/path/in/container
953
954 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
955
956 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true
957
958 type=volume,source=vol1,destination=/path/in/container,ro=true
959
960 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
961
962 type=image,source=fedora,destination=/fedora-image,rw=true
963
964 type=devpts,destination=/dev/pts
965
966 Common Options:
967
968 · src, source: mount source spec for bind and volume. Mandatory for bind.
969
970 · dst, destination, target: mount destination spec.
971
972 Options specific to volume:
973
974 · ro, readonly: true or false (default).
975
976 . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
977
978 · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container.
979
980 Options specific to image:
981
982 · rw, readwrite: true or false (default).
983
984 Options specific to bind:
985
986 · ro, readonly: true or false (default).
987
988 · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2).
989
990 . bind-nonrecursive: do not set up a recursive bind mount. By default it is recursive.
991
992 . relabel: shared, private.
993
994 · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container.
995
996 . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
997
998 Options specific to tmpfs:
999
1000 · ro, readonly: true or false (default).
1001
1002 · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
1003
1004 · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
1005
1006 · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default.
1007
1008 · notmpcopyup: Disable copying files from the image to the tmpfs.
1009
1010 . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
1011
1012 Options specific to devpts:
1013
1014 · uid: UID of the file owner (default 0).
1015
1016 · gid: GID of the file owner (default 0).
1017
1018 · mode: permission mask for the file (default 600).
1019
1020 · max: maximum number of PTYs (default 1048576).
1021
1022
1023
1024 --name=name
1025 Assign a name to the container.
1026
1027
1028 The operator can identify a container in three ways:
1029
1030
1031 • UUID long identifier
1032 (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”);
1033
1034 • UUID short identifier (“f78375b1c487”);
1035
1036 • Name (“jonah”).
1037
1038
1039
1040 Podman generates a UUID for each container, and if a name is not as‐
1041 signed to the container with --name then it will generate a random
1042 string name. The name is useful any place you need to identify a con‐
1043 tainer. This works for both background and foreground containers.
1044
1045
1046 --network=mode, --net
1047 Set the network mode for the container.
1048
1049
1050 Valid mode values are:
1051
1052
1053 • bridge[:OPTIONS,...]: Create a network stack on the default
1054 bridge. This is the default for rootful containers. It is pos‐
1055 sible to specify these additional options:
1056
1057 • alias=name: Add network-scoped alias for the container.
1058
1059 • ip=IPv4: Specify a static ipv4 address for this container.
1060
1061 • ip=IPv6: Specify a static ipv6 address for this container.
1062
1063 • mac=MAC: Specify a static mac address for this container.
1064
1065 • interface_name: Specify a name for the created network in‐
1066 terface inside the container.
1067
1068
1069
1070
1071
1072 For example to set a static ipv4 address and a static mac address, use
1073 --network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99. - <network name
1074 or ID>[:OPTIONS,...]: Connect to a user-defined network; this is the
1075 network name or ID from a network created by podman network create. Us‐
1076 ing the network name implies the bridge network mode. It is possible to
1077 specify the same options described under the bridge mode above. You can
1078 use the --network option multiple times to specify additional networks.
1079 - none: Create a network namespace for the container but do not config‐
1080 ure network interfaces for it, thus the container has no network con‐
1081 nectivity. - container:id: Reuse another container's network stack. -
1082 host: Do not create a network namespace, the container will use the
1083 host's network. Note: The host mode gives the container full access to
1084 local system services such as D-bus and is therefore considered inse‐
1085 cure. - ns:path: Path to a network namespace to join. - private: Cre‐
1086 ate a new namespace for the container. This will use the bridge mode
1087 for rootful containers and slirp4netns for rootless ones. -
1088 slirp4netns[:OPTIONS,...]: use slirp4netns(1) to create a user network
1089 stack. This is the default for rootless containers. It is possible to
1090 specify these additional options, they can also be set with net‐
1091 work_cmd_options in containers.conf:
1092 - allow_host_loopback=true|false: Allow slirp4netns to reach the host
1093 loopback IP (default is 10.0.2.2 or the second IP from slirp4netns cidr
1094 subnet when changed, see the cidr option below). The default is false.
1095 - mtu=MTU: Specify the MTU to use for this network. (Default is
1096 65520).
1097 - cidr=CIDR: Specify ip range to use for this network. (Default is
1098 10.0.2.0/24).
1099 - enable_ipv6=true|false: Enable IPv6. Default is true. (Required for
1100 outbound_addr6).
1101 - outbound_addr=INTERFACE: Specify the outbound interface slirp
1102 should bind to (ipv4 traffic only).
1103 - outbound_addr=IPv4: Specify the outbound ipv4 address slirp should
1104 bind to.
1105 - outbound_addr6=INTERFACE: Specify the outbound interface slirp
1106 should bind to (ipv6 traffic only).
1107 - outbound_addr6=IPv6: Specify the outbound ipv6 address slirp should
1108 bind to.
1109 - port_handler=rootlesskit: Use rootlesskit for port forwarding. De‐
1110 fault.
1111 Note: Rootlesskit changes the source IP address of incoming packets
1112 to an IP address in the container network namespace, usually
1113 10.0.2.100. If your application requires the real source IP address,
1114 e.g. web server logs, use the slirp4netns port handler. The rootlesskit
1115 port handler is also used for rootless containers when connected to
1116 user-defined networks.
1117 - port_handler=slirp4netns: Use the slirp4netns port forwarding, it
1118 is slower than rootlesskit but preserves the correct source IP address.
1119 This port handler cannot be used for user-defined networks.
1120
1121
1122 Invalid if using --dns, --dns-option, or --dns-search with --network
1123 set to none or container:id.
1124
1125
1126 If used together with --pod, the container will not join the pod's net‐
1127 work namespace.
1128
1129
1130 --network-alias=alias
1131 Add a network-scoped alias for the container, setting the alias for all
1132 networks that the container joins. To set a name only for a specific
1133 network, use the alias option as described under the --network option.
1134 If the network has DNS enabled (podman network inspect -f {{.DNSEn‐
1135 abled}} <name>), these aliases can be used for name resolution on the
1136 given network. This option can be specified multiple times. NOTE: When
1137 using CNI a container will only have access to aliases on the first
1138 network that it joins. This limitation does not exist with ne‐
1139 tavark/aardvark-dns.
1140
1141
1142 --no-healthcheck
1143 Disable any defined healthchecks for container.
1144
1145
1146 --no-hosts
1147 Do not create /etc/hosts for the container. By default, Podman will
1148 manage /etc/hosts, adding the container's own IP address and any hosts
1149 from --add-host. --no-hosts disables this, and the image's /etc/hosts
1150 will be preserved unmodified.
1151
1152
1153 This option conflicts with --add-host.
1154
1155
1156 --oom-kill-disable
1157 Whether to disable OOM Killer for the container or not.
1158
1159
1160 This flag is not supported on cgroups V2 systems.
1161
1162
1163 --oom-score-adj=num
1164 Tune the host's OOM preferences for containers (accepts values from
1165 -1000 to 1000).
1166
1167
1168 --os=OS
1169 Override the OS, defaults to hosts, of the image to be pulled. For ex‐
1170 ample, windows. Unless overridden, subsequent lookups of the same im‐
1171 age in the local storage will match this OS, regardless of the host.
1172
1173
1174 --passwd-entry=ENTRY
1175 Customize the entry that is written to the /etc/passwd file within the
1176 container when --passwd is used.
1177
1178
1179 The variables $USERNAME, $UID, $GID, $NAME, $HOME are automatically re‐
1180 placed with their value at runtime.
1181
1182
1183 --personality=persona
1184 Personality sets the execution domain via Linux personality(2).
1185
1186
1187 --pid=mode
1188 Set the PID namespace mode for the container. The default is to create
1189 a private PID namespace for the container.
1190
1191
1192 • container:id: join another container's PID namespace;
1193
1194 • host: use the host's PID namespace for the container. Note the
1195 host mode gives the container full access to local PID and is
1196 therefore considered insecure;
1197
1198 • ns:path: join the specified PID namespace;
1199
1200 • private: create a new namespace for the container (default).
1201
1202
1203
1204 --pidfile=path
1205 When the pidfile location is specified, the container process' PID will
1206 be written to the pidfile. (This option is not available with the re‐
1207 mote Podman client, including Mac and Windows (excluding WSL2) ma‐
1208 chines) If the pidfile option is not specified, the container process'
1209 PID will be written to /run/containers/storage/${storage-driver}-con‐
1210 tainers/$CID/userdata/pidfile.
1211
1212
1213 After the container is started, the location for the pidfile can be
1214 discovered with the following podman inspect command:
1215
1216
1217 $ podman inspect --format '{{ .PidFile }}' $CID
1218 /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile
1219
1220
1221
1222 --pids-limit=limit
1223 Tune the container's pids limit. Set to -1 to have unlimited pids for
1224 the container. The default is 4096 on systems that support "pids"
1225 cgroup controller.
1226
1227
1228 --platform=OS/ARCH
1229 Specify the platform for selecting the image. (Conflicts with --arch
1230 and --os) The --platform option can be used to override the current ar‐
1231 chitecture and operating system. Unless overridden, subsequent lookups
1232 of the same image in the local storage will match this platform, re‐
1233 gardless of the host.
1234
1235
1236 --pod=name
1237 Run container in an existing pod. If you want Podman to make the pod
1238 for you, prefix the pod name with new:. To make a pod with more granu‐
1239 lar options, use the podman pod create command before creating a con‐
1240 tainer. If a container is run with a pod, and the pod has an infra-
1241 container, the infra-container will be started before the container is.
1242
1243
1244 --pod-id-file=file
1245 Run container in an existing pod and read the pod's ID from the speci‐
1246 fied file. If a container is run within a pod, and the pod has an in‐
1247 fra-container, the infra-container will be started before the container
1248 is.
1249
1250
1251 --privileged
1252 Give extended privileges to this container. The default is false.
1253
1254
1255 By default, Podman containers are unprivileged (=false) and cannot, for
1256 example, modify parts of the operating system. This is because by de‐
1257 fault a container is only allowed limited access to devices. A "privi‐
1258 leged" container is given the same access to devices as the user
1259 launching the container.
1260
1261
1262 A privileged container turns off the security features that isolate the
1263 container from the host. Dropped Capabilities, limited devices, read-
1264 only mount points, Apparmor/SELinux separation, and Seccomp filters are
1265 all disabled.
1266
1267
1268 Rootless containers cannot have more privileges than the account that
1269 launched them.
1270
1271
1272 --publish, -p=[[ip:][hostPort]:]containerPort[/protocol]
1273 Publish a container's port, or range of ports, to the host.
1274
1275
1276 Both hostPort and containerPort can be specified as a range of ports.
1277 When specifying ranges for both, the number of container ports in the
1278 range must match the number of host ports in the range.
1279
1280
1281 If host IP is set to 0.0.0.0 or not set at all, the port will be bound
1282 on all IPs on the host.
1283
1284
1285 By default, Podman will publish TCP ports. To publish a UDP port in‐
1286 stead, give udp as protocol. To publish both TCP and UDP ports, set
1287 --publish twice, with tcp, and udp as protocols respectively. Rootful
1288 containers can also publish ports using the sctp protocol.
1289
1290
1291 Host port does not have to be specified (e.g. podman run -p
1292 127.0.0.1::80). If it is not, the container port will be randomly as‐
1293 signed a port on the host.
1294
1295
1296 Use podman port to see the actual mapping: podman port $CONTAINER $CON‐
1297 TAINERPORT.
1298
1299
1300 Note: If a container will be run within a pod, it is not necessary to
1301 publish the port for the containers in the pod. The port must only be
1302 published by the pod itself. Pod network stacks act like the network
1303 stack on the host - you have a variety of containers in the pod, and
1304 programs in the container, all sharing a single interface and IP ad‐
1305 dress, and associated ports. If one container binds to a port, no other
1306 container can use that port within the pod while it is in use. Contain‐
1307 ers in the pod can also communicate over localhost by having one con‐
1308 tainer bind to localhost in the pod, and another connect to that port.
1309
1310
1311 --publish-all, -P
1312 Publish all exposed ports to random ports on the host interfaces. The
1313 default is false.
1314
1315
1316 When set to true, publish all exposed ports to the host interfaces. If
1317 the operator uses -P (or -p) then Podman will make the exposed port ac‐
1318 cessible on the host and the ports will be available to any client that
1319 can reach the host.
1320
1321
1322 When using this option, Podman will bind any exposed port to a random
1323 port on the host within an ephemeral port range defined by
1324 /proc/sys/net/ipv4/ip_local_port_range. To find the mapping between
1325 the host ports and the exposed ports, use podman port.
1326
1327
1328 --pull=policy
1329 Pull image policy. The default is missing.
1330
1331
1332 • always: Always pull the image and throw an error if the pull
1333 fails.
1334
1335 • missing: Pull the image only if it could not be found in the
1336 local containers storage. Throw an error if no image could be
1337 found and the pull fails.
1338
1339 • never: Never pull the image but use the one from the local
1340 containers storage. Throw an error if no image could be
1341 found.
1342
1343 • newer: Pull if the image on the registry is newer than the one
1344 in the local containers storage. An image is considered to be
1345 newer when the digests are different. Comparing the time
1346 stamps is prone to errors. Pull errors are suppressed if a
1347 local image was found.
1348
1349
1350
1351 --quiet, -q
1352 Suppress output information when pulling images
1353
1354
1355 --read-only
1356 Mount the container's root filesystem as read-only.
1357
1358
1359 By default a container will have its root filesystem writable allowing
1360 processes to write files anywhere. By specifying the --read-only flag,
1361 the container will have its root filesystem mounted as read-only pro‐
1362 hibiting any writes.
1363
1364
1365 --read-only-tmpfs
1366 If container is running in --read-only mode, then mount a read-write
1367 tmpfs on /run, /tmp, and /var/tmp. The default is true.
1368
1369
1370 --replace
1371 If another container with the same name already exists, replace and re‐
1372 move it. The default is false.
1373
1374
1375 --requires=container
1376 Specify one or more requirements. A requirement is a dependency con‐
1377 tainer that will be started before this container. Containers can be
1378 specified by name or ID, with multiple containers being separated by
1379 commas.
1380
1381
1382 --restart=policy
1383 Restart policy to follow when containers exit. Restart policy will not
1384 take effect if a container is stopped via the podman kill or podman
1385 stop commands.
1386
1387
1388 Valid policy values are:
1389
1390
1391 • no : Do not restart containers on exit
1392
1393 • on-failure[:max_retries] : Restart containers when they exit
1394 with a non-zero exit code, retrying indefinitely or until the
1395 optional max_retries count is hit
1396
1397 • always : Restart containers when they exit,
1398 regardless of status, retrying indefinitely
1399
1400 • unless-stopped : Identical to always
1401
1402
1403
1404 Please note that restart will not restart containers after a system re‐
1405 boot. If this functionality is required in your environment, you can
1406 invoke Podman from a systemd.unit(5) file, or create an init script for
1407 whichever init system is in use. To generate systemd unit files,
1408 please see podman generate systemd.
1409
1410
1411 --rm
1412 Automatically remove the container when it exits. The default is false.
1413
1414
1415 --rootfs
1416 If specified, the first argument refers to an exploded container on the
1417 file system.
1418
1419
1420 This is useful to run a container without requiring any image manage‐
1421 ment, the rootfs of the container is assumed to be managed externally.
1422
1423
1424 Overlay Rootfs Mounts
1425
1426
1427 The :O flag tells Podman to mount the directory from the rootfs path as
1428 storage using the overlay file system. The container processes can mod‐
1429 ify content within the mount point which is stored in the container
1430 storage in a separate directory. In overlay terms, the source directory
1431 will be the lower, and the container storage directory will be the up‐
1432 per. Modifications to the mount point are destroyed when the container
1433 finishes executing, similar to a tmpfs mount point being unmounted.
1434
1435
1436 Note: On SELinux systems, the rootfs needs the correct label, which is
1437 by default unconfined_u:object_r:container_file_t:s0.
1438
1439
1440 --sdnotify=container | conmon | ignore
1441 Determines how to use the NOTIFY_SOCKET, as passed with systemd and
1442 Type=notify.
1443
1444
1445 Default is container, which means allow the OCI runtime to proxy the
1446 socket into the container to receive ready notification. Podman will
1447 set the MAINPID to conmon's pid. The conmon option sets MAINPID to
1448 conmon's pid, and sends READY when the container has started. The
1449 socket is never passed to the runtime or the container. The ignore op‐
1450 tion removes NOTIFY_SOCKET from the environment for itself and child
1451 processes, for the case where some other process above Podman uses NO‐
1452 TIFY_SOCKET and Podman should not use it.
1453
1454
1455 --seccomp-policy=policy
1456 Specify the policy to select the seccomp profile. If set to image, Pod‐
1457 man will look for a "io.containers.seccomp.profile" label in the con‐
1458 tainer-image config and use its value as a seccomp profile. Otherwise,
1459 Podman will follow the default policy by applying the default profile
1460 unless specified otherwise via --security-opt seccomp as described be‐
1461 low.
1462
1463
1464 Note that this feature is experimental and may change in the future.
1465
1466
1467 --secret=secret[,opt=opt ...]
1468 Give the container access to a secret. Can be specified multiple times.
1469
1470
1471 A secret is a blob of sensitive data which a container needs at runtime
1472 but should not be stored in the image or in source control, such as
1473 usernames and passwords, TLS certificates and keys, SSH keys or other
1474 important generic strings or binary content (up to 500 kb in size).
1475
1476
1477 When secrets are specified as type mount, the secrets are copied and
1478 mounted into the container when a container is created. When secrets
1479 are specified as type env, the secret will be set as an environment
1480 variable within the container. Secrets are written in the container at
1481 the time of container creation, and modifying the secret using podman
1482 secret commands after the container is created will not affect the se‐
1483 cret inside the container.
1484
1485
1486 Secrets and its storage are managed using the podman secret command.
1487
1488
1489 Secret Options
1490
1491
1492 • type=mount|env : How the secret will be exposed to the con‐
1493 tainer. Default mount.
1494
1495 • target=target : Target of secret. Defaults to secret name.
1496
1497 • uid=0 : UID of secret. Defaults to 0. Mount secret
1498 type only.
1499
1500 • gid=0 : GID of secret. Defaults to 0. Mount secret
1501 type only.
1502
1503 • mode=0 : Mode of secret. Defaults to 0444. Mount
1504 secret type only.
1505
1506
1507
1508 --security-opt=option
1509 Security Options
1510
1511
1512 • apparmor=unconfined : Turn off apparmor confinement for the
1513 container
1514
1515 • apparmor=your-profile : Set the apparmor confinement profile
1516 for the container
1517
1518 • label=user:USER : Set the label user for the container
1519 processes
1520
1521 • label=role:ROLE : Set the label role for the container
1522 processes
1523
1524 • label=type:TYPE : Set the label process type for the con‐
1525 tainer processes
1526
1527 • label=level:LEVEL : Set the label level for the container
1528 processes
1529
1530 • label=filetype:TYPE : Set the label file type for the con‐
1531 tainer files
1532
1533 • label=disable : Turn off label separation for the con‐
1534 tainer
1535
1536
1537
1538 Note: Labeling can be disabled for all containers by setting la‐
1539 bel=false in the containers.conf (/etc/containers/containers.conf or
1540 $HOME/.config/containers/containers.conf) file.
1541
1542
1543 • mask=/path/1:/path/2 : The paths to mask separated by a colon.
1544 A masked path cannot be accessed inside the container.
1545
1546 • no-new-privileges : Disable container processes from gaining
1547 additional privileges
1548
1549 • seccomp=unconfined : Turn off seccomp confinement for the con‐
1550 tainer.
1551
1552 • seccomp=profile.json : JSON file to be used as a seccomp fil‐
1553 ter. Note that the io.podman.annotations.seccomp annotation is
1554 set with the specified value as shown in podman inspect.
1555
1556 • proc-opts=OPTIONS : Comma-separated list of options to use for
1557 the /proc mount. More details for the possible mount options
1558 are specified in the proc(5) man page.
1559
1560 • unmask=ALL or /path/1:/path/2, or shell expanded paths
1561 (/proc/*): Paths to unmask separated by a colon. If set to
1562 ALL, it will unmask all the paths that are masked or made
1563 read-only by default. The default masked paths are
1564 /proc/acpi, /proc/kcore, /proc/keys, /proc/latency_stats,
1565 /proc/sched_debug, /proc/scsi, /proc/timer_list,
1566 /proc/timer_stats, /sys/firmware, and /sys/fs/selinux. The
1567 default paths that are read-only are /proc/asound, /proc/bus,
1568 /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trigger,
1569 /sys/fs/cgroup.
1570
1571
1572
1573 Note: Labeling can be disabled for all containers by setting la‐
1574 bel=false in the containers.conf (/etc/containers/containers.conf or
1575 $HOME/.config/containers/containers.conf) file.
1576
1577
1578 --shm-size=number[unit]
1579 Size of /dev/shm. A unit can be b (bytes), k (kibibytes), m
1580 (mebibytes), or g (gibibytes). If the unit is omitted, the system uses
1581 bytes. If the size is omitted, the default is 64m. When size is 0,
1582 there is no limit on the amount of memory used for IPC by the con‐
1583 tainer. This option conflicts with --ipc=host.
1584
1585
1586 --stop-signal=signal
1587 Signal to stop a container. Default is SIGTERM.
1588
1589
1590 --stop-timeout=seconds
1591 Timeout to stop a container. Default is 10. Remote connections use lo‐
1592 cal containers.conf for defaults
1593
1594
1595 --subgidname=name
1596 Run the container in a new user namespace using the map with name in
1597 the /etc/subgid file. If running rootless, the user needs to have the
1598 right to use the mapping. See subgid(5). This flag conflicts with
1599 --userns and --gidmap.
1600
1601
1602 --subuidname=name
1603 Run the container in a new user namespace using the map with name in
1604 the /etc/subuid file. If running rootless, the user needs to have the
1605 right to use the mapping. See subuid(5). This flag conflicts with
1606 --userns and --uidmap.
1607
1608
1609 --sysctl=name=value
1610 Configure namespaced kernel parameters at runtime.
1611
1612
1613 For the IPC namespace, the following sysctls are allowed:
1614
1615
1616 • kernel.msgmax
1617
1618 • kernel.msgmnb
1619
1620 • kernel.msgmni
1621
1622 • kernel.sem
1623
1624 • kernel.shmall
1625
1626 • kernel.shmmax
1627
1628 • kernel.shmmni
1629
1630 • kernel.shm_rmid_forced
1631
1632 • Sysctls beginning with fs.mqueue.*
1633
1634
1635
1636 Note: if you use the --ipc=host option, the above sysctls are not al‐
1637 lowed.
1638
1639
1640 For the network namespace, only sysctls beginning with net.* are al‐
1641 lowed.
1642
1643
1644 Note: if you use the --network=host option, the above sysctls are not
1645 allowed.
1646
1647
1648 --systemd=true | false | always
1649 Run container in systemd mode. The default is true.
1650
1651
1652 The value always enforces the systemd mode is enforced without looking
1653 at the executable name. Otherwise, if set to true and the command you
1654 are running inside the container is systemd, /usr/sbin/init, /sbin/init
1655 or /usr/local/sbin/init.
1656
1657
1658 Running the container in systemd mode causes the following changes:
1659
1660
1661 • Podman mounts tmpfs file systems on the following directories
1662
1663 • /run
1664
1665 • /run/lock
1666
1667 • /tmp
1668
1669 • /sys/fs/cgroup/systemd
1670
1671 • /var/lib/journal
1672
1673
1674
1675 • Podman sets the default stop signal to SIGRTMIN+3.
1676
1677 • Podman sets container_uuid environment variable in the con‐
1678 tainer to the first 32 characters of the container id.
1679
1680
1681
1682 This allows systemd to run in a confined container without any modifi‐
1683 cations.
1684
1685
1686 Note that on SELinux systems, systemd attempts to write to the cgroup
1687 file system. Containers writing to the cgroup file system are denied by
1688 default. The container_manage_cgroup boolean must be enabled for this
1689 to be allowed on an SELinux separated system.
1690
1691
1692 setsebool -P container_manage_cgroup true
1693
1694
1695
1696 --timeout=seconds
1697 Maximum time a container is allowed to run before conmon sends it the
1698 kill signal. By default containers will run until they exit or are
1699 stopped by podman stop.
1700
1701
1702 --tls-verify
1703 Require HTTPS and verify certificates when contacting registries (de‐
1704 fault: true). If explicitly set to true, TLS verification will be
1705 used. If set to false, TLS verification will not be used. If not
1706 specified, TLS verification will be used unless the target registry is
1707 listed as an insecure registry in containers-registries.conf(5)
1708
1709
1710 --tmpfs=fs
1711 Create a tmpfs mount.
1712
1713
1714 Mount a temporary filesystem (tmpfs) mount into a container, for exam‐
1715 ple:
1716
1717
1718 $ podman create -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
1719
1720
1721
1722 This command mounts a tmpfs at /tmp within the container. The supported
1723 mount options are the same as the Linux default mount flags. If you do
1724 not specify any options, the system uses the following options:
1725 rw,noexec,nosuid,nodev.
1726
1727
1728 --tty, -t
1729 Allocate a pseudo-TTY. The default is false.
1730
1731
1732 When set to true, Podman will allocate a pseudo-tty and attach to the
1733 standard input of the container. This can be used, for example, to run
1734 a throwaway interactive shell.
1735
1736
1737 NOTE: The --tty flag prevents redirection of standard output. It com‐
1738 bines STDOUT and STDERR, it can insert control characters, and it can
1739 hang pipes. This option should only be used when run interactively in a
1740 terminal. When feeding input to Podman, use -i only, not -it.
1741
1742
1743 --tz=timezone
1744 Set timezone in container. This flag takes area-based timezones, GMT
1745 time, as well as local, which sets the timezone in the container to
1746 match the host machine. See /usr/share/zoneinfo/ for valid timezones.
1747 Remote connections use local containers.conf for defaults
1748
1749
1750 --uidmap=container_uid:from_uid:amount
1751 Run the container in a new user namespace using the supplied UID map‐
1752 ping. This option conflicts with the --userns and --subuidname options.
1753 This option provides a way to map host UIDs to container UIDs. It can
1754 be passed several times to map different ranges.
1755
1756
1757 The _fromuid value is based upon the user running the command, either
1758 rootful or rootless users. * rootful user: con‐
1759 tainer_uid:host_uid:amount * rootless user: container_uid:intermedi‐
1760 ate_uid:amount
1761
1762
1763 When podman create is called by a privileged user, the option --uidmap
1764 works as a direct mapping between host UIDs and container UIDs.
1765
1766
1767 host UID -> container UID
1768
1769
1770 The amount specifies the number of consecutive UIDs that will be
1771 mapped. If for example amount is 4 the mapping would look like:
1772
1773
1774 | host UID | container UID | | - | -
1775 | | _fromuid | _containeruid | | _fromuid + 1 | _containeruid +
1776 1 | | _fromuid + 2 | _containeruid + 2 | | _fromuid + 3 | _containeruid
1777 + 3 |
1778
1779
1780 When podman create is called by an unprivileged user (i.e. running
1781 rootless), the value _fromuid is interpreted as an "intermediate UID".
1782 In the rootless case, host UIDs are not mapped directly to container
1783 UIDs. Instead the mapping happens over two mapping steps:
1784
1785
1786 host UID -> intermediate UID -> container UID
1787
1788
1789 The --uidmap option only influences the second mapping step.
1790
1791
1792 The first mapping step is derived by Podman from the contents of the
1793 file /etc/subuid and the UID of the user calling Podman.
1794
1795
1796 First mapping step:
1797
1798
1799 | host UID | intermediate UID |
1800 | - | - |
1801 | UID for the user starting Podman | 0 |
1802 | 1st subordinate UID for the user starting Podman | 1 |
1803 | 2nd subordinate UID for the user starting Podman | 2 |
1804 | 3rd subordinate UID for the user starting Podman | 3 |
1805 | nth subordinate UID for the user starting Podman | n |
1806
1807
1808 To be able to use intermediate UIDs greater than zero, the user needs
1809 to have subordinate UIDs configured in /etc/subuid. See subuid(5).
1810
1811
1812 The second mapping step is configured with --uidmap.
1813
1814
1815 If for example amount is 5 the second mapping step would look like:
1816
1817
1818 | intermediate UID | container UID | | - |
1819 - | | _fromuid | _containeruid | |
1820 _fromuid + 1 | _containeruid + 1 | | _fromuid + 2 | _con‐
1821 taineruid + 2 | | _fromuid + 3 | _containeruid + 3 | | _fromuid +
1822 4 | _containeruid + 4 |
1823
1824
1825 When running as rootless, Podman will use all the ranges configured in
1826 the /etc/subuid file.
1827
1828
1829 The current user ID is mapped to UID=0 in the rootless user namespace.
1830 Every additional range is added sequentially afterward:
1831
1832
1833 | host |rootless user namespace | length
1834 | | - | - | -
1835 | | $UID | 0 | 1
1836 | | 1 | $FIRST_RANGE_ID |
1837 $FIRST_RANGE_LENGTH | | 1+$FIRST_RANGE_LENGTH | $SECOND_RANGE_ID
1838 | $SECOND_RANGE_LENGTH|
1839
1840
1841 Even if a user does not have any subordinate UIDs in /etc/subuid,
1842 --uidmap could still be used to map the normal UID of the user to a
1843 container UID by running podman create --uidmap $container_uid:0:1
1844 --user $container_uid ....
1845
1846
1847 Note: the --uidmap flag cannot be called in conjunction with the --pod
1848 flag as a uidmap cannot be set on the container level when in a pod.
1849
1850
1851 --ulimit=option
1852 Ulimit options. You can use host to copy the current configuration from
1853 the host.
1854
1855
1856 --umask=umask
1857 Set the umask inside the container. Defaults to 0022. Remote connec‐
1858 tions use local containers.conf for defaults
1859
1860
1861 --unsetenv=env
1862 Unset default environment variables for the container. Default environ‐
1863 ment variables include variables provided natively by Podman, environ‐
1864 ment variables configured by the image, and environment variables from
1865 containers.conf.
1866
1867
1868 --unsetenv-all
1869 Unset all default environment variables for the container. Default en‐
1870 vironment variables include variables provided natively by Podman, en‐
1871 vironment variables configured by the image, and environment variables
1872 from containers.conf.
1873
1874
1875 --user, -u=user[:group]
1876 Sets the username or UID used and, optionally, the groupname or GID for
1877 the specified command. Both user and group may be symbolic or numeric.
1878
1879
1880 Without this argument, the command will run as the user specified in
1881 the container image. Unless overridden by a USER command in the Con‐
1882 tainerfile or by a value passed to this option, this user generally de‐
1883 faults to root.
1884
1885
1886 When a user namespace is not in use, the UID and GID used within the
1887 container and on the host will match. When user namespaces are in use,
1888 however, the UID and GID in the container may correspond to another UID
1889 and GID on the host. In rootless containers, for example, a user name‐
1890 space is always used, and root in the container will by default corre‐
1891 spond to the UID and GID of the user invoking Podman.
1892
1893
1894 --userns=mode
1895 Set the user namespace mode for the container. It defaults to the POD‐
1896 MAN_USERNS environment variable. An empty value ("") means user name‐
1897 spaces are disabled unless an explicit mapping is set with the --uidmap
1898 and --gidmap options.
1899
1900
1901 This option is incompatible with --gidmap, --uidmap, --subuidname and
1902 --subgidname.
1903
1904
1905 Rootless user --userns=Key mappings:
1906
1907
1908 ┌────────┬───────────┬─────────────────────┐
1909 │Key │ Host User │ Container User │
1910 ├────────┼───────────┼─────────────────────┤
1911 │"" │ $UID │ 0 (Default User ac‐ │
1912 │ │ │ count mapped to │
1913 │ │ │ root user in con‐ │
1914 │ │ │ tainer.) │
1915 ├────────┼───────────┼─────────────────────┤
1916 │keep-id │ $UID │ $UID (Map user ac‐ │
1917 │ │ │ count to same UID │
1918 │ │ │ within container.) │
1919 ├────────┼───────────┼─────────────────────┤
1920 │auto │ $UID │ nil (Host User UID │
1921 │ │ │ is not mapped into │
1922 │ │ │ container.) │
1923 ├────────┼───────────┼─────────────────────┤
1924 │nomap │ $UID │ nil (Host User UID │
1925 │ │ │ is not mapped into │
1926 │ │ │ container.) │
1927 └────────┴───────────┴─────────────────────┘
1928
1929 Valid mode values are:
1930
1931
1932 auto[:OPTIONS,...]: automatically create a unique user namespace.
1933
1934
1935 The --userns=auto flag, requires that the user name containers and a
1936 range of subordinate user ids that the Podman container is allowed to
1937 use be specified in the /etc/subuid and /etc/subgid files.
1938
1939
1940 Example: containers:2147483647:2147483648.
1941
1942
1943 Podman allocates unique ranges of UIDs and GIDs from the containers
1944 subordinate user ids. The size of the ranges is based on the number of
1945 UIDs required in the image. The number of UIDs and GIDs can be overrid‐
1946 den with the size option.
1947
1948
1949 The rootless option --userns=keep-id uses all the subuids and subgids
1950 of the user. Using --userns=auto when starting new containers will not
1951 work as long as any containers exist that were started with
1952 --userns=keep-id.
1953
1954
1955 Valid auto options:
1956
1957
1958 • gidmapping=_CONTAINER_GID:HOSTGID:SIZE: to force a GID mapping
1959 to be present in the user namespace.
1960
1961 • size=SIZE: to specify an explicit size for the automatic user
1962 namespace. e.g. --userns=auto:size=8192. If size is not speci‐
1963 fied, auto will estimate a size for the user namespace.
1964
1965 • uidmapping=_CONTAINER_UID:HOSTUID:SIZE: to force a UID mapping
1966 to be present in the user namespace.
1967
1968
1969
1970 container:id: join the user namespace of the specified container.
1971
1972
1973 host: run in the user namespace of the caller. The processes running in
1974 the container will have the same privileges on the host as any other
1975 process launched by the calling user (default).
1976
1977
1978 keep-id: creates a user namespace where the current rootless user's
1979 UID:GID are mapped to the same values in the container. This option is
1980 not allowed for containers created by the root user.
1981
1982
1983 Valid keep-id options:
1984
1985
1986 • uid=UID: override the UID inside the container that will be
1987 used to map the current rootless user to.
1988
1989 • gid=GID: override the GID inside the container that will be
1990 used to map the current rootless user to.
1991
1992
1993
1994 nomap: creates a user namespace where the current rootless user's
1995 UID:GID are not mapped into the container. This option is not allowed
1996 for containers created by the root user.
1997
1998
1999 ns:namespace: run the container in the given existing user namespace.
2000
2001
2002 --uts=mode
2003 Set the UTS namespace mode for the container. The following values are
2004 supported:
2005
2006
2007 • host: use the host's UTS namespace inside the container.
2008
2009 • private: create a new namespace for the container (default).
2010
2011 • ns:[path]: run the container in the given existing UTS name‐
2012 space.
2013
2014 • container:[container]: join the UTS namespace of the specified
2015 container.
2016
2017
2018
2019 --variant=VARIANT
2020 Use VARIANT instead of the default architecture variant of the con‐
2021 tainer image. Some images can use multiple variants of the arm archi‐
2022 tectures, such as arm/v5 and arm/v7.
2023
2024
2025 --volume, -v=[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]
2026 Create a bind mount. If -v /HOST-DIR:/CONTAINER-DIR is specified, Pod‐
2027 man bind mounts /HOST-DIR from the host into /CONTAINER-DIR in the Pod‐
2028 man container. Similarly, -v SOURCE-VOLUME:/CONTAINER-DIR will mount
2029 the named volume from the host into the container. If no such named
2030 volume exists, Podman will create one. If no source is given, the vol‐
2031 ume will be created as an anonymously named volume with a randomly gen‐
2032 erated name, and will be removed when the container is removed via the
2033 --rm flag or the podman rm --volumes command.
2034
2035
2036 (Note when using the remote client, including Mac and Windows (exclud‐
2037 ing WSL2) machines, the volumes will be mounted from the remote server,
2038 not necessarily the client machine.)
2039
2040
2041 The OPTIONS is a comma-separated list and can be: [1] ⟨#Footnote1⟩
2042
2043
2044 • rw|ro
2045
2046 • z|Z
2047
2048 • [O]
2049
2050 • [U]
2051
2052 • [no]copy
2053
2054 • [no]dev
2055
2056 • [no]exec
2057
2058 • [no]suid
2059
2060 • [r]bind
2061
2062 • [r]shared|[r]slave|[r]private[r]unbindable
2063
2064
2065
2066 The CONTAINER-DIR must be an absolute path such as /src/docs. The vol‐
2067 ume will be mounted into the container at this directory.
2068
2069
2070 If a volume source is specified, it must be a path on the host or the
2071 name of a named volume. Host paths are allowed to be absolute or rela‐
2072 tive; relative paths are resolved relative to the directory Podman is
2073 run in. If the source does not exist, Podman will return an error.
2074 Users must pre-create the source files or directories.
2075
2076
2077 Any source that does not begin with a . or / will be treated as the
2078 name of a named volume. If a volume with that name does not exist, it
2079 will be created. Volumes created with names are not anonymous, and
2080 they are not removed by the --rm option and the podman rm --volumes
2081 command.
2082
2083
2084 Specify multiple -v options to mount one or more volumes into a con‐
2085 tainer.
2086
2087
2088 Write Protected Volume Mounts
2089
2090
2091 Add :ro or :rw option to mount a volume in read-only or read-write
2092 mode, respectively. By default, the volumes are mounted read-write.
2093 See examples.
2094
2095
2096 Chowning Volume Mounts
2097
2098
2099 By default, Podman does not change the owner and group of source volume
2100 directories mounted into containers. If a container is created in a new
2101 user namespace, the UID and GID in the container may correspond to an‐
2102 other UID and GID on the host.
2103
2104
2105 The :U suffix tells Podman to use the correct host UID and GID based on
2106 the UID and GID within the container, to change recursively the owner
2107 and group of the source volume.
2108
2109
2110 Warning use with caution since this will modify the host filesystem.
2111
2112
2113 Labeling Volume Mounts
2114
2115
2116 Labeling systems like SELinux require that proper labels are placed on
2117 volume content mounted into a container. Without a label, the security
2118 system might prevent the processes running inside the container from
2119 using the content. By default, Podman does not change the labels set by
2120 the OS.
2121
2122
2123 To change a label in the container context, add either of two suffixes
2124 :z or :Z to the volume mount. These suffixes tell Podman to relabel
2125 file objects on the shared volumes. The z option tells Podman that two
2126 containers share the volume content. As a result, Podman labels the
2127 content with a shared content label. Shared volume labels allow all
2128 containers to read/write content. The Z option tells Podman to label
2129 the content with a private unshared label. Only the current container
2130 can use a private volume.
2131
2132
2133 Note: Do not relabel system files and directories. Relabeling system
2134 content might cause other confined services on your machine to fail.
2135 For these types of containers we recommend disabling SELinux separa‐
2136 tion. The option --security-opt label=disable disables SELinux separa‐
2137 tion for the container. For example if a user wanted to volume mount
2138 their entire home directory into a container, they need to disable
2139 SELinux separation.
2140
2141
2142 $ podman create --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file
2143
2144
2145
2146 Overlay Volume Mounts
2147
2148
2149 The :O flag tells Podman to mount the directory from the host as a tem‐
2150 porary storage using the overlay file system. The container processes
2151 can modify content within the mountpoint which is stored in the con‐
2152 tainer storage in a separate directory. In overlay terms, the source
2153 directory will be the lower, and the container storage directory will
2154 be the upper. Modifications to the mount point are destroyed when the
2155 container finishes executing, similar to a tmpfs mount point being un‐
2156 mounted.
2157
2158
2159 For advanced users, the overlay option also supports custom non-
2160 volatile upperdir and workdir for the overlay mount. Custom upperdir
2161 and workdir can be fully managed by the users themselves, and Podman
2162 will not remove it on lifecycle completion. Example :O,up‐
2163 perdir=/some/upper,workdir=/some/work
2164
2165
2166 Subsequent executions of the container will see the original source di‐
2167 rectory content, any changes from previous container executions no
2168 longer exist.
2169
2170
2171 One use case of the overlay mount is sharing the package cache from the
2172 host into the container to allow speeding up builds.
2173
2174
2175 Note:
2176
2177
2178 - The `O` flag conflicts with other options listed above.
2179
2180
2181
2182 Content mounted into the container is labeled with the private label.
2183 On SELinux systems, labels in the source directory must be read‐
2184 able by the container label. Usually containers can read/execute con‐
2185 tainer_share_t and can read/write container_file_t. If unable to change
2186 the labels on a source volume, SELinux container separation must be
2187 disabled for the container to work.
2188 - The source directory mounted into the container with an overlay
2189 mount should not be modified, it can cause unexpected failures. It is
2190 recommended to not modify the directory until the container finishes
2191 running.
2192
2193
2194 Mounts propagation
2195
2196
2197 By default bind mounted volumes are private. That means any mounts done
2198 inside the container will not be visible on host and vice versa. One
2199 can change this behavior by specifying a volume mount propagation prop‐
2200 erty. Making a volume shared mounts done under that volume inside the
2201 container will be visible on host and vice versa. Making a volume slave
2202 enables only one way mount propagation and that is mounts done on host
2203 under that volume will be visible inside container but not the other
2204 way around. [1] ⟨#Footnote1⟩
2205
2206
2207 To control mount propagation property of a volume one can use the
2208 [r]shared, [r]slave, [r]private or the [r]unbindable propagation flag.
2209 Propagation property can be specified only for bind mounted volumes and
2210 not for internal volumes or named volumes. For mount propagation to
2211 work the source mount point (the mount point where source dir is
2212 mounted on) has to have the right propagation properties. For shared
2213 volumes, the source mount point has to be shared. And for slave vol‐
2214 umes, the source mount point has to be either shared or slave. [1]
2215 ⟨#Footnote1⟩
2216
2217
2218 To recursively mount a volume and all of its submounts into a con‐
2219 tainer, use the rbind option. By default the bind option is used, and
2220 submounts of the source directory will not be mounted into the con‐
2221 tainer.
2222
2223
2224 Mounting the volume with the nosuid options means that SUID applica‐
2225 tions on the volume will not be able to change their privilege. By de‐
2226 fault volumes are mounted with nosuid.
2227
2228
2229 Mounting the volume with the noexec option means that no executables on
2230 the volume will be able to be executed within the container.
2231
2232
2233 Mounting the volume with the nodev option means that no devices on the
2234 volume will be able to be used by processes within the container. By
2235 default volumes are mounted with nodev.
2236
2237
2238 If the HOST-DIR is a mount point, then dev, suid, and exec options are
2239 ignored by the kernel.
2240
2241
2242 Use df HOST-DIR to figure out the source mount, then use findmnt -o
2243 TARGET,PROPAGATION source-mount-dir to figure out propagation proper‐
2244 ties of source mount. If findmnt[4m(1) utility is not available, then one
2245 can look at the mount entry for the source mount point in
2246 /proc/self/mountinfo. Look at the "optional fields" and see if any
2247 propagation properties are specified. In there, shared:N means the
2248 mount is shared, master:N means mount is slave, and if nothing is
2249 there, the mount is private. [1] ⟨#Footnote1⟩
2250
2251
2252 To change propagation properties of a mount point, use mount(8) com‐
2253 mand. For example, if one wants to bind mount source directory /foo,
2254 one can do mount --bind /foo /foo and mount --make-private --make-
2255 shared /foo. This will convert /foo into a shared mount point. Alterna‐
2256 tively, one can directly change propagation properties of source mount.
2257 Say / is source mount for /foo, then use mount --make-shared / to con‐
2258 vert / into a shared mount.
2259
2260
2261 Note: if the user only has access rights via a group, accessing the
2262 volume from inside a rootless container will fail.
2263
2264
2265 Use the --group-add keep-groups option to pass the user's supplementary
2266 group access into the container.
2267
2268
2269 --volumes-from=CONTAINER[:OPTIONS]
2270 Mount volumes from the specified container(s). Used to share volumes
2271 between containers. The options is a comma-separated list with the fol‐
2272 lowing available elements:
2273
2274
2275 • rw|ro
2276
2277 • z
2278
2279
2280
2281 Mounts already mounted volumes from a source container onto another
2282 container. CONTAINER may be a name or ID. To share a volume, use the
2283 --volumes-from option when running the target container. Volumes can be
2284 shared even if the source container is not running.
2285
2286
2287 By default, Podman mounts the volumes in the same mode (read-write or
2288 read-only) as it is mounted in the source container. This can be
2289 changed by adding a ro or rw option.
2290
2291
2292 Labeling systems like SELinux require that proper labels are placed on
2293 volume content mounted into a container. Without a label, the security
2294 system might prevent the processes running inside the container from
2295 using the content. By default, Podman does not change the labels set by
2296 the OS.
2297
2298
2299 To change a label in the container context, add z to the volume mount.
2300 This suffix tells Podman to relabel file objects on the shared volumes.
2301 The z option tells Podman that two entities share the volume content.
2302 As a result, Podman labels the content with a shared content label.
2303 Shared volume labels allow all containers to read/write content.
2304
2305
2306 If the location of the volume from the source container overlaps with
2307 data residing on a target container, then the volume hides that data on
2308 the target.
2309
2310
2311 --workdir, -w=dir
2312 Working directory inside the container.
2313
2314
2315 The default working directory for running binaries within a container
2316 is the root directory (/). The image developer can set a different de‐
2317 fault with the WORKDIR instruction. The operator can override the work‐
2318 ing directory by using the -w option.
2319
2320
2322 Create a container using a local image
2323 $ podman create alpine ls
2324
2325
2326
2327 Create a container using a local image and annotate it
2328 $ podman create --annotation HELLO=WORLD alpine ls
2329
2330
2331
2332 Create a container using a local image, allocating a pseudo-TTY, keeping
2333 stdin open and name it myctr
2334 podman create -t -i --name myctr alpine ls
2335
2336
2337
2338 Set UID/GID mapping in a new user namespace
2339 Running a container in a new user namespace requires a mapping of the
2340 uids and gids from the host.
2341
2342
2343 $ podman create --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
2344
2345
2346
2347 Setting automatic user namespace separated containers
2348 # podman create --userns=auto:size=65536 ubi8-init
2349
2350
2351
2352 Configure timezone in a container
2353 $ podman create --tz=local alpine date
2354 $ podman create --tz=Asia/Shanghai alpine date
2355 $ podman create --tz=US/Eastern alpine date
2356
2357
2358
2359 Adding dependency containers
2360 Podman will make sure the first container, container1, is running be‐
2361 fore the second container (container2) is started.
2362
2363
2364 $ podman create --name container1 -t -i fedora bash
2365 $ podman create --name container2 --requires container1 -t -i fedora bash
2366 $ podman start --attach container2
2367
2368
2369
2370 Multiple containers can be required.
2371
2372
2373 $ podman create --name container1 -t -i fedora bash
2374 $ podman create --name container2 -t -i fedora bash
2375 $ podman create --name container3 --requires container1,container2 -t -i fedora bash
2376 $ podman start --attach container3
2377
2378
2379
2380 Configure keep supplemental groups for access to volume
2381 $ podman create -v /var/lib/design:/var/lib/design --group-add keep-groups ubi8
2382
2383
2384
2385 Configure execution domain for containers using personality flag
2386 $ podman create --name container1 --personality=LINUX32 fedora bash
2387
2388
2389
2390 Create a container with external rootfs mounted as an overlay
2391 $ podman create --name container1 --rootfs /path/to/rootfs:O bash
2392
2393
2394
2395 Create a container connected to two networks (called net1 and net2) with a
2396 static ip
2397 $ podman create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip addr
2398
2399
2400
2401 Rootless Containers
2402 Podman runs as a non-root user on most systems. This feature requires
2403 that a new enough version of shadow-utils be installed. The shadow-
2404 utils package must include the newuidmap and newgidmap executables.
2405
2406
2407 In order for users to run rootless, there must be an entry for their
2408 username in /etc/subuid and /etc/subgid which lists the UIDs for their
2409 user namespace.
2410
2411
2412 Rootless Podman works better if the fuse-overlayfs and slirp4netns
2413 packages are installed. The fuse-overlayfs package provides a
2414 userspace overlay storage driver, otherwise users need to use the vfs
2415 storage driver, which is diskspace expensive and does not perform well.
2416 slirp4netns is required for VPN, without it containers need to be run
2417 with the --network=host flag.
2418
2419
2421 Environment variables within containers can be set using multiple dif‐
2422 ferent options: This section describes the precedence.
2423
2424
2425 Precedence order (later entries override earlier entries):
2426
2427
2428 • --env-host : Host environment of the process executing Podman
2429 is added.
2430
2431 • --http-proxy: By default, several environment variables will
2432 be passed in from the host, such as http_proxy and no_proxy.
2433 See --http-proxy for details.
2434
2435 • Container image : Any environment variables specified in the
2436 container image.
2437
2438 • --env-file : Any environment variables specified via env-
2439 files. If multiple files specified, then they override each
2440 other in order of entry.
2441
2442 • --env : Any environment variables specified will override pre‐
2443 vious settings.
2444
2445
2446
2447 Create containers and set the environment ending with a *. The trail‐
2448 ing * glob functionality is only active when no value is specified:
2449
2450
2451 $ export ENV1=a
2452 $ podman create --name ctr1 --env 'ENV*' alpine env
2453 $ podman start --attach ctr1 | grep ENV
2454 ENV1=a
2455 $ podman create --name ctr2 --env 'ENV*=b' alpine env
2456 $ podman start --attach ctr2 | grep ENV
2457 ENV*=b
2458
2459
2460
2462 When Podman starts a container it actually executes the conmon program,
2463 which then executes the OCI Runtime. Conmon is the container monitor.
2464 It is a small program whose job is to watch the primary process of the
2465 container, and if the container dies, save the exit code. It also
2466 holds open the tty of the container, so that it can be attached to
2467 later. This is what allows Podman to run in detached mode (back‐
2468 grounded), so Podman can exit but conmon continues to run. Each con‐
2469 tainer has their own instance of conmon. Conmon waits for the container
2470 to exit, gathers and saves the exit code, and then launches a Podman
2471 process to complete the container cleanup, by shutting down the network
2472 and storage. For more information on conmon, please reference the
2473 conmon(8) man page.
2474
2475
2477 /etc/subuid /etc/subgid
2478
2479
2480 NOTE: Use the environment variable TMPDIR to change the temporary stor‐
2481 age location of downloaded container images. Podman defaults to use
2482 /var/tmp.
2483
2484
2486 podman(1), podman-save(1), podman-ps(1), podman-attach(1), podman-pod-
2487 create(1), podman-port(1), podman-start(1), podman-kill(1), podman-
2488 stop(1), podman-generate-systemd(1), podman-rm(1), subgid(5), sub‐
2489 uid(5), containers.conf(5), systemd.unit(5), setsebool(8),
2490 slirp4netns(1), fuse-overlayfs(1), proc(5), conmon(8), personality(2)
2491
2492
2494 October 2017, converted from Docker documentation to Podman by Dan
2495 Walsh for Podman <dwalsh@redhat.com>
2496
2497
2498 November 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2499
2500
2501 September 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2502
2503
2504 August 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2505
2506
2508 1: The Podman project is committed to inclusivity, a core value of open
2509 source. The master and slave mount propagation terminology used here is
2510 problematic and divisive, and should be changed. However, these terms
2511 are currently used within the Linux kernel and must be used as-is at
2512 this time. When the kernel maintainers rectify this usage, Podman will
2513 follow suit immediately.
2514
2515
2516
2517 podman-create(1)