1podman-run(1)()                                                podman-run(1)()
2
3
4

NAME

6       podman-run - Run a command in a new container
7
8

SYNOPSIS

10       podman run [options] image [command [arg ...]]
11
12
13       podman container run [options] image [command [arg ...]]
14
15

DESCRIPTION

17       Run  a process in a new container. podman run starts a process with its
18       own file system, its own networking, and its own isolated process tree.
19       The  image  which starts the process may define defaults related to the
20       process that will be run in the container, the  networking  to  expose,
21       and  more, but podman run gives final control to the operator or admin‐
22       istrator who starts the container from the image. For that reason  pod‐
23       man run has more options than any other Podman command.
24
25
26       If the image is not already loaded then podman run will pull the image,
27       and all image dependencies, from the repository in the same way running
28       podman pull image , before it starts the container from that image.
29
30
31       Several files will be automatically created within the container. These
32       include /etc/hosts, /etc/hostname, and /etc/resolv.conf to manage  net‐
33       working.   These  will  be  based  on  the host's version of the files,
34       though they can be customized with options  (for  example,  --dns  will
35       override  the host's DNS servers in the created resolv.conf). Addition‐
36       ally, a container environment file is created in each container to  in‐
37       dicate  to  programs  they are running in a container. This file is lo‐
38       cated at /run/.containerenv. When using the --privileged flag the .con‐
39       tainerenv  contains  name/value  pairs  indicating the container engine
40       version, whether the engine is running in rootless mode, the  container
41       name  and  id,  as  well as the image name and id that the container is
42       based on.
43
44
45       When   running   from   a   user   defined   network   namespace,   the
46       /etc/netns/NSNAME/resolv.conf  will  be  used  if  it exists, otherwise
47       /etc/resolv.conf will be used.
48
49
50       Default settings are defined in containers.conf. Most settings for  re‐
51       mote  connections  use  the  servers containers.conf, except when docu‐
52       mented in man pages.
53
54

IMAGE

56       The image is specified using transport:path format. If no transport  is
57       specified,  the  docker  (container registry) transport will be used by
58       default. For remote Podman, including Mac and Windows (excluding  WSL2)
59       machines, docker is the only allowed transport.
60
61
62       dir:path
63         An existing local directory path storing the manifest, layer tarballs
64       and signatures as individual files. This is a non-standardized  format,
65       primarily useful for debugging or noninvasive container inspection.
66
67
68              $ podman save --format docker-dir fedora -o /tmp/fedora
69              $ podman run dir:/tmp/fedora echo hello
70
71
72
73       docker://docker-reference (Default)
74         An image reference stored in a remote container image registry. Exam‐
75       ple: "quay.io/podman/stable:latest".  The reference can include a  path
76       to  a  specific registry; if it does not, the registries listed in reg‐
77       istries.conf will be queried to find a  matching  image.   By  default,
78       credentials  from  podman  login  (stored  at $XDG_RUNTIME_DIR/contain‐
79       ers/auth.json by default) will be used to  authenticate;  otherwise  it
80       falls back to using credentials in $HOME/.docker/config.json.
81
82
83              $ podman run registry.fedoraproject.org/fedora:latest echo hello
84
85
86
87       docker-archive:path[:docker-reference]  An  image  stored in the docker
88       save formatted file. docker-reference is only used when creating such a
89       file, and it must not contain a digest.
90
91
92              $ podman save --format docker-archive fedora -o /tmp/fedora
93              $ podman run docker-archive:/tmp/fedora echo hello
94
95
96
97       docker-daemon:docker-reference
98         An  image  in docker-reference format stored in the docker daemon in‐
99       ternal storage. The docker-reference can also be an image  ID  (docker-
100       daemon:algo:digest).
101
102
103              $ sudo docker pull fedora
104              $ sudo podman run docker-daemon:docker.io/library/fedora echo hello
105
106
107
108       oci-archive:path:tag
109         An image in a directory compliant with the "Open Container Image Lay‐
110       out Specification" at the specified path and specified with a tag.
111
112
113              $ podman save --format oci-archive fedora -o /tmp/fedora
114              $ podman run oci-archive:/tmp/fedora echo hello
115
116
117

OPTIONS

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

Exit Status

2228       The exit code from podman run gives information about why the container
2229       failed to run or why it exited. When podman run exits with  a  non-zero
2230       code, the exit codes follow the chroot(1) standard, see below:
2231
2232
2233       125 The error is with Podman itself
2234
2235
2236              $ podman run --foo busybox; echo $?
2237              Error: unknown flag: --foo
2238              125
2239
2240
2241
2242       126 The contained command cannot be invoked
2243
2244
2245              $ podman run busybox /etc; echo $?
2246              Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error
2247              126
2248
2249
2250
2251       127 The contained command cannot be found
2252
2253
2254              $ podman run busybox foo; echo $?
2255              Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error
2256              127
2257
2258
2259
2260       Exit code contained command exit code
2261
2262
2263              $ podman run busybox /bin/sh -c 'exit 3'; echo $?
2264              3
2265
2266
2267

EXAMPLES

2269   Running container in read-only mode
2270       During  container  image development, containers often need to write to
2271       the image content. Installing packages into /usr, for example. In  pro‐
2272       duction, applications seldom need to write to the image.  Container ap‐
2273       plications write to volumes if they need to write to  file  systems  at
2274       all.  Applications can be made more secure by running them in read-only
2275       mode using the --read-only switch.  This protects the containers  image
2276       from  modification. Read only containers may still need to write tempo‐
2277       rary data. The best way to handle this is to mount tmpfs directories on
2278       /run and /tmp.
2279
2280
2281              $ podman run --read-only -i -t fedora /bin/bash
2282
2283              $ podman run --read-only --read-only-tmpfs=false --tmpfs /run -i -t fedora /bin/bash
2284
2285
2286
2287   Exposing log messages from the container to the host's log
2288       If  you  want  messages that are logged in your container to show up in
2289       the host's syslog/journal then you should bind mount the  /dev/log  di‐
2290       rectory as follows.
2291
2292
2293              $ podman run -v /dev/log:/dev/log -i -t fedora /bin/bash
2294
2295
2296
2297       From inside the container you can test this by sending a message to the
2298       log.
2299
2300
2301              (bash)# logger "Hello from my container"
2302
2303
2304
2305       Then exit and check the journal.
2306
2307
2308              (bash)# exit
2309
2310              $ journalctl -b | grep Hello
2311
2312
2313
2314       This should list the message sent to logger.
2315
2316
2317   Attaching to one or more from STDIN, STDOUT, STDERR
2318       If you do not specify -a, Podman will attach everything (stdin, stdout,
2319       stderr).   You  can  specify  to  which  of  the three standard streams
2320       (stdin, stdout, stderr) you'd like to connect instead, as in:
2321
2322
2323              $ podman run -a stdin -a stdout -i -t fedora /bin/bash
2324
2325
2326
2327   Sharing IPC between containers
2328       Using             shm_server.c             available              here:
2329       https://www.cs.cf.ac.uk/Dave/C/node27.html
2330
2331
2332       Testing --ipc=host mode:
2333
2334
2335       Host  shows a shared memory segment with 7 pids attached, happens to be
2336       from httpd:
2337
2338
2339              $ sudo ipcs -m
2340
2341              ------ Shared Memory Segments --------
2342              key        shmid      owner      perms      bytes      nattch     status
2343              0x01128e25 0          root       600        1000       7
2344
2345
2346
2347       Now run a regular container, and it correctly does NOT see  the  shared
2348       memory segment from the host:
2349
2350
2351              $ podman run -it shm ipcs -m
2352
2353              ------ Shared Memory Segments --------
2354              key        shmid      owner      perms      bytes      nattch     status
2355
2356
2357
2358       Run  a  container  with  the new --ipc=host option, and it now sees the
2359       shared memory segment from the host httpd:
2360
2361
2362              $ podman run -it --ipc=host shm ipcs -m
2363
2364              ------ Shared Memory Segments --------
2365              key        shmid      owner      perms      bytes      nattch     status
2366              0x01128e25 0          root       600        1000       7
2367
2368
2369
2370       Testing --ipc=container:id mode:
2371
2372
2373       Start a container with a program to create a shared memory segment:
2374
2375
2376              $ podman run -it shm bash
2377              $ sudo shm/shm_server &
2378              $ sudo ipcs -m
2379
2380              ------ Shared Memory Segments --------
2381              key        shmid      owner      perms      bytes      nattch     status
2382              0x0000162e 0          root       666        27         1
2383
2384
2385
2386       Create a 2nd container correctly shows no shared  memory  segment  from
2387       1st container:
2388
2389
2390              $ podman run shm ipcs -m
2391
2392              ------ Shared Memory Segments --------
2393              key        shmid      owner      perms      bytes      nattch     status
2394
2395
2396
2397       Create  a  3rd  container  using  the --ipc=container:id option, now it
2398       shows the shared memory segment from the first:
2399
2400
2401              $ podman run -it --ipc=container:ed735b2264ac shm ipcs -m
2402              $ sudo ipcs -m
2403
2404              ------ Shared Memory Segments --------
2405              key        shmid      owner      perms      bytes      nattch     status
2406              0x0000162e 0          root       666        27         1
2407
2408
2409
2410   Mapping Ports for External Usage
2411       The exposed port of an application can be mapped to a host  port  using
2412       the  -p  flag.  For example, an httpd port 80 can be mapped to the host
2413       port 8080 using the following:
2414
2415
2416              $ podman run -p 8080:80 -d -i -t fedora/httpd
2417
2418
2419
2420   Mounting External Volumes
2421       To mount a host directory as a container volume, specify  the  absolute
2422       path to the directory and the absolute path for the container directory
2423       separated by a colon. If the source is a  named  volume  maintained  by
2424       Podman,  it  is recommended to use its name rather than the path to the
2425       volume. Otherwise the volume will be considered as an orphan and  wiped
2426       if you execute podman volume prune:
2427
2428
2429              $ podman run -v /var/db:/data1 -i -t fedora bash
2430
2431              $ podman run -v data:/data2 -i -t fedora bash
2432
2433              $ podman run -v /var/cache/dnf:/var/cache/dnf:O -ti fedora dnf -y update
2434
2435              $ podman run -d -e MYSQL_ROOT_PASSWORD=root --user mysql --userns=keep-id -v ~/data:/var/lib/mysql:z,U mariadb
2436
2437
2438
2439       Using  --mount  flags  to mount a host directory as a container folder,
2440       specify the absolute path to the directory or the volume name, and  the
2441       absolute path within the container directory:
2442
2443
2444              $ podman run --mount type=bind,src=/var/db,target=/data1 busybox sh
2445
2446              $ podman run --mount type=bind,src=volume-name,target=/data1 busybox sh
2447
2448
2449
2450       When  using  SELinux,  be  aware that the host has no knowledge of con‐
2451       tainer SELinux policy. Therefore, in the above example, if SELinux pol‐
2452       icy  is  enforced,  the  /var/db  directory is not writable to the con‐
2453       tainer. A "Permission Denied" message will occur and an avc: message in
2454       the host's syslog.
2455
2456
2457       To  work  around  this, at time of writing this man page, the following
2458       command needs to be run in order for the proper SELinux policy type la‐
2459       bel to be attached to the host directory:
2460
2461
2462              $ chcon -Rt svirt_sandbox_file_t /var/db
2463
2464
2465
2466       Now,  writing to the /data1 volume in the container will be allowed and
2467       the changes will also be reflected on the host in /var/db.
2468
2469
2470   Using alternative security labeling
2471       You can override the default labeling  scheme  for  each  container  by
2472       specifying  the  --security-opt  flag. For example, you can specify the
2473       MCS/MLS level, a requirement for MLS systems. Specifying the  level  in
2474       the following command allows you to share the same content between con‐
2475       tainers.
2476
2477
2478              podman run --security-opt label=level:s0:c100,c200 -i -t fedora bash
2479
2480
2481
2482       An MLS example might be:
2483
2484
2485              $ podman run --security-opt label=level:TopSecret -i -t rhel7 bash
2486
2487
2488
2489       To disable the security labeling for this container versus running with
2490       the
2491
2492
2493   --permissive flag, use the following command:
2494              $ podman run --security-opt label=disable -i -t fedora bash
2495
2496
2497
2498       If  you  want  a tighter security policy on the processes within a con‐
2499       tainer, you can specify an alternate type for the container. You  could
2500       run  a container that is only allowed to listen on Apache ports by exe‐
2501       cuting the following command:
2502
2503
2504              $ podman run --security-opt label=type:svirt_apache_t -i -t centos bash
2505
2506
2507
2508       Note you would have to write policy defining a svirt_apache_t type.
2509
2510
2511       To mask additional specific paths in the container, specify  the  paths
2512       separated  by  a  colon  using  the mask option with the --security-opt
2513       flag.
2514
2515
2516              $ podman run --security-opt mask=/foo/bar:/second/path fedora bash
2517
2518
2519
2520       To unmask all the paths that are masked by default, set the unmask  op‐
2521       tion  to  ALL.  Or  to only unmask specific paths, specify the paths as
2522       shown above with the mask option.
2523
2524
2525              $ podman run --security-opt unmask=ALL fedora bash
2526
2527
2528
2529       To unmask all the paths that start with /proc, set the unmask option to
2530       /proc/*.
2531
2532
2533              $ podman run --security-opt unmask=/proc/* fedora bash
2534
2535
2536
2537              $ podman run --security-opt unmask=/foo/bar:/sys/firmware fedora bash
2538
2539
2540
2541   Setting device weight
2542       If  you  want to set /dev/sda device weight to 200, you can specify the
2543       device weight by --blkio-weight-device flag. Use the following command:
2544
2545
2546              $ podman run -it --blkio-weight-device "/dev/sda:200" ubuntu
2547
2548
2549
2550   Using a podman container with input from a pipe
2551              $ echo "asdf" | podman run --rm -i --entrypoint /bin/cat someimage
2552              asdf
2553
2554
2555
2556   Setting automatic user namespace separated containers
2557              # podman run --userns=auto:size=65536 ubi8-micro cat /proc/self/uid_map
2558              0 2147483647      65536
2559              # podman run --userns=auto:size=65536 ubi8-micro cat /proc/self/uid_map
2560              0 2147549183      65536
2561
2562
2563
2564   Setting Namespaced Kernel Parameters (Sysctls)
2565       The --sysctl sets namespaced kernel parameters (sysctls)  in  the  con‐
2566       tainer. For example, to turn on IP forwarding in the containers network
2567       namespace, run this command:
2568
2569
2570              $ podman run --sysctl net.ipv4.ip_forward=1 someimage
2571
2572
2573
2574       Note that not all sysctls  are  namespaced.  Podman  does  not  support
2575       changing  sysctls  inside of a container that also modify the host sys‐
2576       tem. As the kernel evolves we expect to see more sysctls become  names‐
2577       paced.
2578
2579
2580       See the definition of the --sysctl option above for the current list of
2581       supported sysctls.
2582
2583
2584   Set UID/GID mapping in a new user namespace
2585       Running a container in a new user namespace requires a mapping  of  the
2586       uids and gids from the host.
2587
2588
2589              $ podman run --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
2590
2591
2592
2593   Configuring Storage Options from the command line
2594       Podman  allows  for the configuration of storage by changing the values
2595       in the /etc/container/storage.conf or by  using  global  options.  This
2596       shows how to setup and use fuse-overlayfs for a one time run of busybox
2597       using global options.
2598
2599
2600              podman --log-level=debug --storage-driver overlay --storage-opt "overlay.mount_program=/usr/bin/fuse-overlayfs" run busybox /bin/sh
2601
2602
2603
2604   Configure timezone in a container
2605              $ podman run --tz=local alpine date
2606              $ podman run --tz=Asia/Shanghai alpine date
2607              $ podman run --tz=US/Eastern alpine date
2608
2609
2610
2611   Adding dependency containers
2612       The first container, container1, is not started initially, but must  be
2613       running  before  container2  will  start.   The podman run command will
2614       start the container automatically before starting container2.
2615
2616
2617              $ podman create --name container1 -t -i fedora bash
2618              $ podman run --name container2 --requires container1 -t -i fedora bash
2619
2620
2621
2622       Multiple containers can be required.
2623
2624
2625              $ podman create --name container1 -t -i fedora bash
2626              $ podman create --name container2 -t -i fedora bash
2627              $ podman run --name container3 --requires container1,container2 -t -i fedora bash
2628
2629
2630
2631   Configure keep supplemental groups for access to volume
2632              $ podman run -v /var/lib/design:/var/lib/design --group-add keep-groups ubi8
2633
2634
2635
2636   Configure execution domain for containers using personality flag
2637              $ podman run --name container1 --personaity=LINUX32 fedora bash
2638
2639
2640
2641   Run a container with external rootfs mounted as an overlay
2642              $ podman run --name container1 --rootfs /path/to/rootfs:O bash
2643
2644
2645
2646   Handling Timezones in java applications in a container.
2647       In order to use a timezone other than UTC when running a Java  applica‐
2648       tion within a container, the TZ environment variable must be set within
2649       the container. Java applications will ignore the  value  set  with  the
2650       --tz option.
2651
2652
2653              # Example run
2654              podman run -ti --rm  -e TZ=EST mytzimage
2655              lrwxrwxrwx. 1 root root 29 Nov  3 08:51 /etc/localtime -> ../usr/share/zoneinfo/Etc/UTC
2656              Now with default timezone:
2657              Fri Nov 19 18:10:55 EST 2021
2658              Java default sees the following timezone:
2659              2021-11-19T18:10:55.651130-05:00
2660              Forcing UTC:
2661              Fri Nov 19 23:10:55 UTC 2021
2662
2663
2664
2665   Run  a  container  connected  to two networks (called net1 and net2) with a
2666       static ip
2667              $ podman run --network net1:ip=10.89.1.5 --network net2:ip=10.89.10.10 alpine ip addr
2668
2669
2670
2671   Rootless Containers
2672       Podman runs as a non-root user on most systems. This  feature  requires
2673       that  a  new  enough  version of shadow-utils be installed. The shadow-
2674       utils package must include the newuidmap(1) and  newgidmap(1)  executa‐
2675       bles.
2676
2677
2678       In  order  for  users to run rootless, there must be an entry for their
2679       username in /etc/subuid and /etc/subgid which lists the UIDs for  their
2680       user namespace.
2681
2682
2683       Rootless  Podman  works  better  if  the fuse-overlayfs and slirp4netns
2684       packages  are  installed.   The  fuse-overlayfs  package   provides   a
2685       userspace  overlay  storage driver, otherwise users need to use the vfs
2686       storage driver, which is diskspace expensive and does not perform well.
2687       slirp4netns  is  required for VPN, without it containers need to be run
2688       with the --network=host flag.
2689
2690

ENVIRONMENT

2692       Environment variables within containers can be set using multiple  dif‐
2693       ferent  options,  in  the  following order of precedence (later entries
2694       override earlier entries):
2695
2696
2697              • Container image: Any environment variables  specified  in  the
2698                container image.
2699
2700--http-proxy:  By  default, several environment variables will
2701                be passed in from the host, such as http_proxy  and  no_proxy.
2702                See --http-proxy for details.
2703
2704--env-host:  Host  environment of the process executing Podman
2705                is added.
2706
2707--env-file: Any environment variables specified via env-files.
2708                If  multiple files specified, then they override each other in
2709                order of entry.
2710
2711--env: Any environment variables specified will override  pre‐
2712                vious settings.
2713
2714
2715
2716       Run containers and set the environment ending with a * and a *****:
2717
2718
2719              $ export ENV1=a
2720              $ podman run --env ENV* alpine printenv ENV1
2721              a
2722
2723              $ podman run --env ENV*****=b alpine printenv ENV*****
2724              b
2725
2726
2727

CONMON

2729       When Podman starts a container it actually executes the conmon program,
2730       which then executes the OCI Runtime.  Conmon is the container  monitor.
2731       It  is a small program whose job is to watch the primary process of the
2732       container, and if the container dies, save  the  exit  code.   It  also
2733       holds  open  the  tty  of  the container, so that it can be attached to
2734       later. This is what allows  Podman  to  run  in  detached  mode  (back‐
2735       grounded),  so  Podman can exit but conmon continues to run.  Each con‐
2736       tainer has their own instance of conmon. Conmon waits for the container
2737       to  exit,  gathers  and saves the exit code, and then launches a Podman
2738       process to complete the container cleanup, by shutting down the network
2739       and  storage.    For  more  information on conmon, please reference the
2740       conmon(8) man page.
2741
2742

FILES

2744       /etc/subuid
2745
2746
2747       /etc/subgid
2748
2749
2750       NOTE: Use the environment variable TMPDIR to change the temporary stor‐
2751       age  location  of  downloaded  container images. Podman defaults to use
2752       /var/tmp.
2753
2754

SEE ALSO

2756       podman(1), podman-save(1), podman-ps(1), podman-attach(1),  podman-pod-
2757       create(1),  podman-port(1),  podman-start(1),  podman-kill(1),  podman-
2758       stop(1),  podman-generate-systemd(1),  podman-rm(1),  subgid(5),   sub‐
2759       uid(5),      containers.conf(5),     systemd.unit(5),     setsebool(8),
2760       slirp4netns(1), fuse-overlayfs(1), proc(5), conmon(8), personality(2)
2761
2762

HISTORY

2764       September   2018,   updated    by    Kunal    Kushwaha    <kushwaha_ku‐
2765       nal_v7@lab.ntt.co.jp>
2766
2767
2768       October  2017,  converted  from  Docker  documentation to Podman by Dan
2769       Walsh for Podman <dwalsh@redhat.com>
2770
2771
2772       November 2015, updated by Sally O'Malley <somalley@redhat.com>
2773
2774
2775       June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2776
2777
2778       April 2014, Originally compiled by  William  Henry  <whenry@redhat.com>
2779       based on docker.com source material and internal work.
2780
2781

FOOTNOTES

2783       1: The Podman project is committed to inclusivity, a core value of open
2784       source. The master and slave mount propagation terminology used here is
2785       problematic  and  divisive, and should be changed. However, these terms
2786       are currently used within the Linux kernel and must be  used  as-is  at
2787       this  time. When the kernel maintainers rectify this usage, Podman will
2788       follow suit immediately.
2789
2790
2791
2792                                                               podman-run(1)()
Impressum