1podman-run(1) General Commands Manual 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 (or /var/run/.containerenv for FreeBSD con‐
39 tainers). When using the --privileged flag the .containerenv contains
40 name/value pairs indicating the container engine version, whether the
41 engine is running in rootless mode, the container name and ID, as well
42 as the image name and ID that the container is based on. Note:
43 /run/.containerenv will not be created when a volume is mounted on
44 /run.
45 When running from a user defined network namespace, the
48 /etc/netns/NSNAME/resolv.conf will be used if it exists, otherwise
49 /etc/resolv.conf will be used.
50 Default settings are defined in containers.conf. Most settings for re‐
53 mote connections use the servers containers.conf, except when docu‐
54 mented in man pages.
55
58 The image is specified using transport:path format. If no transport is
59 specified, the docker (container registry) transport is used by de‐
60 fault. For remote Podman, including Mac and Windows (excluding WSL2)
61 machines, docker is the only allowed transport.
62 dir:path
65 An existing local directory path storing the manifest, layer tarballs
66 and signatures as individual files. This is a non-standardized format,
67 primarily useful for debugging or noninvasive container inspection.
68 $ podman save --format docker-dir fedora -o /tmp/fedora
71 $ podman run dir:/tmp/fedora echo hello
72 docker://docker-reference (Default)
76 An image reference stored in a remote container image registry. Exam‐
77 ple: "quay.io/podman/stable:latest". The reference can include a path
78 to a specific registry; if it does not, the registries listed in reg‐
79 istries.conf are queried to find a matching image. By default, creden‐
80 tials from podman login (stored at $XDG_RUNTIME_DIR/contain‐
81 ers/auth.json by default) are used to authenticate; otherwise it falls
82 back to using credentials in $HOME/.docker/config.json.
83 $ podman run registry.fedoraproject.org/fedora:latest echo hello
86 docker-archive:path[:docker-reference] An image stored in the docker
90 save formatted file. docker-reference is only used when creating such a
91 file, and it must not contain a digest.
92 $ podman save --format docker-archive fedora -o /tmp/fedora
95 $ podman run docker-archive:/tmp/fedora echo hello
96 docker-daemon:docker-reference
100 An image in docker-reference format stored in the docker daemon in‐
101 ternal storage. The docker-reference can also be an image ID (docker-
102 daemon:algo:digest).
103 $ sudo docker pull fedora
106 $ sudo podman run docker-daemon:docker.io/library/fedora echo hello
107 oci-archive:path:tag
111 An image in a directory compliant with the "Open Container Image Lay‐
112 out Specification" at the specified path and specified with a tag.
113 $ podman save --format oci-archive fedora -o /tmp/fedora
116 $ podman run oci-archive:/tmp/fedora echo hello
117
121 --add-host=host:ip
122 Add a custom host-to-IP mapping (host:ip)
123 Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
126 tion can be set multiple times. Conflicts with the --no-hosts option.
127 --annotation=key=value
130 Add an annotation to the container. This option can be set multiple
131 times.
132 --arch=ARCH
135 Override the architecture, defaults to hosts, of the image to be
136 pulled. For example, arm. Unless overridden, subsequent lookups of the
137 same image in the local storage matches this architecture, regardless
138 of the host.
139 --attach, -a=stdin | stdout | stderr
142 Attach to STDIN, STDOUT or STDERR.
143 In foreground mode (the default when -d is not specified), podman run
146 can start the process in the container and attach the console to the
147 process's standard input, output, and error. It can even pretend to be
148 a TTY (this is what most command-line executables expect) and pass
149 along signals. The -a option can be set for each of stdin, stdout, and
150 stderr.
151 --authfile=path
154 Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
155 ers/auth.json on Linux, and $HOME/.config/containers/auth.json on Win‐
156 dows/macOS. The file is created by podman login. If the authorization
157 state is not found there, $HOME/.docker/config.json is checked, which
158 is set using docker login.
159 Note: There is also the option to override the default path of the au‐
162 thentication file by setting the REGISTRY_AUTH_FILE environment vari‐
163 able. This can be done with export REGISTRY_AUTH_FILE=path.
164 --blkio-weight=weight
167 Block IO relative weight. The weight is a value between 10 and 1000.
168 This option is not supported on cgroups V1 rootless systems.
171 --blkio-weight-device=device:weight
174 Block IO relative device weight.
175 --cap-add=capability
178 Add Linux capabilities.
179 --cap-drop=capability
182 Drop Linux capabilities.
183 --cgroup-conf=KEY=VALUE
186 When running on cgroup v2, specify the cgroup file to write to and its
187 value. For example --cgroup-conf=memory.high=1073741824 sets the mem‐
188 ory.high limit to 1GB.
189 --cgroup-parent=path
192 Path to cgroups under which the cgroup for the container is created. If
193 the path is not absolute, the path is considered to be relative to the
194 cgroups path of the init process. Cgroups are created if they do not
195 already exist.
196 --cgroupns=mode
199 Set the cgroup namespace mode for the container.
200 • host: use the host's cgroup namespace inside the container.
203 • container:id: join the namespace of the specified container.
205 • private: create a new cgroup namespace.
207 • ns:path: join the namespace at the specified path.
209 If the host uses cgroups v1, the default is set to host. On cgroups v2,
213 the default is private.
214 --cgroups=how
217 Determines whether the container creates CGroups.
218 Default is enabled.
221 The enabled option creates a new cgroup under the cgroup-parent. The
224 disabled option forces the container to not create CGroups, and thus
225 conflicts with CGroup options (--cgroupns and --cgroup-parent). The
226 no-conmon option disables a new CGroup only for the conmon process.
227 The split option splits the current CGroup in two sub-cgroups: one for
228 conmon and one for the container payload. It is not possible to set
229 --cgroup-parent with split.
230 --chrootdirs=path
233 Path to a directory inside the container that is treated as a chroot
234 directory. Any Podman managed file (e.g., /etc/resolv.conf,
235 /etc/hosts, etc/hostname) that is mounted into the root directory is
236 mounted into that location as well. Multiple directories are separated
237 with a comma.
238 --cidfile=file
241 Write the container ID to file. The file is removed along with the
242 container, except when used with podman --remote run on detached con‐
243 tainers.
244 --conmon-pidfile=file
247 Write the pid of the conmon process to a file. As conmon runs in a sep‐
248 arate process than Podman, this is necessary when using systemd to
249 restart Podman containers. (This option is not available with the re‐
250 mote Podman client, including Mac and Windows (excluding WSL2) ma‐
251 chines)
252 --cpu-period=limit
255 Set the CPU period for the Completely Fair Scheduler (CFS), which is a
256 duration in microseconds. Once the container's CPU quota is used up, it
257 will not be scheduled to run until the current period ends. Defaults to
258 100000 microseconds.
259 On some systems, changing the resource limits may not be allowed for
262 non-root users. For more details, see https://github.com/contain‐
263 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
264 source-limits-fails-with-a-permissions-error
265 This option is not supported on cgroups V1 rootless systems.
268 --cpu-quota=limit
271 Limit the CPU Completely Fair Scheduler (CFS) quota.
272 Limit the container's CPU usage. By default, containers run with the
275 full CPU resource. The limit is a number in microseconds. If a number
276 is provided, the container is allowed to use that much CPU time until
277 the CPU period ends (controllable via --cpu-period).
278 On some systems, changing the resource limits may not be allowed for
281 non-root users. For more details, see https://github.com/contain‐
282 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
283 source-limits-fails-with-a-permissions-error
284 This option is not supported on cgroups V1 rootless systems.
287 --cpu-rt-period=microseconds
290 Limit the CPU real-time period in microseconds.
291 Limit the container's Real Time CPU usage. This option tells the kernel
294 to restrict the container's Real Time CPU usage to the period speci‐
295 fied.
296 This option is only supported on cgroups V1 rootful systems.
299 --cpu-rt-runtime=microseconds
302 Limit the CPU real-time runtime in microseconds.
303 Limit the containers Real Time CPU usage. This option tells the kernel
306 to limit the amount of time in a given CPU period Real Time tasks may
307 consume. Ex: Period of 1,000,000us and Runtime of 950,000us means that
308 this container can consume 95% of available CPU and leave the remaining
309 5% to normal priority tasks.
310 The sum of all runtimes across containers cannot exceed the amount al‐
313 lotted to the parent cgroup.
314 This option is only supported on cgroups V1 rootful systems.
317 --cpu-shares, -c=shares
320 CPU shares (relative weight).
321 By default, all containers get the same proportion of CPU cycles. This
324 proportion can be modified by changing the container's CPU share
325 weighting relative to the combined weight of all the running contain‐
326 ers. Default weight is 1024.
327 The proportion only applies when CPU-intensive processes are running.
330 When tasks in one container are idle, other containers can use the
331 left-over CPU time. The actual amount of CPU time varies depending on
332 the number of containers running on the system.
333 For example, consider three containers, one has a cpu-share of 1024 and
336 two others have a cpu-share setting of 512. When processes in all three
337 containers attempt to use 100% of CPU, the first container receives 50%
338 of the total CPU time. If a fourth container is added with a cpu-share
339 of 1024, the first container only gets 33% of the CPU. The remaining
340 containers receive 16.5%, 16.5% and 33% of the CPU.
341 On a multi-core system, the shares of CPU time are distributed over all
344 CPU cores. Even if a container is limited to less than 100% of CPU
345 time, it can use 100% of each individual CPU core.
346 For example, consider a system with more than three cores. If the con‐
349 tainer C0 is started with --cpu-shares=512 running one process, and an‐
350 other container C1 with --cpu-shares=1024 running two processes, this
351 can result in the following division of CPU shares:
352 ┌────┬───────────┬─────┬──────────────┐
355 │PID │ container │ CPU │ CPU share │
356 ├────┼───────────┼─────┼──────────────┤
357 │100 │ C0 │ 0 │ 100% of CPU0 │
358 ├────┼───────────┼─────┼──────────────┤
359 │101 │ C1 │ 1 │ 100% of CPU1 │
360 ├────┼───────────┼─────┼──────────────┤
361 │102 │ C1 │ 2 │ 100% of CPU2 │
362 └────┴───────────┴─────┴──────────────┘
363 On some systems, changing the resource limits may not be allowed for
365 non-root users. For more details, see https://github.com/contain‐
366 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
367 source-limits-fails-with-a-permissions-error
368 This option is not supported on cgroups V1 rootless systems.
371 --cpus=number
374 Number of CPUs. The default is 0.0 which means no limit. This is short‐
375 hand for --cpu-period and --cpu-quota, therefore the option cannot be
376 specified with --cpu-period or --cpu-quota.
377 On some systems, changing the CPU limits may not be allowed for non-
380 root users. For more details, see https://github.com/containers/pod‐
381 man/blob/main/troubleshooting.md#26-running-containers-with-resource-
382 limits-fails-with-a-permissions-error
383 This option is not supported on cgroups V1 rootless systems.
386 --cpuset-cpus=number
389 CPUs in which to allow execution. Can be specified as a comma-separated
390 list (e.g. 0,1), as a range (e.g. 0-3), or any combination thereof
391 (e.g. 0-3,7,11-15).
392 On some systems, changing the resource limits may not be allowed for
395 non-root users. For more details, see https://github.com/contain‐
396 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
397 source-limits-fails-with-a-permissions-error
398 This option is not supported on cgroups V1 rootless systems.
401 --cpuset-mems=nodes
404 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
405 tive on NUMA systems.
406 If there are four memory nodes on the system (0-3), use --cpuset-
409 mems=0,1 then processes in the container only uses memory from the
410 first two memory nodes.
411 On some systems, changing the resource limits may not be allowed for
414 non-root users. For more details, see https://github.com/contain‐
415 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
416 source-limits-fails-with-a-permissions-error
417 This option is not supported on cgroups V1 rootless systems.
420 --decryption-key=key[:passphrase]
423 The [key[:passphrase]] to be used for decryption of images. Key can
424 point to keys and/or certificates. Decryption is tried with all keys.
425 If the key is protected by a passphrase, it is required to be passed in
426 the argument and omitted otherwise.
427 --detach, -d
430 Detached mode: run the container in the background and print the new
431 container ID. The default is false.
432 At any time run podman ps in the other shell to view a list of the run‐
435 ning containers. Reattach to a detached container with podman attach
436 command.
437 When attached via tty mode, detach from the container (and leave it
440 running) using a configurable key sequence. The default sequence is
441 ctrl-p,ctrl-q. Specify the key sequence using the --detach-keys op‐
442 tion, or configure it in the containers.conf file: see contain‐
443 ers.conf(5) for more information.
444 --detach-keys=sequence
447 Specify the key sequence for detaching a container. Format is a single
448 character [a-Z] or one or more ctrl-<value> characters where <value> is
449 one of: a-z, @, ^, [, , or _. Specifying "" disables this feature. The
450 default is ctrl-p,ctrl-q.
451 This option can also be set in containers.conf(5) file.
454 --device=host-device[:container-device][:permissions]
457 Add a host device to the container. Optional permissions parameter can
458 be used to specify device permissions by combining r for read, w for
459 write, and m for mknod(2).
460 Example: --device=/dev/sdc:/dev/xvdc:rwm.
463 Note: if host-device is a symbolic link then it is resolved first. The
466 container only stores the major and minor numbers of the host device.
467 Podman may load kernel modules required for using the specified device.
470 The devices that Podman loads modules for when necessary are:
471 /dev/fuse.
472 In rootless mode, the new device is bind mounted in the container from
475 the host rather than Podman creating it within the container space. Be‐
476 cause the bind mount retains its SELinux label on SELinux systems, the
477 container can get permission denied when accessing the mounted device.
478 Modify SELinux settings to allow containers to use all device labels
479 via the following command:
480 $ sudo setsebool -P container_use_devices=true
483 Note: if the user only has access rights via a group, accessing the de‐
486 vice from inside a rootless container fails. Use the --group-add keep-
487 groups flag to pass the user's supplementary group access into the con‐
488 tainer.
489 --device-cgroup-rule="type major:minor mode"
492 Add a rule to the cgroup allowed devices list. The rule is expected to
493 be in the format specified in the Linux kernel documentation (Documen‐
494 tation/cgroup-v1/devices.txt):
495 - type: a (all), c (char), or b (block);
496 - major and minor: either a number, or * for all;
497 - mode: a composition of r (read), w (write), and m (mknod(2)).
498 --device-read-bps=path:rate
501 Limit read rate (in bytes per second) from a device (e.g. --device-
502 read-bps=/dev/sda:1mb).
503 On some systems, changing the resource limits may not be allowed for
506 non-root users. For more details, see https://github.com/contain‐
507 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
508 source-limits-fails-with-a-permissions-error
509 This option is not supported on cgroups V1 rootless systems.
512 --device-read-iops=path:rate
515 Limit read rate (in IO operations per second) from a device (e.g. --de‐
516 vice-read-iops=/dev/sda:1000).
517 On some systems, changing the resource limits may not be allowed for
520 non-root users. For more details, see https://github.com/contain‐
521 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
522 source-limits-fails-with-a-permissions-error
523 This option is not supported on cgroups V1 rootless systems.
526 --device-write-bps=path:rate
529 Limit write rate (in bytes per second) to a device (e.g. --device-
530 write-bps=/dev/sda:1mb).
531 On some systems, changing the resource limits may not be allowed for
534 non-root users. For more details, see https://github.com/contain‐
535 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
536 source-limits-fails-with-a-permissions-error
537 This option is not supported on cgroups V1 rootless systems.
540 --device-write-iops=path:rate
543 Limit write rate (in IO operations per second) to a device (e.g. --de‐
544 vice-write-iops=/dev/sda:1000).
545 On some systems, changing the resource limits may not be allowed for
548 non-root users. For more details, see https://github.com/contain‐
549 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
550 source-limits-fails-with-a-permissions-error
551 This option is not supported on cgroups V1 rootless systems.
554 --disable-content-trust
557 This is a Docker-specific option to disable image verification to a
558 container registry and is not supported by Podman. This option is a
559 NOOP and provided solely for scripting compatibility.
560 --dns=ipaddr
563 Set custom DNS servers.
564 This option can be used to override the DNS configuration passed to the
567 container. Typically this is necessary when the host DNS configuration
568 is invalid for the container (e.g., 127.0.0.1). When this is the case
569 the --dns flag is necessary for every run.
570 The special value none can be specified to disable creation of /etc/re‐
573 solv.conf in the container by Podman. The /etc/resolv.conf file in the
574 image is used without changes.
575 This option cannot be combined with --network that is set to none or
578 container:id.
579 --dns-option=option
582 Set custom DNS options. Invalid if using --dns-option with --network
583 that is set to none or container:id.
584 --dns-search=domain
587 Set custom DNS search domains. Invalid if using --dns-search with
588 --network that is set to none or container:id. Use --dns-search=. to
589 remove the search domain.
590 --entrypoint="command" | '["command", arg1 , ...]'
593 Override the default ENTRYPOINT from the image.
594 The ENTRYPOINT of an image is similar to a COMMAND because it specifies
597 what executable to run when the container starts, but it is (purposely)
598 more difficult to override. The ENTRYPOINT gives a container its de‐
599 fault nature or behavior. When the ENTRYPOINT is set, the container
600 runs as if it were that binary, complete with default options. More op‐
601 tions can be passed in via the COMMAND. But, if a user wants to run
602 something else inside the container, the --entrypoint option allows a
603 new ENTRYPOINT to be specified.
604 Specify multi option commands in the form of a json string.
607 --env, -e=env
610 Set environment variables.
611 This option allows arbitrary environment variables that are available
614 for the process to be launched inside of the container. If an environ‐
615 ment variable is specified without a value, Podman checks the host en‐
616 vironment for a value and set the variable only if it is set on the
617 host. As a special case, if an environment variable ending in * is
618 specified without a value, Podman searches the host environment for
619 variables starting with the prefix and adds those variables to the con‐
620 tainer.
621 See Environment ⟨#environment⟩ note below for precedence and examples.
624 --env-file=file
627 Read in a line-delimited file of environment variables.
628 See Environment ⟨#environment⟩ note below for precedence and examples.
631 --env-host
634 Use host environment inside of the container. See Environment note be‐
635 low for precedence. (This option is not available with the remote Pod‐
636 man client, including Mac and Windows (excluding WSL2) machines)
637 --env-merge=env
640 Preprocess default environment variables for the containers. For exam‐
641 ple if image contains environment variable hello=world user can prepro‐
642 cess it using --env-merge hello=${hello}-some so new value is
643 hello=world-some.
644 Please note that if the environment variable hello is not present in
647 the image, then it'll be replaced by an empty string and so using
648 --env-merge hello=${hello}-some would result in the new value of
649 hello=-some, notice the leading - delimiter.
650 --expose=port
653 Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up
654 port redirection on the host system.
655 --gidmap=[flags]container_uid:from_uid[:amount]
658 Run the container in a new user namespace using the supplied GID map‐
659 ping. This option conflicts with the --userns and --subgidname options.
660 This option provides a way to map host GIDs to container GIDs in the
661 same way as --uidmap maps host UIDs to container UIDs. For details see
662 --uidmap.
663 Note: the --gidmap option cannot be called in conjunction with the
666 --pod option as a gidmap cannot be set on the container level when in a
667 pod.
668 --group-add=group | keep-groups
671 Assign additional groups to the primary user running within the con‐
672 tainer process.
673 • keep-groups is a special flag that tells Podman to keep the
676 supplementary group access.
677 Allows container to use the user's supplementary group access. If file
681 systems or devices are only accessible by the rootless user's group,
682 this flag tells the OCI runtime to pass the group access into the con‐
683 tainer. Currently only available with the crun OCI runtime. Note: keep-
684 groups is exclusive, other groups cannot be specified with this flag.
685 (Not available for remote commands, including Mac and Windows (exclud‐
686 ing WSL2) machines)
687 --group-entry=ENTRY
690 Customize the entry that is written to the /etc/group file within the
691 container when --user is used.
692 The variables $GROUPNAME, $GID, and $USERLIST are automatically re‐
695 placed with their value at runtime if present.
696 --health-cmd="command" | '["command", arg1 , ...]'
699 Set or alter a healthcheck command for a container. The command is a
700 command to be executed inside the container that determines the con‐
701 tainer health. The command is required for other healthcheck options to
702 be applied. A value of none disables existing healthchecks.
703 Multiple options can be passed in the form of a JSON array; otherwise,
706 the command is interpreted as an argument to /bin/sh -c.
707 --health-interval=interval
710 Set an interval for the healthchecks. An interval of disable results in
711 no automatic timer setup. The default is 30s.
712 --health-on-failure=action
715 Action to take once the container transitions to an unhealthy state.
716 The default is none.
717 • none: Take no action.
720 • kill: Kill the container.
722 • restart: Restart the container. Do not combine the restart
724 action with the --restart flag. When running inside of a sys‐
725 temd unit, consider using the kill or stop action instead to
726 make use of systemd's restart policy.
727 • stop: Stop the container.
729 --health-retries=retries
733 The number of retries allowed before a healthcheck is considered to be
734 unhealthy. The default value is 3.
735 --health-start-period=period
738 The initialization time needed for a container to bootstrap. The value
739 can be expressed in time format like 2m3s. The default value is 0s.
740 --health-startup-cmd="command" | '["command", arg1 , ...]'
743 Set a startup healthcheck command for a container. This command is exe‐
744 cuted inside the container and is used to gate the regular healthcheck.
745 When the startup command succeeds, the regular healthcheck begins and
746 the startup healthcheck ceases. Optionally, if the command fails for a
747 set number of attempts, the container is restarted. A startup
748 healthcheck can be used to ensure that containers with an extended
749 startup period are not marked as unhealthy until they are fully
750 started. Startup healthchecks can only be used when a regular
751 healthcheck (from the container's image or the --health-cmd option) is
752 also set.
753 --health-startup-interval=interval
756 Set an interval for the startup healthcheck. An interval of disable re‐
757 sults in no automatic timer setup. The default is 30s.
758 --health-startup-retries=retries
761 The number of attempts allowed before the startup healthcheck restarts
762 the container. If set to 0, the container is never restarted. The de‐
763 fault is 0.
764 --health-startup-success=retries
767 The number of successful runs required before the startup healthcheck
768 succeeds and the regular healthcheck begins. A value of 0 means that
769 any success begins the regular healthcheck. The default is 0.
770 --health-startup-timeout=timeout
773 The maximum time a startup healthcheck command has to complete before
774 it is marked as failed. The value can be expressed in a time format
775 like 2m3s. The default value is 30s.
776 --health-timeout=timeout
779 The maximum time allowed to complete the healthcheck before an interval
780 is considered failed. Like start-period, the value can be expressed in
781 a time format such as 1m22s. The default value is 30s.
782 --help
785 Print usage statement
786 --hostname, -h=name
789 Container host name
790 Sets the container host name that is available inside the container.
793 Can only be used with a private UTS namespace --uts=private (default).
794 If --pod is specified and the pod shares the UTS namespace (default)
795 the pod's hostname is used.
796 --hostuser=name
799 Add a user account to /etc/passwd from the host to the container. The
800 Username or UID must exist on the host system.
801 --http-proxy
804 By default proxy environment variables are passed into the container if
805 set for the Podman process. This can be disabled by setting the value
806 to false. The environment variables passed in include http_proxy,
807 https_proxy, ftp_proxy, no_proxy, and also the upper case versions of
808 those. This option is only needed when the host system must use a proxy
809 but the container does not use any proxy. Proxy environment variables
810 specified for the container in any other way overrides the values that
811 have been passed through from the host. (Other ways to specify the
812 proxy for the container include passing the values with the --env flag,
813 or hard coding the proxy environment at container build time.) When
814 used with the remote client it uses the proxy environment variables
815 that are set on the server process.
816 Defaults to true.
819 --image-volume=bind | tmpfs | ignore
822 Tells Podman how to handle the builtin image volumes. Default is bind.
823 • bind: An anonymous named volume is created and mounted into
826 the container.
827 • tmpfs: The volume is mounted onto the container as a tmpfs,
829 which allows the users to create content that disappears when
830 the container is stopped.
831 • ignore: All volumes are just ignored and no action is taken.
833 --init
837 Run an init inside the container that forwards signals and reaps pro‐
838 cesses. The container-init binary is mounted at /run/podman-init.
839 Mounting over /run breaks container execution.
840 --init-path=path
843 Path to the container-init binary.
844 --interactive, -i
847 When set to true, keep stdin open even if not attached. The default is
848 false.
849 --ip=ipv4
852 Specify a static IPv4 address for the container, for example
853 10.88.64.128. This option can only be used if the container is joined
854 to only a single network - i.e., --network=network-name is used at most
855 once - and if the container is not joining another container's network
856 namespace via --network=container:id. The address must be within the
857 network's IP address pool (default 10.88.0.0/16).
858 To specify multiple static IP addresses per container, set multiple
861 networks using the --network option with a static IP address specified
862 for each using the ip mode for that option.
863 --ip6=ipv6
866 Specify a static IPv6 address for the container, for example
867 fd46:db93:aa76:ac37::10. This option can only be used if the container
868 is joined to only a single network - i.e., --network=network-name is
869 used at most once - and if the container is not joining another con‐
870 tainer's network namespace via --network=container:id. The address
871 must be within the network's IPv6 address pool.
872 To specify multiple static IPv6 addresses per container, set multiple
875 networks using the --network option with a static IPv6 address speci‐
876 fied for each using the ip6 mode for that option.
877 --ipc=ipc
880 Set the IPC namespace mode for a container. The default is to create a
881 private IPC namespace.
882 • "": Use Podman's default, defined in containers.conf.
885 • container:id: reuses another container's shared memory, sema‐
887 phores, and message queues
888 • host: use the host's shared memory, semaphores, and message
890 queues inside the container. Note: the host mode gives the
891 container full access to local shared memory and is therefore
892 considered insecure.
893 • none: private IPC namespace, with /dev/shm not mounted.
895 • ns:path: path to an IPC namespace to join.
897 • private: private IPC namespace.
899 • shareable: private IPC namespace with a possibility to share
901 it with other containers.
902 --label, -l=key=value
906 Add metadata to a container.
907 --label-file=file
910 Read in a line-delimited file of labels.
911 --link-local-ip=ip
914 Not implemented.
915 --log-driver=driver
918 Logging driver for the container. Currently available options are k8s-
919 file, journald, none and passthrough, with json-file aliased to k8s-
920 file for scripting compatibility. (Default journald).
921 The podman info command below displays the default log-driver for the
924 system.
925 $ podman info --format '{{ .Host.LogDriver }}'
928 journald
929 The passthrough driver passes down the standard streams (stdin, stdout,
933 stderr) to the container. It is not allowed with the remote Podman
934 client, including Mac and Windows (excluding WSL2) machines, and on a
935 tty, since it is vulnerable to attacks via TIOCSTI.
936 --log-opt=name=value
939 Logging driver specific options.
940 Set custom logging configuration. The following *name*s are supported:
943 path: specify a path to the log file
946 (e.g. --log-opt path=/var/log/container/mycontainer.json);
947 max-size: specify a max size of the log file
950 (e.g. --log-opt max-size=10mb);
951 tag: specify a custom log tag for the container
954 (e.g. --log-opt tag="{{.ImageName}}". It supports the same keys as
955 podman inspect --format. This option is currently supported only by
956 the journald log driver.
957 --mac-address=address
960 Container network interface MAC address (e.g. 92:d0:c6:0a:29:33) This
961 option can only be used if the container is joined to only a single
962 network - i.e., --network=network-name is used at most once - and if
963 the container is not joining another container's network namespace via
964 --network=container:id.
965 Remember that the MAC address in an Ethernet network must be unique.
968 The IPv6 link-local address is based on the device's MAC address ac‐
969 cording to RFC4862.
970 To specify multiple static MAC addresses per container, set multiple
973 networks using the --network option with a static MAC address specified
974 for each using the mac mode for that option.
975 --memory, -m=number[unit]
978 Memory limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or
979 g (gibibytes).
980 Allows the memory available to a container to be constrained. If the
983 host supports swap memory, then the -m memory setting can be larger
984 than physical RAM. If a limit of 0 is specified (not using -m), the
985 container's memory is not limited. The actual limit may be rounded up
986 to a multiple of the operating system's page size (the value is very
987 large, that's millions of trillions).
988 This option is not supported on cgroups V1 rootless systems.
991 --memory-reservation=number[unit]
994 Memory soft limit. A unit can be b (bytes), k (kibibytes), m
995 (mebibytes), or g (gibibytes).
996 After setting memory reservation, when the system detects memory con‐
999 tention or low memory, containers are forced to restrict their consump‐
1000 tion to their reservation. So always set the value below --memory, oth‐
1001 erwise the hard limit takes precedence. By default, memory reservation
1002 is the same as memory limit.
1003 This option is not supported on cgroups V1 rootless systems.
1006 --memory-swap=number[unit]
1009 A limit value equal to memory plus swap. A unit can be b (bytes), k
1010 (kibibytes), m (mebibytes), or g (gibibytes).
1011 Must be used with the -m (--memory) flag. The argument value must be
1014 larger than that of
1015 -m (--memory) By default, it is set to double the value of --memory.
1016 Set number to -1 to enable unlimited swap.
1019 This option is not supported on cgroups V1 rootless systems.
1022 --memory-swappiness=number
1025 Tune a container's memory swappiness behavior. Accepts an integer be‐
1026 tween 0 and 100.
1027 This flag is only supported on cgroups V1 rootful systems.
1030 --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
1033 Attach a filesystem mount to the container
1034 Current supported mount TYPEs are bind, devpts, glob, image, ramfs,
1037 tmpfs and volume. [1] ⟨#Footnote1⟩
1038 e.g.
1041 type=bind,source=/path/on/host,destination=/path/in/container
1042 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
1044 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true
1046 type=devpts,destination=/dev/pts
1048 type=glob,src=/usr/lib/libfoo*,destination=/usr/lib,ro=true
1050 type=image,source=fedora,destination=/fedora-image,rw=true
1052 type=ramfs,tmpfs-size=512M,destination=/path/in/container
1054 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
1056 type=tmpfs,destination=/path/in/container,noswap
1058 type=volume,source=vol1,destination=/path/in/container,ro=true
1060 Common Options:
1062 · src, source: mount source spec for bind, glob, and volume. Mandatory for bind and glob.
1064 · dst, destination, target: mount destination spec.
1066 When source globs are specified without the destination directory,
1068 the files and directories are mounted with their complete path
1069 within the container. When the destination is specified, the
1070 files and directories matching the glob on the base file name
1071 on the destination directory are mounted. The option
1072 `type=glob,src=/foo*,destination=/tmp/bar` tells container engines
1073 to mount host files matching /foo* to the /tmp/bar/
1074 directory in the container.
1075 Options specific to volume:
1077 · ro, readonly: true or false (default).
1079 . 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.
1081 · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container.
1083 The idmap option supports a custom mapping that can be different than the user namespace used by the container.
1084 The mapping can be specified after the idmap option like: `idmap=uids=0-1-10#10-11-10;gids=0-100-10`. For each triplet, the first value is the
1085 start of the backing file system IDs that are mapped to the second value on the host. The length of this mapping is given in the third value.
1086 Multiple ranges are separated with #. If the specified mapping is prepended with a '@' then the mapping is considered relative to the container
1087 user namespace. The host ID for the mapping is changed to account for the relative position of the container user in the container user namespace.
1088 Options specific to image:
1090 · rw, readwrite: true or false (default).
1092 Options specific to bind and glob:
1094 · ro, readonly: true or false (default).
1096 · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2).
1098 . bind-nonrecursive: do not set up a recursive bind mount. By default it is recursive.
1100 . relabel: shared, private.
1102 · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container.
1104 . 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.
1106 Options specific to tmpfs and ramfs:
1108 · ro, readonly: true or false (default).
1110 · tmpfs-size: Size of the tmpfs/ramfs mount in bytes. Unlimited by default in Linux.
1112 · tmpfs-mode: File mode of the tmpfs/ramfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
1114 · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs/ramfs. Used by default.
1116 · notmpcopyup: Disable copying files from the image to the tmpfs/ramfs.
1118 . 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.
1120 Options specific to devpts:
1122 · uid: UID of the file owner (default 0).
1124 · gid: GID of the file owner (default 0).
1126 · mode: permission mask for the file (default 600).
1128 · max: maximum number of PTYs (default 1048576).
1130 --name=name
1134 Assign a name to the container.
1135 The operator can identify a container in three ways:
1138 • UUID long identifier
1141 (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”);
1142 • UUID short identifier (“f78375b1c487”);
1144 • Name (“jonah”).
1146 Podman generates a UUID for each container, and if a name is not as‐
1150 signed to the container with --name then it generates a random string
1151 name. The name can be useful as a more human-friendly way to identify
1152 containers. This works for both background and foreground containers.
1153 --network=mode, --net
1156 Set the network mode for the container.
1157 Valid mode values are:
1160 • bridge[:OPTIONS,...]: Create a network stack on the default
1163 bridge. This is the default for rootful containers. It is pos‐
1164 sible to specify these additional options:
1165 • alias=name: Add network-scoped alias for the container.
1167 • ip=IPv4: Specify a static ipv4 address for this container.
1169 • ip=IPv6: Specify a static ipv6 address for this container.
1171 • mac=MAC: Specify a static mac address for this container.
1173 • interface_name: Specify a name for the created network in‐
1175 terface inside the container.
1176 For example to set a static ipv4 address and a static mac ad‐
1178 dress, use --network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99.
1179 • <network name or ID>[:OPTIONS,...]: Connect to a user-defined
1181 network; this is the network name or ID from a network created
1182 by podman network create. Using the network name implies the
1183 bridge network mode. It is possible to specify the same op‐
1184 tions described under the bridge mode above. Use the --network
1185 option multiple times to specify additional networks. For
1186 backwards compatibility it is also possible to specify net‐
1187 works comma separated on the first --network argument, however
1188 this prevents you from using the options described under the
1189 bridge section above.
1190 • none: Create a network namespace for the container but do not
1192 configure network interfaces for it, thus the container has no
1193 network connectivity.
1194 • container:id: Reuse another container's network stack.
1196 • host: Do not create a network namespace, the container uses
1198 the host's network. Note: The host mode gives the container
1199 full access to local system services such as D-bus and is
1200 therefore considered insecure.
1201 • ns:path: Path to a network namespace to join.
1203 • private: Create a new namespace for the container. This uses
1205 the bridge mode for rootful containers and slirp4netns for
1206 rootless ones.
1207 • slirp4netns[:OPTIONS,...]: use slirp4netns(1) to create a user
1209 network stack. This is the default for rootless containers. It
1210 is possible to specify these additional options, they can also
1211 be set with network_cmd_options in containers.conf:
1212 • allow_host_loopback=true|false: Allow slirp4netns to reach
1214 the host loopback IP (default is 10.0.2.2 or the second IP
1215 from slirp4netns cidr subnet when changed, see the cidr op‐
1216 tion below). The default is false.
1217 • mtu=MTU: Specify the MTU to use for this network. (Default
1219 is 65520).
1220 • cidr=CIDR: Specify ip range to use for this network. (De‐
1222 fault is 10.0.2.0/24).
1223 • enable_ipv6=true|false: Enable IPv6. Default is true. (Re‐
1225 quired for outbound_addr6).
1226 • outbound_addr=INTERFACE: Specify the outbound interface
1228 slirp binds to (ipv4 traffic only).
1229 • outbound_addr=IPv4: Specify the outbound ipv4 address slirp
1231 binds to.
1232 • outbound_addr6=INTERFACE: Specify the outbound interface
1234 slirp binds to (ipv6 traffic only).
1235 • outbound_addr6=IPv6: Specify the outbound ipv6 address slirp
1237 binds to.
1238 • port_handler=rootlesskit: Use rootlesskit for port forward‐
1240 ing. Default. Note: Rootlesskit changes the source IP ad‐
1241 dress of incoming packets to an IP address in the container
1242 network namespace, usually 10.0.2.100. If the application
1243 requires the real source IP address, e.g. web server logs,
1244 use the slirp4netns port handler. The rootlesskit port han‐
1245 dler is also used for rootless containers when connected to
1246 user-defined networks.
1247 • port_handler=slirp4netns: Use the slirp4netns port forward‐
1249 ing, it is slower than rootlesskit but preserves the correct
1250 source IP address. This port handler cannot be used for
1251 user-defined networks.
1252 • pasta[:OPTIONS,...]: use pasta(1) to create a user-mode net‐
1256 working stack.
1257 This is only supported in rootless mode.
1258 By default, IPv4 and IPv6 addresses and routes, as well as the
1259 pod interface name, are copied from the host. If port forward‐
1260 ing isn't configured, ports are forwarded dynamically as ser‐
1261 vices are bound on either side (init namespace or container
1262 namespace). Port forwarding preserves the original source IP
1263 address. Options described in pasta(1) can be specified as
1264 comma-separated arguments.
1265 In terms of pasta(1) options, --config-net is given by de‐
1266 fault, in order to configure networking when the container is
1267 started, and --no-map-gw is also assumed by default, to avoid
1268 direct access from container to host using the gateway ad‐
1269 dress. The latter can be overridden by passing --map-gw in the
1270 pasta-specific options (despite not being an actual pasta(1)
1271 option).
1272 Also, -t none and -u none are passed if, respectively, no TCP
1273 or UDP port forwarding from host to container is configured,
1274 to disable automatic port forwarding based on bound ports.
1275 Similarly, -T none and -U none are given to disable the same
1276 functionality from container to host.
1277 Some examples:
1278 • pasta:--map-gw: Allow the container to directly reach the
1280 host using the gateway address.
1281 • pasta:--mtu,1500: Specify a 1500 bytes MTU for the tap in‐
1283 terface in the container.
1284 • pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-for‐
1286 ward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp, equiv‐
1287 alent to default slirp4netns(1) options: disable IPv6, as‐
1288 sign 10.0.2.0/24 to the tap0 interface in the container,
1289 with gateway 10.0.2.3, enable DNS forwarder reachable at
1290 10.0.2.3, set MTU to 1500 bytes, disable NDP, DHCPv6 and
1291 DHCP support.
1292 • pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-
1294 forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp, equivalent
1295 to default slirp4netns(1) options with Podman overrides:
1296 same as above, but leave the MTU to 65520 bytes
1297 • pasta:-t,auto,-u,auto,-T,auto,-U,auto: enable automatic port
1299 forwarding based on observed bound ports from both host and
1300 container sides
1301 • pasta:-T,5201: enable forwarding of TCP port 5201 from con‐
1303 tainer to host, using the loopback interface instead of the
1304 tap interface for improved performance
1305 NOTE: For backward compatibility reasons, if there is an exist‐
1307 ing network named pasta, Podman uses it instead of the pasta
1308 mode."?
1309 Invalid if using --dns, --dns-option, or --dns-search with --network
1313 set to none or container:id.
1314 If used together with --pod, the container joins the pod's network
1317 namespace.
1318 --network-alias=alias
1321 Add a network-scoped alias for the container, setting the alias for all
1322 networks that the container joins. To set a name only for a specific
1323 network, use the alias option as described under the --network option.
1324 If the network has DNS enabled (podman network inspect -f {{.DNSEn‐
1325 abled}} <name>), these aliases can be used for name resolution on the
1326 given network. This option can be specified multiple times. NOTE: When
1327 using CNI a container only has access to aliases on the first network
1328 that it joins. This limitation does not exist with netavark/aardvark-
1329 dns.
1330 --no-healthcheck
1333 Disable any defined healthchecks for container.
1334 --no-hosts
1337 Do not create /etc/hosts for the container. By default, Podman manages
1338 /etc/hosts, adding the container's own IP address and any hosts from
1339 --add-host. --no-hosts disables this, and the image's /etc/hosts is
1340 preserved unmodified.
1341 This option conflicts with --add-host.
1344 --oom-kill-disable
1347 Whether to disable OOM Killer for the container or not.
1348 This flag is not supported on cgroups V2 systems.
1351 --oom-score-adj=num
1354 Tune the host's OOM preferences for containers (accepts values from
1355 -1000 to 1000).
1356 When running in rootless mode, the specified value can't be lower than
1359 the oom_score_adj for the current process. In this case, the oom-score-
1360 adj is clamped to the current process value.
1361 --os=OS
1364 Override the OS, defaults to hosts, of the image to be pulled. For ex‐
1365 ample, windows. Unless overridden, subsequent lookups of the same im‐
1366 age in the local storage matches this OS, regardless of the host.
1367 --passwd
1370 Allow Podman to add entries to /etc/passwd and /etc/group when used in
1371 conjunction with the --user option. This is used to override the Pod‐
1372 man provided user setup in favor of entrypoint configurations such as
1373 libnss-extrausers.
1374 --passwd-entry=ENTRY
1377 Customize the entry that is written to the /etc/passwd file within the
1378 container when --passwd is used.
1379 The variables $USERNAME, $UID, $GID, $NAME, $HOME are automatically re‐
1382 placed with their value at runtime.
1383 --personality=persona
1386 Personality sets the execution domain via Linux personality(2).
1387 --pid=mode
1390 Set the PID namespace mode for the container. The default is to create
1391 a private PID namespace for the container.
1392 • container:id: join another container's PID namespace;
1395 • host: use the host's PID namespace for the container. Note the
1397 host mode gives the container full access to local PID and is
1398 therefore considered insecure;
1399 • ns:path: join the specified PID namespace;
1401 • private: create a new namespace for the container (default).
1403 --pidfile=path
1407 When the pidfile location is specified, the container process' PID is
1408 written to the pidfile. (This option is not available with the remote
1409 Podman client, including Mac and Windows (excluding WSL2) machines) If
1410 the pidfile option is not specified, the container process' PID is
1411 written to /run/containers/storage/${storage-driver}-contain‐
1412 ers/$CID/userdata/pidfile.
1413 After the container is started, the location for the pidfile can be
1416 discovered with the following podman inspect command:
1417 $ podman inspect --format '{{ .PidFile }}' $CID
1420 /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile
1421 --pids-limit=limit
1425 Tune the container's pids limit. Set to -1 to have unlimited pids for
1426 the container. The default is 2048 on systems that support "pids"
1427 cgroup controller.
1428 --platform=OS/ARCH
1431 Specify the platform for selecting the image. (Conflicts with --arch
1432 and --os) The --platform option can be used to override the current ar‐
1433 chitecture and operating system. Unless overridden, subsequent lookups
1434 of the same image in the local storage matches this platform, regard‐
1435 less of the host.
1436 --pod=name
1439 Run container in an existing pod. Podman makes the pod automatically if
1440 the pod name is prefixed with new:. To make a pod with more granular
1441 options, use the podman pod create command before creating a container.
1442 When a container is run with a pod with an infra-container, the infra-
1443 container is started first.
1444 --pod-id-file=file
1447 Run container in an existing pod and read the pod's ID from the speci‐
1448 fied file. When a container is run within a pod which has an infra-
1449 container, the infra-container starts first.
1450 --preserve-fds=N
1453 Pass down to the process N additional file descriptors (in addition to
1454 0, 1, 2). The total FDs are 3+N. (This option is not available with
1455 the remote Podman client, including Mac and Windows (excluding WSL2)
1456 machines)
1457 --privileged
1460 Give extended privileges to this container. The default is false.
1461 By default, Podman containers are unprivileged (=false) and cannot, for
1464 example, modify parts of the operating system. This is because by de‐
1465 fault a container is only allowed limited access to devices. A "privi‐
1466 leged" container is given the same access to devices as the user
1467 launching the container, with the exception of virtual consoles
1468 (/dev/tty\d+) when running in systemd mode (--systemd=always).
1469 A privileged container turns off the security features that isolate the
1472 container from the host. Dropped Capabilities, limited devices, read-
1473 only mount points, Apparmor/SELinux separation, and Seccomp filters are
1474 all disabled.
1475 Rootless containers cannot have more privileges than the account that
1478 launched them.
1479 --publish, -p=[[ip:][hostPort]:]containerPort[/protocol]
1482 Publish a container's port, or range of ports, to the host.
1483 Both hostPort and containerPort can be specified as a range of ports.
1486 When specifying ranges for both, the number of container ports in the
1487 range must match the number of host ports in the range.
1488 If host IP is set to 0.0.0.0 or not set at all, the port is bound on
1491 all IPs on the host.
1492 By default, Podman publishes TCP ports. To publish a UDP port instead,
1495 give udp as protocol. To publish both TCP and UDP ports, set --publish
1496 twice, with tcp, and udp as protocols respectively. Rootful containers
1497 can also publish ports using the sctp protocol.
1498 Host port does not have to be specified (e.g. podman run -p
1501 127.0.0.1::80). If it is not, the container port is randomly assigned
1502 a port on the host.
1503 Use podman port to see the actual mapping: podman port $CONTAINER $CON‐
1506 TAINERPORT.
1507 Note: If a container runs within a pod, it is not necessary to publish
1510 the port for the containers in the pod. The port must only be published
1511 by the pod itself. Pod network stacks act like the network stack on the
1512 host - meaning a variety of containers in the pod and programs in the
1513 container all share a single interface, IP address, and associated
1514 ports. If one container binds to a port, no other container can use
1515 that port within the pod while it is in use. Containers in the pod can
1516 also communicate over localhost by having one container bind to local‐
1517 host in the pod, and another connect to that port.
1518 --publish-all, -P
1521 Publish all exposed ports to random ports on the host interfaces. The
1522 default is false.
1523 When set to true, publish all exposed ports to the host interfaces. If
1526 the operator uses -P (or -p) then Podman makes the exposed port acces‐
1527 sible on the host and the ports are available to any client that can
1528 reach the host.
1529 When using this option, Podman binds any exposed port to a random port
1532 on the host within an ephemeral port range defined by
1533 /proc/sys/net/ipv4/ip_local_port_range. To find the mapping between
1534 the host ports and the exposed ports, use podman port.
1535 --pull=policy
1538 Pull image policy. The default is missing.
1539 • always: Always pull the image and throw an error if the pull
1542 fails.
1543 • missing: Pull the image only when the image is not in the lo‐
1545 cal containers storage. Throw an error if no image is found
1546 and the pull fails.
1547 • never: Never pull the image but use the one from the local
1549 containers storage. Throw an error if no image is found.
1550 • newer: Pull if the image on the registry is newer than the one
1552 in the local containers storage. An image is considered to be
1553 newer when the digests are different. Comparing the time
1554 stamps is prone to errors. Pull errors are suppressed if a
1555 local image was found.
1556 --quiet, -q
1560 Suppress output information when pulling images
1561 --read-only
1564 Mount the container's root filesystem as read-only.
1565 By default, container root filesystems are writable, allowing processes
1568 to write files anywhere. By specifying the --read-only flag, the con‐
1569 tainers root filesystem are mounted read-only prohibiting any writes.
1570 --read-only-tmpfs
1573 If container is running in --read-only mode, then mount a read-write
1574 tmpfs on /dev, /dev/shm, /run, /tmp, and /var/tmp. The default is true.
1575 --replace
1578 If another container with the same name already exists, replace and re‐
1579 move it. The default is false.
1580 --requires=container
1583 Specify one or more requirements. A requirement is a dependency con‐
1584 tainer that is started before this container. Containers can be speci‐
1585 fied by name or ID, with multiple containers being separated by commas.
1586 --restart=policy
1589 Restart policy to follow when containers exit. Restart policy does not
1590 take effect if a container is stopped via the podman kill or podman
1591 stop commands.
1592 Valid policy values are:
1595 • no : Do not restart containers on exit
1598 • never : Synonym for no; do not restart con‐
1600 tainers on exit
1601 • on-failure[:max_retries] : Restart containers when they exit
1603 with a non-zero exit code, retrying indefinitely or until the
1604 optional max_retries count is hit
1605 • always : Restart containers when they exit,
1607 regardless of status, retrying indefinitely
1608 • unless-stopped : Identical to always
1610 Podman provides a systemd unit file, podman-restart.service, which
1614 restarts containers after a system reboot.
1615 When running containers in systemd services, use the restart function‐
1618 ality provided by systemd. In other words, do not use this option in a
1619 container unit, instead set the Restart= systemd directive in the [Ser‐
1620 vice] section. See podman-systemd.unit(5) and systemd.service(5).
1621 --rm
1624 Automatically remove the container and any anonymous unnamed volume as‐
1625 sociated with the container when it exits. The default is false.
1626 --rmi
1629 After exit of the container, remove the image unless another container
1630 is using it. Implies --rm on the new container. The default is false.
1631 --rootfs
1634 If specified, the first argument refers to an exploded container on the
1635 file system.
1636 This is useful to run a container without requiring any image manage‐
1639 ment, the rootfs of the container is assumed to be managed externally.
1640 Overlay Rootfs Mounts
1643 The :O flag tells Podman to mount the directory from the rootfs path as
1646 storage using the overlay file system. The container processes can mod‐
1647 ify content within the mount point which is stored in the container
1648 storage in a separate directory. In overlay terms, the source directory
1649 is the lower, and the container storage directory is the upper. Modifi‐
1650 cations to the mount point are destroyed when the container finishes
1651 executing, similar to a tmpfs mount point being unmounted.
1652 Note: On SELinux systems, the rootfs needs the correct label, which is
1655 by default unconfined_u:object_r:container_file_t:s0.
1656 idmap
1659 If idmap is specified, create an idmapped mount to the target user
1662 namespace in the container. The idmap option supports a custom mapping
1663 that can be different than the user namespace used by the container.
1664 The mapping can be specified after the idmap option like:
1665 idmap=uids=0-1-10#10-11-10;gids=0-100-10. For each triplet, the first
1666 value is the start of the backing file system IDs that are mapped to
1667 the second value on the host. The length of this mapping is given in
1668 the third value. Multiple ranges are separated with #.
1669 --sdnotify=container | conmon | healthy | ignore
1672 Determines how to use the NOTIFY_SOCKET, as passed with systemd and
1673 Type=notify.
1674 Default is container, which means allow the OCI runtime to proxy the
1677 socket into the container to receive ready notification. Podman sets
1678 the MAINPID to conmon's pid. The conmon option sets MAINPID to con‐
1679 mon's pid, and sends READY when the container has started. The socket
1680 is never passed to the runtime or the container. The healthy option
1681 sets MAINPID to conmon's pid, and sends READY when the container has
1682 turned healthy; requires a healthcheck to be set. The socket is never
1683 passed to the runtime or the container. The ignore option removes NO‐
1684 TIFY_SOCKET from the environment for itself and child processes, for
1685 the case where some other process above Podman uses NOTIFY_SOCKET and
1686 Podman does not use it.
1687 --seccomp-policy=policy
1690 Specify the policy to select the seccomp profile. If set to image, Pod‐
1691 man looks for a "io.containers.seccomp.profile" label in the container-
1692 image config and use its value as a seccomp profile. Otherwise, Podman
1693 follows the default policy by applying the default profile unless spec‐
1694 ified otherwise via --security-opt seccomp as described below.
1695 Note that this feature is experimental and may change in the future.
1698 --secret=secret[,opt=opt ...]
1701 Give the container access to a secret. Can be specified multiple times.
1702 A secret is a blob of sensitive data which a container needs at runtime
1705 but is not stored in the image or in source control, such as usernames
1706 and passwords, TLS certificates and keys, SSH keys or other important
1707 generic strings or binary content (up to 500 kb in size).
1708 When secrets are specified as type mount, the secrets are copied and
1711 mounted into the container when a container is created. When secrets
1712 are specified as type env, the secret is set as an environment variable
1713 within the container. Secrets are written in the container at the time
1714 of container creation, and modifying the secret using podman secret
1715 commands after the container is created affects the secret inside the
1716 container.
1717 Secrets and its storage are managed using the podman secret command.
1720 Secret Options
1723 • type=mount|env : How the secret is exposed to the con‐
1726 tainer.
1727 mount mounts the secret into the container
1728 as a file.
1729 env exposes the secret as an environment
1730 variable.
1731 Defaults to mount.
1732 • target=target : Target of secret.
1734 For mounted secrets, this is the path to
1735 the secret inside the container.
1736 If a fully qualified path is provided, the
1737 secret is mounted at that location.
1738 Otherwise, the secret is mounted to
1739 /run/secrets/target for linux containers
1740 or
1741 /var/run/secrets/target for freebsd con‐
1742 tainers.
1743 If the target is not set, the secret is
1744 mounted to /run/secrets/secretname by default.
1745 For env secrets, this is the environment
1746 variable key. Defaults to secretname.
1747 • uid=0 : UID of secret. Defaults to 0. Mount secret
1749 type only.
1750 • gid=0 : GID of secret. Defaults to 0. Mount secret
1752 type only.
1753 • mode=0 : Mode of secret. Defaults to 0444. Mount
1755 secret type only.
1756 Examples
1760 Mount at /my/location/mysecret with UID 1:
1763 --secret mysecret,target=/my/location/mysecret,uid=1
1766 Mount at /run/secrets/customtarget with mode 0777:
1770 --secret mysecret,target=customtarget,mode=0777
1773 Create a secret environment variable called ENVSEC:
1777 --secret mysecret,type=env,target=ENVSEC
1780 --security-opt=option
1784 Security Options
1785 • apparmor=unconfined : Turn off apparmor confinement for the
1788 container
1789 • apparmor=alternate-profile : Set the apparmor confinement pro‐
1791 file for the container
1792 • label=user:USER: Set the label user for the container pro‐
1794 cesses
1795 • label=role:ROLE: Set the label role for the container pro‐
1797 cesses
1798 • label=type:TYPE: Set the label process type for the container
1800 processes
1801 • label=level:LEVEL: Set the label level for the container pro‐
1803 cesses
1804 • label=filetype:TYPE: Set the label file type for the container
1806 files
1807 • label=disable: Turn off label separation for the container
1809 Note: Labeling can be disabled for all containers by setting la‐
1813 bel=false in the containers.conf (/etc/containers/containers.conf or
1814 $HOME/.config/containers/containers.conf) file.
1815 • label=nested: Allows SELinux modifications within the con‐
1818 tainer. Containers are allowed to modify SELinux labels on
1819 files and processes, as long as SELinux policy allows. Without
1820 nested, containers view SELinux as disabled, even when it is
1821 enabled on the host. Containers are prevented from setting any
1822 labels.
1823 • mask=/path/1:/path/2: The paths to mask separated by a colon.
1825 A masked path cannot be accessed inside the container.
1826 • no-new-privileges: Disable container processes from gaining
1828 additional privileges.
1829 • seccomp=unconfined: Turn off seccomp confinement for the con‐
1831 tainer.
1832 • seccomp=profile.json: JSON file to be used as a seccomp fil‐
1834 ter. Note that the io.podman.annotations.seccomp annotation is
1835 set with the specified value as shown in podman inspect.
1836 • proc-opts=OPTIONS : Comma-separated list of options to use for
1838 the /proc mount. More details for the possible mount options
1839 are specified in the proc(5) man page.
1840 • unmask=ALL or /path/1:/path/2, or shell expanded paths
1842 (/proc/*): Paths to unmask separated by a colon. If set to
1843 ALL, it unmasks all the paths that are masked or made read-
1844 only by default. The default masked paths are /proc/acpi,
1845 /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_de‐
1846 bug, /proc/scsi, /proc/timer_list, /proc/timer_stats,
1847 /sys/firmware, and /sys/fs/selinux. The default paths that
1848 are read-only are /proc/asound, /proc/bus, /proc/fs,
1849 /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup.
1850 Note: Labeling can be disabled for all containers by setting la‐
1854 bel=false in the containers.conf(5) file.
1855 --shm-size=number[unit]
1858 Size of /dev/shm. A unit can be b (bytes), k (kibibytes), m
1859 (mebibytes), or g (gibibytes). If the unit is omitted, the system uses
1860 bytes. If the size is omitted, the default is 64m. When size is 0,
1861 there is no limit on the amount of memory used for IPC by the con‐
1862 tainer. This option conflicts with --ipc=host.
1863 --shm-size-systemd=number[unit]
1866 Size of systemd-specific tmpfs mounts such as /run, /run/lock,
1867 /var/log/journal and /tmp. A unit can be b (bytes), k (kibibytes), m
1868 (mebibytes), or g (gibibytes). If the unit is omitted, the system uses
1869 bytes. If the size is omitted, the default is 64m. When size is 0, the
1870 usage is limited to 50% of the host's available memory.
1871 --sig-proxy
1874 Proxy received signals to the container process (non-TTY mode only).
1875 SIGCHLD, SIGSTOP, and SIGKILL are not proxied.
1876 The default is true.
1879 --stop-signal=signal
1882 Signal to stop a container. Default is SIGTERM.
1883 --stop-timeout=seconds
1886 Timeout to stop a container. Default is 10. Remote connections use lo‐
1887 cal containers.conf for defaults.
1888 --subgidname=name
1891 Run the container in a new user namespace using the map with name in
1892 the /etc/subgid file. If running rootless, the user needs to have the
1893 right to use the mapping. See subgid(5). This flag conflicts with
1894 --userns and --gidmap.
1895 --subuidname=name
1898 Run the container in a new user namespace using the map with name in
1899 the /etc/subuid file. If running rootless, the user needs to have the
1900 right to use the mapping. See subuid(5). This flag conflicts with
1901 --userns and --uidmap.
1902 --sysctl=name=value
1905 Configure namespaced kernel parameters at runtime.
1906 For the IPC namespace, the following sysctls are allowed:
1909 • kernel.msgmax
1912 • kernel.msgmnb
1914 • kernel.msgmni
1916 • kernel.sem
1918 • kernel.shmall
1920 • kernel.shmmax
1922 • kernel.shmmni
1924 • kernel.shm_rmid_forced
1926 • Sysctls beginning with fs.mqueue.*
1928 Note: if using the --ipc=host option, the above sysctls are not al‐
1932 lowed.
1933 For the network namespace, only sysctls beginning with net.* are al‐
1936 lowed.
1937 Note: if using the --network=host option, the above sysctls are not al‐
1940 lowed.
1941 --systemd=true | false | always
1944 Run container in systemd mode. The default is true.
1945 • true enables systemd mode only when the command executed in‐
1948 side the container is systemd, /usr/sbin/init, /sbin/init or
1949 /usr/local/sbin/init.
1950 • false disables systemd mode.
1952 • always enforces the systemd mode to be enabled.
1954 Running the container in systemd mode causes the following changes:
1958 • Podman mounts tmpfs file systems on the following directories
1961 • /run
1963 • /run/lock
1965 • /tmp
1967 • /sys/fs/cgroup/systemd
1969 • /var/lib/journal
1971 • Podman sets the default stop signal to SIGRTMIN+3.
1975 • Podman sets container_uuid environment variable in the con‐
1977 tainer to the first 32 characters of the container ID.
1978 • Podman does not mount virtual consoles (/dev/tty\d+) when run‐
1980 ning with --privileged.
1981 This allows systemd to run in a confined container without any modifi‐
1985 cations.
1986 Note that on SELinux systems, systemd attempts to write to the cgroup
1989 file system. Containers writing to the cgroup file system are denied by
1990 default. The container_manage_cgroup boolean must be enabled for this
1991 to be allowed on an SELinux separated system.
1992 setsebool -P container_manage_cgroup true
1995 --timeout=seconds
1999 Maximum time a container is allowed to run before conmon sends it the
2000 kill signal. By default containers run until they exit or are stopped
2001 by podman stop.
2002 --tls-verify
2005 Require HTTPS and verify certificates when contacting registries (de‐
2006 fault: true). If explicitly set to true, TLS verification is used. If
2007 set to false, TLS verification is not used. If not specified, TLS ver‐
2008 ification is used unless the target registry is listed as an insecure
2009 registry in containers-registries.conf(5)
2010 --tmpfs=fs
2013 Create a tmpfs mount.
2014 Mount a temporary filesystem (tmpfs) mount into a container, for exam‐
2017 ple:
2018 $ podman run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
2021 This command mounts a tmpfs at /tmp within the container. The supported
2025 mount options are the same as the Linux default mount flags. If no op‐
2026 tions are specified, the system uses the following options:
2027 rw,noexec,nosuid,nodev.
2028 --tty, -t
2031 Allocate a pseudo-TTY. The default is false.
2032 When set to true, Podman allocates a pseudo-tty and attach to the stan‐
2035 dard input of the container. This can be used, for example, to run a
2036 throwaway interactive shell.
2037 NOTE: The --tty flag prevents redirection of standard output. It com‐
2040 bines STDOUT and STDERR, it can insert control characters, and it can
2041 hang pipes. This option is only used when run interactively in a termi‐
2042 nal. When feeding input to Podman, use -i only, not -it.
2043 echo "asdf" | podman run --rm -i someimage /bin/cat
2046 --tz=timezone
2050 Set timezone in container. This flag takes area-based timezones, GMT
2051 time, as well as local, which sets the timezone in the container to
2052 match the host machine. See /usr/share/zoneinfo/ for valid timezones.
2053 Remote connections use local containers.conf for defaults
2054 --uidmap=[flags]container_uid:from_uid[:amount]
2057 Run the container in a new user namespace using the supplied UID map‐
2058 ping. This option conflicts with the --userns and --subuidname options.
2059 This option provides a way to map host UIDs to container UIDs. It can
2060 be passed several times to map different ranges.
2061 The possible values of the optional flags are discussed further down on
2064 this page. The amount value is optional and assumed to be 1 if not
2065 given.
2066 The from_uid value is based upon the user running the command, either
2069 rootful or rootless users.
2070 • rootful user: [flags]container_uid:host_uid[:amount]
2073 • rootless user: [flags]container_uid:intermediate_uid[:amount]
2075 Rootful mappings
2079 When podman run is called by a privileged user, the option --uidmap
2082 works as a direct mapping between host UIDs and container UIDs.
2083 host UID -> container UID
2086 The amount specifies the number of consecutive UIDs that is mapped. If
2089 for example amount is 4 the mapping looks like:
2090 ┌─────────────┬───────────────────┐
2093 │host UID │ container UID │
2094 ├─────────────┼───────────────────┤
2095 │from_uid │ container_uid │
2096 ├─────────────┼───────────────────┤
2097 │from_uid + 1 │ container_uid + 1 │
2098 ├─────────────┼───────────────────┤
2099 │from_uid + 2 │ container_uid + 2 │
2100 ├─────────────┼───────────────────┤
2101 │from_uid + 3 │ container_uid + 3 │
2102 └─────────────┴───────────────────┘
2103 Rootless mappings
2105 When podman run is called by an unprivileged user (i.e. running root‐
2108 less), the value from_uid is interpreted as an "intermediate UID". In
2109 the rootless case, host UIDs are not mapped directly to container UIDs.
2110 Instead the mapping happens over two mapping steps:
2111 host UID -> intermediate UID -> container UID
2114 The --uidmap option only influences the second mapping step.
2117 The first mapping step is derived by Podman from the contents of the
2120 file /etc/subuid and the UID of the user calling Podman.
2121 First mapping step:
2124 ┌────────────────────┬──────────────────┐
2127 │host UID │ intermediate UID │
2128 ├────────────────────┼──────────────────┤
2129 │UID for Podman user │ 0 │
2130 ├────────────────────┼──────────────────┤
2131 │1st subordinate UID │ 1 │
2132 ├────────────────────┼──────────────────┤
2133 │2nd subordinate UID │ 2 │
2134 ├────────────────────┼──────────────────┤
2135 │3rd subordinate UID │ 3 │
2136 ├────────────────────┼──────────────────┤
2137 │nth subordinate UID │ n │
2138 └────────────────────┴──────────────────┘
2139 To be able to use intermediate UIDs greater than zero, the user needs
2141 to have subordinate UIDs configured in /etc/subuid. See subuid(5).
2142 The second mapping step is configured with --uidmap.
2145 If for example amount is 5 the second mapping step looks like:
2148 ┌─────────────────┬───────────────────┐
2151 │intermediate UID │ container UID │
2152 ├─────────────────┼───────────────────┤
2153 │from_uid │ container_uid │
2154 ├─────────────────┼───────────────────┤
2155 │from_uid + 1 │ container_uid + 1 │
2156 ├─────────────────┼───────────────────┤
2157 │from_uid + 2 │ container_uid + 2 │
2158 ├─────────────────┼───────────────────┤
2159 │from_uid + 3 │ container_uid + 3 │
2160 ├─────────────────┼───────────────────┤
2161 │from_uid + 4 │ container_uid + 4 │
2162 └─────────────────┴───────────────────┘
2163 When running as rootless, Podman uses all the ranges configured in the
2165 /etc/subuid file.
2166 The current user ID is mapped to UID=0 in the rootless user namespace.
2169 Every additional range is added sequentially afterward:
2170 ┌──────────────────────┬─────────────────────────┬──────────────────────┐
2173 │host │ rootless user namespace │ length │
2174 ├──────────────────────┼─────────────────────────┼──────────────────────┤
2175 │$UID │ 0 │ 1 │
2176 ├──────────────────────┼─────────────────────────┼──────────────────────┤
2177 │1 │ $FIRST_RANGE_ID │ $FIRST_RANGE_LENGTH │
2178 ├──────────────────────┼─────────────────────────┼──────────────────────┤
2179 │1+$FIRST_RANGE_LENGTH │ $SECOND_RANGE_ID │ $SECOND_RANGE_LENGTH │
2180 └──────────────────────┴─────────────────────────┴──────────────────────┘
2181 Referencing a host ID from the parent namespace
2183 As a rootless user, the given host ID in --uidmap or --gidmap is mapped
2186 from the intermediate namespace generated by Podman. Sometimes it is
2187 desirable to refer directly at the host namespace. It is possible to
2188 manually do so, by running podman unshare cat /proc/self/gid_map, find‐
2189 ing the desired host id at the second column of the output, and getting
2190 the corresponding intermediate id from the first column.
2191 Podman can perform all that by preceding the host id in the mapping
2194 with the @ symbol. For instance, by specifying --gidmap 100000:@2000:1,
2195 podman will look up the intermediate id corresponding to host id 2000
2196 and it will map the found intermediate id to the container id 100000.
2197 The given host id must have been subordinated (otherwise it would not
2198 be mapped into the intermediate space in the first place).
2199 If the length is greater than one, for instance with --gidmap
2202 100000:@2000:2, Podman will map host ids 2000 and 2001 to 100000 and
2203 100001, respectively, regardless of how the intermediate mapping is de‐
2204 fined.
2205 Extending previous mappings
2208 Some mapping modifications may be cumbersome. For instance, a user
2211 starts with a mapping such as --gidmap="0:0:65000", that needs to be
2212 changed such as the parent id 1000 is mapped to container id 100000 in‐
2213 stead, leaving container id 1 unassigned. The corresponding --gidmap
2214 becomes --gidmap="0:0:1" --gidmap="2:2:65534" --gidmap="100000:1:1".
2215 This notation can be simplified using the + flag, that takes care of
2218 breaking previous mappings removing any conflicting assignment with the
2219 given mapping. The flag is given before the container id as follows:
2220 --gidmap="0:0:65000" --gidmap="+100000:1:1"
2221 ┌─────┬─────────────┬─────────────────────────────┐
2224 │Flag │ Example │ Description │
2225 ├─────┼─────────────┼─────────────────────────────┤
2226 │+ │ +100000:1:1 │ Extend the previous mapping │
2227 └─────┴─────────────┴─────────────────────────────┘
2228 This notation leads to gaps in the assignment, so it may be convenient
2230 to fill those gaps afterwards: --gidmap="0:0:65000"
2231 --gidmap="+100000:1:1" --gidmap="1:65001:1"
2232 One specific use case for this flag is in the context of rootless
2235 users. A rootless user may specify mappings with the + flag as in
2236 --gidmap="+100000:1:1". Podman will then "fill the gaps" starting from
2237 zero with all the remaining intermediate ids. This is convenient when a
2238 user wants to map a specific intermediate id to a container id, leaving
2239 the rest of subordinate ids to be mapped by Podman at will.
2240 Passing only one of --uidmap or --gidmap
2243 Usually, subordinated user and group ids are assigned simultaneously,
2246 and for any user the subordinated user ids match the subordinated group
2247 ids. For convenience, if only one of --uidmap or --gidmap is given,
2248 podman assumes the mapping refers to both UIDs and GIDs and applies the
2249 given mapping to both. If only one value of the two needs to be
2250 changed, the mappings should include the u or the g flags to specify
2251 that they only apply to UIDs or GIDs and should not be copied over.
2252 ┌─────┬───────────────┬─────────────────────┐
2255 │flag │ Example │ Description │
2256 ├─────┼───────────────┼─────────────────────┤
2257 │u │ u20000:2000:1 │ The mapping only │
2258 │ │ │ applies to UIDs │
2259 ├─────┼───────────────┼─────────────────────┤
2260 │g │ g10000:1000:1 │ The mapping only │
2261 │ │ │ applies to GIDs │
2262 └─────┴───────────────┴─────────────────────┘
2263 For instance given the command
2265 podman run --gidmap "0:0:1000" --gidmap "g2000:2000:1"
2268 Since no --uidmap is given, the --gidmap is copied to --uidmap, giving
2272 a command equivalent to
2273 podman run --gidmap "0:0:1000" --gidmap "2000:2000:1" --uidmap "0:0:1000"
2276 The --gidmap "g2000:2000:1" used the g flag and therefore it was not
2280 copied to --uidmap.
2281 Rootless mapping of additional host GIDs
2284 A rootless user may desire to map a specific host group that has al‐
2287 ready been subordinated within /etc/subgid without specifying the rest
2288 of the mapping.
2289 This can be done with --gidmap "+gcontainer_gid:@host_gid"
2292 Where:
2295 • The host GID is given through the @ symbol
2298 • The mapping of this GID is not copied over to --usermap thanks
2300 to the g flag.
2301 • The rest of the container IDs will be mapped starting from 0
2303 to n, with all the remaining subordinated GIDs, thanks to the
2304 + flag.
2305 For instance, if a user belongs to the group 2000 and that group is
2309 subordinated to that user (with usermod --add-subgids 2000-2000 $USER),
2310 the user can map the group into the container with:
2311 --gidmap=+g100000:@2000.
2312 If this mapping is combined with the option, --group-add=keep-groups,
2315 the process in the container will belong to group 100000, and files be‐
2316 longing to group 2000 in the host will appear as being owned by group
2317 100000 inside the container.
2318 podman run --group-add=keep-groups --gidmap="+g100000:@2000" ...
2321 No subordinate UIDs
2325 Even if a user does not have any subordinate UIDs in /etc/subuid,
2328 --uidmap can be used to map the normal UID of the user to a container
2329 UID by running podman run --uidmap $container_uid:0:1 --user $con‐
2330 tainer_uid ....
2331 Pods
2334 The --uidmap option cannot be called in conjunction with the --pod op‐
2337 tion as a uidmap cannot be set on the container level when in a pod.
2338 --ulimit=option
2341 Ulimit options. Sets the ulimits values inside of the container.
2342 --ulimit with a soft and hard limit in the format =[:]. For example:
2345 $ podman run --ulimit nofile=1024:1024 --rm ubi9 ulimit -n 1024
2348 Use host to copy the current configuration from the host.
2351 Don't use nproc with the ulimit flag as Linux uses nproc to set the
2354 maximum number of processes available to a user, not to a container.
2355 Use the --pids-limit option to modify the cgroup control to limit the
2358 number of processes within a container.
2359 --umask=umask
2362 Set the umask inside the container. Defaults to 0022. Remote connec‐
2363 tions use local containers.conf for defaults
2364 --unsetenv=env
2367 Unset default environment variables for the container. Default environ‐
2368 ment variables include variables provided natively by Podman, environ‐
2369 ment variables configured by the image, and environment variables from
2370 containers.conf.
2371 --unsetenv-all
2374 Unset all default environment variables for the container. Default en‐
2375 vironment variables include variables provided natively by Podman, en‐
2376 vironment variables configured by the image, and environment variables
2377 from containers.conf.
2378 --user, -u=user[:group]
2381 Sets the username or UID used and, optionally, the groupname or GID for
2382 the specified command. Both user and group may be symbolic or numeric.
2383 Without this argument, the command runs as the user specified in the
2386 container image. Unless overridden by a USER command in the Container‐
2387 file or by a value passed to this option, this user generally defaults
2388 to root.
2389 When a user namespace is not in use, the UID and GID used within the
2392 container and on the host match. When user namespaces are in use, how‐
2393 ever, the UID and GID in the container may correspond to another UID
2394 and GID on the host. In rootless containers, for example, a user name‐
2395 space is always used, and root in the container by default corresponds
2396 to the UID and GID of the user invoking Podman.
2397 --userns=mode
2400 Set the user namespace mode for the container.
2401 If --userns is not set, the default value is determined as follows. -
2404 If --pod is set, --userns is ignored and the user namespace of the pod
2405 is used. - If the environment variable PODMAN_USERNS is set its value
2406 is used. - If userns is specified in containers.conf this value is
2407 used. - Otherwise, --userns=host is assumed.
2408 --userns="" (i.e., an empty string) is an alias for --userns=host.
2411 This option is incompatible with --gidmap, --uidmap, --subuidname and
2414 --subgidname.
2415 Rootless user --userns=Key mappings:
2418 ┌────────────────────────┬───────────┬─────────────────────┐
2421 │Key │ Host User │ Container User │
2422 ├────────────────────────┼───────────┼─────────────────────┤
2423 │auto │ $UID │ nil (Host User UID │
2424 │ │ │ is not mapped into │
2425 │ │ │ container.) │
2426 ├────────────────────────┼───────────┼─────────────────────┤
2427 │host │ $UID │ 0 (Default User ac‐ │
2428 │ │ │ count mapped to │
2429 │ │ │ root user in con‐ │
2430 │ │ │ tainer.) │
2431 ├────────────────────────┼───────────┼─────────────────────┤
2432 │keep-id │ $UID │ $UID (Map user ac‐ │
2433 │ │ │ count to same UID │
2434 │ │ │ within container.) │
2435 ├────────────────────────┼───────────┼─────────────────────┤
2436 │keep-id:uid=200,gid=210 │ $UID │ 200:210 (Map user │
2437 │ │ │ account to speci‐ │
2438 │ │ │ fied UID, GID value │
2439 │ │ │ within container.) │
2440 ├────────────────────────┼───────────┼─────────────────────┤
2441 │nomap │ $UID │ nil (Host User UID │
2442 │ │ │ is not mapped into │
2443 │ │ │ container.) │
2444 └────────────────────────┴───────────┴─────────────────────┘
2445 Valid mode values are:
2447 auto[:OPTIONS,...]: automatically create a unique user namespace.
2450 The --userns=auto flag requires that the user name containers be speci‐
2453 fied in the /etc/subuid and /etc/subgid files, with an unused range of
2454 subordinate user IDs that Podman containers are allowed to allocate.
2455 See subuid(5).
2456 Example: containers:2147483647:2147483648.
2459 Podman allocates unique ranges of UIDs and GIDs from the containers
2462 subordinate user IDs. The size of the ranges is based on the number of
2463 UIDs required in the image. The number of UIDs and GIDs can be overrid‐
2464 den with the size option.
2465 The option --userns=keep-id uses all the subuids and subgids of the
2468 user. The option --userns=nomap uses all the subuids and subgids of
2469 the user except the user's own ID. Using --userns=auto when starting
2470 new containers does not work as long as any containers exist that were
2471 started with --userns=keep-id or --userns=nomap.
2472 Valid auto options:
2475 • gidmapping=CONTAINER_GID:HOST_GID:SIZE: to force a GID mapping
2478 to be present in the user namespace.
2479 • size=SIZE: to specify an explicit size for the automatic user
2481 namespace. e.g. --userns=auto:size=8192. If size is not speci‐
2482 fied, auto estimates a size for the user namespace.
2483 • uidmapping=CONTAINER_UID:HOST_UID:SIZE: to force a UID mapping
2485 to be present in the user namespace.
2486 container:id: join the user namespace of the specified container.
2490 host or "" (empty string): run in the user namespace of the caller. The
2493 processes running in the container have the same privileges on the host
2494 as any other process launched by the calling user.
2495 keep-id: creates a user namespace where the current user's UID:GID are
2498 mapped to the same values in the container. For containers created by
2499 root, the current mapping is created into a new user namespace.
2500 Valid keep-id options:
2503 • uid=UID: override the UID inside the container that is used to
2506 map the current user to.
2507 • gid=GID: override the GID inside the container that is used to
2509 map the current user to.
2510 nomap: creates a user namespace where the current rootless user's
2514 UID:GID are not mapped into the container. This option is not allowed
2515 for containers created by the root user.
2516 ns:namespace: run the container in the given existing user namespace.
2519 --uts=mode
2522 Set the UTS namespace mode for the container. The following values are
2523 supported:
2524 • host: use the host's UTS namespace inside the container.
2527 • private: create a new namespace for the container (default).
2529 • ns:[path]: run the container in the given existing UTS name‐
2531 space.
2532 • container:[container]: join the UTS namespace of the specified
2534 container.
2535 --variant=VARIANT
2539 Use VARIANT instead of the default architecture variant of the con‐
2540 tainer image. Some images can use multiple variants of the arm archi‐
2541 tectures, such as arm/v5 and arm/v7.
2542 --volume, -v=[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]
2545 Create a bind mount. If -v /HOST-DIR:/CONTAINER-DIR is specified, Pod‐
2546 man bind mounts /HOST-DIR from the host into /CONTAINER-DIR in the Pod‐
2547 man container. Similarly, -v SOURCE-VOLUME:/CONTAINER-DIR mounts the
2548 named volume from the host into the container. If no such named volume
2549 exists, Podman creates one. If no source is given, the volume is cre‐
2550 ated as an anonymously named volume with a randomly generated name, and
2551 is removed when the container is removed via the --rm flag or the pod‐
2552 man rm --volumes command.
2553 (Note when using the remote client, including Mac and Windows (exclud‐
2556 ing WSL2) machines, the volumes are mounted from the remote server, not
2557 necessarily the client machine.)
2558 The OPTIONS is a comma-separated list and can be: [1] ⟨#Footnote1⟩
2561 • rw|ro
2564 • z|Z
2566 • [O]
2568 • [U]
2570 • [no]copy
2572 • [no]dev
2574 • [no]exec
2576 • [no]suid
2578 • [r]bind
2580 • [r]shared|[r]slave|[r]private[r]unbindable
2582 • idmap[=options]
2584 The CONTAINER-DIR must be an absolute path such as /src/docs. The vol‐
2588 ume is mounted into the container at this directory.
2589 If a volume source is specified, it must be a path on the host or the
2592 name of a named volume. Host paths are allowed to be absolute or rela‐
2593 tive; relative paths are resolved relative to the directory Podman is
2594 run in. If the source does not exist, Podman returns an error. Users
2595 must pre-create the source files or directories.
2596 Any source that does not begin with a . or / is treated as the name of
2599 a named volume. If a volume with that name does not exist, it is cre‐
2600 ated. Volumes created with names are not anonymous, and they are not
2601 removed by the --rm option and the podman rm --volumes command.
2602 Specify multiple -v options to mount one or more volumes into a con‐
2605 tainer.
2606 Write Protected Volume Mounts
2609 Add :ro or :rw option to mount a volume in read-only or read-write
2612 mode, respectively. By default, the volumes are mounted read-write.
2613 See examples.
2614 Chowning Volume Mounts
2617 By default, Podman does not change the owner and group of source volume
2620 directories mounted into containers. If a container is created in a new
2621 user namespace, the UID and GID in the container may correspond to an‐
2622 other UID and GID on the host.
2623 The :U suffix tells Podman to use the correct host UID and GID based on
2626 the UID and GID within the container, to change recursively the owner
2627 and group of the source volume. Chowning walks the file system under
2628 the volume and changes the UID/GID on each file. If the volume has
2629 thousands of inodes, this process takes a long time, delaying the start
2630 of the container.
2631 Warning use with caution since this modifies the host filesystem.
2634 Labeling Volume Mounts
2637 Labeling systems like SELinux require that proper labels are placed on
2640 volume content mounted into a container. Without a label, the security
2641 system might prevent the processes running inside the container from
2642 using the content. By default, Podman does not change the labels set by
2643 the OS.
2644 To change a label in the container context, add either of two suffixes
2647 :z or :Z to the volume mount. These suffixes tell Podman to relabel
2648 file objects on the shared volumes. The z option tells Podman that two
2649 or more containers share the volume content. As a result, Podman labels
2650 the content with a shared content label. Shared volume labels allow all
2651 containers to read/write content. The Z option tells Podman to label
2652 the content with a private unshared label Only the current container
2653 can use a private volume. Relabeling walks the file system under the
2654 volume and changes the label on each file, if the volume has thousands
2655 of inodes, this process takes a long time, delaying the start of the
2656 container. If the volume was previously relabeled with the z option,
2657 Podman is optimized to not relabel a second time. If files are moved
2658 into the volume, then the labels can be manually change with the chcon
2659 -R container_file_t PATH command.
2660 Note: Do not relabel system files and directories. Relabeling system
2663 content might cause other confined services on the machine to fail.
2664 For these types of containers we recommend disabling SELinux separa‐
2665 tion. The option --security-opt label=disable disables SELinux separa‐
2666 tion for the container. For example if a user wanted to volume mount
2667 their entire home directory into a container, they need to disable
2668 SELinux separation.
2669 $ podman run --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file
2672 Overlay Volume Mounts
2676 The :O flag tells Podman to mount the directory from the host as a tem‐
2679 porary storage using the overlay file system. The container processes
2680 can modify content within the mountpoint which is stored in the con‐
2681 tainer storage in a separate directory. In overlay terms, the source
2682 directory is the lower, and the container storage directory is the up‐
2683 per. Modifications to the mount point are destroyed when the container
2684 finishes executing, similar to a tmpfs mount point being unmounted.
2685 For advanced users, the overlay option also supports custom non-
2688 volatile upperdir and workdir for the overlay mount. Custom upperdir
2689 and workdir can be fully managed by the users themselves, and Podman
2690 does not remove it on lifecycle completion. Example :O,up‐
2691 perdir=/some/upper,workdir=/some/work
2692 Subsequent executions of the container sees the original source direc‐
2695 tory content, any changes from previous container executions no longer
2696 exist.
2697 One use case of the overlay mount is sharing the package cache from the
2700 host into the container to allow speeding up builds.
2701 Note: The O flag conflicts with other options listed above.
2704 Content mounted into the container is labeled with the private label.
2707 On SELinux systems, labels in the source directory must be read‐
2708 able by the container label. Usually containers can read/execute con‐
2709 tainer_share_t and can read/write container_file_t. If unable to change
2710 the labels on a source volume, SELinux container separation must be
2711 disabled for the container to work.
2712 - Do not modify the source directory mounted into the container
2713 with an overlay mount, it can cause unexpected failures. Only modify
2714 the directory after the container finishes running.
2715 Mounts propagation
2718 By default bind mounted volumes are private. That means any mounts done
2721 inside the container is not visible on host and vice versa. One can
2722 change this behavior by specifying a volume mount propagation property.
2723 Making a volume shared mounts done under that volume inside the con‐
2724 tainer is visible on host and vice versa. Making a volume slave enables
2725 only one way mount propagation and that is mounts done on host under
2726 that volume is visible inside container but not the other way around.
2727 [1] ⟨#Footnote1⟩
2728 To control mount propagation property of a volume one can use the
2731 [r]shared, [r]slave, [r]private or the [r]unbindable propagation flag.
2732 Propagation property can be specified only for bind mounted volumes and
2733 not for internal volumes or named volumes. For mount propagation to
2734 work the source mount point (the mount point where source dir is
2735 mounted on) has to have the right propagation properties. For shared
2736 volumes, the source mount point has to be shared. And for slave vol‐
2737 umes, the source mount point has to be either shared or slave. [1]
2738 ⟨#Footnote1⟩
2739 To recursively mount a volume and all of its submounts into a con‐
2742 tainer, use the rbind option. By default the bind option is used, and
2743 submounts of the source directory is not mounted into the container.
2744 Mounting the volume with a copy option tells podman to copy content
2747 from the underlying destination directory onto newly created internal
2748 volumes. The copy only happens on the initial creation of the volume.
2749 Content is not copied up when the volume is subsequently used on dif‐
2750 ferent containers. The copy option is ignored on bind mounts and has no
2751 effect.
2752 Mounting volumes with the nosuid options means that SUID executables on
2755 the volume can not be used by applications to change their privilege.
2756 By default volumes are mounted with nosuid.
2757 Mounting the volume with the noexec option means that no executables on
2760 the volume can be executed within the container.
2761 Mounting the volume with the nodev option means that no devices on the
2764 volume can be used by processes within the container. By default vol‐
2765 umes are mounted with nodev.
2766 If the HOST-DIR is a mount point, then dev, suid, and exec options are
2769 ignored by the kernel.
2770 Use df HOST-DIR to figure out the source mount, then use findmnt -o
2773 TARGET,PROPAGATION source-mount-dir to figure out propagation proper‐
2774 ties of source mount. If findmnt[4m(1) utility is not available, then one
2775 can look at the mount entry for the source mount point in
2776 /proc/self/mountinfo. Look at the "optional fields" and see if any
2777 propagation properties are specified. In there, shared:N means the
2778 mount is shared, master:N means mount is slave, and if nothing is
2779 there, the mount is private. [1] ⟨#Footnote1⟩
2780 To change propagation properties of a mount point, use mount(8) com‐
2783 mand. For example, if one wants to bind mount source directory /foo,
2784 one can do mount --bind /foo /foo and mount --make-private --make-
2785 shared /foo. This converts /foo into a shared mount point. Alterna‐
2786 tively, one can directly change propagation properties of source mount.
2787 Say / is source mount for /foo, then use mount --make-shared / to con‐
2788 vert / into a shared mount.
2789 Note: if the user only has access rights via a group, accessing the
2792 volume from inside a rootless container fails.
2793 Idmapped mount
2796 If idmap is specified, create an idmapped mount to the target user
2799 namespace in the container. The idmap option supports a custom mapping
2800 that can be different than the user namespace used by the container.
2801 The mapping can be specified after the idmap option like:
2802 idmap=uids=0-1-10#10-11-10;gids=0-100-10. For each triplet, the first
2803 value is the start of the backing file system IDs that are mapped to
2804 the second value on the host. The length of this mapping is given in
2805 the third value. Multiple ranges are separated with #.
2806 Use the --group-add keep-groups option to pass the user's supplementary
2809 group access into the container.
2810 --volumes-from=CONTAINER[:OPTIONS]
2813 Mount volumes from the specified container(s). Used to share volumes
2814 between containers. The options is a comma-separated list with the fol‐
2815 lowing available elements:
2816 • rw|ro
2819 • z
2821 Mounts already mounted volumes from a source container onto another
2825 container. CONTAINER may be a name or ID. To share a volume, use the
2826 --volumes-from option when running the target container. Volumes can be
2827 shared even if the source container is not running.
2828 By default, Podman mounts the volumes in the same mode (read-write or
2831 read-only) as it is mounted in the source container. This can be
2832 changed by adding a ro or rw option.
2833 Labeling systems like SELinux require that proper labels are placed on
2836 volume content mounted into a container. Without a label, the security
2837 system might prevent the processes running inside the container from
2838 using the content. By default, Podman does not change the labels set by
2839 the OS.
2840 To change a label in the container context, add z to the volume mount.
2843 This suffix tells Podman to relabel file objects on the shared volumes.
2844 The z option tells Podman that two entities share the volume content.
2845 As a result, Podman labels the content with a shared content label.
2846 Shared volume labels allow all containers to read/write content.
2847 If the location of the volume from the source container overlaps with
2850 data residing on a target container, then the volume hides that data on
2851 the target.
2852 --workdir, -w=dir
2855 Working directory inside the container.
2856 The default working directory for running binaries within a container
2859 is the root directory (/). The image developer can set a different de‐
2860 fault with the WORKDIR instruction. The operator can override the work‐
2861 ing directory by using the -w option.
2862
2865 The exit code from podman run gives information about why the container
2866 failed to run or why it exited. When podman run exits with a non-zero
2867 code, the exit codes follow the chroot(1) standard, see below:
2868 125 The error is with Podman itself
2871 $ podman run --foo busybox; echo $?
2874 Error: unknown flag: --foo
2875 125
2876 126 The contained command cannot be invoked
2880 $ podman run busybox /etc; echo $?
2883 Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error
2884 126
2885 127 The contained command cannot be found
2889 $ podman run busybox foo; echo $?
2892 Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error
2893 127
2894 Exit code contained command exit code
2898 $ podman run busybox /bin/sh -c 'exit 3'; echo $?
2901 3
2902
2906 Running container in read-only mode
2907 During container image development, containers often need to write to
2908 the image content. Installing packages into /usr, for example. In pro‐
2909 duction, applications seldom need to write to the image. Container ap‐
2910 plications write to volumes if they need to write to file systems at
2911 all. Applications can be made more secure by running them in read-only
2912 mode using the --read-only switch. This protects the container's image
2913 from modification. By default read-only containers can write to tempo‐
2914 rary data. Podman mounts a tmpfs on /run and /tmp within the container.
2915 If the container does not write to any file system within the con‐
2916 tainer, including tmpfs, set --read-only-tmpfs=false.
2917 $ podman run --read-only -i -t fedora /bin/bash
2920 $ podman run --read-only --read-only-tmpfs=false --tmpfs /run -i -t fedora /bin/bash
2922 Exposing shared libraries inside of container as read-only using a glob
2926 $ podman run --mount type=glob,src=/usr/lib64/libnvidia\*,ro=true -i -t fedora /bin/bash
2927 Exposing log messages from the container to the host's log
2931 Bind mount the /dev/log directory to have messages that are logged in
2932 the container show up in the host's syslog/journal.
2933 $ podman run -v /dev/log:/dev/log -i -t fedora /bin/bash
2936 From inside the container test this by sending a message to the log.
2940 (bash)# logger "Hello from my container"
2943 Then exit and check the journal.
2947 (bash)# exit
2950 $ journalctl -b | grep Hello
2952 This lists the message sent to the logger.
2956 Attaching to one or more from STDIN, STDOUT, STDERR
2959 Without specifying the -a option, Podman attaches everything (stdin,
2960 stdout, stderr). Override the default by specifying -a (stdin, stdout,
2961 stderr), as in:
2962 $ podman run -a stdin -a stdout -i -t fedora /bin/bash
2965 Sharing IPC between containers
2969 Using shm_server.c available here:
2970 https://www.cs.cf.ac.uk/Dave/C/node27.html
2971 Testing --ipc=host mode:
2974 Host shows a shared memory segment with 7 pids attached, happens to be
2977 from httpd:
2978 $ sudo ipcs -m
2981 ------ Shared Memory Segments --------
2983 key shmid owner perms bytes nattch status
2984 0x01128e25 0 root 600 1000 7
2985 Now run a regular container, and it correctly does NOT see the shared
2989 memory segment from the host:
2990 $ podman run -it shm ipcs -m
2993 ------ Shared Memory Segments --------
2995 key shmid owner perms bytes nattch status
2996 Run a container with the new --ipc=host option, and it now sees the
3000 shared memory segment from the host httpd:
3001 $ podman run -it --ipc=host shm ipcs -m
3004 ------ Shared Memory Segments --------
3006 key shmid owner perms bytes nattch status
3007 0x01128e25 0 root 600 1000 7
3008 Testing --ipc=container:id mode:
3012 Start a container with a program to create a shared memory segment:
3015 $ podman run -it shm bash
3018 $ sudo shm/shm_server &
3019 $ sudo ipcs -m
3020 ------ Shared Memory Segments --------
3022 key shmid owner perms bytes nattch status
3023 0x0000162e 0 root 666 27 1
3024 Create a 2nd container correctly shows no shared memory segment from
3028 1st container:
3029 $ podman run shm ipcs -m
3032 ------ Shared Memory Segments --------
3034 key shmid owner perms bytes nattch status
3035 Create a 3rd container using the --ipc=container:id option, now it
3039 shows the shared memory segment from the first:
3040 $ podman run -it --ipc=container:ed735b2264ac shm ipcs -m
3043 $ sudo ipcs -m
3044 ------ Shared Memory Segments --------
3046 key shmid owner perms bytes nattch status
3047 0x0000162e 0 root 666 27 1
3048 Mapping Ports for External Usage
3052 The exposed port of an application can be mapped to a host port using
3053 the -p flag. For example, an httpd port 80 can be mapped to the host
3054 port 8080 using the following:
3055 $ podman run -p 8080:80 -d -i -t fedora/httpd
3058 Mounting External Volumes
3062 To mount a host directory as a container volume, specify the absolute
3063 path to the directory and the absolute path for the container directory
3064 separated by a colon. If the source is a named volume maintained by
3065 Podman, it is recommended to use its name rather than the path to the
3066 volume. Otherwise the volume is considered an orphan and wiped by the
3067 podman volume prune command:
3068 $ podman run -v /var/db:/data1 -i -t fedora bash
3071 $ podman run -v data:/data2 -i -t fedora bash
3073 $ podman run -v /var/cache/dnf:/var/cache/dnf:O -ti fedora dnf -y update
3075 If the container needs a writeable mounted volume by a non root user
3079 inside the container, use the U option. This option tells Podman to
3080 chown the source volume to match the default UID and GID used within
3081 the container.
3082 $ podman run -d -e MYSQL_ROOT_PASSWORD=root --user mysql --userns=keep-id -v ~/data:/var/lib/mysql:Z,U mariadb
3085 Alternatively if the container needs a writable volume by a non root
3089 user inside of the container, the --userns=keep-id option allows users
3090 to specify the UID and GID of the user executing Podman to specific
3091 UIDs and GIDs within the container. Since the processes running in the
3092 container run as the user's UID, they can read/write files owned by the
3093 user.
3094 $ podman run -d -e MYSQL_ROOT_PASSWORD=root --user mysql --userns=keep-id:uid=999,gid=999 -v ~/data:/var/lib/mysql:Z mariadb
3097 Using --mount flags to mount a host directory as a container folder,
3101 specify the absolute path to the directory or the volume name, and the
3102 absolute path within the container directory:
3103 $ podman run --mount type=bind,src=/var/db,target=/data1 busybox sh
3106 $ podman run --mount type=bind,src=volume-name,target=/data1 busybox sh
3108 When using SELinux, be aware that the host has no knowledge of con‐
3112 tainer SELinux policy. Therefore, in the above example, if SELinux pol‐
3113 icy is enforced, the /var/db directory is not writable to the con‐
3114 tainer. A "Permission Denied" message occurs, and an avc: message is
3115 added to the host's syslog.
3116 To work around this, at time of writing this man page, the following
3119 command needs to be run in order for the proper SELinux policy type la‐
3120 bel to be attached to the host directory:
3121 $ chcon -Rt svirt_sandbox_file_t /var/db
3124 Now, writing to the /data1 volume in the container is allowed and the
3128 changes are reflected on the host in /var/db.
3129 Using alternative security labeling
3132 Override the default labeling scheme for each container by specifying
3133 the --security-opt flag. For example, specify the MCS/MLS level, a re‐
3134 quirement for MLS systems. Specifying the level in the following com‐
3135 mand allows the same content to be shared between containers.
3136 podman run --security-opt label=level:s0:c100,c200 -i -t fedora bash
3139 An MLS example might be:
3143 $ podman run --security-opt label=level:TopSecret -i -t rhel7 bash
3146 To disable the security labeling for this container versus running with
3150 the
3151 --permissive flag, use the following command:
3154 $ podman run --security-opt label=disable -i -t fedora bash
3155 Tighten the security policy on the processes within a container by
3159 specifying an alternate type for the container. For example, run a con‐
3160 tainer that is only allowed to listen on Apache ports by executing the
3161 following command:
3162 $ podman run --security-opt label=type:svirt_apache_t -i -t centos bash
3165 Note that an SELinux policy defining a svirt_apache_t type must be
3169 written.
3170 To mask additional specific paths in the container, specify the paths
3173 separated by a colon using the mask option with the --security-opt
3174 flag.
3175 $ podman run --security-opt mask=/foo/bar:/second/path fedora bash
3178 To unmask all the paths that are masked by default, set the unmask op‐
3182 tion to ALL. Or to only unmask specific paths, specify the paths as
3183 shown above with the mask option.
3184 $ podman run --security-opt unmask=ALL fedora bash
3187 To unmask all the paths that start with /proc, set the unmask option to
3191 /proc/*.
3192 $ podman run --security-opt unmask=/proc/* fedora bash
3195 $ podman run --security-opt unmask=/foo/bar:/sys/firmware fedora bash
3199 Setting device weight via --blkio-weight-device flag.
3203 $ podman run -it --blkio-weight-device "/dev/sda:200" ubuntu
3204 Using a podman container with input from a pipe
3208 $ echo "asdf" | podman run --rm -i --entrypoint /bin/cat someimage
3209 asdf
3210 Setting automatic user namespace separated containers
3214 # podman run --userns=auto:size=65536 ubi8-micro cat /proc/self/uid_map
3215 0 2147483647 65536
3216 # podman run --userns=auto:size=65536 ubi8-micro cat /proc/self/uid_map
3217 0 2147549183 65536
3218 Setting Namespaced Kernel Parameters (Sysctls)
3222 The --sysctl sets namespaced kernel parameters (sysctls) in the con‐
3223 tainer. For example, to turn on IP forwarding in the containers network
3224 namespace, run this command:
3225 $ podman run --sysctl net.ipv4.ip_forward=1 someimage
3228 Note that not all sysctls are namespaced. Podman does not support
3232 changing sysctls inside of a container that also modify the host sys‐
3233 tem. As the kernel evolves we expect to see more sysctls become names‐
3234 paced.
3235 See the definition of the --sysctl option above for the current list of
3238 supported sysctls.
3239 Set UID/GID mapping in a new user namespace
3242 Running a container in a new user namespace requires a mapping of the
3243 UIDs and GIDs from the host.
3244 $ podman run --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
3247 Configuring Storage Options from the command line
3251 Podman allows for the configuration of storage by changing the values
3252 in the /etc/container/storage.conf or by using global options. This
3253 shows how to set up and use fuse-overlayfs for a one-time run of busy‐
3254 box using global options.
3255 podman --log-level=debug --storage-driver overlay --storage-opt "overlay.mount_program=/usr/bin/fuse-overlayfs" run busybox /bin/sh
3258 Configure timezone in a container
3262 $ podman run --tz=local alpine date
3263 $ podman run --tz=Asia/Shanghai alpine date
3264 $ podman run --tz=US/Eastern alpine date
3265 Adding dependency containers
3269 The first container, container1, is not started initially, but must be
3270 running before container2 starts. The podman run command starts the
3271 container automatically before starting container2.
3272 $ podman create --name container1 -t -i fedora bash
3275 $ podman run --name container2 --requires container1 -t -i fedora bash
3276 Multiple containers can be required.
3280 $ podman create --name container1 -t -i fedora bash
3283 $ podman create --name container2 -t -i fedora bash
3284 $ podman run --name container3 --requires container1,container2 -t -i fedora bash
3285 Configure keep supplemental groups for access to volume
3289 $ podman run -v /var/lib/design:/var/lib/design --group-add keep-groups ubi8
3290 Configure execution domain for containers using personality flag
3294 $ podman run --name container1 --personality=LINUX32 fedora bash
3295 Run a container with external rootfs mounted as an overlay
3299 $ podman run --name container1 --rootfs /path/to/rootfs:O bash
3300 Handling Timezones in java applications in a container.
3304 In order to use a timezone other than UTC when running a Java applica‐
3305 tion within a container, the TZ environment variable must be set within
3306 the container. Java applications ignores the value set with the --tz
3307 option.
3308 # Example run
3311 podman run -ti --rm -e TZ=EST mytzimage
3312 lrwxrwxrwx. 1 root root 29 Nov 3 08:51 /etc/localtime -> ../usr/share/zoneinfo/Etc/UTC
3313 Now with default timezone:
3314 Fri Nov 19 18:10:55 EST 2021
3315 Java default sees the following timezone:
3316 2021-11-19T18:10:55.651130-05:00
3317 Forcing UTC:
3318 Fri Nov 19 23:10:55 UTC 2021
3319 Run a container connected to two networks (called net1 and net2) with a
3323 static ip
3324 $ podman run --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip addr
3325 Rootless Containers
3329 Podman runs as a non-root user on most systems. This feature requires
3330 that a new enough version of shadow-utils be installed. The shadow-
3331 utils package must include the newuidmap(1) and newgidmap(1) executa‐
3332 bles.
3333 In order for users to run rootless, there must be an entry for their
3336 username in /etc/subuid and /etc/subgid which lists the UIDs for their
3337 user namespace.
3338 Rootless Podman works better if the fuse-overlayfs and slirp4netns
3341 packages are installed. The fuse-overlayfs package provides a
3342 userspace overlay storage driver, otherwise users need to use the vfs
3343 storage driver, which can be disk space expensive and less performant
3344 than other drivers.
3345 To enable VPN on the container, slirp4netns or pasta needs to be speci‐
3348 fied; without either, containers need to be run with the --network=host
3349 flag.
3350
3353 Environment variables within containers can be set using multiple dif‐
3354 ferent options, in the following order of precedence (later entries
3355 override earlier entries):
3356 • Container image: Any environment variables specified in the
3359 container image.
3360 • --http-proxy: By default, several environment variables are
3362 passed in from the host, such as http_proxy and no_proxy. See
3363 --http-proxy for details.
3364 • --env-host: Host environment of the process executing Podman
3366 is added.
3367 • --env-file: Any environment variables specified via env-files.
3369 If multiple files are specified, then they override each other
3370 in order of entry.
3371 • --env: Any environment variables specified overrides previous
3373 settings.
3374 Run containers and set the environment ending with a *. The trailing *
3378 glob functionality is only active when no value is specified:
3379 $ export ENV1=a
3382 $ podman run --env 'ENV*' alpine env | grep ENV
3383 ENV1=a
3384 $ podman run --env 'ENV*=b' alpine env | grep ENV
3385 ENV*=b
3386
3390 When Podman starts a container it actually executes the conmon program,
3391 which then executes the OCI Runtime. Conmon is the container monitor.
3392 It is a small program whose job is to watch the primary process of the
3393 container, and if the container dies, save the exit code. It also
3394 holds open the tty of the container, so that it can be attached to
3395 later. This is what allows Podman to run in detached mode (back‐
3396 grounded), so Podman can exit but conmon continues to run. Each con‐
3397 tainer has their own instance of conmon. Conmon waits for the container
3398 to exit, gathers and saves the exit code, and then launches a Podman
3399 process to complete the container cleanup, by shutting down the network
3400 and storage. For more information about conmon, see the conmon(8) man
3401 page.
3402
3405 /etc/subuid
3406 /etc/subgid
3409 NOTE: Use the environment variable TMPDIR to change the temporary stor‐
3412 age location of downloaded container images. Podman defaults to use
3413 /var/tmp.
3414
3417 podman(1), podman-save(1), podman-ps(1), podman-attach(1), podman-pod-
3418 create(1), podman-port(1), podman-start(1), podman-kill(1), podman-
3419 stop(1), podman-generate-systemd(1), podman-rm(1), subgid(5), sub‐
3420 uid(5), containers.conf(5), systemd.unit(5), setsebool(8),
3421 slirp4netns(1), pasta(1), fuse-overlayfs(1), proc(5), conmon(8), per‐
3422 sonality(2)
3423
3426 September 2018, updated by Kunal Kushwaha <kushwaha_ku‐
3427 nal_v7@lab.ntt.co.jp>
3428 October 2017, converted from Docker documentation to Podman by Dan
3431 Walsh for Podman <dwalsh@redhat.com>
3432 November 2015, updated by Sally O'Malley <somalley@redhat.com>
3435 June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
3438 April 2014, Originally compiled by William Henry <whenry@redhat.com>
3441 based on docker.com source material and internal work.
3442
3445 1: The Podman project is committed to inclusivity, a core value of open
3446 source. The master and slave mount propagation terminology used here is
3447 problematic and divisive, and needs to be changed. However, these terms
3448 are currently used within the Linux kernel and must be used as-is at
3449 this time. When the kernel maintainers rectify this usage, Podman will
3450 follow suit immediately.
3451 podman-run(1)