1podman-create(1)            General Commands Manual           podman-create(1)
2
3
4

NAME

6       podman-create - Create a new container
7
8

SYNOPSIS

10       podman create [options] image [command [arg ...]]
11
12

DESCRIPTION

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
20
21       The initial status of the container created with podman create is
22       'created'.
23
24

OPTIONS

26       --add-host=[]
27
28
29       Add a custom host-to-IP mapping (host:ip)
30
31
32       Add a line to /etc/hosts. The format is hostname:ip.  The --add-host
33       option can be set multiple times.
34
35
36       --annotation=[]
37
38
39       Add an annotation to the container. The format is key=value.  The
40       --annotation option can be set multiple times.
41
42
43       --attach, -a=[]
44
45
46       Attach to STDIN, STDOUT or STDERR.
47
48
49       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
56
57       --authfile
58
59
60       Path of the authentication file. Default is
61       ${XDG_\RUNTIME_DIR}/containers/auth.json
62
63
64       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
68
69       --blkio-weight=0
70
71
72       Block IO weight (relative weight) accepts a weight value between 10 and
73       1000.
74
75
76       --blkio-weight-device=[]
77
78
79       Block IO weight (relative device weight, format: DEVICE_NAME:WEIGHT).
80
81
82       --cap-add=[]
83
84
85       Add Linux capabilities
86
87
88       --cap-drop=[]
89
90
91       Drop Linux capabilities
92
93
94       --cgroup-parent=""
95
96
97       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
102
103       --cidfile=""
104
105
106       Write the container ID to the file
107
108
109       --conmon-pidfile=""
110
111
112       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
116
117       --cpu-count=0
118
119
120       Limit the number of CPUs available for execution by the container.
121
122
123       On Windows Server containers, this is approximated as a percentage of
124       total CPU usage.
125
126
127       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
131
132       --cpu-period=0
133
134
135       Limit the CPU CFS (Completely Fair Scheduler) period
136
137
138       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
141
142       --cpu-quota=0
143
144
145       Limit the CPU CFS (Completely Fair Scheduler) quota
146
147
148       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
152
153       --cpu-rt-period=0
154
155
156       Limit the CPU real-time period in microseconds
157
158
159       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
162
163       --cpu-rt-runtime=0
164
165
166       Limit the CPU real-time runtime in microseconds
167
168
169       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
175
176       The sum of all runtimes across containers cannot exceed the amount
177       allotted to the parent cgroup.
178
179
180       --cpu-shares=0
181
182
183       CPU shares (relative weight)
184
185
186       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
190
191       To modify the proportion from the default of 1024, use the --cpu-shares
192       flag to set the weighting to 2 or higher.
193
194
195       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
200
201       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
208
209       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
213
214       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
219
220       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
223
224       --cpus=0.0
225
226
227       Number of CPUs. The default is 0.0 which means no limit.
228
229
230       --cpuset-cpus=""
231
232
233       CPUs in which to allow execution (0-3, 0,1)
234
235
236       --cpuset-mems=""
237
238
239       Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only
240       effective on NUMA systems.
241
242
243       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
247
248       --detach, -d=true|false
249
250
251       Detached mode: run the container in the background and print the new
252       container ID. The default is false.
253
254
255       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
259
260       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
266
267       --detach-keys=""
268
269
270       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
274
275       --device=[]
276
277
278       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
282
283       --device-read-bps=[]
284
285
286       Limit read rate (bytes per second) from a device (e.g.
287       --device-read-bps=/dev/sda:1mb)
288
289
290       --device-read-iops=[]
291
292
293       Limit read rate (IO per second) from a device (e.g.
294       --device-read-iops=/dev/sda:1000)
295
296
297       --device-write-bps=[]
298
299
300       Limit write rate (bytes per second) to a device (e.g.
301       --device-write-bps=/dev/sda:1mb)
302
303
304       --device-write-iops=[]
305
306
307       Limit write rate (IO per second) to a device (e.g.
308       --device-write-iops=/dev/sda:1000)
309
310
311       --dns=[]
312
313
314       Set custom DNS servers
315
316
317       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
322
323       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
327
328       --dns-option=[]
329
330
331       Set custom DNS options
332
333
334       --dns-search=[]
335
336
337       Set custom DNS search domains (Use --dns-search=. if you don't wish to
338       set the search domain)
339
340
341       --entrypoint "command" | '["command", "arg1", ...]'
342
343
344       Overwrite the default ENTRYPOINT of the image
345
346
347       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
359
360       You need to specify multi option commands in the form of a json string.
361
362
363       --env, -e=[]
364
365
366       Set environment variables
367
368
369       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
373
374       --env-file=[]
375
376
377       Read in a line delimited file of environment variables
378
379
380       --expose=[]
381
382
383       Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up
384       port redirection on the host system.
385
386
387       --gidmap=map
388
389
390       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
394
395       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
399
400       --group-add=[]
401
402
403       Add additional groups to run as
404
405
406       --healthcheck=""
407
408
409       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
414
415       --healthcheck-interval=""
416
417
418       Set an interval for the healthchecks (a value of disable results in no
419       automatic timer setup) (default "30s")
420
421
422       --healthcheck-retries=
423
424
425       The number of retries allowed before a healthcheck is considered to be
426       unhealthy.  The default value is 3.
427
428
429       --healthcheck-start-period=""
430
431
432       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
435
436       --healthcheck-timeout=""
437
438
439       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
443
444       --hostname=""
445
446
447       Container host name
448
449
450       Sets the container host name that is available inside the container.
451
452
453       --help
454
455
456       Print usage statement
457
458
459       --http-proxy=true|false
460
461
462       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
474
475       For example, to disable passing these environment variables from host
476       to container:
477
478
479       --http-proxy=false
480
481
482       Defaults to true
483
484
485       --image-volume, builtin-volume=bind|tmpfs|ignore
486
487
488       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
496
497       --init
498
499
500       Run an init inside the container that forwards signals and reaps
501       processes.
502
503
504       --init-path=""
505
506
507       Path to the container-init binary.
508
509
510       --interactive, -i=true|false
511
512
513       Keep STDIN open even if not attached. The default is false.
514
515
516       --ip6=""
517
518
519       Not implemented
520
521
522       --ip=""
523
524
525       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
532
533       --ipc=""
534
535
536       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
546
547       --kernel-memory=""
548
549
550       Kernel memory limit (format: <number>[<unit>], where unit = b, k, m or
551       g)
552
553
554       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
560
561       --label, -l=[]
562
563
564       Add metadata to a container (e.g., --label com.example.key=value)
565
566
567       --label-file=[]
568
569
570       Read in a line delimited file of labels
571
572
573       --link-local-ip=[]
574
575
576       Not implemented
577
578
579       --log-driver="k8s-file"
580
581
582       Logging driver for the container.  Currently not supported.  This flag
583       is a NOOP provided soley for scripting compatibility.
584
585
586       --log-opt=[]
587
588
589       Logging driver specific options.  Used to set the path to the container
590       log file.  For example:
591
592
593       --log-opt path=/var/log/container/mycontainer.json
594
595
596       --mac-address=""
597
598
599       Container MAC address (e.g. 92:d0:c6:0a:29:33)
600
601
602       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
606
607       Not currently supported
608
609
610       --memory, -m=""
611
612
613       Memory limit (format: <number>[<unit>], where unit = b, k, m or g)
614
615
616       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
623
624       --memory-reservation=""
625
626
627       Memory soft limit (format: <number>[<unit>], where unit = b, k, m or g)
628
629
630       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
636
637       --memory-swap="LIMIT"
638
639
640       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
645
646       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
650
651       --memory-swappiness=""
652
653
654       Tune a container's memory swappiness behavior. Accepts an integer
655       between 0 and 100.
656
657
658       --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
659
660
661       Attach a filesystem mount to the container
662
663
664       Current supported mount TYPES are bind, and tmpfs.
665
666
667                 e.g.
668
669                 type=bind,source=/path/on/host,destination=/path/in/container
670
671                 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
672
673                 Common Options:
674
675                        · src, source: mount source spec for bind and volume. Mandatory for bind.
676
677                        · dst, destination, target: mount destination spec.
678
679                        · ro, read-only: true or false (default).
680
681                 Options specific to bind:
682
683                        · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
684
685                 Options specific to tmpfs:
686
687                        · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
688
689                        · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
690
691
692
693       --name=""
694
695
696       Assign a name to the container
697
698
699       The operator can identify a container in three ways: UUID long
700       identifier
701       (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”)
702       UUID short identifier (“f78375b1c487”) Name (“jonah”)
703
704
705       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
710
711       --network, --net="bridge"
712
713
714       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
728
729       --network-alias=[]
730
731
732       Not implemented
733
734
735       --no-hosts=true|false
736
737
738       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
743
744       --oom-kill-disable=true|false
745
746
747       Whether to disable OOM Killer for the container or not.
748
749
750       --oom-score-adj=""
751
752
753       Tune the host's OOM preferences for containers (accepts -1000 to 1000)
754
755
756       --pid=""
757
758
759       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
768
769       --pids-limit=""
770
771
772       Tune the container's pids limit. Set -1 to have unlimited pids for the
773       container.
774
775
776       --pod=""
777
778
779       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
784
785       --privileged=true|false
786
787
788       Give extended privileges to this container. The default is false.
789
790
791       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
796
797       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
802
803       --publish, -p=[]
804
805
806       Publish a container's port, or range of ports, to the host
807
808
809       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
820
821       --publish-all, -P=true|false
822
823
824       Publish all exposed ports to random ports on the host interfaces. The
825       default is false.
826
827
828       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
836
837       --quiet, -q
838
839
840       Suppress output information when pulling images
841
842
843       --read-only=true|false
844
845
846       Mount the container's root filesystem as read only.
847
848
849       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
854
855       --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
859
860       --restart=""
861
862
863       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
867
868              · no                       : Do not restart containers on exit
869
870              · 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
874              · always                   : Restart containers when they exit,
875                regardless of status, retrying indefinitely
876
877
878
879       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
885
886       --rm=true|false
887
888
889       Automatically remove the container when it exits. The default is false.
890
891
892       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
896
897       --rootfs
898
899
900       If specified, the first argument refers to an exploded container on the
901       file system.
902
903
904       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
908
909       --security-opt=[]
910
911
912       Security Options
913
914
915       "apparmor=unconfined" : Turn off apparmor confinement for the container
916       "apparmor=your-profile" : Set the apparmor confinement profile for the
917       container
918
919
920       "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
926
927       "no-new-privileges" : Disable container processes from gaining
928       additional privileges
929
930
931       "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
935
936       Note: Labelling can be disabled for all containers by setting
937       label=false in the libpod.conf (/etc/containers/libpod.conf) file.
938
939
940       --shm-size=""
941
942
943       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
948
949       --stop-signal=SIGTERM
950
951
952       Signal to stop a container. Default is SIGTERM.
953
954
955       --stop-timeout=10
956
957
958       Timeout (in seconds) to stop a container. Default is 10.
959
960
961       --subgidname=name
962
963
964       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
968
969       --subuidname=name
970
971
972       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
976
977       --sysctl=SYSCTL
978
979
980       Configure namespaced kernel parameters at runtime
981
982
983       IPC Namespace - current sysctls allowed:
984
985
986       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
990
991       Note: if you use the --ipc=host option these sysctls will not be
992       allowed.
993
994
995       Network Namespace - current sysctls allowed:
996           Sysctls beginning with net.*
997
998
999       Note: if you use the --network=host option these sysctls will not be
1000       allowed.
1001
1002
1003       --systemd=true|false
1004
1005
1006       Run container in systemd mode. The default is true.
1007
1008
1009       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
1012
1013       /run, /run/lock, /tmp, /sys/fs/cgroup/systemd, /var/lib/journal
1014
1015
1016       It will also set the default stop signal to SIGRTMIN+3.
1017
1018
1019       This allow systemd to run in a confined container without any
1020       modifications.
1021
1022
1023       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
1028
1029       setsebool -P container_manage_cgroup true
1030
1031
1032       --tmpfs=[] Create a tmpfs mount
1033
1034
1035       Mount a temporary filesystem (tmpfs) mount into a container, for
1036       example:
1037
1038
1039       $ podman run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
1040
1041
1042       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
1047
1048       --tty, -t=true|false
1049
1050
1051       Allocate a pseudo-TTY. The default is false.
1052
1053
1054       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
1058
1059       Note: The -t option is incompatible with a redirection of the podman
1060       client standard input.
1061
1062
1063       --uidmap=map
1064
1065
1066       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
1070
1071       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
1075
1076       --ulimit=[]
1077
1078
1079       Ulimit options
1080
1081
1082       --user, -u=""
1083
1084
1085       Sets the username or UID used and optionally the groupname or GID for
1086       the specified command.
1087
1088
1089       The followings examples are all valid: --user [user | user:group | uid
1090       | uid:gid | user:gid | uid:group ]
1091
1092
1093       Without this argument the command will be run as root in the container.
1094
1095
1096       --userns=host --userns=keep-id --userns=ns:my_namespace
1097
1098
1099       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
1103
1104              · 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
1109              · 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
1114              · ns: run the container in the given existing user namespace.
1115
1116
1117
1118       This option is incompatible with --gidmap, --uidmap, --subuid and
1119       --subgid
1120
1121
1122       --uts=host
1123
1124
1125       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
1131
1132       --volume, -v[=[HOST-DIR:CONTAINER-DIR[:OPTIONS]]]
1133
1134
1135       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
1139
1140              · [rw|ro]
1141
1142              · [z|Z]
1143
1144              · [[r]shared|[r]slave|[r]private]
1145
1146
1147
1148       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
1153
1154       You can specify multiple  -v options to mount one or more mounts to a
1155       container.
1156
1157
1158       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
1162
1163       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
1169
1170       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
1179
1180       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
1189
1190       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
1198
1199       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
1208
1209       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
1217
1218       --volumes-from[=CONTAINER[:OPTIONS]]
1219
1220
1221       Mount volumes from the specified container(s).  OPTIONS is a comma
1222       delimited list with the following available elements:
1223
1224
1225              · [rw|ro]
1226
1227              · z
1228
1229
1230
1231       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
1237
1238       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
1243
1244       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
1250
1251       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
1257
1258       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
1262
1263       --workdir, -w=""
1264
1265
1266       Working directory inside the container
1267
1268
1269       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
1274

EXAMPLES

1276   Create a container using a local image
1277              $ podman create alpine ls
1278
1279
1280
1281   Create a container using a local image and annotate it
1282              $ podman create --annotation HELLO=WORLD alpine ls
1283
1284
1285
1286   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
1290
1291
1292   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
1296
1297              $ podman create --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
1298
1299
1300
1301   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
1307
1308       Note: RHEL7 and Centos 7 will not have this feature until RHEL7.7 is
1309       released.
1310
1311
1312       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
1316
1317       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
1324

FILES

1326       /etc/subuid /etc/subgid
1327
1328

SEE ALSO

1330       subgid(5), subuid(5), libpod.conf(5), systemd.unit(5), setsebool(8),
1331       slirp4netns(1), fuse-overlayfs(1)
1332
1333

HISTORY

1335       October 2017, converted from Docker documentation to podman by Dan
1336       Walsh for podman ⟨dwalsh@redhat.com⟩
1337
1338
1339       November 2014, updated by Sven Dowideit ⟨SvenDowideit@home.org.au⟩
1340
1341
1342       September 2014, updated by Sven Dowideit ⟨SvenDowideit@home.org.au⟩
1343
1344
1345       August 2014, updated by Sven Dowideit ⟨SvenDowideit@home.org.au⟩
1346
1347
1348
1349                                                              podman-create(1)
Impressum