1podman-run(1)() podman-run(1)()
2
6 podman-run - Run a command in a new container
7
10 podman run [options] image [command [arg ...]]
11 podman container run [options] image [command [arg ...]]
14
17 Run a process in a new container. podman run starts a process with its
18 own file system, its own networking, and its own isolated process tree.
19 The IMAGE which starts the process may define defaults related to the
20 process that will be run in the container, the networking to expose,
21 and more, but podman run gives final control to the operator or admin‐
22 istrator who starts the container from the image. For that reason pod‐
23 man run has more options than any other podman command.
24 If the IMAGE is not already loaded then podman run will pull the IMAGE,
27 and all image dependencies, from the repository in the same way running
28 podman pull IMAGE, before it starts the container from that image.
29 Several files will be automatically created within the container. These
32 include /etc/hosts, /etc/hostname, and /etc/resolv.conf to manage net‐
33 working. These will be based on the host's version of the files,
34 though they can be customized with options (for example, --dns will
35 override the host's DNS servers in the created resolv.conf). Addition‐
36 ally, an empty file is created in each container to indicate to pro‐
37 grams they are running in a container. This file is located at
38 /run/.containerenv.
39 When running from a user defined network namespace, the
42 /etc/netns/NSNAME/resolv.conf will be used if it exists, otherwise
43 /etc/resolv.conf will be used.
44
47 --add-host=host:ip
48 Add a custom host-to-IP mapping (host:ip)
51 Add a line to /etc/hosts. The format is hostname:ip. The --add-host
54 option can be set multiple times.
55 --annotation=key=value
58 Add an annotation to the container. The format is key=value. The
61 --annotation option can be set multiple times.
62 --attach, -a=stdio
65 Attach to STDIN, STDOUT or STDERR.
68 In foreground mode (the default when -d is not specified), podman run
71 can start the process in the container and attach the console to the
72 process's standard input, output, and standard error. It can even pre‐
73 tend to be a TTY (this is what most commandline executables expect) and
74 pass along signals. The -a option can be set for each of stdin, stdout,
75 and stderr.
76 --authfile[=path]
79 Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
82 ers/auth.json (Not available for remote commands)
83 Note: You can also override the default path of the authentication file
86 by setting the REGISTRY_AUTH_FILE environment variable. export REG‐
87 ISTRY_AUTH_FILE=path
88 --blkio-weight=weight
91 Block IO weight (relative weight) accepts a weight value between 10 and
94 1000.
95 --blkio-weight-device=DEVICE_NAME:WEIGHT
98 Block IO weight (relative device weight, format: DEVICE_NAME:WEIGHT).
101 --cap-add=capability
104 Add Linux capabilities
107 --cap-drop=capability
110 Drop Linux capabilities
113 --cgroupns=mode
116 Set the cgroup namespace mode for the container, by default host is
119 used.
120 host: use the host's cgroup namespace inside the container.
121 container:: join the namespace of the specified container.
122 private: create a new cgroup namespace.
123 ns:: join the namespace at the specified path.
124 --cgroups=mode
127 Determines whether the container will create CGroups. Valid values are
130 enabled and disabled, which the default being enabled. The disabled
131 option will force the container to not create CGroups, and thus con‐
132 flicts with CGroup options (--cgroupns and --cgroup-parent).
133 --cgroup-parent=cgroup
136 Path to cgroups under which the cgroup for the container will be cre‐
139 ated. If the path is not absolute, the path is considered to be rela‐
140 tive to the cgroups path of the init process. Cgroups will be created
141 if they do not already exist.
142 --cidfile=file
145 Write the container ID to the file
148 --conmon-pidfile=file
151 Write the pid of the conmon process to a file. conmon runs in a sepa‐
154 rate process than Podman, so this is necessary when using systemd to
155 restart Podman containers.
156 --cpu-period=limit
159 Limit the CPU CFS (Completely Fair Scheduler) period
162 Limit the container's CPU usage. This flag tell the kernel to restrict
165 the container's CPU usage to the period you specify.
166 --cpu-quota=limit
169 Limit the CPU CFS (Completely Fair Scheduler) quota
172 Limit the container's CPU usage. By default, containers run with the
175 full CPU resource. This flag tell the kernel to restrict the con‐
176 tainer's CPU usage to the quota you specify.
177 --cpu-rt-period=microseconds
180 Limit the CPU real-time period in microseconds
183 Limit the container's Real Time CPU usage. This flag tell the kernel to
186 restrict the container's Real Time CPU usage to the period you specify.
187 --cpu-rt-runtime=microseconds
190 Limit the CPU real-time runtime in microseconds
193 Limit the containers Real Time CPU usage. This flag tells the kernel to
196 limit the amount of time in a given CPU period Real Time tasks may con‐
197 sume. Ex: Period of 1,000,000us and Runtime of 950,000us means that
198 this container could consume 95% of available CPU and leave the remain‐
199 ing 5% to normal priority tasks.
200 The sum of all runtimes across containers cannot exceed the amount
203 allotted to the parent cgroup.
204 --cpu-shares=shares
207 CPU shares (relative weight)
210 By default, all containers get the same proportion of CPU cycles. This
213 proportion can be modified by changing the container's CPU share
214 weighting relative to the weighting of all other running containers.
215 To modify the proportion from the default of 1024, use the --cpu-shares
218 flag to set the weighting to 2 or higher.
219 The proportion will only apply when CPU-intensive processes are run‐
222 ning. When tasks in one container are idle, other containers can use
223 the left-over CPU time. The actual amount of CPU time will vary depend‐
224 ing on the number of containers running on the system.
225 For example, consider three containers, one has a cpu-share of 1024 and
228 two others have a cpu-share setting of 512. When processes in all three
229 containers attempt to use 100% of CPU, the first container would
230 receive 50% of the total CPU time. If you add a fourth container with a
231 cpu-share of 1024, the first container only gets 33% of the CPU. The
232 remaining containers receive 16.5%, 16.5% and 33% of the CPU.
233 On a multi-core system, the shares of CPU time are distributed over all
236 CPU cores. Even if a container is limited to less than 100% of CPU
237 time, it can use 100% of each individual CPU core.
238 For example, consider a system with more than three cores. If you start
241 one container {C0} with -c=512 running one process, and another con‐
242 tainer {C1} with -c=1024 running two processes, this can result in the
243 following division of CPU shares:
244 PID container CPU CPU share 100 {C0} 0 100% of
247 CPU0 101 {C1} 1 100% of CPU1 102
248 {C1} 2 100% of CPU2
249 --cpus=number
252 Number of CPUs. The default is 0.0 which means no limit.
255 --cpuset-cpus=number
258 CPUs in which to allow execution (0-3, 0,1)
261 --cpuset-mems=nodes
264 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
267 tive on NUMA systems.
268 If you have four memory nodes on your system (0-3), use
271 --cpuset-mems=0,1 then processes in your container will only use memory
272 from the first two memory nodes.
273 --detach, -d=true|false
276 Detached mode: run the container in the background and print the new
279 container ID. The default is false.
280 At any time you can run podman ps in the other shell to view a list of
283 the running containers. You can reattach to a detached container with
284 podman attach.
285 When attached in the tty mode, you can detach from the container (and
288 leave it running) using a configurable key sequence. The default
289 sequence is ctrl-p,ctrl-q. Configure the keys sequence using the
290 --detach-keys option, or specifying it in the libpod.conf file: see
291 libpod.conf(5) for more information.
292 --detach-keys=sequence
295 Override the key sequence for detaching a container. Format is a single
298 character [a-Z] or a comma separated sequence of ctrl-<value>, where
299 <value> is one of: a-z, @, ^, [, \\, ], ^ or _.
300 --device=device
303 Add a host device to the container. The format is
306 <device-on-host>[:<device-on-container>][:<permissions>] (e.g.
307 --device=/dev/sdc:/dev/xvdc:rwm)
308 --device-read-bps=path
311 Limit read rate (bytes per second) from a device (e.g.
314 --device-read-bps=/dev/sda:1mb)
315 --device-read-iops=path
318 Limit read rate (IO per second) from a device (e.g.
321 --device-read-iops=/dev/sda:1000)
322 --device-write-bps=path
325 Limit write rate (bytes per second) to a device (e.g.
328 --device-write-bps=/dev/sda:1mb)
329 --device-write-iops=path
332 Limit write rate (IO per second) to a device (e.g.
335 --device-write-iops=/dev/sda:1000)
336 --dns=dns
339 Set custom DNS servers. Invalid if using --dns with --network that is
342 set to 'none' or 'container:'.
343 This option can be used to override the DNS configuration passed to the
346 container. Typically this is necessary when the host DNS configuration
347 is invalid for the container (e.g., 127.0.0.1). When this is the case
348 the --dns flags is necessary for every run.
349 The special value none can be specified to disable creation of
352 /etc/resolv.conf in the container by Podman. The /etc/resolv.conf file
353 in the image will be used without changes.
354 --dns-option=option
357 Set custom DNS options. Invalid if using --dns-option with --network
360 that is set to 'none' or 'container:'.
361 --dns-search=domain
364 Set custom DNS search domains. Invalid if using --dns-search and --net‐
367 work that is set to 'none' or 'container:'. (Use --dns-search=. if you
368 don't wish to set the search domain)
369 --entrypoint="command" | '["command", "arg1", ...]'
372 Overwrite the default ENTRYPOINT of the image
375 This option allows you to overwrite the default entrypoint of the
378 image.
379 The ENTRYPOINT of an image is similar to a COMMAND because it specifies
382 what executable to run when the container starts, but it is (purposely)
383 more difficult to override. The ENTRYPOINT gives a container its
384 default nature or behavior, so that when you set an ENTRYPOINT you can
385 run the container as if it were that binary, complete with default
386 options, and you can pass in more options via the COMMAND. But, some‐
387 times an operator may want to run something else inside the container,
388 so you can override the default ENTRYPOINT at runtime by using a
389 --entrypoint and a string to specify the new ENTRYPOINT.
390 You need to specify multi option commands in the form of a json string.
393 --env, -e=env
396 Set environment variables
399 This option allows arbitrary environment variables that are available
402 for the process to be launched inside of the container. If an environ‐
403 ment variable is specified without a value, Podman will check the host
404 environment for a value and set the variable only if it is set on the
405 host. If an environment variable ending in * is specified, Podman will
406 search the host environment for variables starting with the prefix and
407 will add those variables to the container. If an environment variable
408 with a trailing ***** is specified, then a value must be supplied.
409 See Environment ⟨#environment⟩ note below for precedence and examples.
412 --env-host=true|false
415 Use host environment inside of the container. See Environment note
418 below for precedence.
419 --env-file=file
422 Read in a line delimited file of environment variables. See Environment
425 note below for precedence.
426 --expose=port
429 Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up
432 port redirection on the host system.
433 --gidmap=container_gid:host_gid:amount
436 Run the container in a new user namespace using the supplied mapping.
439 This option conflicts with the --userns and --subgidname flags. This
440 option can be passed several times to map different ranges. If calling
441 Podman run as an unprivileged user, the user needs to have the right to
442 use the mapping. See subuid(5). The example maps gids 0-1999 in the
443 container to the gids 30000-31999 on the host. --gidmap=0:30000:2000
444 --group-add=group
447 Add additional groups to run as
450 --health-cmd="command" | '["command", "arg1", ...]'
453 Set or alter a healthcheck command for a container. The command is a
456 command to be executed inside your container that determines your con‐
457 tainer health. The command is required for other healthcheck options
458 to be applied. A value of none disables existing healthchecks.
459 Multiple options can be passed in the form of a JSON array; otherwise,
462 the command will be interpreted as an argument to /bin/sh -c.
463 --health-interval=interval
466 Set an interval for the healthchecks (a value of disable results in no
469 automatic timer setup) (default "30s")
470 --health-retries=retries
473 The number of retries allowed before a healthcheck is considered to be
476 unhealthy. The default value is 3.
477 --health-start-period=period
480 The initialization time needed for a container to bootstrap. The value
483 can be expressed in time format like 2m3s. The default value is 0s
484 --health-timeout=timeout
487 The maximum time allowed to complete the healthcheck before an interval
490 is considered failed. Like start-period, the value can be expressed in
491 a time format such as 1m22s. The default value is 30s.
492 --help
495 Print usage statement
498 --hostname=name
501 Container host name
504 Sets the container host name that is available inside the container.
507 --http-proxy=true|false
510 By default proxy environment variables are passed into the container if
513 set for the Podman process. This can be disabled by setting the
514 --http-proxy option to false. The environment variables passed in
515 include http_proxy, https_proxy, ftp_proxy, no_proxy, and also the
516 upper case versions of those. This option is only needed when the host
517 system must use a proxy but the container should not use any proxy.
518 Proxy environment variables specified for the container in any other
519 way will override the values that would have been passed thru from the
520 host. (Other ways to specify the proxy for the container include pass‐
521 ing the values with the --env flag, or hard coding the proxy environ‐
522 ment at container build time.)
523 For example, to disable passing these environment variables from host
526 to container:
527 --http-proxy=false
530 Defaults to true
533 --image-volume, builtin-volume=bind|tmpfs|ignore
536 Tells Podman how to handle the builtin image volumes.
539 The options are: bind, tmpfs, or ignore (default bind)
542 · bind: A directory is created inside the container state direc‐
545 tory and bind mounted into the container for the volumes.
546 · tmpfs: The volume is mounted onto the container as a tmpfs,
548 which allows the users to create content that disappears when
549 the container is stopped.
550 · ignore: All volumes are just ignored and no action is taken.
552 --init
556 Run an init inside the container that forwards signals and reaps pro‐
559 cesses.
560 --init-path=path
563 Path to the container-init binary.
566 --interactive, -i=true|false
569 When set to true, keep stdin open even if not attached. The default is
572 false.
573 --ip6=ip
576 Not implemented
579 --ip=ip
582 Specify a static IP address for the container, for example
585 '10.88.64.128'. Can only be used if no additional CNI networks to join
586 were specified via '--network=', and if the container is not joining
587 another container's network namespace via '--network=container:'. The
588 address must be within the default CNI network's pool (default
589 10.88.0.0/16).
590 --ipc=ipc
593 Default is to create a private IPC namespace (POSIX SysV IPC) for the
596 container
597 · container:<name|id>: reuses another container shared memory,
600 semaphores and message queues
601 · host: use the host shared memory,semaphores and message queues
603 inside the container. Note: the host mode gives the container
604 full access to local shared memory and is therefore considered
605 insecure.
606 · ns:<path> path to an IPC namespace to join.
608 --kernel-memory=number[unit]
612 Kernel memory limit (format: <number>[<unit>], where unit = b (bytes),
615 k (kilobytes), m (megabytes), or g (gigabytes))
616 Constrains the kernel memory available to a container. If a limit of 0
619 is specified (not using --kernel-memory), the container's kernel memory
620 is not limited. If you specify a limit, it may be rounded up to a mul‐
621 tiple of the operating system's page size and the value can be very
622 large, millions of trillions.
623 --label, -l=label
626 Add metadata to a container (e.g., --label com.example.key=value)
629 --label-file=file
632 Read in a line delimited file of labels
635 --link-local-ip=ip
638 Not implemented
641 --log-driver="k8s-file"
644 Logging driver for the container. Currently available options are
647 k8s-file and journald, with json-file aliased to k8s-file for scripting
648 compatibility.
649 --log-opt=path
652 Logging driver specific options. Used to set the path to the container
655 log file. For example:
656 --log-opt path=/var/log/container/mycontainer.json
659 --mac-address=address
662 Container MAC address (e.g. 92:d0:c6:0a:29:33)
665 Remember that the MAC address in an Ethernet network must be unique.
668 The IPv6 link-local address will be based on the device's MAC address
669 according to RFC4862.
670 Not currently supported
673 --memory, -m=limit
676 Memory limit (format: [], where unit = b (bytes), k (kilobytes), m
679 (megabytes), or g (gigabytes))
680 Allows you to constrain the memory available to a container. If the
683 host supports swap memory, then the -m memory setting can be larger
684 than physical RAM. If a limit of 0 is specified (not using -m), the
685 container's memory is not limited. The actual limit may be rounded up
686 to a multiple of the operating system's page size (the value would be
687 very large, that's millions of trillions).
688 --memory-reservation=limit
691 Memory soft limit (format: [], where unit = b (bytes), k (kilobytes), m
694 (megabytes), or g (gigabytes))
695 After setting memory reservation, when the system detects memory con‐
698 tention or low memory, containers are forced to restrict their consump‐
699 tion to their reservation. So you should always set the value below
700 --memory, otherwise the hard limit will take precedence. By default,
701 memory reservation will be the same as memory limit.
702 --memory-swap=limit
705 A limit value equal to memory plus swap. Must be used with the -m
708 (--memory) flag. The swap LIMIT should always be larger than -m (--mem‐
709 ory) value. By default, the swap LIMIT will be set to double the value
710 of --memory.
711 The format of LIMIT is <number>[<unit>]. Unit can be b (bytes), k
714 (kilobytes), m (megabytes), or g (gigabytes). If you don't specify a
715 unit, b is used. Set LIMIT to -1 to enable unlimited swap.
716 --memory-swappiness=number
719 Tune a container's memory swappiness behavior. Accepts an integer
722 between 0 and 100.
723 --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
726 Attach a filesystem mount to the container
729 Current supported mount TYPES are bind, volume, and tmpfs.
732 e.g.
735 type=bind,source=/path/on/host,destination=/path/in/container
737 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
739 type=volume,source=vol1,destination=/path/in/container,ro=true
741 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
743 Common Options:
745 · src, source: mount source spec for bind and volume. Mandatory for bind.
747 · dst, destination, target: mount destination spec.
749 · ro, read-only: true or false (default).
751 Options specific to bind:
753 · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
755 . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive.
757 . relabel: shared, private.
759 Options specific to tmpfs:
761 · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
763 · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
765 --name=name
769 Assign a name to the container
772 The operator can identify a container in three ways: - UUID long iden‐
775 tifier
776 (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”) -
777 UUID short identifier (“f78375b1c487”) - Name (“jonah”)
778 podman generates a UUID for each container, and if a name is not
781 assigned to the container with --name then it will generate a random
782 string name. The name is useful any place you need to identify a con‐
783 tainer. This works for both background and foreground containers.
784 --network, --net=node
787 Set the Network mode for the container. Invalid if using --dns,
790 --dns-option, or --dns-search with --network that is set to 'none' or
791 'container:'. - bridge: create a network stack on the default bridge -
792 none: no networking - container:<name|id>: reuse another container's
793 network stack - host: use the Podman host network stack. Note: the host
794 mode gives the container full access to local system services such as
795 D-bus and is therefore considered insecure. - <network-name>|<net‐
796 work-id>: connect to a user-defined network - ns:<path>: path to a net‐
797 work namespace to join - slirp4netns: use slirp4netns to create a user
798 network stack. This is the default for rootless containers
799 --network-alias=alias
802 Not implemented
805 --no-hosts=true|false
808 Do not create /etc/hosts for the container. By default, Podman will
811 manage /etc/hosts, adding the container's own IP address and any hosts
812 from --add-host. --no-hosts disables this, and the image's /etc/host
813 will be preserved unmodified. This option conflicts with --add-host.
814 --oom-kill-disable=true|false
817 Whether to disable OOM Killer for the container or not.
820 --oom-score-adj=num
823 Tune the host's OOM preferences for containers (accepts -1000 to 1000)
826 --pid=pid
829 Set the PID mode for the container
832 Default is to create a private PID namespace for the container
835 · container:<name|id>: join another container's PID namespace
838 · host: use the host's PID namespace for the container. Note:
840 the host mode gives the container full access to local PID and
841 is therefore considered insecure.
842 · ns: join the specified PID namespace
844 --pids-limit=limit
848 Tune the container's pids limit. Set 0 to have unlimited pids for the
851 container. (default "4096" on systems that support PIDS cgroups).
852 --pod=name
855 Run container in an existing pod. If you want Podman to make the pod
858 for you, preference the pod name with new:. To make a pod with more
859 granular options, use the podman pod create command before creating a
860 container. If a container is run with a pod, and the pod has an
861 infra-container, the infra-container will be started before the con‐
862 tainer is.
863 --privileged=true|false
866 Give extended privileges to this container. The default is false.
869 By default, Podman containers are “unprivileged” (=false) and cannot,
872 for example, modify parts of the kernel. This is because by default a
873 container is not allowed to access any devices. A “privileged” con‐
874 tainer is given access to all devices.
875 When the operator executes podman run --privileged, Podman enables
878 access to all devices on the host, turns off graphdriver mount options,
879 as well as turning off most of the security measures protecting the
880 host from the container.
881 --publish, -p=port
884 Publish a container's port, or range of ports, to the host
887 Format: ip:hostPort:containerPort | ip::containerPort | hostPort:con‐
890 tainerPort | containerPort
891 Both hostPort and containerPort can be specified as a range of ports.
894 When specifying ranges for both, the number of container ports in the
897 range must match the number of host ports in the range. (e.g., podman
898 run -p 1234-1236:1222-1224 --name thisWorks -t busybox but not podman
899 run -p 1230-1236:1230-1240 --name RangeContainerPortsBiggerThanRange‐
900 HostPorts -t busybox)
901 With ip: podman run -p 127.0.0.1:$HOSTPORT:$CONTAINERPORT --name CON‐
904 TAINER -t someimage
905 Use podman port to see the actual mapping: podman port CONTAINER $CON‐
908 TAINERPORT
909 --publish-all, -P=true|false
912 Publish all exposed ports to random ports on the host interfaces. The
915 default is false.
916 When set to true publish all exposed ports to the host interfaces. The
919 default is false. If the operator uses -P (or -p) then Podman will make
920 the exposed port accessible on the host and the ports will be available
921 to any client that can reach the host.
922 When using -P, Podman will bind any exposed port to a random port on
925 the host within an ephemeral port range defined by
926 /proc/sys/net/ipv4/ip_local_port_range. To find the mapping between
927 the host ports and the exposed ports, use podman port.
928 --pull=missing
931 Pull image before running ("always"|"missing"|"never") (default "miss‐
934 ing").
935 'missing': default value, attempt to pull the latest image from
936 the registries listed in registries.conf if a local image does not
937 exist.Raise an error if the image is not in any listed registry and is
938 not present locally.
939 'always': Pull the image from the first registry it is found in
940 as listed in registries.conf. Raise an error if not found in the reg‐
941 istries, even if the image is present locally.
942 'never': do not pull the image from the registry, use only the
943 local version. Raise an error if the image is not present locally.
944 Defaults to missing.
947 --quiet, -q
950 Suppress output information when pulling images
953 --read-only=true|false
956 Mount the container's root filesystem as read only.
959 By default a container will have its root filesystem writable allowing
962 processes to write files anywhere. By specifying the --read-only flag
963 the container will have its root filesystem mounted as read only pro‐
964 hibiting any writes.
965 --read-only-tmpfs=true|false
968 If container is running in --read-only mode, then mount a read-write
971 tmpfs on /run, /tmp, and /var/tmp. The default is true
972 --restart=policy
975 Restart policy to follow when containers exit. Restart policy will not
978 take effect if a container is stopped via the podman kill or podman
979 stop commands. Valid values are:
980 · no : Do not restart containers on exit
983 · on-failure[:max_retries] : Restart containers when they exit
985 with a non-0 exit code, retrying indefinitely or until the
986 optional max_retries count is hit
987 · always : Restart containers when they exit,
989 regardless of status, retrying indefinitely
990 Please note that restart will not restart containers after a system
994 reboot. If this functionality is required in your environment, you can
995 invoke Podman from a systemd unit file, or create an init script for
996 whichever init system is in use. To generate systemd unit files,
997 please see podman generate systemd
998 --rm=true|false
1001 Automatically remove the container when it exits. The default is false.
1004 Note that the container will not be removed when it could not be cre‐
1007 ated or started successfully. This allows the user to inspect the con‐
1008 tainer after failure.
1009 --rootfs
1012 If specified, the first argument refers to an exploded container on the
1015 file system.
1016 This is useful to run a container without requiring any image manage‐
1019 ment, the rootfs of the container is assumed to be managed externally.
1020 Note: On SELinux systems, the rootfs needs the correct label, which is
1023 by default unconfined_u:object_r:container_file_t.
1024 --security-opt=option
1027 Security Options
1030 · apparmor=unconfined : Turn off apparmor confinement for the
1033 container
1034 · apparmor=your-profile : Set the apparmor confinement profile
1036 for the container
1037 · label=user:USER : Set the label user for the container
1039 processes
1040 · label=role:ROLE : Set the label role for the container
1042 processes
1043 · label=type:TYPE : Set the label process type for the con‐
1045 tainer processes
1046 · label=level:LEVEL : Set the label level for the container
1048 processes
1049 · label=filetype:TYPE : Set the label file type for the con‐
1051 tainer files
1052 · label=disable : Turn off label separation for the con‐
1054 tainer
1055 · no-new-privileges : Disable container processes from gaining
1057 additional privileges
1058 · seccomp=unconfined : Turn off seccomp confinement for the con‐
1060 tainer
1061 · seccomp=profile.json : White listed syscalls seccomp Json
1063 file to be used as a seccomp filter
1064 Note: Labeling can be disabled for all containers by setting
1068 label=false in the libpod.conf (/etc/containers/libpod.conf) file.
1069 --shm-size=size
1072 Size of /dev/shm (format: [], where unit = b (bytes), k (kilobytes), m
1075 (megabytes), or g (gigabytes)) If you omit the unit, the system uses
1076 bytes. If you omit the size entirely, the system uses 64m. When size
1077 is 0, there is no limit on the amount of memory used for IPC by the
1078 container.
1079 --sig-proxy=true|false
1082 Proxy signals sent to the podman run command to the container process.
1085 SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is true.
1086 --stop-signal=SIGTERM
1089 Signal to stop a container. Default is SIGTERM.
1092 --stop-timeout=seconds
1095 Timeout (in seconds) to stop a container. Default is 10.
1098 --subgidname=name
1101 Run the container in a new user namespace using the map with 'name' in
1104 the /etc/subgid file. If calling Podman run as an unprivileged user,
1105 the user needs to have the right to use the mapping. See subgid(5).
1106 This flag conflicts with --userns and --gidmap.
1107 --subuidname=name
1110 Run the container in a new user namespace using the map with 'name' in
1113 the /etc/subuid file. If calling Podman run as an unprivileged user,
1114 the user needs to have the right to use the mapping. See subuid(5).
1115 This flag conflicts with --userns and --uidmap.
1116 --sysctl=SYSCTL
1119 Configure namespaced kernel parameters at runtime
1122 IPC Namespace - current sysctls allowed:
1125 · kernel.msgmax
1128 · kernel.msgmnb
1130 · kernel.msgmni
1132 · kernel.sem
1134 · kernel.shmall
1136 · kernel.shmmax
1138 · kernel.shmmni
1140 · kernel.shm_rmid_forced
1142 · Sysctls beginning with fs.mqueue.*
1144 Note: if you use the --ipc=host option these sysctls will not be
1148 allowed.
1149 Network Namespace - current sysctls allowed: - Sysctls beginning with
1152 net.*
1153 Note: if you use the --network=host option these sysctls will not be
1156 allowed.
1157 --systemd=true|false|always
1160 Run container in systemd mode. The default is true.
1163 The value always enforces the systemd mode is enforced without looking
1166 at the executable name. Otherwise, if set to true and the command you
1167 are running inside the container is systemd, /usr/sbin/init or
1168 /sbin/init.
1169 If the command you are running inside of the container is systemd Pod‐
1172 man will setup tmpfs mount points in the following directories:
1173 /run, /run/lock, /tmp, /sys/fs/cgroup/systemd, /var/lib/journal
1176 It will also set the default stop signal to SIGRTMIN+3.
1179 This allows systemd to run in a confined container without any modifi‐
1182 cations.
1183 Note: On SELinux systems, systemd attempts to write to the cgroup file
1186 system. Containers writing to the cgroup file system are denied by
1187 default. The container_manage_cgroup boolean must be enabled for this
1188 to be allowed on an SELinux separated system.
1189 setsebool -P container_manage_cgroup true
1192 --tmpfs=fs
1195 Create a tmpfs mount
1198 Mount a temporary filesystem (tmpfs) mount into a container, for exam‐
1201 ple:
1202 $ podman run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
1205 This command mounts a tmpfs at /tmp within the container. The sup‐
1208 ported mount options are the same as the Linux default mount flags. If
1209 you do not specify any options, the systems uses the following options:
1210 rw,noexec,nosuid,nodev.
1211 --tty, -t=true|false
1214 Allocate a pseudo-TTY. The default is false.
1217 When set to true Podman will allocate a pseudo-tty and attach to the
1220 standard input of the container. This can be used, for example, to run
1221 a throwaway interactive shell. The default is false.
1222 NOTE: The -t option is incompatible with a redirection of the Podman
1225 client standard input.
1226 --uidmap=container_uid:host_uid:amount
1229 Run the container in a new user namespace using the supplied mapping.
1232 This option conflicts with the --userns and --subuidname flags. This
1233 option can be passed several times to map different ranges. If calling
1234 Podman run as an unprivileged user, the user needs to have the right to
1235 use the mapping. See subuid(5). The example maps uids 0-1999 in the
1236 container to the uids 30000-31999 on the host. --uidmap=0:30000:2000
1237 --ulimit=option
1240 Ulimit options
1243 You can pass host to copy the current configuration from the host.
1246 --user, -u=user
1249 Sets the username or UID used and optionally the groupname or GID for
1252 the specified command.
1253 The followings examples are all valid: --user [user | user:group | uid
1256 | uid:gid | user:gid | uid:group ]
1257 Without this argument the command will be run as root in the container.
1260 --userns=host --userns=keep-id --userns=container:container
1263 --userns=ns:my_namespace
1264 Set the user namespace mode for the container. It defaults to the POD‐
1267 MAN_USERNS environment variable. An empty value means user namespaces
1268 are disabled.
1269 · host: run in the user namespace of the caller. This is the
1272 default if no user namespace options are set. The processes
1273 running in the container will have the same privileges on the
1274 host as any other process launched by the calling user.
1275 · keep-id: creates a user namespace where the current rootless
1277 user's UID:GID are mapped to the same values in the container.
1278 This option is ignored for containers created by the root
1279 user.
1280 · ns: run the container in the given existing user namespace.
1282 · container: join the user namespace of the specified container.
1284 This option is incompatible with --gidmap, --uidmap, --subuid and
1288 --subgid
1289 --uts=host
1292 Set the UTS mode for the container
1295 · host: use the host's UTS namespace inside the container.
1298 · ns: specify the user namespace to use.
1300 NOTE: the host mode gives the container access to changing the host's
1304 hostname and is therefore considered insecure.
1305 --volume, -v[=[HOST-DIR-OR-VOUME-NAME:CONTAINER-DIR[:OPTIONS]]]
1308 Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR, Pod‐
1311 man bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Podman
1312 container. Similarly, -v VOLUME-NAME:/CONTAINER-DIR will mount the vol‐
1313 ume in the host to the container. If no such named volume exists, Pod‐
1314 man will create one.
1315 The OPTIONS are a comma delimited list and can be:
1318 · [rw|ro]
1321 · [z|Z]
1323 · [[r]shared|[r]slave|[r]private]
1325 The /CONTAINER-DIR must be an absolute path such as /src/docs. The
1329 /HOST-DIR must be an absolute path as well. Podman bind-mounts the
1330 HOST-DIR to the path you specify. For example, if you supply the /foo
1331 value, Podman creates a bind-mount.
1332 You can specify multiple -v options to mount one or more mounts to a
1335 container.
1336 You can add :ro or :rw suffix to a volume to mount it read-only or
1339 read-write mode, respectively. By default, the volumes are mounted
1340 read-write. See examples.
1341 Labeling systems like SELinux require that proper labels are placed on
1344 volume content mounted into a container. Without a label, the security
1345 system might prevent the processes running inside the container from
1346 using the content. By default, Podman does not change the labels set by
1347 the OS.
1348 To change a label in the container context, you can add either of two
1351 suffixes :z or :Z to the volume mount. These suffixes tell Podman to
1352 relabel file objects on the shared volumes. The z option tells Podman
1353 that two containers share the volume content. As a result, Podman
1354 labels the content with a shared content label. Shared volume labels
1355 allow all containers to read/write content. The Z option tells Podman
1356 to label the content with a private unshared label. Only the current
1357 container can use a private volume.
1358 By default bind mounted volumes are private. That means any mounts done
1361 inside container will not be visible on host and vice versa. One can
1362 change this behavior by specifying a volume mount propagation property.
1363 Making a volume shared mounts done under that volume inside container
1364 will be visible on host and vice versa. Making a volume slave enables
1365 only one way mount propagation and that is mounts done on host under
1366 that volume will be visible inside container but not the other way
1367 around.
1368 To control mount propagation property of volume one can use :[r]shared,
1371 :[r]slave or :[r]private propagation flag. Propagation property can be
1372 specified only for bind mounted volumes and not for internal volumes or
1373 named volumes. For mount propagation to work source mount point (mount
1374 point where source dir is mounted on) has to have right propagation
1375 properties. For shared volumes, source mount point has to be shared.
1376 And for slave volumes, source mount has to be either shared or slave.
1377 Use df <source-dir> to figure out the source mount and then use findmnt
1380 -o TARGET,PROPAGATION <source-mount-dir> to figure out propagation
1381 properties of source mount. If findmnt utility is not available, then
1382 one can look at mount entry for source mount point in
1383 /proc/self/mountinfo. Look at optional fields and see if any propaga‐
1384 tion properties are specified. shared:X means mount is shared, mas‐
1385 ter:X means mount is slave and if nothing is there that means mount is
1386 private.
1387 To change propagation properties of a mount point use mount command.
1390 For example, if one wants to bind mount source directory /foo one can
1391 do mount --bind /foo /foo and mount --make-private --make-shared /foo.
1392 This will convert /foo into a shared mount point. Alternatively one can
1393 directly change propagation properties of source mount. Say / is source
1394 mount for /foo, then use mount --make-shared / to convert / into a
1395 shared mount.
1396 --volumes-from[=CONTAINER[:OPTIONS]]
1399 Mount volumes from the specified container(s). OPTIONS is a comma
1402 delimited list with the following available elements:
1403 · [rw|ro]
1406 · z
1408 Mounts already mounted volumes from a source container onto another
1412 container. You must supply the source's container-id or container-name.
1413 To share a volume, use the --volumes-from option when running the tar‐
1414 get container. You can share volumes even if the source container is
1415 not running.
1416 By default, Podman mounts the volumes in the same mode (read-write or
1419 read-only) as it is mounted in the source container. Optionally, you
1420 can change this by suffixing the container-id with either the ro or rw
1421 keyword.
1422 Labeling systems like SELinux require that proper labels are placed on
1425 volume content mounted into a container. Without a label, the security
1426 system might prevent the processes running inside the container from
1427 using the content. By default, Podman does not change the labels set by
1428 the OS.
1429 To change a label in the container context, you can add z to the volume
1432 mount. This suffix tells Podman to relabel file objects on the shared
1433 volumes. The z option tells Podman that two containers share the volume
1434 content. As a result, podman labels the content with a shared content
1435 label. Shared volume labels allow all containers to read/write content.
1436 If the location of the volume from the source container overlaps with
1439 data residing on a target container, then the volume hides that data on
1440 the target.
1441 --workdir, -w=dir
1444 Working directory inside the container
1447 The default working directory for running binaries within a container
1450 is the root directory (/). The image developer can set a different
1451 default with the WORKDIR instruction. The operator can override the
1452 working directory by using the -w option.
1453
1456 The exit code from podman run gives information about why the container
1457 failed to run or why it exited. When podman run exits with a non-zero
1458 code, the exit codes follow the chroot standard, see below:
1459 125 if the error is with Podman itself
1462 $ podman run --foo busybox; echo $?
1465 Error: unknown flag: --foo
1466 125
1467 126 if the contained command cannot be invoked
1471 $ podman run busybox /etc; echo $?
1474 Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error
1475 126
1476 127 if the contained command cannot be found
1480 $ podman run busybox foo; echo $?
1483 Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error
1484 127
1485 Exit code of contained command otherwise
1489 $ podman run busybox /bin/sh -c 'exit 3'
1492 3
1493
1497 Running container in read-only mode
1498 During container image development, containers often need to write to
1499 the image content. Installing packages into /usr, for example. In
1500 production, applications seldom need to write to the image. Container
1501 applications write to volumes if they need to write to file systems at
1502 all. Applications can be made more secure by running them in read-only
1503 mode using the --read-only switch. This protects the containers image
1504 from modification. Read only containers may still need to write tempo‐
1505 rary data. The best way to handle this is to mount tmpfs directories
1506 on /run and /tmp.
1507 $ podman run --read-only -i -t fedora /bin/bash
1510 $ podman run --read-only --read-only-tmpfs=false --tmpfs /run -i -t fedora /bin/bash
1514 Exposing log messages from the container to the host's log
1518 If you want messages that are logged in your container to show up in
1519 the host's syslog/journal then you should bind mount the /dev/log
1520 directory as follows.
1521 $ podman run -v /dev/log:/dev/log -i -t fedora /bin/bash
1524 From inside the container you can test this by sending a message to the
1528 log.
1529 (bash)# logger "Hello from my container"
1532 Then exit and check the journal.
1536 (bash)# exit
1539 $ journalctl -b | grep Hello
1541 This should list the message sent to logger.
1545 Attaching to one or more from STDIN, STDOUT, STDERR
1548 If you do not specify -a then Podman will attach everything (stdin,std‐
1549 out,stderr). You can specify to which of the three standard streams
1550 (stdin, stdout, stderr) you'd like to connect instead, as in:
1551 $ podman run -a stdin -a stdout -i -t fedora /bin/bash
1554
1558 Using shm_server.c available here:
1559 https://www.cs.cf.ac.uk/Dave/C/node27.html
1560 Testing --ipc=host mode:
1563 Host shows a shared memory segment with 7 pids attached, happens to be
1566 from httpd:
1567 $ sudo ipcs -m
1570 ------ Shared Memory Segments --------
1572 key shmid owner perms bytes nattch status
1573 0x01128e25 0 root 600 1000 7
1574 Now run a regular container, and it correctly does NOT see the shared
1578 memory segment from the host:
1579 $ podman run -it shm ipcs -m
1582 ------ Shared Memory Segments --------
1584 key shmid owner perms bytes nattch status
1585 Run a container with the new --ipc=host option, and it now sees the
1589 shared memory segment from the host httpd:
1590 $ podman run -it --ipc=host shm ipcs -m
1593 ------ Shared Memory Segments --------
1595 key shmid owner perms bytes nattch status
1596 0x01128e25 0 root 600 1000 7
1597 Testing --ipc=container:CONTAINERID mode:
1601 Start a container with a program to create a shared memory segment:
1604 $ podman run -it shm bash
1607 $ sudo shm/shm_server
1608 $ sudo ipcs -m
1609 ------ Shared Memory Segments --------
1611 key shmid owner perms bytes nattch status
1612 0x0000162e 0 root 666 27 1
1613 Create a 2nd container correctly shows no shared memory segment from
1617 1st container:
1618 $ podman run shm ipcs -m
1621 ------ Shared Memory Segments --------
1623 key shmid owner perms bytes nattch status
1624 Create a 3rd container using the new --ipc=container:CONTAINERID
1628 option, now it shows the shared memory segment from the first:
1629 $ podman run -it --ipc=container:ed735b2264ac shm ipcs -m
1632 $ sudo ipcs -m
1633 ------ Shared Memory Segments --------
1635 key shmid owner perms bytes nattch status
1636 0x0000162e 0 root 666 27 1
1637 Mapping Ports for External Usage
1641 The exposed port of an application can be mapped to a host port using
1642 the -p flag. For example, an httpd port 80 can be mapped to the host
1643 port 8080 using the following:
1644 $ podman run -p 8080:80 -d -i -t fedora/httpd
1647 Mounting External Volumes
1651 To mount a host directory as a container volume, specify the absolute
1652 path to the directory and the absolute path for the container directory
1653 separated by a colon. If the source is a named volume maintained by
1654 Podman, it's recommended to use it's name rather than the path to the
1655 volume. Otherwise the volume will be considered as an orphan and wiped
1656 if you execute podman volume prune:
1657 $ podman run -v /var/db:/data1 -i -t fedora bash
1660 $ podman run -v data:/data2 -i -t fedora bash
1662 Using --mount flags, To mount a host directory as a container folder,
1666 specify the absolute path to the directory or the volume name, and the
1667 absolute path within the container directory:
1668 $ podman run --mount type=bind,src=/var/db,target=/data1 busybox sh
1671 $ podman run --mount type=bind,src=volume-name,target=/data1 busybox sh
1673 When using SELinux, be aware that the host has no knowledge of con‐
1677 tainer SELinux policy. Therefore, in the above example, if SELinux pol‐
1678 icy is enforced, the /var/db directory is not writable to the con‐
1679 tainer. A "Permission Denied" message will occur and an avc: message in
1680 the host's syslog.
1681 To work around this, at time of writing this man page, the following
1684 command needs to be run in order for the proper SELinux policy type
1685 label to be attached to the host directory:
1686 $ chcon -Rt svirt_sandbox_file_t /var/db
1689 Now, writing to the /data1 volume in the container will be allowed and
1693 the changes will also be reflected on the host in /var/db.
1694 Using alternative security labeling
1697 You can override the default labeling scheme for each container by
1698 specifying the --security-opt flag. For example, you can specify the
1699 MCS/MLS level, a requirement for MLS systems. Specifying the level in
1700 the following command allows you to share the same content between con‐
1701 tainers.
1702 podman run --security-opt label=level:s0:c100,c200 -i -t fedora bash
1705 An MLS example might be:
1709 $ podman run --security-opt label=level:TopSecret -i -t rhel7 bash
1712 To disable the security labeling for this container versus running with
1716 the --permissive flag, use the following command:
1717 $ podman run --security-opt label=disable -i -t fedora bash
1720 If you want a tighter security policy on the processes within a con‐
1724 tainer, you can specify an alternate type for the container. You could
1725 run a container that is only allowed to listen on Apache ports by exe‐
1726 cuting the following command:
1727 $ podman run --security-opt label=type:svirt_apache_t -i -t centos bash
1730 Note:
1734 You would have to write policy defining a svirt_apache_t type.
1737 Setting device weight
1740 If you want to set /dev/sda device weight to 200, you can specify the
1741 device weight by --blkio-weight-device flag. Use the following command:
1742 $ podman run -it --blkio-weight-device "/dev/sda:200" ubuntu
1745 Setting Namespaced Kernel Parameters (Sysctls)
1749 The --sysctl sets namespaced kernel parameters (sysctls) in the con‐
1750 tainer. For example, to turn on IP forwarding in the containers network
1751 namespace, run this command:
1752 $ podman run --sysctl net.ipv4.ip_forward=1 someimage
1755 Note:
1759 Not all sysctls are namespaced. Podman does not support changing
1762 sysctls inside of a container that also modify the host system. As the
1763 kernel evolves we expect to see more sysctls become namespaced.
1764 See the definition of the --sysctl option above for the current list of
1767 supported sysctls.
1768 Set UID/GID mapping in a new user namespace
1771 Running a container in a new user namespace requires a mapping of the
1772 uids and gids from the host.
1773 $ podman run --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
1776 Configuring Storage Options from the command line
1780 Podman allows for the configuration of storage by changing the values
1781 in the /etc/container/storage.conf or by using global options. This
1782 shows how to setup and use fuse-overlayfs for a one time run of busybox
1783 using global options.
1784 podman --log-level=debug --storage-driver overlay --storage-opt "over‐
1787 lay.mount_program=/usr/bin/fuse-overlayfs" run busybox /bin/sh
1788 Rootless Containers
1791 Podman runs as a non root user on most systems. This feature requires
1792 that a new enough version of shadow-utils be installed. The
1793 shadow-utils package must include the newuidmap and newgidmap executa‐
1794 bles.
1795 Note: RHEL7 and Centos 7 will not have this feature until RHEL7.7 is
1798 released.
1799 In order for users to run rootless, there must be an entry for their
1802 username in /etc/subuid and /etc/subgid which lists the UIDs for their
1803 user namespace.
1804 Rootless Podman works better if the fuse-overlayfs and slirp4netns
1807 packages are installed. The fuse-overlay package provides a userspace
1808 overlay storage driver, otherwise users need to use the vfs storage
1809 driver, which is diskspace expensive and does not perform well.
1810 slirp4netns is required for VPN, without it containers need to be run
1811 with the --net=host flag.
1812
1815 Environment variables within containers can be set using multiple dif‐
1816 ferent options: This section describes the precedence.
1817 Precedence Order:
1820 **--env-host** : Host environment of the process executing Podman is added.
1823 Container image : Any environment variables specified in the container image.
1825 **--env-file** : Any environment variables specified via env-files. If multiple files specified, then they override each other in order of entry.
1827 **--env** : Any environment variables specified will override previous settings.
1829 Run containers and set the environment ending with a * and a *****
1833 $ export ENV1=a
1836 $ $ podman run --env ENV* alpine printenv ENV1
1837 a
1838 $ podman run --env ENV*****=b alpine printenv ENV*****
1840 b
1841
1845 /etc/subuid /etc/subgid
1846
1849 subgid(5), subuid(5), libpod.conf(5), systemd.unit(5), setsebool(8),
1850 slirp4netns(1), fuse-overlayfs(1)
1851
1854 September 2018, updated by Kunal Kushwaha
1855 October 2017, converted from Docker documentation to Podman by Dan
1858 Walsh for Podman dwalsh@redhat.com ⟨mailto:dwalsh@redhat.com⟩
1859 November 2015, updated by Sally O'Malley somalley@redhat.com
1862 ⟨mailto:somalley@redhat.com⟩
1863 July 2014, updated by Sven Dowideit SvenDowideit@home.org.au
1866 ⟨mailto:SvenDowideit@home.org.au⟩
1867 June 2014, updated by Sven Dowideit SvenDowideit@home.org.au
1870 ⟨mailto:SvenDowideit@home.org.au⟩
1871 April 2014, Originally compiled by William Henry whenry@redhat.com
1874 ⟨mailto:whenry@redhat.com⟩ based on docker.com source material and
1875 internal work.
1876 podman-run(1)()