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, an empty file is created in each container to  indicate  to  pro‐
37       grams  they  are  running  in  a  container.  This  file  is located at
38       /run/.containerenv.
39
40
41       When   running   from   a   user   defined   network   namespace,   the
42       /etc/netns/NSNAME/resolv.conf  will  be  used  if  it exists, otherwise
43       /etc/resolv.conf will be used.
44
45

OPTIONS

47       --add-host=host:ip
48
49
50       Add a line to container's /etc/hosts  for  custom  host-to-IP  mapping.
51       This option can be set multiple times.
52
53
54       --annotation=key=value
55
56
57       Add  an  annotation  to the container.  This option can be set multiple
58       times.
59
60
61       --attach, -a=stdin|stdout|stderr
62
63
64       Attach to STDIN, STDOUT or STDERR.
65
66
67       In foreground mode (the default when -d is not specified),  podman  run
68       can  start  the  process in the container and attach the console to the
69       process's standard input, output, and error. It can even pretend to  be
70       a TTY (this is what most commandline executables expect) and pass along
71       signals. The -a option can be  set  for  each  of  stdin,  stdout,  and
72       stderr.
73
74
75       --authfile[=path]
76
77
78       Path to the authentication file. Default is ${XDG_RUNTIME_DIR}/contain‐
79       ers/auth.json. (Not available for remote commands)
80
81
82       Note: You can also override the default path of the authentication file
83       by setting the REGISTRY_AUTH_FILE environment variable.
84
85
86       --blkio-weight=weight
87
88
89       Block IO relative weight. The weight is a value between 10 and 1000.
90
91
92       --blkio-weight-device=device:weight
93
94
95       Block IO relative device weight.
96
97
98       --cap-add=capability
99
100
101       Add Linux capabilities.
102
103
104       --cap-drop=capability
105
106
107       Drop Linux capabilities.
108
109
110       --cgroupns=mode
111
112
113       Set the cgroup namespace mode for the container.
114
115
116              · host: use the host's cgroup namespace inside the container.
117
118              · container:id: join the namespace of the specified container.
119
120              · private: create a new cgroup namespace.
121
122              · ns:path: join the namespace at the specified path.
123
124
125
126       If  the  host  uses cgroups v1, the default is set to host.  On cgroups
127       v2, the default is private.
128
129
130       --cgroups=enabled|disabled|no-conmon
131
132
133       Determines whether the container will create CGroups.
134
135
136       Default is enabled. The disabled option will force the container to not
137       create  CGroups, and thus conflicts with CGroup options (--cgroupns and
138       --cgroup-parent).  The no-conmon option disables a new CGroup only  for
139       the conmon process.
140
141
142       --cgroup-parent=path
143
144
145       Path  to  cgroups under which the cgroup for the container will be cre‐
146       ated. If the path is not absolute, the path is considered to  be  rela‐
147       tive  to  the cgroups path of the init process. Cgroups will be created
148       if they do not already exist.
149
150
151       --cidfile=file
152
153
154       Write the container ID to file.
155
156
157       --conmon-pidfile=file
158
159
160       Write the pid of the conmon process to a file. As conmon runs in a sep‐
161       arate  process  than  Podman,  this  is necessary when using systemd to
162       restart Podman containers.
163
164
165       --cpu-period=limit
166
167
168       Limit the container's CPU usage by setting  CPU  CFS  (Completely  Fair
169       Scheduler) period.
170
171
172       --cpu-quota=limit
173
174
175       Limit the CPU CFS (Completely Fair Scheduler) quota.
176
177
178       Limit  the  container's  CPU usage. By default, containers run with the
179       full CPU resource. This flag tell  the  kernel  to  restrict  the  con‐
180       tainer's CPU usage to the quota you specify.
181
182
183       --cpu-rt-period=microseconds
184
185
186       Limit the CPU real-time period in microseconds.
187
188
189       Limit the container's Real Time CPU usage. This flag tell the kernel to
190       restrict the container's Real Time CPU usage to the period you specify.
191
192
193       --cpu-rt-runtime=microseconds
194
195
196       Limit the CPU real-time runtime in microseconds.
197
198
199       Limit the containers Real Time CPU usage. This flag tells the kernel to
200       limit the amount of time in a given CPU period Real Time tasks may con‐
201       sume. Ex: Period of 1,000,000us and Runtime  of  950,000us  means  that
202       this container could consume 95% of available CPU and leave the remain‐
203       ing 5% to normal priority tasks.
204
205
206       The sum of all runtimes across  containers  cannot  exceed  the  amount
207       allotted to the parent cgroup.
208
209
210       --cpu-shares=shares
211
212
213       CPU shares (relative weight).
214
215
216       By  default, all containers get the same proportion of CPU cycles. This
217       proportion can be  modified  by  changing  the  container's  CPU  share
218       weighting  relative  to the combined weight of all the running contain‐
219       ers. Default weight is 1024.
220
221
222       The proportion will only apply when CPU-intensive  processes  are  run‐
223       ning.   When  tasks in one container are idle, other containers can use
224       the left-over CPU time. The actual amount of CPU time will vary depend‐
225       ing on the number of containers running on the system.
226
227
228       For example, consider three containers, one has a cpu-share of 1024 and
229       two others have a cpu-share setting of 512. When processes in all three
230       containers  attempt  to  use  100%  of  CPU,  the first container would
231       receive 50% of the total CPU time. If you add a fourth container with a
232       cpu-share  of  1024,  the first container only gets 33% of the CPU. The
233       remaining containers receive 16.5%, 16.5% and 33% of the CPU.
234
235
236       On a multi-core system, the shares of CPU time are distributed over all
237       CPU  cores.  Even  if  a  container is limited to less than 100% of CPU
238       time, it can use 100% of each individual CPU core.
239
240
241       For example, consider a system with more than three cores. If you start
242       one  container  {C0}  with  --cpu-shares=512  running  one process, and
243       another container {C1} with --cpu-shares=1024  running  two  processes,
244       this can result in the following division of CPU shares:
245
246
247       ┌────┬───────────┬─────┬──────────────┐
248PID container CPU CPU share    
249       ├────┼───────────┼─────┼──────────────┤
250       │100 │ {C0}      │ 0   │ 100% of CPU0 │
251       ├────┼───────────┼─────┼──────────────┤
252       │101 │ {C1}      │ 1   │ 100% of CPU1 │
253       ├────┼───────────┼─────┼──────────────┤
254       │102 │ {C1}      │ 2   │ 100% of CPU2 │
255       └────┴───────────┴─────┴──────────────┘
256
257       --cpus=number
258
259
260       Number of CPUs. The default is 0.0 which means no limit.
261
262
263       --cpuset-cpus=number
264
265
266       CPUs in which to allow execution. Can be specified as a comma-separated
267       list (e.g. 0,1), as a range (e.g.  0-3),  or  any  combination  thereof
268       (e.g. 0-3,7,11-15).
269
270
271       --cpuset-mems=nodes
272
273
274       Memory nodes (MEMs) in which to allow execution. Only effective on NUMA
275       systems.
276
277
278       For example, if you have four memory nodes (0-3) on  your  system,  use
279       --cpuset-mems=0,1 to only use memory from the first two memory nodes.
280
281
282       --detach, -d=true|false
283
284
285       Detached  mode:  run  the container in the background and print the new
286       container ID. The default is false.
287
288
289       At any time you can run podman ps in the other shell to view a list  of
290       the  running  containers. You can reattach to a detached container with
291       podman attach.
292
293
294       When attached in the tty mode, you can detach from the  container  (and
295       leave it running) using a configurable key sequence.
296
297
298       --detach-keys=sequence
299
300
301       Specify  the  key  sequence  for  detaching  a container; sequence is a
302       comma-delimited set in which each item can be a single  character  from
303       the [a-Z] range, or ctrl-value, where value is one of: a-z or @^[,_.
304
305
306       This option can also be set in libpod.conf(5) file.
307
308
309       Specifying "" will disable this feature. The default is ctrl-p,ctrl-q.
310
311
312       --device=host-device[:container-device][:permissions]
313
314
315       Add  a host device to the container. Optional permissions parameter can
316       be used to specify device permissions, it is combination of r for read,
317       w for write, and m for mknod(2).
318
319
320       Example: --device=/dev/sdc:/dev/xvdc:rwm.
321
322
323       Note: if _hostdevice is a symbolic link then it will be resolved first.
324       The container will only store the major and minor numbers of  the  host
325       device.
326
327
328       Note:  if  the  user  only has access rights via a group, accessing the
329       device from inside a rootless container will fail. The crun(1)  runtime
330       offers  a  workaround  for  this  by  adding  the  option  --annotation
331       run.oci.keep_original_groups=1.
332
333
334       --device-cgroup-rule=rule
335
336
337       Add a rule to the cgroup allowed devices list
338
339
340       --device-read-bps=path:rate
341
342
343       Limit  read  rate  (in  bytes  per  second)   from   a   device   (e.g.
344       --device-read-bps=/dev/sda:1mb).
345
346
347       --device-read-iops=path:rate
348
349
350       Limit  read  rate  (in  IO  operations  per second) from a device (e.g.
351       --device-read-iops=/dev/sda:1000).
352
353
354       --device-write-bps=path:rate
355
356
357       Limit  write  rate  (in  bytes  per   second)   to   a   device   (e.g.
358       --device-write-bps=/dev/sda:1mb).
359
360
361       --device-write-iops=path:rate
362
363
364       Limit  write  rate  (in  IO  operations  per  second) to a device (e.g.
365       --device-write-iops=/dev/sda:1000).
366
367
368       --dns=ipaddr
369
370
371       Set custom DNS servers. Invalid if using --dns with --network  that  is
372       set to none or container:id.
373
374
375       This option can be used to override the DNS configuration passed to the
376       container. Typically this is necessary when the host DNS  configuration
377       is  invalid  for the container (e.g., 127.0.0.1). When this is the case
378       the --dns flags is necessary for every run.
379
380
381       The special  value  none  can  be  specified  to  disable  creation  of
382       /etc/resolv.conf in the container by Podman.  The /etc/resolv.conf file
383       in the image will be used without changes.
384
385
386       --dns-opt=option
387
388
389       Set custom DNS options. Invalid if using --dns-opt with --network  that
390       is set to none or container:id.
391
392
393       --dns-search=domain
394
395
396       Set custom DNS search domains. Invalid if using --dns-search and --net‐
397       work that is set to none or container:id.  Use  --dns-search=.  if  you
398       don't wish to set the search domain.
399
400
401       --entrypoint="command" | '["command", "arg1", ...]'
402
403
404       Overwrite the default ENTRYPOINT of the image.
405
406
407       This  option  allows  you  to  overwrite  the default entrypoint of the
408       image.
409
410
411       The ENTRYPOINT of an image is similar to a COMMAND because it specifies
412       what executable to run when the container starts, but it is (purposely)
413       more difficult to  override.  The  ENTRYPOINT  gives  a  container  its
414       default  nature or behavior, so that when you set an ENTRYPOINT you can
415       run the container as if it were  that  binary,  complete  with  default
416       options,  and  you can pass in more options via the COMMAND. But, some‐
417       times an operator may want to run something else inside the  container,
418       so  you  can  override  the  default  ENTRYPOINT  at runtime by using a
419       --entrypoint and a string to specify the new ENTRYPOINT.
420
421
422       You need to specify multi option commands in the form of a json string.
423
424
425       --env, -e=env
426
427
428       Set environment variables.
429
430
431       This option allows arbitrary environment variables that  are  available
432       for the process to be launched inside of the container.  If an environ‐
433       ment variable is specified without a value, Podman will check the  host
434       environment  for  a value and set the variable only if it is set on the
435       host.  If an environment variable ending in * is specified, Podman will
436       search  the host environment for variables starting with the prefix and
437       will add those variables to the container.  If an environment  variable
438       with a trailing ***** is specified, then a value must be supplied.
439
440
441       See Environment ⟨#environment⟩ note below for precedence and examples.
442
443
444       --env-host=true|false
445
446
447       Use  host  environment  inside  of  the container. See Environment note
448       below for precedence.
449
450
451       --env-file=file
452
453
454       Read in a line delimited file of environment variables. See Environment
455       note below for precedence.
456
457
458       --expose=port
459
460
461       Expose  a port, or a range of ports (e.g. --expose=3300-3310) to set up
462       port redirection on the host system.
463
464
465       --gidmap=container_gid:host_gid:amount
466
467
468       Run the container in a new user namespace using the  supplied  mapping.
469       This  option  conflicts with the --userns and --subgidname flags.  This
470       option can be passed several times to map different ranges. If  calling
471       podman run as an unprivileged user, the user needs to have the right to
472       use the mapping. See subuid(5).  The example maps gids  0-1999  in  the
473       container to the gids 30000-31999 on the host: --gidmap=0:30000:2000.
474
475
476       --group-add=group
477
478
479       Add additional groups to run as
480
481
482       --health-cmd="command" | '["command", "arg1", ...]'
483
484
485       Set  or  alter  a healthcheck command for a container. The command is a
486       command to be executed inside your container that determines your  con‐
487       tainer  health.   The command is required for other healthcheck options
488       to be applied.  A value of none disables existing healthchecks.
489
490
491       Multiple options can be passed in the form of a JSON array;  otherwise,
492       the command will be interpreted as an argument to /bin/sh -c.
493
494
495       --health-interval=interval
496
497
498       Set an interval for the healthchecks. An interval of disable results in
499       no automatic timer setup. The default is 30s.
500
501
502       --health-retries=retries
503
504
505       The number of retries allowed before a healthcheck is considered to  be
506       unhealthy. The default value is 3.
507
508
509       --health-start-period=period
510
511
512       The  initialization time needed for a container to bootstrap. The value
513       can be expressed in time format like 2m3s.  The default value is 0s.
514
515
516       --health-timeout=timeout
517
518
519       The maximum time allowed to complete the healthcheck before an interval
520       is considered failed.  Like start-period, the value can be expressed in
521       a time format such as 1m22s.  The default value is 30s.
522
523
524       --help
525
526
527       Print usage statement
528
529
530       -h, --hostname=name
531
532
533       Container host name
534
535
536       Sets the container host name that is available inside the container.
537
538
539       --http-proxy=true|false
540
541
542       By default proxy environment variables are passed into the container if
543       set  for the Podman process.  This can be disabled by setting the value
544       to false.  The environment  variables  passed  in  include  http_proxy,
545       https_proxy,  ftp_proxy,  no_proxy, and also the upper case versions of
546       those.  This option is only needed when the  host  system  must  use  a
547       proxy  but  the  container should not use any proxy.  Proxy environment
548       variables specified for the container in any other  way  will  override
549       the  values  that would have been passed through from the host.  (Other
550       ways to specify the proxy for the container include passing the  values
551       with  the --env flag, or hard coding the proxy environment at container
552       build time.)
553
554
555       Defaults to true.
556
557
558       --image-volume, builtin-volume=bind|tmpfs|ignore
559
560
561       Tells Podman how to handle the builtin image volumes. Default is bind.
562
563
564              · bind: A directory is created inside the container state direc‐
565                tory and bind mounted into the container for the volumes.
566
567              · tmpfs:  The  volume  is mounted onto the container as a tmpfs,
568                which allows the users to create content that disappears  when
569                the container is stopped.
570
571              · ignore: All volumes are just ignored and no action is taken.
572
573
574
575       --init
576
577
578       Run  an  init inside the container that forwards signals and reaps pro‐
579       cesses.
580
581
582       --init-path=path
583
584
585       Path to the container-init binary.
586
587
588       --interactive, -i=true|false
589
590
591       When set to true, keep stdin open even if not attached. The default  is
592       false.
593
594
595       --ip6=ip
596
597
598       Not implemented.
599
600
601       --ip=ip
602
603
604       Specify   a   static   IP   address  for  the  container,  for  example
605       10.88.64.128.  Can only be used if no additional CNI networks  to  join
606       were  specified via --network=network-name, and if the container is not
607       joining  another  container's  network  namespace  via   --network=con‐
608       tainer:id.   The  address must be within the default CNI network's pool
609       (default 10.88.0.0/16).
610
611
612       --ipc=mode
613
614
615       Set the IPC namespace mode for a container. The default is to create  a
616       private IPC namespace.
617
618
619              · container:id:  reuses  another  container shared memory, sema‐
620                phores and message queues
621
622              · host: use the host shared memory,semaphores and message queues
623                inside the container.  Note: the host mode gives the container
624                full access to local shared memory and is therefore considered
625                insecure.
626
627              · ns:path: path to an IPC namespace to join.
628
629
630
631       --kernel-memory=number[unit]
632
633
634       Kernel  memory  limit.  A  unit  can  be  b  (bytes),  k (kilobytes), m
635       (megabytes), or g (gigabytes).
636
637
638       Constrains the kernel memory available to a container. If a limit of  0
639       is specified (not using --kernel-memory), the container's kernel memory
640       is not limited. If you specify a limit, it may be rounded up to a  mul‐
641       tiple  of  the  operating  system's page size and the value can be very
642       large, millions of trillions.
643
644
645       --label, -l=key=value
646
647
648       Add metadata to a container.
649
650
651       --label-file=file
652
653
654       Read in a line-delimited file of labels.
655
656
657       --link-local-ip=ip
658
659
660       Not implemented.
661
662
663       --log-driver="driver"
664
665
666       Logging driver for  the  container.  Currently  available  options  are
667       k8s-file and journald, with json-file aliased to k8s-file for scripting
668       compatibility.
669
670
671       --log-opt=name=value
672
673
674       Set custom logging configuration. The following *name*s are  supported:
675       -   path:   specify   a   path   to   the  log  file  (e.g.   --log-opt
676       path=/var/log/container/mycontainer.json); - tag: specify a custom  log
677       tag  for  the  container (e.g.  --log-opt tag="{{.ImageName}}". It sup‐
678       ports the same keys as podman inspect --format.
679
680
681       This option is currently supported only by the journald log driver.
682
683
684       --mac-address=address
685
686
687       Container MAC address (e.g. 92:d0:c6:0a:29:33).
688
689
690       Remember that the MAC address in an Ethernet network  must  be  unique.
691       The  IPv6  link-local address will be based on the device's MAC address
692       according to RFC4862.
693
694
695       Not currently supported
696
697
698       --memory, -m=number[unit]
699
700
701       Memory limit. A unit can be b (bytes), k (kilobytes), m (megabytes), or
702       g (gigabytes).
703
704
705       Allows  you  to  constrain  the memory available to a container. If the
706       host supports swap memory, then the -m memory  setting  can  be  larger
707       than  physical  RAM.  If  a limit of 0 is specified (not using -m), the
708       container's memory is not limited. The actual limit may be  rounded  up
709       to  a  multiple of the operating system's page size (the value would be
710       very large, that's millions of trillions).
711
712
713       --memory-reservation=number[unit]
714
715
716       Memory  soft  limit.  A  unit  can  be  b  (bytes),  k  (kilobytes),  m
717       (megabytes), or g (gigabytes).
718
719
720       After  setting  memory reservation, when the system detects memory con‐
721       tention or low memory, containers are forced to restrict their consump‐
722       tion  to  their  reservation.  So you should always set the value below
723       --memory, otherwise the hard limit will take  precedence.  By  default,
724       memory reservation will be the same as memory limit.
725
726
727       --memory-swap=number[unit]
728
729
730       A  limit  value  equal to memory plus swap.  A unit can be b (bytes), k
731       (kilobytes), m (megabytes), or g (gigabytes).
732
733
734       Must be used with the  -m (--memory) flag.  The argument  value  should
735       always be larger than that of
736        -m (--memory).  By default, it is set to double the value of --memory.
737
738
739       Set number to -1 to enable unlimited swap.
740
741
742       --memory-swappiness=number
743
744
745       Tune  a  container's  memory  swappiness  behavior.  Accepts an integer
746       between 0 and 100.
747
748
749       --mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]
750
751
752       Attach a filesystem mount to the container
753
754
755       Current supported mount TYPEs are bind, volume, and tmpfs.
756
757
758                 e.g.
759
760                 type=bind,source=/path/on/host,destination=/path/in/container
761
762                 type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
763
764                 type=volume,source=vol1,destination=/path/in/container,ro=true
765
766                 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
767
768                 Common Options:
769
770                    · src, source: mount source spec for bind and volume. Mandatory for bind.
771
772                    · dst, destination, target: mount destination spec.
773
774                    · ro, read-only: true or false (default).
775
776                 Options specific to bind:
777
778                    · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2).
779
780                    . bind-nonrecursive: do not setup a recursive bind mount.  By default it is recursive.
781
782                    . relabel: shared, private.
783
784                 Options specific to tmpfs:
785
786                    · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
787
788                    · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
789
790                    · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs.  Used by default.
791
792                    · notmpcopyup: Disable copying files from the image to the tmpfs.
793
794
795
796       --name=name
797
798
799       Assign a name to the container.
800
801
802       The operator can identify a container in three ways:
803
804
805              · UUID                      long                      identifier
806                (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”);
807
808              · UUID short identifier (“f78375b1c487”);
809
810              · Name (“jonah”).
811
812
813
814       Podman generates a UUID for each  container,  and  if  a  name  is  not
815       assigned  to  the  container with --name then it will generate a random
816       string name. The name is useful any place you need to identify  a  con‐
817       tainer.  This works for both background and foreground containers.
818
819
820       --network, --net=mode
821
822
823       Set  the  network  mode  for  the  container.  Invalid  if using --dns,
824       --dns-opt, or --dns-search with --network that is set to none  or  con‐
825       tainer:id.
826
827
828       Valid mode values are:
829
830
831              · bridge: create a network stack on the default bridge;
832
833              · none: no networking;
834
835              · container:id: reuse another container's network stack;
836
837              · host:  use  the Podman host network stack. Note: the host mode
838                gives the container full access to local system services  such
839                as D-bus and is therefore considered insecure;
840
841              · network-id:  connect  to a user-defined network, multiple net‐
842                works should be comma separated;
843
844              · ns:path: path to a network namespace to join;
845
846              · private: create a new namespace for the container (default)
847
848              · slirp4netns: use  slirp4netns(1)  to  create  a  user  network
849                stack.  This is the default for rootless containers.
850
851
852
853       --network-alias=alias
854
855
856       Not implemented.
857
858
859       --no-healthcheck=true|false
860
861
862       Disable any defined healthchecks for container.
863
864
865       --no-hosts=true|false
866
867
868       Do not create /etc/hosts for the container.
869
870
871       By  default,  Podman will manage /etc/hosts, adding the container's own
872       IP address and any hosts from --add-host.   --no-hosts  disables  this,
873       and  the  image's /etc/hosts will be preserved unmodified.  This option
874       conflicts with --add-host.
875
876
877       --oom-kill-disable=true|false
878
879
880       Whether to disable OOM Killer for the container or not.
881
882
883       --oom-score-adj=num
884
885
886       Tune the host's OOM preferences for  containers  (accepts  values  from
887       -1000 to 1000).
888
889
890       --pid=mode
891
892
893       Set  the PID namespace mode for the container.  The efault is to create
894       a private PID namespace for the container.
895
896
897              · container:id: join another container's PID namespace;
898
899              · host: use the host's PID namespace for the container. Note the
900                host  mode gives the container full access to local PID and is
901                therefore considered insecure;
902
903              · private: create a new namespace for the container (default)
904
905              · ns:path: join the specified PID namespace.
906
907
908
909       --pids-limit=limit
910
911
912       Tune the container's pids limit. Set to 0 to have  unlimited  pids  for
913       the  container.  The  default  is  4096  on systems that support "pids"
914       cgroup controller.
915
916
917       --pod=name
918
919
920       Run container in an existing pod. If you want Podman to  make  the  pod
921       for you, prefix the pod name with new:.  To make a pod with more granu‐
922       lar options, use the podman pod create command before creating  a  con‐
923       tainer.   If  a  container  is  run  with  a  pod,  and  the pod has an
924       infra-container, the infra-container will be started  before  the  con‐
925       tainer is.
926
927
928       --privileged=true|false
929
930
931       Give extended privileges to this container. The default is false.
932
933
934       By default, Podman containers are unprivileged (=false) and cannot, for
935       example, modify parts of the operating  system.   This  is  because  by
936       default  a  container  is  only  allowed  limited access to devices.  A
937       "privileged" container is given the same access to devices as the  user
938       launching the container.
939
940
941       A privileged container turns off the security features that isolate the
942       container  from  the  host.  Dropped  Capabilities,  limited   devices,
943       read-only  mount  points, Apparmor/SELinux separation, and Seccomp fil‐
944       ters are all disabled.
945
946
947       Rootless containers cannot have more privileges than the  account  that
948       launched them.
949
950
951       --publish,  -p=ip:hostPort:containerPort  |  ip::containerPort  | host‐
952       Port:containerPort | containerPort
953
954
955       Publish a container's port, or range of ports, to the host.
956
957
958       Both hostPort and containerPort can be specified as a range of ports.
959
960
961       When specifying ranges for both, the number of container ports  in  the
962       range must match the number of host ports in the range.
963
964
965       Use podman port to see the actual mapping: podman port $CONTAINER $CON‐
966       TAINERPORT.
967
968
969       --publish-all, -P=true|false
970
971
972       Publish all exposed ports to random ports on the host  interfaces.  The
973       default is false.
974
975
976       When set to true, publish all exposed ports to the host interfaces. The
977       default is false. If the operator uses -P (or -p) then Podman will make
978       the exposed port accessible on the host and the ports will be available
979       to any client that can reach the host.
980
981
982       When using this option, Podman will bind any exposed port to  a  random
983       port   on   the   host  within  an  ephemeral  port  range  defined  by
984       /proc/sys/net/ipv4/ip_local_port_range.  To find  the  mapping  between
985       the host ports and the exposed ports, use podman port.
986
987
988       --pull=always|missing|never
989
990
991       Pull image before running. The default is missing.
992
993
994              · missing:  attempt to pull the latest image from the registries
995                listed  in  registries.conf  if  a  local   image   does   not
996                exist.Raise  an  error  if the image is not in any listed reg‐
997                istry and is not present locally.
998
999              · always: Pull the image from the first registry it is found  in
1000                as  listed in  registries.conf. Raise an error if not found in
1001                the registries, even if the image is present locally.
1002
1003              · never: do not pull the image from the registry, use  only  the
1004                local  version.  Raise  an  error  if the image is not present
1005                locally.
1006
1007
1008
1009       --quiet, -q
1010
1011
1012       Suppress output information when pulling images
1013
1014
1015       --read-only=true|false
1016
1017
1018       Mount the container's root filesystem as read only.
1019
1020
1021       By default a container will have its root filesystem writable  allowing
1022       processes to write files anywhere.  By specifying the --read-only flag,
1023       the container will have its root filesystem mounted as read  only  pro‐
1024       hibiting any writes.
1025
1026
1027       --read-only-tmpfs=true|false
1028
1029
1030       If  container  is  running in --read-only mode, then mount a read-write
1031       tmpfs on /run, /tmp, and /var/tmp. The default is true.
1032
1033
1034       --restart=policy
1035
1036
1037       Restart policy to follow when containers exit.  Restart policy will not
1038       take  effect  if  a  container is stopped via the podman kill or podman
1039       stop commands.
1040
1041
1042       Valid policy values are:
1043
1044
1045              · no: Do not restart containers on exit;
1046
1047              · on-failure[:max_retries]: Restart containers  when  they  exit
1048                with  a non-zero exit code, retrying indefinitely or until the
1049                optional max_retries count is hit;
1050
1051              · always: Restart containers when they exit, regardless of  sta‐
1052                tus, retrying indefinitely.
1053
1054
1055
1056       Please  note  that  restart  will not restart containers after a system
1057       reboot.  If this functionality is required in your environment, you can
1058       invoke Podman from a systemd.unit(5) file, or create an init script for
1059       whichever init system is in  use.   To  generate  systemd  unit  files,
1060       please see podman generate systemd.
1061
1062
1063       --rm=true|false
1064
1065
1066       Automatically remove the container when it exits. The default is false.
1067
1068
1069       Note  that  the container will not be removed when it could not be cre‐
1070       ated or started successfully. This allows the user to inspect the  con‐
1071       tainer after failure.
1072
1073
1074       --rmi=true|false
1075
1076
1077       After  exit of the container, remove the image unless another container
1078       is using it. The default is false.
1079
1080
1081       --rootfs
1082
1083
1084       If specified, the first argument refers to an exploded container on the
1085       file system.
1086
1087
1088       This  is  useful to run a container without requiring any image manage‐
1089       ment, the rootfs of the container is assumed to be managed externally.
1090
1091
1092       Note: On SELinux systems, the rootfs needs the correct label, which  is
1093       by default unconfined_u:object_r:container_file_t.
1094
1095
1096       --seccomp-policy=policy
1097
1098
1099       Specify the policy to select the seccomp profile. If set to image, Pod‐
1100       man will look for  a  "io.podman.seccomp.profile"  label  in  the  con‐
1101       tainer-image  config and use its value as a seccomp profile. Otherwise,
1102       Podman will follow the default policy by applying the  default  profile
1103       unless  specified  otherwise  via  --security-opt  seccomp as described
1104       below.
1105
1106
1107       Note that this feature is experimental and may change in the future.
1108
1109
1110       --security-opt=option
1111
1112
1113       Security Options
1114
1115
1116              · apparmor=unconfined : Turn off apparmor  confinement  for  the
1117                container
1118
1119              · apparmor=your-profile  :  Set the apparmor confinement profile
1120                for the container
1121
1122              · label=user:USER: Set the label user  for  the  container  pro‐
1123                cesses
1124
1125              · label=role:ROLE:  Set  the  label  role for the container pro‐
1126                cesses
1127
1128              · label=type:TYPE: Set the label process type for the  container
1129                processes
1130
1131              · label=level:LEVEL:  Set the label level for the container pro‐
1132                cesses
1133
1134              · label=filetype:TYPE_: Set the label file  type  for  the  con‐
1135                tainer files
1136
1137              · label=disable: Turn off label separation for the container
1138
1139              · no-new-privileges:  Disable  container  processes from gaining
1140                additional privileges
1141
1142              · seccomp=unconfined: Turn off seccomp confinement for the  con‐
1143                tainer
1144
1145              · seccomp=profile.json:   Whitelisted syscalls seccomp JSON file
1146                to be used as a seccomp filter
1147
1148
1149
1150       Note:  Labeling  can  be  disabled  for  all  containers   by   setting
1151       label=false in the libpod.conf(5) file.
1152
1153
1154       --shm-size=number[unit]
1155
1156
1157       Size  of  /dev/shm.  A  unit   can  be  b  (bytes),  k  (kilobytes),  m
1158       (megabytes), or g (gigabytes).  If you omit the unit, the  system  uses
1159       bytes. If you omit the size entirely, the default is 64m.  When size is
1160       0, there is no limit on the amount of memory used for IPC by  the  con‐
1161       tainer.
1162
1163
1164       --sig-proxy=true|false
1165
1166
1167       Sets  whether the signals sent to the podman run command are proxied to
1168       the container process. SIGCHLD, SIGSTOP, and SIGKILL are  not  proxied.
1169       The default is true.
1170
1171
1172       --stop-signal=signal
1173
1174
1175       Signal to stop a container. Default is SIGTERM.
1176
1177
1178       --stop-timeout=seconds
1179
1180
1181       Timeout to stop a container. Default is 10.
1182
1183
1184       --subgidname=name
1185
1186
1187       Run  the  container  in a new user namespace using the map with name in
1188       the /etc/subgid file.  If calling podman run as an  unprivileged  user,
1189       the  user  needs  to  have the right to use the mapping. See subgid(5).
1190       This flag conflicts with --userns and --gidmap.
1191
1192
1193       --subuidname=name
1194
1195
1196       Run the container in a new user namespace using the map  with  name  in
1197       the  /etc/subuid  file.  If calling podman run as an unprivileged user,
1198       the user needs to have the right to use  the  mapping.  See  subuid(5).
1199       This flag conflicts with --userns and --uidmap.
1200
1201
1202       --sysctl=name=value
1203
1204
1205       Configure namespaced kernel parameters at runtime.
1206
1207
1208       For the IPC namespace, the following sysctls are allowed:
1209
1210
1211              · kernel.msgmax
1212
1213              · kernel.msgmnb
1214
1215              · kernel.msgmni
1216
1217              · kernel.sem
1218
1219              · kernel.shmall
1220
1221              · kernel.shmmax
1222
1223              · kernel.shmmni
1224
1225              · kernel.shm_rmid_forced
1226
1227              · Sysctls beginning with fs.mqueue.*
1228
1229
1230
1231       Note:  if  you use the --ipc=host option, the above sysctls will not be
1232       allowed.
1233
1234
1235       For the network namespace, the following ysctls areallowed:
1236
1237
1238              · Sysctls beginning with net.*
1239
1240
1241
1242       Note: if you use the --network=host option, these sysctls will  not  be
1243       allowed.
1244
1245
1246       --systemd=true|false|always
1247
1248
1249       Run container in systemd mode. The default is true.
1250
1251
1252       The  value always enforces the systemd mode is enforced without looking
1253       at the executable name.  Otherwise, if set to true and the command  you
1254       are   running  inside  the  container  is  systemd,  /usr/sbin/init  or
1255       /sbin/init.
1256
1257
1258       If the command you are running inside of the container is systemd  Pod‐
1259       man will setup tmpfs mount points in the following directories:
1260
1261
1262              · /run
1263
1264              · /run/lock
1265
1266              · /tmp
1267
1268              · /sys/fs/cgroup/systemd
1269
1270              · /var/lib/journal
1271
1272
1273
1274       It will also set the default stop signal to SIGRTMIN+3.
1275
1276
1277       This  allows systemd to run in a confined container without any modifi‐
1278       cations.
1279
1280
1281       Note that on SELinux systems, systemd attempts to write to  the  cgroup
1282       file  system.   Containers writing to the cgroup file system are denied
1283       by default.  The container_manage_cgroup boolean must  be  enabled  for
1284       this to be allowed on an SELinux separated system.
1285
1286
1287              setsebool -P container_manage_cgroup true
1288
1289
1290
1291       --tmpfs=fs
1292
1293
1294       Create a tmpfs mount.
1295
1296
1297       Mount  a temporary filesystem (tmpfs) mount into a container, for exam‐
1298       ple:
1299
1300
1301              $ podman run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
1302
1303
1304
1305       This command mounts a tmpfs at /tmp within  the  container.   The  sup‐
1306       ported  mount options are the same as the Linux default mount flags. If
1307       you do not specify any options, the systems uses the following options:
1308       rw,noexec,nosuid,nodev.
1309
1310
1311       --tty, -t=true|false
1312
1313
1314       Allocate a pseudo-TTY. The default is false.
1315
1316
1317       When  set  to true, Podman will allocate a pseudo-tty and attach to the
1318       standard input of the container. This can be used, for example, to  run
1319       a throwaway interactive shell. The default is false.
1320
1321
1322       NOTE:  The  -t  option is incompatible with a redirection of the Podman
1323       client standard input.
1324
1325
1326       --uidmap=container_uid:host_uid:amount
1327
1328
1329       Run the container in a new user namespace using the  supplied  mapping.
1330       This  option  conflicts with the --userns and --subuidname flags.  This
1331       option can be passed several times to map different ranges. If  calling
1332       podman run as an unprivileged user, the user needs to have the right to
1333       use the mapping. See subuid(5).
1334
1335
1336       The following example maps uids 0-1999 in the  container  to  the  uids
1337       30000-31999 on the host: --uidmap=0:30000:2000.
1338
1339
1340       --ulimit=option
1341
1342
1343       Ulimit options. You can use host to copy the current configuration from
1344       the host.
1345
1346
1347       --user, -u=[user | user:group | uid | uid:gid | user:gid | uid:group ]
1348
1349
1350       Sets the username or UID used and optionally the groupname or  GID  for
1351       the specified command.
1352
1353
1354       Without this argument the command will be run as root in the container.
1355
1356
1357       --userns=auto|host|keep-id|container:id|ns:namespace
1358
1359
1360       Set the user namespace mode for the container.  It defaults to the POD‐
1361       MAN_USERNS environment variable.  An empty value means user  namespaces
1362       are disabled.
1363
1364
1365              · auto:  automatically  create  a  namespace.  It is possible to
1366                specify other options to  auto.   The  supported  options  are
1367                size=SIZE  to  specify an explicit size for the automatic user
1368                namespace.  e.g.  --userns=auto:size=8192.   If  size  is  not
1369                specified,  auto  will  guess  a  size for the user namespace.
1370                uidmapping=HOST_UID:CONTAINER_UID:SIZE to force a UID  mapping
1371                to be present in the user namespace.  gidmapping=HOST_UID:CON‐
1372                TAINER_UID:SIZE to force a GID mapping to be  present  in  the
1373                user namespace.
1374
1375              · host:  run  in  the  user namespace of the caller. This is the
1376                default if no user namespace options are  set.  The  processes
1377                running  in the container will have the same privileges on the
1378                host as any other process launched by the calling user.
1379
1380              · keep-id: creates a user namespace where the  current  rootless
1381                user's UID:GID are mapped to the same values in the container.
1382                This option is ignored for  containers  created  by  the  root
1383                user.
1384
1385              · ns: run the container in the given existing user namespace.
1386
1387              · private: create a new namespace for the container (default)
1388
1389              · container: join the user namespace of the specified container.
1390
1391
1392
1393       This  option  is  incompatible  with  --gidmap,  --uidmap, --subuid and
1394       --subgid.
1395
1396
1397       --uts=mode
1398
1399
1400       Set the UTS namespace mode for the container. The following values  are
1401       supported:
1402
1403
1404              · host: use the host's UTS namespace inside the container.
1405
1406              · private: create a new namespace for the container (default)
1407
1408              · ns: use own UTS namespace.
1409
1410
1411
1412       NOTE:  the  host mode gives the container access to changing the host's
1413       hostname and is therefore considered insecure.
1414
1415
1416       --volume, -v[=[[source-volume|host-dir:]container-dir[:options]]]
1417
1418
1419       Create a bind mount. If you  specify  /host-dir:/container-dir,  Podman
1420       bind  mounts  host-dir  in the host to container-dir in the Podman con‐
1421       tainer. Similarly, source-volume:/container-dir will mount  the  volume
1422       in  the  host  to the container. If no such named volume exists, Podman
1423       will create one.
1424
1425
1426       The options is a comma delimited list and can be:
1427
1428
1429              · rw|ro
1430
1431              · z|Z
1432
1433              · [r]shared|[r]slave|[r]private
1434
1435              · [r]bind
1436
1437              · [no]exec
1438
1439              · [no]dev
1440
1441              · [no]suid
1442
1443
1444
1445       The container-dir must be an absolute path.
1446
1447
1448       Volumes may specify a source as well, as either a directory on the host
1449       or  the  name of a named volume. If no source is given, the volume will
1450       be created as an anonymous named volume with a randomly generated name,
1451       and  will be removed when the container is removed via the --rm flag or
1452       podman rm --volumes.
1453
1454
1455       If a volume source is specified, it must be a path on the host  or  the
1456       name  of a named volume. Host paths are allowed to be absolute or rela‐
1457       tive; relative paths are resolved relative to the directory  Podman  is
1458       run in. Any source that does not begin with a . or / it will be treated
1459       as the name of a named volume.  If a volume with  that  name  does  not
1460       exist, it will be created. Volumes created with names are not anonymous
1461       and are not removed by --rm and podman rm --volumes.
1462
1463
1464       You can specify multiple  -v options to mount one or more volumes  into
1465       a container.
1466
1467
1468       You  can  add  :ro  or  :rw  option  to  mount a volume in read-only or
1469       read-write mode, respectively. By  default,  the  volumes  are  mounted
1470       read-write.
1471
1472
1473       Labeling  systems like SELinux require that proper labels are placed on
1474       volume content mounted into a container. Without a label, the  security
1475       system  might  prevent  the processes running inside the container from
1476       using the content. By default, Podman does not change the labels set by
1477       the OS.
1478
1479
1480       To  change  a label in the container context, you can add either of two
1481       suffixes :z or :Z to the volume mount. These suffixes  tell  Podman  to
1482       relabel  file  objects on the shared volumes. The z option tells Podman
1483       that two containers share the  volume  content.  As  a  result,  Podman
1484       labels  the  content  with a shared content label. Shared volume labels
1485       allow all containers to read/write content.  The Z option tells  Podman
1486       to  label  the content with a private unshared label.  Only the current
1487       container can use a private volume.
1488
1489
1490       By default bind mounted volumes are private. That means any mounts done
1491       inside  container  will  not be visible on host and vice versa. One can
1492       change this behavior by specifying a volume mount propagation property.
1493       Making  a  volume shared mounts done under that volume inside container
1494       will be visible on host and vice versa. Making a volume  slave  enables
1495       only  one  way  mount propagation and that is mounts done on host under
1496       that volume will be visible inside container  but  not  the  other  way
1497       around.
1498
1499
1500       To  control mount propagation property of volume one can use [r]shared,
1501       [r]slave or [r]private propagation flag. Propagation  property  can  be
1502       specified only for bind mounted volumes and not for internal volumes or
1503       named volumes. For mount propagation to work source mount point  (mount
1504       point  where  source  dir  is mounted on) has to have right propagation
1505       properties. For shared volumes, source mount point has  to  be  shared.
1506       And for slave volumes, source mount has to be either shared or slave.
1507
1508
1509       If you want to recursively mount a volume and all of its submounts into
1510       a container, then you can use the rbind option.  By  default  the  bind
1511       option  is  used,  and  submounts  of  the source directory will not be
1512       mounted into the container.
1513
1514
1515       Mounting the volume with the nosuid options means  that  SUID  applica‐
1516       tions  on  the  volume  will  not be able to change their privilege. By
1517       default volumes are mounted with nosuid.
1518
1519
1520       Mounting the volume with the noexec option means that no executables on
1521       the volume will be able to executed within the container.
1522
1523
1524       Mounting  the volume with the nodev option means that no devices on the
1525       volume will be able to be used by processes within  the  container.  By
1526       default volumes are mounted with nodev.
1527
1528
1529       If  the host-dir is a mount point, then dev, suid, and exec options are
1530       ignored by the kernel.
1531
1532
1533       Use df $hostdir to figure out the source mount, and then use findmnt -o
1534       TARGET,PROPAGATION  source-mount-dir  to figure out propagation proper‐
1535       ties of source mount. If findmnt(1) utility is not available, then  one
1536       can look at mount entry for source mount point in /proc/self/mountinfo.
1537       Look at the "optional fields" and see if any propagation properties are
1538       specified.   In  there,  shared:N  means  the mount is shared, master:N
1539       means mount is slave, and if nothing is there, the mount is private.
1540
1541
1542       To change propagation properties of a mount point,  use  mount(8)  com‐
1543       mand.  For  example,  if one wants to bind mount source directory /foo,
1544       one  can  do  mount  --bind  /foo   /foo   and   mount   --make-private
1545       --make-shared  /foo.  This will convert /foo into a shared mount point.
1546       Alternatively, one can directly change propagation properties of source
1547       mount. Say, if / is source mount for /foo, then use mount --make-shared
1548       / to convert / into a shared mount.
1549
1550
1551       --volumes-from[=container-id[:options]]
1552
1553
1554       Mount volumes from the specified container(s). Used  to  share  volumes
1555       between containers. The options is a comma delimited list with the fol‐
1556       lowing available elements:
1557
1558
1559              · rw|ro
1560
1561              · z
1562
1563
1564
1565       You can share volumes even if the source container is not running.
1566
1567
1568       By default, Podman mounts the volumes in the same mode  (read-write  or
1569       read-only)  as  it  is mounted in the source container.  You can change
1570       this by adding a ro or rw option.
1571
1572
1573       Labeling systems like SELinux require that proper labels are placed  on
1574       volume  content mounted into a container. Without a label, the security
1575       system might prevent the processes running inside  the  container  from
1576       using the content. By default, Podman does not change the labels set by
1577       the OS.
1578
1579
1580       To change a label in the container context, you can add z to the volume
1581       mount.   This suffix tells Podman to relabel file objects on the shared
1582       volumes. The z option tells Podman that two containers share the volume
1583       content.  As  a result, podman labels the content with a shared content
1584       label. Shared volume labels allow all containers to read/write content.
1585
1586
1587       If the location of the volume from the source container  overlaps  with
1588       data residing on a target container, then the volume hides that data on
1589       the target.
1590
1591
1592       --workdir, -w=dir
1593
1594
1595       Working directory inside the container.
1596
1597
1598       The default working directory for running binaries within  a  container
1599       is  the  root  directory  (/).  The image developer can set a different
1600       default with the WORKDIR instruction. The  operator  can  override  the
1601       working directory by using the -w option.
1602
1603

Exit Status

1605       The exit code from podman run gives information about why the container
1606       failed to run or why it exited.  When podman run exits with a  non-zero
1607       code, the exit codes follow the chroot(1) standard, see below:
1608
1609
1610       125 The error is with Podman itself
1611
1612
1613              $ podman run --foo busybox; echo $?
1614              Error: unknown flag: --foo
1615              125
1616
1617
1618
1619       126 The contained command cannot be invoked
1620
1621
1622              $ podman run busybox /etc; echo $?
1623              Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error
1624              126
1625
1626
1627
1628       127 The contained command cannot be found
1629
1630
1631              $ podman run busybox foo; echo $?
1632              Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error
1633              127
1634
1635
1636
1637       Exit code contained command exit code
1638
1639
1640              $ podman run busybox /bin/sh -c 'exit 3'
1641              3
1642
1643
1644

EXAMPLES

1646   Running container in read-only mode
1647       During  container  image development, containers often need to write to
1648       the image content.  Installing packages into  /usr,  for  example.   In
1649       production,  applications seldom need to write to the image.  Container
1650       applications write to volumes if they need to write to file systems  at
1651       all.  Applications can be made more secure by running them in read-only
1652       mode using the --read-only switch.  This protects the containers  image
1653       from  modification. Read only containers may still need to write tempo‐
1654       rary data.  The best way to handle this is to mount  tmpfs  directories
1655       on /run and /tmp.
1656
1657
1658              $ podman run --read-only -i -t fedora /bin/bash
1659
1660              $ podman run --read-only --read-only-tmpfs=false --tmpfs /run -i -t fedora /bin/bash
1661
1662
1663
1664   Exposing log messages from the container to the host's log
1665       If  you  want  messages that are logged in your container to show up in
1666       the host's syslog/journal then  you  should  bind  mount  the  /dev/log
1667       directory as follows.
1668
1669
1670              $ podman run -v /dev/log:/dev/log -i -t fedora /bin/bash
1671
1672
1673
1674       From inside the container you can test this by sending a message to the
1675       log.
1676
1677
1678              (bash)# logger "Hello from my container"
1679
1680
1681
1682       Then exit and check the journal.
1683
1684
1685              (bash)# exit
1686
1687              $ journalctl -b | grep Hello
1688
1689
1690
1691       This should list the message sent to logger.
1692
1693
1694   Attaching to one or more from STDIN, STDOUT, STDERR
1695       If you do not specify -a, Podman will attach everything (stdin, stdout,
1696       stderr).   You  can  specify  to  which  of  the three standard streams
1697       (stdin, stdout, stderr) you'd like to connect instead, as in:
1698
1699
1700              $ podman run -a stdin -a stdout -i -t fedora /bin/bash
1701
1702
1703

Sharing IPC between containers

1705       Using             shm_server.c             available              here:
1706       https://www.cs.cf.ac.uk/Dave/C/node27.html
1707
1708
1709       Testing --ipc=host mode:
1710
1711
1712       Host  shows a shared memory segment with 7 pids attached, happens to be
1713       from httpd:
1714
1715
1716              $ sudo ipcs -m
1717
1718              ------ Shared Memory Segments --------
1719              key        shmid      owner      perms      bytes      nattch     status
1720              0x01128e25 0          root       600        1000       7
1721
1722
1723
1724       Now run a regular container, and it correctly does NOT see  the  shared
1725       memory segment from the host:
1726
1727
1728              $ podman run -it shm ipcs -m
1729
1730              ------ Shared Memory Segments --------
1731              key        shmid      owner      perms      bytes      nattch     status
1732
1733
1734
1735       Run  a  container  with  the new --ipc=host option, and it now sees the
1736       shared memory segment from the host httpd:
1737
1738
1739              $ podman run -it --ipc=host shm ipcs -m
1740
1741              ------ Shared Memory Segments --------
1742              key        shmid      owner      perms      bytes      nattch     status
1743              0x01128e25 0          root       600        1000       7
1744
1745
1746
1747       Testing --ipc=container:id mode:
1748
1749
1750       Start a container with a program to create a shared memory segment:
1751
1752
1753              $ podman run -it shm bash
1754              $ sudo shm/shm_server
1755              $ sudo ipcs -m
1756
1757              ------ Shared Memory Segments --------
1758              key        shmid      owner      perms      bytes      nattch     status
1759              0x0000162e 0          root       666        27         1
1760
1761
1762
1763       Create a 2nd container correctly shows no shared  memory  segment  from
1764       1st container:
1765
1766
1767              $ podman run shm ipcs -m
1768
1769              ------ Shared Memory Segments --------
1770              key        shmid      owner      perms      bytes      nattch     status
1771
1772
1773
1774       Create  a  3rd  container  using  the --ipc=container:id option, now it
1775       shows the shared memory segment from the first:
1776
1777
1778              $ podman run -it --ipc=container:ed735b2264ac shm ipcs -m
1779              $ sudo ipcs -m
1780
1781              ------ Shared Memory Segments --------
1782              key        shmid      owner      perms      bytes      nattch     status
1783              0x0000162e 0          root       666        27         1
1784
1785
1786
1787   Mapping Ports for External Usage
1788       The exposed port of an application can be mapped to a host  port  using
1789       the  -p  flag.  For example, an httpd port 80 can be mapped to the host
1790       port 8080 using the following:
1791
1792
1793              $ podman run -p 8080:80 -d -i -t fedora/httpd
1794
1795
1796
1797   Mounting External Volumes
1798       To mount a host directory as a container volume, specify  the  absolute
1799       path to the directory and the absolute path for the container directory
1800       separated by a colon. If the source is a  named  volume  maintained  by
1801       Podman,  it's  recommended to use it's name rather than the path to the
1802       volume. Otherwise the volume will be considered as an orphan and  wiped
1803       if you execute podman volume prune:
1804
1805
1806              $ podman run -v /var/db:/data1 -i -t fedora bash
1807
1808              $ podman run -v data:/data2 -i -t fedora bash
1809
1810
1811
1812       Using  --mount  flags  to mount a host directory as a container folder,
1813       specify the absolute path to the directory or the volume name, and  the
1814       absolute path within the container directory:
1815
1816
1817              $ podman run --mount type=bind,src=/var/db,target=/data1 busybox sh
1818
1819              $ podman run --mount type=bind,src=volume-name,target=/data1 busybox sh
1820
1821
1822
1823       When  using  SELinux,  be  aware that the host has no knowledge of con‐
1824       tainer SELinux policy. Therefore, in the above example, if SELinux pol‐
1825       icy  is  enforced,  the  /var/db  directory is not writable to the con‐
1826       tainer. A "Permission Denied" message will occur and an avc: message in
1827       the host's syslog.
1828
1829
1830       To  work  around  this, at time of writing this man page, the following
1831       command needs to be run in order for the  proper  SELinux  policy  type
1832       label to be attached to the host directory:
1833
1834
1835              $ chcon -Rt svirt_sandbox_file_t /var/db
1836
1837
1838
1839       Now,  writing to the /data1 volume in the container will be allowed and
1840       the changes will also be reflected on the host in /var/db.
1841
1842
1843   Using alternative security labeling
1844       You can override the default labeling  scheme  for  each  container  by
1845       specifying  the  --security-opt  flag. For example, you can specify the
1846       MCS/MLS level, a requirement for MLS systems. Specifying the  level  in
1847       the following command allows you to share the same content between con‐
1848       tainers.
1849
1850
1851              podman run --security-opt label=level:s0:c100,c200 -i -t fedora bash
1852
1853
1854
1855       An MLS example might be:
1856
1857
1858              $ podman run --security-opt label=level:TopSecret -i -t rhel7 bash
1859
1860
1861
1862       To disable the security labeling for this container versus running with
1863       the --permissive flag, use the following command:
1864
1865
1866              $ podman run --security-opt label=disable -i -t fedora bash
1867
1868
1869
1870       If  you  want  a tighter security policy on the processes within a con‐
1871       tainer, you can specify an alternate type for the container. You  could
1872       run  a container that is only allowed to listen on Apache ports by exe‐
1873       cuting the following command:
1874
1875
1876              $ podman run --security-opt label=type:svirt_apache_t -i -t centos bash
1877
1878
1879
1880       Note you would have to write policy defining a svirt_apache_t type.
1881
1882
1883   Setting device weight
1884       If you want to set /dev/sda device weight to 200, you can  specify  the
1885       device weight by --blkio-weight-device flag. Use the following command:
1886
1887
1888              $ podman run -it --blkio-weight-device "/dev/sda:200" ubuntu
1889
1890
1891
1892   Setting Namespaced Kernel Parameters (Sysctls)
1893       The  --sysctl  sets  namespaced kernel parameters (sysctls) in the con‐
1894       tainer. For example, to turn on IP forwarding in the containers network
1895       namespace, run this command:
1896
1897
1898              $ podman run --sysctl net.ipv4.ip_forward=1 someimage
1899
1900
1901
1902       Note  that  not  all  sysctls  are  namespaced. Podman does not support
1903       changing sysctls inside of a container that also modify the  host  sys‐
1904       tem.  As the kernel evolves we expect to see more sysctls become names‐
1905       paced.
1906
1907
1908       See the definition of the --sysctl option above for the current list of
1909       supported sysctls.
1910
1911
1912   Set UID/GID mapping in a new user namespace
1913       Running  a  container in a new user namespace requires a mapping of the
1914       uids and gids from the host.
1915
1916
1917              $ podman run --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
1918
1919
1920
1921   Configuring Storage Options from the command line
1922       Podman allows for the configuration of storage by changing  the  values
1923       in  the  /etc/container/storage.conf  or by using global options.  This
1924       shows how to setup and use fuse-overlayfs for a one time run of busybox
1925       using global options.
1926
1927
1928              podman --log-level=debug --storage-driver overlay --storage-opt "overlay.mount_program=/usr/bin/fuse-overlayfs" run busybox /bin/sh
1929
1930
1931
1932   Rootless Containers
1933       Podman  runs  as a non root user on most systems. This feature requires
1934       that  a  new  enough  version  of  shadow-utils  be   installed.    The
1935       shadow-utils  package  must  include  the newuidmap(1) and newgidmap(1)
1936       executables.
1937
1938
1939       Note: RHEL7 and Centos 7 will not have this feature  until  RHEL7.7  is
1940       released.
1941
1942
1943       In  order  for  users to run rootless, there must be an entry for their
1944       username in /etc/subuid and /etc/subgid which lists the UIDs for  their
1945       user namespace.
1946
1947
1948       Rootless  Podman  works  better  if  the fuse-overlayfs and slirp4netns
1949       packages are installed.  The fuse-overlay package provides a  userspace
1950       overlay  storage  driver,  otherwise  users need to use the vfs storage
1951       driver, which  is  diskspace  expensive  and  does  not  perform  well.
1952       slirp4netns  is  required for VPN, without it containers need to be run
1953       with the --network=host flag.
1954
1955

ENVIRONMENT

1957       Environment variables within containers can be set using multiple  dif‐
1958       ferent options, in the following order of precedence:
1959
1960
1961              · --env-host:  Host  environment of the process executing Podman
1962                is added.
1963
1964              · Container image: Any environment variables  specified  in  the
1965                container image.
1966
1967              · --env-file: Any environment variables specified via env-files.
1968                If multiple files specified, then they override each other  in
1969                order of entry.
1970
1971              · --env:  Any environment variables specified will override pre‐
1972                vious settings.
1973
1974
1975
1976       Run containers and set the environment ending with a * and a *****:
1977
1978
1979              $ export ENV1=a
1980              $ podman run --env ENV* alpine printenv ENV1
1981              a
1982
1983              $ podman run --env ENV*****=b alpine printenv ENV*****
1984              b
1985
1986
1987

FILES

1989       /etc/subuid
1990
1991
1992       /etc/subgid
1993
1994
1995       NOTE: Use the environment variable TMPDIR to change the temporary stor‐
1996       age  location  of  downloaded  container images. Podman defaults to use
1997       /var/tmp.
1998
1999

SEE ALSO

2001       subgid(5), subuid(5),  libpod.conf(5),  systemd.unit(5),  setsebool(8),
2002       slirp4netns(1), fuse-overlayfs(1).
2003
2004

HISTORY

2006       September 2018, updated by Kunal Kushwaha
2007
2008
2009       October  2017,  converted  from  Docker  documentation to Podman by Dan
2010       Walsh for Podman dwalsh@redhat.com ⟨mailto:dwalsh@redhat.com⟩
2011
2012
2013       November  2015,   updated   by   Sally   O'Malley   somalley@redhat.com
2014       ⟨mailto:somalley@redhat.com⟩
2015
2016
2017       July   2014,   updated   by   Sven   Dowideit  SvenDowideit@home.org.au
2018       ⟨mailto:SvenDowideit@home.org.au⟩
2019
2020
2021       June  2014,   updated   by   Sven   Dowideit   SvenDowideit@home.org.au
2022       ⟨mailto:SvenDowideit@home.org.au⟩
2023
2024
2025       April  2014,  Originally  compiled  by  William Henry whenry@redhat.com
2026       ⟨mailto:whenry@redhat.com⟩ based  on  docker.com  source  material  and
2027       internal work.
2028
2029
2030
2031                                                               podman-run(1)()
Impressum