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
14 Creates a writable container layer over the specified image and
15 prepares it for running the specified command. The container ID is then
16 printed to STDOUT. This is similar to podman run -d except the
17 container is never started. You can then use the podman start container
18 command to start the container at any point.
19 The initial status of the container created with podman create is
22 'created'.
23
26 --add-host=[]
27 Add a custom host-to-IP mapping (host:ip)
30 Add a line to /etc/hosts. The format is hostname:ip. The --add-host
33 option can be set multiple times.
34 --annotation=[]
37 Add an annotation to the container. The format is key=value. The
40 --annotation option can be set multiple times.
41 --attach, -a=[]
44 Attach to STDIN, STDOUT or STDERR.
47 In foreground mode (the default when -d is not specified), podman run
50 can start the process in the container and attach the console to the
51 process's standard input, output, and standard error. It can even
52 pretend to be a TTY (this is what most commandline executables expect)
53 and pass along signals. The -a option can be set for each of stdin,
54 stdout, and stderr.
55 --authfile
58 Path of the authentication file. Default is
61 ${XDG_\RUNTIME_DIR}/containers/auth.json
62 Note: You can also override the default path of the authentication file
65 by setting the REGISTRY_AUTH_FILE environment variable. export
66 REGISTRY_AUTH_FILE=path (Not available for remote commands)
67 --blkio-weight=0
70 Block IO weight (relative weight) accepts a weight value between 10 and
73 1000.
74 --blkio-weight-device=[]
77 Block IO weight (relative device weight, format: DEVICE_NAME:WEIGHT).
80 --cap-add=[]
83 Add Linux capabilities
86 --cap-drop=[]
89 Drop Linux capabilities
92 --cgroup-parent=""
95 Path to cgroups under which the cgroup for the container will be
98 created. If the path is not absolute, the path is considered to be
99 relative to the cgroups path of the init process. Cgroups will be
100 created if they do not already exist.
101 --cidfile=""
104 Write the container ID to the file
107 --conmon-pidfile=""
110 Write the pid of the conmon process to a file. conmon runs in a
113 separate process than Podman, so this is necessary when using systemd
114 to restart Podman containers.
115 --cpu-count=0
118 Limit the number of CPUs available for execution by the container.
121 On Windows Server containers, this is approximated as a percentage of
124 total CPU usage.
125 On Windows Server containers, the processor resource controls are
128 mutually exclusive, the order of precedence is CPUCount first, then
129 CPUShares, and CPUPercent last.
130 --cpu-period=0
133 Limit the CPU CFS (Completely Fair Scheduler) period
136 Limit the container's CPU usage. This flag tell the kernel to restrict
139 the container's CPU usage to the period you specify.
140 --cpu-quota=0
143 Limit the CPU CFS (Completely Fair Scheduler) quota
146 Limit the container's CPU usage. By default, containers run with the
149 full CPU resource. This flag tell the kernel to restrict the
150 container's CPU usage to the quota you specify.
151 --cpu-rt-period=0
154 Limit the CPU real-time period in microseconds
157 Limit the container's Real Time CPU usage. This flag tell the kernel to
160 restrict the container's Real Time CPU usage to the period you specify.
161 --cpu-rt-runtime=0
164 Limit the CPU real-time runtime in microseconds
167 Limit the containers Real Time CPU usage. This flag tells the kernel to
170 limit the amount of time in a given CPU period Real Time tasks may
171 consume. Ex: Period of 1,000,000us and Runtime of 950,000us means that
172 this container could consume 95% of available CPU and leave the
173 remaining 5% to normal priority tasks.
174 The sum of all runtimes across containers cannot exceed the amount
177 allotted to the parent cgroup.
178 --cpu-shares=0
181 CPU shares (relative weight)
184 By default, all containers get the same proportion of CPU cycles. This
187 proportion can be modified by changing the container's CPU share
188 weighting relative to the weighting of all other running containers.
189 To modify the proportion from the default of 1024, use the --cpu-shares
192 flag to set the weighting to 2 or higher.
193 The proportion will only apply when CPU-intensive processes are
196 running. When tasks in one container are idle, other containers can
197 use the left-over CPU time. The actual amount of CPU time will vary
198 depending on the number of containers running on the system.
199 For example, consider three containers, one has a cpu-share of 1024 and
202 two others have a cpu-share setting of 512. When processes in all three
203 containers attempt to use 100% of CPU, the first container would
204 receive 50% of the total CPU time. If you add a fourth container with a
205 cpu-share of 1024, the first container only gets 33% of the CPU. The
206 remaining containers receive 16.5%, 16.5% and 33% of the CPU.
207 On a multi-core system, the shares of CPU time are distributed over all
210 CPU cores. Even if a container is limited to less than 100% of CPU
211 time, it can use 100% of each individual CPU core.
212 For example, consider a system with more than three cores. If you start
215 one container {C0} with -c=512 running one process, and another
216 container {C1} with -c=1024 running two processes, this can result in
217 the following division of CPU shares:
218 PID container CPU CPU share 100 {C0} 0 100% of CPU0 101
221 {C1} 1 100% of CPU1 102 {C1} 2 100% of CPU2
222 --cpus=0.0
225 Number of CPUs. The default is 0.0 which means no limit.
228 --cpuset-cpus=""
231 CPUs in which to allow execution (0-3, 0,1)
234 --cpuset-mems=""
237 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only
240 effective on NUMA systems.
241 If you have four memory nodes on your system (0-3), use
244 --cpuset-mems=0,1 then processes in your container will only use memory
245 from the first two memory nodes.
246 --detach, -d=true|false
249 Detached mode: run the container in the background and print the new
252 container ID. The default is false.
253 At any time you can run podman ps in the other shell to view a list of
256 the running containers. You can reattach to a detached container with
257 podman attach.
258 When attached in the tty mode, you can detach from the container (and
261 leave it running) using a configurable key sequence. The default
262 sequence is ctrl-p,ctrl-q. You configure the key sequence using the
263 --detach-keys option or a configuration file. See config-json(5) for
264 documentation on using a configuration file.
265 --detach-keys=""
268 Override the key sequence for detaching a container. Format is a single
271 character [a-Z] or ctrl-<value> where <value> is one of: a-z, @, ^, [,
272 \\, ], ^ or _.
273 --device=[]
276 Add a host device to the container. The format is
279 <device-on-host>[:<device-on-container>][:<permissions>] (e.g.
280 --device=/dev/sdc:/dev/xvdc:rwm)
281 --device-read-bps=[]
284 Limit read rate (bytes per second) from a device (e.g.
287 --device-read-bps=/dev/sda:1mb)
288 --device-read-iops=[]
291 Limit read rate (IO per second) from a device (e.g.
294 --device-read-iops=/dev/sda:1000)
295 --device-write-bps=[]
298 Limit write rate (bytes per second) to a device (e.g.
301 --device-write-bps=/dev/sda:1mb)
302 --device-write-iops=[]
305 Limit write rate (IO per second) to a device (e.g.
308 --device-write-iops=/dev/sda:1000)
309 --dns=[]
312 Set custom DNS servers
315 This option can be used to override the DNS configuration passed to the
318 container. Typically this is necessary when the host DNS configuration
319 is invalid for the container (e.g., 127.0.0.1). When this is the case
320 the --dns flags is necessary for every run.
321 The special value none can be specified to disable creation of
324 /etc/resolv.conf in the container by Podman. The /etc/resolv.conf file
325 in the image will be used without changes.
326 --dns-option=[]
329 Set custom DNS options
332 --dns-search=[]
335 Set custom DNS search domains (Use --dns-search=. if you don't wish to
338 set the search domain)
339 --entrypoint "command" | '["command", "arg1", ...]'
342 Overwrite the default ENTRYPOINT of the image
345 This option allows you to overwrite the default entrypoint of the
348 image. The ENTRYPOINT of an image is similar to a COMMAND because it
349 specifies what executable to run when the container starts, but it is
350 (purposely) more difficult to override. The ENTRYPOINT gives a
351 container its default nature or behavior, so that when you set an
352 ENTRYPOINT you can run the container as if it were that binary,
353 complete with default options, and you can pass in more options via the
354 COMMAND. But, sometimes an operator may want to run something else
355 inside the container, so you can override the default ENTRYPOINT at
356 runtime by using a --entrypoint and a string to specify the new
357 ENTRYPOINT.
358 You need to specify multi option commands in the form of a json string.
361 --env, -e=[]
364 Set environment variables
367 This option allows you to specify arbitrary environment variables that
370 are available for the process that will be launched inside of the
371 container.
372 --env-file=[]
375 Read in a line delimited file of environment variables
378 --expose=[]
381 Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up
384 port redirection on the host system.
385 --gidmap=map
388 GID map for the user namespace. Using this flag will run the container
391 with user namespace enabled. It conflicts with the --userns and
392 --subgidname flags.
393 The following example maps uids 0-2000 in the container to the uids
396 30000-31999 on the host and gids 0-2000 in the container to the gids
397 30000-31999 on the host.
398 --group-add=[]
401 Add additional groups to run as
404 --healthcheck=""
407 Set or alter a healthcheck command for a container. The command is a
410 command to be executed inside your container that determines your
411 container health. The command is required for other healthcheck
412 options to be applied. A value of none disables existing healthchecks.
413 --healthcheck-interval=""
416 Set an interval for the healthchecks (a value of disable results in no
419 automatic timer setup) (default "30s")
420 --healthcheck-retries=
423 The number of retries allowed before a healthcheck is considered to be
426 unhealthy. The default value is 3.
427 --healthcheck-start-period=""
430 The initialization time needed for a container to bootstrap. The value
433 can be expressed in time format like 2m3s. The default value is 0s
434 --healthcheck-timeout=""
437 The maximum time allowed to complete the healthcheck before an interval
440 is considered failed. Like start-period, the value can be expressed in
441 a time format such as 1m22s. The default value is 30s.
442 --hostname=""
445 Container host name
448 Sets the container host name that is available inside the container.
451 --help
454 Print usage statement
457 --http-proxy=true|false
460 By default proxy environment variables are passed into the container if
463 set for the podman process. This can be disabled by setting the
464 --http-proxy option to false. The environment variables passed in
465 include http_proxy, https_proxy, ftp_proxy, no_proxy, and also the
466 upper case versions of those. This option is only needed when the host
467 system must use a proxy but the container should not use any proxy.
468 Proxy environment variables specified for the container in any other
469 way will override the values that would have been passed thru from the
470 host. (Other ways to specify the proxy for the container include
471 passing the values with the --env flag, or hardcoding the proxy
472 environment at container build time.)
473 For example, to disable passing these environment variables from host
476 to container:
477 --http-proxy=false
480 Defaults to true
483 --image-volume, builtin-volume=bind|tmpfs|ignore
486 Tells podman how to handle the builtin image volumes. The options are:
489 'bind', 'tmpfs', or 'ignore' (default 'bind'). bind: A directory is
490 created inside the container state directory and bind mounted into the
491 container for the volumes. tmpfs: The volume is mounted onto the
492 container as a tmpfs, which allows the users to create content that
493 disappears when the container is stopped. ignore: All volumes are just
494 ignored and no action is taken.
495 --init
498 Run an init inside the container that forwards signals and reaps
501 processes.
502 --init-path=""
505 Path to the container-init binary.
508 --interactive, -i=true|false
511 Keep STDIN open even if not attached. The default is false.
514 --ip6=""
517 Not implemented
520 --ip=""
523 Specify a static IP address for the container, for example
526 '10.88.64.128'. Can only be used if no additional CNI networks to join
527 were specified via '--network=<network-name>', and if the container is
528 not joining another container's network namespace via
529 '--network=container:<name|id>'. The address must be within the
530 default CNI network's pool (default 10.88.0.0/16).
531 --ipc=""
534 Default is to create a private IPC namespace (POSIX SysV IPC) for the
537 container
538 'container:<name|id>': reuses another container shared
539 memory, semaphores and message queues
540 'host': use the host shared memory,semaphores and
541 message queues inside the container. Note: the host mode gives the
542 container full access to local shared memory and is therefore
543 considered insecure.
544 'ns:<path>' path to an IPC namespace to join.
545 --kernel-memory=""
548 Kernel memory limit (format: <number>[<unit>], where unit = b, k, m or
551 g)
552 Constrains the kernel memory available to a container. If a limit of 0
555 is specified (not using --kernel-memory), the container's kernel memory
556 is not limited. If you specify a limit, it may be rounded up to a
557 multiple of the operating system's page size and the value can be very
558 large, millions of trillions.
559 --label, -l=[]
562 Add metadata to a container (e.g., --label com.example.key=value)
565 --label-file=[]
568 Read in a line delimited file of labels
571 --link-local-ip=[]
574 Not implemented
577 --log-driver="k8s-file"
580 Logging driver for the container. Currently not supported. This flag
583 is a NOOP provided soley for scripting compatibility.
584 --log-opt=[]
587 Logging driver specific options. Used to set the path to the container
590 log file. For example:
591 --log-opt path=/var/log/container/mycontainer.json
594 --mac-address=""
597 Container MAC address (e.g. 92:d0:c6:0a:29:33)
600 Remember that the MAC address in an Ethernet network must be unique.
603 The IPv6 link-local address will be based on the device's MAC address
604 according to RFC4862.
605 Not currently supported
608 --memory, -m=""
611 Memory limit (format: <number>[<unit>], where unit = b, k, m or g)
614 Allows you to constrain the memory available to a container. If the
617 host supports swap memory, then the -m memory setting can be larger
618 than physical RAM. If a limit of 0 is specified (not using -m), the
619 container's memory is not limited. The actual limit may be rounded up
620 to a multiple of the operating system's page size (the value would be
621 very large, that's millions of trillions).
622 --memory-reservation=""
625 Memory soft limit (format: <number>[<unit>], where unit = b, k, m or g)
628 After setting memory reservation, when the system detects memory
631 contention or low memory, containers are forced to restrict their
632 consumption to their reservation. So you should always set the value
633 below --memory, otherwise the hard limit will take precedence. By
634 default, memory reservation will be the same as memory limit.
635 --memory-swap="LIMIT"
638 A limit value equal to memory plus swap. Must be used with the -m
641 (--memory) flag. The swap LIMIT should always be larger than -m
642 (--memory) value. By default, the swap LIMIT will be set to double the
643 value of --memory.
644 The format of LIMIT is <number>[<unit>]. Unit can be b (bytes), k
647 (kilobytes), m (megabytes), or g (gigabytes). If you don't specify a
648 unit, b is used. Set LIMIT to -1 to enable unlimited swap.
649 --memory-swappiness=""
652 Tune a container's memory swappiness behavior. Accepts an integer
655 between 0 and 100.
656 --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
659 Attach a filesystem mount to the container
662 Current supported mount TYPES are bind, and tmpfs.
665 e.g.
668 type=bind,source=/path/on/host,destination=/path/in/container
670 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
672 Common Options:
674 · src, source: mount source spec for bind and volume. Mandatory for bind.
676 · dst, destination, target: mount destination spec.
678 · ro, read-only: true or false (default).
680 Options specific to bind:
682 · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
684 Options specific to tmpfs:
686 · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
688 · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
690 --name=""
694 Assign a name to the container
697 The operator can identify a container in three ways: UUID long
700 identifier
701 (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”)
702 UUID short identifier (“f78375b1c487”) Name (“jonah”)
703 podman generates a UUID for each container, and if a name is not
706 assigned to the container with --name then it will generate a random
707 string name. The name is useful any place you need to identify a
708 container. This works for both background and foreground containers.
709 --network, --net="bridge"
712 Set the Network mode for the container
715 'bridge': create a network stack on the default bridge
716 'none': no networking
717 'container:<name|id>': reuse another container's
718 network stack
719 'host': use the podman host network stack. Note: the
720 host mode gives the container full access to local system services such
721 as D-bus and is therefore considered insecure.
722 '<network-name>|<network-id>': connect to a
723 user-defined network
724 'ns:<path>': path to a network namespace to join
725 'slirp4netns': use slirp4netns to create a user network
726 stack. This is the default for rootless containers
727 --network-alias=[]
730 Not implemented
733 --no-hosts=true|false
736 Do not create /etc/hosts for the container. By default, Podman will
739 manage /etc/hosts, adding the container's own IP address and any hosts
740 from --add-host. --no-hosts disables this, and the image's /etc/host
741 will be preserved unmodified. This option conflicts with --add-host.
742 --oom-kill-disable=true|false
745 Whether to disable OOM Killer for the container or not.
748 --oom-score-adj=""
751 Tune the host's OOM preferences for containers (accepts -1000 to 1000)
754 --pid=""
757 Set the PID mode for the container Default is to create a private PID
760 namespace for the container
761 'container:<name|id>': join another container's PID
762 namespace
763 'host': use the host's PID namespace for the container.
764 Note: the host mode gives the container full access to local PID and is
765 therefore considered insecure.
766 'ns': join the specified PID namespace
767 --pids-limit=""
770 Tune the container's pids limit. Set -1 to have unlimited pids for the
773 container.
774 --pod=""
777 Run container in an existing pod. If you want podman to make the pod
780 for you, preference the pod name with new:. To make a pod with more
781 granular options, use the podman pod create command before creating a
782 container.
783 --privileged=true|false
786 Give extended privileges to this container. The default is false.
789 By default, podman containers are “unprivileged” (=false) and cannot,
792 for example, modify parts of the kernel. This is because by default a
793 container is not allowed to access any devices. A “privileged”
794 container is given access to all devices.
795 When the operator executes a privileged container, podman enables
798 access to all devices on the host, turns off graphdriver mount options,
799 as well as turning off most of the security measures protecting the
800 host from the container.
801 --publish, -p=[]
804 Publish a container's port, or range of ports, to the host
807 Format: ip:hostPort:containerPort | ip::containerPort |
810 hostPort:containerPort | containerPort Both hostPort and containerPort
811 can be specified as a range of ports. When specifying ranges for both,
812 the number of container ports in the range must match the number of
813 host ports in the range. (e.g., podman run -p 1234-1236:1222-1224
814 --name thisWorks -t busybox but not podman run -p 1230-1236:1230-1240
815 --name RangeContainerPortsBiggerThanRangeHostPorts -t busybox) With ip:
816 podman run -p 127.0.0.1:$HOSTPORT:$CONTAINERPORT --name CONTAINER -t
817 someimage Use podman port to see the actual mapping: podman port
818 CONTAINER $CONTAINERPORT
819 --publish-all, -P=true|false
822 Publish all exposed ports to random ports on the host interfaces. The
825 default is false.
826 When set to true publish all exposed ports to the host interfaces. The
829 default is false. If the operator uses -P (or -p) then podman will make
830 the exposed port accessible on the host and the ports will be available
831 to any client that can reach the host. When using -P, podman will bind
832 any exposed port to a random port on the host within an ephemeral port
833 range defined by /proc/sys/net/ipv4/ip_local_port_range. To find the
834 mapping between the host ports and the exposed ports, use podman port.
835 --quiet, -q
838 Suppress output information when pulling images
841 --read-only=true|false
844 Mount the container's root filesystem as read only.
847 By default a container will have its root filesystem writable allowing
850 processes to write files anywhere. By specifying the --read-only flag
851 the container will have its root filesystem mounted as read only
852 prohibiting any writes.
853 --read-only-tmpfs=true|false If container is running in --read-only
856 mode, then mount a read-write tmpfs on /run, /tmp, and /var/tmp. The
857 default is true
858 --restart=""
861 Restart policy to follow when containers exit. Restart policy will not
864 take effect if a container is stopped via the podman kill or podman
865 stop commands. Valid values are:
866 · no : Do not restart containers on exit
869 · on-failure[:max_retries] : Restart containers when they exit
871 with a non-0 exit code, retrying indefinitely or until the
872 optional max_retries count is hit
873 · always : Restart containers when they exit,
875 regardless of status, retrying indefinitely
876 Please note that restart will not restart containers after a system
880 reboot. If this functionality is required in your environment, you can
881 invoke Podman from a systemd unit file, or create an init script for
882 whichever init system is in use. To generate systemd unit files,
883 please see podman generate systemd
884 --rm=true|false
887 Automatically remove the container when it exits. The default is false.
890 Note that the container will not be removed when it could not be
893 created or started successfully. This allows the user to inspect the
894 container after failure.
895 --rootfs
898 If specified, the first argument refers to an exploded container on the
901 file system.
902 This is useful to run a container without requiring any image
905 management, the rootfs of the container is assumed to be managed
906 externally.
907 --security-opt=[]
910 Security Options
913 "apparmor=unconfined" : Turn off apparmor confinement for the container
916 "apparmor=your-profile" : Set the apparmor confinement profile for the
917 container
918 "label=user:USER" : Set the label user for the container
921 "label=role:ROLE" : Set the label role for the container
922 "label=type:TYPE" : Set the label type for the container
923 "label=level:LEVEL" : Set the label level for the container
924 "label=disable" : Turn off label confinement for the container
925 "no-new-privileges" : Disable container processes from gaining
928 additional privileges
929 "seccomp=unconfined" : Turn off seccomp confinement for the container
932 "seccomp=profile.json : White listed syscalls seccomp Json file to be
933 used as a seccomp filter
934 Note: Labelling can be disabled for all containers by setting
937 label=false in the libpod.conf (/etc/containers/libpod.conf) file.
938 --shm-size=""
941 Size of /dev/shm. The format is <number><unit>. number must be greater
944 than 0. Unit is optional and can be b (bytes), k (kilobytes),
945 m(megabytes), or g (gigabytes). If you omit the unit, the system uses
946 bytes. If you omit the size entirely, the system uses 64m.
947 --stop-signal=SIGTERM
950 Signal to stop a container. Default is SIGTERM.
953 --stop-timeout=10
956 Timeout (in seconds) to stop a container. Default is 10.
959 --subgidname=name
962 Name for GID map from the /etc/subgid file. Using this flag will run
965 the container with user namespace enabled. This flag conflicts with
966 --userns and --gidmap.
967 --subuidname=name
970 Name for UID map from the /etc/subuid file. Using this flag will run
973 the container with user namespace enabled. This flag conflicts with
974 --userns and --uidmap.
975 --sysctl=SYSCTL
978 Configure namespaced kernel parameters at runtime
981 IPC Namespace - current sysctls allowed:
984 kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall,
987 kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced Sysctls beginning
988 with fs.mqueue.*
989 Note: if you use the --ipc=host option these sysctls will not be
992 allowed.
993 Network Namespace - current sysctls allowed:
996 Sysctls beginning with net.*
997 Note: if you use the --network=host option these sysctls will not be
1000 allowed.
1001 --systemd=true|false
1004 Run container in systemd mode. The default is true.
1007 If the command you running inside of the container is systemd or init,
1010 podman will setup tmpfs mount points in the following directories:
1011 /run, /run/lock, /tmp, /sys/fs/cgroup/systemd, /var/lib/journal
1014 It will also set the default stop signal to SIGRTMIN+3.
1017 This allow systemd to run in a confined container without any
1020 modifications.
1021 Note: On SELinux systems, systemd attempts to write to the cgroup file
1024 system. Containers writing to the cgroup file system are denied by
1025 default. The container_manage_cgroup boolean must be enabled for this
1026 to be allowed on an SELinux separated system.
1027 setsebool -P container_manage_cgroup true
1030 --tmpfs=[] Create a tmpfs mount
1033 Mount a temporary filesystem (tmpfs) mount into a container, for
1036 example:
1037 $ podman run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
1040 This command mounts a tmpfs at /tmp within the container. The
1043 supported mount options are the same as the Linux default mount flags.
1044 If you do not specify any options, the systems uses the following
1045 options: rw,noexec,nosuid,nodev,size=65536k.
1046 --tty, -t=true|false
1049 Allocate a pseudo-TTY. The default is false.
1052 When set to true podman will allocate a pseudo-tty and attach to the
1055 standard input of the container. This can be used, for example, to run
1056 a throwaway interactive shell. The default is false.
1057 Note: The -t option is incompatible with a redirection of the podman
1060 client standard input.
1061 --uidmap=map
1064 UID map for the user namespace. Using this flag will run the container
1067 with user namespace enabled. It conflicts with the --userns and
1068 --subuidname flags.
1069 The following example maps uids 0-2000 in the container to the uids
1072 30000-31999 on the host and gids 0-2000 in the container to the gids
1073 30000-31999 on the host.
1074 --ulimit=[]
1077 Ulimit options
1080 --user, -u=""
1083 Sets the username or UID used and optionally the groupname or GID for
1086 the specified command.
1087 The followings examples are all valid: --user [user | user:group | uid
1090 | uid:gid | user:gid | uid:group ]
1091 Without this argument the command will be run as root in the container.
1094 --userns=host --userns=keep-id --userns=ns:my_namespace
1097 Set the user namespace mode for the container. It defaults to the
1100 PODMAN_USERNS environment variable. An empty value means user
1101 namespaces are disabled.
1102 · host: run in the user namespace of the caller. This is the
1105 default if no user namespace options are set. The processes
1106 running in the container will have the same privileges on the
1107 host as any other process launched by the calling user.
1108 · keep-id: creates a user namespace where the current rootless
1110 user's UID:GID are mapped to the same values in the container.
1111 This option is ignored for containers created by the root
1112 user.
1113 · ns: run the container in the given existing user namespace.
1115 This option is incompatible with --gidmap, --uidmap, --subuid and
1119 --subgid
1120 --uts=host
1123 Set the UTS mode for the container
1126 host: use the host's UTS namespace inside the container.
1127 ns: specify the user namespace to use.
1128 Note: the host mode gives the container access to changing the
1129 host's hostname and is therefore considered insecure.
1130 --volume, -v[=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]]
1133 Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR,
1136 podman bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the
1137 podman container. The OPTIONS are a comma delimited list and can be:
1138 · [rw|ro]
1141 · [z|Z]
1143 · [[r]shared|[r]slave|[r]private]
1145 The CONTAINER-DIR must be an absolute path such as /src/docs. The
1149 HOST-DIR must be an absolute path as well. podman bind-mounts the
1150 HOST-DIR to the path you specify. For example, if you supply the /foo
1151 value, podman creates a bind-mount.
1152 You can specify multiple -v options to mount one or more mounts to a
1155 container.
1156 You can add :ro or :rw suffix to a volume to mount it read-only or
1159 read-write mode, respectively. By default, the volumes are mounted
1160 read-write. See examples.
1161 Labeling systems like SELinux require that proper labels are placed on
1164 volume content mounted into a container. Without a label, the security
1165 system might prevent the processes running inside the container from
1166 using the content. By default, podman does not change the labels set by
1167 the OS.
1168 To change a label in the container context, you can add either of two
1171 suffixes :z or :Z to the volume mount. These suffixes tell podman to
1172 relabel file objects on the shared volumes. The z option tells podman
1173 that two containers share the volume content. As a result, podman
1174 labels the content with a shared content label. Shared volume labels
1175 allow all containers to read/write content. The Z option tells podman
1176 to label the content with a private unshared label. Only the current
1177 container can use a private volume.
1178 By default bind mounted volumes are private. That means any mounts done
1181 inside container will not be visible on host and vice versa. One can
1182 change this behavior by specifying a volume mount propagation property.
1183 Making a volume shared mounts done under that volume inside container
1184 will be visible on host and vice versa. Making a volume slave enables
1185 only one way mount propagation and that is mounts done on host under
1186 that volume will be visible inside container but not the other way
1187 around.
1188 To control mount propagation property of volume one can use :[r]shared,
1191 :[r]slave or :[r]private propagation flag. Propagation property can be
1192 specified only for bind mounted volumes and not for internal volumes or
1193 named volumes. For mount propagation to work source mount point (mount
1194 point where source dir is mounted on) has to have right propagation
1195 properties. For shared volumes, source mount point has to be shared.
1196 And for slave volumes, source mount has to be either shared or slave.
1197 Use df <source-dir> to figure out the source mount and then use findmnt
1200 -o TARGET,PROPAGATION <source-mount-dir> to figure out propagation
1201 properties of source mount. If findmnt utility is not available, then
1202 one can look at mount entry for source mount point in
1203 /proc/self/mountinfo. Look at optional fields and see if any
1204 propagation properties are specified. shared:X means mount is shared,
1205 master:X means mount is slave and if nothing is there that means mount
1206 is private.
1207 To change propagation properties of a mount point use mount command.
1210 For example, if one wants to bind mount source directory /foo one can
1211 do mount --bind /foo /foo and mount --make-private --make-shared /foo.
1212 This will convert /foo into a shared mount point. Alternatively one can
1213 directly change propagation properties of source mount. Say / is source
1214 mount for /foo, then use mount --make-shared / to convert / into a
1215 shared mount.
1216 --volumes-from[=CONTAINER[:OPTIONS]]
1219 Mount volumes from the specified container(s). OPTIONS is a comma
1222 delimited list with the following available elements:
1223 · [rw|ro]
1226 · z
1228 Mounts already mounted volumes from a source container onto another
1232 container. You must supply the source's container-id or container-name.
1233 To share a volume, use the --volumes-from option when running the
1234 target container. You can share volumes even if the source container is
1235 not running.
1236 By default, podman mounts the volumes in the same mode (read-write or
1239 read-only) as it is mounted in the source container. Optionally, you
1240 can change this by suffixing the container-id with either the ro or rw
1241 keyword.
1242 Labeling systems like SELinux require that proper labels are placed on
1245 volume content mounted into a container. Without a label, the security
1246 system might prevent the processes running inside the container from
1247 using the content. By default, podman does not change the labels set by
1248 the OS.
1249 To change a label in the container context, you can add z to the volume
1252 mount. This suffix tells podman to relabel file objects on the shared
1253 volumes. The z option tells podman that two containers share the volume
1254 content. As a result, podman labels the content with a shared content
1255 label. Shared volume labels allow all containers to read/write content.
1256 If the location of the volume from the source container overlaps with
1259 data residing on a target container, then the volume hides that data on
1260 the target.
1261 --workdir, -w=""
1264 Working directory inside the container
1267 The default working directory for running binaries within a container
1270 is the root directory (/). The image developer can set a different
1271 default with the WORKDIR instruction. The operator can override the
1272 working directory by using the -w option.
1273
1276 Create a container using a local image
1277 $ podman create alpine ls
1278 Create a container using a local image and annotate it
1282 $ podman create --annotation HELLO=WORLD alpine ls
1283 Create a container using a local image, allocating a pseudo-TTY, keeping
1287 stdin open and name it myctr
1288 podman create -t -i --name myctr alpine ls
1289 Set UID/GID mapping in a new user namespace
1293 Running a container in a new user namespace requires a mapping of the
1294 uids and gids from the host.
1295 $ podman create --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
1298 Rootless Containers
1302 Podman runs as a non root user on most systems. This feature requires
1303 that a new enough version of shadow-utils be installed. The
1304 shadow-utils package must include the newuidmap and newgidmap
1305 executables.
1306 Note: RHEL7 and Centos 7 will not have this feature until RHEL7.7 is
1309 released.
1310 In order for users to run rootless, there must be an entry for their
1313 username in /etc/subuid and /etc/subgid which lists the UIDs for their
1314 user namespace.
1315 Rootless podman works better if the fuse-overlayfs and slirp4netns
1318 packages are installed. The fuse-overlay package provides a userspace
1319 overlay storage driver, otherwise users need to use the vfs storage
1320 driver, which is diskspace expensive and does not perform well.
1321 slirp4netns is required for VPN, without it containers need to be run
1322 with the --net=host flag.
1323
1326 /etc/subuid /etc/subgid
1327
1330 subgid(5), subuid(5), libpod.conf(5), systemd.unit(5), setsebool(8),
1331 slirp4netns(1), fuse-overlayfs(1)
1332
1335 October 2017, converted from Docker documentation to podman by Dan
1336 Walsh for podman ⟨dwalsh@redhat.com⟩
1337 November 2014, updated by Sven Dowideit ⟨SvenDowideit@home.org.au⟩
1340 September 2014, updated by Sven Dowideit ⟨SvenDowideit@home.org.au⟩
1343 August 2014, updated by Sven Dowideit ⟨SvenDowideit@home.org.au⟩
1346 podman-create(1)