1podman-run(1)() podman-run(1)()
2
6 podman-run - Run a command in a new container
7
10 podman run [options] image [command [arg ...]]
11 podman container run [options] image [command [arg ...]]
14
17 Run a process in a new container. podman run starts a process with its
18 own file system, its own networking, and its own isolated process tree.
19 The image which starts the process may define defaults related to the
20 process that will be run in the container, the networking to expose,
21 and more, but podman run gives final control to the operator or admin‐
22 istrator who starts the container from the image. For that reason pod‐
23 man run has more options than any other Podman command.
24 If the image is not already loaded then podman run will pull the image,
27 and all image dependencies, from the repository in the same way running
28 podman pull image , before it starts the container from that image.
29 Several files will be automatically created within the container. These
32 include /etc/hosts, /etc/hostname, and /etc/resolv.conf to manage net‐
33 working. These will be based on the host's version of the files,
34 though they can be customized with options (for example, --dns will
35 override the host's DNS servers in the created resolv.conf). Addition‐
36 ally, a container environment file is created in each container to in‐
37 dicate to programs they are running in a container. This file is lo‐
38 cated at /run/.containerenv. When using the --privileged flag the .con‐
39 tainerenv contains name/value pairs indicating the container engine
40 version, whether the engine is running in rootless mode, the container
41 name and id, as well as the image name and id that the container is
42 based on.
43 When running from a user defined network namespace, the
46 /etc/netns/NSNAME/resolv.conf will be used if it exists, otherwise
47 /etc/resolv.conf will be used.
48 Default settings are defined in containers.conf. Most settings for re‐
51 mote connections use the servers containers.conf, except when docu‐
52 mented in man pages.
53
56 The image is specified using transport:path format. If no transport is
57 specified, the docker (container registry) transport will be used by
58 default. For remote Podman, including Mac and Windows (excluding WSL2)
59 machines, docker is the only allowed transport.
60 dir:path
63 An existing local directory path storing the manifest, layer tarballs
64 and signatures as individual files. This is a non-standardized format,
65 primarily useful for debugging or noninvasive container inspection.
66 $ podman save --format docker-dir fedora -o /tmp/fedora
69 $ podman run dir:/tmp/fedora echo hello
70 docker://docker-reference (Default)
74 An image reference stored in a remote container image registry. Exam‐
75 ple: "quay.io/podman/stable:latest". The reference can include a path
76 to a specific registry; if it does not, the registries listed in reg‐
77 istries.conf will be queried to find a matching image. By default,
78 credentials from podman login (stored at $XDG_RUNTIME_DIR/contain‐
79 ers/auth.json by default) will be used to authenticate; otherwise it
80 falls back to using credentials in $HOME/.docker/config.json.
81 $ podman run registry.fedoraproject.org/fedora:latest echo hello
84 docker-archive:path[:docker-reference] An image stored in the docker
88 save formatted file. docker-reference is only used when creating such a
89 file, and it must not contain a digest.
90 $ podman save --format docker-archive fedora -o /tmp/fedora
93 $ podman run docker-archive:/tmp/fedora echo hello
94 docker-daemon:docker-reference
98 An image in docker-reference format stored in the docker daemon in‐
99 ternal storage. The docker-reference can also be an image ID (docker-
100 daemon:algo:digest).
101 $ sudo docker pull fedora
104 $ sudo podman run docker-daemon:docker.io/library/fedora echo hello
105 oci-archive:path:tag
109 An image in a directory compliant with the "Open Container Image Lay‐
110 out Specification" at the specified path and specified with a tag.
111 $ podman save --format oci-archive fedora -o /tmp/fedora
114 $ podman run oci-archive:/tmp/fedora echo hello
115
119 --add-host=host:ip
120 Add a custom host-to-IP mapping (host:ip)
121 Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
124 tion can be set multiple times.
125 --annotation=key=value
128 Add an annotation to the container. This option can be set multiple
129 times.
130 --arch=ARCH
133 Override the architecture, defaults to hosts, of the image to be
134 pulled. For example, arm.
135 --attach, -a=stdin|stdout|stderr
138 Attach to STDIN, STDOUT or STDERR.
139 In foreground mode (the default when -d is not specified), podman run
142 can start the process in the container and attach the console to the
143 process's standard input, output, and error. It can even pretend to be
144 a TTY (this is what most commandline executables expect) and pass along
145 signals. The -a option can be set for each of stdin, stdout, and
146 stderr.
147 --authfile[=path]
150 Path to the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
151 ers/auth.json.
152 Note: You can also override the default path of the authentication file
155 by setting the REGISTRY_AUTH_FILE environment variable.
156 --blkio-weight=weight
159 Block IO relative weight. The weight is a value between 10 and 1000.
160 --blkio-weight-device=device:weight
163 Block IO relative device weight.
164 --cap-add=capability
167 Add Linux capabilities.
168 --cap-drop=capability
171 Drop Linux capabilities.
172 --cgroup-conf=KEY=VALUE
175 When running on cgroup v2, specify the cgroup file to write to and its
176 value. For example --cgroup-conf=memory.high=1073741824 sets the mem‐
177 ory.high limit to 1GB.
178 --cgroup-parent=path
181 Path to cgroups under which the cgroup for the container will be cre‐
182 ated. If the path is not absolute, the path is considered to be rela‐
183 tive to the cgroups path of the init process. Cgroups will be created
184 if they do not already exist.
185 --cgroupns=mode
188 Set the cgroup namespace mode for the container.
189 • host: use the host's cgroup namespace inside the container.
192 • container:id: join the namespace of the specified container.
194 • private: create a new cgroup namespace.
196 • ns:path: join the namespace at the specified path.
198 If the host uses cgroups v1, the default is set to host. On cgroups v2,
202 the default is private.
203 --cgroups=enabled|disabled|no-conmon|split
206 Determines whether the container will create CGroups.
207 Default is enabled.
210 The enabled option will create a new cgroup under the cgroup-parent.
213 The disabled option will force the container to not create CGroups, and
214 thus conflicts with CGroup options (--cgroupns and --cgroup-parent).
215 The no-conmon option disables a new CGroup only for the conmon process.
216 The split option splits the current CGroup in two sub-cgroups: one for
217 conmon and one for the container payload. It is not possible to set
218 --cgroup-parent with split.
219 --chrootdirs=path
222 Path to a directory inside the container that should be treated as a
223 chroot directory. Any Podman managed file (e.g., /etc/resolv.conf,
224 /etc/hosts, etc/hostname) that is mounted into the root directory will
225 be mounted into that location as well. Multiple directories should be
226 separated with a comma.
227 --cidfile=file
230 Write the container ID to file.
231 --conmon-pidfile=file
234 Write the pid of the conmon process to a file. As conmon runs in a sep‐
235 arate process than Podman, this is necessary when using systemd to
236 restart Podman containers. (This option is not available with the re‐
237 mote Podman client, including Mac and Windows (excluding WSL2) ma‐
238 chines)
239 --cpu-period=limit
242 Set the CPU period for the Completely Fair Scheduler (CFS), which is a
243 duration in microseconds. Once the container's CPU quota is used up, it
244 will not be scheduled to run until the current period ends. Defaults to
245 100000 microseconds.
246 On some systems, changing the CPU limits may not be allowed for non-
249 root users. For more details, see https://github.com/containers/pod‐
250 man/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-
251 fails-with-a-permissions-error
252 --cpu-quota=limit
255 Limit the CPU Completely Fair Scheduler (CFS) quota.
256 Limit the container's CPU usage. By default, containers run with the
259 full CPU resource. The limit is a number in microseconds. If you pro‐
260 vide a number, the container will be allowed to use that much CPU time
261 until the CPU period ends (controllable via --cpu-period).
262 On some systems, changing the CPU limits may not be allowed for non-
265 root users. For more details, see https://github.com/containers/pod‐
266 man/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-
267 fails-with-a-permissions-error
268 --cpu-rt-period=microseconds
271 Limit the CPU real-time period in microseconds.
272 Limit the container's Real Time CPU usage. This flag tell the kernel to
275 restrict the container's Real Time CPU usage to the period you specify.
276 This flag is not supported on cgroups V2 systems.
279 --cpu-rt-runtime=microseconds
282 Limit the CPU real-time runtime in microseconds.
283 Limit the containers Real Time CPU usage. This flag tells the kernel to
286 limit the amount of time in a given CPU period Real Time tasks may con‐
287 sume. Ex: Period of 1,000,000us and Runtime of 950,000us means that
288 this container could consume 95% of available CPU and leave the remain‐
289 ing 5% to normal priority tasks.
290 The sum of all runtimes across containers cannot exceed the amount al‐
293 lotted to the parent cgroup.
294 This flag is not supported on cgroups V2 systems.
297 --cpu-shares=shares
300 CPU shares (relative weight).
301 By default, all containers get the same proportion of CPU cycles. This
304 proportion can be modified by changing the container's CPU share
305 weighting relative to the combined weight of all the running contain‐
306 ers. Default weight is 1024.
307 The proportion will only apply when CPU-intensive processes are run‐
310 ning. When tasks in one container are idle, other containers can use
311 the left-over CPU time. The actual amount of CPU time will vary depend‐
312 ing on the number of containers running on the system.
313 For example, consider three containers, one has a cpu-share of 1024 and
316 two others have a cpu-share setting of 512. When processes in all three
317 containers attempt to use 100% of CPU, the first container would re‐
318 ceive 50% of the total CPU time. If you add a fourth container with a
319 cpu-share of 1024, the first container only gets 33% of the CPU. The
320 remaining containers receive 16.5%, 16.5% and 33% of the CPU.
321 On a multi-core system, the shares of CPU time are distributed over all
324 CPU cores. Even if a container is limited to less than 100% of CPU
325 time, it can use 100% of each individual CPU core.
326 For example, consider a system with more than three cores. If you start
329 one container {C0} with --cpu-shares=512 running one process, and an‐
330 other container {C1} with --cpu-shares=1024 running two processes, this
331 can result in the following division of CPU shares:
332 ┌────┬───────────┬─────┬──────────────┐
335 │PID │ container │ CPU │ CPU share │
336 ├────┼───────────┼─────┼──────────────┤
337 │100 │ {C0} │ 0 │ 100% of CPU0 │
338 ├────┼───────────┼─────┼──────────────┤
339 │101 │ {C1} │ 1 │ 100% of CPU1 │
340 ├────┼───────────┼─────┼──────────────┤
341 │102 │ {C1} │ 2 │ 100% of CPU2 │
342 └────┴───────────┴─────┴──────────────┘
343 --cpus=number
345 Number of CPUs. The default is 0.0 which means no limit. This is short‐
346 hand for --cpu-period and --cpu-quota, so you may only set either
347 --cpus or --cpu-period and --cpu-quota.
350 On some systems, changing the CPU limits may not be allowed for non-
351 root users. For more details, see https://github.com/containers/pod‐
352 man/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-
353 fails-with-a-permissions-error
354 --cpuset-cpus=number
357 CPUs in which to allow execution. Can be specified as a comma-separated
358 list (e.g. 0,1), as a range (e.g. 0-3), or any combination thereof
359 (e.g. 0-3,7,11-15).
360 --cpuset-mems=nodes
363 Memory nodes (MEMs) in which to allow execution. Only effective on NUMA
364 systems.
365 For example, if you have four memory nodes (0-3) on your system, use
368 --cpuset-mems=0,1 to only use memory from the first two memory nodes.
369 --detach, -d
372 Detached mode: run the container in the background and print the new
373 container ID. The default is false.
374 At any time you can run podman ps in the other shell to view a list of
377 the running containers. You can reattach to a detached container with
378 podman attach.
379 When attached in the tty mode, you can detach from the container (and
382 leave it running) using a configurable key sequence. The default se‐
383 quence is ctrl-p,ctrl-q. Configure the keys sequence using the --de‐
384 tach-keys option, or specifying it in the containers.conf file: see
385 containers.conf(5) for more information.
386 --detach-keys=sequence
389 Specify the key sequence for detaching a container. Format is a single
390 character [a-Z] or one or more ctrl-<value> characters where <value> is
391 one of: a-z, @, ^, [, , or _. Specifying "" will set the sequence to
392 the default value of ctrl-p,ctrl-q.
393 This option can also be set in containers.conf(5) file.
396 --device=host-device[:container-device][:permissions]
399 Add a host device to the container. Optional permissions parameter can
400 be used to specify device permissions, it is combination of r for read,
401 w for write, and m for mknod(2).
402 Example: --device=/dev/sdc:/dev/xvdc:rwm.
405 Note: if _hostdevice is a symbolic link then it will be resolved first.
408 The container will only store the major and minor numbers of the host
409 device.
410 Note: if the user only has access rights via a group, accessing the de‐
413 vice from inside a rootless container will fail. Use the --group-add
414 keep-groups flag to pass the user's supplementary group access into the
415 container.
416 Podman may load kernel modules required for using the specified device.
419 The devices that Podman will load modules when necessary are:
420 /dev/fuse.
421 --device-cgroup-rule=rule
424 Add a rule to the cgroup allowed devices list
425 --device-read-bps=path:rate
428 Limit read rate (in bytes per second) from a device (e.g. --device-
429 read-bps=/dev/sda:1mb).
430 --device-read-iops=path:rate
433 Limit read rate (in IO operations per second) from a device (e.g. --de‐
434 vice-read-iops=/dev/sda:1000).
435 --device-write-bps=path:rate
438 Limit write rate (in bytes per second) to a device (e.g. --device-
439 write-bps=/dev/sda:1mb).
440 --device-write-iops=path:rate
443 Limit write rate (in IO operations per second) to a device (e.g. --de‐
444 vice-write-iops=/dev/sda:1000).
445 --disable-content-trust
448 This is a Docker specific option to disable image verification to a
449 Docker registry and is not supported by Podman. This flag is a NOOP and
450 provided solely for scripting compatibility.
451 --dns=ipaddr
454 Set custom DNS servers. Invalid if using --dns with --network that is
455 set to none or container:id.
456 This option can be used to override the DNS configuration passed to the
459 container. Typically this is necessary when the host DNS configuration
460 is invalid for the container (e.g., 127.0.0.1). When this is the case
461 the --dns flag is necessary for every run.
462 The special value none can be specified to disable creation of /etc/re‐
465 solv.conf in the container by Podman. The /etc/resolv.conf file in the
466 image will be used without changes.
467 --dns-opt=option
470 Set custom DNS options. Invalid if using --dns-opt with --network that
471 is set to none or container:id.
472 --dns-search=domain
475 Set custom DNS search domains. Invalid if using --dns-search and --net‐
476 work that is set to none or container:id. Use --dns-search=. if you
477 don't wish to set the search domain.
478 --entrypoint="command" | '["command", arg1 , ...]'
481 Overwrite the default ENTRYPOINT of the image.
482 This option allows you to overwrite the default entrypoint of the im‐
485 age.
486 The ENTRYPOINT of an image is similar to a COMMAND because it specifies
489 what executable to run when the container starts, but it is (purposely)
490 more difficult to override. The ENTRYPOINT gives a container its de‐
491 fault nature or behavior, so that when you set an ENTRYPOINT you can
492 run the container as if it were that binary, complete with default op‐
493 tions, and you can pass in more options via the COMMAND. But, sometimes
494 an operator may want to run something else inside the container, so you
495 can override the default ENTRYPOINT at runtime by using a --entrypoint
496 and a string to specify the new ENTRYPOINT.
497 You need to specify multi option commands in the form of a json string.
500 --env, -e=env
503 Set environment variables.
504 This option allows arbitrary environment variables that are available
507 for the process to be launched inside of the container. If an environ‐
508 ment variable is specified without a value, Podman will check the host
509 environment for a value and set the variable only if it is set on the
510 host. If an environment variable ending in * is specified, Podman will
511 search the host environment for variables starting with the prefix and
512 will add those variables to the container. If an environment variable
513 with a trailing * is specified, then a value must be supplied.
514 See Environment ⟨#environment⟩ note below for precedence and examples.
517 --env-file=file
520 Read in a line delimited file of environment variables. See Environment
521 note below for precedence.
522 --env-host
525 Use host environment inside of the container. See Environment note be‐
526 low for precedence. (This option is not available with the remote Pod‐
527 man client, including Mac and Windows (excluding WSL2) machines)
528 --expose=port
531 Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up
532 port redirection on the host system.
533 --gidmap=container_gid:host_gid:amount
536 Run the container in a new user namespace using the supplied mapping.
537 This option conflicts with the --userns and --subgidname flags. This
538 option can be passed several times to map different ranges. If calling
539 podman run as an unprivileged user, the user needs to have the right to
540 use the mapping. See subuid(5). The example maps gids 0-1999 in the
541 container to the gids 30000-31999 on the host: --gidmap=0:30000:2000.
542 Important note: The new user namespace mapping based on --gidmap is
545 based on the initial mapping made in the /etc/subgid file. Assuming
546 there is a /etc/subgid mapping groupname:100000:65536, then groupname
547 is initially mapped to a namespace starting with gid 100000 for 65536
548 ids. From here the --gidmap mapping to the new namespace starts from 0
549 again, but is based on the initial mapping. Meaning groupname is ini‐
550 tially mapped to gid 100000 which is referenced as 0 in the following
551 --gidmap mapping. In terms of the example above: The group groupname is
552 mapped to group 100000 of the initial namespace then the 30000st id of
553 this namespace (which is gid 130000 in this namespace) is mapped to
554 container namespace group id 0. (groupname -> 100000 / 30000 -> 0)
555 Note: the --gidmap flag cannot be called in conjunction with the --pod
558 flag as a gidmap cannot be set on the container level when in a pod.
559 --group-add=group|keep-groups
562 Assign additional groups to the primary user running within the con‐
563 tainer process.
564 • keep-groups is a special flag that tells Podman to keep the
567 supplementary group access.
568 Allows container to use the user's supplementary group access. If file
572 systems or devices are only accessible by the rootless user's group,
573 this flag tells the OCI runtime to pass the group access into the con‐
574 tainer. Currently only available with the crun OCI runtime. Note: keep-
575 groups is exclusive, you cannot add any other groups with this flag.
576 (Not available for remote commands, including Mac and Windows (exclud‐
577 ing WSL2) machines)
578 --health-cmd="command" | '["command", arg1 , ...]'
581 Set or alter a healthcheck command for a container. The command is a
582 command to be executed inside your container that determines your con‐
583 tainer health. The command is required for other healthcheck options to
584 be applied. A value of none disables existing healthchecks.
585 Multiple options can be passed in the form of a JSON array; otherwise,
588 the command will be interpreted as an argument to /bin/sh -c.
589 --health-interval=interval
592 Set an interval for the healthchecks. An interval of disable results in
593 no automatic timer setup. The default is 30s.
594 --health-retries=retries
597 The number of retries allowed before a healthcheck is considered to be
598 unhealthy. The default value is 3.
599 --health-start-period=period
602 The initialization time needed for a container to bootstrap. The value
603 can be expressed in time format like 2m3s. The default value is 0s.
604 --health-timeout=timeout
607 The maximum time allowed to complete the healthcheck before an interval
608 is considered failed. Like start-period, the value can be expressed in
609 a time format such as 1m22s. The default value is 30s.
610 --help
613 Print usage statement
614 --hostname=name, -h
617 Container host name
618 Sets the container host name that is available inside the container.
621 Can only be used with a private UTS namespace --uts=private (default).
622 If --pod is specified and the pod shares the UTS namespace (default)
623 the pod's hostname will be used.
624 --hostuser=name
627 Add a user account to /etc/passwd from the host to the container. The
628 Username or UID must exist on the host system.
629 --http-proxy
632 By default proxy environment variables are passed into the container if
633 set for the Podman process. This can be disabled by setting the value
634 to false. The environment variables passed in include http_proxy,
635 https_proxy, ftp_proxy, no_proxy, and also the upper case versions of
636 those. This option is only needed when the host system must use a proxy
637 but the container should not use any proxy. Proxy environment variables
638 specified for the container in any other way will override the values
639 that would have been passed through from the host. (Other ways to spec‐
640 ify the proxy for the container include passing the values with the
641 --env flag, or hard coding the proxy environment at container build
642 time.) (This option is not available with the remote Podman client, in‐
643 cluding Mac and Windows (excluding WSL2) machines)
644 Defaults to true.
647 --image-volume, builtin-volume=bind|tmpfs|ignore
650 Tells Podman how to handle the builtin image volumes. Default is bind.
651 • bind: An anonymous named volume will be created and mounted
654 into the container.
655 • tmpfs: The volume is mounted onto the container as a tmpfs,
657 which allows the users to create content that disappears when
658 the container is stopped.
659 • ignore: All volumes are just ignored and no action is taken.
661 --init
665 Run an init inside the container that forwards signals and reaps pro‐
666 cesses.
667 --init-path=path
670 Path to the container-init binary.
671 --interactive, -i
674 When set to true, keep stdin open even if not attached. The default is
675 false.
676 --ip=ipv4
679 Specify a static IPv4 address for the container, for example
680 10.88.64.128. This option can only be used if the container is joined
681 to only a single network - i.e., --network=network-name is used at most
682 once - and if the container is not joining another container's network
683 namespace via --network=container:id. The address must be within the
684 network's IP address pool (default 10.88.0.0/16).
685 To specify multiple static IP addresses per container, set multiple
688 networks using the --network option with a static IP address specified
689 for each using the ip mode for that option.
690 --ip6=ipv6
693 Specify a static IPv6 address for the container, for example
694 fd46:db93:aa76:ac37::10. This option can only be used if the container
695 is joined to only a single network - i.e., --network=network-name is
696 used at most once - and if the container is not joining another con‐
697 tainer's network namespace via --network=container:id. The address
698 must be within the network's IPv6 address pool.
699 To specify multiple static IPv6 addresses per container, set multiple
702 networks using the --network option with a static IPv6 address speci‐
703 fied for each using the ip6 mode for that option.
704 --ipc=mode
707 Set the IPC namespace mode for a container. The default is to create a
708 private IPC namespace.
709 • "": Use Podman's default, defined in containers.conf.
712 • container:id: reuses another container shared memory, sema‐
714 phores and message queues
715 • host: use the host shared memory,semaphores and message queues
717 inside the container. Note: the host mode gives the container
718 full access to local shared memory and is therefore considered
719 insecure.
720 • none: private IPC namespace, with /dev/shm not mounted.
722 • ns:path: path to an IPC namespace to join.
724 • private: private IPC namespace. = shareable: private IPC
726 namespace with a possibility to share it with other contain‐
727 ers.
728 --label, -l=key=value
732 Add metadata to a container.
733 --label-file=file
736 Read in a line-delimited file of labels.
737 --link-local-ip=ip
740 Not implemented.
741 --log-driver="driver"
744 Logging driver for the container. Currently available options are k8s-
745 file, journald, none and passthrough, with json-file aliased to k8s-
746 file for scripting compatibility. (Default journald)
747 The podman info command below will display the default log-driver for
750 the system.
751 $ podman info --format '{{ .Host.LogDriver }}'
754 journald
755 The passthrough driver passes down the standard streams (stdin, stdout,
759 stderr) to the container. It is not allowed with the remote Podman
760 client, including Mac and Windows (excluding WSL2) machines, and on a
761 tty, since it is vulnerable to attacks via TIOCSTI.
762 --log-opt=name=value
765 Logging driver specific options.
766 Set custom logging configuration. The following *name*s are supported:
769 path: specify a path to the log file
772 (e.g. --log-opt path=/var/log/container/mycontainer.json);
773 max-size: specify a max size of the log file
776 (e.g. --log-opt max-size=10mb);
777 tag: specify a custom log tag for the container
780 (e.g. --log-opt tag="{{.ImageName}}".
781 This option is currently supported only by the journald log driver.
784 --mac-address=address
787 Container network interface MAC address (e.g. 92:d0:c6:0a:29:33) This
788 option can only be used if the container is joined to only a single
789 network - i.e., --network=network-name is used at most once - and if
790 the container is not joining another container's network namespace via
791 --network=container:id.
792 Remember that the MAC address in an Ethernet network must be unique.
795 The IPv6 link-local address will be based on the device's MAC address
796 according to RFC4862.
797 To specify multiple static MAC addresses per container, set multiple
800 networks using the --network option with a static MAC address specified
801 for each using the mac mode for that option.
802 --memory, -m=number[unit]
805 Memory limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or
806 g (gibibytes).
807 Allows you to constrain the memory available to a container. If the
810 host supports swap memory, then the -m memory setting can be larger
811 than physical RAM. If a limit of 0 is specified (not using -m), the
812 container's memory is not limited. The actual limit may be rounded up
813 to a multiple of the operating system's page size (the value would be
814 very large, that's millions of trillions).
815 --memory-reservation=number[unit]
818 Memory soft limit. A unit can be b (bytes), k (kibibytes), m
819 (mebibytes), or g (gibibytes).
820 After setting memory reservation, when the system detects memory con‐
823 tention or low memory, containers are forced to restrict their consump‐
824 tion to their reservation. So you should always set the value below
825 --memory, otherwise the hard limit will take precedence. By default,
826 memory reservation will be the same as memory limit.
827 --memory-swap=number[unit]
830 A limit value equal to memory plus swap. A unit can be b (bytes), k
831 (kibibytes), m (mebibytes), or g (gibibytes).
832 Must be used with the -m (--memory) flag. The argument value should
835 always be larger than that of
836 -m (--memory) By default, it is set to double the value of --memory.
837 Set number to -1 to enable unlimited swap.
840 --memory-swappiness=number
843 Tune a container's memory swappiness behavior. Accepts an integer be‐
844 tween 0 and 100.
845 This flag is not supported on cgroups V2 systems.
848 --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
851 Attach a filesystem mount to the container
852 Current supported mount TYPEs are bind, volume, image, tmpfs and de‐
855 vpts. [1] ⟨#Footnote1⟩
856 e.g.
859 type=bind,source=/path/on/host,destination=/path/in/container
861 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
863 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true
865 type=volume,source=vol1,destination=/path/in/container,ro=true
867 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
869 type=image,source=fedora,destination=/fedora-image,rw=true
871 type=devpts,destination=/dev/pts
873 Common Options:
875 · src, source: mount source spec for bind and volume. Mandatory for bind.
877 · dst, destination, target: mount destination spec.
879 Options specific to volume:
881 · ro, readonly: true or false (default).
883 . 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.
885 · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container.
887 Options specific to image:
889 · rw, readwrite: true or false (default).
891 Options specific to bind:
893 · ro, readonly: true or false (default).
895 · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2).
897 . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive.
899 . relabel: shared, private.
901 · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container.
903 . 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.
905 Options specific to tmpfs:
907 · ro, readonly: true or false (default).
909 · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
911 · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
913 · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default.
915 · notmpcopyup: Disable copying files from the image to the tmpfs.
917 . 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.
919 Options specific to devpts:
921 · uid: UID of the file owner (default 0).
923 · gid: GID of the file owner (default 0).
925 · mode: permission mask for the file (default 600).
927 · max: maximum number of PTYs (default 1048576).
929 --name=name
933 Assign a name to the container.
934 The operator can identify a container in three ways:
937 • UUID long identifier
940 (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”);
941 • UUID short identifier (“f78375b1c487”);
943 • Name (“jonah”).
945 Podman generates a UUID for each container, and if a name is not as‐
949 signed to the container with --name then it will generate a random
950 string name. The name is useful any place you need to identify a con‐
951 tainer. This works for both background and foreground containers.
952 --network=mode, --net
955 Set the network mode for the container. Invalid if using --dns, --dns-
956 opt, or --dns-search with --network set to none or container:id. If
957 used together with --pod, the container will not join the pod's network
958 namespace.
959 Valid mode values are:
962 • bridge[:OPTIONS,...]: Create a network stack on the default
965 bridge. This is the default for rootful containers. It is pos‐
966 sible to specify these additional options:
967 • alias=name: Add network-scoped alias for the container.
969 • ip=IPv4: Specify a static ipv4 address for this container.
971 • ip=IPv6: Specify a static ipv6 address for this container.
973 • mac=MAC: Specify a static mac address for this container.
975 • interface_name: Specify a name for the created network in‐
977 terface inside the container.
978 For example to set a static ipv4 address and a static mac address, use
984 --network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99. - <network name
985 or ID>[:OPTIONS,...]: Connect to a user-defined network; this is the
986 network name or ID from a network created by podman network create. Us‐
987 ing the network name implies the bridge network mode. It is possible to
988 specify the same options described under the bridge mode above. You can
989 use the --network option multiple times to specify additional networks.
990 - none: Create a network namespace for the container but do not config‐
991 ure network interfaces for it, thus the container has no network con‐
992 nectivity. - container:id: Reuse another container's network stack. -
993 host: Do not create a network namespace, the container will use the
994 host's network. Note: The host mode gives the container full access to
995 local system services such as D-bus and is therefore considered inse‐
996 cure. - ns:path: Path to a network namespace to join. - private: Cre‐
997 ate a new namespace for the container. This will use the bridge mode
998 for rootful containers and slirp4netns for rootless ones. -
999 slirp4netns[:OPTIONS,...]: use slirp4netns(1) to create a user network
1000 stack. This is the default for rootless containers. It is possible to
1001 specify these additional options, they can also be set with net‐
1002 work_cmd_options in containers.conf:
1003 - allow_host_loopback=true|false: Allow the slirp4netns to reach the
1004 host loopback IP (10.0.2.2). Default is false.
1005 - mtu=MTU: Specify the MTU to use for this network. (Default is
1006 65520).
1007 - cidr=CIDR: Specify ip range to use for this network. (Default is
1008 10.0.2.0/24).
1009 - enable_ipv6=true|false: Enable IPv6. Default is true. (Required for
1010 outbound_addr6).
1011 - outbound_addr=INTERFACE: Specify the outbound interface slirp
1012 should bind to (ipv4 traffic only).
1013 - outbound_addr=IPv4: Specify the outbound ipv4 address slirp should
1014 bind to.
1015 - outbound_addr6=INTERFACE: Specify the outbound interface slirp
1016 should bind to (ipv6 traffic only).
1017 - outbound_addr6=IPv6: Specify the outbound ipv6 address slirp should
1018 bind to.
1019 - port_handler=rootlesskit: Use rootlesskit for port forwarding. De‐
1020 fault.
1021 Note: Rootlesskit changes the source IP address of incoming packets
1022 to an IP address in the container network namespace, usually
1023 10.0.2.100. If your application requires the real source IP address,
1024 e.g. web server logs, use the slirp4netns port handler. The rootlesskit
1025 port handler is also used for rootless containers when connected to
1026 user-defined networks.
1027 - port_handler=slirp4netns: Use the slirp4netns port forwarding, it
1028 is slower than rootlesskit but preserves the correct source IP address.
1029 This port handler cannot be used for user-defined networks.
1030 --network-alias=alias
1033 Add a network-scoped alias for the container, setting the alias for all
1034 networks that the container joins. To set a name only for a specific
1035 network, use the alias option as described under the --network option.
1036 Network aliases work only with the bridge networking mode. This option
1037 can be specified multiple times. NOTE: A container will only have ac‐
1038 cess to aliases on the first network that it joins. This is a limita‐
1039 tion that will be removed in a later release.
1040 --no-healthcheck
1043 Disable any defined healthchecks for container.
1044 --no-hosts
1047 Do not create /etc/hosts for the container. By default, Podman will
1048 manage /etc/hosts, adding the container's own IP address and any hosts
1049 from --add-host. --no-hosts disables this, and the image's /etc/hosts
1050 will be preserved unmodified. This option conflicts with --add-host.
1051 --oom-kill-disable
1054 Whether to disable OOM Killer for the container or not.
1055 This flag is not supported on cgroups V2 systems.
1058 --oom-score-adj=num
1061 Tune the host's OOM preferences for containers (accepts values from
1062 -1000 to 1000).
1063 --os=OS
1066 Override the OS, defaults to hosts, of the image to be pulled. For ex‐
1067 ample, windows.
1068 --passwd
1071 Allow Podman to add entries to /etc/passwd and /etc/group when used in
1072 conjunction with the --user option. This is used to override the Pod‐
1073 man provided user setup in favor of entrypoint configurations such as
1074 libnss-extrausers.
1075 --passwd-entry=ENTRY
1078 Customize the entry that is written to the /etc/passwd file within the
1079 container when --passwd is used.
1080 The variables $USERNAME, $UID, $GID, $NAME, $HOME are automatically re‐
1083 placed with their value at runtime.
1084 --personality=persona
1087 Personality sets the execution domain via Linux personality(2).
1088 --pid=mode
1091 Set the PID namespace mode for the container. The default is to create
1092 a private PID namespace for the container.
1093 • container:id: join another container's PID namespace;
1096 • host: use the host's PID namespace for the container. Note the
1098 host mode gives the container full access to local PID and is
1099 therefore considered insecure;
1100 • private: create a new namespace for the container (default)
1102 • ns:path: join the specified PID namespace.
1104 --pidfile=path
1108 When the pidfile location is specified, the container process' PID will
1109 be written to the pidfile. (This option is not available with the re‐
1110 mote Podman client, including Mac and Windows (excluding WSL2) ma‐
1111 chines) If the pidfile option is not specified, the container process'
1112 PID will be written to /run/containers/storage/${storage-driver}-con‐
1113 tainers/$CID/userdata/pidfile.
1114 After the container is started, the location for the pidfile can be
1117 discovered with the following podman inspect command:
1118 $ podman inspect --format '{{ .PidFile }}' $CID
1121 /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile
1122 --pids-limit=limit
1126 Tune the container's pids limit. Set to -1 to have unlimited pids for
1127 the container. The default is 4096 on systems that support "pids"
1128 cgroup controller.
1129 --platform=OS/ARCH
1132 Specify the platform for selecting the image. (Conflicts with --arch
1133 and --os) The --platform option can be used to override the current ar‐
1134 chitecture and operating system.
1135 --pod=name
1138 Run container in an existing pod. If you want Podman to make the pod
1139 for you, prefix the pod name with new:. To make a pod with more granu‐
1140 lar options, use the podman pod create command before creating a con‐
1141 tainer. If a container is run with a pod, and the pod has an infra-
1142 container, the infra-container will be started before the container is.
1143 --pod-id-file=path
1146 Run container in an existing pod and read the pod's ID from the speci‐
1147 fied file. If a container is run within a pod, and the pod has an in‐
1148 fra-container, the infra-container will be started before the container
1149 is.
1150 --preserve-fds=N
1153 Pass down to the process N additional file descriptors (in addition to
1154 0, 1, 2). The total FDs will be 3+N. (This option is not available
1155 with the remote Podman client, including Mac and Windows (excluding
1156 WSL2) machines)
1157 --privileged
1160 Give extended privileges to this container. The default is false.
1161 By default, Podman containers are unprivileged (=false) and cannot, for
1164 example, modify parts of the operating system. This is because by de‐
1165 fault a container is only allowed limited access to devices. A "privi‐
1166 leged" container is given the same access to devices as the user
1167 launching the container.
1168 A privileged container turns off the security features that isolate the
1171 container from the host. Dropped Capabilities, limited devices, read-
1172 only mount points, Apparmor/SELinux separation, and Seccomp filters are
1173 all disabled.
1174 Rootless containers cannot have more privileges than the account that
1177 launched them.
1178 --publish, -p=[[ip:][hostPort]:]containerPort[/protocol]
1181 Publish a container's port, or range of ports, to the host.
1182 Both hostPort and containerPort can be specified as a range of ports.
1185 When specifying ranges for both, the number of container ports in the
1186 range must match the number of host ports in the range.
1187 If host IP is set to 0.0.0.0 or not set at all, the port will be bound
1190 on all IPs on the host.
1191 By default, Podman will publish TCP ports. To publish a UDP port in‐
1194 stead, give udp as protocol. To publish both TCP and UDP ports, set
1195 --publish twice, with tcp, and udp as protocols respectively. Rootful
1196 containers can also publish ports using the sctp protocol.
1197 Host port does not have to be specified (e.g. podman run -p
1200 127.0.0.1::80). If it is not, the container port will be randomly as‐
1201 signed a port on the host.
1202 Use podman port to see the actual mapping: podman port $CONTAINER $CON‐
1205 TAINERPORT.
1206 Note: If a container will be run within a pod, it is not necessary to
1209 publish the port for the containers in the pod. The port must only be
1210 published by the pod itself. Pod network stacks act like the network
1211 stack on the host - you have a variety of containers in the pod, and
1212 programs in the container, all sharing a single interface and IP ad‐
1213 dress, and associated ports. If one container binds to a port, no other
1214 container can use that port within the pod while it is in use. Contain‐
1215 ers in the pod can also communicate over localhost by having one con‐
1216 tainer bind to localhost in the pod, and another connect to that port.
1217 --publish-all, -P
1220 Publish all exposed ports to random ports on the host interfaces. The
1221 default is false.
1222 When set to true, publish all exposed ports to the host interfaces. The
1225 default is false. If the operator uses -P (or -p) then Podman will make
1226 the exposed port accessible on the host and the ports will be available
1227 to any client that can reach the host.
1228 When using this option, Podman will bind any exposed port to a random
1231 port on the host within an ephemeral port range defined by
1232 /proc/sys/net/ipv4/ip_local_port_range. To find the mapping between
1233 the host ports and the exposed ports, use podman port.
1234 --pull=always|missing|never
1237 Pull image before running. The default is missing.
1238 • missing: attempt to pull the latest image from the registries
1241 listed in registries.conf if a local image does not ex‐
1242 ist.Raise an error if the image is not in any listed registry
1243 and is not present locally.
1244 • always: Pull the image from the first registry it is found in
1246 as listed in registries.conf. Raise an error if not found in
1247 the registries, even if the image is present locally.
1248 • never: do not pull the image from the registry, use only the
1250 local version. Raise an error if the image is not present lo‐
1251 cally.
1252 --quiet, -q
1256 Suppress output information when pulling images
1257 --read-only
1260 Mount the container's root filesystem as read only.
1261 By default a container will have its root filesystem writable allowing
1264 processes to write files anywhere. By specifying the --read-only flag,
1265 the container will have its root filesystem mounted as read only pro‐
1266 hibiting any writes.
1267 --read-only-tmpfs
1270 If container is running in --read-only mode, then mount a read-write
1271 tmpfs on /run, /tmp, and /var/tmp. The default is true.
1272 --replace
1275 If another container with the same name already exists, replace and re‐
1276 move it. The default is false.
1277 --requires=container
1280 Specify one or more requirements. A requirement is a dependency con‐
1281 tainer that will be started before this container. Containers can be
1282 specified by name or ID, with multiple containers being separated by
1283 commas.
1284 --restart=policy
1287 Restart policy to follow when containers exit. Restart policy will not
1288 take effect if a container is stopped via the podman kill or podman
1289 stop commands.
1290 Valid policy values are:
1293 • no : Do not restart containers on exit
1296 • on-failure[:max_retries] : Restart containers when they exit
1298 with a non-zero exit code, retrying indefinitely or until the
1299 optional max_retries count is hit
1300 • always : Restart containers when they exit,
1302 regardless of status, retrying indefinitely
1303 • unless-stopped : Identical to always
1305 Please note that restart will not restart containers after a system re‐
1309 boot. If this functionality is required in your environment, you can
1310 invoke Podman from a systemd.unit(5) file, or create an init script for
1311 whichever init system is in use. To generate systemd unit files,
1312 please see podman generate systemd.
1313 --rm
1316 Automatically remove the container when it exits. The default is false.
1317 --rmi
1320 After exit of the container, remove the image unless another container
1321 is using it. The default is false.
1322 --rootfs
1325 If specified, the first argument refers to an exploded container on the
1326 file system.
1327 This is useful to run a container without requiring any image manage‐
1330 ment, the rootfs of the container is assumed to be managed externally.
1331 Overlay Rootfs Mounts
1334 The :O flag tells Podman to mount the directory from the rootfs path as
1337 storage using the overlay file system. The container processes can mod‐
1338 ify content within the mount point which is stored in the container
1339 storage in a separate directory. In overlay terms, the source directory
1340 will be the lower, and the container storage directory will be the up‐
1341 per. Modifications to the mount point are destroyed when the container
1342 finishes executing, similar to a tmpfs mount point being unmounted.
1343 Note: On SELinux systems, the rootfs needs the correct label, which is
1346 by default unconfined_u:object_r:container_file_t.
1347 --sdnotify=container|conmon|ignore
1350 Determines how to use the NOTIFY_SOCKET, as passed with systemd and
1351 Type=notify.
1352 Default is container, which means allow the OCI runtime to proxy the
1355 socket into the container to receive ready notification. Podman will
1356 set the MAINPID to conmon's pid. The conmon option sets MAINPID to
1357 conmon's pid, and sends READY when the container has started. The
1358 socket is never passed to the runtime or the container. The ignore op‐
1359 tion removes NOTIFY_SOCKET from the environment for itself and child
1360 processes, for the case where some other process above Podman uses NO‐
1361 TIFY_SOCKET and Podman should not use it.
1362 --seccomp-policy=policy
1365 Specify the policy to select the seccomp profile. If set to image, Pod‐
1366 man will look for a "io.containers.seccomp.profile" label in the con‐
1367 tainer-image config and use its value as a seccomp profile. Otherwise,
1368 Podman will follow the default policy by applying the default profile
1369 unless specified otherwise via --security-opt seccomp as described be‐
1370 low.
1371 Note that this feature is experimental and may change in the future.
1374 --secret=secret[,opt=opt ...]
1377 Give the container access to a secret. Can be specified multiple times.
1378 A secret is a blob of sensitive data which a container needs at runtime
1381 but should not be stored in the image or in source control, such as
1382 usernames and passwords, TLS certificates and keys, SSH keys or other
1383 important generic strings or binary content (up to 500 kb in size).
1384 When secrets are specified as type mount, the secrets are copied and
1387 mounted into the container when a container is created. When secrets
1388 are specified as type env, the secret will be set as an environment
1389 variable within the container. Secrets are written in the container at
1390 the time of container creation, and modifying the secret using podman
1391 secret commands after the container is created will not affect the se‐
1392 cret inside the container.
1393 Secrets and its storage are managed using the podman secret command.
1396 Secret Options
1399 • type=mount|env : How the secret will be exposed to the con‐
1402 tainer. Default mount.
1403 • target=target : Target of secret. Defaults to secret name.
1405 • uid=0 : UID of secret. Defaults to 0. Mount secret
1407 type only.
1408 • gid=0 : GID of secret. Defaults to 0. Mount secret
1410 type only.
1411 • mode=0 : Mode of secret. Defaults to 0444. Mount
1413 secret type only.
1414 --security-opt=option
1418 Security Options
1419 • apparmor=unconfined : Turn off apparmor confinement for the
1422 container
1423 • apparmor=your-profile : Set the apparmor confinement profile
1425 for the container
1426 • label=user:USER: Set the label user for the container pro‐
1428 cesses
1429 • label=role:ROLE: Set the label role for the container pro‐
1431 cesses
1432 • label=type:TYPE: Set the label process type for the container
1434 processes
1435 • label=level:LEVEL: Set the label level for the container pro‐
1437 cesses
1438 • label=filetype:TYPE_: Set the label file type for the con‐
1440 tainer files
1441 • label=disable: Turn off label separation for the container
1443 Note: Labeling can be disabled for all containers by setting la‐
1447 bel=false in the containers.conf (/etc/containers/containers.conf or
1448 $HOME/.config/containers/containers.conf) file.
1449 • mask=/path/1:/path/2: The paths to mask separated by a colon.
1452 A masked path cannot be accessed inside the container.
1453 • no-new-privileges: Disable container processes from gaining
1455 additional privileges
1456 • seccomp=unconfined: Turn off seccomp confinement for the con‐
1458 tainer.
1459 • seccomp=profile.json: JSON file to be used as a seccomp fil‐
1461 ter. Note that the io.podman.annotations.seccomp annotation is
1462 set with the specified value as shown in podman inspect.
1463 • proc-opts=OPTIONS : Comma-separated list of options to use for
1465 the /proc mount. More details for the possible mount options
1466 are specified in the proc(5) man page.
1467 • unmask=ALL or /path/1:/path/2, or shell expanded paths
1469 (/proc/*): Paths to unmask separated by a colon. If set to
1470 ALL, it will unmask all the paths that are masked or made read
1471 only by default. The default masked paths are /proc/acpi,
1472 /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_de‐
1473 bug, /proc/scsi, /proc/timer_list, /proc/timer_stats,
1474 /sys/firmware, and /sys/fs/selinux.. The default paths that
1475 are read only are /proc/asound, /proc/bus, /proc/fs,
1476 /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup.
1477 Note: Labeling can be disabled for all containers by setting la‐
1481 bel=false in the containers.conf(5) file.
1482 --shm-size=number[unit]
1485 Size of /dev/shm. A unit can be b (bytes), k (kibibytes), m
1486 (mebibytes), or g (gibibytes). If you omit the unit, the system uses
1487 bytes. If you omit the size entirely, the default is 64m. When size is
1488 0, there is no limit on the amount of memory used for IPC by the con‐
1489 tainer.
1490 --sig-proxy
1493 Sets whether the signals sent to the podman run command are proxied to
1494 the container process. SIGCHLD, SIGSTOP, and SIGKILL are not proxied.
1495 The default is true.
1496 --stop-signal=signal
1499 Signal to stop a container. Default is SIGTERM.
1500 --stop-timeout=seconds
1503 Timeout to stop a container. Default is 10. Remote connections use lo‐
1504 cal containers.conf for defaults
1505 --subgidname=name
1508 Run the container in a new user namespace using the map with name in
1509 the /etc/subgid file. If calling podman run as an unprivileged user,
1510 the user needs to have the right to use the mapping. See subgid(5).
1511 This flag conflicts with --userns and --gidmap.
1512 --subuidname=name
1515 Run the container in a new user namespace using the map with name in
1516 the /etc/subuid file. If calling podman run as an unprivileged user,
1517 the user needs to have the right to use the mapping. See subuid(5).
1518 This flag conflicts with --userns and --uidmap.
1519 --sysctl=name=value
1522 Configure namespaced kernel parameters at runtime.
1523 For the IPC namespace, the following sysctls are allowed:
1526 • kernel.msgmax
1529 • kernel.msgmnb
1531 • kernel.msgmni
1533 • kernel.sem
1535 • kernel.shmall
1537 • kernel.shmmax
1539 • kernel.shmmni
1541 • kernel.shm_rmid_forced
1543 • Sysctls beginning with fs.mqueue.*
1545 Note: if you use the --ipc=host option, the above sysctls will not be
1549 allowed.
1550 For the network namespace, the following sysctls are allowed:
1553 • Sysctls beginning with net.*
1556 Note: if you use the --network=host option, these sysctls will not be
1560 allowed.
1561 --systemd=true|false|always
1564 Run container in systemd mode. The default is true.
1565 The value always enforces the systemd mode is enforced without looking
1568 at the executable name. Otherwise, if set to true and the command you
1569 are running inside the container is systemd, /usr/sbin/init, /sbin/init
1570 or /usr/local/sbin/init.
1571 Running the container in systemd mode causes the following changes:
1574 • Podman mounts tmpfs file systems on the following directories
1577 • /run
1579 • /run/lock
1581 • /tmp
1583 • /sys/fs/cgroup/systemd
1585 • /var/lib/journal
1587 • Podman sets the default stop signal to SIGRTMIN+3.
1591 • Podman sets container_uuid environment variable in the con‐
1593 tainer to the first 32 characters of the container id.
1594 This allows systemd to run in a confined container without any modifi‐
1598 cations.
1599 Note that on SELinux systems, systemd attempts to write to the cgroup
1602 file system. Containers writing to the cgroup file system are denied by
1603 default. The container_manage_cgroup boolean must be enabled for this
1604 to be allowed on an SELinux separated system.
1605 setsebool -P container_manage_cgroup true
1608 --timeout=seconds
1612 Maximum time a container is allowed to run before conmon sends it the
1613 kill signal. By default containers will run until they exit or are
1614 stopped by podman stop.
1615 --tls-verify
1618 Require HTTPS and verify certificates when contacting registries (de‐
1619 fault: true). If explicitly set to true, then TLS verification will be
1620 used. If set to false, then TLS verification will not be used. If not
1621 specified, TLS verification will be used unless the target registry is
1622 listed as an insecure registry in registries.conf.
1623 --tmpfs=fs
1626 Create a tmpfs mount.
1627 Mount a temporary filesystem (tmpfs) mount into a container, for exam‐
1630 ple:
1631 $ podman run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
1634 This command mounts a tmpfs at /tmp within the container. The supported
1638 mount options are the same as the Linux default mount flags. If you do
1639 not specify any options, the systems uses the following options:
1640 rw,noexec,nosuid,nodev.
1641 --tty, -t
1644 Allocate a pseudo-TTY. The default is false.
1645 When set to true, Podman will allocate a pseudo-tty and attach to the
1648 standard input of the container. This can be used, for example, to run
1649 a throwaway interactive shell. The default is false.
1650 NOTE: The --tty flag prevents redirection of standard output. It com‐
1653 bines STDOUT and STDERR, it can insert control characters, and it can
1654 hang pipes. This option should only be used when run interactively in a
1655 terminal. When feeding input to Podman, use -i only, not -it.
1656 echo "asdf" | podman run --rm -i someimage /bin/cat
1659 --tz=timezone
1663 Set timezone in container. This flag takes area-based timezones, GMT
1664 time, as well as local, which sets the timezone in the container to
1665 match the host machine. See /usr/share/zoneinfo/ for valid timezones.
1666 Remote connections use local containers.conf for defaults
1667 --uidmap=container_uid:from_uid:amount
1670 Run the container in a new user namespace using the supplied mapping.
1671 This option conflicts with the --userns and --subuidname options. This
1672 option provides a way to map host UIDs to container UIDs. It can be
1673 passed several times to map different ranges.
1674 The _fromuid value is based upon the user running the command, either
1677 rootful or rootless users. * rootful user: con‐
1678 tainer_uid:host_uid:amount * rootless user: container_uid:intermedi‐
1679 ate_uid:amount
1680 When podman run is called by a privileged user, the option --uidmap
1683 works as a direct mapping between host UIDs and container UIDs.
1684 host UID -> container UID
1687 The amount specifies the number of consecutive UIDs that will be
1690 mapped. If for example amount is 4 the mapping would look like:
1691 | host UID | container UID | | - | -
1694 | | _fromuid | _containeruid | | _fromuid + 1 | _containeruid +
1695 1 | | _fromuid + 2 | _containeruid + 2 | | _fromuid + 3 | _containeruid
1696 + 3 |
1697 When podman run is called by an unprivileged user (i.e. running root‐
1700 less), the value _fromuid is interpreted as an "intermediate UID". In
1701 the rootless case, host UIDs are not mapped directly to container UIDs.
1702 Instead the mapping happens over two mapping steps:
1703 host UID -> intermediate UID -> container UID
1706 The --uidmap option only influences the second mapping step.
1709 The first mapping step is derived by Podman from the contents of the
1712 file /etc/subuid and the UID of the user calling Podman.
1713 First mapping step:
1716 | host UID | intermediate UID |
1719 | - | - |
1720 | UID for the user starting Podman | 0 |
1721 | 1st subordinate UID for the user starting Podman | 1 |
1722 | 2nd subordinate UID for the user starting Podman | 2 |
1723 | 3rd subordinate UID for the user starting Podman | 3 |
1724 | nth subordinate UID for the user starting Podman | n |
1725 To be able to use intermediate UIDs greater than zero, the user needs
1728 to have subordinate UIDs configured in /etc/subuid. See subuid(5).
1729 The second mapping step is configured with --uidmap.
1732 If for example amount is 5 the second mapping step would look like:
1735 | intermediate UID | container UID | | - |
1738 - | | _fromuid | _containeruid | |
1739 _fromuid + 1 | _containeruid + 1 | | _fromuid + 2 | _con‐
1740 taineruid + 2 | | _fromuid + 3 | _containeruid + 3 | | _fromuid +
1741 4 | _containeruid + 4 |
1742 When running as rootless, Podman will use all the ranges configured in
1745 the /etc/subuid file.
1746 The current user ID is mapped to UID=0 in the rootless user namespace.
1749 Every additional range is added sequentially afterward:
1750 | host |rootless user namespace | length
1753 | | - | - | -
1754 | | $UID | 0 | 1
1755 | | 1 | $FIRST_RANGE_ID |
1756 $FIRST_RANGE_LENGTH | | 1+$FIRST_RANGE_LENGTH | $SECOND_RANGE_ID
1757 | $SECOND_RANGE_LENGTH|
1758 Even if a user does not have any subordinate UIDs in /etc/subuid,
1761 --uidmap could still be used to map the normal UID of the user to a
1762 container UID by running podman run --uidmap $container_uid:0:1 --user
1763 $container_uid ....
1764 Note: the --uidmap flag cannot be called in conjunction with the --pod
1767 flag as a uidmap cannot be set on the container level when in a pod.
1768 --ulimit=option
1771 Ulimit options. You can use host to copy the current configuration from
1772 the host.
1773 --umask=umask
1776 Set the umask inside the container. Defaults to 0022. Remote connec‐
1777 tions use local containers.conf for defaults
1778 --unsetenv=env
1781 Unset default environment variables for the container. Default environ‐
1782 ment variables include variables provided natively by Podman, environ‐
1783 ment variables configured by the image, and environment variables from
1784 containers.conf.
1785 --unsetenv-all=true|false
1788 Unset all default environment variables for the container. Default en‐
1789 vironment variables include variables provided natively by Podman, en‐
1790 vironment variables configured by the image, and environment variables
1791 from containers.conf.
1792 --user, -u=[user | user:group | uid | uid:gid | user:gid | uid:group ]
1795 Sets the username or UID used and optionally the groupname or GID for
1796 the specified command.
1797 Without this argument, the command will run as the user specified in
1800 the container image. Unless overridden by a USER command in the Con‐
1801 tainerfile or by a value passed to this option, this user generally de‐
1802 faults to root.
1803 When a user namespace is not in use, the UID and GID used within the
1806 container and on the host will match. When user namespaces are in use,
1807 however, the UID and GID in the container may correspond to another UID
1808 and GID on the host. In rootless containers, for example, a user name‐
1809 space is always used, and root in the container will by default corre‐
1810 spond to the UID and GID of the user invoking Podman.
1811 --userns=mode
1814 Set the user namespace mode for the container. It defaults to the POD‐
1815 MAN_USERNS environment variable. An empty value ("") means user name‐
1816 spaces are disabled unless an explicit mapping is set with the --uidmap
1817 and --gidmap options.
1818 Rootless user --userns=Key mappings:
1821 ┌────────┬───────────┬─────────────────────┐
1824 │Key │ Host User │ Container User │
1825 ├────────┼───────────┼─────────────────────┤
1826 │"" │ $UID │ 0 (Default User ac‐ │
1827 │ │ │ count mapped to │
1828 │ │ │ root user in con‐ │
1829 │ │ │ tainer.) │
1830 ├────────┼───────────┼─────────────────────┤
1831 │keep-id │ $UID │ $UID (Map user ac‐ │
1832 │ │ │ count to same UID │
1833 │ │ │ within container.) │
1834 ├────────┼───────────┼─────────────────────┤
1835 │auto │ $UID │ nil (Host User UID │
1836 │ │ │ is not mapped into │
1837 │ │ │ container.) │
1838 ├────────┼───────────┼─────────────────────┤
1839 │nomap │ $UID │ nil (Host User UID │
1840 │ │ │ is not mapped into │
1841 │ │ │ container.) │
1842 └────────┴───────────┴─────────────────────┘
1843 Valid mode values are:
1845 auto[:OPTIONS,...]: automatically create a unique user namespace.
1848 The --userns=auto flag, requires that the user name containers and a
1851 range of subordinate user ids that the Podman container is allowed to
1852 use be specified in the /etc/subuid and /etc/subgid files.
1853 Example: containers:2147483647:2147483648.
1856 Podman allocates unique ranges of UIDs and GIDs from the containers
1859 subordinate user ids. The size of the ranges is based on the number of
1860 UIDs required in the image. The number of UIDs and GIDs can be overrid‐
1861 den with the size option.
1862 The rootless option --userns=keep-id uses all the subuids and subgids
1865 of the user. Using --userns=auto when starting new containers will not
1866 work as long as any containers exist that were started with
1867 --userns=keep-id.
1868 Valid auto options:
1871 • gidmapping=_CONTAINER_GID:HOSTGID:SIZE: to force a GID mapping
1874 to be present in the user namespace.
1875 • size=SIZE: to specify an explicit size for the automatic user
1877 namespace. e.g. --userns=auto:size=8192. If size is not speci‐
1878 fied, auto will estimate a size for the user namespace.
1879 • uidmapping=_CONTAINER_UID:HOSTUID:SIZE: to force a UID mapping
1881 to be present in the user namespace.
1882 container:id: join the user namespace of the specified container.
1886 host: run in the user namespace of the caller. The processes running in
1889 the container will have the same privileges on the host as any other
1890 process launched by the calling user (default).
1891 keep-id: creates a user namespace where the current rootless user's
1894 UID:GID are mapped to the same values in the container. This option is
1895 ignored for containers created by the root user.
1896 nomap: creates a user namespace where the current rootless user's
1899 UID:GID are not mapped into the container. This option is ignored for
1900 containers created by the root user.
1901 ns:namespace: run the container in the given existing user namespace.
1904 private: create a new namespace for the container. This option is in‐
1907 compatible with --gidmap, --uidmap, --subuidname and --subgidname.
1908 --uts=mode
1911 Set the UTS namespace mode for the container. The following values are
1912 supported:
1913 • host: use the host's UTS namespace inside the container.
1916 • private: create a new namespace for the container (default).
1918 • ns:[path]: run the container in the given existing UTS name‐
1920 space.
1921 • container:[container]: join the UTS namespace of the specified
1923 container.
1924 --variant=VARIANT
1928 Use VARIANT instead of the default architecture variant of the con‐
1929 tainer image. Some images can use multiple variants of the arm archi‐
1930 tectures, such as arm/v5 and arm/v7.
1931 --volume, -v[=[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]]
1934 Create a bind mount. If you specify /HOST-DIR:/CONTAINER-DIR, Podman
1935 bind mounts host-dir in the host to CONTAINER-DIR in the Podman con‐
1936 tainer. Similarly, SOURCE-VOLUME:/CONTAINER-DIR will mount the volume
1937 in the host to the container. If no such named volume exists, Podman
1938 will create one. (Note when using the remote client, including Mac and
1939 Windows (excluding WSL2) machines, the volumes will be mounted from the
1940 remote server, not necessarily the client machine.)
1941 The options is a comma-separated list and can be: [1] ⟨#Footnote1⟩
1944 • rw|ro
1947 • z|Z
1949 • [r]shared|[r]slave|[r]private[r]unbindable
1951 • [r]bind
1953 • [no]exec
1955 • [no]dev
1957 • [no]suid
1959 • [O]
1961 • [U]
1963 The CONTAINER-DIR must be an absolute path such as /src/docs. The vol‐
1967 ume will be mounted into the container at this directory.
1968 Volumes may specify a source as well, as either a directory on the host
1971 or the name of a named volume. If no source is given, the volume will
1972 be created as an anonymously named volume with a randomly generated
1973 name, and will be removed when the container is removed via the --rm
1974 flag or podman rm --volumes.
1975 If a volume source is specified, it must be a path on the host or the
1978 name of a named volume. Host paths are allowed to be absolute or rela‐
1979 tive; relative paths are resolved relative to the directory Podman is
1980 run in. If the source does not exist, Podman will return an error.
1981 Users must pre-create the source files or directories.
1982 Any source that does not begin with a . or / will be treated as the
1985 name of a named volume. If a volume with that name does not exist, it
1986 will be created. Volumes created with names are not anonymous, and
1987 they are not removed by the --rm option and the podman rm --volumes
1988 command.
1989 You can specify multiple -v options to mount one or more volumes into a
1992 container.
1993 Write Protected Volume Mounts
1996 You can add :ro or :rw option to mount a volume in read-only or read-
1999 write mode, respectively. By default, the volumes are mounted read-
2000 write.
2001 Chowning Volume Mounts
2004 By default, Podman does not change the owner and group of source volume
2007 directories mounted into containers. If a container is created in a new
2008 user namespace, the UID and GID in the container may correspond to an‐
2009 other UID and GID on the host.
2010 The :U suffix tells Podman to use the correct host UID and GID based on
2013 the UID and GID within the container, to change recursively the owner
2014 and group of the source volume.
2015 Warning use with caution since this will modify the host filesystem.
2018 Labeling Volume Mounts
2021 Labeling systems like SELinux require that proper labels are placed on
2024 volume content mounted into a container. Without a label, the security
2025 system might prevent the processes running inside the container from
2026 using the content. By default, Podman does not change the labels set by
2027 the OS.
2028 To change a label in the container context, you can add either of two
2031 suffixes :z or :Z to the volume mount. These suffixes tell Podman to
2032 relabel file objects on the shared volumes. The z option tells Podman
2033 that two containers share the volume content. As a result, Podman la‐
2034 bels the content with a shared content label. Shared volume labels al‐
2035 low all containers to read/write content. The Z option tells Podman to
2036 label the content with a private unshared label.
2037 Note: Do not relabel system files and directories. Relabeling system
2040 content might cause other confined services on your machine to fail.
2041 For these types of containers we recommend disabling SELinux separa‐
2042 tion. The option --security-opt label=disable disables SELinux separa‐
2043 tion for the container. For example if a user wanted to volume mount
2044 their entire home directory into a container, they need to disable
2045 SELinux separation.
2046 $ podman run --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file
2049 Overlay Volume Mounts
2053 The :O flag tells Podman to mount the directory from the host as a tem‐
2056 porary storage using the overlay file system. The container processes
2057 can modify content within the mountpoint which is stored in the con‐
2058 tainer storage in a separate directory. In overlay terms, the source
2059 directory will be the lower, and the container storage directory will
2060 be the upper. Modifications to the mount point are destroyed when the
2061 container finishes executing, similar to a tmpfs mount point being un‐
2062 mounted.
2063 For advanced users overlay option also supports custom non-volatile up‐
2066 perdir and workdir for the overlay mount. Custom upperdir and workdir
2067 can be fully managed by the users themselves and podman will not remove
2068 it on lifecycle completion. Example :O,upperdir=/some/up‐
2069 per,workdir=/some/work
2070 Subsequent executions of the container will see the original source di‐
2073 rectory content, any changes from previous container executions no
2074 longer exist.
2075 One use case of the overlay mount is sharing the package cache from the
2078 host into the container to allow speeding up builds.
2079 Note:
2082 - The `O` flag conflicts with other options listed above.
2085 Content mounted into the container is labeled with the private label.
2089 On SELinux systems, labels in the source directory must be read‐
2090 able by the container label. Usually containers can read/execute con‐
2091 tainer_share_t and can read/write container_file_t. If you cannot
2092 change the labels on a source volume, SELinux container separation must
2093 be disabled for the container to work.
2094 - The source directory mounted into the container with an overlay
2095 mount should not be modified, it can cause unexpected failures. It is
2096 recommended that you do not modify the directory until the container
2097 finishes running.
2098 Only the current container can use a private volume.
2101 Mounts propagation
2104 By default bind mounted volumes are private. That means any mounts done
2107 inside container will not be visible on host and vice versa. One can
2108 change this behavior by specifying a volume mount propagation property.
2109 Making a volume shared mounts done under that volume inside container
2110 will be visible on host and vice versa. Making a volume slave enables
2111 only one way mount propagation and that is mounts done on host under
2112 that volume will be visible inside container but not the other way
2113 around. [1] ⟨#Footnote1⟩
2114 To control mount propagation property of a volume one can use the
2117 [r]shared, [r]slave, [r]private or the [r]unbindable propagation flag.
2118 For mount propagation to work the source mount point (the mount point
2119 where source dir is mounted on) has to have the right propagation prop‐
2120 erties. For shared volumes, the source mount point has to be shared.
2121 And for slave volumes, the source mount point has to be either shared
2122 or slave. [1] ⟨#Footnote1⟩
2123 If you want to recursively mount a volume and all of its submounts into
2126 a container, then you can use the rbind option. By default the bind op‐
2127 tion is used, and submounts of the source directory will not be mounted
2128 into the container.
2129 Mounting the volume with the nosuid options means that SUID applica‐
2132 tions on the volume will not be able to change their privilege. By de‐
2133 fault volumes are mounted with nosuid.
2134 Mounting the volume with the noexec option means that no executables on
2137 the volume will be able to be executed within the container.
2138 Mounting the volume with the nodev option means that no devices on the
2141 volume will be able to be used by processes within the container. By
2142 default volumes are mounted with nodev.
2143 If the host-dir is a mount point, then dev, suid, and exec options are
2146 ignored by the kernel.
2147 Use df $hostdir to figure out the source mount, and then use findmnt -o
2150 TARGET,PROPAGATION source-mount-dir to figure out propagation proper‐
2151 ties of source mount. If findmnt[4m(1) utility is not available, then one
2152 can look at mount entry for source mount point in /proc/self/mountinfo.
2153 Look at the "optional fields" and see if any propagation properties are
2154 specified. In there, shared:N means the mount is shared, master:N
2155 means mount is slave, and if nothing is there, the mount is private.
2156 [1] ⟨#Footnote1⟩
2157 To change propagation properties of a mount point, use mount(8) com‐
2160 mand. For example, if one wants to bind mount source directory /foo,
2161 one can do mount --bind /foo /foo and mount --make-private --make-
2162 shared /foo. This will convert /foo into a shared mount point. Alterna‐
2163 tively, one can directly change propagation properties of source mount.
2164 Say, if / is source mount for /foo, then use mount --make-shared / to
2165 convert / into a shared mount.
2166 Note: if the user only has access rights via a group, accessing the
2169 volume from inside a rootless container will fail. Use the --group-add
2170 keep-groups flag to pass the user's supplementary group access into the
2171 container.
2172 --volumes-from[=CONTAINER[:OPTIONS]]
2175 Mount volumes from the specified container(s). Used to share volumes
2176 between containers. The options is a comma-separated list with the fol‐
2177 lowing available elements:
2178 • rw|ro
2181 • z
2183 Mounts already mounted volumes from a source container onto another
2187 container. You must supply the source's container-id or container-name.
2188 To share a volume, use the --volumes-from option when running the tar‐
2189 get container. You can share volumes even if the source container is
2190 not running.
2191 By default, Podman mounts the volumes in the same mode (read-write or
2194 read-only) as it is mounted in the source container. You can change
2195 this by adding a ro or rw option.
2196 Labeling systems like SELinux require that proper labels are placed on
2199 volume content mounted into a container. Without a label, the security
2200 system might prevent the processes running inside the container from
2201 using the content. By default, Podman does not change the labels set by
2202 the OS.
2203 To change a label in the container context, you can add z to the volume
2206 mount. This suffix tells Podman to relabel file objects on the shared
2207 volumes. The z option tells Podman that two containers share the volume
2208 content. As a result, Podman labels the content with a shared content
2209 label. Shared volume labels allow all containers to read/write content.
2210 If the location of the volume from the source container overlaps with
2213 data residing on a target container, then the volume hides that data on
2214 the target.
2215 --workdir, -w=dir
2218 Working directory inside the container.
2219 The default working directory for running binaries within a container
2222 is the root directory (/). The image developer can set a different de‐
2223 fault with the WORKDIR instruction. The operator can override the work‐
2224 ing directory by using the -w option.
2225
2228 The exit code from podman run gives information about why the container
2229 failed to run or why it exited. When podman run exits with a non-zero
2230 code, the exit codes follow the chroot(1) standard, see below:
2231 125 The error is with Podman itself
2234 $ podman run --foo busybox; echo $?
2237 Error: unknown flag: --foo
2238 125
2239 126 The contained command cannot be invoked
2243 $ podman run busybox /etc; echo $?
2246 Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error
2247 126
2248 127 The contained command cannot be found
2252 $ podman run busybox foo; echo $?
2255 Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error
2256 127
2257 Exit code contained command exit code
2261 $ podman run busybox /bin/sh -c 'exit 3'; echo $?
2264 3
2265
2269 Running container in read-only mode
2270 During container image development, containers often need to write to
2271 the image content. Installing packages into /usr, for example. In pro‐
2272 duction, applications seldom need to write to the image. Container ap‐
2273 plications write to volumes if they need to write to file systems at
2274 all. Applications can be made more secure by running them in read-only
2275 mode using the --read-only switch. This protects the containers image
2276 from modification. Read only containers may still need to write tempo‐
2277 rary data. The best way to handle this is to mount tmpfs directories on
2278 /run and /tmp.
2279 $ podman run --read-only -i -t fedora /bin/bash
2282 $ podman run --read-only --read-only-tmpfs=false --tmpfs /run -i -t fedora /bin/bash
2284 Exposing log messages from the container to the host's log
2288 If you want messages that are logged in your container to show up in
2289 the host's syslog/journal then you should bind mount the /dev/log di‐
2290 rectory as follows.
2291 $ podman run -v /dev/log:/dev/log -i -t fedora /bin/bash
2294 From inside the container you can test this by sending a message to the
2298 log.
2299 (bash)# logger "Hello from my container"
2302 Then exit and check the journal.
2306 (bash)# exit
2309 $ journalctl -b | grep Hello
2311 This should list the message sent to logger.
2315 Attaching to one or more from STDIN, STDOUT, STDERR
2318 If you do not specify -a, Podman will attach everything (stdin, stdout,
2319 stderr). You can specify to which of the three standard streams
2320 (stdin, stdout, stderr) you'd like to connect instead, as in:
2321 $ podman run -a stdin -a stdout -i -t fedora /bin/bash
2324 Sharing IPC between containers
2328 Using shm_server.c available here:
2329 https://www.cs.cf.ac.uk/Dave/C/node27.html
2330 Testing --ipc=host mode:
2333 Host shows a shared memory segment with 7 pids attached, happens to be
2336 from httpd:
2337 $ sudo ipcs -m
2340 ------ Shared Memory Segments --------
2342 key shmid owner perms bytes nattch status
2343 0x01128e25 0 root 600 1000 7
2344 Now run a regular container, and it correctly does NOT see the shared
2348 memory segment from the host:
2349 $ podman run -it shm ipcs -m
2352 ------ Shared Memory Segments --------
2354 key shmid owner perms bytes nattch status
2355 Run a container with the new --ipc=host option, and it now sees the
2359 shared memory segment from the host httpd:
2360 $ podman run -it --ipc=host shm ipcs -m
2363 ------ Shared Memory Segments --------
2365 key shmid owner perms bytes nattch status
2366 0x01128e25 0 root 600 1000 7
2367 Testing --ipc=container:id mode:
2371 Start a container with a program to create a shared memory segment:
2374 $ podman run -it shm bash
2377 $ sudo shm/shm_server &
2378 $ sudo ipcs -m
2379 ------ Shared Memory Segments --------
2381 key shmid owner perms bytes nattch status
2382 0x0000162e 0 root 666 27 1
2383 Create a 2nd container correctly shows no shared memory segment from
2387 1st container:
2388 $ podman run shm ipcs -m
2391 ------ Shared Memory Segments --------
2393 key shmid owner perms bytes nattch status
2394 Create a 3rd container using the --ipc=container:id option, now it
2398 shows the shared memory segment from the first:
2399 $ podman run -it --ipc=container:ed735b2264ac shm ipcs -m
2402 $ sudo ipcs -m
2403 ------ Shared Memory Segments --------
2405 key shmid owner perms bytes nattch status
2406 0x0000162e 0 root 666 27 1
2407 Mapping Ports for External Usage
2411 The exposed port of an application can be mapped to a host port using
2412 the -p flag. For example, an httpd port 80 can be mapped to the host
2413 port 8080 using the following:
2414 $ podman run -p 8080:80 -d -i -t fedora/httpd
2417 Mounting External Volumes
2421 To mount a host directory as a container volume, specify the absolute
2422 path to the directory and the absolute path for the container directory
2423 separated by a colon. If the source is a named volume maintained by
2424 Podman, it is recommended to use its name rather than the path to the
2425 volume. Otherwise the volume will be considered as an orphan and wiped
2426 if you execute podman volume prune:
2427 $ podman run -v /var/db:/data1 -i -t fedora bash
2430 $ podman run -v data:/data2 -i -t fedora bash
2432 $ podman run -v /var/cache/dnf:/var/cache/dnf:O -ti fedora dnf -y update
2434 $ podman run -d -e MYSQL_ROOT_PASSWORD=root --user mysql --userns=keep-id -v ~/data:/var/lib/mysql:z,U mariadb
2436 Using --mount flags to mount a host directory as a container folder,
2440 specify the absolute path to the directory or the volume name, and the
2441 absolute path within the container directory:
2442 $ podman run --mount type=bind,src=/var/db,target=/data1 busybox sh
2445 $ podman run --mount type=bind,src=volume-name,target=/data1 busybox sh
2447 When using SELinux, be aware that the host has no knowledge of con‐
2451 tainer SELinux policy. Therefore, in the above example, if SELinux pol‐
2452 icy is enforced, the /var/db directory is not writable to the con‐
2453 tainer. A "Permission Denied" message will occur and an avc: message in
2454 the host's syslog.
2455 To work around this, at time of writing this man page, the following
2458 command needs to be run in order for the proper SELinux policy type la‐
2459 bel to be attached to the host directory:
2460 $ chcon -Rt svirt_sandbox_file_t /var/db
2463 Now, writing to the /data1 volume in the container will be allowed and
2467 the changes will also be reflected on the host in /var/db.
2468 Using alternative security labeling
2471 You can override the default labeling scheme for each container by
2472 specifying the --security-opt flag. For example, you can specify the
2473 MCS/MLS level, a requirement for MLS systems. Specifying the level in
2474 the following command allows you to share the same content between con‐
2475 tainers.
2476 podman run --security-opt label=level:s0:c100,c200 -i -t fedora bash
2479 An MLS example might be:
2483 $ podman run --security-opt label=level:TopSecret -i -t rhel7 bash
2486 To disable the security labeling for this container versus running with
2490 the
2491 --permissive flag, use the following command:
2494 $ podman run --security-opt label=disable -i -t fedora bash
2495 If you want a tighter security policy on the processes within a con‐
2499 tainer, you can specify an alternate type for the container. You could
2500 run a container that is only allowed to listen on Apache ports by exe‐
2501 cuting the following command:
2502 $ podman run --security-opt label=type:svirt_apache_t -i -t centos bash
2505 Note you would have to write policy defining a svirt_apache_t type.
2509 To mask additional specific paths in the container, specify the paths
2512 separated by a colon using the mask option with the --security-opt
2513 flag.
2514 $ podman run --security-opt mask=/foo/bar:/second/path fedora bash
2517 To unmask all the paths that are masked by default, set the unmask op‐
2521 tion to ALL. Or to only unmask specific paths, specify the paths as
2522 shown above with the mask option.
2523 $ podman run --security-opt unmask=ALL fedora bash
2526 To unmask all the paths that start with /proc, set the unmask option to
2530 /proc/*.
2531 $ podman run --security-opt unmask=/proc/* fedora bash
2534 $ podman run --security-opt unmask=/foo/bar:/sys/firmware fedora bash
2538 Setting device weight
2542 If you want to set /dev/sda device weight to 200, you can specify the
2543 device weight by --blkio-weight-device flag. Use the following command:
2544 $ podman run -it --blkio-weight-device "/dev/sda:200" ubuntu
2547 Using a podman container with input from a pipe
2551 $ echo "asdf" | podman run --rm -i --entrypoint /bin/cat someimage
2552 asdf
2553 Setting automatic user namespace separated containers
2557 # podman run --userns=auto:size=65536 ubi8-micro cat /proc/self/uid_map
2558 0 2147483647 65536
2559 # podman run --userns=auto:size=65536 ubi8-micro cat /proc/self/uid_map
2560 0 2147549183 65536
2561 Setting Namespaced Kernel Parameters (Sysctls)
2565 The --sysctl sets namespaced kernel parameters (sysctls) in the con‐
2566 tainer. For example, to turn on IP forwarding in the containers network
2567 namespace, run this command:
2568 $ podman run --sysctl net.ipv4.ip_forward=1 someimage
2571 Note that not all sysctls are namespaced. Podman does not support
2575 changing sysctls inside of a container that also modify the host sys‐
2576 tem. As the kernel evolves we expect to see more sysctls become names‐
2577 paced.
2578 See the definition of the --sysctl option above for the current list of
2581 supported sysctls.
2582 Set UID/GID mapping in a new user namespace
2585 Running a container in a new user namespace requires a mapping of the
2586 uids and gids from the host.
2587 $ podman run --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
2590 Configuring Storage Options from the command line
2594 Podman allows for the configuration of storage by changing the values
2595 in the /etc/container/storage.conf or by using global options. This
2596 shows how to setup and use fuse-overlayfs for a one time run of busybox
2597 using global options.
2598 podman --log-level=debug --storage-driver overlay --storage-opt "overlay.mount_program=/usr/bin/fuse-overlayfs" run busybox /bin/sh
2601 Configure timezone in a container
2605 $ podman run --tz=local alpine date
2606 $ podman run --tz=Asia/Shanghai alpine date
2607 $ podman run --tz=US/Eastern alpine date
2608 Adding dependency containers
2612 The first container, container1, is not started initially, but must be
2613 running before container2 will start. The podman run command will
2614 start the container automatically before starting container2.
2615 $ podman create --name container1 -t -i fedora bash
2618 $ podman run --name container2 --requires container1 -t -i fedora bash
2619 Multiple containers can be required.
2623 $ podman create --name container1 -t -i fedora bash
2626 $ podman create --name container2 -t -i fedora bash
2627 $ podman run --name container3 --requires container1,container2 -t -i fedora bash
2628 Configure keep supplemental groups for access to volume
2632 $ podman run -v /var/lib/design:/var/lib/design --group-add keep-groups ubi8
2633 Configure execution domain for containers using personality flag
2637 $ podman run --name container1 --personaity=LINUX32 fedora bash
2638 Run a container with external rootfs mounted as an overlay
2642 $ podman run --name container1 --rootfs /path/to/rootfs:O bash
2643 Handling Timezones in java applications in a container.
2647 In order to use a timezone other than UTC when running a Java applica‐
2648 tion within a container, the TZ environment variable must be set within
2649 the container. Java applications will ignore the value set with the
2650 --tz option.
2651 # Example run
2654 podman run -ti --rm -e TZ=EST mytzimage
2655 lrwxrwxrwx. 1 root root 29 Nov 3 08:51 /etc/localtime -> ../usr/share/zoneinfo/Etc/UTC
2656 Now with default timezone:
2657 Fri Nov 19 18:10:55 EST 2021
2658 Java default sees the following timezone:
2659 2021-11-19T18:10:55.651130-05:00
2660 Forcing UTC:
2661 Fri Nov 19 23:10:55 UTC 2021
2662 Run a container connected to two networks (called net1 and net2) with a
2666 static ip
2667 $ podman run --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip addr
2668 Rootless Containers
2672 Podman runs as a non-root user on most systems. This feature requires
2673 that a new enough version of shadow-utils be installed. The shadow-
2674 utils package must include the newuidmap(1) and newgidmap(1) executa‐
2675 bles.
2676 In order for users to run rootless, there must be an entry for their
2679 username in /etc/subuid and /etc/subgid which lists the UIDs for their
2680 user namespace.
2681 Rootless Podman works better if the fuse-overlayfs and slirp4netns
2684 packages are installed. The fuse-overlayfs package provides a
2685 userspace overlay storage driver, otherwise users need to use the vfs
2686 storage driver, which is diskspace expensive and does not perform well.
2687 slirp4netns is required for VPN, without it containers need to be run
2688 with the --network=host flag.
2689
2692 Environment variables within containers can be set using multiple dif‐
2693 ferent options, in the following order of precedence (later entries
2694 override earlier entries):
2695 • Container image: Any environment variables specified in the
2698 container image.
2699 • --http-proxy: By default, several environment variables will
2701 be passed in from the host, such as http_proxy and no_proxy.
2702 See --http-proxy for details.
2703 • --env-host: Host environment of the process executing Podman
2705 is added.
2706 • --env-file: Any environment variables specified via env-files.
2708 If multiple files specified, then they override each other in
2709 order of entry.
2710 • --env: Any environment variables specified will override pre‐
2712 vious settings.
2713 Run containers and set the environment ending with a * and a *****:
2717 $ export ENV1=a
2720 $ podman run --env ENV* alpine printenv ENV1
2721 a
2722 $ podman run --env ENV*****=b alpine printenv ENV*****
2724 b
2725
2729 When Podman starts a container it actually executes the conmon program,
2730 which then executes the OCI Runtime. Conmon is the container monitor.
2731 It is a small program whose job is to watch the primary process of the
2732 container, and if the container dies, save the exit code. It also
2733 holds open the tty of the container, so that it can be attached to
2734 later. This is what allows Podman to run in detached mode (back‐
2735 grounded), so Podman can exit but conmon continues to run. Each con‐
2736 tainer has their own instance of conmon. Conmon waits for the container
2737 to exit, gathers and saves the exit code, and then launches a Podman
2738 process to complete the container cleanup, by shutting down the network
2739 and storage. For more information on conmon, please reference the
2740 conmon(8) man page.
2741
2744 /etc/subuid
2745 /etc/subgid
2748 NOTE: Use the environment variable TMPDIR to change the temporary stor‐
2751 age location of downloaded container images. Podman defaults to use
2752 /var/tmp.
2753
2756 podman(1), podman-save(1), podman-ps(1), podman-attach(1), podman-pod-
2757 create(1), podman-port(1), podman-start(1), podman-kill(1), podman-
2758 stop(1), podman-generate-systemd(1), podman-rm(1), subgid(5), sub‐
2759 uid(5), containers.conf(5), systemd.unit(5), setsebool(8),
2760 slirp4netns(1), fuse-overlayfs(1), proc(5), conmon(8), personality(2)
2761
2764 September 2018, updated by Kunal Kushwaha <kushwaha_ku‐
2765 nal_v7@lab.ntt.co.jp>
2766 October 2017, converted from Docker documentation to Podman by Dan
2769 Walsh for Podman <dwalsh@redhat.com>
2770 November 2015, updated by Sally O'Malley <somalley@redhat.com>
2773 June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2776 April 2014, Originally compiled by William Henry <whenry@redhat.com>
2779 based on docker.com source material and internal work.
2780
2783 1: The Podman project is committed to inclusivity, a core value of open
2784 source. The master and slave mount propagation terminology used here is
2785 problematic and divisive, and should be changed. However, these terms
2786 are currently used within the Linux kernel and must be used as-is at
2787 this time. When the kernel maintainers rectify this usage, Podman will
2788 follow suit immediately.
2789 podman-run(1)()