1podman-create(1)()                                          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
13       podman container create [options] image [command [arg ...]]
14
15

DESCRIPTION

17       Creates  a  writable  container layer over the specified image and pre‐
18       pares it for running the specified command. The container  ID  is  then
19       printed  to  STDOUT.  This  is similar to podman run -d except the con‐
20       tainer is never started. You can then use the  podman  start  container
21       command to start the container at any point.
22
23
24       The initial status of the container created with podman create is 'cre‐
25       ated'.
26
27
28       Default settings for flags are defined in  containers.conf.  Most  set‐
29       tings  for  remote connections use the server's containers.conf, except
30       when documented in man pages.
31
32

IMAGE

34       The image is specified using transport:path format. If no transport  is
35       specified,  the  docker  (container registry) transport will be used by
36       default. For remote Podman, including Mac and Windows (excluding  WSL2)
37       machines, docker is the only allowed transport.
38
39
40       dir:path
41         An existing local directory path storing the manifest, layer tarballs
42       and signatures as individual files. This is a non-standardized  format,
43       primarily useful for debugging or noninvasive container inspection.
44
45
46              $ podman save --format docker-dir fedora -o /tmp/fedora
47              $ podman create dir:/tmp/fedora echo hello
48
49
50
51       docker://docker-reference (Default)
52         An  image reference stored in  a remote container image registry. Ex‐
53       ample: "quay.io/podman/stable:latest".  The  reference  can  include  a
54       path  to  a specific registry; if it does not, the registries listed in
55       registries.conf will be queried to find a matching image.  By  default,
56       credentials  from  podman  login  (stored  at $XDG_RUNTIME_DIR/contain‐
57       ers/auth.json by default) will be used to  authenticate;  otherwise  it
58       falls back to using credentials in $HOME/.docker/config.json.
59
60
61              $ podman create registry.fedoraproject.org/fedora:latest echo hello
62
63
64
65       docker-archive:path[:docker-reference]  An  image  stored in the docker
66       save formatted file. docker-reference is only used when creating such a
67       file, and it must not contain a digest.
68
69
70              $ podman save --format docker-archive fedora -o /tmp/fedora
71              $ podman create docker-archive:/tmp/fedora echo hello
72
73
74
75       docker-daemon:docker-reference
76         An  image  in docker-reference format stored in the docker daemon in‐
77       ternal storage. The docker-reference can also be an image  ID  (docker-
78       daemon:algo:digest).
79
80
81              $ sudo docker pull fedora
82              $ sudo podman create docker-daemon:docker.io/library/fedora echo hello
83
84
85
86       oci-archive:path:tag
87         An image in a directory compliant with the "Open Container Image Lay‐
88       out Specification" at the specified path and specified with a tag.
89
90
91              $ podman save --format oci-archive fedora -o /tmp/fedora
92              $ podman create oci-archive:/tmp/fedora echo hello
93
94
95

OPTIONS

97   --add-host=host
98       Add a custom host-to-IP mapping (host:ip)
99
100
101       Add a line to /etc/hosts. The format is hostname:ip. The --add-host op‐
102       tion can be set multiple times.
103
104
105   --annotation=key=value
106       Add an annotation to the container. The format is key=value.  The --an‐
107       notation option can be set multiple times.
108
109
110   --arch=ARCH
111       Override the architecture, defaults  to  hosts,  of  the  image  to  be
112       pulled. For example, arm.
113
114
115   --attach, -a=location
116       Attach to STDIN, STDOUT or STDERR.
117
118
119       In  foreground  mode (the default when -d is not specified), podman run
120       can start the process in the container and attach the  console  to  the
121       process's  standard input, output, and standard error. It can even pre‐
122       tend to be a TTY (this is what most command  line  executables  expect)
123       and  pass  along  signals.  The -a option can be set for each of stdin,
124       stdout, and stderr.
125
126
127   --authfile=path
128       Path of the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
129       ers/auth.json
130
131
132       Note: You can also override the default path of the authentication file
133       by setting the REGISTRY_AUTH_FILE  environment  variable.  export  REG‐
134       ISTRY_AUTH_FILE=path
135
136
137   --blkio-weight=weight
138       Block IO weight (relative weight) accepts a weight value between 10 and
139       1000.
140
141
142   --blkio-weight-device=weight
143       Block IO weight (relative device weight, format: DEVICE_NAME:WEIGHT).
144
145
146   --cap-add=capability
147       Add Linux capabilities
148
149
150   --cap-drop=capability
151       Drop Linux capabilities
152
153
154   --cgroup-conf=KEY=VALUE
155       When running on cgroup v2, specify the cgroup file to write to and  its
156       value.  For  example --cgroup-conf=memory.high=1073741824 sets the mem‐
157       ory.high limit to 1GB.
158
159
160   --cgroup-parent=path
161       Path to cgroups under which the cgroup for the container will  be  cre‐
162       ated.  If  the path is not absolute, the path is considered to be rela‐
163       tive to the cgroups path of the init process. Cgroups will  be  created
164       if they do not already exist.
165
166
167   --cgroupns=mode
168       Set the cgroup namespace mode for the container.
169           host: use the host's cgroup namespace inside the container.
170           container:<NAME|ID>: join the namespace of the specified container.
171           ns:<PATH>: join the namespace at the specified path.
172           private: create a new cgroup namespace.
173
174
175       If  the host uses cgroups v1, the default is set to host. On cgroups v2
176       the default is private.
177
178
179   --cgroups=mode
180       Determines whether the container will create CGroups.  Valid values are
181       enabled, disabled, no-conmon, split, with the default being enabled.
182
183
184       The  enabled  option  will create a new cgroup under the cgroup-parent.
185       The disabled option will force the container to not create CGroups, and
186       thus  conflicts  with  CGroup options (--cgroupns and --cgroup-parent).
187       The no-conmon option disables a new CGroup only for the conmon process.
188       The  split option splits the current cgroup in two sub-cgroups: one for
189       conmon and one for the container payload. It is  not  possible  to  set
190       --cgroup-parent with split.
191
192
193   --chrootdirs=path
194       Path  to  a  directory inside the container that should be treated as a
195       chroot directory.  Any Podman  managed  file  (e.g.,  /etc/resolv.conf,
196       /etc/hosts,  etc/hostname) that is mounted into the root directory will
197       be mounted into that location as well.  Multiple directories should  be
198       separated with a comma.
199
200
201   --cidfile=id
202       Write the container ID to the file
203
204
205   --conmon-pidfile=path
206       Write  the  pid of the conmon process to a file. conmon runs in a sepa‐
207       rate process than Podman, so this is necessary when  using  systemd  to
208       restart  Podman containers.  (This option is not available with the re‐
209       mote Podman client, including Mac  and  Windows  (excluding  WSL2)  ma‐
210       chines)
211
212
213   --cpu-period=limit
214       Set  the CPU period for the Completely Fair Scheduler (CFS), which is a
215       duration in microseconds. Once the container's CPU quota is used up, it
216       will not be scheduled to run until the current period ends. Defaults to
217       100000 microseconds.
218
219
220       On some systems, changing the CPU limits may not be  allowed  for  non-
221       root  users.  For  more details, see https://github.com/containers/pod
222       man/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-
223       fails-with-a-permissions-error
224
225
226   --cpu-quota=limit
227       Limit the CPU Completely Fair Scheduler (CFS) quota.
228
229
230       Limit  the  container's  CPU usage. By default, containers run with the
231       full CPU resource. The limit is a number in microseconds. If  you  pro‐
232       vide  a number, the container will be allowed to use that much CPU time
233       until the CPU period ends (controllable via --cpu-period).
234
235
236       On some systems, changing the CPU limits may not be  allowed  for  non-
237       root  users.  For  more details, see https://github.com/containers/pod
238       man/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-
239       fails-with-a-permissions-error
240
241
242   --cpu-rt-period=microseconds
243       Limit the CPU real-time period in microseconds
244
245
246       Limit the container's Real Time CPU usage. This flag tell the kernel to
247       restrict the container's Real Time CPU usage to the period you specify.
248
249
250       This flag is not supported on cgroups V2 systems.
251
252
253   --cpu-rt-runtime=microseconds
254       Limit the CPU real-time runtime in microseconds
255
256
257       Limit the containers Real Time CPU usage. This flag tells the kernel to
258       limit the amount of time in a given CPU period Real Time tasks may con‐
259       sume. Ex: Period of 1,000,000us and Runtime  of  950,000us  means  that
260       this container could consume 95% of available CPU and leave the remain‐
261       ing 5% to normal priority tasks.
262
263
264       The sum of all runtimes across containers cannot exceed the amount  al‐
265       lotted to the parent cgroup.
266
267
268       This flag is not supported on cgroups V2 systems.
269
270
271   --cpu-shares=shares
272       CPU shares (relative weight)
273
274
275       By  default, all containers get the same proportion of CPU cycles. This
276       proportion can be  modified  by  changing  the  container's  CPU  share
277       weighting relative to the weighting of all other running containers.
278
279
280       To modify the proportion from the default of 1024, use the --cpu-shares
281       flag to set the weighting to 2 or higher.
282
283
284       The proportion will only apply when CPU-intensive  processes  are  run‐
285       ning.   When  tasks in one container are idle, other containers can use
286       the left-over CPU time. The actual amount of CPU time will vary depend‐
287       ing on the number of containers running on the system.
288
289
290       For example, consider three containers, one has a cpu-share of 1024 and
291       two others have a cpu-share setting of 512. When processes in all three
292       containers  attempt  to  use 100% of CPU, the first container would re‐
293       ceive 50% of the total CPU time. If you add a fourth container  with  a
294       cpu-share  of  1024,  the first container only gets 33% of the CPU. The
295       remaining containers receive 16.5%, 16.5% and 33% of the CPU.
296
297
298       On a multi-core system, the shares of CPU time are distributed over all
299       CPU  cores.  Even  if  a  container is limited to less than 100% of CPU
300       time, it can use 100% of each individual CPU core.
301
302
303       For example, consider a system with more than three cores. If you start
304       one  container  {C0}  with -c=512 running one process, and another con‐
305       tainer {C1} with -c=1024 running two processes, this can result in  the
306       following division of CPU shares:
307
308
309       PID     container    CPU  CPU  share  100     {C0}         0    100% of
310       CPU0      101         {C1}         1    100%      of      CPU1      102
311       {C1}         2    100% of CPU2
312
313
314   --cpus=number
315       Number of CPUs. The default is 0.0 which means no limit. This is short‐
316       hand for --cpu-period and --cpu-quota, so you may only set either
317
318
319   --cpus or --cpu-period and --cpu-quota.
320       On some systems, changing the CPU limits may not be  allowed  for  non-
321       root  users.  For  more details, see https://github.com/containers/pod
322       man/blob/main/troubleshooting.md#26-running-containers-with-cpu-limits-
323       fails-with-a-permissions-error
324
325
326   --cpuset-cpus=cpus
327       CPUs in which to allow execution (0-3, 0,1)
328
329
330   --cpuset-mems=nodes
331       Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effec‐
332       tive on NUMA systems.
333
334
335       If you have four memory nodes  on  your  system  (0-3),  use  --cpuset-
336       mems=0,1 then processes in your container will only use memory from the
337       first two memory nodes.
338
339
340   --device=host-device[:container-device][:permissions]
341       Add a host device to the container. Optional permissions parameter  can
342       be used to specify device permissions, it is combination of r for read,
343       w for write, and m for mknod(2).
344
345
346       Example: --device=/dev/sdc:/dev/xvdc:rwm.
347
348
349       Note: if _hostdevice is a symbolic link then it will be resolved first.
350       The  container  will only store the major and minor numbers of the host
351       device.
352
353
354       Note: if the user only has access rights via a group, accessing the de‐
355       vice  from  inside  a rootless container will fail. Use the --group-add
356       keep-groups flag to pass the user's supplementary group access into the
357       container.
358
359
360       Podman may load kernel modules required for using the specified device.
361       The  devices  that  podman  will  load  modules  when  necessary   are:
362       /dev/fuse.
363
364
365   --device-cgroup-rule="type major:minor mode"
366       Add  a rule to the cgroup allowed devices list. The rule is expected to
367       be in the format specified in the Linux kernel documentation  (Documen‐
368       tation/cgroup-v1/devices.txt):
369              - type: a (all), c (char), or b (block);
370              - major and minor: either a number, or * for all;
371              - mode: a composition of r (read), w (write), and m (mknod(2)).
372
373
374   --device-read-bps=path
375       Limit  read  rate (bytes per second) from a device (e.g. --device-read-
376       bps=/dev/sda:1mb)
377
378
379   --device-read-iops=path
380       Limit read rate (IO per second)  from  a  device  (e.g.  --device-read-
381       iops=/dev/sda:1000)
382
383
384   --device-write-bps=path
385       Limit  write  rate (bytes per second) to a device (e.g. --device-write-
386       bps=/dev/sda:1mb)
387
388
389   --device-write-iops=path
390       Limit write rate (IO per second)  to  a  device  (e.g.  --device-write-
391       iops=/dev/sda:1000)
392
393
394   --disable-content-trust
395       This  is  a  Docker  specific option to disable image verification to a
396       Docker registry and is not supported by Podman. This flag is a NOOP and
397       provided solely for scripting compatibility.
398
399
400   --dns=dns
401       Set  custom  DNS  servers. Invalid if using --dns and --network that is
402       set to 'none' or container:<name|id>.
403
404
405       This option can be used to override the DNS configuration passed to the
406       container.  Typically this is necessary when the host DNS configuration
407       is invalid for the container (e.g., 127.0.0.1). When this is  the  case
408       the --dns flag is necessary for every run.
409
410
411       The special value none can be specified to disable creation of /etc/re‐
412       solv.conf in the container by Podman.  The /etc/resolv.conf file in the
413       image will be used without changes.
414
415
416   --dns-opt=option
417       Set  custom  DNS options. Invalid if using --dns-opt and --network that
418       is set to 'none' or container:<name|id>.
419
420
421   --dns-search=domain
422       Set custom DNS search domains. Invalid if using --dns-search and --net‐
423       work  that is set to 'none' or container:<name|id>. (Use --dns-search=.
424       if you don't wish to set the search domain)
425
426
427   --entrypoint="command" | '["command", arg1 , ...]'
428       Overwrite the default ENTRYPOINT of the image
429
430
431       This option allows you to overwrite the default entrypoint of  the  im‐
432       age.   The  ENTRYPOINT  of  an image is similar to a COMMAND because it
433       specifies what executable to run when the container starts, but  it  is
434       (purposely)  more  difficult  to  override. The ENTRYPOINT gives a con‐
435       tainer its default nature or behavior, so that when you set  an  ENTRY‐
436       POINT  you  can  run  the container as if it were that binary, complete
437       with default options, and you can pass in more options via the COMMAND.
438       But,  sometimes  an  operator may want to run something else inside the
439       container, so you can override the default ENTRYPOINT at runtime by us‐
440       ing a --entrypoint and a string to specify the new ENTRYPOINT.
441
442
443       You need to specify multi option commands in the form of a json string.
444
445
446   --env, -e=env
447       Set environment variables
448
449
450       This  option  allows arbitrary environment variables that are available
451       for the process to be launched inside of the container. If an  environ‐
452       ment  variable is specified without a value, Podman will check the host
453       environment for a value and set the variable only if it is set  on  the
454       host.  If an environment variable ending in * is specified, Podman will
455       search the host environment for variables starting with the prefix  and
456       will  add  those variables to the container. If an environment variable
457       with a trailing ***** is specified, then a value must be supplied.
458
459
460       See Environment ⟨#environment⟩ note below for precedence and examples.
461
462
463   --env-file=file
464       Read in a line delimited file of environment variables. See Environment
465       note below for precedence.
466
467
468   --env-host
469       Use  host environment inside of the container. See Environment note be‐
470       low for precedence. (This option is not available with the remote  Pod‐
471       man client, including Mac and Windows (excluding WSL2) machines)
472
473
474   --expose=port
475       Expose  a port, or a range of ports (e.g. --expose=3300-3310) to set up
476       port redirection on the host system.
477
478
479   --gidmap=container_gid:host_gid:amount
480       GID map for the user namespace. Using this flag will run the  container
481       with  user namespace enabled. It conflicts with the --userns and --sub‐
482       gidname flags.
483
484
485       The following example maps uids 0-2000 in the  container  to  the  uids
486       30000-31999  on  the  host and gids 0-2000 in the container to the gids
487       30000-31999 on the host. --gidmap=0:30000:2000
488
489
490       Note: the --gidmap flag cannot be called in conjunction with the  --pod
491       flag as a gidmap cannot be set on the container level when in a pod.
492
493
494   --group-add=group|keep-groups
495       Assign  additional  groups  to the primary user running within the con‐
496       tainer process.
497
498
499keep-groups is a special flag that tells Podman  to  keep  the
500                supplementary group access.
501
502
503
504       Allows  container to use the user's supplementary group access. If file
505       systems or devices are only accessible by the  rootless  user's  group,
506       this  flag tells the OCI runtime to pass the group access into the con‐
507       tainer. Currently only available with the crun OCI runtime. Note: keep-
508       groups  is  exclusive,  you cannot add any other groups with this flag.
509       (Not available for remote commands, including Mac and Windows  (exclud‐
510       ing WSL2) machines)
511
512
513   --health-cmd="command" | '["command", arg1 , ...]'
514       Set  or  alter  a healthcheck command for a container. The command is a
515       command to be executed inside your container that determines your  con‐
516       tainer health. The command is required for other healthcheck options to
517       be applied. A value of none disables existing healthchecks.
518
519
520       Multiple options can be passed in the form of a JSON array;  otherwise,
521       the command will be interpreted as an argument to /bin/sh -c.
522
523
524   --health-interval=interval
525       Set  an interval for the healthchecks (a value of disable results in no
526       automatic timer setup) (default "30s")
527
528
529   --health-retries=retries
530       The number of retries allowed before a healthcheck is considered to  be
531       unhealthy. The default value is 3.
532
533
534   --health-start-period=period
535       The  initialization time needed for a container to bootstrap. The value
536       can be expressed in time format like 2m3s. The default value is 0s
537
538
539   --health-timeout=timeout
540       The maximum time allowed to complete the healthcheck before an interval
541       is  considered failed. Like start-period, the value can be expressed in
542       a time format such as 1m22s. The default value is 30s.
543
544
545   --help
546       Print usage statement
547
548
549   --hostname=name, -h
550       Container host name
551
552
553       Sets the container host name that is available  inside  the  container.
554       Can  only be used with a private UTS namespace --uts=private (default).
555       If --pod is specified and the pod shares the  UTS  namespace  (default)
556       the pod's hostname will be used.
557
558
559   --hostuser=name
560       Add  a  user account to /etc/passwd from the host to the container. The
561       Username or UID must exist on the host system.
562
563
564   --http-proxy
565       By default proxy environment variables are passed into the container if
566       set for the Podman process. This can be disabled by setting the --http-
567       proxy option to false. The  environment  variables  passed  in  include
568       http_proxy,  https_proxy,  ftp_proxy, no_proxy, and also the upper case
569       versions of those. This option is only needed when the host system must
570       use  a proxy but the container should not use any proxy. Proxy environ‐
571       ment variables specified for the container in any other way will  over‐
572       ride  the  values  that  would  have been passed through from the host.
573       (Other ways to specify the proxy for the container include passing  the
574       values  with  the  --env  flag, or hard coding the proxy environment at
575       container build time.)  (This option is not available with  the  remote
576       Podman client, including Mac and Windows (excluding WSL2) machines)
577
578
579       For  example,  to disable passing these environment variables from host
580       to container:
581
582
583       --http-proxy=false
584
585
586       Defaults to true
587
588
589   --image-volume, builtin-volume=bind|tmpfs|ignore
590       Tells Podman how to handle the builtin image volumes. Default is bind.
591
592
593bind: An anonymous named volume will be  created  and  mounted
594                into the container.
595
596tmpfs:  The  volume  is mounted onto the container as a tmpfs,
597                which allows the users to create content that disappears  when
598                the container is stopped.
599
600ignore: All volumes are just ignored and no action is taken.
601
602
603
604   --init
605       Run  an  init inside the container that forwards signals and reaps pro‐
606       cesses.
607
608
609   --init-ctr=type (pods only)
610       When using pods, create an init style container, which is run after the
611       infra  container  is  started  but  before  regular  pod containers are
612       started.  Init containers are useful for running setup  operations  for
613       the pod's applications.
614
615
616       Valid  values  for  init-ctr type are always or once.  The always value
617       means the container will run with each and every pod start, whereas the
618       once  value  means  the  container  will  only run once when the pod is
619       started and then the container is removed.
620
621
622       Init containers are only run on pod start.  Restarting a pod  will  not
623       execute  any init containers should they be present.  Furthermore, init
624       containers can only be created in a pod when that pod is not running.
625
626
627   --init-path=path
628       Path to the container-init binary.
629
630
631   --interactive, -i
632       Keep STDIN open even if not attached. The default is false.
633
634
635   --ip=ipv4
636       Specify  a  static  IPv4  address  for  the  container,   for   example
637       10.88.64.128.   This option can only be used if the container is joined
638       to only a single network - i.e., --network=network-name is used at most
639       once  - and if the container is not joining another container's network
640       namespace via --network=container:id.  The address must be  within  the
641       network's IP address pool (default 10.88.0.0/16).
642
643
644       To  specify  multiple  static  IP addresses per container, set multiple
645       networks using the --network option with a static IP address  specified
646       for each using the ip mode for that option.
647
648
649   --ip6=ipv6
650       Specify   a   static  IPv6  address  for  the  container,  for  example
651       fd46:db93:aa76:ac37::10.  This option can only be used if the container
652       is  joined  to  only a single network - i.e., --network=network-name is
653       used at most once - and if the container is not  joining  another  con‐
654       tainer's  network  namespace  via  --network=container:id.  The address
655       must be within the network's IPv6 address pool.
656
657
658       To specify multiple static IPv6 addresses per container,  set  multiple
659       networks  using  the --network option with a static IPv6 address speci‐
660       fied for each using the ip6 mode for that option.
661
662
663   --ipc=ipc
664       Set the IPC namespace mode for a container. The default is to create  a
665       private IPC namespace.
666
667
668              • "": Use Podman's default, defined in containers.conf.
669
670container:id:  reuses another container's shared memory, sema‐
671                phores, and message queues
672
673host: use the host's shared memory,  semaphores,  and  message
674                queues  inside  the  container.  Note: the host mode gives the
675                container full access to local shared memory and is  therefore
676                considered insecure.
677
678none:  private IPC namespace, with /dev/shm not mounted.
679
680ns:path: path to an IPC namespace to join.
681
682private:  private  IPC  namespace.   =  shareable: private IPC
683                namespace with a possibility to share it with  other  contain‐
684                ers.
685
686
687
688   --label, -l=label
689       Add metadata to a container (e.g., --label com.example.key=value)
690
691
692   --label-file=file
693       Read in a line delimited file of labels
694
695
696   --link-local-ip=ip
697       Not implemented
698
699
700   --log-driver="k8s-file"
701       Logging  driver for the container. Currently available options are k8s-
702       file, journald, none and passthrough, with json-file  aliased  to  k8s-
703       file for scripting compatibility.
704
705
706       The  podman  info command below will display the default log-driver for
707       the system.
708
709
710              $ podman info --format '{{ .Host.LogDriver }}'
711              journald
712
713
714
715       The passthrough driver passes down the standard streams (stdin, stdout,
716       stderr)  to  the  container.   It is not allowed with the remote Podman
717       client, including Mac and Windows (excluding WSL2) machines, and  on  a
718       tty, since it is vulnerable to attacks via TIOCSTI.
719
720
721   --log-opt=name=value
722       Set custom logging configuration. The following *name*s are supported:
723
724
725path:   specify  a  path  to  the  log  file  (e.g.  --log-opt
726                path=/var/log/container/mycontainer.json);
727
728max-size: specify a max size of the log file  (e.g.  --log-opt
729                max-size=10mb);
730
731tag:  specify  a custom log tag for the container (e.g. --log-
732                opt tag="{{.ImageName}}".
733
734
735
736       It supports the same keys as podman inspect --format.
737
738
739       This option is currently supported only by the journald log driver.
740
741
742   --mac-address=address
743       Container network interface MAC address (e.g.  92:d0:c6:0a:29:33)  This
744       option  can  only  be  used if the container is joined to only a single
745       network - i.e., --network=network-name is used at most once  -  and  if
746       the  container is not joining another container's network namespace via
747       --network=container:id.
748
749
750       Remember that the MAC address in an Ethernet network  must  be  unique.
751       The  IPv6  link-local address will be based on the device's MAC address
752       according to RFC4862.
753
754
755       To specify multiple static MAC addresses per  container,  set  multiple
756       networks using the --network option with a static MAC address specified
757       for each using the mac mode for that option.
758
759
760   --memory, -m=limit
761       Memory limit (format: <number>[<unit>],  where  unit  =  b  (bytes),  k
762       (kibibytes), m (mebibytes), or g (gibibytes))
763
764
765       Allows  you  to  constrain  the memory available to a container. If the
766       host supports swap memory, then the -m memory  setting  can  be  larger
767       than  physical  RAM.  If  a limit of 0 is specified (not using -m), the
768       container's memory is not limited. The actual limit may be  rounded  up
769       to  a  multiple of the operating system's page size (the value would be
770       very large, that's millions of trillions).
771
772
773   --memory-reservation=limit
774       Memory soft limit (format: <number>[<unit>], where unit = b (bytes),  k
775       (kibibytes), m (mebibytes), or g (gibibytes))
776
777
778       After  setting  memory reservation, when the system detects memory con‐
779       tention or low memory, containers are forced to restrict their consump‐
780       tion  to  their  reservation.  So you should always set the value below
781       --memory, otherwise the hard limit will take  precedence.  By  default,
782       memory reservation will be the same as memory limit.
783
784
785   --memory-swap=limit
786       A  limit  value  equal  to  memory plus swap. Must be used with the  -m
787       (--memory) flag. The swap LIMIT should always be larger than -m (--mem‐
788       ory)  value. By default, the swap LIMIT will be set to double the value
789       of --memory.
790
791
792       The format of LIMIT is <number>[<unit>].  Unit  can  be  b  (bytes),  k
793       (kibibytes),  m  (mebibytes),  or g (gibibytes). If you don't specify a
794       unit, b is used. Set LIMIT to -1 to enable unlimited swap.
795
796
797   --memory-swappiness=number
798       Tune a container's memory swappiness behavior. Accepts an  integer  be‐
799       tween 0 and 100.
800
801
802       This flag is not supported on cgroups V2 systems.
803
804
805   --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
806       Attach a filesystem mount to the container
807
808
809       Current  supported  mount  TYPEs are bind, volume, image, tmpfs and de‐
810       vpts. [1] ⟨#Footnote1⟩
811
812
813                 e.g.
814
815                 type=bind,source=/path/on/host,destination=/path/in/container
816
817                 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
818
819                 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=true
820
821                 type=volume,source=vol1,destination=/path/in/container,ro=true
822
823                 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
824
825                 type=image,source=fedora,destination=/fedora-image,rw=true
826
827                 type=devpts,destination=/dev/pts
828
829                 Common Options:
830
831                    · src, source: mount source spec for bind and volume. Mandatory for bind.
832
833                    · dst, destination, target: mount destination spec.
834
835                 Options specific to volume:
836
837                    · ro, readonly: true or false (default).
838
839                    . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
840
841                    · idmap: true or false (default).  If specified, create an idmapped mount to the target user namespace in the container.
842
843                 Options specific to image:
844
845                    · rw, readwrite: true or false (default).
846
847                 Options specific to bind:
848
849                    · ro, readonly: true or false (default).
850
851                    · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2).
852
853                    . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive.
854
855                    . relabel: shared, private.
856
857                    · idmap: true or false (default).  If specified, create an idmapped mount to the target user namespace in the container.
858
859                    . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
860
861                 Options specific to tmpfs:
862
863                    · ro, readonly: true or false (default).
864
865                    · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
866
867                    · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
868
869                    · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default.
870
871                    · notmpcopyup: Disable copying files from the image to the tmpfs.
872
873                    . U, chown: true or false (default). Change recursively the owner and group of the source volume based on the UID and GID of the container.
874
875                 Options specific to devpts:
876
877                    · uid: UID of the file owner (default 0).
878
879                    · gid: GID of the file owner (default 0).
880
881                    · mode: permission mask for the file (default 600).
882
883                    · max: maximum number of PTYs (default 1048576).
884
885
886
887   --name=name
888       Assign a name to the container
889
890
891       The operator can identify a container in three ways: UUID long  identi‐
892       fier
893       (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”)
894       UUID short identifier (“f78375b1c487”) Name (“jonah”)
895
896
897       podman  generates  a  UUID for each container, and if a name is not as‐
898       signed to the container with --name then  it  will  generate  a  random
899       string  name.  The name is useful any place you need to identify a con‐
900       tainer.  This works for both background and foreground containers.
901
902
903   --network=mode, --net
904       Set the network mode for the container. Invalid if using --dns,  --dns-
905       opt,  or  --dns-search  with  --network set to none or container:id. If
906       used together with --pod, the container will not join the pod's network
907       namespace.
908
909
910       Valid mode values are:
911
912
913bridge[:OPTIONS,...]:  Create  a  network stack on the default
914                bridge. This is the default for rootful containers. It is pos‐
915                sible to specify these additional options:
916
917alias=name: Add network-scoped alias for the container.
918
919ip=IPv4: Specify a static ipv4 address for this container.
920
921ip=IPv6: Specify a static ipv6 address for this container.
922
923mac=MAC: Specify a static mac address for this container.
924
925interface_name:  Specify  a name for the created network in‐
926                  terface inside the container.
927
928
929
930
931
932       For example to set a static ipv4 address and a static mac address,  use
933       --network  bridge:ip=10.88.0.10,mac=44:33:22:11:00:99.  - <network name
934       or ID>[:OPTIONS,...]: Connect to a user-defined network;  this  is  the
935       network name or ID from a network created by podman network create. Us‐
936       ing the network name implies the bridge network mode. It is possible to
937       specify the same options described under the bridge mode above. You can
938       use the --network option multiple times to specify additional networks.
939       - none: Create a network namespace for the container but do not config‐
940       ure network interfaces for it, thus the container has no  network  con‐
941       nectivity.  - container:id: Reuse another container's network stack.  -
942       host: Do not create a network namespace, the  container  will  use  the
943       host's  network. Note: The host mode gives the container full access to
944       local system services such as D-bus and is therefore  considered  inse‐
945       cure.  - ns:path: Path to a network namespace to join.  - private: Cre‐
946       ate a new namespace for the container. This will use  the  bridge  mode
947       for   rootful   containers   and  slirp4netns  for  rootless  ones.   -
948       slirp4netns[:OPTIONS,...]: use slirp4netns(1) to create a user  network
949       stack.  This  is the default for rootless containers. It is possible to
950       specify these additional options,  they  can  also  be  set  with  net‐
951       work_cmd_options in containers.conf:
952         -  allow_host_loopback=true|false: Allow the slirp4netns to reach the
953       host loopback IP (10.0.2.2). Default is false.
954         - mtu=MTU: Specify the MTU to  use  for  this  network.  (Default  is
955       65520).
956         -  cidr=CIDR:  Specify  ip range to use for this network. (Default is
957       10.0.2.0/24).
958         - enable_ipv6=true|false: Enable IPv6. Default is true. (Required for
959       outbound_addr6).
960         -  outbound_addr=INTERFACE:  Specify  the  outbound  interface  slirp
961       should bind to (ipv4 traffic only).
962         - outbound_addr=IPv4: Specify the outbound ipv4 address slirp  should
963       bind to.
964         -  outbound_addr6=INTERFACE:  Specify  the  outbound  interface slirp
965       should bind to (ipv6 traffic only).
966         - outbound_addr6=IPv6: Specify the outbound ipv6 address slirp should
967       bind to.
968         -  port_handler=rootlesskit: Use rootlesskit for port forwarding. De‐
969       fault.
970         Note: Rootlesskit changes the source IP address of  incoming  packets
971       to   an   IP  address  in  the  container  network  namespace,  usually
972       10.0.2.100. If your application requires the real  source  IP  address,
973       e.g. web server logs, use the slirp4netns port handler. The rootlesskit
974       port handler is also used for rootless  containers  when  connected  to
975       user-defined networks.
976         -  port_handler=slirp4netns:  Use the slirp4netns port forwarding, it
977       is slower than rootlesskit but preserves the correct source IP address.
978       This port handler cannot be used for user-defined networks.
979
980
981   --network-alias=alias
982       Add a network-scoped alias for the container, setting the alias for all
983       networks that the container joins. To set a name only  for  a  specific
984       network,  use the alias option as described under the --network option.
985       Network aliases work only with the bridge networking mode. This  option
986       can  be specified multiple times.  NOTE: A container will only have ac‐
987       cess to aliases on the first network that it joins. This is  a  limita‐
988       tion that will be removed in a later release.
989
990
991   --no-healthcheck
992       Disable any defined healthchecks for container.
993
994
995   --no-hosts
996       Do  not  create  /etc/hosts for the container.  By default, Podman will
997       manage /etc/hosts, adding the container's own IP address and any  hosts
998       from  --add-host.  --no-hosts disables this, and the image's /etc/hosts
999       will be preserved unmodified.  This option conflicts with --add-host.
1000
1001
1002   --oom-kill-disable
1003       Whether to disable OOM Killer for the container or not.
1004
1005
1006       This flag is not supported on cgroups V2 systems.
1007
1008
1009   --oom-score-adj=num
1010       Tune the host's OOM preferences for containers (accepts -1000 to 1000)
1011
1012
1013   --os=OS
1014       Override the OS, defaults to hosts, of the image to be pulled. For  ex‐
1015       ample, windows.
1016
1017
1018   --passwd-entry=ENTRY
1019       Customize  the entry that is written to the /etc/passwd file within the
1020       container when --passwd is used.
1021
1022
1023       The variables $USERNAME, $UID, $GID, $NAME, $HOME are automatically re‐
1024       placed with their value at runtime.
1025
1026
1027   --personality=persona
1028       Personality sets the execution domain via Linux personality(2).
1029
1030
1031   --pid=pid
1032       Set  the  PID mode for the container Default is to create a private PID
1033       namespace for the container - container:<name|id>:  join  another  con‐
1034       tainer's  PID  namespace  -  host: use the host's PID namespace for the
1035       container. Note: the host mode gives the container full access to local
1036       PID and is therefore considered insecure.  - ns: join the specified PID
1037       namespace - private: create a new namespace for the container (default)
1038
1039
1040   --pidfile=path
1041       When the pidfile location is specified, the container process' PID will
1042       be  written  to the pidfile. (This option is not available with the re‐
1043       mote Podman client, including Mac  and  Windows  (excluding  WSL2)  ma‐
1044       chines)  If the pidfile option is not specified, the container process'
1045       PID will be written  to  /run/containers/storage/${storage-driver}-con‐
1046       tainers/$CID/userdata/pidfile.
1047
1048
1049       After  the  container  is  started, the location for the pidfile can be
1050       discovered with the following podman inspect command:
1051
1052
1053              $ podman inspect --format '{{ .PidFile }}' $CID
1054              /run/containers/storage/${storage-driver}-containers/$CID/userdata/pidfile
1055
1056
1057
1058   --pids-limit=limit
1059       Tune the container's pids limit. Set -1 to have unlimited pids for  the
1060       container. (default "4096" on systems that support PIDS cgroups).
1061
1062
1063   --platform=OS/ARCH
1064       Specify  the platform for selecting the image.   (Conflicts with --arch
1065       and --os) The --platform option can be used to override the current ar‐
1066       chitecture and operating system.
1067
1068
1069   --pod=name
1070       Run  container  in  an existing pod. If you want Podman to make the pod
1071       for you, preference the pod name with new:.  To make a  pod  with  more
1072       granular  options,  use the podman pod create command before creating a
1073       container.
1074
1075
1076   --pod-id-file=path
1077       Run container in an existing pod and read the pod's ID from the  speci‐
1078       fied  file.  If a container is run within a pod, and the pod has an in‐
1079       fra-container, the infra-container will be started before the container
1080       is.
1081
1082
1083   --privileged
1084       Give extended privileges to this container. The default is false.
1085
1086
1087       By  default,  Podman containers are “unprivileged” (=false) and cannot,
1088       for example, modify parts of the operating system.  This is because  by
1089       default  a  container  is not allowed to access any devices.  A “privi‐
1090       leged” container is given access to all devices.
1091
1092
1093       When the operator executes a privileged container, Podman  enables  ac‐
1094       cess  to  all devices on the host, turns off graphdriver mount options,
1095       as well as turning off most of the  security  measures  protecting  the
1096       host from the container.
1097
1098
1099       Rootless  containers  cannot have more privileges than the account that
1100       launched them.
1101
1102
1103   --publish, -p=[[ip:][hostPort]:]containerPort[/protocol]
1104       Publish a container's port, or range of ports, to the host.
1105
1106
1107       Both hostPort and containerPort can be specified as a range  of  ports.
1108       When  specifying  ranges for both, the number of container ports in the
1109       range must match the number of host ports in the range.
1110
1111
1112       If host IP is set to 0.0.0.0 or not set at all, the port will be  bound
1113       on all IPs on the host.
1114
1115
1116       By  default,  Podman  will publish TCP ports. To publish a UDP port in‐
1117       stead, give udp as protocol. To publish both TCP  and  UDP  ports,  set
1118       --publish  twice,  with tcp, and udp as protocols respectively. Rootful
1119       containers can also publish ports using the sctp protocol.
1120
1121
1122       Host  port  does  not  have  to  be  specified  (e.g.  podman  run   -p
1123       127.0.0.1::80).   If it is not, the container port will be randomly as‐
1124       signed a port on the host.
1125
1126
1127       Use podman port to see the actual mapping: podman port $CONTAINER $CON‐
1128       TAINERPORT.
1129
1130
1131       Note:  If  a container will be run within a pod, it is not necessary to
1132       publish the port for the containers in the pod. The port must  only  be
1133       published  by  the  pod itself. Pod network stacks act like the network
1134       stack on the host - you have a variety of containers in  the  pod,  and
1135       programs  in  the  container, all sharing a single interface and IP ad‐
1136       dress, and associated ports. If one container binds to a port, no other
1137       container can use that port within the pod while it is in use. Contain‐
1138       ers in the pod can also communicate over localhost by having  one  con‐
1139       tainer bind to localhost in the pod, and another connect to that port.
1140
1141
1142   --publish-all, -P
1143       Publish  all  exposed ports to random ports on the host interfaces. The
1144       default is false.
1145
1146
1147       When set to true publish all exposed ports to the host interfaces.  The
1148       default is false. If the operator uses -P (or -p) then Podman will make
1149       the exposed port accessible on the host and the ports will be available
1150       to  any client that can reach the host. When using -P, Podman will bind
1151       any exposed port to a random port on the host within an ephemeral  port
1152       range  defined  by  /proc/sys/net/ipv4/ip_local_port_range. To find the
1153       mapping between the host ports and the exposed ports, use podman port.
1154
1155
1156   --pull=missing
1157       Pull image before creating ("always"|"missing"|"never") (default "miss‐
1158       ing").
1159              'missing':  default value, attempt to pull the latest image from
1160       the registries listed in registries.conf if a local image does not  ex‐
1161       ist.Raise  an  error  if the image is not in any listed registry and is
1162       not present locally.
1163              'always': Pull the image from the first registry it is found  in
1164       as  listed in  registries.conf. Raise an error if not found in the reg‐
1165       istries, even if the image is present locally.
1166              'never': do not pull the image from the registry, use  only  the
1167       local version. Raise an error if the image is not present locally.
1168
1169
1170       Defaults to missing.
1171
1172
1173   --quiet, -q
1174       Suppress output information when pulling images
1175
1176
1177   --read-only
1178       Mount the container's root filesystem as read only.
1179
1180
1181       By  default a container will have its root filesystem writable allowing
1182       processes to write files anywhere. By specifying the  --read-only  flag
1183       the  container  will have its root filesystem mounted as read only pro‐
1184       hibiting any writes.
1185
1186
1187   --read-only-tmpfs
1188       If container is running in --read-only mode, then  mount  a  read-write
1189       tmpfs on /run, /tmp, and /var/tmp. The default is true
1190
1191
1192   --replace
1193       If another container with the same name already exists, replace and re‐
1194       move it. The default is false.
1195
1196
1197   --requires=container
1198       Specify one or more requirements.  A requirement is a  dependency  con‐
1199       tainer  that  will be started before this container.  Containers can be
1200       specified by name or ID, with multiple containers  being  separated  by
1201       commas.
1202
1203
1204   --restart=policy
1205       Restart policy to follow when containers exit.  Restart policy will not
1206       take effect if a container is stopped via the  podman  kill  or  podman
1207       stop commands.
1208
1209
1210       Valid values are:
1211
1212
1213no                       : Do not restart containers on exit
1214
1215on-failure[:max_retries]  :  Restart containers when they exit
1216                with a non-0 exit code, retrying indefinitely or until the op‐
1217                tional max_retries count is hit
1218
1219always                    : Restart containers when they exit,
1220                regardless of status, retrying indefinitely
1221
1222unless-stopped           : Identical to always
1223
1224
1225
1226       Please note that restart will not restart containers after a system re‐
1227       boot.   If  this functionality is required in your environment, you can
1228       invoke Podman from a systemd unit file, or create an  init  script  for
1229       whichever  init  system  is  in  use.   To generate systemd unit files,
1230       please see podman generate systemd
1231
1232
1233   --rm
1234       Automatically remove the container when it exits. The default is false.
1235
1236
1237   --rootfs
1238       If specified, the first argument refers to an exploded container on the
1239       file system.
1240
1241
1242       This  is  useful to run a container without requiring any image manage‐
1243       ment, the rootfs of the container is assumed to be managed externally.
1244
1245
1246       Overlay Rootfs Mounts
1247
1248
1249       The :O flag tells Podman to mount the directory from the rootfs path as
1250       storage using the overlay file system. The container processes can mod‐
1251       ify content within the mount point which is  stored  in  the  container
1252       storage in a separate directory. In overlay terms, the source directory
1253       will be the lower, and the container storage directory will be the  up‐
1254       per.  Modifications to the mount point are destroyed when the container
1255       finishes executing, similar to a tmpfs mount point being unmounted.
1256
1257
1258   --sdnotify=container|conmon|ignore
1259       Determines how to use the NOTIFY_SOCKET, as  passed  with  systemd  and
1260       Type=notify.
1261
1262
1263       Default  is  container,  which means allow the OCI runtime to proxy the
1264       socket into the container to receive ready  notification.  Podman  will
1265       set  the  MAINPID  to  conmon's pid.  The conmon option sets MAINPID to
1266       conmon's pid, and sends READY  when  the  container  has  started.  The
1267       socket is never passed to the runtime or the container.  The ignore op‐
1268       tion removes NOTIFY_SOCKET from the environment for  itself  and  child
1269       processes,  for the case where some other process above Podman uses NO‐
1270       TIFY_SOCKET and Podman should not use it.
1271
1272
1273   --seccomp-policy=policy
1274       Specify the policy to select the seccomp profile. If set to image, Pod‐
1275       man  will  look for a "io.containers.seccomp.profile" label in the con‐
1276       tainer-image config and use its value as a seccomp profile.  Otherwise,
1277       Podman  will  follow the default policy by applying the default profile
1278       unless specified otherwise via --security-opt seccomp as described  be‐
1279       low.
1280
1281
1282       Note that this feature is experimental and may change in the future.
1283
1284
1285   --secret=secret[,opt=opt ...]
1286       Give the container access to a secret. Can be specified multiple times.
1287
1288
1289       A secret is a blob of sensitive data which a container needs at runtime
1290       but should not be stored in the image or in  source  control,  such  as
1291       usernames  and  passwords, TLS certificates and keys, SSH keys or other
1292       important generic strings or binary content (up to 500 kb in size).
1293
1294
1295       When secrets are specified as type mount, the secrets  are  copied  and
1296       mounted  into  the container when a container is created.  When secrets
1297       are specified as type env, the secret will be  set  as  an  environment
1298       variable within the container.  Secrets are written in the container at
1299       the time of container creation, and modifying the secret  using  podman
1300       secret  commands after the container is created will not affect the se‐
1301       cret inside the container.
1302
1303
1304       Secrets and its storage are managed using the podman secret command.
1305
1306
1307       Secret Options
1308
1309
1310type=mount|env    : How the secret will be exposed to the con‐
1311                tainer. Default mount.
1312
1313target=target     : Target of secret. Defaults to secret name.
1314
1315uid=0             : UID of secret. Defaults to 0. Mount secret
1316                type only.
1317
1318gid=0             : GID of secret. Defaults to 0. Mount secret
1319                type only.
1320
1321mode=0             :  Mode  of secret. Defaults to 0444. Mount
1322                secret type only.
1323
1324
1325
1326   --security-opt=option
1327       Security Options
1328
1329
1330apparmor=unconfined : Turn off apparmor  confinement  for  the
1331                container
1332
1333apparmor=your-profile  :  Set the apparmor confinement profile
1334                for the container
1335
1336label=user:USER     : Set the label  user  for  the  container
1337                processes
1338
1339label=role:ROLE      :  Set  the  label role for the container
1340                processes
1341
1342label=type:TYPE     : Set the label process type for the  con‐
1343                tainer processes
1344
1345label=level:LEVEL    :  Set  the label level for the container
1346                processes
1347
1348label=filetype:TYPE : Set the label file  type  for  the  con‐
1349                tainer files
1350
1351label=disable        :  Turn off label separation for the con‐
1352                tainer
1353
1354
1355
1356       Note: Labeling can be  disabled  for  all  containers  by  setting  la‐
1357       bel=false  in  the  containers.conf (/etc/containers/containers.conf or
1358       $HOME/.config/containers/containers.conf) file.
1359
1360
1361mask=/path/1:/path/2 : The paths to mask separated by a colon.
1362                A masked path cannot be accessed inside the container.
1363
1364no-new-privileges  :  Disable container processes from gaining
1365                additional privileges
1366
1367seccomp=unconfined : Turn off seccomp confinement for the con‐
1368                tainer.
1369
1370seccomp=profile.json  : JSON file to be used as a seccomp fil‐
1371                ter. Note that the io.podman.annotations.seccomp annotation is
1372                set with the specified value as shown in podman inspect.
1373
1374proc-opts=OPTIONS : Comma-separated list of options to use for
1375                the /proc mount. More details for the possible  mount  options
1376                are specified in the proc(5) man page.
1377
1378unmask=ALL   or   /path/1:/path/2,  or  shell  expanded  paths
1379                (/proc/*): Paths to unmask separated by a  colon.  If  set  to
1380                ALL, it will unmask all the paths that are masked or made read
1381                only by default.  The default  masked  paths  are  /proc/acpi,
1382                /proc/kcore,  /proc/keys, /proc/latency_stats, /proc/sched_de‐
1383                bug,    /proc/scsi,    /proc/timer_list,    /proc/timer_stats,
1384                /sys/firmware,  and  /sys/fs/selinux.   The default paths that
1385                are  read  only   are   /proc/asound,   /proc/bus,   /proc/fs,
1386                /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup.
1387
1388
1389
1390       Note:  Labeling  can  be  disabled  for  all  containers by setting la‐
1391       bel=false in the  containers.conf  (/etc/containers/containers.conf  or
1392       $HOME/.config/containers/containers.conf) file.
1393
1394
1395   --shm-size=size
1396       Size  of  /dev/shm (format: <number>[<unit>], where unit = b (bytes), k
1397       (kibibytes), m (mebibytes), or g (gibibytes)) If you omit the unit, the
1398       system  uses bytes. If you omit the size entirely, the system uses 64m.
1399       When size is 0, there is no limit on the amount of memory used for  IPC
1400       by the container.
1401
1402
1403   --stop-signal=SIGTERM
1404       Signal to stop a container. Default is SIGTERM.
1405
1406
1407   --stop-timeout=seconds
1408       Timeout  (in  seconds) to stop a container. Default is 10.  Remote con‐
1409       nections use local containers.conf for defaults
1410
1411
1412   --subgidname=name
1413       Name for GID map from the /etc/subgid file. Using this  flag  will  run
1414       the  container  with  user  namespace enabled. This flag conflicts with
1415       --userns and --gidmap.
1416
1417
1418   --subuidname=name
1419       Name for UID map from the /etc/subuid file. Using this  flag  will  run
1420       the  container  with  user  namespace enabled. This flag conflicts with
1421       --userns and --uidmap.
1422
1423
1424   --sysctl=SYSCTL
1425       Configure namespaced kernel parameters at runtime
1426
1427
1428       IPC Namespace - current sysctls allowed:
1429
1430
1431       kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall,
1432       kernel.shmmax,  kernel.shmmni, kernel.shm_rmid_forced Sysctls beginning
1433       with fs.mqueue.*
1434
1435
1436       Note: if you use the --ipc=host option these sysctls will  not  be  al‐
1437       lowed.
1438
1439
1440       Network Namespace - current sysctls allowed:
1441           Sysctls beginning with net.*
1442
1443
1444       Note:  if  you  use the --network=host option these sysctls will not be
1445       allowed.
1446
1447
1448   --systemd=true|false|always
1449       Run container in systemd mode. The default is true.
1450
1451
1452       The value always enforces the systemd mode is enforced without  looking
1453       at  the  executable name. Otherwise, if set to true and the command you
1454       are running inside the container is systemd, /usr/sbin/init, /sbin/init
1455       or /usr/local/sbin/init.
1456
1457
1458       Running the container in systemd mode causes the following changes:
1459
1460
1461              • Podman mounts tmpfs file systems on the following directories
1462
1463/run
1464
1465/run/lock
1466
1467/tmp
1468
1469/sys/fs/cgroup/systemd
1470
1471/var/lib/journal
1472
1473
1474
1475              • Podman sets the default stop signal to SIGRTMIN+3.
1476
1477              • Podman  sets  container_uuid  environment variable in the con‐
1478                tainer to the first 32 characters of the container id.
1479
1480
1481
1482       This allows systemd to run in a confined container without any  modifi‐
1483       cations.
1484
1485
1486       Note:  On SELinux systems, systemd attempts to write to the cgroup file
1487       system. Containers writing to the cgroup file system are denied by  de‐
1488       fault.  The container_manage_cgroup boolean must be enabled for this to
1489       be allowed on an SELinux separated system.
1490
1491
1492       setsebool -P container_manage_cgroup true
1493
1494
1495   --timeout=seconds
1496       Maximum time a container is allowed to run before conmon sends  it  the
1497       kill  signal.   By  default  containers will run until they exit or are
1498       stopped by podman stop.
1499
1500
1501   --tls-verify
1502       Require HTTPS and verify certificates when contacting  registries  (de‐
1503       fault:  true). If explicitly set to true, then TLS verification will be
1504       used. If set to false, then TLS verification will not be used.  If  not
1505       specified,  TLS verification will be used unless the target registry is
1506       listed as an insecure registry in registries.conf.
1507
1508
1509   --tmpfs=fs
1510       Create a tmpfs mount
1511
1512
1513       Mount a temporary filesystem (tmpfs) mount into a container, for  exam‐
1514       ple:
1515
1516
1517       $ podman create -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
1518
1519
1520       This command mounts a tmpfs at /tmp within the container. The supported
1521       mount options are the same as the Linux default mount flags. If you  do
1522       not  specify  any  options,  the  systems  uses  the following options:
1523       rw,noexec,nosuid,nodev.
1524
1525
1526   --tty, -t
1527       Allocate a pseudo-TTY. The default is false.
1528
1529
1530       When set to true Podman will allocate a pseudo-tty and  attach  to  the
1531       standard  input of the container. This can be used, for example, to run
1532       a throwaway interactive shell. The default is false.
1533
1534
1535       Note: The -t option is incompatible with a redirection  of  the  Podman
1536       client standard input.
1537
1538
1539   --tz=timezone
1540       Set  timezone  in  container. This flag takes area-based timezones, GMT
1541       time, as well as local, which sets the timezone  in  the  container  to
1542       match  the  host machine. See /usr/share/zoneinfo/ for valid timezones.
1543       Remote connections use local containers.conf for defaults
1544
1545
1546   --uidmap=container_uid:from_uid:amount
1547       Run the container in a new user namespace using the  supplied  mapping.
1548       This  option conflicts with the --userns and --subuidname options. This
1549       option provides a way to map host UIDs to container  UIDs.  It  can  be
1550       passed several times to map different ranges.
1551
1552
1553       The  _fromuid  value is based upon the user running the command, either
1554       rootful    or    rootless    users.     *    rootful    user:      con‐
1555       tainer_uid:host_uid:amount  *  rootless  user: container_uid:intermedi‐
1556       ate_uid:amount
1557
1558
1559       When podman create is called by a privileged user, the option  --uidmap
1560       works as a direct mapping between host UIDs and container UIDs.
1561
1562
1563       host UID -> container UID
1564
1565
1566       The  amount  specifies  the  number  of  consecutive  UIDs that will be
1567       mapped.  If for example amount is 4 the mapping would look like:
1568
1569
1570       |    host  UID      |     container  UID     |  |  -               |  -
1571       | | _fromuid     | _containeruid     | | _fromuid + 1 | _containeruid +
1572       1 | | _fromuid + 2 | _containeruid + 2 | | _fromuid + 3 | _containeruid
1573       + 3 |
1574
1575
1576       When  podman  create  is  called  by an unprivileged user (i.e. running
1577       rootless), the value _fromuid is interpreted as an "intermediate  UID".
1578       In  the  rootless  case, host UIDs are not mapped directly to container
1579       UIDs. Instead the mapping happens over two mapping steps:
1580
1581
1582       host UID -> intermediate UID -> container UID
1583
1584
1585       The --uidmap option only influences the second mapping step.
1586
1587
1588       The first mapping step is derived by Podman from the  contents  of  the
1589       file /etc/subuid and the UID of the user calling Podman.
1590
1591
1592       First mapping step:
1593
1594
1595       | host UID                                         | intermediate UID |
1596       | -                                                |                - |
1597       | UID for the user starting Podman                 |                0 |
1598       | 1st subordinate UID for the user starting Podman |                1 |
1599       | 2nd subordinate UID for the user starting Podman |                2 |
1600       | 3rd subordinate UID for the user starting Podman |                3 |
1601       | nth subordinate UID for the user starting Podman |                n |
1602
1603
1604       To  be  able to use intermediate UIDs greater than zero, the user needs
1605       to have subordinate UIDs configured in /etc/subuid. See subuid(5).
1606
1607
1608       The second mapping step is configured with --uidmap.
1609
1610
1611       If for example amount is 5 the second mapping step would look like:
1612
1613
1614       |   intermediate UID   |    container UID    | | -                    |
1615       -                    |  |  _fromuid            |  _containeruid     | |
1616       _fromuid + 1       | _containeruid + 1 | | _fromuid + 2        |  _con‐
1617       taineruid + 2 | | _fromuid + 3       | _containeruid + 3 | | _fromuid +
1618       4       | _containeruid + 4 |
1619
1620
1621       The current user ID is mapped to UID=0 in the rootless user  namespace.
1622       Every additional range is added sequentially afterward:
1623
1624
1625       |      host                   |rootless   user   namespace   |   length
1626       |   |    -                        |    -                         |    -
1627       |    |    $UID                     |    0                         |   1
1628       |    |     1                         |     $FIRST_RANGE_ID            |
1629       $FIRST_RANGE_LENGTH   |   |  1+$FIRST_RANGE_LENGTH  |  $SECOND_RANGE_ID
1630       | $SECOND_RANGE_LENGTH|
1631
1632
1633       Even if a user does not have  any  subordinate  UIDs  in   /etc/subuid,
1634       --uidmap  could  still  be  used to map the normal UID of the user to a
1635       container UID by  running  podman  create  --uidmap  $container_uid:0:1
1636       --user $container_uid ....
1637
1638
1639       Note:  the --uidmap flag cannot be called in conjunction with the --pod
1640       flag as a uidmap cannot be set on the container level when in a pod.
1641
1642
1643   --ulimit=option
1644       Ulimit options
1645
1646
1647       You can pass host to copy the current configuration from the host.
1648
1649
1650   --umask=umask
1651       Set the umask inside the container. Defaults to 0022.   Remote  connec‐
1652       tions use local containers.conf for defaults
1653
1654
1655   --unsetenv=env
1656       Unset default environment variables for the container. Default environ‐
1657       ment variables include variables provided natively by Podman,  environ‐
1658       ment  variables configured by the image, and environment variables from
1659       containers.conf.
1660
1661
1662   --unsetenv-all=true|false
1663       Unset all default environment variables for the container. Default  en‐
1664       vironment  variables include variables provided natively by Podman, en‐
1665       vironment variables configured by the image, and environment  variables
1666       from containers.conf.
1667
1668
1669   --user, -u=user
1670       Sets  the  username or UID used and optionally the groupname or GID for
1671       the specified command.
1672
1673
1674       The following examples are all valid: --user [user | user:group | uid |
1675       uid:gid | user:gid | uid:group ]
1676
1677
1678       Without this argument the command will be run as root in the container.
1679
1680
1681   --userns=mode
1682       Set  the user namespace mode for the container. It defaults to the POD‐
1683       MAN_USERNS environment variable. An empty value ("") means  user  name‐
1684       spaces are disabled unless an explicit mapping is set with the --uidmap
1685       and --gidmap options.
1686
1687
1688       Rootless user --userns=Key mappings:
1689
1690
1691       ┌────────┬───────────┬─────────────────────┐
1692Key     Host User Container User      
1693       ├────────┼───────────┼─────────────────────┤
1694       │""      │ $UID      │ 0 (Default User ac‐ │
1695       │        │           │ count   mapped   to │
1696       │        │           │ root user  in  con‐ │
1697       │        │           │ tainer.)            │
1698       ├────────┼───────────┼─────────────────────┤
1699       │keep-id │ $UID      │ $UID  (Map user ac‐ │
1700       │        │           │ count to  same  UID │
1701       │        │           │ within container.)  │
1702       ├────────┼───────────┼─────────────────────┤
1703       │auto    │ $UID      │ nil  (Host User UID │
1704       │        │           │ is not mapped  into │
1705       │        │           │ container.)         │
1706       ├────────┼───────────┼─────────────────────┤
1707       │nomap   │ $UID      │ nil  (Host User UID │
1708       │        │           │ is not mapped  into │
1709       │        │           │ container.)         │
1710       └────────┴───────────┴─────────────────────┘
1711
1712       Valid mode values are:
1713
1714
1715       auto[:OPTIONS,...]: automatically create a unique user namespace.
1716
1717
1718       The  --userns=auto  flag,  requires that the user name containers and a
1719       range of subordinate user ids that the Podman container is  allowed  to
1720       use be specified in the /etc/subuid and /etc/subgid files.
1721
1722
1723       Example: containers:2147483647:2147483648.
1724
1725
1726       Podman  allocates  unique  ranges  of UIDs and GIDs from the containers
1727       subordinate user ids. The size of the ranges is based on the number  of
1728       UIDs required in the image. The number of UIDs and GIDs can be overrid‐
1729       den with the size option. The auto options currently does not  work  in
1730       rootless mode
1731
1732
1733       Valid auto options:
1734
1735
1736gidmapping=_CONTAINER_GID:HOSTGID:SIZE: to force a GID mapping
1737                to be present in the user namespace.
1738
1739size=SIZE: to specify an explicit size for the automatic  user
1740                namespace. e.g. --userns=auto:size=8192. If size is not speci‐
1741                fied, auto will estimate a size for the user namespace.
1742
1743uidmapping=_CONTAINER_UID:HOSTUID:SIZE: to force a UID mapping
1744                to be present in the user namespace.
1745
1746
1747
1748       container:id: join the user namespace of the specified container.
1749
1750
1751       host: run in the user namespace of the caller. The processes running in
1752       the container will have the same privileges on the host  as  any  other
1753       process launched by the calling user (default).
1754
1755
1756       keep-id:  creates  a  user  namespace where the current rootless user's
1757       UID:GID are mapped to the same values in the container. This option  is
1758       ignored for containers created by the root user.
1759
1760
1761       nomap:  creates  a  user  namespace  where  the current rootless user's
1762       UID:GID are not mapped into the container. This option is  ignored  for
1763       containers created by the root user.
1764
1765
1766       ns:namespace: run the container in the given existing user namespace.
1767
1768
1769       private: create a new namespace for the container.
1770
1771
1772       This  option  is incompatible with --gidmap, --uidmap, --subuidname and
1773       --subgidname.
1774
1775
1776   --uts=mode
1777       Set the UTS namespace mode for the container. The following values  are
1778       supported:
1779
1780
1781host: use the host's UTS namespace inside the container.
1782
1783private: create a new namespace for the container (default).
1784
1785ns:[path]:  run  the container in the given existing UTS name‐
1786                space.
1787
1788container:[container]: join the UTS namespace of the specified
1789                container.
1790
1791
1792
1793   --variant=VARIANT
1794       Use  VARIANT  instead  of  the default architecture variant of the con‐
1795       tainer image. Some images can use multiple variants of the  arm  archi‐
1796       tectures, such as arm/v5 and arm/v7.
1797
1798
1799   --volume, -v[=[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]]
1800       Create  a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR, Pod‐
1801       man bind mounts /HOST-DIR in the host to /CONTAINER-DIR in  the  Podman
1802       container.  Similarly,  -v  SOURCE-VOLUME:/CONTAINER-DIR will mount the
1803       volume in the host to the container. If no such  named  volume  exists,
1804       Podman  will create one. The OPTIONS are a comma-separated list and can
1805       be: [1] ⟨#Footnote1⟩  (Note when using the remote client, including Mac
1806       and Windows (excluding WSL2) machines, the volumes will be mounted from
1807       the remote server, not necessarily the client machine.)
1808
1809
1810       The options is a comma-separated list and can be:
1811
1812
1813rw|ro
1814
1815z|Z
1816
1817              • [r]shared|[r]slave|[r]private[r]unbindable
1818
1819              • [r]bind
1820
1821              • [no]exec
1822
1823              • [no]dev
1824
1825              • [no]suid
1826
1827              • [O]
1828
1829              • [U]
1830
1831
1832
1833       The CONTAINER-DIR must be an absolute path such as /src/docs. The  vol‐
1834       ume will be mounted into the container at this directory.
1835
1836
1837       Volumes may specify a source as well, as either a directory on the host
1838       or the name of a named volume. If no source is given, the  volume  will
1839       be  created  as  an  anonymously named volume with a randomly generated
1840       name, and will be removed when the container is removed  via  the  --rm
1841       flag or podman rm --volumes.
1842
1843
1844       If  a  volume source is specified, it must be a path on the host or the
1845       name of a named volume. Host paths are allowed to be absolute or  rela‐
1846       tive;  relative  paths are resolved relative to the directory Podman is
1847       run in. If the source does not exist,  Podman  will  return  an  error.
1848       Users must pre-create the source files or directories.
1849
1850
1851       Any  source  that  does  not begin with a . or / will be treated as the
1852       name of a named volume. If a volume with that name does not  exist,  it
1853       will  be  created.   Volumes  created with names are not anonymous, and
1854       they are not removed by the --rm option and  the  podman  rm  --volumes
1855       command.
1856
1857
1858       You  can specify multiple  -v options to mount one or more volumes into
1859       a container.
1860
1861
1862       Write Protected Volume Mounts
1863
1864
1865       You can add :ro or :rw suffix to a volume  to  mount  it  read-only  or
1866       read-write  mode,  respectively.  By  default,  the volumes are mounted
1867       read-write.  See examples.
1868
1869
1870       Chowning Volume Mounts
1871
1872
1873       By default, Podman does not change the owner and group of source volume
1874       directories mounted into containers. If a container is created in a new
1875       user namespace, the UID and GID in the container may correspond to  an‐
1876       other UID and GID on the host.
1877
1878
1879       The :U suffix tells Podman to use the correct host UID and GID based on
1880       the UID and GID within the container, to change recursively  the  owner
1881       and group of the source volume.
1882
1883
1884       Warning use with caution since this will modify the host filesystem.
1885
1886
1887       Labeling Volume Mounts
1888
1889
1890       Labeling  systems like SELinux require that proper labels are placed on
1891       volume content mounted into a container. Without a label, the  security
1892       system  might  prevent  the processes running inside the container from
1893       using the content. By default, Podman does not change the labels set by
1894       the OS.
1895
1896
1897       To  change  a label in the container context, you can add either of two
1898       suffixes :z or :Z to the volume mount. These suffixes  tell  Podman  to
1899       relabel  file  objects on the shared volumes. The z option tells Podman
1900       that two containers share the volume content. As a result,  Podman  la‐
1901       bels  the content with a shared content label. Shared volume labels al‐
1902       low all containers to read/write content.  The Z option tells Podman to
1903       label the content with a private unshared label.  Only the current con‐
1904       tainer can use a private volume.
1905
1906
1907       Note: Do not relabel system files and  directories.  Relabeling  system
1908       content  might  cause  other confined services on your machine to fail.
1909       For these types of containers we recommend  disabling  SELinux  separa‐
1910       tion.  The option --security-opt label=disable disables SELinux separa‐
1911       tion for containers used in the build.  For example if a user wanted to
1912       volume mount their entire home directory into a container, they need to
1913       disable SELinux separation.
1914
1915
1916                 $ podman create --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/file
1917
1918
1919
1920       Overlay Volume Mounts
1921
1922
1923       The :O flag tells Podman to mount the directory from the host as a tem‐
1924       porary  storage  using the overlay file system. The container processes
1925       can modify content within the mountpoint which is stored  in  the  con‐
1926       tainer  storage  in  a separate directory. In overlay terms, the source
1927       directory will be the lower, and the container storage  directory  will
1928       be  the  upper. Modifications to the mount point are destroyed when the
1929       container finishes executing, similar to a tmpfs mount point being  un‐
1930       mounted.
1931
1932
1933       Subsequent executions of the container will see the original source di‐
1934       rectory content, any changes  from  previous  container  executions  no
1935       longer exist.
1936
1937
1938       One use case of the overlay mount is sharing the package cache from the
1939       host into the container to allow speeding up builds.
1940
1941
1942       Note:
1943
1944
1945               - The `O` flag conflicts with other options listed above.
1946
1947
1948
1949       Content mounted into the container is labeled with the private label.
1950              On SELinux systems, labels in the source directory must be read‐
1951       able  by  the container label. Usually containers can read/execute con‐
1952       tainer_share_t and  can  read/write  container_file_t.  If  you  cannot
1953       change the labels on a source volume, SELinux container separation must
1954       be disabled for the container to work.
1955            - The source directory mounted into the container with an  overlay
1956       mount  should  not be modified, it can cause unexpected failures. It is
1957       recommended that you do not modify the directory  until  the  container
1958       finishes running.
1959
1960
1961       Mounts propagation
1962
1963
1964       By default bind mounted volumes are private. That means any mounts done
1965       inside container will not be visible on host and vice  versa.  One  can
1966       change this behavior by specifying a volume mount propagation property.
1967       Making a volume shared mounts done under that volume  inside  container
1968       will  be  visible on host and vice versa. Making a volume slave enables
1969       only one way mount propagation and that is mounts done  on  host  under
1970       that  volume  will  be  visible  inside container but not the other way
1971       around. [1] ⟨#Footnote1⟩
1972
1973
1974       To control mount propagation property of  a  volume  one  can  use  the
1975       [r]shared,  [r]slave, [r]private or the [r]unbindable propagation flag.
1976       For mount propagation to work the source mount point (the  mount  point
1977       where source dir is mounted on) has to have the right propagation prop‐
1978       erties. For shared volumes, the source mount point has  to  be  shared.
1979       And  for  slave volumes, the source mount point has to be either shared
1980       or slave. [1] ⟨#Footnote1⟩
1981
1982
1983       If you want to recursively mount a volume and all of its submounts into
1984       a container, then you can use the rbind option. By default the bind op‐
1985       tion is used, and submounts of the source directory will not be mounted
1986       into the container.
1987
1988
1989       Mounting  the  volume  with the nosuid options means that SUID applica‐
1990       tions on the volume will not be able to change their privilege. By  de‐
1991       fault volumes are mounted with nosuid.
1992
1993
1994       Mounting the volume with the noexec option means that no executables on
1995       the volume will be able to be executed within the container.
1996
1997
1998       Mounting the volume with the nodev option means that no devices on  the
1999       volume  will  be  able to be used by processes within the container. By
2000       default volumes are mounted with nodev.
2001
2002
2003       If the <source-dir> is a mount point, then "dev",  "suid",  and  "exec"
2004       options are ignored by the kernel.
2005
2006
2007       Use df <source-dir> to figure out the source mount and then use findmnt
2008       -o TARGET,PROPAGATION  <source-mount-dir>  to  figure  out  propagation
2009       properties  of  source mount. If findmnt utility is not available, then
2010       one  can  look   at   mount   entry   for   source   mount   point   in
2011       /proc/self/mountinfo.  Look  at optional fields and see if any propaga‐
2012       tion properties are specified.  shared:X means mount  is  shared,  mas‐
2013       ter:X  means mount is slave and if nothing is there that means mount is
2014       private. [1] ⟨#Footnote1⟩
2015
2016
2017       To change propagation properties of a mount point  use  mount  command.
2018       For  example,  if one wants to bind mount source directory /foo one can
2019       do mount --bind /foo /foo and mount --make-private --make-shared  /foo.
2020       This will convert /foo into a shared mount point. Alternatively one can
2021       directly change propagation properties of source mount. Say / is source
2022       mount  for  /foo,  then  use  mount --make-shared / to convert / into a
2023       shared mount.
2024
2025
2026       Note: if the user only has access rights via  a  group,  accessing  the
2027       volume  from inside a rootless container will fail. Use the --group-add
2028       keep-groups flag to pass the user's supplementary group access into the
2029       container.
2030
2031
2032   --volumes-from[=CONTAINER[:OPTIONS]]
2033       Mount  volumes  from  the specified container(s). Used to share volumes
2034       between containers. The options is a comma-separated list with the fol‐
2035       lowing available elements:
2036
2037
2038rw|ro
2039
2040z
2041
2042
2043
2044       Mounts  already  mounted  volumes  from a source container onto another
2045       container. You must supply the source's container-id or container-name.
2046       To  share a volume, use the --volumes-from option when running the tar‐
2047       get container. You can share volumes even if the  source  container  is
2048       not running.
2049
2050
2051       By  default,  Podman mounts the volumes in the same mode (read-write or
2052       read-only) as it is mounted in the source container.   You  can  change
2053       this by adding a ro or rw option.
2054
2055
2056       Labeling  systems like SELinux require that proper labels are placed on
2057       volume content mounted into a container. Without a label, the  security
2058       system  might  prevent  the processes running inside the container from
2059       using the content. By default, Podman does not change the labels set by
2060       the OS.
2061
2062
2063       To change a label in the container context, you can add z to the volume
2064       mount.  This suffix tells Podman to relabel file objects on the  shared
2065       volumes. The z option tells Podman that two containers share the volume
2066       content. As a result, Podman labels the content with a  shared  content
2067       label. Shared volume labels allow all containers to read/write content.
2068
2069
2070       If  the  location of the volume from the source container overlaps with
2071       data residing on a target container, then the volume hides that data on
2072       the target.
2073
2074
2075   --workdir, -w=dir
2076       Working directory inside the container
2077
2078
2079       The  default  working directory for running binaries within a container
2080       is the root directory (/).  The image developer can set a different de‐
2081       fault with the WORKDIR instruction. The operator can override the work‐
2082       ing directory by using the -w option.
2083
2084

EXAMPLES

2086   Create a container using a local image
2087              $ podman create alpine ls
2088
2089
2090
2091   Create a container using a local image and annotate it
2092              $ podman create --annotation HELLO=WORLD alpine ls
2093
2094
2095
2096   Create a container using a local image, allocating  a  pseudo-TTY,  keeping
2097       stdin open and name it myctr
2098                podman create -t -i --name myctr alpine ls
2099
2100
2101
2102   Set UID/GID mapping in a new user namespace
2103       Running  a  container in a new user namespace requires a mapping of the
2104       uids and gids from the host.
2105
2106
2107              $ podman create --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
2108
2109
2110
2111   Setting automatic user namespace separated containers
2112              # podman create --userns=auto:size=65536 ubi8-init
2113
2114
2115
2116   Configure timezone in a container
2117              $ podman create --tz=local alpine date
2118              $ podman create --tz=Asia/Shanghai alpine date
2119              $ podman create --tz=US/Eastern alpine date
2120
2121
2122
2123   Adding dependency containers
2124       Podman will make sure the first container, container1, is  running  be‐
2125       fore the second container (container2) is started.
2126
2127
2128              $ podman create --name container1 -t -i fedora bash
2129              $ podman create --name container2 --requires container1 -t -i fedora bash
2130              $ podman start --attach container2
2131
2132
2133
2134       Multiple containers can be required.
2135
2136
2137              $ podman create --name container1 -t -i fedora bash
2138              $ podman create --name container2 -t -i fedora bash
2139              $ podman create --name container3 --requires container1,container2 -t -i fedora bash
2140              $ podman start --attach container3
2141
2142
2143
2144   Configure keep supplemental groups for access to volume
2145              $ podman create -v /var/lib/design:/var/lib/design --group-add keep-groups ubi8
2146
2147
2148
2149   Configure execution domain for containers using personality flag
2150              $ podman create --name container1 --personaity=LINUX32 fedora bash
2151
2152
2153
2154   Create a container with external rootfs mounted as an overlay
2155              $ podman create --name container1 --rootfs /path/to/rootfs:O bash
2156
2157
2158
2159   Create  a container connected to two networks (called net1 and net2) with a
2160       static ip
2161              $ podman create --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip addr
2162
2163
2164
2165   Rootless Containers
2166       Podman runs as a non-root user on most systems. This  feature  requires
2167       that  a  new  enough  version of shadow-utils be installed. The shadow-
2168       utils package must include the newuidmap and newgidmap executables.
2169
2170
2171       In order for users to run rootless, there must be an  entry  for  their
2172       username  in /etc/subuid and /etc/subgid which lists the UIDs for their
2173       user namespace.
2174
2175
2176       Rootless Podman works better  if  the  fuse-overlayfs  and  slirp4netns
2177       packages   are   installed.   The  fuse-overlayfs  package  provides  a
2178       userspace overlay storage driver, otherwise users need to use  the  vfs
2179       storage driver, which is diskspace expensive and does not perform well.
2180       slirp4netns is required for VPN, without it containers need to  be  run
2181       with the --network=host flag.
2182
2183

ENVIRONMENT

2185       Environment  variables within containers can be set using multiple dif‐
2186       ferent options:  This section describes the precedence.
2187
2188
2189       Precedence order (later entries override earlier entries):
2190
2191
2192--env-host : Host environment of the process executing  Podman
2193                is added.
2194
2195--http-proxy:  By  default, several environment variables will
2196                be passed in from the host, such as http_proxy  and  no_proxy.
2197                See --http-proxy for details.
2198
2199              • Container  image  : Any environment variables specified in the
2200                container image.
2201
2202--env-file : Any  environment  variables  specified  via  env-
2203                files.  If  multiple  files specified, then they override each
2204                other in order of entry.
2205
2206--env : Any environment variables specified will override pre‐
2207                vious settings.
2208
2209
2210
2211       Create containers and set the environment ending with a * and a *****
2212
2213
2214              $ export ENV1=a
2215              $ podman create --name ctr --env ENV* alpine printenv ENV1
2216              $ podman start --attach ctr
2217              a
2218
2219              $ podman create --name ctr --env ENV*****=b alpine printenv ENV*****
2220              $ podman start --attach ctr
2221              b
2222
2223
2224

CONMON

2226       When Podman starts a container it actually executes the conmon program,
2227       which then executes the OCI Runtime.  Conmon is the container  monitor.
2228       It  is a small program whose job is to watch the primary process of the
2229       container, and if the container dies, save  the  exit  code.   It  also
2230       holds  open  the  tty  of  the container, so that it can be attached to
2231       later. This is what allows  Podman  to  run  in  detached  mode  (back‐
2232       grounded),  so  Podman can exit but conmon continues to run.  Each con‐
2233       tainer has their own instance of conmon. Conmon waits for the container
2234       to  exit,  gathers  and saves the exit code, and then launches a Podman
2235       process to complete the container cleanup, by shutting down the network
2236       and  storage.    For  more  information on conmon, please reference the
2237       conmon(8) man page.
2238
2239

FILES

2241       /etc/subuid /etc/subgid
2242
2243
2244       NOTE: Use the environment variable TMPDIR to change the temporary stor‐
2245       age  location  of  downloaded  container images. Podman defaults to use
2246       /var/tmp.
2247
2248

SEE ALSO

2250       podman(1), podman-save(1), podman-ps(1), podman-attach(1),  podman-pod-
2251       create(1),  podman-port(1),  podman-start(1),  podman-kill(1),  podman-
2252       stop(1),  podman-generate-systemd(1),  podman-rm(1),  subgid(5),   sub‐
2253       uid(5),      containers.conf(5),     systemd.unit(5),     setsebool(8),
2254       slirp4netns(1), fuse-overlayfs(1), proc(5), conmon(8), personality(2)
2255
2256

HISTORY

2258       October 2017, converted from Docker  documentation  to  Podman  by  Dan
2259       Walsh for Podman <dwalsh@redhat.com>
2260
2261
2262       November 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2263
2264
2265       September 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2266
2267
2268       August 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2269
2270

FOOTNOTES

2272       1: The Podman project is committed to inclusivity, a core value of open
2273       source. The master and slave mount propagation terminology used here is
2274       problematic  and  divisive, and should be changed. However, these terms
2275       are currently used within the Linux kernel and must be  used  as-is  at
2276       this  time. When the kernel maintainers rectify this usage, Podman will
2277       follow suit immediately.
2278
2279
2280
2281                                                            podman-create(1)()
Impressum