1podman-run(1)               General Commands Manual              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

DESCRIPTION

14       Run a process in a new container. podman run starts a process with its
15       own file system, its own networking, and its own isolated process tree.
16       The IMAGE which starts the process may define defaults related to the
17       process that will be run in the container, the networking to expose,
18       and more, but podman run gives final control to the operator or
19       administrator who starts the container from the image. For that reason
20       podman run has more options than any other podman command.
21
22
23       If the IMAGE is not already loaded then podman run will pull the IMAGE,
24       and all image dependencies, from the repository in the same way running
25       podman pull IMAGE, before it starts the container from that image.
26
27
28       Several files will be automatically created within the container. These
29       include /etc/hosts, /etc/hostname, and /etc/resolv.conf to manage
30       networking.  These will be based on the host's version of the files,
31       though they can be customized with options (for example, --dns will
32       override the host's DNS servers in the created resolv.conf).
33       Additionally, an empty file is created in each container to indicate to
34       programs they are running in a container. This file is located at
35       /run/.containerenv.
36
37
38       When running from a user defined network namespace, the
39       /etc/netns/NSNAME/resolv.conf will be used if it exists, otherwise
40       /etc/resolv.conf will be used.
41
42

OPTIONS

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

Exit Status

1369       The exit code from podman run gives information about why the container
1370       failed to run or why it exited.  When podman run exits with a non-zero
1371       code, the exit codes follow the chroot standard, see below:
1372
1373
1374       125 if the error is with podman itself
1375
1376
1377              $ podman run --foo busybox; echo $?
1378              # flag provided but not defined: --foo
1379                See 'podman run --help'.
1380                125
1381
1382
1383
1384       126 if the contained command cannot be invoked
1385
1386
1387              $ podman run busybox /etc; echo $?
1388              # exec: "/etc": permission denied
1389                podman: Error response from daemon: Contained command could not be invoked
1390                126
1391
1392
1393
1394       127 if the contained command cannot be found
1395
1396
1397              $ podman run busybox foo; echo $?
1398              # exec: "foo": executable file not found in $PATH
1399                podman: Error response from daemon: Contained command not found or does not exist
1400                127
1401
1402
1403
1404       Exit code of contained command otherwise
1405
1406
1407              $ podman run busybox /bin/sh -c 'exit 3'
1408              # 3
1409
1410
1411

EXAMPLES

1413   Running container in read-only mode
1414       During container image development, containers often need to write to
1415       the image content.  Installing packages into /usr, for example.  In
1416       production, applications seldom need to write to the image.  Container
1417       applications write to volumes if they need to write to file systems at
1418       all.  Applications can be made more secure by running them in read-only
1419       mode using the --read-only switch.  This protects the containers image
1420       from modification. Read only containers may still need to write
1421       temporary data.  The best way to handle this is to mount tmpfs
1422       directories on /run and /tmp.
1423
1424
1425              $ podman run --read-only -i -t fedora /bin/bash
1426
1427
1428
1429              $ podman run --read-only --read-only-tmpfs=false --tmpfs /run -i -t fedora /bin/bash
1430
1431
1432
1433   Exposing log messages from the container to the host's log
1434       If you want messages that are logged in your container to show up in
1435       the host's syslog/journal then you should bind mount the /dev/log
1436       directory as follows.
1437
1438
1439              $ podman run -v /dev/log:/dev/log -i -t fedora /bin/bash
1440
1441
1442
1443       From inside the container you can test this by sending a message to the
1444       log.
1445
1446
1447              (bash)# logger "Hello from my container"
1448
1449
1450
1451       Then exit and check the journal.
1452
1453
1454              (bash)# exit
1455
1456              $ journalctl -b | grep Hello
1457
1458
1459
1460       This should list the message sent to logger.
1461
1462
1463   Attaching to one or more from STDIN, STDOUT, STDERR
1464       If you do not specify -a then podman will attach everything
1465       (stdin,stdout,stderr).  You can specify to which of the three standard
1466       streams (stdin, stdout, stderr) you'd like to connect instead, as in:
1467
1468
1469              $ podman run -a stdin -a stdout -i -t fedora /bin/bash
1470
1471
1472

Sharing IPC between containers

1474       Using shm_server.c available here:
1475https://www.cs.cf.ac.uk/Dave/C/node27.html
1476
1477
1478       Testing --ipc=host mode:
1479
1480
1481       Host shows a shared memory segment with 7 pids attached, happens to be
1482       from httpd:
1483
1484
1485              $ sudo ipcs -m
1486
1487              ------ Shared Memory Segments --------
1488              key        shmid      owner      perms      bytes      nattch     status
1489              0x01128e25 0          root       600        1000       7
1490
1491
1492
1493       Now run a regular container, and it correctly does NOT see the shared
1494       memory segment from the host:
1495
1496
1497              $ podman run -it shm ipcs -m
1498
1499              ------ Shared Memory Segments --------
1500              key        shmid      owner      perms      bytes      nattch     status
1501
1502
1503
1504       Run a container with the new --ipc=host option, and it now sees the
1505       shared memory segment from the host httpd:
1506
1507
1508              $ podman run -it --ipc=host shm ipcs -m
1509
1510              ------ Shared Memory Segments --------
1511              key        shmid      owner      perms      bytes      nattch     status
1512              0x01128e25 0          root       600        1000       7
1513
1514
1515
1516       Testing --ipc=container:CONTAINERID mode:
1517
1518
1519       Start a container with a program to create a shared memory segment:
1520
1521
1522              $ podman run -it shm bash
1523              $ sudo shm/shm_server
1524              $ sudo ipcs -m
1525
1526              ------ Shared Memory Segments --------
1527              key        shmid      owner      perms      bytes      nattch     status
1528              0x0000162e 0          root       666        27         1
1529
1530
1531
1532       Create a 2nd container correctly shows no shared memory segment from
1533       1st container:
1534
1535
1536              $ podman run shm ipcs -m
1537
1538              ------ Shared Memory Segments --------
1539              key        shmid      owner      perms      bytes      nattch     status
1540
1541
1542
1543       Create a 3rd container using the new --ipc=container:CONTAINERID
1544       option, now it shows the shared memory segment from the first:
1545
1546
1547              $ podman run -it --ipc=container:ed735b2264ac shm ipcs -m
1548              $ sudo ipcs -m
1549
1550              ------ Shared Memory Segments --------
1551              key        shmid      owner      perms      bytes      nattch     status
1552              0x0000162e 0          root       666        27         1
1553
1554
1555
1556   Mapping Ports for External Usage
1557       The exposed port of an application can be mapped to a host port using
1558       the -p flag. For example, an httpd port 80 can be mapped to the host
1559       port 8080 using the following:
1560
1561
1562              $ podman run -p 8080:80 -d -i -t fedora/httpd
1563
1564
1565
1566   Mounting External Volumes
1567       To mount a host directory as a container volume, specify the absolute
1568       path to the directory and the absolute path for the container directory
1569       separated by a colon:
1570
1571
1572              $ podman run -v /var/db:/data1 -i -t fedora bash
1573
1574
1575
1576       Using --mount flags, To mount a host directory as a container folder,
1577       specify the absolute path to the directory and the absolute path for
1578       the container directory:
1579
1580
1581       $ podman run --mount type=bind,src=/var/db,target=/data1 busybox sh
1582
1583
1584       When using SELinux, be aware that the host has no knowledge of
1585       container SELinux policy. Therefore, in the above example, if SELinux
1586       policy is enforced, the /var/db directory is not writable to the
1587       container. A "Permission Denied" message will occur and an avc: message
1588       in the host's syslog.
1589
1590
1591       To work around this, at time of writing this man page, the following
1592       command needs to be run in order for the proper SELinux policy type
1593       label to be attached to the host directory:
1594
1595
1596              $ chcon -Rt svirt_sandbox_file_t /var/db
1597
1598
1599
1600       Now, writing to the /data1 volume in the container will be allowed and
1601       the changes will also be reflected on the host in /var/db.
1602
1603
1604   Using alternative security labeling
1605       You can override the default labeling scheme for each container by
1606       specifying the --security-opt flag. For example, you can specify the
1607       MCS/MLS level, a requirement for MLS systems. Specifying the level in
1608       the following command allows you to share the same content between
1609       containers.
1610
1611
1612              podman run --security-opt label=level:s0:c100,c200 -i -t fedora bash
1613
1614
1615
1616       An MLS example might be:
1617
1618
1619              $ podman run --security-opt label=level:TopSecret -i -t rhel7 bash
1620
1621
1622
1623       To disable the security labeling for this container versus running with
1624       the --permissive flag, use the following command:
1625
1626
1627              $ podman run --security-opt label=disable -i -t fedora bash
1628
1629
1630
1631       If you want a tighter security policy on the processes within a
1632       container, you can specify an alternate type for the container. You
1633       could run a container that is only allowed to listen on Apache ports by
1634       executing the following command:
1635
1636
1637              $ podman run --security-opt label=type:svirt_apache_t -i -t centos bash
1638
1639
1640
1641       Note:
1642
1643
1644       You would have to write policy defining a svirt_apache_t type.
1645
1646
1647   Setting device weight
1648       If you want to set /dev/sda device weight to 200, you can specify the
1649       device weight by --blkio-weight-device flag. Use the following command:
1650
1651
1652              $ podman run -it --blkio-weight-device "/dev/sda:200" ubuntu
1653
1654
1655
1656   Setting Namespaced Kernel Parameters (Sysctls)
1657       The --sysctl sets namespaced kernel parameters (sysctls) in the
1658       container. For example, to turn on IP forwarding in the containers
1659       network namespace, run this command:
1660
1661
1662              $ podman run --sysctl net.ipv4.ip_forward=1 someimage
1663
1664
1665
1666       Note:
1667
1668
1669       Not all sysctls are namespaced. podman does not support changing
1670       sysctls inside of a container that also modify the host system. As the
1671       kernel evolves we expect to see more sysctls become namespaced.
1672
1673
1674       See the definition of the --sysctl option above for the current list of
1675       supported sysctls.
1676
1677
1678   Set UID/GID mapping in a new user namespace
1679       Running a container in a new user namespace requires a mapping of the
1680       uids and gids from the host.
1681
1682
1683              $ podman run --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
1684
1685
1686
1687   Configuring Storage Options from the command line
1688       Podman allows for the configuration of storage by changing the values
1689       in the /etc/container/storage.conf or by using global options.  This
1690       shows how to setup and use fuse-overlayfs for a one time run of busybox
1691       using global options.
1692
1693
1694       podman --log-level=debug --storage-driver overlay --storage-opt
1695       "overlay.mount_program=/usr/bin/fuse-overlayfs" run busybox /bin/sh
1696
1697
1698   Rootless Containers
1699       Podman runs as a non root user on most systems. This feature requires
1700       that a new enough version of shadow-utils be installed.  The
1701       shadow-utils package must include the newuidmap and newgidmap
1702       executables.
1703
1704
1705       Note: RHEL7 and Centos 7 will not have this feature until RHEL7.7 is
1706       released.
1707
1708
1709       In order for users to run rootless, there must be an entry for their
1710       username in /etc/subuid and /etc/subgid which lists the UIDs for their
1711       user namespace.
1712
1713
1714       Rootless podman works better if the fuse-overlayfs and slirp4netns
1715       packages are installed.  The fuse-overlay package provides a userspace
1716       overlay storage driver, otherwise users need to use the vfs storage
1717       driver, which is diskspace expensive and does not perform well.
1718       slirp4netns is required for VPN, without it containers need to be run
1719       with the --net=host flag.
1720
1721

FILES

1723       /etc/subuid /etc/subgid
1724
1725

SEE ALSO

1727       subgid(5), subuid(5), libpod.conf(5), systemd.unit(5), setsebool(8),
1728       slirp4netns(1), fuse-overlayfs(1)
1729
1730

HISTORY

1732       September 2018, updated by Kunal Kushwaha
1733       <kushwaha_kunal_v7@lab.ntt.co.jp>
1734
1735
1736       October 2017, converted from Docker documentation to podman by Dan
1737       Walsh for podman ⟨dwalsh@redhat.com⟩
1738
1739
1740       November 2015, updated by Sally O'Malley ⟨somalley@redhat.com⟩
1741
1742
1743       July 2014, updated by Sven Dowideit ⟨SvenDowideit@home.org.au⟩
1744
1745
1746       June 2014, updated by Sven Dowideit ⟨SvenDowideit@home.org.au⟩
1747
1748
1749       April 2014, Originally compiled by William Henry ⟨whenry@redhat.com⟩
1750       based on docker.com source material and internal work.
1751
1752
1753
1754                                                                 podman-run(1)
Impressum