1DOCKER(1)(Docker) DOCKER(1)(Docker)
2Docker Community JUNE 2014
6
9 docker-run - Run a command in a new container
10
14 docker run [-a|--attach[=[]]] [--add-host[=[]]]
15 [--blkio-weight[=[BLKIO-WEIGHT]]] [--blkio-weight-device[=[]]]
16 [--cpu-shares[=0]] [--cap-add[=[]]] [--cap-drop[=[]]] [--cgroup-par‐
17 ent[=CGROUP-PATH]] [--cidfile[=CIDFILE]] [--cpu-count[=0]] [--cpu-per‐
18 cent[=0]] [--cpu-period[=0]] [--cpu-quota[=0]] [--cpu-rt-period[=0]]
19 [--cpu-rt-runtime[=0]] [--cpus[=0.0]] [--cpuset-cpus[=CPUSET-CPUS]]
20 [--cpuset-mems[=CPUSET-MEMS]] [-d|--detach] [--detach-keys[=[]]]
21 [--device[=[]]] [--device-cgroup-rule[=[]]] [--device-read-bps[=[]]]
22 [--device-read-iops[=[]]] [--device-write-bps[=[]]]
23 [--device-write-iops[=[]]] [--dns[=[]]] [--dns-option[=[]]]
24 [--dns-search[=[]]] [--domainname[=DOMAINNAME]] [-e|--env[=[]]]
25 [--entrypoint[=ENTRYPOINT]] [--env-file[=[]]] [--expose[=[]]]
26 [--group-add[=[]]] [-h|--hostname[=HOSTNAME]] [--help] [--init]
27 [-i|--interactive] [--ip[=IPv4-ADDRESS]] [--ip6[=IPv6-ADDRESS]]
28 [--ipc[=IPC]] [--isolation[=default]] [--kernel-memory[=KERNEL-MEMORY]]
29 [-l|--label[=[]]] [--label-file[=[]]] [--link[=[]]]
30 [--link-local-ip[=[]]] [--log-driver[=[]]] [--log-opt[=[]]] [-m|--mem‐
31 ory[=MEMORY]] [--mac-address[=MAC-ADDRESS]] [--memory-reservation[=MEM‐
32 ORY-RESERVATION]] [--memory-swap[=LIMIT]] [--memory-swappiness[=MEM‐
33 ORY-SWAPPINESS]] [--mount[=[MOUNT]]] [--name[=NAME]] [--net‐
34 work-alias[=[]]] [--network[="bridge"]] [--oom-kill-disable]
35 [--oom-score-adj[=0]] [-P|--publish-all] [-p|--publish[=[]]]
36 [--pid[=[PID]]] [--userns[=[]]] [--pids-limit[=PIDS_LIMIT]] [--privi‐
37 leged] [--read-only] [--restart[=RESTART]] [--rm] [--security-opt[=[]]]
38 [--storage-opt[=[]]] [--stop-signal[=SIGNAL]] [--stop-timeout[=TIME‐
39 OUT]] [--shm-size[=[]]] [--sig-proxy[=true]] [--sysctl[=[]]] [-t|--tty]
40 [--tmpfs[=[CONTAINER-DIR[:OPTIONS]]] [-u|--user[=USER]] [--ulimit[=[]]]
41 [--uts[=[]]] [-v|--volume[=[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]]]
42 [--volume-driver[=DRIVER]] [--volumes-from[=[]]]
43 [-w|--workdir[=WORKDIR]] IMAGE [COMMAND] [ARG...]
44
48 Run a process in a new container. docker run starts a process with its
49 own file system, its own networking, and its own isolated process tree.
50 The IMAGE which starts the process may define defaults related to the
51 process that will be run in the container, the networking to expose,
52 and more, but docker run gives final control to the operator or admin‐
53 istrator who starts the container from the image. For that reason
54 docker run has more options than any other Docker command.
55 If the IMAGE is not already loaded then docker run will pull the IMAGE,
58 and all image dependencies, from the repository in the same way running
59 docker pull IMAGE, before it starts the container from that image.
60
64 -a, --attach=[]
65 Attach to STDIN, STDOUT or STDERR.
66 In foreground mode (the default when -d is not specified), docker run
69 can start the process in the container and attach the console to the
70 process's standard input, output, and standard error. It can even pre‐
71 tend to be a TTY (this is what most commandline executables expect) and
72 pass along signals. The -a option can be set for each of stdin, stdout,
73 and stderr.
74 --add-host=[]
77 Add a custom host-to-IP mapping (host:ip)
78 Add a line to /etc/hosts. The format is hostname:ip. The --add-host
81 option can be set multiple times.
82 --blkio-weight=0
85 Block IO weight (relative weight) accepts a weight value between 10
86 and 1000.
87 --blkio-weight-device=[]
90 Block IO weight (relative device weight, format:
91 DEVICE_NAME:WEIGHT).
92 --cpu-shares=0
95 CPU shares (relative weight)
96 By default, all containers get the same proportion of CPU cycles. This
99 proportion can be modified by changing the container's CPU share
100 weighting relative to the weighting of all other running containers.
101 To modify the proportion from the default of 1024, use the --cpu-shares
104 flag to set the weighting to 2 or higher.
105 The proportion will only apply when CPU-intensive processes are run‐
108 ning. When tasks in one container are idle, other containers can use
109 the left-over CPU time. The actual amount of CPU time will vary depend‐
110 ing on the number of containers running on the system.
111 For example, consider three containers, one has a cpu-share of 1024 and
114 two others have a cpu-share setting of 512. When processes in all three
115 containers attempt to use 100% of CPU, the first container would
116 receive 50% of the total CPU time. If you add a fourth container with a
117 cpu-share of 1024, the first container only gets 33% of the CPU. The
118 remaining containers receive 16.5%, 16.5% and 33% of the CPU.
119 On a multi-core system, the shares of CPU time are distributed over all
122 CPU cores. Even if a container is limited to less than 100% of CPU
123 time, it can use 100% of each individual CPU core.
124 For example, consider a system with more than three cores. If you start
127 one container {C0} with -c=512 running one process, and another con‐
128 tainer {C1} with -c=1024 running two processes, this can result in the
129 following division of CPU shares:
130 PID container CPU CPU share
133 100 {C0} 0 100% of CPU0
134 101 {C1} 1 100% of CPU1
135 102 {C1} 2 100% of CPU2
136 --cap-add=[]
140 Add Linux capabilities
141 --cap-drop=[]
144 Drop Linux capabilities
145 --cgroup-parent=""
148 Path to cgroups under which the cgroup for the container will be
149 created. If the path is not absolute, the path is considered to be rel‐
150 ative to the cgroups path of the init process. Cgroups will be created
151 if they do not already exist.
152 --cidfile=""
155 Write the container ID to the file
156 --cpu-count=0
159 Limit the number of CPUs available for execution by the container.
160 On Windows Server containers, this is approximated as a percentage of total CPU usage.
163 On Windows Server containers, the processor resource controls are mutually exclusive, the order of precedence is CPUCount first, then CPUShares, and CPUPercent last.
165 --cpu-percent=0
169 Limit the percentage of CPU available for execution by a container
170 running on a Windows daemon.
171 On Windows Server containers, the processor resource controls are mutually exclusive, the order of precedence is CPUCount first, then CPUShares, and CPUPercent last.
174 --cpu-period=0
178 Limit the CPU CFS (Completely Fair Scheduler) period
179 Limit the container's CPU usage. This flag tell the kernel to restrict
182 the container's CPU usage to the period you specify.
183 --cpuset-cpus=""
186 CPUs in which to allow execution (0-3, 0,1)
187 --cpuset-mems=""
190 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only
191 effective on NUMA systems.
192 If you have four memory nodes on your system (0-3), use
195 --cpuset-mems=0,1 then processes in your Docker container will only use
196 memory from the first two memory nodes.
197 --cpu-quota=0
200 Limit the CPU CFS (Completely Fair Scheduler) quota
201 Limit the container's CPU usage. By default, containers run with the
204 full CPU resource. This flag tell the kernel to restrict the con‐
205 tainer's CPU usage to the quota you specify.
206 --cpu-rt-period=0
209 Limit the CPU real-time period in microseconds
210 Limit the container's Real Time CPU usage. This flag tell the kernel to
213 restrict the container's Real Time CPU usage to the period you specify.
214 --cpu-rt-runtime=0
217 Limit the CPU real-time runtime in microseconds
218 Limit the containers Real Time CPU usage. This flag tells the kernel to
221 limit the amount of time in a given CPU period Real Time tasks may con‐
222 sume. Ex:
223 Period of 1,000,000us and Runtime of 950,000us means that this con‐
224 tainer could consume 95% of available CPU and leave the remaining 5% to
225 normal priority tasks.
226 The sum of all runtimes across containers cannot exceed the amount
229 allotted to the parent cgroup.
230 --cpus=0.0
233 Number of CPUs. The default is 0.0 which means no limit.
234 -d, --detach=true|false
237 Detached mode: run the container in the background and print the new
238 container ID. The default is false.
239 At any time you can run docker ps in the other shell to view a list of
242 the running containers. You can reattach to a detached container with
243 docker attach.
244 When attached in the tty mode, you can detach from the container (and
247 leave it running) using a configurable key sequence. The default
248 sequence is CTRL-p CTRL-q. You configure the key sequence using the
249 --detach-keys option or a configuration file. See config-json(5) for
250 documentation on using a configuration file.
251 --detach-keys=key
254 Override the key sequence for detaching a container; key is a single
255 character from the [a-Z] range, or ctrl-value, where value is one of:
256 a-z, @, ^, [, ,, or _.
257 --device=onhost:incontainer[:mode]
260 Add a host device onhost to the container under the incontainer
261 name. Optional mode parameter can be used to specify device permis‐
262 sions, it is a combination of r (for read), w (for write), and m (for
263 mknod(2)).
264 For example, --device=/dev/sdc:/dev/xvdc:rwm will give a container all
267 permissions for the host device /dev/sdc, seen as /dev/xvdc inside the
268 container.
269 --device-cgroup-rule="type major:minor mode"
272 Add a rule to the cgroup allowed devices list. The rule is expected
273 to be in the format specified in the Linux kernel documentation (Docu‐
274 mentation/cgroup-v1/devices.txt):
275 - type: a (all), c (char), or b (block);
276 - major and minor: either a number, or * for all;
277 - mode: a composition of r (read), w (write), and m (mknod(2)).
278 Example: --device-cgroup-rule "c 1:3 mr": allow for a character device
281 idendified by 1:3 to be created and read.
282 --device-read-bps=[]
285 Limit read rate from a device (e.g. --device-read-bps=/dev/sda:1mb)
286 --device-read-iops=[]
289 Limit read rate from a device (e.g.
290 --device-read-iops=/dev/sda:1000)
291 --device-write-bps=[]
294 Limit write rate to a device (e.g. --device-write-bps=/dev/sda:1mb)
295 --device-write-iops=[]
298 Limit write rate to a device (e.g.
299 --device-write-iops=/dev/sda:1000)
300 --dns-search=[]
303 Set custom DNS search domains (Use --dns-search=. if you don't wish
304 to set the search domain)
305 --dns-option=[]
308 Set custom DNS options
309 --dns=[]
312 Set custom DNS servers
313 This option can be used to override the DNS configuration passed to the
316 container. Typically this is necessary when the host DNS configuration
317 is invalid for the container (e.g., 127.0.0.1). When this is the case
318 the --dns flags is necessary for every run.
319 --domainname=""
322 Container NIS domain name
323 Sets the container's NIS domain name (see also setdomainname(2)) that
326 is
327 available inside the container.
328 -e, --env=[]
331 Set environment variables
332 This option allows you to specify arbitrary environment variables that
335 are available for the process that will be launched inside of the con‐
336 tainer.
337 --entrypoint=""
340 Overwrite the default ENTRYPOINT of the image
341 This option allows you to overwrite the default entrypoint of the image
344 that is set in the Dockerfile. The ENTRYPOINT of an image is similar to
345 a COMMAND because it specifies what executable to run when the con‐
346 tainer starts, but it is (purposely) more difficult to override. The
347 ENTRYPOINT gives a container its default nature or behavior, so that
348 when you set an ENTRYPOINT you can run the container as if it were that
349 binary, complete with default options, and you can pass in more options
350 via the COMMAND. But, sometimes an operator may want to run something
351 else inside the container, so you can override the default ENTRYPOINT
352 at runtime by using a --entrypoint and a string to specify the new
353 ENTRYPOINT.
354 --env-file=[]
357 Read in a line delimited file of environment variables
358 --expose=[]
361 Expose a port, or a range of ports (e.g. --expose=3300-3310) informs
362 Docker that the container listens on the specified network ports at
363 runtime. Docker uses this information to interconnect containers using
364 links and to set up port redirection on the host system.
365 --group-add=[]
368 Add additional groups to run as
369 -h, --hostname=""
372 Container host name
373 Sets the container host name that is available inside the container.
376 --help
379 Print usage statement
380 --init
383 Run an init inside the container that forwards signals and reaps
384 processes
385 -i, --interactive=true|false
388 Keep STDIN open even if not attached. The default is false.
389 When set to true, keep stdin open even if not attached.
392 --ip=""
395 Sets the container's interface IPv4 address (e.g., 172.23.0.9)
396 It can only be used in conjunction with --network for user-defined net‐
399 works
400 --ip6=""
403 Sets the container's interface IPv6 address (e.g., 2001:db8::1b99)
404 It can only be used in conjunction with --network for user-defined net‐
407 works
408 --ipc=""
411 Sets the IPC mode for the container. The following values are
412 accepted:
413 ┌─────────────────────┬────────────────────────────┐
416 │Value │ Description │
417 ├─────────────────────┼────────────────────────────┤
418 │(empty) │ Use daemon's default. │
419 ├─────────────────────┼────────────────────────────┤
420 │none │ Own private IPC namespace, │
421 │ │ with /dev/shm not mounted. │
422 ├─────────────────────┼────────────────────────────┤
423 │private │ Own private IPC namespace. │
424 ├─────────────────────┼────────────────────────────┤
425 │shareable │ Own private IPC namespace, │
426 │ │ with a possibility to │
427 │ │ share it with other con‐ │
428 │ │ tainers. │
429 ├─────────────────────┼────────────────────────────┤
430 │container:name-or-ID │ Join another ("shareable") │
431 │ │ container's IPC namespace. │
432 ├─────────────────────┼────────────────────────────┤
433 │host │ Use the host system's IPC │
434 │ │ namespace. │
435 ├─────────────────────┼────────────────────────────┤
436 │ │ │
437 └─────────────────────┴────────────────────────────┘
438 If not specified, daemon default is used, which can either be private
440 or shareable, depending on the daemon version and configuration.
441 --isolation="default"
444 Isolation specifies the type of isolation technology used by con‐
445 tainers. Note that the default on Windows server is process, and the
446 default on Windows client is hyperv. Linux only supports default.
447 -l, --label key=value
450 Set metadata on the container (for example, --label com.exam‐
451 ple.key=value).
452 --kernel-memory=number[S]
455 Kernel memory limit; S is an optional suffix which can be one of b,
456 k, m, or g.
457 Constrains the kernel memory available to a container. If a limit of 0
460 is specified (not using --kernel-memory), the container's kernel memory
461 is not limited. If you specify a limit, it may be rounded up to a mul‐
462 tiple of the operating system's page size and the value can be very
463 large, millions of trillions.
464 --label-file=[]
467 Read in a line delimited file of labels
468 --link=name-or-id[:alias]
471 Add link to another container.
472 If the operator uses --link when starting the new client container,
475 then the client container can access the exposed port via a private
476 networking interface. Docker will set some environment variables in the
477 client container to help indicate which interface and port to use.
478 --link-local-ip=[]
481 Add one or more link-local IPv4/IPv6 addresses to the container's
482 interface
483 --log-driver="json-file|syslog|journald|gelf|flu‐
486 entd|awslogs|splunk|etwlogs|gcplogs|none"
487 Logging driver for the container. Default is defined by daemon
488 --log-driver flag.
489 Warning: the docker logs command works only for the json-file and
490 journald logging drivers.
491 --log-opt=[]
494 Logging driver specific options.
495 -m, --memory=number[*S]
498 Memory limit; S is an optional suffix which can be one of b, k, m,
499 or g.
500 Allows you to constrain the memory available to a container. If the
503 host supports swap memory, then the -m memory setting can be larger
504 than physical RAM. If a limit of 0 is specified (not using -m), the
505 container's memory is not limited. The actual limit may be rounded up
506 to a multiple of the operating system's page size (the value would be
507 very large, that's millions of trillions).
508 --memory-reservation=number[*S]
511 Memory soft limit; S is an optional suffix which can be one of b, k,
512 m, or g.
513 After setting memory reservation, when the system detects memory con‐
516 tention or low memory, containers are forced to restrict their consump‐
517 tion to their reservation. So you should always set the value below
518 --memory, otherwise the hard limit will take precedence. By default,
519 memory reservation will be the same as memory limit.
520 --memory-swap=number[S]
523 Combined memory plus swap limit; S is an optional suffix which can
524 be one of b, k, m, or g.
525 This option can only be used together with --memory. The argument
528 should always be larger than that of --memory. Default is double the
529 value of --memory. Set to -1 to enable unlimited swap.
530 --mac-address=""
533 Container MAC address (e.g., 92:d0:c6:0a:29:33)
534 Remember that the MAC address in an Ethernet network must be unique.
537 The IPv6 link-local address will be based on the device's MAC address
538 according to RFC4862.
539 --mount type=TYPE,TYPE-SPECIFIC-OPTION[,...]
542 Attach a filesystem mount to the container
543 Current supported mount TYPES are bind, volume, and tmpfs.
546 e.g.
549 type=bind,source=/path/on/host,destination=/path/in/container
552 type=volume,source=my-volume,destination=/path/in/container,vol‐
555 ume-label="color=red",volume-label="shape=round"
556 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
559 Common Options:
562 · src, source: mount source spec for bind and volume. Mandatory
565 for bind.
566 · dst, destination, target: mount destination spec.
568 · ro, readonly: true or false (default).
570 Note: setting readonly for a bind mount does not make its submounts
574 read-only on the current Linux implementation. See also bind-nonre‐
575 cursive.
576 Options specific to bind:
579 · bind-propagation: shared, slave, private, rshared, rslave, or
582 rprivate(default). See also mount(2).
583 · consistency: consistent(default), cached, or delegated. Cur‐
585 rently, only effective for Docker for Mac.
586 · bind-nonrecursive: true or false (default). If set to true,
588 submounts are not recursively bind-mounted. This option is
589 useful for readonly bind mount.
590 Options specific to volume:
594 · volume-driver: Name of the volume-driver plugin.
597 · volume-label: Custom metadata.
599 · volume-nocopy: true(default) or false. If set to false, the
601 Engine copies existing files and directories under the
602 mount-path into the volume, allowing the host to access them.
603 · volume-opt: specific to a given volume driver.
605 Options specific to tmpfs:
609 · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by
612 default in Linux.
613 · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or
615 0700.) Defaults to 1777 in Linux.
616 --name=""
620 Assign a name to the container
621 The operator can identify a container in three ways:
624 ┌──────────────────────┬────────────────────────────────────────────────────────────────────┐
627 │Identifier type │ Example value │
628 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
629 │UUID long identifier │ "f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778" │
630 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
631 │UUID short identifier │ "f78375b1c487" │
632 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
633 │Name │ "evil_ptolemy" │
634 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
635 │ │ │
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 │ │
664 ├───────────────┼────────────────────────────┤
665 │idnetwork-name │ │
666 ├───────────────┼────────────────────────────┤
667 │network-id │ │
668 └───────────────┴────────────────────────────┘
669 Default is bridge.
671 --network-alias=[]
674 Add network-scoped alias for the container
675 --oom-kill-disable=true|false
678 Whether to disable OOM Killer for the container or not.
679 --oom-score-adj=""
682 Tune the host's OOM preferences for containers (accepts -1000 to
683 1000)
684 -P, --publish-all=true|false
687 Publish all exposed ports to random ports on the host interfaces.
688 The default is false.
689 When set to true publish all exposed ports to the host interfaces. The
692 default is false. If the operator uses -P (or -p) then Docker will make
693 the exposed port accessible on the host and the ports will be available
694 to any client that can reach the host. When using -P, Docker will bind
695 any exposed port to a random port on the host within an ephemeral port
696 range defined by /proc/sys/net/ipv4/ip_local_port_range. To find the
697 mapping between the host ports and the exposed ports, use docker
698 port(1).
699 -p, --publish ip:[hostPort]:containerPort | [hostPort:]containerPort
702 Publish a container's port, or range of ports, to the host.
703 Both hostPort and containerPort can be specified as a range. When
706 specifying ranges for both, the number of ports in ranges should be
707 equal.
708 Examples: -p 1234-1236:1222-1224, -p 127.0.0.1:$HOSTPORT:$CONTAINER‐
711 PORT.
712 Use docker port(1) to see the actual mapping, e.g. docker port CON‐
715 TAINER $CONTAINERPORT.
716 --pid=""
719 Set the PID mode for the container
720 Default is to create a private PID namespace for the container
721 'container:': join another container's
722 PID namespace
723 'host': use the host's PID namespace for
724 the container. Note: the host mode gives the container full access to
725 local PID and is therefore considered insecure.
726 --userns=""
729 Set the usernamespace mode for the container when userns-remap
730 option is enabled.
731 host: use the host usernamespace and enable all privileged options
732 (e.g., pid=host or --privileged).
733 --pids-limit=""
736 Tune the container's pids (process IDs) limit. Set to -1 to have
737 unlimited pids for the container.
738 --uts=type
741 Set the UTS mode for the container. The only possible type is host,
742 meaning to use the host's UTS namespace inside the container.
743 Note: the host mode gives the container access to changing the
744 host's hostname and is therefore considered insecure.
745 --privileged [true|false]
748 Give extended privileges to this container. A "privileged" container
749 is given access to all devices.
750 When the operator executes docker run --privileged, Docker will enable
753 access to all devices on the host as well as set some configuration in
754 AppArmor to allow the container nearly all the same access to the host
755 as processes running outside of a container on the host.
756 --read-only=true|false
759 Mount the container's root filesystem as read only.
760 By default a container will have its root filesystem writable allowing
763 processes to write files anywhere. By specifying the --read-only flag
764 the container will have its root filesystem mounted as read only pro‐
765 hibiting any writes.
766 --restart policy
769 Restart policy to apply when a container exits. Supported values
770 are:
771 ┌─────────────────────────┬────────────────────────────┐
774 │Policy │ Result │
775 ├─────────────────────────┼────────────────────────────┤
776 │no │ Do not automatically │
777 │ │ restart the container when │
778 │ │ it exits. │
779 ├─────────────────────────┼────────────────────────────┤
780 │on-failure[:max-retries] │ Restart only if the con‐ │
781 │ │ tainer exits with a │
782 │ │ non-zero exit status. │
783 │ │ Optionally, limit the num‐ │
784 │ │ ber of restart retries the │
785 │ │ Docker daemon attempts. │
786 ├─────────────────────────┼────────────────────────────┤
787 │always │ Always restart the con‐ │
788 │ │ tainer regardless of the │
789 │ │ exit status. When you │
790 │ │ specify always, the Docker │
791 │ │ daemon will try to restart │
792 │ │ the container indefi‐ │
793 │ │ nitely. The container will │
794 │ │ also always start on dae‐ │
795 │ │ mon startup, regardless of │
796 │ │ the current state of the │
797 │ │ container. │
798 ├─────────────────────────┼────────────────────────────┤
799 │unless-stopped │ Always restart the con‐ │
800 │ │ tainer regardless of the │
801 │ │ exit status, but do not │
802 │ │ start it on daemon startup │
803 │ │ if the container has been │
804 │ │ put to a stopped state │
805 │ │ before. │
806 ├─────────────────────────┼────────────────────────────┤
807 │ │ │
808 └─────────────────────────┴────────────────────────────┘
809 Default is no.
811 --rm true|false
814 Automatically remove the container when it exits. The default is
815 false.
816 --rm flag can work together with -d, and auto-removal will be done
817 on daemon side. Note that it's incompatible with any restart policy
818 other than none.
819 --security-opt value[,...]
822 Security Options for the container. The following options can be
823 given:
824 "label=user:USER" : Set the label user for the container
827 "label=role:ROLE" : Set the label role for the container
828 "label=type:TYPE" : Set the label type for the container
829 "label=level:LEVEL" : Set the label level for the container
830 "label=disable" : Turn off label confinement for the container
831 "no-new-privileges" : Disable container processes from gaining additional privileges
832 "seccomp=unconfined" : Turn off seccomp confinement for the container
834 "seccomp=profile.json : White listed syscalls seccomp Json file to be used as a seccomp filter
835 "apparmor=unconfined" : Turn off apparmor confinement for the container
837 "apparmor=your-profile" : Set the apparmor confinement profile for the container
838 --storage-opt
842 Storage driver options per container
843 $ docker run -it --storage-opt size=120G fedora /bin/bash
846 This (size) will allow to set the container rootfs size to 120G at cre‐
849 ation time.
850 This option is only available for the devicemapper, btrfs, overlay2
851 and zfs graph drivers.
852 For the devicemapper, btrfs and zfs storage drivers, user cannot
853 pass a size less than the Default BaseFS Size.
854 For the overlay2 storage driver, the size option is only available
855 if the backing fs is xfs and mounted with the pquota mount option.
856 Under these conditions, user can pass any size less than the backing
857 fs size.
858 --stop-signal=SIGTERM
861 Signal to stop a container. Default is SIGTERM.
862 --stop-timeout=10
865 Timeout (in seconds) to stop a container. Default is 10.
866 --shm-size=""
869 Size of /dev/shm. The format is <number><unit>.
870 number must be greater than 0. Unit is optional and can be b
871 (bytes), k (kilobytes), m(megabytes), or g (gigabytes).
872 If you omit the unit, the system uses bytes. If you omit the size
873 entirely, the system uses 64m.
874 --sysctl=SYSCTL
877 Configure namespaced kernel parameters at runtime
878 IPC Namespace - current sysctls allowed:
881 kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall,
884 kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced
885 Sysctls beginning with fs.mqueue.*
886 If you use the --ipc=host option these sysctls will not be allowed.
889 Network Namespace - current sysctls allowed:
892 Sysctls beginning with net.*
893 If you use the --network=host option these sysctls will not be allowed.
896 --sig-proxy=true|false
899 Proxy received signals to the process (non-TTY mode only). SIGCHLD,
900 SIGSTOP, and SIGKILL are not proxied. The default is true.
901 --memory-swappiness=""
904 Tune a container's memory swappiness behavior. Accepts an integer
905 between 0 and 100.
906 -t, --tty=true|false
909 Allocate a pseudo-TTY. The default is false.
910 When set to true Docker can allocate a pseudo-tty and attach to the
913 standard input of any container. This can be used, for example, to run
914 a throwaway interactive shell. The default is false.
915 The -t option is incompatible with a redirection of the docker client
918 standard input.
919 --tmpfs=[] Create a tmpfs mount
922 Mount a temporary filesystem (tmpfs) mount into a container, for exam‐
925 ple:
926 $ docker run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
929 This command mounts a tmpfs at /tmp within the container. The sup‐
932 ported mount options are the same as the Linux default mount flags. If
933 you do not specify any options, the systems uses the following options:
934 rw,noexec,nosuid,nodev,size=65536k.
935 See also --mount, which is the successor of --tmpfs and --volume.
938 Even though there is no plan to deprecate --tmpfs, usage of --mount
939 is recommended.
940 -u, --user=""
943 Sets the username or UID used and optionally the groupname or GID
944 for the specified command.
945 The followings examples are all valid:
948 --user [user | user:group | uid | uid:gid | user:gid | uid:group ]
949 Without this argument the command will be run as root in the container.
952 --ulimit=[]
955 Ulimit options
956 -v|--volume[=[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]]
959 Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR,
960 Docker
961 bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Docker
962 container. If 'HOST-DIR' is omitted, Docker automatically creates
963 the new
964 volume on the host. The OPTIONS are a comma delimited list and can
965 be:
966 · [rw|ro]
969 · [z|Z]
971 · [[r]shared|[r]slave|[r]private]
973 · [delegated|cached|consistent]
975 · [nocopy]
977 The CONTAINER-DIR must be an absolute path such as /src/docs. The
981 HOST-DIR can be an absolute path or a name value. A name value must
982 start with an alphanumeric character, followed by a-z0-9, _ (under‐
983 score), . (period) or - (hyphen). An absolute path starts with a /
984 (forward slash).
985 If you supply a HOST-DIR that is an absolute path, Docker bind-mounts
988 to the path you specify. If you supply a name, Docker creates a named
989 volume by that name. For example, you can specify either /foo or foo
990 for a HOST-DIR value. If you supply the /foo value, Docker creates a
991 bind mount. If you supply the foo specification, Docker creates a named
992 volume.
993 You can specify multiple -v options to mount one or more mounts to a
996 container. To use these same mounts in other containers, specify the
997 --volumes-from option also.
998 You can supply additional options for each bind mount following an
1001 additional colon. A :ro or :rw suffix mounts a volume in read-only or
1002 read-write mode, respectively. By default, volumes are mounted in
1003 read-write mode. You can also specify the consistency requirement for
1004 the mount, either :consistent (the default), :cached, or :delegated.
1005 Multiple options are separated by commas, e.g. :ro,cached.
1006 Labeling systems like SELinux require that proper labels are placed on
1009 volume content mounted into a container. Without a label, the security
1010 system might prevent the processes running inside the container from
1011 using the content. By default, Docker does not change the labels set by
1012 the OS.
1013 To change a label in the container context, you can add either of two
1016 suffixes :z or :Z to the volume mount. These suffixes tell Docker to
1017 relabel file objects on the shared volumes. The z option tells Docker
1018 that two containers share the volume content. As a result, Docker
1019 labels the content with a shared content label. Shared volume labels
1020 allow all containers to read/write content. The Z option tells Docker
1021 to label the content with a private unshared label. Only the current
1022 container can use a private volume.
1023 By default bind mounted volumes are private. That means any mounts done
1026 inside container will not be visible on host and vice-a-versa. One can
1027 change this behavior by specifying a volume mount propagation property.
1028 Making a volume shared mounts done under that volume inside container
1029 will be visible on host and vice-a-versa. Making a volume slave enables
1030 only one way mount propagation and that is mounts done on host under
1031 that volume will be visible inside container but not the other way
1032 around.
1033 To control mount propagation property of volume one can use :[r]shared,
1036 :[r]slave or :[r]private propagation flag. Propagation property can be
1037 specified only for bind mounted volumes and not for internal volumes or
1038 named volumes. For mount propagation to work source mount point (mount
1039 point where source dir is mounted on) has to have right propagation
1040 properties. For shared volumes, source mount point has to be shared.
1041 And for slave volumes, source mount has to be either shared or slave.
1042 Use df <source-dir> to figure out the source mount and then use findmnt
1045 -o TARGET,PROPAGATION <source-mount-dir> to figure out propagation
1046 properties of source mount. If findmnt utility is not available, then
1047 one can look at mount entry for source mount point in
1048 /proc/self/mountinfo. Look at optional fields and see if any propaga‐
1049 tion properties are specified. shared:X means mount is shared, mas‐
1050 ter:X means mount is slave and if nothing is there that means mount is
1051 private.
1052 To change propagation properties of a mount point use mount command.
1055 For example, if one wants to bind mount source directory /foo one can
1056 do mount --bind /foo /foo and mount --make-private --make-shared /foo.
1057 This will convert /foo into a shared mount point. Alternatively one can
1058 directly change propagation properties of source mount. Say / is source
1059 mount for /foo, then use mount --make-shared / to convert / into a
1060 shared mount.
1061 Note: When using systemd to manage the Docker daemon's start and
1064 stop, in the systemd unit file there is an option to control
1065 mount propagation for the Docker daemon itself, called Mount‐
1066 Flags. The value of this setting may cause Docker to not see
1067 mount propagation changes made on the mount point. For example,
1068 if this value is slave, you may not be able to use the shared or
1069 rshared propagation on a volume.
1070 To disable automatic copying of data from the container path to the
1074 volume, use the nocopy flag. The nocopy flag can be set on bind mounts
1075 and named volumes.
1076 See also --mount, which is the successor of --tmpfs and --volume. Even
1079 though there is no plan to deprecate --volume, usage of --mount is rec‐
1080 ommended.
1081 --volume-driver=""
1084 Container's volume driver. This driver creates volumes specified
1085 either from
1086 a Dockerfile's VOLUME instruction or from the docker run -v flag.
1087 See docker-volume-create(1) for full details.
1088 --volumes-from=[]
1091 Mount volumes from the specified container(s)
1092 Mounts already mounted volumes from a source container onto another
1095 container. You must supply the source's container-id. To share
1096 a volume, use the --volumes-from option when running
1097 the target container. You can share volumes even if the source con‐
1098 tainer
1099 is not running.
1100 By default, Docker mounts the volumes in the same mode (read-write or
1103 read-only) as it is mounted in the source container. Optionally, you
1104 can change this by suffixing the container-id with either the :ro or
1105 :rw keyword.
1106 If the location of the volume from the source container overlaps with
1109 data residing on a target container, then the volume hides
1110 that data on the target.
1111 -w, --workdir=""
1114 Working directory inside the container
1115 The default working directory for running binaries within a container
1118 is the root directory (/). The developer can set a different default
1119 with the Dockerfile WORKDIR instruction. The operator can override the
1120 working directory by using the -w option.
1121
1125 The exit code from docker run gives information about why the container
1126 failed to run or why it exited. When docker run exits with a non-zero
1127 code, the exit codes follow the chroot standard, see below:
1128 125 if the error is with Docker daemon itself
1131 $ docker run --foo busybox; echo $?
1134 # flag provided but not defined: --foo
1135 See 'docker run --help'.
1136 125
1137 126 if the contained command cannot be invoked
1141 $ docker run busybox /etc; echo $?
1144 # exec: "/etc": permission denied
1145 docker: Error response from daemon: Contained command could not be invoked
1146 126
1147 127 if the contained command cannot be found
1151 $ docker run busybox foo; echo $?
1154 # exec: "foo": executable file not found in $PATH
1155 docker: Error response from daemon: Contained command not found or does not exist
1156 127
1157 Exit code of contained command otherwise
1161 $ docker run busybox /bin/sh -c 'exit 3'
1164 # 3
1165
1171 During container image development, containers often need to write to
1172 the image content. Installing packages into /usr, for example. In
1173 production, applications seldom need to write to the image. Container
1174 applications write to volumes if they need to write to file systems at
1175 all. Applications can be made more secure by running them in read-only
1176 mode using the --read-only switch. This protects the containers image
1177 from modification. Read only containers may still need to write tempo‐
1178 rary data. The best way to handle this is to mount tmpfs directories
1179 on /run and /tmp.
1180 # docker run --read-only --tmpfs /run --tmpfs /tmp -i -t fedora /bin/bash
1183
1187 If you want messages that are logged in your container to show up in
1188 the host's syslog/journal then you should bind mount the /dev/log
1189 directory as follows.
1190 # docker run -v /dev/log:/dev/log -i -t fedora /bin/bash
1193 From inside the container you can test this by sending a message to the
1197 log.
1198 (bash)# logger "Hello from my container"
1201 Then exit and check the journal.
1205 # exit
1208 # journalctl -b | grep Hello
1210 This should list the message sent to logger.
1214
1217 If you do not specify -a then Docker will attach everything (stdin,std‐
1218 out,stderr) you'd like to connect instead, as in:
1219 # docker run -a stdin -a stdout -i -t fedora /bin/bash
1222
1226 Using shm_server.c available here:
1227 https://www.cs.cf.ac.uk/Dave/C/node27.html
1228 Testing --ipc=host mode:
1231 Host shows a shared memory segment with 7 pids attached, happens to be
1234 from httpd:
1235 $ sudo ipcs -m
1238 ------ Shared Memory Segments --------
1240 key shmid owner perms bytes nattch status
1241 0x01128e25 0 root 600 1000 7
1242 Now run a regular container, and it correctly does NOT see the shared
1246 memory segment from the host:
1247 $ docker run -it shm ipcs -m
1250 ------ Shared Memory Segments --------
1252 key shmid owner perms bytes nattch status
1253 Run a container with the new --ipc=host option, and it now sees the
1257 shared memory segment from the host httpd:
1258 $ docker run -it --ipc=host shm ipcs -m
1261 ------ Shared Memory Segments --------
1263 key shmid owner perms bytes nattch status
1264 0x01128e25 0 root 600 1000 7
1265 Testing --ipc=container:CONTAINERID mode:
1269 Start a container with a program to create a shared memory segment:
1272 $ docker run -it shm bash
1275 $ sudo shm/shm_server
1276 $ sudo ipcs -m
1277 ------ Shared Memory Segments --------
1279 key shmid owner perms bytes nattch status
1280 0x0000162e 0 root 666 27 1
1281 Create a 2nd container correctly shows no shared memory segment from
1285 1st container:
1286 $ docker run shm ipcs -m
1289 ------ Shared Memory Segments --------
1291 key shmid owner perms bytes nattch status
1292 Create a 3rd container using the new --ipc=container:CONTAINERID
1296 option, now it shows the shared memory segment from the first:
1297 $ docker run -it --ipc=container:ed735b2264ac shm ipcs -m
1300 $ sudo ipcs -m
1301 ------ Shared Memory Segments --------
1303 key shmid owner perms bytes nattch status
1304 0x0000162e 0 root 666 27 1
1305
1309 Note: This section describes linking between containers on the
1310 default (bridge) network, also known as "legacy links". Using
1311 --link on user-defined networks uses the DNS-based discovery,
1312 which does not add entries to /etc/hosts, and does not set envi‐
1313 ronment variables for discovery.
1314 The link feature allows multiple containers to communicate with each
1318 other. For example, a container whose Dockerfile has exposed port 80
1319 can be run and named as follows:
1320 # docker run --name=link-test -d -i -t fedora/httpd
1323 A second container, in this case called linker, can communicate with
1327 the httpd container, named link-test, by running with the --link=:
1328 # docker run -t -i --link=link-test:lt --name=linker fedora /bin/bash
1331 Now the container linker is linked to container link-test with the
1335 alias lt. Running the env command in the linker container shows envi‐
1336 ronment variables
1337 with the LT (alias) context (LT_)
1338 # env
1341 HOSTNAME=668231cb0978
1342 TERM=xterm
1343 LT_PORT_80_TCP=tcp://172.17.0.3:80
1344 LT_PORT_80_TCP_PORT=80
1345 LT_PORT_80_TCP_PROTO=tcp
1346 LT_PORT=tcp://172.17.0.3:80
1347 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
1348 PWD=/
1349 LT_NAME=/linker/lt
1350 SHLVL=1
1351 HOME=/
1352 LT_PORT_80_TCP_ADDR=172.17.0.3
1353 _=/usr/bin/env
1354 When linking two containers Docker will use the exposed ports of the
1358 container to create a secure tunnel for the parent to access.
1359 If a container is connected to the default bridge network and linked
1362 with other containers, then the container's /etc/hosts file is updated
1363 with the linked container's name.
1364 Note Since Docker may live update the container's /etc/hosts
1367 file, there may be situations when processes inside the con‐
1368 tainer can end up reading an empty or incomplete /etc/hosts
1369 file. In most cases, retrying the read again should fix the
1370 problem.
1371
1375 The exposed port of an application can be mapped to a host port using
1376 the -p flag. For example, an httpd port 80 can be mapped to the host
1377 port 8080 using the following:
1378 # docker run -p 8080:80 -d -i -t fedora/httpd
1381
1385 Many applications require the sharing of persistent data across several
1386 containers. Docker allows you to create a Data Volume Container that
1387 other containers can mount from. For example, create a named container
1388 that contains directories /var/volume1 and /tmp/volume2. The image will
1389 need to contain these directories so a couple of RUN mkdir instructions
1390 might be required for you fedora-data image:
1391 # docker run --name=data -v /var/volume1 -v /tmp/volume2 -i -t fedora-data true
1394 # docker run --volumes-from=data --name=fedora-container1 -i -t fedora bash
1395 Multiple --volumes-from parameters will bring together multiple data
1399 volumes from multiple containers. And it's possible to mount the vol‐
1400 umes that came from the DATA container in yet another container via the
1401 fedora-container1 intermediary container, allowing to abstract the
1402 actual data source from users of that data:
1403 # docker run --volumes-from=fedora-container1 --name=fedora-container2 -i -t fedora bash
1406
1410 To mount a host directory as a container volume, specify the absolute
1411 path to the directory and the absolute path for the container directory
1412 separated by a colon:
1413 # docker run -v /var/db:/data1 -i -t fedora bash
1416 When using SELinux, be aware that the host has no knowledge of con‐
1420 tainer SELinux policy. Therefore, in the above example, if SELinux pol‐
1421 icy is enforced, the /var/db directory is not writable to the con‐
1422 tainer. A "Permission Denied" message will occur and an avc: message in
1423 the host's syslog.
1424 To work around this, at time of writing this man page, the following
1427 command needs to be run in order for the proper SELinux policy type
1428 label to be attached to the host directory:
1429 # chcon -Rt svirt_sandbox_file_t /var/db
1432 Now, writing to the /data1 volume in the container will be allowed and
1436 the changes will also be reflected on the host in /var/db.
1437
1440 You can override the default labeling scheme for each container by
1441 specifying the --security-opt flag. For example, you can specify the
1442 MCS/MLS level, a requirement for MLS systems. Specifying the level in
1443 the following command allows you to share the same content between con‐
1444 tainers.
1445 # docker run --security-opt label=level:s0:c100,c200 -i -t fedora bash
1448 An MLS example might be:
1452 # docker run --security-opt label=level:TopSecret -i -t rhel7 bash
1455 To disable the security labeling for this container versus running with
1459 the --permissive flag, use the following command:
1460 # docker run --security-opt label=disable -i -t fedora bash
1463 If you want a tighter security policy on the processes within a con‐
1467 tainer, you can specify an alternate type for the container. You could
1468 run a container that is only allowed to listen on Apache ports by exe‐
1469 cuting the following command:
1470 # docker run --security-opt label=type:svirt_apache_t -i -t centos bash
1473 Note:
1477 You would have to write policy defining a svirt_apache_t type.
1480
1483 If you want to set /dev/sda device weight to 200, you can specify the
1484 device weight by --blkio-weight-device flag. Use the following command:
1485 # docker run -it --blkio-weight-device "/dev/sda:200" ubuntu
1488
1492 This option is useful in situations where you are running Docker con‐
1493 tainers on Microsoft Windows. The --isolation <value> option sets a
1494 container's isolation technology. On Linux, the only supported is the
1495 default option which uses Linux namespaces. These two commands are
1496 equivalent on Linux:
1497 $ docker run -d busybox top
1500 $ docker run -d --isolation default busybox top
1501 On Microsoft Windows, can take any of these values:
1505 · default: Use the value specified by the Docker daemon's
1508 --exec-opt . If the daemon does not specify an isolation tech‐
1509 nology, Microsoft Windows uses process as its default value.
1510 · process: Namespace isolation only.
1512 · hyperv: Hyper-V hypervisor partition-based isolation.
1514 In practice, when running on Microsoft Windows without a daemon option
1518 set, these two commands are equivalent:
1519 $ docker run -d --isolation default busybox top
1522 $ docker run -d --isolation process busybox top
1523 If you have set the --exec-opt isolation=hyperv option on the Docker
1527 daemon, any of these commands also result in hyperv isolation:
1528 $ docker run -d --isolation default busybox top
1531 $ docker run -d --isolation hyperv busybox top
1532
1536 The --sysctl sets namespaced kernel parameters (sysctls) in the con‐
1537 tainer. For example, to turn on IP forwarding in the containers network
1538 namespace, run this command:
1539 $ docker run --sysctl net.ipv4.ip_forward=1 someimage
1542 Note:
1546 Not all sysctls are namespaced. Docker does not support changing
1549 sysctls inside of a container that also modify the host system. As the
1550 kernel evolves we expect to see more sysctls become namespaced.
1551 See the definition of the --sysctl option above for the current list of
1554 supported sysctls.
1555
1559 April 2014, Originally compiled by William Henry (whenry at redhat dot
1560 com) based on docker.com source material and internal work. June 2014,
1561 updated by Sven Dowideit SvenDowideit@home.org.au ⟨mailto:Sven‐
1562 Dowideit@home.org.au⟩ July 2014, updated by Sven Dowideit Sven‐
1563 Dowideit@home.org.au ⟨mailto:SvenDowideit@home.org.au⟩ November 2015,
1564 updated by Sally O'Malley somalley@redhat.com ⟨mailto:somalley@red‐
1565 hat.com⟩
1566Manuals User DOCKER(1)(Docker)