1DOCKER(1) Docker User Manuals DOCKER(1)
2
6 docker-run - Run a command in a new container
7
11 docker run [-a|--attach[=[]]] [--add-host[=[]]] [--blkio-
12 weight[=[BLKIO-WEIGHT]]] [--blkio-weight-device[=[]]] [--cpu-
13 shares[=0]] [--cap-add[=[]]] [--cap-drop[=[]]] [--cgroupns[=[]]]
14 [--cgroup-parent[=CGROUP-PATH]] [--cidfile[=CIDFILE]] [--cpu-count[=0]]
15 [--cpu-percent[=0]] [--cpu-period[=0]] [--cpu-quota[=0]] [--cpu-rt-pe‐
16 riod[=0]] [--cpu-rt-runtime[=0]] [--cpus[=0.0]] [--cpuset-cpus[=CPUSET-
17 CPUS]] [--cpuset-mems[=CPUSET-MEMS]] [-d|--detach] [--detach-keys[=[]]]
18 [--device[=[]]] [--device-cgroup-rule[=[]]] [--device-read-bps[=[]]]
19 [--device-read-iops[=[]]] [--device-write-bps[=[]]] [--device-write-
20 iops[=[]]] [--dns[=[]]] [--dns-option[=[]]] [--dns-search[=[]]] [--do‐
21 mainname[=DOMAINNAME]] [-e|--env[=[]]] [--entrypoint[=ENTRYPOINT]]
22 [--env-file[=[]]] [--expose[=[]]] [--group-add[=[]]] [-h|--host‐
23 name[=HOSTNAME]] [--help] [--init] [-i|--interactive] [--ip[=IPv4-AD‐
24 DRESS]] [--ip6[=IPv6-ADDRESS]] [--ipc[=IPC]] [--isolation[=default]]
25 [--kernel-memory[=KERNEL-MEMORY]] [-l|--label[=[]]] [--label-file[=[]]]
26 [--link[=[]]] [--link-local-ip[=[]]] [--log-driver[=[]]] [--log-
27 opt[=[]]] [-m|--memory[=MEMORY]] [--mac-address[=MAC-ADDRESS]] [--mem‐
28 ory-reservation[=MEMORY-RESERVATION]] [--memory-swap[=LIMIT]] [--mem‐
29 ory-swappiness[=MEMORY-SWAPPINESS]] [--mount[=[MOUNT]]] [--name[=NAME]]
30 [--network-alias[=[]]] [--network[="bridge"]] [--oom-kill-disable]
31 [--oom-score-adj[=0]] [-P|--publish-all] [-p|--publish[=[]]]
32 [--pid[=[PID]]] [--userns[=[]]] [--pids-limit[=PIDS_LIMIT]] [--privi‐
33 leged] [--read-only] [--restart[=RESTART]] [--rm] [--security-opt[=[]]]
34 [--storage-opt[=[]]] [--stop-signal[=SIGNAL]] [--stop-timeout[=TIME‐
35 OUT]] [--shm-size[=[]]] [--sig-proxy[=true]] [--sysctl[=[]]] [-t|--tty]
36 [--tmpfs[=[CONTAINER-DIR[:OPTIONS]]] [-u|--user[=USER]] [--ulimit[=[]]]
37 [--uts[=[]]] [-v|--volume[=[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]]]
38 [--volume-driver[=DRIVER]] [--volumes-from[=[]]]
39 [-w|--workdir[=WORKDIR]] IMAGE [COMMAND] [ARG...]
40
44 Run a process in a new container. docker run starts a process with its
45 own file system, its own networking, and its own isolated process tree.
46 The IMAGE which starts the process may define defaults related to the
47 process that will be run in the container, the networking to expose,
48 and more, but docker run gives final control to the operator or admin‐
49 istrator who starts the container from the image. For that reason
50 docker run has more options than any other Docker command.
51 If the IMAGE is not already loaded then docker run will pull the IMAGE,
54 and all image dependencies, from the repository in the same way running
55 docker pull IMAGE, before it starts the container from that image.
56
60 -a, --attach=[]
61 Attach to STDIN, STDOUT or STDERR.
62 In foreground mode (the default when -d is not specified), docker run
65 can start the process in the container and attach the console to the
66 process's standard input, output, and standard error. It can even pre‐
67 tend to be a TTY (this is what most commandline executables expect) and
68 pass along signals. The -a option can be set for each of stdin, stdout,
69 and stderr.
70 --add-host=[]
73 Add a custom host-to-IP mapping (host:ip)
74 Add a line to /etc/hosts. The format is hostname:ip. The --add-host
77 option can be set multiple times.
78 --blkio-weight=0
81 Block IO weight (relative weight) accepts a weight value between 10
82 and 1000.
83 --blkio-weight-device=[]
86 Block IO weight (relative device weight, format: DE‐
87 VICE_NAME:WEIGHT).
88 --cpu-shares=0
91 CPU shares (relative weight)
92 By default, all containers get the same proportion of CPU cycles. This
95 proportion can be modified by changing the container's CPU share
96 weighting relative to the weighting of all other running containers.
97 To modify the proportion from the default of 1024, use the --cpu-shares
100 flag to set the weighting to 2 or higher.
101 The proportion will only apply when CPU-intensive processes are run‐
104 ning. When tasks in one container are idle, other containers can use
105 the left-over CPU time. The actual amount of CPU time will vary depend‐
106 ing on the number of containers running on the system.
107 For example, consider three containers, one has a cpu-share of 1024 and
110 two others have a cpu-share setting of 512. When processes in all three
111 containers attempt to use 100% of CPU, the first container would re‐
112 ceive 50% of the total CPU time. If you add a fourth container with a
113 cpu-share of 1024, the first container only gets 33% of the CPU. The
114 remaining containers receive 16.5%, 16.5% and 33% of the CPU.
115 On a multi-core system, the shares of CPU time are distributed over all
118 CPU cores. Even if a container is limited to less than 100% of CPU
119 time, it can use 100% of each individual CPU core.
120 For example, consider a system with more than three cores. If you start
123 one container {C0} with -c=512 running one process, and another con‐
124 tainer {C1} with -c=1024 running two processes, this can result in the
125 following division of CPU shares:
126 PID container CPU CPU share
129 100 {C0} 0 100% of CPU0
130 101 {C1} 1 100% of CPU1
131 102 {C1} 2 100% of CPU2
132 --cap-add=[]
136 Add Linux capabilities
137 --cap-drop=[]
140 Drop Linux capabilities
141 --cgroupns=""
144 Set the cgroup namespace mode for the container.
145 host: run the container in the host's cgroup namespace
146 private: run the container in its own private cgroup namespace
147 "": (unset) use the daemon's default configuration (host on
148 cgroup v1, private on cgroup v2)
149 --cgroup-parent=""
152 Path to cgroups under which the cgroup for the container will be
153 created. If the path is not absolute, the path is considered to be rel‐
154 ative to the cgroups path of the init process. Cgroups will be created
155 if they do not already exist.
156 --cidfile=""
159 Write the container ID to the file
160 --cpu-count=0
163 Limit the number of CPUs available for execution by the container.
164 On Windows Server containers, this is approximated as a percentage of total CPU usage.
167 On Windows Server containers, the processor resource controls are mutually exclusive, the order of precedence is CPUCount first, then CPUShares, and CPUPercent last.
169 --cpu-percent=0
173 Limit the percentage of CPU available for execution by a container
174 running on a Windows daemon.
175 On Windows Server containers, the processor resource controls are mutually exclusive, the order of precedence is CPUCount first, then CPUShares, and CPUPercent last.
178 --cpu-period=0
182 Limit the CPU CFS (Completely Fair Scheduler) period
183 Limit the container's CPU usage. This flag tell the kernel to restrict
186 the container's CPU usage to the period you specify.
187 --cpuset-cpus=""
190 CPUs in which to allow execution (0-3, 0,1)
191 --cpuset-mems=""
194 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only ef‐
195 fective on NUMA systems.
196 If you have four memory nodes on your system (0-3), use --cpuset-
199 mems=0,1 then processes in your Docker container will only use memory
200 from the first two memory nodes.
201 --cpu-quota=0
204 Limit the CPU CFS (Completely Fair Scheduler) quota
205 Limit the container's CPU usage. By default, containers run with the
208 full CPU resource. This flag tell the kernel to restrict the con‐
209 tainer's CPU usage to the quota you specify.
210 --cpu-rt-period=0
213 Limit the CPU real-time period in microseconds
214 Limit the container's Real Time CPU usage. This flag tell the kernel to
217 restrict the container's Real Time CPU usage to the period you specify.
218 --cpu-rt-runtime=0
221 Limit the CPU real-time runtime in microseconds
222 Limit the containers Real Time CPU usage. This flag tells the kernel to
225 limit the amount of time in a given CPU period Real Time tasks may con‐
226 sume. Ex:
227 Period of 1,000,000us and Runtime of 950,000us means that this con‐
228 tainer could consume 95% of available CPU and leave the remaining 5% to
229 normal priority tasks.
230 The sum of all runtimes across containers cannot exceed the amount al‐
233 lotted to the parent cgroup.
234 --cpus=0.0
237 Number of CPUs. The default is 0.0 which means no limit.
238 -d, --detach=true|false
241 Detached mode: run the container in the background and print the new
242 container ID. The default is false.
243 At any time you can run docker ps in the other shell to view a list of
246 the running containers. You can reattach to a detached container with
247 docker attach.
248 When attached in the tty mode, you can detach from the container (and
251 leave it running) using a configurable key sequence. The default se‐
252 quence is CTRL-p CTRL-q. You configure the key sequence using the
253 --detach-keys option or a configuration file. See config-json(5) for
254 documentation on using a configuration file.
255 --detach-keys=key
258 Override the key sequence for detaching a container; key is a single
259 character from the [a-Z] range, or ctrl-value, where value is one of:
260 a-z, @, ^, [, ,, or _.
261 --device=onhost:incontainer[:mode]
264 Add a host device onhost to the container under the incontainer
265 name. Optional mode parameter can be used to specify device permis‐
266 sions, it is a combination of r (for read), w (for write), and m (for
267 mknod(2)).
268 For example, --device=/dev/sdc:/dev/xvdc:rwm will give a container all
271 permissions for the host device /dev/sdc, seen as /dev/xvdc inside the
272 container.
273 --device-cgroup-rule="type major:minor mode"
276 Add a rule to the cgroup allowed devices list. The rule is expected
277 to be in the format specified in the Linux kernel documentation (Docu‐
278 mentation/cgroup-v1/devices.txt):
279 - type: a (all), c (char), or b (block);
280 - major and minor: either a number, or * for all;
281 - mode: a composition of r (read), w (write), and m (mknod(2)).
282 Example: --device-cgroup-rule "c 1:3 mr": allow for a character device
285 idendified by 1:3 to be created and read.
286 --device-read-bps=[]
289 Limit read rate from a device (e.g. --device-read-bps=/dev/sda:1mb)
290 --device-read-iops=[]
293 Limit read rate from a device (e.g. --device-read-
294 iops=/dev/sda:1000)
295 --device-write-bps=[]
298 Limit write rate to a device (e.g. --device-write-bps=/dev/sda:1mb)
299 --device-write-iops=[]
302 Limit write rate to a device (e.g. --device-write-
303 iops=/dev/sda:1000)
304 --dns-search=[]
307 Set custom DNS search domains (Use --dns-search=. if you don't wish
308 to set the search domain)
309 --dns-option=[]
312 Set custom DNS options
313 --dns=[]
316 Set custom DNS servers
317 This option can be used to override the DNS configuration passed to the
320 container. Typically this is necessary when the host DNS configuration
321 is invalid for the container (e.g., 127.0.0.1). When this is the case
322 the --dns flags is necessary for every run.
323 --domainname=""
326 Container NIS domain name
327 Sets the container's NIS domain name (see also setdomainname(2)) that
330 is
331 available inside the container.
332 -e, --env=[]
335 Set environment variables
336 This option allows you to specify arbitrary environment variables that
339 are available for the process that will be launched inside of the con‐
340 tainer.
341 --entrypoint=""
344 Overwrite the default ENTRYPOINT of the image
345 This option allows you to overwrite the default entrypoint of the image
348 that is set in the Dockerfile. The ENTRYPOINT of an image is similar to
349 a COMMAND because it specifies what executable to run when the con‐
350 tainer starts, but it is (purposely) more difficult to override. The
351 ENTRYPOINT gives a container its default nature or behavior, so that
352 when you set an ENTRYPOINT you can run the container as if it were that
353 binary, complete with default options, and you can pass in more options
354 via the COMMAND. But, sometimes an operator may want to run something
355 else inside the container, so you can override the default ENTRYPOINT
356 at runtime by using a --entrypoint and a string to specify the new EN‐
357 TRYPOINT.
358 --env-file=[]
361 Read in a line delimited file of environment variables
362 --expose=[]
365 Expose a port, or a range of ports (e.g. --expose=3300-3310) informs
366 Docker that the container listens on the specified network ports at
367 runtime. Docker uses this information to interconnect containers using
368 links and to set up port redirection on the host system.
369 --group-add=[]
372 Add additional groups to run as
373 -h, --hostname=""
376 Container host name
377 Sets the container host name that is available inside the container.
380 --help
383 Print usage statement
384 --init
387 Run an init inside the container that forwards signals and reaps
388 processes
389 -i, --interactive=true|false
392 Keep STDIN open even if not attached. The default is false.
393 When set to true, keep stdin open even if not attached.
396 --ip=""
399 Sets the container's interface IPv4 address (e.g., 172.23.0.9)
400 It can only be used in conjunction with --network for user-defined net‐
403 works
404 --ip6=""
407 Sets the container's interface IPv6 address (e.g., 2001:db8::1b99)
408 It can only be used in conjunction with --network for user-defined net‐
411 works
412 --ipc=""
415 Sets the IPC mode for the container. The following values are ac‐
416 cepted:
417 ┌─────────────────────┬────────────────────────────┐
420 │Value │ Description │
421 ├─────────────────────┼────────────────────────────┤
422 │(empty) │ Use daemon's default. │
423 ├─────────────────────┼────────────────────────────┤
424 │none │ Own private IPC namespace, │
425 │ │ with /dev/shm not mounted. │
426 ├─────────────────────┼────────────────────────────┤
427 │private │ Own private IPC namespace. │
428 ├─────────────────────┼────────────────────────────┤
429 │shareable │ Own private IPC namespace, │
430 │ │ with a possibility to │
431 │ │ share it with other con‐ │
432 │ │ tainers. │
433 ├─────────────────────┼────────────────────────────┤
434 │container:name-or-ID │ Join another ("shareable") │
435 │ │ container's IPC namespace. │
436 ├─────────────────────┼────────────────────────────┤
437 │host │ Use the host system's IPC │
438 │ │ namespace. │
439 └─────────────────────┴────────────────────────────┘
440 If not specified, daemon default is used, which can either be private
442 or shareable, depending on the daemon version and configuration.
443 --isolation="default"
446 Isolation specifies the type of isolation technology used by con‐
447 tainers. Note that the default on Windows server is process, and the
448 default on Windows client is hyperv. Linux only supports default.
449 -l, --label key=value
452 Set metadata on the container (for example, --label com.exam‐
453 ple.key=value).
454 --kernel-memory=number[S]
457 Kernel memory limit; S is an optional suffix which can be one of b,
458 k, m, or g.
459 Constrains the kernel memory available to a container. If a limit of 0
462 is specified (not using --kernel-memory), the container's kernel memory
463 is not limited. If you specify a limit, it may be rounded up to a mul‐
464 tiple of the operating system's page size and the value can be very
465 large, millions of trillions.
466 --label-file=[]
469 Read in a line delimited file of labels
470 --link=name-or-id[:alias]
473 Add link to another container.
474 If the operator uses --link when starting the new client container,
477 then the client container can access the exposed port via a private
478 networking interface. Docker will set some environment variables in the
479 client container to help indicate which interface and port to use.
480 --link-local-ip=[]
483 Add one or more link-local IPv4/IPv6 addresses to the container's
484 interface
485 --log-driver="json-file|syslog|journald|gelf|flu‐
488 entd|awslogs|splunk|etwlogs|gcplogs|none"
489 Logging driver for the container. Default is defined by daemon --log-
490 driver flag.
491 Warning: the docker logs command works only for the json-file and
492 journald logging drivers.
493 --log-opt=[]
496 Logging driver specific options.
497 -m, --memory=number[*S]
500 Memory limit; S is an optional suffix which can be one of b, k, m,
501 or g.
502 Allows you to constrain the memory available to a container. If the
505 host supports swap memory, then the -m memory setting can be larger
506 than physical RAM. If a limit of 0 is specified (not using -m), the
507 container's memory is not limited. The actual limit may be rounded up
508 to a multiple of the operating system's page size (the value would be
509 very large, that's millions of trillions).
510 --memory-reservation=number[*S]
513 Memory soft limit; S is an optional suffix which can be one of b, k,
514 m, or g.
515 After setting memory reservation, when the system detects memory con‐
518 tention or low memory, containers are forced to restrict their consump‐
519 tion to their reservation. So you should always set the value below
520 --memory, otherwise the hard limit will take precedence. By default,
521 memory reservation will be the same as memory limit.
522 --memory-swap=number[S]
525 Combined memory plus swap limit; S is an optional suffix which can
526 be one of b, k, m, or g.
527 This option can only be used together with --memory. The argument
530 should always be larger than that of --memory. Default is double the
531 value of --memory. Set to -1 to enable unlimited swap.
532 --mac-address=""
535 Container MAC address (e.g., 92:d0:c6:0a:29:33)
536 Remember that the MAC address in an Ethernet network must be unique.
539 The IPv6 link-local address will be based on the device's MAC address
540 according to RFC4862.
541 --mount type=TYPE,TYPE-SPECIFIC-OPTION[,...]
544 Attach a filesystem mount to the container
545 Current supported mount TYPES are bind, volume, and tmpfs.
548 e.g.
551 type=bind,source=/path/on/host,destination=/path/in/container
554 type=volume,source=my-volume,destination=/path/in/container,volume-la‐
557 bel="color=red",volume-label="shape=round"
558 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
561 Common Options:
564 • src, source: mount source spec for bind and volume. Mandatory
567 for bind.
568 • dst, destination, target: mount destination spec.
570 • ro, readonly: true or false (default).
572 Note: setting readonly for a bind mount does not make its submounts
576 read-only on the current Linux implementation. See also bind-nonre‐
577 cursive.
578 Options specific to bind:
581 • bind-propagation: shared, slave, private, rshared, rslave, or
584 rprivate(default). See also mount(2).
585 • consistency: consistent(default), cached, or delegated. Cur‐
587 rently, only effective for Docker for Mac.
588 • bind-nonrecursive: true or false (default). If set to true,
590 submounts are not recursively bind-mounted. This option is
591 useful for readonly bind mount.
592 Options specific to volume:
596 • volume-driver: Name of the volume-driver plugin.
599 • volume-label: Custom metadata.
601 • volume-nocopy: true(default) or false. If set to false, the
603 Engine copies existing files and directories under the mount-
604 path into the volume, allowing the host to access them.
605 • volume-opt: specific to a given volume driver.
607 Options specific to tmpfs:
611 • tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by de‐
614 fault in Linux.
615 • tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or
617 0700.) Defaults to 1777 in Linux.
618 --name=""
622 Assign a name to the container
623 The operator can identify a container in three ways:
626 ┌──────────────────────┬────────────────────────────────────────────────────────────────────┐
629 │Identifier type │ Example value │
630 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
631 │UUID long identifier │ "f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778" │
632 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
633 │UUID short identifier │ "f78375b1c487" │
634 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
635 │Name │ "evil_ptolemy" │
636 └──────────────────────┴────────────────────────────────────────────────────────────────────┘
637 The UUID identifiers come from the Docker daemon, and if a name is not
639 assigned to the container with --name then the daemon will also gener‐
640 ate a random string name. The name is useful when defining links (see
641 --link) (or any other place you need to identify a container). This
642 works for both background and foreground Docker containers.
643 --network=type
646 Set the Network mode for the container. Supported values are:
647 ┌────────────────────────┬────────────────────────────┐
650 │Value │ Description │
651 ├────────────────────────┼────────────────────────────┤
652 │none │ No networking in the con‐ │
653 │ │ tainer. │
654 ├────────────────────────┼────────────────────────────┤
655 │bridge │ Connect the container to │
656 │ │ the default Docker bridge │
657 │ │ via veth interfaces. │
658 ├────────────────────────┼────────────────────────────┤
659 │host │ Use the host's network │
660 │ │ stack inside the con‐ │
661 │ │ tainer. │
662 ├────────────────────────┼────────────────────────────┤
663 │container:name|id │ Use the network stack of │
664 │ │ another container, speci‐ │
665 │ │ fied via its name or id. │
666 ├────────────────────────┼────────────────────────────┤
667 │network-name|network-id │ Connects the container to │
668 │ │ a user created network │
669 │ │ (using docker network cre‐ │
670 │ │ ate command) │
671 └────────────────────────┴────────────────────────────┘
672 Default is bridge.
674 --network-alias=[]
677 Add network-scoped alias for the container
678 --oom-kill-disable=true|false
681 Whether to disable OOM Killer for the container or not.
682 --oom-score-adj=""
685 Tune the host's OOM preferences for containers (accepts -1000 to
686 1000)
687 -P, --publish-all=true|false
690 Publish all exposed ports to random ports on the host interfaces.
691 The default is false.
692 When set to true publish all exposed ports to the host interfaces. The
695 default is false. If the operator uses -P (or -p) then Docker will make
696 the exposed port accessible on the host and the ports will be available
697 to any client that can reach the host. When using -P, Docker will bind
698 any exposed port to a random port on the host within an ephemeral port
699 range defined by /proc/sys/net/ipv4/ip_local_port_range. To find the
700 mapping between the host ports and the exposed ports, use docker
701 port(1).
702 -p, --publish ip:[hostPort]:containerPort | [hostPort:]containerPort
705 Publish a container's port, or range of ports, to the host.
706 Both hostPort and containerPort can be specified as a range. When
709 specifying ranges for both, the number of ports in ranges should be
710 equal.
711 Examples: -p 1234-1236:1222-1224, -p 127.0.0.1:$HOSTPORT:$CONTAINER‐
714 PORT.
715 Use docker port(1) to see the actual mapping, e.g. docker port CON‐
718 TAINER $CONTAINERPORT.
719 --pid=""
722 Set the PID mode for the container
723 Default is to create a private PID namespace for the container
724 'container:': join another container's
725 PID namespace
726 'host': use the host's PID namespace for
727 the container. Note: the host mode gives the container full access to
728 local PID and is therefore considered insecure.
729 --userns=""
732 Set the usernamespace mode for the container when userns-remap op‐
733 tion is enabled.
734 host: use the host usernamespace and enable all privileged options
735 (e.g., pid=host or --privileged).
736 --pids-limit=""
739 Tune the container's pids (process IDs) limit. Set to -1 to have un‐
740 limited pids for the container.
741 --uts=type
744 Set the UTS mode for the container. The only possible type is host,
745 meaning to use the host's UTS namespace inside the container.
746 Note: the host mode gives the container access to changing the
747 host's hostname and is therefore considered insecure.
748 --privileged [true|false]
751 Give extended privileges to this container. A "privileged" container
752 is given access to all devices.
753 When the operator executes docker run --privileged, Docker will enable
756 access to all devices on the host as well as set some configuration in
757 AppArmor to allow the container nearly all the same access to the host
758 as processes running outside of a container on the host.
759 --read-only=true|false
762 Mount the container's root filesystem as read only.
763 By default a container will have its root filesystem writable allowing
766 processes to write files anywhere. By specifying the --read-only flag
767 the container will have its root filesystem mounted as read only pro‐
768 hibiting any writes.
769 --restart policy
772 Restart policy to apply when a container exits. Supported values
773 are:
774 ┌─────────────────────────┬────────────────────────────┐
777 │Policy │ Result │
778 ├─────────────────────────┼────────────────────────────┤
779 │no │ Do not automatically │
780 │ │ restart the container when │
781 │ │ it exits. │
782 ├─────────────────────────┼────────────────────────────┤
783 │on-failure[:max-retries] │ Restart only if the con‐ │
784 │ │ tainer exits with a non- │
785 │ │ zero exit status. Option‐ │
786 │ │ ally, limit the number of │
787 │ │ restart retries the Docker │
788 │ │ daemon attempts. │
789 ├─────────────────────────┼────────────────────────────┤
790 │always │ Always restart the con‐ │
791 │ │ tainer regardless of the │
792 │ │ exit status. When you │
793 │ │ specify always, the Docker │
794 │ │ daemon will try to restart │
795 │ │ the container indefi‐ │
796 │ │ nitely. The container will │
797 │ │ also always start on dae‐ │
798 │ │ mon startup, regardless of │
799 │ │ the current state of the │
800 │ │ container. │
801 ├─────────────────────────┼────────────────────────────┤
802 │unless-stopped │ Always restart the con‐ │
803 │ │ tainer regardless of the │
804 │ │ exit status, but do not │
805 │ │ start it on daemon startup │
806 │ │ if the container has been │
807 │ │ put to a stopped state be‐ │
808 │ │ fore. │
809 └─────────────────────────┴────────────────────────────┘
810 Default is no.
812 --rm true|false
815 Automatically remove the container when it exits. The default is
816 false.
817 --rm flag can work together with -d, and auto-removal will be done
818 on daemon side. Note that it's incompatible with any restart policy
819 other than none.
820 --security-opt value[,...]
823 Security Options for the container. The following options can be
824 given:
825 "label=user:USER" : Set the label user for the container
828 "label=role:ROLE" : Set the label role for the container
829 "label=type:TYPE" : Set the label type for the container
830 "label=level:LEVEL" : Set the label level for the container
831 "label=disable" : Turn off label confinement for the container
832 "no-new-privileges" : Disable container processes from gaining additional privileges
833 "seccomp=unconfined" : Turn off seccomp confinement for the container
835 "seccomp=profile.json : White listed syscalls seccomp Json file to be used as a seccomp filter
836 "apparmor=unconfined" : Turn off apparmor confinement for the container
838 "apparmor=your-profile" : Set the apparmor confinement profile for the container
839 --storage-opt
843 Storage driver options per container
844 $ docker run -it --storage-opt size=120G fedora /bin/bash
847 This (size) will allow to set the container rootfs size to 120G at cre‐
850 ation time.
851 This option is only available for the devicemapper, btrfs, overlay2
852 and zfs graph drivers.
853 For the devicemapper, btrfs and zfs storage drivers, user cannot
854 pass a size less than the Default BaseFS Size.
855 For the overlay2 storage driver, the size option is only available
856 if the backing fs is xfs and mounted with the pquota mount option.
857 Under these conditions, user can pass any size less than the backing
858 fs size.
859 --stop-signal=SIGTERM
862 Signal to stop the container. Default is SIGTERM.
863 The --stop-signal flag sets the system call signal that will be sent to
866 the
867 container to exit. This signal can be a signal name in the format
868 SIG<NAME>,
869 for instance SIGKILL, or an unsigned number that matches a position
870 in the
871 kernel's syscall table, for instance 9.
872 --stop-timeout
875 Timeout (in seconds) to stop a container, or -1 to disable timeout.
876 The --stop-timeout flag sets the number of seconds to wait for the con‐
879 tainer
880 to stop after sending the pre-defined (see --stop-signal) system call
881 signal.
882 If the container does not exit after the timeout elapses, it is
883 forcibly killed
884 with a SIGKILL signal.
885 If --stop-timeout is set to -1, no timeout is applied, and the daemon
888 will
889 wait indefinitely for the container to exit.
890 The default is determined by the daemon, and 10 seconds for Linux con‐
893 tainers,
894 and 30 seconds for Windows containers.
895 --shm-size=""
898 Size of /dev/shm. The format is <number><unit>.
899 number must be greater than 0. Unit is optional and can be b
900 (bytes), k (kilobytes), m(megabytes), or g (gigabytes).
901 If you omit the unit, the system uses bytes. If you omit the size
902 entirely, the system uses 64m.
903 --sysctl=SYSCTL
906 Configure namespaced kernel parameters at runtime
907 IPC Namespace - current sysctls allowed:
910 kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall,
913 kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced
914 Sysctls beginning with fs.mqueue.*
915 If you use the --ipc=host option these sysctls will not be allowed.
918 Network Namespace - current sysctls allowed:
921 Sysctls beginning with net.*
922 If you use the --network=host option these sysctls will not be allowed.
925 --sig-proxy=true|false
928 Proxy received signals to the process (non-TTY mode only). SIGCHLD,
929 SIGSTOP, and SIGKILL are not proxied. The default is true.
930 --memory-swappiness=""
933 Tune a container's memory swappiness behavior. Accepts an integer
934 between 0 and 100.
935 -t, --tty=true|false
938 Allocate a pseudo-TTY. The default is false.
939 When set to true Docker can allocate a pseudo-tty and attach to the
942 standard input of any container. This can be used, for example, to run
943 a throwaway interactive shell. The default is false.
944 The -t option is incompatible with a redirection of the docker client
947 standard input.
948 --tmpfs=[] Create a tmpfs mount
951 Mount a temporary filesystem (tmpfs) mount into a container, for exam‐
954 ple:
955 $ docker run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
958 This command mounts a tmpfs at /tmp within the container. The sup‐
961 ported mount options are the same as the Linux default mount flags. If
962 you do not specify any options, the systems uses the following options:
963 rw,noexec,nosuid,nodev,size=65536k.
964 See also --mount, which is the successor of --tmpfs and --volume.
967 Even though there is no plan to deprecate --tmpfs, usage of --mount
968 is recommended.
969 -u, --user=""
972 Sets the username or UID used and optionally the groupname or GID
973 for the specified command.
974 The followings examples are all valid:
977 --user [user | user:group | uid | uid:gid | user:gid | uid:group ]
978 Without this argument the command will be run as root in the container.
981 --ulimit=[]
984 Ulimit options
985 -v|--volume[=[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]]
988 Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR,
989 Docker
990 bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Docker
991 container. If 'HOST-DIR' is omitted, Docker automatically creates
992 the new
993 volume on the host. The OPTIONS are a comma delimited list and can
994 be:
995 • [rw|ro]
998 • [z|Z]
1000 • [[r]shared|[r]slave|[r]private]
1002 • [delegated|cached|consistent]
1004 • [nocopy]
1006 The CONTAINER-DIR must be an absolute path such as /src/docs. The HOST-
1010 DIR can be an absolute path or a name value. A name value must start
1011 with an alphanumeric character, followed by a-z0-9, _ (underscore), .
1012 (period) or - (hyphen). An absolute path starts with a / (forward
1013 slash).
1014 If you supply a HOST-DIR that is an absolute path, Docker bind-mounts
1017 to the path you specify. If you supply a name, Docker creates a named
1018 volume by that name. For example, you can specify either /foo or foo
1019 for a HOST-DIR value. If you supply the /foo value, Docker creates a
1020 bind mount. If you supply the foo specification, Docker creates a named
1021 volume.
1022 You can specify multiple -v options to mount one or more mounts to a
1025 container. To use these same mounts in other containers, specify the
1026 --volumes-from option also.
1027 You can supply additional options for each bind mount following an ad‐
1030 ditional colon. A :ro or :rw suffix mounts a volume in read-only or
1031 read-write mode, respectively. By default, volumes are mounted in read-
1032 write mode. You can also specify the consistency requirement for the
1033 mount, either :consistent (the default), :cached, or :delegated. Mul‐
1034 tiple options are separated by commas, e.g. :ro,cached.
1035 Labeling systems like SELinux require that proper labels are placed on
1038 volume content mounted into a container. Without a label, the security
1039 system might prevent the processes running inside the container from
1040 using the content. By default, Docker does not change the labels set by
1041 the OS.
1042 To change a label in the container context, you can add either of two
1045 suffixes :z or :Z to the volume mount. These suffixes tell Docker to
1046 relabel file objects on the shared volumes. The z option tells Docker
1047 that two containers share the volume content. As a result, Docker la‐
1048 bels the content with a shared content label. Shared volume labels al‐
1049 low all containers to read/write content. The Z option tells Docker to
1050 label the content with a private unshared label. Only the current con‐
1051 tainer can use a private volume.
1052 By default bind mounted volumes are private. That means any mounts done
1055 inside container will not be visible on host and vice-a-versa. One can
1056 change this behavior by specifying a volume mount propagation property.
1057 Making a volume shared mounts done under that volume inside container
1058 will be visible on host and vice-a-versa. Making a volume slave enables
1059 only one way mount propagation and that is mounts done on host under
1060 that volume will be visible inside container but not the other way
1061 around.
1062 To control mount propagation property of volume one can use :[r]shared,
1065 :[r]slave or :[r]private propagation flag. Propagation property can be
1066 specified only for bind mounted volumes and not for internal volumes or
1067 named volumes. For mount propagation to work source mount point (mount
1068 point where source dir is mounted on) has to have right propagation
1069 properties. For shared volumes, source mount point has to be shared.
1070 And for slave volumes, source mount has to be either shared or slave.
1071 Use df <source-dir> to figure out the source mount and then use findmnt
1074 -o TARGET,PROPAGATION <source-mount-dir> to figure out propagation
1075 properties of source mount. If findmnt utility is not available, then
1076 one can look at mount entry for source mount point in
1077 /proc/self/mountinfo. Look at optional fields and see if any propaga‐
1078 tion properties are specified. shared:X means mount is shared, mas‐
1079 ter:X means mount is slave and if nothing is there that means mount is
1080 private.
1081 To change propagation properties of a mount point use mount command.
1084 For example, if one wants to bind mount source directory /foo one can
1085 do mount --bind /foo /foo and mount --make-private --make-shared /foo.
1086 This will convert /foo into a shared mount point. Alternatively one can
1087 directly change propagation properties of source mount. Say / is source
1088 mount for /foo, then use mount --make-shared / to convert / into a
1089 shared mount.
1090 Note: When using systemd to manage the Docker daemon's start and
1093 stop, in the systemd unit file there is an option to control
1094 mount propagation for the Docker daemon itself, called Mount‐
1095 Flags. The value of this setting may cause Docker to not see
1096 mount propagation changes made on the mount point. For example,
1097 if this value is slave, you may not be able to use the shared or
1098 rshared propagation on a volume.
1099 To disable automatic copying of data from the container path to the
1103 volume, use the nocopy flag. The nocopy flag can be set on bind mounts
1104 and named volumes.
1105 See also --mount, which is the successor of --tmpfs and --volume. Even
1108 though there is no plan to deprecate --volume, usage of --mount is rec‐
1109 ommended.
1110 --volume-driver=""
1113 Container's volume driver. This driver creates volumes specified ei‐
1114 ther from
1115 a Dockerfile's VOLUME instruction or from the docker run -v flag.
1116 See docker-volume-create(1) for full details.
1117 --volumes-from=[]
1120 Mount volumes from the specified container(s)
1121 Mounts already mounted volumes from a source container onto another
1124 container. You must supply the source's container-id. To share
1125 a volume, use the --volumes-from option when running
1126 the target container. You can share volumes even if the source con‐
1127 tainer
1128 is not running.
1129 By default, Docker mounts the volumes in the same mode (read-write or
1132 read-only) as it is mounted in the source container. Optionally, you
1133 can change this by suffixing the container-id with either the :ro or
1134 :rw keyword.
1135 If the location of the volume from the source container overlaps with
1138 data residing on a target container, then the volume hides
1139 that data on the target.
1140 -w, --workdir=""
1143 Working directory inside the container
1144 The default working directory for running binaries within a container
1147 is the root directory (/). The developer can set a different default
1148 with the Dockerfile WORKDIR instruction. The operator can override the
1149 working directory by using the -w option.
1150
1154 The exit code from docker run gives information about why the container
1155 failed to run or why it exited. When docker run exits with a non-zero
1156 code, the exit codes follow the chroot standard, see below:
1157 125 if the error is with Docker daemon itself
1160 $ docker run --foo busybox; echo $?
1163 # flag provided but not defined: --foo
1164 See 'docker run --help'.
1165 125
1166 126 if the contained command cannot be invoked
1170 $ docker run busybox /etc; echo $?
1173 # exec: "/etc": permission denied
1174 docker: Error response from daemon: Contained command could not be invoked
1175 126
1176 127 if the contained command cannot be found
1180 $ docker run busybox foo; echo $?
1183 # exec: "foo": executable file not found in $PATH
1184 docker: Error response from daemon: Contained command not found or does not exist
1185 127
1186 Exit code of contained command otherwise
1190 $ docker run busybox /bin/sh -c 'exit 3'
1193 # 3
1194
1200 During container image development, containers often need to write to
1201 the image content. Installing packages into /usr, for example. In
1202 production, applications seldom need to write to the image. Container
1203 applications write to volumes if they need to write to file systems at
1204 all. Applications can be made more secure by running them in read-only
1205 mode using the --read-only switch. This protects the containers image
1206 from modification. Read only containers may still need to write tempo‐
1207 rary data. The best way to handle this is to mount tmpfs directories
1208 on /run and /tmp.
1209 # docker run --read-only --tmpfs /run --tmpfs /tmp -i -t fedora /bin/bash
1212
1216 If you want messages that are logged in your container to show up in
1217 the host's syslog/journal then you should bind mount the /dev/log di‐
1218 rectory as follows.
1219 # docker run -v /dev/log:/dev/log -i -t fedora /bin/bash
1222 From inside the container you can test this by sending a message to the
1226 log.
1227 (bash)# logger "Hello from my container"
1230 Then exit and check the journal.
1234 # exit
1237 # journalctl -b | grep Hello
1239 This should list the message sent to logger.
1243
1246 If you do not specify -a then Docker will attach everything (stdin,std‐
1247 out,stderr) you'd like to connect instead, as in:
1248 # docker run -a stdin -a stdout -i -t fedora /bin/bash
1251
1255 Using shm_server.c available here:
1256 https://www.cs.cf.ac.uk/Dave/C/node27.html
1257 Testing --ipc=host mode:
1260 Host shows a shared memory segment with 7 pids attached, happens to be
1263 from httpd:
1264 $ sudo ipcs -m
1267 ------ Shared Memory Segments --------
1269 key shmid owner perms bytes nattch status
1270 0x01128e25 0 root 600 1000 7
1271 Now run a regular container, and it correctly does NOT see the shared
1275 memory segment from the host:
1276 $ docker run -it shm ipcs -m
1279 ------ Shared Memory Segments --------
1281 key shmid owner perms bytes nattch status
1282 Run a container with the new --ipc=host option, and it now sees the
1286 shared memory segment from the host httpd:
1287 $ docker run -it --ipc=host shm ipcs -m
1290 ------ Shared Memory Segments --------
1292 key shmid owner perms bytes nattch status
1293 0x01128e25 0 root 600 1000 7
1294 Testing --ipc=container:CONTAINERID mode:
1298 Start a container with a program to create a shared memory segment:
1301 $ docker run -it shm bash
1304 $ sudo shm/shm_server &
1305 $ sudo ipcs -m
1306 ------ Shared Memory Segments --------
1308 key shmid owner perms bytes nattch status
1309 0x0000162e 0 root 666 27 1
1310 Create a 2nd container correctly shows no shared memory segment from
1314 1st container:
1315 $ docker run shm ipcs -m
1318 ------ Shared Memory Segments --------
1320 key shmid owner perms bytes nattch status
1321 Create a 3rd container using the new --ipc=container:CONTAINERID op‐
1325 tion, now it shows the shared memory segment from the first:
1326 $ docker run -it --ipc=container:ed735b2264ac shm ipcs -m
1329 $ sudo ipcs -m
1330 ------ Shared Memory Segments --------
1332 key shmid owner perms bytes nattch status
1333 0x0000162e 0 root 666 27 1
1334
1338 Note: This section describes linking between containers on the
1339 default (bridge) network, also known as "legacy links". Using
1340 --link on user-defined networks uses the DNS-based discovery,
1341 which does not add entries to /etc/hosts, and does not set envi‐
1342 ronment variables for discovery.
1343 The link feature allows multiple containers to communicate with each
1347 other. For example, a container whose Dockerfile has exposed port 80
1348 can be run and named as follows:
1349 # docker run --name=link-test -d -i -t fedora/httpd
1352 A second container, in this case called linker, can communicate with
1356 the httpd container, named link-test, by running with the --link=:
1357 # docker run -t -i --link=link-test:lt --name=linker fedora /bin/bash
1360 Now the container linker is linked to container link-test with the
1364 alias lt. Running the env command in the linker container shows envi‐
1365 ronment variables
1366 with the LT (alias) context (LT_)
1367 # env
1370 HOSTNAME=668231cb0978
1371 TERM=xterm
1372 LT_PORT_80_TCP=tcp://172.17.0.3:80
1373 LT_PORT_80_TCP_PORT=80
1374 LT_PORT_80_TCP_PROTO=tcp
1375 LT_PORT=tcp://172.17.0.3:80
1376 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
1377 PWD=/
1378 LT_NAME=/linker/lt
1379 SHLVL=1
1380 HOME=/
1381 LT_PORT_80_TCP_ADDR=172.17.0.3
1382 _=/usr/bin/env
1383 When linking two containers Docker will use the exposed ports of the
1387 container to create a secure tunnel for the parent to access.
1388 If a container is connected to the default bridge network and linked
1391 with other containers, then the container's /etc/hosts file is updated
1392 with the linked container's name.
1393 Note Since Docker may live update the container's /etc/hosts
1396 file, there may be situations when processes inside the con‐
1397 tainer can end up reading an empty or incomplete /etc/hosts
1398 file. In most cases, retrying the read again should fix the
1399 problem.
1400
1404 The exposed port of an application can be mapped to a host port using
1405 the -p flag. For example, an httpd port 80 can be mapped to the host
1406 port 8080 using the following:
1407 # docker run -p 8080:80 -d -i -t fedora/httpd
1410
1414 Many applications require the sharing of persistent data across several
1415 containers. Docker allows you to create a Data Volume Container that
1416 other containers can mount from. For example, create a named container
1417 that contains directories /var/volume1 and /tmp/volume2. The image will
1418 need to contain these directories so a couple of RUN mkdir instructions
1419 might be required for you fedora-data image:
1420 # docker run --name=data -v /var/volume1 -v /tmp/volume2 -i -t fedora-data true
1423 # docker run --volumes-from=data --name=fedora-container1 -i -t fedora bash
1424 Multiple --volumes-from parameters will bring together multiple data
1428 volumes from multiple containers. And it's possible to mount the vol‐
1429 umes that came from the DATA container in yet another container via the
1430 fedora-container1 intermediary container, allowing to abstract the ac‐
1431 tual data source from users of that data:
1432 # docker run --volumes-from=fedora-container1 --name=fedora-container2 -i -t fedora bash
1435
1439 To mount a host directory as a container volume, specify the absolute
1440 path to the directory and the absolute path for the container directory
1441 separated by a colon:
1442 # docker run -v /var/db:/data1 -i -t fedora bash
1445 When using SELinux, be aware that the host has no knowledge of con‐
1449 tainer SELinux policy. Therefore, in the above example, if SELinux pol‐
1450 icy is enforced, the /var/db directory is not writable to the con‐
1451 tainer. A "Permission Denied" message will occur and an avc: message in
1452 the host's syslog.
1453 To work around this, at time of writing this man page, the following
1456 command needs to be run in order for the proper SELinux policy type la‐
1457 bel to be attached to the host directory:
1458 # chcon -Rt svirt_sandbox_file_t /var/db
1461 Now, writing to the /data1 volume in the container will be allowed and
1465 the changes will also be reflected on the host in /var/db.
1466
1469 You can override the default labeling scheme for each container by
1470 specifying the --security-opt flag. For example, you can specify the
1471 MCS/MLS level, a requirement for MLS systems. Specifying the level in
1472 the following command allows you to share the same content between con‐
1473 tainers.
1474 # docker run --security-opt label=level:s0:c100,c200 -i -t fedora bash
1477 An MLS example might be:
1481 # docker run --security-opt label=level:TopSecret -i -t rhel7 bash
1484 To disable the security labeling for this container versus running with
1488 the --permissive flag, use the following command:
1489 # docker run --security-opt label=disable -i -t fedora bash
1492 If you want a tighter security policy on the processes within a con‐
1496 tainer, you can specify an alternate type for the container. You could
1497 run a container that is only allowed to listen on Apache ports by exe‐
1498 cuting the following command:
1499 # docker run --security-opt label=type:svirt_apache_t -i -t centos bash
1502 Note:
1506 You would have to write policy defining a svirt_apache_t type.
1509
1512 If you want to set /dev/sda device weight to 200, you can specify the
1513 device weight by --blkio-weight-device flag. Use the following command:
1514 # docker run -it --blkio-weight-device "/dev/sda:200" ubuntu
1517
1521 This option is useful in situations where you are running Docker con‐
1522 tainers on Microsoft Windows. The --isolation <value> option sets a
1523 container's isolation technology. On Linux, the only supported is the
1524 default option which uses Linux namespaces. These two commands are
1525 equivalent on Linux:
1526 $ docker run -d busybox top
1529 $ docker run -d --isolation default busybox top
1530 On Microsoft Windows, can take any of these values:
1534 • default: Use the value specified by the Docker daemon's
1537 --exec-opt . If the daemon does not specify an isolation tech‐
1538 nology, Microsoft Windows uses process as its default value.
1539 • process: Namespace isolation only.
1541 • hyperv: Hyper-V hypervisor partition-based isolation.
1543 In practice, when running on Microsoft Windows without a daemon option
1547 set, these two commands are equivalent:
1548 $ docker run -d --isolation default busybox top
1551 $ docker run -d --isolation process busybox top
1552 If you have set the --exec-opt isolation=hyperv option on the Docker
1556 daemon, any of these commands also result in hyperv isolation:
1557 $ docker run -d --isolation default busybox top
1560 $ docker run -d --isolation hyperv busybox top
1561
1565 The --sysctl sets namespaced kernel parameters (sysctls) in the con‐
1566 tainer. For example, to turn on IP forwarding in the containers network
1567 namespace, run this command:
1568 $ docker run --sysctl net.ipv4.ip_forward=1 someimage
1571 Note:
1575 Not all sysctls are namespaced. Docker does not support changing
1578 sysctls inside of a container that also modify the host system. As the
1579 kernel evolves we expect to see more sysctls become namespaced.
1580 See the definition of the --sysctl option above for the current list of
1583 supported sysctls.
1584
1588 April 2014, Originally compiled by William Henry (whenry at redhat dot
1589 com) based on docker.com source material and internal work. June 2014,
1590 updated by Sven Dowideit SvenDowideit@home.org.au ⟨mailto:Sven‐
1591 Dowideit@home.org.au⟩ July 2014, updated by Sven Dowideit Sven‐
1592 Dowideit@home.org.au ⟨mailto:SvenDowideit@home.org.au⟩ November 2015,
1593 updated by Sally O'Malley somalley@redhat.com ⟨mailto:somalley@red‐
1594 hat.com⟩
1595Docker Community JUNE 2014 DOCKER(1)