1podman-create(1) General Commands Manual podman-create(1)
2
6 podman-create - Create a new container
7
10 podman create [options] image [command [arg ...]]
11 podman container create [options] image [command [arg ...]]
14
17 Creates a writable container layer over the specified image and pre‐
18 pares it for running the specified command. The container ID is then
19 printed to STDOUT. This is similar to podman run -d except the con‐
20 tainer is never started. You can then use the podman start container
21 command to start the container at any point.
22 The initial status of the container created with podman create is 'cre‐
25 ated'.
26 Default settings for flags are defined in containers.conf. Most set‐
29 tings for remote connections use the server's containers.conf, except
30 when documented in man pages.
31
34 The image is specified using transport:path format. If no transport is
35 specified, the docker (container registry) transport will be used by
36 default. For remote Podman, including Mac and Windows (excluding WSL2)
37 machines, docker is the only allowed transport.
38 dir:path
41 An existing local directory path storing the manifest, layer tarballs
42 and signatures as individual files. This is a non-standardized format,
43 primarily useful for debugging or noninvasive container inspection.
44 $ podman save --format docker-dir fedora -o /tmp/fedora
47 $ podman create dir:/tmp/fedora echo hello
48 docker://docker-reference (Default)
52 An image reference stored in a remote container image registry. Ex‐
53 ample: "quay.io/podman/stable:latest". The reference can include a
54 path to a specific registry; if it does not, the registries listed in
55 registries.conf will be queried to find a matching image. By default,
56 credentials from podman login (stored at $XDG_RUNTIME_DIR/contain‐
57 ers/auth.json by default) will be used to authenticate; otherwise it
58 falls back to using credentials in $HOME/.docker/config.json.
59 $ podman create registry.fedoraproject.org/fedora:latest echo hello
62 docker-archive:path[:docker-reference] An image stored in the docker
66 save formatted file. docker-reference is only used when creating such a
67 file, and it must not contain a digest.
68 $ podman save --format docker-archive fedora -o /tmp/fedora
71 $ podman create docker-archive:/tmp/fedora echo hello
72 docker-daemon:docker-reference
76 An image in docker-reference format stored in the docker daemon in‐
77 ternal storage. The docker-reference can also be an image ID (docker-
78 daemon:algo:digest).
79 $ sudo docker pull fedora
82 $ sudo podman create docker-daemon:docker.io/library/fedora echo hello
83 oci-archive:path:tag
87 An image in a directory compliant with the "Open Container Image Lay‐
88 out Specification" at the specified path and specified with a tag.
89 $ podman save --format oci-archive fedora -o /tmp/fedora
92 $ podman create oci-archive:/tmp/fedora echo hello
93
97 --add-host=host:ip
98 Add a custom host-to-IP mapping (host:ip)
99 Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
102 tion can be set multiple times. Conflicts with the --no-hosts option.
103 --annotation=key=value
106 Add an annotation to the container. This option can be set multiple
107 times.
108 --arch=ARCH
111 Override the architecture, defaults to hosts, of the image to be
112 pulled. For example, arm. Unless overridden, subsequent lookups of the
113 same image in the local storage will match this architecture, regard‐
114 less of the host.
115 --attach, -a=stdin | stdout | stderr
118 Attach to STDIN, STDOUT or STDERR.
119 In foreground mode (the default when -d is not specified), podman run
122 can start the process in the container and attach the console to the
123 process's standard input, output, and error. It can even pretend to be
124 a TTY (this is what most command-line executables expect) and pass
125 along signals. The -a option can be set for each of stdin, stdout, and
126 stderr.
127 --authfile=path
130 Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
131 ers/auth.json, which is set using podman login. If the authorization
132 state is not found there, $HOME/.docker/config.json is checked, which
133 is set using docker login.
134 Note: There is also the option to override the default path of the au‐
137 thentication file by setting the REGISTRY_AUTH_FILE environment vari‐
138 able. This can be done with export REGISTRY_AUTH_FILE=path.
139 --blkio-weight=weight
142 Block IO relative weight. The weight is a value between 10 and 1000.
143 This option is not supported on cgroups V1 rootless systems.
146 --blkio-weight-device=device:weight
149 Block IO relative device weight.
150 --cap-add=capability
153 Add Linux capabilities.
154 --cap-drop=capability
157 Drop Linux capabilities.
158 --cgroup-conf=KEY=VALUE
161 When running on cgroup v2, specify the cgroup file to write to and its
162 value. For example --cgroup-conf=memory.high=1073741824 sets the mem‐
163 ory.high limit to 1GB.
164 --cgroup-parent=path
167 Path to cgroups under which the cgroup for the container will be cre‐
168 ated. If the path is not absolute, the path is considered to be rela‐
169 tive to the cgroups path of the init process. Cgroups will be created
170 if they do not already exist.
171 --cgroupns=mode
174 Set the cgroup namespace mode for the container.
175 • host: use the host's cgroup namespace inside the container.
178 • container:id: join the namespace of the specified container.
180 • private: create a new cgroup namespace.
182 • ns:path: join the namespace at the specified path.
184 If the host uses cgroups v1, the default is set to host. On cgroups v2,
188 the default is private.
189 --cgroups=how
192 Determines whether the container will create CGroups.
193 Default is enabled.
196 The enabled option will create a new cgroup under the cgroup-parent.
199 The disabled option will force the container to not create CGroups, and
200 thus conflicts with CGroup options (--cgroupns and --cgroup-parent).
201 The no-conmon option disables a new CGroup only for the conmon process.
202 The split option splits the current CGroup in two sub-cgroups: one for
203 conmon and one for the container payload. It is not possible to set
204 --cgroup-parent with split.
205 --chrootdirs=path
208 Path to a directory inside the container that should be treated as a
209 chroot directory. Any Podman managed file (e.g., /etc/resolv.conf,
210 /etc/hosts, etc/hostname) that is mounted into the root directory will
211 be mounted into that location as well. Multiple directories should be
212 separated with a comma.
213 --cidfile=file
216 Write the container ID to file.
217 --conmon-pidfile=file
220 Write the pid of the conmon process to a file. As conmon runs in a sep‐
221 arate process than Podman, this is necessary when using systemd to
222 restart Podman containers. (This option is not available with the re‐
223 mote Podman client, including Mac and Windows (excluding WSL2) ma‐
224 chines)
225 --cpu-period=limit
228 Set the CPU period for the Completely Fair Scheduler (CFS), which is a
229 duration in microseconds. Once the container's CPU quota is used up, it
230 will not be scheduled to run until the current period ends. Defaults to
231 100000 microseconds.
232 On some systems, changing the resource limits may not be allowed for
235 non-root users. For more details, see https://github.com/contain‐
236 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
237 source-limits-fails-with-a-permissions-error
238 This option is not supported on cgroups V1 rootless systems.
241 --cpu-quota=limit
244 Limit the CPU Completely Fair Scheduler (CFS) quota.
245 Limit the container's CPU usage. By default, containers run with the
248 full CPU resource. The limit is a number in microseconds. If a number
249 is provided, the container will be allowed to use that much CPU time
250 until the CPU period ends (controllable via --cpu-period).
251 On some systems, changing the resource limits may not be allowed for
254 non-root users. For more details, see https://github.com/contain‐
255 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
256 source-limits-fails-with-a-permissions-error
257 This option is not supported on cgroups V1 rootless systems.
260 --cpu-rt-period=microseconds
263 Limit the CPU real-time period in microseconds.
264 Limit the container's Real Time CPU usage. This option tells the kernel
267 to restrict the container's Real Time CPU usage to the period speci‐
268 fied.
269 This option is only supported on cgroups V1 rootful systems.
272 --cpu-rt-runtime=microseconds
275 Limit the CPU real-time runtime in microseconds.
276 Limit the containers Real Time CPU usage. This option tells the kernel
279 to limit the amount of time in a given CPU period Real Time tasks may
280 consume. Ex: Period of 1,000,000us and Runtime of 950,000us means that
281 this container could consume 95% of available CPU and leave the remain‐
282 ing 5% to normal priority tasks.
283 The sum of all runtimes across containers cannot exceed the amount al‐
286 lotted to the parent cgroup.
287 This option is only supported on cgroups V1 rootful systems.
290 --cpu-shares, -c=shares
293 CPU shares (relative weight).
294 By default, all containers get the same proportion of CPU cycles. This
297 proportion can be modified by changing the container's CPU share
298 weighting relative to the combined weight of all the running contain‐
299 ers. Default weight is 1024.
300 The proportion will only apply when CPU-intensive processes are run‐
303 ning. When tasks in one container are idle, other containers can use
304 the left-over CPU time. The actual amount of CPU time will vary depend‐
305 ing on the number of containers running on the system.
306 For example, consider three containers, one has a cpu-share of 1024 and
309 two others have a cpu-share setting of 512. When processes in all three
310 containers attempt to use 100% of CPU, the first container would re‐
311 ceive 50% of the total CPU time. If a fourth container is added with a
312 cpu-share of 1024, the first container only gets 33% of the CPU. The
313 remaining containers receive 16.5%, 16.5% and 33% of the CPU.
314 On a multi-core system, the shares of CPU time are distributed over all
317 CPU cores. Even if a container is limited to less than 100% of CPU
318 time, it can use 100% of each individual CPU core.
319 For example, consider a system with more than three cores. If the con‐
322 tainer C0 is started with --cpu-shares=512 running one process, and an‐
323 other container C1 with --cpu-shares=1024 running two processes, this
324 can result in the following division of CPU shares:
325 ┌────┬───────────┬─────┬──────────────┐
328 │PID │ container │ CPU │ CPU share │
329 ├────┼───────────┼─────┼──────────────┤
330 │100 │ C0 │ 0 │ 100% of CPU0 │
331 ├────┼───────────┼─────┼──────────────┤
332 │101 │ C1 │ 1 │ 100% of CPU1 │
333 ├────┼───────────┼─────┼──────────────┤
334 │102 │ C1 │ 2 │ 100% of CPU2 │
335 └────┴───────────┴─────┴──────────────┘
336 On some systems, changing the resource limits may not be allowed for
338 non-root users. For more details, see https://github.com/contain‐
339 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
340 source-limits-fails-with-a-permissions-error
341 This option is not supported on cgroups V1 rootless systems.
344 --cpus=number
347 Number of CPUs. The default is 0.0 which means no limit. This is short‐
348 hand for --cpu-period and --cpu-quota, so you may only set either
349 --cpus or --cpu-period and --cpu-quota.
350 On some systems, changing the CPU limits may not be allowed for non-
353 root users. For more details, see https://github.com/containers/pod‐
354 man/blob/main/troubleshooting.md#26-running-containers-with-resource-
355 limits-fails-with-a-permissions-error
356 This option is not supported on cgroups V1 rootless systems.
359 --cpuset-cpus=number
362 CPUs in which to allow execution. Can be specified as a comma-separated
363 list (e.g. 0,1), as a range (e.g. 0-3), or any combination thereof
364 (e.g. 0-3,7,11-15).
365 On some systems, changing the resource limits may not be allowed for
368 non-root users. For more details, see https://github.com/contain‐
369 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
370 source-limits-fails-with-a-permissions-error
371 This option is not supported on cgroups V1 rootless systems.
374 --cpuset-mems=nodes
377 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
378 tive on NUMA systems.
379 If there are four memory nodes on the system (0-3), use --cpuset-
382 mems=0,1 then processes in the container will only use memory from the
383 first two memory nodes.
384 On some systems, changing the resource limits may not be allowed for
387 non-root users. For more details, see https://github.com/contain‐
388 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
389 source-limits-fails-with-a-permissions-error
390 This option is not supported on cgroups V1 rootless systems.
393 --device=host-device[:container-device][:permissions]
396 Add a host device to the container. Optional permissions parameter can
397 be used to specify device permissions by combining r for read, w for
398 write, and m for mknod(2).
399 Example: --device=/dev/sdc:/dev/xvdc:rwm.
402 Note: if host-device is a symbolic link then it will be resolved first.
405 The container will only store the major and minor numbers of the host
406 device.
407 Podman may load kernel modules required for using the specified device.
410 The devices that Podman will load modules for when necessary are:
411 /dev/fuse.
412 In rootless mode, the new device is bind mounted in the container from
415 the host rather than Podman creating it within the container space. Be‐
416 cause the bind mount retains its SELinux label on SELinux systems, the
417 container can get permission denied when accessing the mounted device.
418 Modify SELinux settings to allow containers to use all device labels
419 via the following command:
420 $ sudo setsebool -P container_use_devices=true
423 Note: if the user only has access rights via a group, accessing the de‐
426 vice from inside a rootless container will fail. Use the --group-add
427 keep-groups flag to pass the user's supplementary group access into the
428 container.
429 --device-cgroup-rule="type major:minor mode"
432 Add a rule to the cgroup allowed devices list. The rule is expected to
433 be in the format specified in the Linux kernel documentation (Documen‐
434 tation/cgroup-v1/devices.txt):
435 - type: a (all), c (char), or b (block);
436 - major and minor: either a number, or * for all;
437 - mode: a composition of r (read), w (write), and m (mknod(2)).
438 --device-read-bps=path:rate
441 Limit read rate (in bytes per second) from a device (e.g. --device-
442 read-bps=/dev/sda:1mb).
443 On some systems, changing the resource limits may not be allowed for
446 non-root users. For more details, see https://github.com/contain‐
447 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
448 source-limits-fails-with-a-permissions-error
449 This option is not supported on cgroups V1 rootless systems.
452 --device-read-iops=path:rate
455 Limit read rate (in IO operations per second) from a device (e.g. --de‐
456 vice-read-iops=/dev/sda:1000).
457 On some systems, changing the resource limits may not be allowed for
460 non-root users. For more details, see https://github.com/contain‐
461 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
462 source-limits-fails-with-a-permissions-error
463 This option is not supported on cgroups V1 rootless systems.
466 --device-write-bps=path:rate
469 Limit write rate (in bytes per second) to a device (e.g. --device-
470 write-bps=/dev/sda:1mb).
471 On some systems, changing the resource limits may not be allowed for
474 non-root users. For more details, see https://github.com/contain‐
475 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
476 source-limits-fails-with-a-permissions-error
477 This option is not supported on cgroups V1 rootless systems.
480 --device-write-iops=path:rate
483 Limit write rate (in IO operations per second) to a device (e.g. --de‐
484 vice-write-iops=/dev/sda:1000).
485 On some systems, changing the resource limits may not be allowed for
488 non-root users. For more details, see https://github.com/contain‐
489 ers/podman/blob/main/troubleshooting.md#26-running-containers-with-re‐
490 source-limits-fails-with-a-permissions-error
491 This option is not supported on cgroups V1 rootless systems.
494 --disable-content-trust
497 This is a Docker-specific option to disable image verification to a
498 container registry and is not supported by Podman. This option is a
499 NOOP and provided solely for scripting compatibility.
500 --dns=ipaddr
503 Set custom DNS servers.
504 This option can be used to override the DNS configuration passed to the
507 container. Typically this is necessary when the host DNS configuration
508 is invalid for the container (e.g., 127.0.0.1). When this is the case
509 the --dns flag is necessary for every run.
510 The special value none can be specified to disable creation of /etc/re‐
513 solv.conf in the container by Podman. The /etc/resolv.conf file in the
514 image will be used without changes.
515 This option cannot be combined with --network that is set to none or
518 container:id.
519 --dns-option=option
522 Set custom DNS options. Invalid if using --dns-option with --network
523 that is set to none or container:id.
524 --dns-search=domain
527 Set custom DNS search domains. Invalid if using --dns-search with
528 --network that is set to none or container:id. Use --dns-search=. if
529 you don't wish to set the search domain.
530 --entrypoint="command" | '["command", arg1 , ...]'
533 Overwrite the default ENTRYPOINT of the image.
534 This option allows you to overwrite the default entrypoint of the im‐
537 age.
538 The ENTRYPOINT of an image is similar to a COMMAND because it specifies
541 what executable to run when the container starts, but it is (purposely)
542 more difficult to override. The ENTRYPOINT gives a container its de‐
543 fault nature or behavior, so that when you set an ENTRYPOINT you can
544 run the container as if it were that binary, complete with default op‐
545 tions, and you can pass in more options via the COMMAND. But, sometimes
546 an operator may want to run something else inside the container, so you
547 can override the default ENTRYPOINT at runtime by using a --entrypoint
548 and a string to specify the new ENTRYPOINT.
549 You need to specify multi option commands in the form of a json string.
552 --env, -e=env
555 Set environment variables.
556 This option allows arbitrary environment variables that are available
559 for the process to be launched inside of the container. If an environ‐
560 ment variable is specified without a value, Podman will check the host
561 environment for a value and set the variable only if it is set on the
562 host. As a special case, if an environment variable ending in * is
563 specified without a value, Podman will search the host environment for
564 variables starting with the prefix and will add those variables to the
565 container.
566 See Environment ⟨#environment⟩ note below for precedence and examples.
569 --env-file=file
572 Read in a line-delimited file of environment variables.
573 See Environment ⟨#environment⟩ note below for precedence and examples.
576 --env-host
579 Use host environment inside of the container. See Environment note be‐
580 low for precedence. (This option is not available with the remote Pod‐
581 man client, including Mac and Windows (excluding WSL2) machines)
582 --env-merge=env
585 Preprocess default environment variables for the containers. For exam‐
586 ple if image contains environment variable hello=world user can prepro‐
587 cess it using --env-merge hello=${hello}-some so new value will be
588 hello=world-some.
589 --expose=port
592 Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up
593 port redirection on the host system.
594 --gidmap=container_gid:host_gid:amount
597 Run the container in a new user namespace using the supplied GID map‐
598 ping. This option conflicts with the --userns and --subgidname options.
599 This option provides a way to map host GIDs to container GIDs in the
600 same way as --uidmap maps host UIDs to container UIDs. For details see
601 --uidmap.
602 Note: the --gidmap flag cannot be called in conjunction with the --pod
605 flag as a gidmap cannot be set on the container level when in a pod.
606 --group-add=group | keep-groups
609 Assign additional groups to the primary user running within the con‐
610 tainer process.
611 • keep-groups is a special flag that tells Podman to keep the
614 supplementary group access.
615 Allows container to use the user's supplementary group access. If file
619 systems or devices are only accessible by the rootless user's group,
620 this flag tells the OCI runtime to pass the group access into the con‐
621 tainer. Currently only available with the crun OCI runtime. Note: keep-
622 groups is exclusive, you cannot add any other groups with this flag.
623 (Not available for remote commands, including Mac and Windows (exclud‐
624 ing WSL2) machines)
625 --health-cmd="command" | '["command", arg1 , ...]'
628 Set or alter a healthcheck command for a container. The command is a
629 command to be executed inside your container that determines your con‐
630 tainer health. The command is required for other healthcheck options to
631 be applied. A value of none disables existing healthchecks.
632 Multiple options can be passed in the form of a JSON array; otherwise,
635 the command will be interpreted as an argument to /bin/sh -c.
636 --health-interval=interval
639 Set an interval for the healthchecks. An interval of disable results in
640 no automatic timer setup. The default is 30s.
641 --health-on-failure=action
644 Action to take once the container transitions to an unhealthy state.
645 The default is none.
646 • none: Take no action.
649 • kill: Kill the container.
651 • restart: Restart the container. Do not combine the restart
653 action with the --restart flag. When running inside of a sys‐
654 temd unit, consider using the kill or stop action instead to
655 make use of systemd's restart policy.
656 • stop: Stop the container.
658 --health-retries=retries
662 The number of retries allowed before a healthcheck is considered to be
663 unhealthy. The default value is 3.
664 --health-start-period=period
667 The initialization time needed for a container to bootstrap. The value
668 can be expressed in time format like 2m3s. The default value is 0s.
669 --health-timeout=timeout
672 The maximum time allowed to complete the healthcheck before an interval
673 is considered failed. Like start-period, the value can be expressed in
674 a time format such as 1m22s. The default value is 30s.
675 --help
678 Print usage statement
679 --hostname, -h=name
682 Container host name
683 Sets the container host name that is available inside the container.
686 Can only be used with a private UTS namespace --uts=private (default).
687 If --pod is specified and the pod shares the UTS namespace (default)
688 the pod's hostname will be used.
689 --hostuser=name
692 Add a user account to /etc/passwd from the host to the container. The
693 Username or UID must exist on the host system.
694 --http-proxy
697 By default proxy environment variables are passed into the container if
698 set for the Podman process. This can be disabled by setting the value
699 to false. The environment variables passed in include http_proxy,
700 https_proxy, ftp_proxy, no_proxy, and also the upper case versions of
701 those. This option is only needed when the host system must use a proxy
702 but the container should not use any proxy. Proxy environment variables
703 specified for the container in any other way will override the values
704 that would have been passed through from the host. (Other ways to spec‐
705 ify the proxy for the container include passing the values with the
706 --env flag, or hard coding the proxy environment at container build
707 time.) (This option is not available with the remote Podman client,
708 including Mac and Windows (excluding WSL2) machines)
709 Defaults to true.
712 --image-volume=bind | tmpfs | ignore
715 Tells Podman how to handle the builtin image volumes. Default is bind.
716 • bind: An anonymous named volume will be created and mounted
719 into the container.
720 • tmpfs: The volume is mounted onto the container as a tmpfs,
722 which allows the users to create content that disappears when
723 the container is stopped.
724 • ignore: All volumes are just ignored and no action is taken.
726 --init
730 Run an init inside the container that forwards signals and reaps pro‐
731 cesses. The container-init binary is mounted at /run/podman-init.
732 Mounting over /run will hence break container execution.
733 --init-ctr=type
736 (Pods only). When using pods, create an init style container, which is
737 run after the infra container is started but before regular pod con‐
738 tainers are started. Init containers are useful for running setup op‐
739 erations for the pod's applications.
740 Valid values for init-ctr type are always or once. The always value
743 means the container will run with each and every pod start, whereas the
744 once value means the container will only run once when the pod is
745 started and then the container is removed.
746 Init containers are only run on pod start. Restarting a pod will not
749 execute any init containers should they be present. Furthermore, init
750 containers can only be created in a pod when that pod is not running.
751 --init-path=path
754 Path to the container-init binary.
755 --interactive, -i
758 When set to true, keep stdin open even if not attached. The default is
759 false.
760 --ip=ipv4
763 Specify a static IPv4 address for the container, for example
764 10.88.64.128. This option can only be used if the container is joined
765 to only a single network - i.e., --network=network-name is used at most
766 once - and if the container is not joining another container's network
767 namespace via --network=container:id. The address must be within the
768 network's IP address pool (default 10.88.0.0/16).
769 To specify multiple static IP addresses per container, set multiple
772 networks using the --network option with a static IP address specified
773 for each using the ip mode for that option.
774 --ip6=ipv6
777 Specify a static IPv6 address for the container, for example
778 fd46:db93:aa76:ac37::10. This option can only be used if the container
779 is joined to only a single network - i.e., --network=network-name is
780 used at most once - and if the container is not joining another con‐
781 tainer's network namespace via --network=container:id. The address
782 must be within the network's IPv6 address pool.
783 To specify multiple static IPv6 addresses per container, set multiple
786 networks using the --network option with a static IPv6 address speci‐
787 fied for each using the ip6 mode for that option.
788 --ipc=ipc
791 Set the IPC namespace mode for a container. The default is to create a
792 private IPC namespace.
793 • "": Use Podman's default, defined in containers.conf.
796 • container:id: reuses another container's shared memory, sema‐
798 phores, and message queues
799 • host: use the host's shared memory, semaphores, and message
801 queues inside the container. Note: the host mode gives the
802 container full access to local shared memory and is therefore
803 considered insecure.
804 • none: private IPC namespace, with /dev/shm not mounted.
806 • ns:path: path to an IPC namespace to join.
808 • private: private IPC namespace. = shareable: private IPC
810 namespace with a possibility to share it with other contain‐
811 ers.
812 --label, -l=key=value
816 Add metadata to a container.
817 --label-file=file
820 Read in a line-delimited file of labels.
821 --link-local-ip=ip
824 Not implemented.
825 --log-driver=driver
828 Logging driver for the container. Currently available options are k8s-
829 file, journald, none and passthrough, with json-file aliased to k8s-
830 file for scripting compatibility. (Default journald).
831 The podman info command below will display the default log-driver for
834 the system.
835 $ podman info --format '{{ .Host.LogDriver }}'
838 journald
839 The passthrough driver passes down the standard streams (stdin, stdout,
843 stderr) to the container. It is not allowed with the remote Podman
844 client, including Mac and Windows (excluding WSL2) machines, and on a
845 tty, since it is vulnerable to attacks via TIOCSTI.
846 --log-opt=name=value
849 Logging driver specific options.
850 Set custom logging configuration. The following *name*s are supported:
853 path: specify a path to the log file
856 (e.g. --log-opt path=/var/log/container/mycontainer.json);
857 max-size: specify a max size of the log file
860 (e.g. --log-opt max-size=10mb);
861 tag: specify a custom log tag for the container
864 (e.g. --log-opt tag="{{.ImageName}}". It supports the same keys as
865 podman inspect --format. This option is currently supported only by
866 the journald log driver.
867 --mac-address=address
870 Container network interface MAC address (e.g. 92:d0:c6:0a:29:33) This
871 option can only be used if the container is joined to only a single
872 network - i.e., --network=network-name is used at most once - and if
873 the container is not joining another container's network namespace via
874 --network=container:id.
875 Remember that the MAC address in an Ethernet network must be unique.
878 The IPv6 link-local address will be based on the device's MAC address
879 according to RFC4862.
880 To specify multiple static MAC addresses per container, set multiple
883 networks using the --network option with a static MAC address specified
884 for each using the mac mode for that option.
885 --memory, -m=number[unit]
888 Memory limit. A unit can be b (bytes), k (kibibytes), m (mebibytes), or
889 g (gibibytes).
890 Allows the memory available to a container to be constrained. If the
893 host supports swap memory, then the -m memory setting can be larger
894 than physical RAM. If a limit of 0 is specified (not using -m), the
895 container's memory is not limited. The actual limit may be rounded up
896 to a multiple of the operating system's page size (the value would be
897 very large, that's millions of trillions).
898 This option is not supported on cgroups V1 rootless systems.
901 --memory-reservation=number[unit]
904 Memory soft limit. A unit can be b (bytes), k (kibibytes), m
905 (mebibytes), or g (gibibytes).
906 After setting memory reservation, when the system detects memory con‐
909 tention or low memory, containers are forced to restrict their consump‐
910 tion to their reservation. So you should always set the value below
911 --memory, otherwise the hard limit will take precedence. By default,
912 memory reservation will be the same as memory limit.
913 This option is not supported on cgroups V1 rootless systems.
916 --memory-swap=number[unit]
919 A limit value equal to memory plus swap. A unit can be b (bytes), k
920 (kibibytes), m (mebibytes), or g (gibibytes).
921 Must be used with the -m (--memory) flag. The argument value should
924 always be larger than that of
925 -m (--memory) By default, it is set to double the value of --memory.
926 Set number to -1 to enable unlimited swap.
929 This option is not supported on cgroups V1 rootless systems.
932 --memory-swappiness=number
935 Tune a container's memory swappiness behavior. Accepts an integer be‐
936 tween 0 and 100.
937 This flag is only supported on cgroups V1 rootful systems.
940 --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
943 Attach a filesystem mount to the container
944 Current supported mount TYPEs are bind, volume, image, tmpfs and de‐
947 vpts. [1] ⟨#Footnote1⟩
948 e.g.
951 type=bind,source=/path/on/host,destination=/path/in/container
953 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
955 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true
957 type=volume,source=vol1,destination=/path/in/container,ro=true
959 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
961 type=image,source=fedora,destination=/fedora-image,rw=true
963 type=devpts,destination=/dev/pts
965 Common Options:
967 · src, source: mount source spec for bind and volume. Mandatory for bind.
969 · dst, destination, target: mount destination spec.
971 Options specific to volume:
973 · ro, readonly: true or false (default).
975 . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
977 · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container.
979 Options specific to image:
981 · rw, readwrite: true or false (default).
983 Options specific to bind:
985 · ro, readonly: true or false (default).
987 · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2).
989 . bind-nonrecursive: do not set up a recursive bind mount. By default it is recursive.
991 . relabel: shared, private.
993 · idmap: true or false (default). If specified, create an idmapped mount to the target user namespace in the container.
995 . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
997 Options specific to tmpfs:
999 · ro, readonly: true or false (default).
1001 · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
1003 · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
1005 · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default.
1007 · notmpcopyup: Disable copying files from the image to the tmpfs.
1009 . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
1011 Options specific to devpts:
1013 · uid: UID of the file owner (default 0).
1015 · gid: GID of the file owner (default 0).
1017 · mode: permission mask for the file (default 600).
1019 · max: maximum number of PTYs (default 1048576).
1021 --name=name
1025 Assign a name to the container.
1026 The operator can identify a container in three ways:
1029 • UUID long identifier
1032 (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”);
1033 • UUID short identifier (“f78375b1c487”);
1035 • Name (“jonah”).
1037 Podman generates a UUID for each container, and if a name is not as‐
1041 signed to the container with --name then it will generate a random
1042 string name. The name is useful any place you need to identify a con‐
1043 tainer. This works for both background and foreground containers.
1044 --network=mode, --net
1047 Set the network mode for the container.
1048 Valid mode values are:
1051 • bridge[:OPTIONS,...]: Create a network stack on the default
1054 bridge. This is the default for rootful containers. It is pos‐
1055 sible to specify these additional options:
1056 • alias=name: Add network-scoped alias for the container.
1058 • ip=IPv4: Specify a static ipv4 address for this container.
1060 • ip=IPv6: Specify a static ipv6 address for this container.
1062 • mac=MAC: Specify a static mac address for this container.
1064 • interface_name: Specify a name for the created network in‐
1066 terface inside the container.
1067 For example to set a static ipv4 address and a static mac address, use
1073 --network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99. - <network name
1074 or ID>[:OPTIONS,...]: Connect to a user-defined network; this is the
1075 network name or ID from a network created by podman network create. Us‐
1076 ing the network name implies the bridge network mode. It is possible to
1077 specify the same options described under the bridge mode above. You can
1078 use the --network option multiple times to specify additional networks.
1079 - none: Create a network namespace for the container but do not config‐
1080 ure network interfaces for it, thus the container has no network con‐
1081 nectivity. - container:id: Reuse another container's network stack. -
1082 host: Do not create a network namespace, the container will use the
1083 host's network. Note: The host mode gives the container full access to
1084 local system services such as D-bus and is therefore considered inse‐
1085 cure. - ns:path: Path to a network namespace to join. - private: Cre‐
1086 ate a new namespace for the container. This will use the bridge mode
1087 for rootful containers and slirp4netns for rootless ones. -
1088 slirp4netns[:OPTIONS,...]: use slirp4netns(1) to create a user network
1089 stack. This is the default for rootless containers. It is possible to
1090 specify these additional options, they can also be set with net‐
1091 work_cmd_options in containers.conf:
1092 - allow_host_loopback=true|false: Allow slirp4netns to reach the host
1093 loopback IP (default is 10.0.2.2 or the second IP from slirp4netns cidr
1094 subnet when changed, see the cidr option below). The default is false.
1095 - mtu=MTU: Specify the MTU to use for this network. (Default is
1096 65520).
1097 - cidr=CIDR: Specify ip range to use for this network. (Default is
1098 10.0.2.0/24).
1099 - enable_ipv6=true|false: Enable IPv6. Default is true. (Required for
1100 outbound_addr6).
1101 - outbound_addr=INTERFACE: Specify the outbound interface slirp
1102 should bind to (ipv4 traffic only).
1103 - outbound_addr=IPv4: Specify the outbound ipv4 address slirp should
1104 bind to.
1105 - outbound_addr6=INTERFACE: Specify the outbound interface slirp
1106 should bind to (ipv6 traffic only).
1107 - outbound_addr6=IPv6: Specify the outbound ipv6 address slirp should
1108 bind to.
1109 - port_handler=rootlesskit: Use rootlesskit for port forwarding. De‐
1110 fault.
1111 Note: Rootlesskit changes the source IP address of incoming packets
1112 to an IP address in the container network namespace, usually
1113 10.0.2.100. If your application requires the real source IP address,
1114 e.g. web server logs, use the slirp4netns port handler. The rootlesskit
1115 port handler is also used for rootless containers when connected to
1116 user-defined networks.
1117 - port_handler=slirp4netns: Use the slirp4netns port forwarding, it
1118 is slower than rootlesskit but preserves the correct source IP address.
1119 This port handler cannot be used for user-defined networks.
1120 Invalid if using --dns, --dns-option, or --dns-search with --network
1123 set to none or container:id.
1124 If used together with --pod, the container will not join the pod's net‐
1127 work namespace.
1128 --network-alias=alias
1131 Add a network-scoped alias for the container, setting the alias for all
1132 networks that the container joins. To set a name only for a specific
1133 network, use the alias option as described under the --network option.
1134 If the network has DNS enabled (podman network inspect -f {{.DNSEn‐
1135 abled}} <name>), these aliases can be used for name resolution on the
1136 given network. This option can be specified multiple times. NOTE: When
1137 using CNI a container will only have access to aliases on the first
1138 network that it joins. This limitation does not exist with ne‐
1139 tavark/aardvark-dns.
1140 --no-healthcheck
1143 Disable any defined healthchecks for container.
1144 --no-hosts
1147 Do not create /etc/hosts for the container. By default, Podman will
1148 manage /etc/hosts, adding the container's own IP address and any hosts
1149 from --add-host. --no-hosts disables this, and the image's /etc/hosts
1150 will be preserved unmodified.
1151 This option conflicts with --add-host.
1154 --oom-kill-disable
1157 Whether to disable OOM Killer for the container or not.
1158 This flag is not supported on cgroups V2 systems.
1161 --oom-score-adj=num
1164 Tune the host's OOM preferences for containers (accepts values from
1165 -1000 to 1000).
1166 --os=OS
1169 Override the OS, defaults to hosts, of the image to be pulled. For ex‐
1170 ample, windows. Unless overridden, subsequent lookups of the same im‐
1171 age in the local storage will match this OS, regardless of the host.
1172 --passwd-entry=ENTRY
1175 Customize the entry that is written to the /etc/passwd file within the
1176 container when --passwd is used.
1177 The variables $USERNAME, $UID, $GID, $NAME, $HOME are automatically re‐
1180 placed with their value at runtime.
1181 --personality=persona
1184 Personality sets the execution domain via Linux personality(2).
1185 --pid=mode
1188 Set the PID namespace mode for the container. The default is to create
1189 a private PID namespace for the container.
1190 • container:id: join another container's PID namespace;
1193 • host: use the host's PID namespace for the container. Note the
1195 host mode gives the container full access to local PID and is
1196 therefore considered insecure;
1197 • ns:path: join the specified PID namespace;
1199 • private: create a new namespace for the container (default).
1201 --pidfile=path
1205 When the pidfile location is specified, the container process' PID will
1206 be written to the pidfile. (This option is not available with the re‐
1207 mote Podman client, including Mac and Windows (excluding WSL2) ma‐
1208 chines) If the pidfile option is not specified, the container process'
1209 PID will be written to /run/containers/storage/${storage-driver}-con‐
1210 tainers/$CID/userdata/pidfile.
1211 After the container is started, the location for the pidfile can be
1214 discovered with the following podman inspect command:
1215 $ podman inspect --format '{{ .PidFile }}' $CID
1218 /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile
1219 --pids-limit=limit
1223 Tune the container's pids limit. Set to -1 to have unlimited pids for
1224 the container. The default is 4096 on systems that support "pids"
1225 cgroup controller.
1226 --platform=OS/ARCH
1229 Specify the platform for selecting the image. (Conflicts with --arch
1230 and --os) The --platform option can be used to override the current ar‐
1231 chitecture and operating system. Unless overridden, subsequent lookups
1232 of the same image in the local storage will match this platform, re‐
1233 gardless of the host.
1234 --pod=name
1237 Run container in an existing pod. If you want Podman to make the pod
1238 for you, prefix the pod name with new:. To make a pod with more granu‐
1239 lar options, use the podman pod create command before creating a con‐
1240 tainer. If a container is run with a pod, and the pod has an infra-
1241 container, the infra-container will be started before the container is.
1242 --pod-id-file=file
1245 Run container in an existing pod and read the pod's ID from the speci‐
1246 fied file. If a container is run within a pod, and the pod has an in‐
1247 fra-container, the infra-container will be started before the container
1248 is.
1249 --privileged
1252 Give extended privileges to this container. The default is false.
1253 By default, Podman containers are unprivileged (=false) and cannot, for
1256 example, modify parts of the operating system. This is because by de‐
1257 fault a container is only allowed limited access to devices. A "privi‐
1258 leged" container is given the same access to devices as the user
1259 launching the container.
1260 A privileged container turns off the security features that isolate the
1263 container from the host. Dropped Capabilities, limited devices, read-
1264 only mount points, Apparmor/SELinux separation, and Seccomp filters are
1265 all disabled.
1266 Rootless containers cannot have more privileges than the account that
1269 launched them.
1270 --publish, -p=[[ip:][hostPort]:]containerPort[/protocol]
1273 Publish a container's port, or range of ports, to the host.
1274 Both hostPort and containerPort can be specified as a range of ports.
1277 When specifying ranges for both, the number of container ports in the
1278 range must match the number of host ports in the range.
1279 If host IP is set to 0.0.0.0 or not set at all, the port will be bound
1282 on all IPs on the host.
1283 By default, Podman will publish TCP ports. To publish a UDP port in‐
1286 stead, give udp as protocol. To publish both TCP and UDP ports, set
1287 --publish twice, with tcp, and udp as protocols respectively. Rootful
1288 containers can also publish ports using the sctp protocol.
1289 Host port does not have to be specified (e.g. podman run -p
1292 127.0.0.1::80). If it is not, the container port will be randomly as‐
1293 signed a port on the host.
1294 Use podman port to see the actual mapping: podman port $CONTAINER $CON‐
1297 TAINERPORT.
1298 Note: If a container will be run within a pod, it is not necessary to
1301 publish the port for the containers in the pod. The port must only be
1302 published by the pod itself. Pod network stacks act like the network
1303 stack on the host - you have a variety of containers in the pod, and
1304 programs in the container, all sharing a single interface and IP ad‐
1305 dress, and associated ports. If one container binds to a port, no other
1306 container can use that port within the pod while it is in use. Contain‐
1307 ers in the pod can also communicate over localhost by having one con‐
1308 tainer bind to localhost in the pod, and another connect to that port.
1309 --publish-all, -P
1312 Publish all exposed ports to random ports on the host interfaces. The
1313 default is false.
1314 When set to true, publish all exposed ports to the host interfaces. If
1317 the operator uses -P (or -p) then Podman will make the exposed port ac‐
1318 cessible on the host and the ports will be available to any client that
1319 can reach the host.
1320 When using this option, Podman will bind any exposed port to a random
1323 port on the host within an ephemeral port range defined by
1324 /proc/sys/net/ipv4/ip_local_port_range. To find the mapping between
1325 the host ports and the exposed ports, use podman port.
1326 --pull=policy
1329 Pull image policy. The default is missing.
1330 • always: Always pull the image and throw an error if the pull
1333 fails.
1334 • missing: Pull the image only if it could not be found in the
1336 local containers storage. Throw an error if no image could be
1337 found and the pull fails.
1338 • never: Never pull the image but use the one from the local
1340 containers storage. Throw an error if no image could be
1341 found.
1342 • newer: Pull if the image on the registry is newer than the one
1344 in the local containers storage. An image is considered to be
1345 newer when the digests are different. Comparing the time
1346 stamps is prone to errors. Pull errors are suppressed if a
1347 local image was found.
1348 --quiet, -q
1352 Suppress output information when pulling images
1353 --read-only
1356 Mount the container's root filesystem as read-only.
1357 By default a container will have its root filesystem writable allowing
1360 processes to write files anywhere. By specifying the --read-only flag,
1361 the container will have its root filesystem mounted as read-only pro‐
1362 hibiting any writes.
1363 --read-only-tmpfs
1366 If container is running in --read-only mode, then mount a read-write
1367 tmpfs on /run, /tmp, and /var/tmp. The default is true.
1368 --replace
1371 If another container with the same name already exists, replace and re‐
1372 move it. The default is false.
1373 --requires=container
1376 Specify one or more requirements. A requirement is a dependency con‐
1377 tainer that will be started before this container. Containers can be
1378 specified by name or ID, with multiple containers being separated by
1379 commas.
1380 --restart=policy
1383 Restart policy to follow when containers exit. Restart policy will not
1384 take effect if a container is stopped via the podman kill or podman
1385 stop commands.
1386 Valid policy values are:
1389 • no : Do not restart containers on exit
1392 • on-failure[:max_retries] : Restart containers when they exit
1394 with a non-zero exit code, retrying indefinitely or until the
1395 optional max_retries count is hit
1396 • always : Restart containers when they exit,
1398 regardless of status, retrying indefinitely
1399 • unless-stopped : Identical to always
1401 Please note that restart will not restart containers after a system re‐
1405 boot. If this functionality is required in your environment, you can
1406 invoke Podman from a systemd.unit(5) file, or create an init script for
1407 whichever init system is in use. To generate systemd unit files,
1408 please see podman generate systemd.
1409 --rm
1412 Automatically remove the container when it exits. The default is false.
1413 --rootfs
1416 If specified, the first argument refers to an exploded container on the
1417 file system.
1418 This is useful to run a container without requiring any image manage‐
1421 ment, the rootfs of the container is assumed to be managed externally.
1422 Overlay Rootfs Mounts
1425 The :O flag tells Podman to mount the directory from the rootfs path as
1428 storage using the overlay file system. The container processes can mod‐
1429 ify content within the mount point which is stored in the container
1430 storage in a separate directory. In overlay terms, the source directory
1431 will be the lower, and the container storage directory will be the up‐
1432 per. Modifications to the mount point are destroyed when the container
1433 finishes executing, similar to a tmpfs mount point being unmounted.
1434 Note: On SELinux systems, the rootfs needs the correct label, which is
1437 by default unconfined_u:object_r:container_file_t:s0.
1438 --sdnotify=container | conmon | ignore
1441 Determines how to use the NOTIFY_SOCKET, as passed with systemd and
1442 Type=notify.
1443 Default is container, which means allow the OCI runtime to proxy the
1446 socket into the container to receive ready notification. Podman will
1447 set the MAINPID to conmon's pid. The conmon option sets MAINPID to
1448 conmon's pid, and sends READY when the container has started. The
1449 socket is never passed to the runtime or the container. The ignore op‐
1450 tion removes NOTIFY_SOCKET from the environment for itself and child
1451 processes, for the case where some other process above Podman uses NO‐
1452 TIFY_SOCKET and Podman should not use it.
1453 --seccomp-policy=policy
1456 Specify the policy to select the seccomp profile. If set to image, Pod‐
1457 man will look for a "io.containers.seccomp.profile" label in the con‐
1458 tainer-image config and use its value as a seccomp profile. Otherwise,
1459 Podman will follow the default policy by applying the default profile
1460 unless specified otherwise via --security-opt seccomp as described be‐
1461 low.
1462 Note that this feature is experimental and may change in the future.
1465 --secret=secret[,opt=opt ...]
1468 Give the container access to a secret. Can be specified multiple times.
1469 A secret is a blob of sensitive data which a container needs at runtime
1472 but should not be stored in the image or in source control, such as
1473 usernames and passwords, TLS certificates and keys, SSH keys or other
1474 important generic strings or binary content (up to 500 kb in size).
1475 When secrets are specified as type mount, the secrets are copied and
1478 mounted into the container when a container is created. When secrets
1479 are specified as type env, the secret will be set as an environment
1480 variable within the container. Secrets are written in the container at
1481 the time of container creation, and modifying the secret using podman
1482 secret commands after the container is created will not affect the se‐
1483 cret inside the container.
1484 Secrets and its storage are managed using the podman secret command.
1487 Secret Options
1490 • type=mount|env : How the secret will be exposed to the con‐
1493 tainer. Default mount.
1494 • target=target : Target of secret. Defaults to secret name.
1496 • uid=0 : UID of secret. Defaults to 0. Mount secret
1498 type only.
1499 • gid=0 : GID of secret. Defaults to 0. Mount secret
1501 type only.
1502 • mode=0 : Mode of secret. Defaults to 0444. Mount
1504 secret type only.
1505 --security-opt=option
1509 Security Options
1510 • apparmor=unconfined : Turn off apparmor confinement for the
1513 container
1514 • apparmor=your-profile : Set the apparmor confinement profile
1516 for the container
1517 • label=user:USER : Set the label user for the container
1519 processes
1520 • label=role:ROLE : Set the label role for the container
1522 processes
1523 • label=type:TYPE : Set the label process type for the con‐
1525 tainer processes
1526 • label=level:LEVEL : Set the label level for the container
1528 processes
1529 • label=filetype:TYPE : Set the label file type for the con‐
1531 tainer files
1532 • label=disable : Turn off label separation for the con‐
1534 tainer
1535 Note: Labeling can be disabled for all containers by setting la‐
1539 bel=false in the containers.conf (/etc/containers/containers.conf or
1540 $HOME/.config/containers/containers.conf) file.
1541 • mask=/path/1:/path/2 : The paths to mask separated by a colon.
1544 A masked path cannot be accessed inside the container.
1545 • no-new-privileges : Disable container processes from gaining
1547 additional privileges
1548 • seccomp=unconfined : Turn off seccomp confinement for the con‐
1550 tainer.
1551 • seccomp=profile.json : JSON file to be used as a seccomp fil‐
1553 ter. Note that the io.podman.annotations.seccomp annotation is
1554 set with the specified value as shown in podman inspect.
1555 • proc-opts=OPTIONS : Comma-separated list of options to use for
1557 the /proc mount. More details for the possible mount options
1558 are specified in the proc(5) man page.
1559 • unmask=ALL or /path/1:/path/2, or shell expanded paths
1561 (/proc/*): Paths to unmask separated by a colon. If set to
1562 ALL, it will unmask all the paths that are masked or made
1563 read-only by default. The default masked paths are
1564 /proc/acpi, /proc/kcore, /proc/keys, /proc/latency_stats,
1565 /proc/sched_debug, /proc/scsi, /proc/timer_list,
1566 /proc/timer_stats, /sys/firmware, and /sys/fs/selinux. The
1567 default paths that are read-only are /proc/asound, /proc/bus,
1568 /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trigger,
1569 /sys/fs/cgroup.
1570 Note: Labeling can be disabled for all containers by setting la‐
1574 bel=false in the containers.conf (/etc/containers/containers.conf or
1575 $HOME/.config/containers/containers.conf) file.
1576 --shm-size=number[unit]
1579 Size of /dev/shm. A unit can be b (bytes), k (kibibytes), m
1580 (mebibytes), or g (gibibytes). If the unit is omitted, the system uses
1581 bytes. If the size is omitted, the default is 64m. When size is 0,
1582 there is no limit on the amount of memory used for IPC by the con‐
1583 tainer. This option conflicts with --ipc=host.
1584 --stop-signal=signal
1587 Signal to stop a container. Default is SIGTERM.
1588 --stop-timeout=seconds
1591 Timeout to stop a container. Default is 10. Remote connections use lo‐
1592 cal containers.conf for defaults
1593 --subgidname=name
1596 Run the container in a new user namespace using the map with name in
1597 the /etc/subgid file. If running rootless, the user needs to have the
1598 right to use the mapping. See subgid(5). This flag conflicts with
1599 --userns and --gidmap.
1600 --subuidname=name
1603 Run the container in a new user namespace using the map with name in
1604 the /etc/subuid file. If running rootless, the user needs to have the
1605 right to use the mapping. See subuid(5). This flag conflicts with
1606 --userns and --uidmap.
1607 --sysctl=name=value
1610 Configure namespaced kernel parameters at runtime.
1611 For the IPC namespace, the following sysctls are allowed:
1614 • kernel.msgmax
1617 • kernel.msgmnb
1619 • kernel.msgmni
1621 • kernel.sem
1623 • kernel.shmall
1625 • kernel.shmmax
1627 • kernel.shmmni
1629 • kernel.shm_rmid_forced
1631 • Sysctls beginning with fs.mqueue.*
1633 Note: if you use the --ipc=host option, the above sysctls are not al‐
1637 lowed.
1638 For the network namespace, only sysctls beginning with net.* are al‐
1641 lowed.
1642 Note: if you use the --network=host option, the above sysctls are not
1645 allowed.
1646 --systemd=true | false | always
1649 Run container in systemd mode. The default is true.
1650 The value always enforces the systemd mode is enforced without looking
1653 at the executable name. Otherwise, if set to true and the command you
1654 are running inside the container is systemd, /usr/sbin/init, /sbin/init
1655 or /usr/local/sbin/init.
1656 Running the container in systemd mode causes the following changes:
1659 • Podman mounts tmpfs file systems on the following directories
1662 • /run
1664 • /run/lock
1666 • /tmp
1668 • /sys/fs/cgroup/systemd
1670 • /var/lib/journal
1672 • Podman sets the default stop signal to SIGRTMIN+3.
1676 • Podman sets container_uuid environment variable in the con‐
1678 tainer to the first 32 characters of the container id.
1679 This allows systemd to run in a confined container without any modifi‐
1683 cations.
1684 Note that on SELinux systems, systemd attempts to write to the cgroup
1687 file system. Containers writing to the cgroup file system are denied by
1688 default. The container_manage_cgroup boolean must be enabled for this
1689 to be allowed on an SELinux separated system.
1690 setsebool -P container_manage_cgroup true
1693 --timeout=seconds
1697 Maximum time a container is allowed to run before conmon sends it the
1698 kill signal. By default containers will run until they exit or are
1699 stopped by podman stop.
1700 --tls-verify
1703 Require HTTPS and verify certificates when contacting registries (de‐
1704 fault: true). If explicitly set to true, TLS verification will be
1705 used. If set to false, TLS verification will not be used. If not
1706 specified, TLS verification will be used unless the target registry is
1707 listed as an insecure registry in containers-registries.conf(5)
1708 --tmpfs=fs
1711 Create a tmpfs mount.
1712 Mount a temporary filesystem (tmpfs) mount into a container, for exam‐
1715 ple:
1716 $ podman create -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
1719 This command mounts a tmpfs at /tmp within the container. The supported
1723 mount options are the same as the Linux default mount flags. If you do
1724 not specify any options, the system uses the following options:
1725 rw,noexec,nosuid,nodev.
1726 --tty, -t
1729 Allocate a pseudo-TTY. The default is false.
1730 When set to true, Podman will allocate a pseudo-tty and attach to the
1733 standard input of the container. This can be used, for example, to run
1734 a throwaway interactive shell.
1735 NOTE: The --tty flag prevents redirection of standard output. It com‐
1738 bines STDOUT and STDERR, it can insert control characters, and it can
1739 hang pipes. This option should only be used when run interactively in a
1740 terminal. When feeding input to Podman, use -i only, not -it.
1741 --tz=timezone
1744 Set timezone in container. This flag takes area-based timezones, GMT
1745 time, as well as local, which sets the timezone in the container to
1746 match the host machine. See /usr/share/zoneinfo/ for valid timezones.
1747 Remote connections use local containers.conf for defaults
1748 --uidmap=container_uid:from_uid:amount
1751 Run the container in a new user namespace using the supplied UID map‐
1752 ping. This option conflicts with the --userns and --subuidname options.
1753 This option provides a way to map host UIDs to container UIDs. It can
1754 be passed several times to map different ranges.
1755 The _fromuid value is based upon the user running the command, either
1758 rootful or rootless users. * rootful user: con‐
1759 tainer_uid:host_uid:amount * rootless user: container_uid:intermedi‐
1760 ate_uid:amount
1761 When podman create is called by a privileged user, the option --uidmap
1764 works as a direct mapping between host UIDs and container UIDs.
1765 host UID -> container UID
1768 The amount specifies the number of consecutive UIDs that will be
1771 mapped. If for example amount is 4 the mapping would look like:
1772 | host UID | container UID | | - | -
1775 | | _fromuid | _containeruid | | _fromuid + 1 | _containeruid +
1776 1 | | _fromuid + 2 | _containeruid + 2 | | _fromuid + 3 | _containeruid
1777 + 3 |
1778 When podman create is called by an unprivileged user (i.e. running
1781 rootless), the value _fromuid is interpreted as an "intermediate UID".
1782 In the rootless case, host UIDs are not mapped directly to container
1783 UIDs. Instead the mapping happens over two mapping steps:
1784 host UID -> intermediate UID -> container UID
1787 The --uidmap option only influences the second mapping step.
1790 The first mapping step is derived by Podman from the contents of the
1793 file /etc/subuid and the UID of the user calling Podman.
1794 First mapping step:
1797 | host UID | intermediate UID |
1800 | - | - |
1801 | UID for the user starting Podman | 0 |
1802 | 1st subordinate UID for the user starting Podman | 1 |
1803 | 2nd subordinate UID for the user starting Podman | 2 |
1804 | 3rd subordinate UID for the user starting Podman | 3 |
1805 | nth subordinate UID for the user starting Podman | n |
1806 To be able to use intermediate UIDs greater than zero, the user needs
1809 to have subordinate UIDs configured in /etc/subuid. See subuid(5).
1810 The second mapping step is configured with --uidmap.
1813 If for example amount is 5 the second mapping step would look like:
1816 | intermediate UID | container UID | | - |
1819 - | | _fromuid | _containeruid | |
1820 _fromuid + 1 | _containeruid + 1 | | _fromuid + 2 | _con‐
1821 taineruid + 2 | | _fromuid + 3 | _containeruid + 3 | | _fromuid +
1822 4 | _containeruid + 4 |
1823 When running as rootless, Podman will use all the ranges configured in
1826 the /etc/subuid file.
1827 The current user ID is mapped to UID=0 in the rootless user namespace.
1830 Every additional range is added sequentially afterward:
1831 | host |rootless user namespace | length
1834 | | - | - | -
1835 | | $UID | 0 | 1
1836 | | 1 | $FIRST_RANGE_ID |
1837 $FIRST_RANGE_LENGTH | | 1+$FIRST_RANGE_LENGTH | $SECOND_RANGE_ID
1838 | $SECOND_RANGE_LENGTH|
1839 Even if a user does not have any subordinate UIDs in /etc/subuid,
1842 --uidmap could still be used to map the normal UID of the user to a
1843 container UID by running podman create --uidmap $container_uid:0:1
1844 --user $container_uid ....
1845 Note: the --uidmap flag cannot be called in conjunction with the --pod
1848 flag as a uidmap cannot be set on the container level when in a pod.
1849 --ulimit=option
1852 Ulimit options. You can use host to copy the current configuration from
1853 the host.
1854 --umask=umask
1857 Set the umask inside the container. Defaults to 0022. Remote connec‐
1858 tions use local containers.conf for defaults
1859 --unsetenv=env
1862 Unset default environment variables for the container. Default environ‐
1863 ment variables include variables provided natively by Podman, environ‐
1864 ment variables configured by the image, and environment variables from
1865 containers.conf.
1866 --unsetenv-all
1869 Unset all default environment variables for the container. Default en‐
1870 vironment variables include variables provided natively by Podman, en‐
1871 vironment variables configured by the image, and environment variables
1872 from containers.conf.
1873 --user, -u=user[:group]
1876 Sets the username or UID used and, optionally, the groupname or GID for
1877 the specified command. Both user and group may be symbolic or numeric.
1878 Without this argument, the command will run as the user specified in
1881 the container image. Unless overridden by a USER command in the Con‐
1882 tainerfile or by a value passed to this option, this user generally de‐
1883 faults to root.
1884 When a user namespace is not in use, the UID and GID used within the
1887 container and on the host will match. When user namespaces are in use,
1888 however, the UID and GID in the container may correspond to another UID
1889 and GID on the host. In rootless containers, for example, a user name‐
1890 space is always used, and root in the container will by default corre‐
1891 spond to the UID and GID of the user invoking Podman.
1892 --userns=mode
1895 Set the user namespace mode for the container. It defaults to the POD‐
1896 MAN_USERNS environment variable. An empty value ("") means user name‐
1897 spaces are disabled unless an explicit mapping is set with the --uidmap
1898 and --gidmap options.
1899 This option is incompatible with --gidmap, --uidmap, --subuidname and
1902 --subgidname.
1903 Rootless user --userns=Key mappings:
1906 ┌────────┬───────────┬─────────────────────┐
1909 │Key │ Host User │ Container User │
1910 ├────────┼───────────┼─────────────────────┤
1911 │"" │ $UID │ 0 (Default User ac‐ │
1912 │ │ │ count mapped to │
1913 │ │ │ root user in con‐ │
1914 │ │ │ tainer.) │
1915 ├────────┼───────────┼─────────────────────┤
1916 │keep-id │ $UID │ $UID (Map user ac‐ │
1917 │ │ │ count to same UID │
1918 │ │ │ within container.) │
1919 ├────────┼───────────┼─────────────────────┤
1920 │auto │ $UID │ nil (Host User UID │
1921 │ │ │ is not mapped into │
1922 │ │ │ container.) │
1923 ├────────┼───────────┼─────────────────────┤
1924 │nomap │ $UID │ nil (Host User UID │
1925 │ │ │ is not mapped into │
1926 │ │ │ container.) │
1927 └────────┴───────────┴─────────────────────┘
1928 Valid mode values are:
1930 auto[:OPTIONS,...]: automatically create a unique user namespace.
1933 The --userns=auto flag, requires that the user name containers and a
1936 range of subordinate user ids that the Podman container is allowed to
1937 use be specified in the /etc/subuid and /etc/subgid files.
1938 Example: containers:2147483647:2147483648.
1941 Podman allocates unique ranges of UIDs and GIDs from the containers
1944 subordinate user ids. The size of the ranges is based on the number of
1945 UIDs required in the image. The number of UIDs and GIDs can be overrid‐
1946 den with the size option.
1947 The rootless option --userns=keep-id uses all the subuids and subgids
1950 of the user. Using --userns=auto when starting new containers will not
1951 work as long as any containers exist that were started with
1952 --userns=keep-id.
1953 Valid auto options:
1956 • gidmapping=_CONTAINER_GID:HOSTGID:SIZE: to force a GID mapping
1959 to be present in the user namespace.
1960 • size=SIZE: to specify an explicit size for the automatic user
1962 namespace. e.g. --userns=auto:size=8192. If size is not speci‐
1963 fied, auto will estimate a size for the user namespace.
1964 • uidmapping=_CONTAINER_UID:HOSTUID:SIZE: to force a UID mapping
1966 to be present in the user namespace.
1967 container:id: join the user namespace of the specified container.
1971 host: run in the user namespace of the caller. The processes running in
1974 the container will have the same privileges on the host as any other
1975 process launched by the calling user (default).
1976 keep-id: creates a user namespace where the current rootless user's
1979 UID:GID are mapped to the same values in the container. This option is
1980 not allowed for containers created by the root user.
1981 Valid keep-id options:
1984 • uid=UID: override the UID inside the container that will be
1987 used to map the current rootless user to.
1988 • gid=GID: override the GID inside the container that will be
1990 used to map the current rootless user to.
1991 nomap: creates a user namespace where the current rootless user's
1995 UID:GID are not mapped into the container. This option is not allowed
1996 for containers created by the root user.
1997 ns:namespace: run the container in the given existing user namespace.
2000 --uts=mode
2003 Set the UTS namespace mode for the container. The following values are
2004 supported:
2005 • host: use the host's UTS namespace inside the container.
2008 • private: create a new namespace for the container (default).
2010 • ns:[path]: run the container in the given existing UTS name‐
2012 space.
2013 • container:[container]: join the UTS namespace of the specified
2015 container.
2016 --variant=VARIANT
2020 Use VARIANT instead of the default architecture variant of the con‐
2021 tainer image. Some images can use multiple variants of the arm archi‐
2022 tectures, such as arm/v5 and arm/v7.
2023 --volume, -v=[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]
2026 Create a bind mount. If -v /HOST-DIR:/CONTAINER-DIR is specified, Pod‐
2027 man bind mounts /HOST-DIR from the host into /CONTAINER-DIR in the Pod‐
2028 man container. Similarly, -v SOURCE-VOLUME:/CONTAINER-DIR will mount
2029 the named volume from the host into the container. If no such named
2030 volume exists, Podman will create one. If no source is given, the vol‐
2031 ume will be created as an anonymously named volume with a randomly gen‐
2032 erated name, and will be removed when the container is removed via the
2033 --rm flag or the podman rm --volumes command.
2034 (Note when using the remote client, including Mac and Windows (exclud‐
2037 ing WSL2) machines, the volumes will be mounted from the remote server,
2038 not necessarily the client machine.)
2039 The OPTIONS is a comma-separated list and can be: [1] ⟨#Footnote1⟩
2042 • rw|ro
2045 • z|Z
2047 • [O]
2049 • [U]
2051 • [no]copy
2053 • [no]dev
2055 • [no]exec
2057 • [no]suid
2059 • [r]bind
2061 • [r]shared|[r]slave|[r]private[r]unbindable
2063 The CONTAINER-DIR must be an absolute path such as /src/docs. The vol‐
2067 ume will be mounted into the container at this directory.
2068 If a volume source is specified, it must be a path on the host or the
2071 name of a named volume. Host paths are allowed to be absolute or rela‐
2072 tive; relative paths are resolved relative to the directory Podman is
2073 run in. If the source does not exist, Podman will return an error.
2074 Users must pre-create the source files or directories.
2075 Any source that does not begin with a . or / will be treated as the
2078 name of a named volume. If a volume with that name does not exist, it
2079 will be created. Volumes created with names are not anonymous, and
2080 they are not removed by the --rm option and the podman rm --volumes
2081 command.
2082 Specify multiple -v options to mount one or more volumes into a con‐
2085 tainer.
2086 Write Protected Volume Mounts
2089 Add :ro or :rw option to mount a volume in read-only or read-write
2092 mode, respectively. By default, the volumes are mounted read-write.
2093 See examples.
2094 Chowning Volume Mounts
2097 By default, Podman does not change the owner and group of source volume
2100 directories mounted into containers. If a container is created in a new
2101 user namespace, the UID and GID in the container may correspond to an‐
2102 other UID and GID on the host.
2103 The :U suffix tells Podman to use the correct host UID and GID based on
2106 the UID and GID within the container, to change recursively the owner
2107 and group of the source volume.
2108 Warning use with caution since this will modify the host filesystem.
2111 Labeling Volume Mounts
2114 Labeling systems like SELinux require that proper labels are placed on
2117 volume content mounted into a container. Without a label, the security
2118 system might prevent the processes running inside the container from
2119 using the content. By default, Podman does not change the labels set by
2120 the OS.
2121 To change a label in the container context, add either of two suffixes
2124 :z or :Z to the volume mount. These suffixes tell Podman to relabel
2125 file objects on the shared volumes. The z option tells Podman that two
2126 containers share the volume content. As a result, Podman labels the
2127 content with a shared content label. Shared volume labels allow all
2128 containers to read/write content. The Z option tells Podman to label
2129 the content with a private unshared label. Only the current container
2130 can use a private volume.
2131 Note: Do not relabel system files and directories. Relabeling system
2134 content might cause other confined services on your machine to fail.
2135 For these types of containers we recommend disabling SELinux separa‐
2136 tion. The option --security-opt label=disable disables SELinux separa‐
2137 tion for the container. For example if a user wanted to volume mount
2138 their entire home directory into a container, they need to disable
2139 SELinux separation.
2140 $ podman create --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file
2143 Overlay Volume Mounts
2147 The :O flag tells Podman to mount the directory from the host as a tem‐
2150 porary storage using the overlay file system. The container processes
2151 can modify content within the mountpoint which is stored in the con‐
2152 tainer storage in a separate directory. In overlay terms, the source
2153 directory will be the lower, and the container storage directory will
2154 be the upper. Modifications to the mount point are destroyed when the
2155 container finishes executing, similar to a tmpfs mount point being un‐
2156 mounted.
2157 For advanced users, the overlay option also supports custom non-
2160 volatile upperdir and workdir for the overlay mount. Custom upperdir
2161 and workdir can be fully managed by the users themselves, and Podman
2162 will not remove it on lifecycle completion. Example :O,up‐
2163 perdir=/some/upper,workdir=/some/work
2164 Subsequent executions of the container will see the original source di‐
2167 rectory content, any changes from previous container executions no
2168 longer exist.
2169 One use case of the overlay mount is sharing the package cache from the
2172 host into the container to allow speeding up builds.
2173 Note:
2176 - The `O` flag conflicts with other options listed above.
2179 Content mounted into the container is labeled with the private label.
2183 On SELinux systems, labels in the source directory must be read‐
2184 able by the container label. Usually containers can read/execute con‐
2185 tainer_share_t and can read/write container_file_t. If unable to change
2186 the labels on a source volume, SELinux container separation must be
2187 disabled for the container to work.
2188 - The source directory mounted into the container with an overlay
2189 mount should not be modified, it can cause unexpected failures. It is
2190 recommended to not modify the directory until the container finishes
2191 running.
2192 Mounts propagation
2195 By default bind mounted volumes are private. That means any mounts done
2198 inside the container will not be visible on host and vice versa. One
2199 can change this behavior by specifying a volume mount propagation prop‐
2200 erty. Making a volume shared mounts done under that volume inside the
2201 container will be visible on host and vice versa. Making a volume slave
2202 enables only one way mount propagation and that is mounts done on host
2203 under that volume will be visible inside container but not the other
2204 way around. [1] ⟨#Footnote1⟩
2205 To control mount propagation property of a volume one can use the
2208 [r]shared, [r]slave, [r]private or the [r]unbindable propagation flag.
2209 Propagation property can be specified only for bind mounted volumes and
2210 not for internal volumes or named volumes. For mount propagation to
2211 work the source mount point (the mount point where source dir is
2212 mounted on) has to have the right propagation properties. For shared
2213 volumes, the source mount point has to be shared. And for slave vol‐
2214 umes, the source mount point has to be either shared or slave. [1]
2215 ⟨#Footnote1⟩
2216 To recursively mount a volume and all of its submounts into a con‐
2219 tainer, use the rbind option. By default the bind option is used, and
2220 submounts of the source directory will not be mounted into the con‐
2221 tainer.
2222 Mounting the volume with the nosuid options means that SUID applica‐
2225 tions on the volume will not be able to change their privilege. By de‐
2226 fault volumes are mounted with nosuid.
2227 Mounting the volume with the noexec option means that no executables on
2230 the volume will be able to be executed within the container.
2231 Mounting the volume with the nodev option means that no devices on the
2234 volume will be able to be used by processes within the container. By
2235 default volumes are mounted with nodev.
2236 If the HOST-DIR is a mount point, then dev, suid, and exec options are
2239 ignored by the kernel.
2240 Use df HOST-DIR to figure out the source mount, then use findmnt -o
2243 TARGET,PROPAGATION source-mount-dir to figure out propagation proper‐
2244 ties of source mount. If findmnt[4m(1) utility is not available, then one
2245 can look at the mount entry for the source mount point in
2246 /proc/self/mountinfo. Look at the "optional fields" and see if any
2247 propagation properties are specified. In there, shared:N means the
2248 mount is shared, master:N means mount is slave, and if nothing is
2249 there, the mount is private. [1] ⟨#Footnote1⟩
2250 To change propagation properties of a mount point, use mount(8) com‐
2253 mand. For example, if one wants to bind mount source directory /foo,
2254 one can do mount --bind /foo /foo and mount --make-private --make-
2255 shared /foo. This will convert /foo into a shared mount point. Alterna‐
2256 tively, one can directly change propagation properties of source mount.
2257 Say / is source mount for /foo, then use mount --make-shared / to con‐
2258 vert / into a shared mount.
2259 Note: if the user only has access rights via a group, accessing the
2262 volume from inside a rootless container will fail.
2263 Use the --group-add keep-groups option to pass the user's supplementary
2266 group access into the container.
2267 --volumes-from=CONTAINER[:OPTIONS]
2270 Mount volumes from the specified container(s). Used to share volumes
2271 between containers. The options is a comma-separated list with the fol‐
2272 lowing available elements:
2273 • rw|ro
2276 • z
2278 Mounts already mounted volumes from a source container onto another
2282 container. CONTAINER may be a name or ID. To share a volume, use the
2283 --volumes-from option when running the target container. Volumes can be
2284 shared even if the source container is not running.
2285 By default, Podman mounts the volumes in the same mode (read-write or
2288 read-only) as it is mounted in the source container. This can be
2289 changed by adding a ro or rw option.
2290 Labeling systems like SELinux require that proper labels are placed on
2293 volume content mounted into a container. Without a label, the security
2294 system might prevent the processes running inside the container from
2295 using the content. By default, Podman does not change the labels set by
2296 the OS.
2297 To change a label in the container context, add z to the volume mount.
2300 This suffix tells Podman to relabel file objects on the shared volumes.
2301 The z option tells Podman that two entities share the volume content.
2302 As a result, Podman labels the content with a shared content label.
2303 Shared volume labels allow all containers to read/write content.
2304 If the location of the volume from the source container overlaps with
2307 data residing on a target container, then the volume hides that data on
2308 the target.
2309 --workdir, -w=dir
2312 Working directory inside the container.
2313 The default working directory for running binaries within a container
2316 is the root directory (/). The image developer can set a different de‐
2317 fault with the WORKDIR instruction. The operator can override the work‐
2318 ing directory by using the -w option.
2319
2322 Create a container using a local image
2323 $ podman create alpine ls
2324 Create a container using a local image and annotate it
2328 $ podman create --annotation HELLO=WORLD alpine ls
2329 Create a container using a local image, allocating a pseudo-TTY, keeping
2333 stdin open and name it myctr
2334 podman create -t -i --name myctr alpine ls
2335 Set UID/GID mapping in a new user namespace
2339 Running a container in a new user namespace requires a mapping of the
2340 uids and gids from the host.
2341 $ podman create --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
2344 Setting automatic user namespace separated containers
2348 # podman create --userns=auto:size=65536 ubi8-init
2349 Configure timezone in a container
2353 $ podman create --tz=local alpine date
2354 $ podman create --tz=Asia/Shanghai alpine date
2355 $ podman create --tz=US/Eastern alpine date
2356 Adding dependency containers
2360 Podman will make sure the first container, container1, is running be‐
2361 fore the second container (container2) is started.
2362 $ podman create --name container1 -t -i fedora bash
2365 $ podman create --name container2 --requires container1 -t -i fedora bash
2366 $ podman start --attach container2
2367 Multiple containers can be required.
2371 $ podman create --name container1 -t -i fedora bash
2374 $ podman create --name container2 -t -i fedora bash
2375 $ podman create --name container3 --requires container1,container2 -t -i fedora bash
2376 $ podman start --attach container3
2377 Configure keep supplemental groups for access to volume
2381 $ podman create -v /var/lib/design:/var/lib/design --group-add keep-groups ubi8
2382 Configure execution domain for containers using personality flag
2386 $ podman create --name container1 --personality=LINUX32 fedora bash
2387 Create a container with external rootfs mounted as an overlay
2391 $ podman create --name container1 --rootfs /path/to/rootfs:O bash
2392 Create a container connected to two networks (called net1 and net2) with a
2396 static ip
2397 $ podman create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip addr
2398 Rootless Containers
2402 Podman runs as a non-root user on most systems. This feature requires
2403 that a new enough version of shadow-utils be installed. The shadow-
2404 utils package must include the newuidmap and newgidmap executables.
2405 In order for users to run rootless, there must be an entry for their
2408 username in /etc/subuid and /etc/subgid which lists the UIDs for their
2409 user namespace.
2410 Rootless Podman works better if the fuse-overlayfs and slirp4netns
2413 packages are installed. The fuse-overlayfs package provides a
2414 userspace overlay storage driver, otherwise users need to use the vfs
2415 storage driver, which is diskspace expensive and does not perform well.
2416 slirp4netns is required for VPN, without it containers need to be run
2417 with the --network=host flag.
2418
2421 Environment variables within containers can be set using multiple dif‐
2422 ferent options: This section describes the precedence.
2423 Precedence order (later entries override earlier entries):
2426 • --env-host : Host environment of the process executing Podman
2429 is added.
2430 • --http-proxy: By default, several environment variables will
2432 be passed in from the host, such as http_proxy and no_proxy.
2433 See --http-proxy for details.
2434 • Container image : Any environment variables specified in the
2436 container image.
2437 • --env-file : Any environment variables specified via env-
2439 files. If multiple files specified, then they override each
2440 other in order of entry.
2441 • --env : Any environment variables specified will override pre‐
2443 vious settings.
2444 Create containers and set the environment ending with a *. The trail‐
2448 ing * glob functionality is only active when no value is specified:
2449 $ export ENV1=a
2452 $ podman create --name ctr1 --env 'ENV*' alpine env
2453 $ podman start --attach ctr1 | grep ENV
2454 ENV1=a
2455 $ podman create --name ctr2 --env 'ENV*=b' alpine env
2456 $ podman start --attach ctr2 | grep ENV
2457 ENV*=b
2458
2462 When Podman starts a container it actually executes the conmon program,
2463 which then executes the OCI Runtime. Conmon is the container monitor.
2464 It is a small program whose job is to watch the primary process of the
2465 container, and if the container dies, save the exit code. It also
2466 holds open the tty of the container, so that it can be attached to
2467 later. This is what allows Podman to run in detached mode (back‐
2468 grounded), so Podman can exit but conmon continues to run. Each con‐
2469 tainer has their own instance of conmon. Conmon waits for the container
2470 to exit, gathers and saves the exit code, and then launches a Podman
2471 process to complete the container cleanup, by shutting down the network
2472 and storage. For more information on conmon, please reference the
2473 conmon(8) man page.
2474
2477 /etc/subuid /etc/subgid
2478 NOTE: Use the environment variable TMPDIR to change the temporary stor‐
2481 age location of downloaded container images. Podman defaults to use
2482 /var/tmp.
2483
2486 podman(1), podman-save(1), podman-ps(1), podman-attach(1), podman-pod-
2487 create(1), podman-port(1), podman-start(1), podman-kill(1), podman-
2488 stop(1), podman-generate-systemd(1), podman-rm(1), subgid(5), sub‐
2489 uid(5), containers.conf(5), systemd.unit(5), setsebool(8),
2490 slirp4netns(1), fuse-overlayfs(1), proc(5), conmon(8), personality(2)
2491
2494 October 2017, converted from Docker documentation to Podman by Dan
2495 Walsh for Podman <dwalsh@redhat.com>
2496 November 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2499 September 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2502 August 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2505
2508 1: The Podman project is committed to inclusivity, a core value of open
2509 source. The master and slave mount propagation terminology used here is
2510 problematic and divisive, and should be changed. However, these terms
2511 are currently used within the Linux kernel and must be used as-is at
2512 this time. When the kernel maintainers rectify this usage, Podman will
2513 follow suit immediately.
2514 podman-create(1)