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

OPTIONS

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

Exit Status

2041       The exit code from podman run gives information about why the container
2042       failed to run or why it exited. When podman run exits with  a  non-zero
2043       code, the exit codes follow the chroot(1) standard, see below:
2044
2045
2046       125 The error is with Podman itself
2047
2048
2049              $ podman run --foo busybox; echo $?
2050              Error: unknown flag: --foo
2051              125
2052
2053
2054
2055       126 The contained command cannot be invoked
2056
2057
2058              $ podman run busybox /etc; echo $?
2059              Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error
2060              126
2061
2062
2063
2064       127 The contained command cannot be found
2065
2066
2067              $ podman run busybox foo; echo $?
2068              Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error
2069              127
2070
2071
2072
2073       Exit code contained command exit code
2074
2075
2076              $ podman run busybox /bin/sh -c 'exit 3'; echo $?
2077              3
2078
2079
2080

EXAMPLES

2082   Running container in read-only mode
2083       During  container  image development, containers often need to write to
2084       the image content. Installing packages into /usr, for example. In  pro‐
2085       duction, applications seldom need to write to the image.  Container ap‐
2086       plications write to volumes if they need to write to  file  systems  at
2087       all.  Applications can be made more secure by running them in read-only
2088       mode using the --read-only switch.  This protects the containers  image
2089       from  modification. Read only containers may still need to write tempo‐
2090       rary data. The best way to handle this is to mount tmpfs directories on
2091       /run and /tmp.
2092
2093
2094              $ podman run --read-only -i -t fedora /bin/bash
2095
2096              $ podman run --read-only --read-only-tmpfs=false --tmpfs /run -i -t fedora /bin/bash
2097
2098
2099
2100   Exposing log messages from the container to the host's log
2101       If  you  want  messages that are logged in your container to show up in
2102       the host's syslog/journal then you should bind mount the  /dev/log  di‐
2103       rectory as follows.
2104
2105
2106              $ podman run -v /dev/log:/dev/log -i -t fedora /bin/bash
2107
2108
2109
2110       From inside the container you can test this by sending a message to the
2111       log.
2112
2113
2114              (bash)# logger "Hello from my container"
2115
2116
2117
2118       Then exit and check the journal.
2119
2120
2121              (bash)# exit
2122
2123              $ journalctl -b | grep Hello
2124
2125
2126
2127       This should list the message sent to logger.
2128
2129
2130   Attaching to one or more from STDIN, STDOUT, STDERR
2131       If you do not specify -a, Podman will attach everything (stdin, stdout,
2132       stderr).   You  can  specify  to  which  of  the three standard streams
2133       (stdin, stdout, stderr) you'd like to connect instead, as in:
2134
2135
2136              $ podman run -a stdin -a stdout -i -t fedora /bin/bash
2137
2138
2139
2140   Sharing IPC between containers
2141       Using             shm_server.c             available              here:
2142       https://www.cs.cf.ac.uk/Dave/C/node27.html
2143
2144
2145       Testing --ipc=host mode:
2146
2147
2148       Host  shows a shared memory segment with 7 pids attached, happens to be
2149       from httpd:
2150
2151
2152              $ sudo ipcs -m
2153
2154              ------ Shared Memory Segments --------
2155              key        shmid      owner      perms      bytes      nattch     status
2156              0x01128e25 0          root       600        1000       7
2157
2158
2159
2160       Now run a regular container, and it correctly does NOT see  the  shared
2161       memory segment from the host:
2162
2163
2164              $ podman run -it shm ipcs -m
2165
2166              ------ Shared Memory Segments --------
2167              key        shmid      owner      perms      bytes      nattch     status
2168
2169
2170
2171       Run  a  container  with  the new --ipc=host option, and it now sees the
2172       shared memory segment from the host httpd:
2173
2174
2175              $ podman run -it --ipc=host shm ipcs -m
2176
2177              ------ Shared Memory Segments --------
2178              key        shmid      owner      perms      bytes      nattch     status
2179              0x01128e25 0          root       600        1000       7
2180
2181
2182
2183       Testing --ipc=container:id mode:
2184
2185
2186       Start a container with a program to create a shared memory segment:
2187
2188
2189              $ podman run -it shm bash
2190              $ sudo shm/shm_server &
2191              $ sudo ipcs -m
2192
2193              ------ Shared Memory Segments --------
2194              key        shmid      owner      perms      bytes      nattch     status
2195              0x0000162e 0          root       666        27         1
2196
2197
2198
2199       Create a 2nd container correctly shows no shared  memory  segment  from
2200       1st container:
2201
2202
2203              $ podman run shm ipcs -m
2204
2205              ------ Shared Memory Segments --------
2206              key        shmid      owner      perms      bytes      nattch     status
2207
2208
2209
2210       Create  a  3rd  container  using  the --ipc=container:id option, now it
2211       shows the shared memory segment from the first:
2212
2213
2214              $ podman run -it --ipc=container:ed735b2264ac shm ipcs -m
2215              $ sudo ipcs -m
2216
2217              ------ Shared Memory Segments --------
2218              key        shmid      owner      perms      bytes      nattch     status
2219              0x0000162e 0          root       666        27         1
2220
2221
2222
2223   Mapping Ports for External Usage
2224       The exposed port of an application can be mapped to a host  port  using
2225       the  -p  flag.  For example, an httpd port 80 can be mapped to the host
2226       port 8080 using the following:
2227
2228
2229              $ podman run -p 8080:80 -d -i -t fedora/httpd
2230
2231
2232
2233   Mounting External Volumes
2234       To mount a host directory as a container volume, specify  the  absolute
2235       path to the directory and the absolute path for the container directory
2236       separated by a colon. If the source is a  named  volume  maintained  by
2237       Podman,  it  is recommended to use its name rather than the path to the
2238       volume. Otherwise the volume will be considered as an orphan and  wiped
2239       if you execute podman volume prune:
2240
2241
2242              $ podman run -v /var/db:/data1 -i -t fedora bash
2243
2244              $ podman run -v data:/data2 -i -t fedora bash
2245
2246              $ podman run -v /var/cache/dnf:/var/cache/dnf:O -ti fedora dnf -y update
2247
2248              $ podman run -d -e MYSQL_ROOT_PASSWORD=root --user mysql --userns=keep-id -v ~/data:/var/lib/mysql:z,U mariadb
2249
2250
2251
2252       Using  --mount  flags  to mount a host directory as a container folder,
2253       specify the absolute path to the directory or the volume name, and  the
2254       absolute path within the container directory:
2255
2256
2257              $ podman run --mount type=bind,src=/var/db,target=/data1 busybox sh
2258
2259              $ podman run --mount type=bind,src=volume-name,target=/data1 busybox sh
2260
2261
2262
2263       When  using  SELinux,  be  aware that the host has no knowledge of con‐
2264       tainer SELinux policy. Therefore, in the above example, if SELinux pol‐
2265       icy  is  enforced,  the  /var/db  directory is not writable to the con‐
2266       tainer. A "Permission Denied" message will occur and an avc: message in
2267       the host's syslog.
2268
2269
2270       To  work  around  this, at time of writing this man page, the following
2271       command needs to be run in order for the proper SELinux policy type la‐
2272       bel to be attached to the host directory:
2273
2274
2275              $ chcon -Rt svirt_sandbox_file_t /var/db
2276
2277
2278
2279       Now,  writing to the /data1 volume in the container will be allowed and
2280       the changes will also be reflected on the host in /var/db.
2281
2282
2283   Using alternative security labeling
2284       You can override the default labeling  scheme  for  each  container  by
2285       specifying  the  --security-opt  flag. For example, you can specify the
2286       MCS/MLS level, a requirement for MLS systems. Specifying the  level  in
2287       the following command allows you to share the same content between con‐
2288       tainers.
2289
2290
2291              podman run --security-opt label=level:s0:c100,c200 -i -t fedora bash
2292
2293
2294
2295       An MLS example might be:
2296
2297
2298              $ podman run --security-opt label=level:TopSecret -i -t rhel7 bash
2299
2300
2301
2302       To disable the security labeling for this container versus running with
2303       the
2304
2305
2306   --permissive flag, use the following command:
2307              $ podman run --security-opt label=disable -i -t fedora bash
2308
2309
2310
2311       If  you  want  a tighter security policy on the processes within a con‐
2312       tainer, you can specify an alternate type for the container. You  could
2313       run  a container that is only allowed to listen on Apache ports by exe‐
2314       cuting the following command:
2315
2316
2317              $ podman run --security-opt label=type:svirt_apache_t -i -t centos bash
2318
2319
2320
2321       Note you would have to write policy defining a svirt_apache_t type.
2322
2323
2324       To mask additional specific paths in the container, specify  the  paths
2325       separated  by  a  colon  using  the mask option with the --security-opt
2326       flag.
2327
2328
2329              $ podman run --security-opt mask=/foo/bar:/second/path fedora bash
2330
2331
2332
2333       To unmask all the paths that are masked by default, set the unmask  op‐
2334       tion  to  ALL.  Or  to only unmask specific paths, specify the paths as
2335       shown above with the mask option.
2336
2337
2338              $ podman run --security-opt unmask=ALL fedora bash
2339
2340
2341
2342       To unmask all the paths that start with /proc, set the unmask option to
2343       /proc/*.
2344
2345
2346              $ podman run --security-opt unmask=/proc/* fedora bash
2347
2348
2349
2350              $ podman run --security-opt unmask=/foo/bar:/sys/firmware fedora bash
2351
2352
2353
2354   Setting device weight
2355       If  you  want to set /dev/sda device weight to 200, you can specify the
2356       device weight by --blkio-weight-device flag. Use the following command:
2357
2358
2359              $ podman run -it --blkio-weight-device "/dev/sda:200" ubuntu
2360
2361
2362
2363   Using a podman container with input from a pipe
2364              $ echo "asdf" | podman run --rm -i --entrypoint /bin/cat someimage
2365              asdf
2366
2367
2368
2369   Setting automatic user namespace separated containers
2370              # podman run --userns=auto:size=65536 ubi8-micro cat /proc/self/uid_map
2371              0 2147483647      65536
2372              # podman run --userns=auto:size=65536 ubi8-micro cat /proc/self/uid_map
2373              0 2147549183      65536
2374
2375
2376
2377   Setting Namespaced Kernel Parameters (Sysctls)
2378       The --sysctl sets namespaced kernel parameters (sysctls)  in  the  con‐
2379       tainer. For example, to turn on IP forwarding in the containers network
2380       namespace, run this command:
2381
2382
2383              $ podman run --sysctl net.ipv4.ip_forward=1 someimage
2384
2385
2386
2387       Note that not all sysctls  are  namespaced.  Podman  does  not  support
2388       changing  sysctls  inside of a container that also modify the host sys‐
2389       tem. As the kernel evolves we expect to see more sysctls become  names‐
2390       paced.
2391
2392
2393       See the definition of the --sysctl option above for the current list of
2394       supported sysctls.
2395
2396
2397   Set UID/GID mapping in a new user namespace
2398       Running a container in a new user namespace requires a mapping  of  the
2399       uids and gids from the host.
2400
2401
2402              $ podman run --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
2403
2404
2405
2406   Configuring Storage Options from the command line
2407       Podman  allows  for the configuration of storage by changing the values
2408       in the /etc/container/storage.conf or by  using  global  options.  This
2409       shows how to setup and use fuse-overlayfs for a one time run of busybox
2410       using global options.
2411
2412
2413              podman --log-level=debug --storage-driver overlay --storage-opt "overlay.mount_program=/usr/bin/fuse-overlayfs" run busybox /bin/sh
2414
2415
2416
2417   Configure timezone in a container
2418              $ podman run --tz=local alpine date
2419              $ podman run --tz=Asia/Shanghai alpine date
2420              $ podman run --tz=US/Eastern alpine date
2421
2422
2423
2424   Adding dependency containers
2425       The first container, container1, is not started initially, but must  be
2426       running  before  container2  will  start.   The podman run command will
2427       start the container automatically before starting container2.
2428
2429
2430              $ podman create --name container1 -t -i fedora bash
2431              $ podman run --name container2 --requires container1 -t -i fedora bash
2432
2433
2434
2435       Multiple containers can be required.
2436
2437
2438              $ podman create --name container1 -t -i fedora bash
2439              $ podman create --name container2 -t -i fedora bash
2440              $ podman run --name container3 --requires container1,container2 -t -i fedora bash
2441
2442
2443
2444   Configure keep supplemental groups for access to volume
2445              $ podman run -v /var/lib/design:/var/lib/design --group-add keep-groups ubi8
2446
2447
2448
2449   Configure execution domain for containers using personality flag
2450              $ podman run --name container1 --personaity=LINUX32 fedora bash
2451
2452
2453
2454   Rootless Containers
2455       Podman runs as a non root user on most systems. This  feature  requires
2456       that  a  new  enough  version of shadow-utils be installed. The shadow-
2457       utils package must include the newuidmap(1) and  newgidmap(1)  executa‐
2458       bles.
2459
2460
2461       Note:  RHEL7  and  Centos 7 will not have this feature until RHEL7.7 is
2462       released.
2463
2464
2465       In order for users to run rootless, there must be an  entry  for  their
2466       username  in /etc/subuid and /etc/subgid which lists the UIDs for their
2467       user namespace.
2468
2469
2470       Rootless Podman works better  if  the  fuse-overlayfs  and  slirp4netns
2471       packages   are   installed.   The  fuse-overlayfs  package  provides  a
2472       userspace overlay storage driver, otherwise users need to use  the  vfs
2473       storage driver, which is diskspace expensive and does not perform well.
2474       slirp4netns is required for VPN, without it containers need to  be  run
2475       with the --network=host flag.
2476
2477

ENVIRONMENT

2479       Environment  variables within containers can be set using multiple dif‐
2480       ferent options, in the following order  of  precedence  (later  entries
2481       override earlier entries):
2482
2483
2484              • Container  image:  Any  environment variables specified in the
2485                container image.
2486
2487--http-proxy: By default, several environment  variables  will
2488                be  passed  in from the host, such as http_proxy and no_proxy.
2489                See --http-proxy for details.
2490
2491--env-host: Host environment of the process  executing  Podman
2492                is added.
2493
2494--env-file: Any environment variables specified via env-files.
2495                If multiple files specified, then they override each other  in
2496                order of entry.
2497
2498--env:  Any environment variables specified will override pre‐
2499                vious settings.
2500
2501
2502
2503       Run containers and set the environment ending with a * and a *****:
2504
2505
2506              $ export ENV1=a
2507              $ podman run --env ENV* alpine printenv ENV1
2508              a
2509
2510              $ podman run --env ENV*****=b alpine printenv ENV*****
2511              b
2512
2513
2514

CONMON

2516       When Podman starts a container it actually executes the conmon program,
2517       which  then executes the OCI Runtime.  Conmon is the container monitor.
2518       It is a small program whose job is to watch the primary process of  the
2519       container,  and  if  the  container  dies, save the exit code.  It also
2520       holds open the tty of the container, so that  it  can  be  attached  to
2521       later.  This  is  what  allows  Podman  to  run in detached mode (back‐
2522       grounded), so Podman can exit but conmon continues to run.   Each  con‐
2523       tainer has their own instance of conmon. Conmon waits for the container
2524       to exit, gathers and saves the exit code, and then  launches  a  Podman
2525       process to complete the container cleanup, by shutting down the network
2526       and storage.   For more information on  conmon,  please  reference  the
2527       conmon(8) man page.
2528
2529

FILES

2531       /etc/subuid
2532
2533
2534       /etc/subgid
2535
2536
2537       NOTE: Use the environment variable TMPDIR to change the temporary stor‐
2538       age location of downloaded container images.  Podman  defaults  to  use
2539       /var/tmp.
2540
2541

SEE ALSO

2543       podman(1),  podman-save(1), podman-ps(1), podman-attach(1), podman-pod-
2544       create(1),  podman-port(1),  podman-start(1),  podman-kill(1),  podman-
2545       stop(1), podman-generate-systemd(1) podman-rm(1), subgid(5), subuid(5),
2546       containers.conf(5),  systemd.unit(5),   setsebool(8),   slirp4netns(1),
2547       fuse-overlayfs(1), proc(5), conmon(8), personality(2).
2548
2549

HISTORY

2551       September    2018,    updated    by    Kunal   Kushwaha   <kushwaha_ku‐
2552       nal_v7@lab.ntt.co.jp>
2553
2554
2555       October 2017, converted from Docker  documentation  to  Podman  by  Dan
2556       Walsh for Podman <dwalsh@redhat.com>
2557
2558
2559       November 2015, updated by Sally O'Malley <somalley@redhat.com>
2560
2561
2562       June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
2563
2564
2565       April  2014,  Originally  compiled by William Henry <whenry@redhat.com>
2566       based on docker.com source material and internal work.
2567
2568

FOOTNOTES

2570       1: The Podman project is committed to inclusivity, a core value of open
2571       source. The master and slave mount propagation terminology used here is
2572       problematic and divisive, and should be changed. However,  these  terms
2573       are  currently  used  within the Linux kernel and must be used as-is at
2574       this time. When the kernel maintainers rectify this usage, Podman  will
2575       follow suit immediately.
2576
2577
2578
2579                                                               podman-run(1)()
Impressum