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[=[]]]
12 [--blkio-weight[=[BLKIO-WEIGHT]]] [--blkio-weight-device[=[]]]
13 [--cpu-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]]
17 [--cpuset-cpus[=CPUSET-CPUS]] [--cpuset-mems[=CPUSET-MEMS]] [-d|--de‐
18 tach] [--detach-keys[=[]]] [--device[=[]]] [--device-cgroup-rule[=[]]]
19 [--device-read-bps[=[]]] [--device-read-iops[=[]]] [--de‐
20 vice-write-bps[=[]]] [--device-write-iops[=[]]] [--dns[=[]]] [--dns-op‐
21 tion[=[]]] [--dns-search[=[]]] [--domainname[=DOMAINNAME]]
22 [-e|--env[=[]]] [--entrypoint[=ENTRYPOINT]] [--env-file[=[]]] [--ex‐
23 pose[=[]]] [--group-add[=[]]] [-h|--hostname[=HOSTNAME]] [--help]
24 [--init] [-i|--interactive] [--ip[=IPv4-ADDRESS]] [--ip6[=IPv6-AD‐
25 DRESS]] [--ipc[=IPC]] [--isolation[=default]] [--kernel-memory[=KER‐
26 NEL-MEMORY]] [-l|--label[=[]]] [--label-file[=[]]] [--link[=[]]]
27 [--link-local-ip[=[]]] [--log-driver[=[]]] [--log-opt[=[]]] [-m|--mem‐
28 ory[=MEMORY]] [--mac-address[=MAC-ADDRESS]] [--memory-reservation[=MEM‐
29 ORY-RESERVATION]] [--memory-swap[=LIMIT]] [--memory-swappiness[=MEM‐
30 ORY-SWAPPINESS]] [--mount[=[MOUNT]]] [--name[=NAME]] [--net‐
31 work-alias[=[]]] [--network[="bridge"]] [--oom-kill-disable]
32 [--oom-score-adj[=0]] [-P|--publish-all] [-p|--publish[=[]]]
33 [--pid[=[PID]]] [--userns[=[]]] [--pids-limit[=PIDS_LIMIT]] [--privi‐
34 leged] [--read-only] [--restart[=RESTART]] [--rm] [--security-opt[=[]]]
35 [--storage-opt[=[]]] [--stop-signal[=SIGNAL]] [--stop-timeout[=TIME‐
36 OUT]] [--shm-size[=[]]] [--sig-proxy[=true]] [--sysctl[=[]]] [-t|--tty]
37 [--tmpfs[=[CONTAINER-DIR[:OPTIONS]]] [-u|--user[=USER]] [--ulimit[=[]]]
38 [--uts[=[]]] [-v|--volume[=[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]]]
39 [--volume-driver[=DRIVER]] [--volumes-from[=[]]]
40 [-w|--workdir[=WORKDIR]] IMAGE [COMMAND] [ARG...]
41
45 Run a process in a new container. docker run starts a process with its
46 own file system, its own networking, and its own isolated process tree.
47 The IMAGE which starts the process may define defaults related to the
48 process that will be run in the container, the networking to expose,
49 and more, but docker run gives final control to the operator or admin‐
50 istrator who starts the container from the image. For that reason
51 docker run has more options than any other Docker command.
52 If the IMAGE is not already loaded then docker run will pull the IMAGE,
55 and all image dependencies, from the repository in the same way running
56 docker pull IMAGE, before it starts the container from that image.
57
61 -a, --attach=[]
62 Attach to STDIN, STDOUT or STDERR.
63 In foreground mode (the default when -d is not specified), docker run
66 can start the process in the container and attach the console to the
67 process's standard input, output, and standard error. It can even pre‐
68 tend to be a TTY (this is what most commandline executables expect) and
69 pass along signals. The -a option can be set for each of stdin, stdout,
70 and stderr.
71 --add-host=[]
74 Add a custom host-to-IP mapping (host:ip)
75 Add a line to /etc/hosts. The format is hostname:ip. The --add-host
78 option can be set multiple times.
79 --blkio-weight=0
82 Block IO weight (relative weight) accepts a weight value between 10
83 and 1000.
84 --blkio-weight-device=[]
87 Block IO weight (relative device weight, format: DE‐
88 VICE_NAME:WEIGHT).
89 --cpu-shares=0
92 CPU shares (relative weight)
93 By default, all containers get the same proportion of CPU cycles. This
96 proportion can be modified by changing the container's CPU share
97 weighting relative to the weighting of all other running containers.
98 To modify the proportion from the default of 1024, use the --cpu-shares
101 flag to set the weighting to 2 or higher.
102 The proportion will only apply when CPU-intensive processes are run‐
105 ning. When tasks in one container are idle, other containers can use
106 the left-over CPU time. The actual amount of CPU time will vary depend‐
107 ing on the number of containers running on the system.
108 For example, consider three containers, one has a cpu-share of 1024 and
111 two others have a cpu-share setting of 512. When processes in all three
112 containers attempt to use 100% of CPU, the first container would re‐
113 ceive 50% of the total CPU time. If you add a fourth container with a
114 cpu-share of 1024, the first container only gets 33% of the CPU. The
115 remaining containers receive 16.5%, 16.5% and 33% of the CPU.
116 On a multi-core system, the shares of CPU time are distributed over all
119 CPU cores. Even if a container is limited to less than 100% of CPU
120 time, it can use 100% of each individual CPU core.
121 For example, consider a system with more than three cores. If you start
124 one container {C0} with -c=512 running one process, and another con‐
125 tainer {C1} with -c=1024 running two processes, this can result in the
126 following division of CPU shares:
127 PID container CPU CPU share
130 100 {C0} 0 100% of CPU0
131 101 {C1} 1 100% of CPU1
132 102 {C1} 2 100% of CPU2
133 --cap-add=[]
137 Add Linux capabilities
138 --cap-drop=[]
141 Drop Linux capabilities
142 --cgroupns=""
145 Set the cgroup namespace mode for the container.
146 host: run the container in the host's cgroup namespace
147 private: run the container in its own private cgroup namespace
148 "": (unset) use the daemon's default configuration (host on
149 cgroup v1, private on cgroup v2)
150 --cgroup-parent=""
153 Path to cgroups under which the cgroup for the container will be
154 created. If the path is not absolute, the path is considered to be rel‐
155 ative to the cgroups path of the init process. Cgroups will be created
156 if they do not already exist.
157 --cidfile=""
160 Write the container ID to the file
161 --cpu-count=0
164 Limit the number of CPUs available for execution by the container.
165 On Windows Server containers, this is approximated as a percentage of total CPU usage.
168 On Windows Server containers, the processor resource controls are mutually exclusive, the order of precedence is CPUCount first, then CPUShares, and CPUPercent last.
170 --cpu-percent=0
174 Limit the percentage of CPU available for execution by a container
175 running on a Windows daemon.
176 On Windows Server containers, the processor resource controls are mutually exclusive, the order of precedence is CPUCount first, then CPUShares, and CPUPercent last.
179 --cpu-period=0
183 Limit the CPU CFS (Completely Fair Scheduler) period
184 Limit the container's CPU usage. This flag tell the kernel to restrict
187 the container's CPU usage to the period you specify.
188 --cpuset-cpus=""
191 CPUs in which to allow execution (0-3, 0,1)
192 --cpuset-mems=""
195 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only ef‐
196 fective on NUMA systems.
197 If you have four memory nodes on your system (0-3), use
200 --cpuset-mems=0,1 then processes in your Docker container will only use
201 memory from the first two memory nodes.
202 --cpu-quota=0
205 Limit the CPU CFS (Completely Fair Scheduler) quota
206 Limit the container's CPU usage. By default, containers run with the
209 full CPU resource. This flag tell the kernel to restrict the con‐
210 tainer's CPU usage to the quota you specify.
211 --cpu-rt-period=0
214 Limit the CPU real-time period in microseconds
215 Limit the container's Real Time CPU usage. This flag tell the kernel to
218 restrict the container's Real Time CPU usage to the period you specify.
219 --cpu-rt-runtime=0
222 Limit the CPU real-time runtime in microseconds
223 Limit the containers Real Time CPU usage. This flag tells the kernel to
226 limit the amount of time in a given CPU period Real Time tasks may con‐
227 sume. Ex:
228 Period of 1,000,000us and Runtime of 950,000us means that this con‐
229 tainer could consume 95% of available CPU and leave the remaining 5% to
230 normal priority tasks.
231 The sum of all runtimes across containers cannot exceed the amount al‐
234 lotted to the parent cgroup.
235 --cpus=0.0
238 Number of CPUs. The default is 0.0 which means no limit.
239 -d, --detach=true|false
242 Detached mode: run the container in the background and print the new
243 container ID. The default is false.
244 At any time you can run docker ps in the other shell to view a list of
247 the running containers. You can reattach to a detached container with
248 docker attach.
249 When attached in the tty mode, you can detach from the container (and
252 leave it running) using a configurable key sequence. The default se‐
253 quence is CTRL-p CTRL-q. You configure the key sequence using the
254 --detach-keys option or a configuration file. See config-json(5) for
255 documentation on using a configuration file.
256 --detach-keys=key
259 Override the key sequence for detaching a container; key is a single
260 character from the [a-Z] range, or ctrl-value, where value is one of:
261 a-z, @, ^, [, ,, or _.
262 --device=onhost:incontainer[:mode]
265 Add a host device onhost to the container under the incontainer
266 name. Optional mode parameter can be used to specify device permis‐
267 sions, it is a combination of r (for read), w (for write), and m (for
268 mknod(2)).
269 For example, --device=/dev/sdc:/dev/xvdc:rwm will give a container all
272 permissions for the host device /dev/sdc, seen as /dev/xvdc inside the
273 container.
274 --device-cgroup-rule="type major:minor mode"
277 Add a rule to the cgroup allowed devices list. The rule is expected
278 to be in the format specified in the Linux kernel documentation (Docu‐
279 mentation/cgroup-v1/devices.txt):
280 - type: a (all), c (char), or b (block);
281 - major and minor: either a number, or * for all;
282 - mode: a composition of r (read), w (write), and m (mknod(2)).
283 Example: --device-cgroup-rule "c 1:3 mr": allow for a character device
286 idendified by 1:3 to be created and read.
287 --device-read-bps=[]
290 Limit read rate from a device (e.g. --device-read-bps=/dev/sda:1mb)
291 --device-read-iops=[]
294 Limit read rate from a device (e.g. --de‐
295 vice-read-iops=/dev/sda:1000)
296 --device-write-bps=[]
299 Limit write rate to a device (e.g. --device-write-bps=/dev/sda:1mb)
300 --device-write-iops=[]
303 Limit write rate to a device (e.g. --de‐
304 vice-write-iops=/dev/sda:1000)
305 --dns-search=[]
308 Set custom DNS search domains (Use --dns-search=. if you don't wish
309 to set the search domain)
310 --dns-option=[]
313 Set custom DNS options
314 --dns=[]
317 Set custom DNS servers
318 This option can be used to override the DNS configuration passed to the
321 container. Typically this is necessary when the host DNS configuration
322 is invalid for the container (e.g., 127.0.0.1). When this is the case
323 the --dns flags is necessary for every run.
324 --domainname=""
327 Container NIS domain name
328 Sets the container's NIS domain name (see also setdomainname(2)) that
331 is
332 available inside the container.
333 -e, --env=[]
336 Set environment variables
337 This option allows you to specify arbitrary environment variables that
340 are available for the process that will be launched inside of the con‐
341 tainer.
342 --entrypoint=""
345 Overwrite the default ENTRYPOINT of the image
346 This option allows you to overwrite the default entrypoint of the image
349 that is set in the Dockerfile. The ENTRYPOINT of an image is similar to
350 a COMMAND because it specifies what executable to run when the con‐
351 tainer starts, but it is (purposely) more difficult to override. The
352 ENTRYPOINT gives a container its default nature or behavior, so that
353 when you set an ENTRYPOINT you can run the container as if it were that
354 binary, complete with default options, and you can pass in more options
355 via the COMMAND. But, sometimes an operator may want to run something
356 else inside the container, so you can override the default ENTRYPOINT
357 at runtime by using a --entrypoint and a string to specify the new EN‐
358 TRYPOINT.
359 --env-file=[]
362 Read in a line delimited file of environment variables
363 --expose=[]
366 Expose a port, or a range of ports (e.g. --expose=3300-3310) informs
367 Docker that the container listens on the specified network ports at
368 runtime. Docker uses this information to interconnect containers using
369 links and to set up port redirection on the host system.
370 --group-add=[]
373 Add additional groups to run as
374 -h, --hostname=""
377 Container host name
378 Sets the container host name that is available inside the container.
381 --help
384 Print usage statement
385 --init
388 Run an init inside the container that forwards signals and reaps
389 processes
390 -i, --interactive=true|false
393 Keep STDIN open even if not attached. The default is false.
394 When set to true, keep stdin open even if not attached.
397 --ip=""
400 Sets the container's interface IPv4 address (e.g., 172.23.0.9)
401 It can only be used in conjunction with --network for user-defined net‐
404 works
405 --ip6=""
408 Sets the container's interface IPv6 address (e.g., 2001:db8::1b99)
409 It can only be used in conjunction with --network for user-defined net‐
412 works
413 --ipc=""
416 Sets the IPC mode for the container. The following values are ac‐
417 cepted:
418 ┌─────────────────────┬────────────────────────────┐
421 │Value │ Description │
422 ├─────────────────────┼────────────────────────────┤
423 │(empty) │ Use daemon's default. │
424 ├─────────────────────┼────────────────────────────┤
425 │none │ Own private IPC namespace, │
426 │ │ with /dev/shm not mounted. │
427 ├─────────────────────┼────────────────────────────┤
428 │private │ Own private IPC namespace. │
429 ├─────────────────────┼────────────────────────────┤
430 │shareable │ Own private IPC namespace, │
431 │ │ with a possibility to │
432 │ │ share it with other con‐ │
433 │ │ tainers. │
434 ├─────────────────────┼────────────────────────────┤
435 │container:name-or-ID │ Join another ("shareable") │
436 │ │ container's IPC namespace. │
437 ├─────────────────────┼────────────────────────────┤
438 │host │ Use the host system's IPC │
439 │ │ namespace. │
440 ├─────────────────────┼────────────────────────────┤
441 │ │ │
442 └─────────────────────┴────────────────────────────┘
443 If not specified, daemon default is used, which can either be private
445 or shareable, depending on the daemon version and configuration.
446 --isolation="default"
449 Isolation specifies the type of isolation technology used by con‐
450 tainers. Note that the default on Windows server is process, and the
451 default on Windows client is hyperv. Linux only supports default.
452 -l, --label key=value
455 Set metadata on the container (for example, --label com.exam‐
456 ple.key=value).
457 --kernel-memory=number[S]
460 Kernel memory limit; S is an optional suffix which can be one of b,
461 k, m, or g.
462 Constrains the kernel memory available to a container. If a limit of 0
465 is specified (not using --kernel-memory), the container's kernel memory
466 is not limited. If you specify a limit, it may be rounded up to a mul‐
467 tiple of the operating system's page size and the value can be very
468 large, millions of trillions.
469 --label-file=[]
472 Read in a line delimited file of labels
473 --link=name-or-id[:alias]
476 Add link to another container.
477 If the operator uses --link when starting the new client container,
480 then the client container can access the exposed port via a private
481 networking interface. Docker will set some environment variables in the
482 client container to help indicate which interface and port to use.
483 --link-local-ip=[]
486 Add one or more link-local IPv4/IPv6 addresses to the container's
487 interface
488 --log-driver="json-file|syslog|journald|gelf|flu‐
491 entd|awslogs|splunk|etwlogs|gcplogs|none"
492 Logging driver for the container. Default is defined by daemon
493 --log-driver flag.
494 Warning: the docker logs command works only for the json-file and
495 journald logging drivers.
496 --log-opt=[]
499 Logging driver specific options.
500 -m, --memory=number[*S]
503 Memory limit; S is an optional suffix which can be one of b, k, m,
504 or g.
505 Allows you to constrain the memory available to a container. If the
508 host supports swap memory, then the -m memory setting can be larger
509 than physical RAM. If a limit of 0 is specified (not using -m), the
510 container's memory is not limited. The actual limit may be rounded up
511 to a multiple of the operating system's page size (the value would be
512 very large, that's millions of trillions).
513 --memory-reservation=number[*S]
516 Memory soft limit; S is an optional suffix which can be one of b, k,
517 m, or g.
518 After setting memory reservation, when the system detects memory con‐
521 tention or low memory, containers are forced to restrict their consump‐
522 tion to their reservation. So you should always set the value below
523 --memory, otherwise the hard limit will take precedence. By default,
524 memory reservation will be the same as memory limit.
525 --memory-swap=number[S]
528 Combined memory plus swap limit; S is an optional suffix which can
529 be one of b, k, m, or g.
530 This option can only be used together with --memory. The argument
533 should always be larger than that of --memory. Default is double the
534 value of --memory. Set to -1 to enable unlimited swap.
535 --mac-address=""
538 Container MAC address (e.g., 92:d0:c6:0a:29:33)
539 Remember that the MAC address in an Ethernet network must be unique.
542 The IPv6 link-local address will be based on the device's MAC address
543 according to RFC4862.
544 --mount type=TYPE,TYPE-SPECIFIC-OPTION[,...]
547 Attach a filesystem mount to the container
548 Current supported mount TYPES are bind, volume, and tmpfs.
551 e.g.
554 type=bind,source=/path/on/host,destination=/path/in/container
557 type=volume,source=my-volume,destination=/path/in/container,volume-la‐
560 bel="color=red",volume-label="shape=round"
561 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
564 Common Options:
567 • src, source: mount source spec for bind and volume. Mandatory
570 for bind.
571 • dst, destination, target: mount destination spec.
573 • ro, readonly: true or false (default).
575 Note: setting readonly for a bind mount does not make its submounts
579 read-only on the current Linux implementation. See also bind-nonre‐
580 cursive.
581 Options specific to bind:
584 • bind-propagation: shared, slave, private, rshared, rslave, or
587 rprivate(default). See also mount(2).
588 • consistency: consistent(default), cached, or delegated. Cur‐
590 rently, only effective for Docker for Mac.
591 • bind-nonrecursive: true or false (default). If set to true,
593 submounts are not recursively bind-mounted. This option is
594 useful for readonly bind mount.
595 Options specific to volume:
599 • volume-driver: Name of the volume-driver plugin.
602 • volume-label: Custom metadata.
604 • volume-nocopy: true(default) or false. If set to false, the
606 Engine copies existing files and directories under the
607 mount-path into the volume, allowing the host to access them.
608 • volume-opt: specific to a given volume driver.
610 Options specific to tmpfs:
614 • tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by de‐
617 fault in Linux.
618 • tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or
620 0700.) Defaults to 1777 in Linux.
621 --name=""
625 Assign a name to the container
626 The operator can identify a container in three ways:
629 ┌──────────────────────┬────────────────────────────────────────────────────────────────────┐
632 │Identifier type │ Example value │
633 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
634 │UUID long identifier │ "f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778" │
635 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
636 │UUID short identifier │ "f78375b1c487" │
637 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
638 │Name │ "evil_ptolemy" │
639 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
640 │ │ │
641 └──────────────────────┴────────────────────────────────────────────────────────────────────┘
642 The UUID identifiers come from the Docker daemon, and if a name is not
644 assigned to the container with --name then the daemon will also gener‐
645 ate a random string name. The name is useful when defining links (see
646 --link) (or any other place you need to identify a container). This
647 works for both background and foreground Docker containers.
648 --network=type
651 Set the Network mode for the container. Supported values are:
652 ┌───────────────────────────────┬────────────────────────────┐
655 │Value │ Description │
656 ├───────────────────────────────┼────────────────────────────┤
657 │none │ No networking in the con‐ │
658 │ │ tainer. │
659 ├───────────────────────────────┼────────────────────────────┤
660 │bridge │ Connect the container to │
661 │ │ the default Docker bridge │
662 │ │ via veth interfaces. │
663 ├───────────────────────────────┼────────────────────────────┤
664 │host │ Use the host's network │
665 │ │ stack inside the con‐ │
666 │ │ tainer. │
667 ├───────────────────────────────┼────────────────────────────┤
668 │container:name|id │ Use the network stack of │
669 │ │ another container, speci‐ │
670 │ │ fied via its │
671 ├───────────────────────────────┼────────────────────────────┤
672 │name or │ │
673 ├───────────────────────────────┼────────────────────────────┤
674 │id. │ │
675 ├───────────────────────────────┼────────────────────────────┤
676 │network-name|network-id │ Connects the container to │
677 │ │ a user created network │
678 │ │ (using │
679 ├───────────────────────────────┼────────────────────────────┤
680 │docker network create command) │ │
681 ├───────────────────────────────┼────────────────────────────┤
682 │ │ │
683 └───────────────────────────────┴────────────────────────────┘
684 Default is bridge.
686 --network-alias=[]
689 Add network-scoped alias for the container
690 --oom-kill-disable=true|false
693 Whether to disable OOM Killer for the container or not.
694 --oom-score-adj=""
697 Tune the host's OOM preferences for containers (accepts -1000 to
698 1000)
699 -P, --publish-all=true|false
702 Publish all exposed ports to random ports on the host interfaces.
703 The default is false.
704 When set to true publish all exposed ports to the host interfaces. The
707 default is false. If the operator uses -P (or -p) then Docker will make
708 the exposed port accessible on the host and the ports will be available
709 to any client that can reach the host. When using -P, Docker will bind
710 any exposed port to a random port on the host within an ephemeral port
711 range defined by /proc/sys/net/ipv4/ip_local_port_range. To find the
712 mapping between the host ports and the exposed ports, use docker
713 port(1).
714 -p, --publish ip:[hostPort]:containerPort | [hostPort:]containerPort
717 Publish a container's port, or range of ports, to the host.
718 Both hostPort and containerPort can be specified as a range. When
721 specifying ranges for both, the number of ports in ranges should be
722 equal.
723 Examples: -p 1234-1236:1222-1224, -p 127.0.0.1:$HOSTPORT:$CONTAINER‐
726 PORT.
727 Use docker port(1) to see the actual mapping, e.g. docker port CON‐
730 TAINER $CONTAINERPORT.
731 --pid=""
734 Set the PID mode for the container
735 Default is to create a private PID namespace for the container
736 'container:': join another container's
737 PID namespace
738 'host': use the host's PID namespace for
739 the container. Note: the host mode gives the container full access to
740 local PID and is therefore considered insecure.
741 --userns=""
744 Set the usernamespace mode for the container when userns-remap op‐
745 tion is enabled.
746 host: use the host usernamespace and enable all privileged options
747 (e.g., pid=host or --privileged).
748 --pids-limit=""
751 Tune the container's pids (process IDs) limit. Set to -1 to have un‐
752 limited pids for the container.
753 --uts=type
756 Set the UTS mode for the container. The only possible type is host,
757 meaning to use the host's UTS namespace inside the container.
758 Note: the host mode gives the container access to changing the
759 host's hostname and is therefore considered insecure.
760 --privileged [true|false]
763 Give extended privileges to this container. A "privileged" container
764 is given access to all devices.
765 When the operator executes docker run --privileged, Docker will enable
768 access to all devices on the host as well as set some configuration in
769 AppArmor to allow the container nearly all the same access to the host
770 as processes running outside of a container on the host.
771 --read-only=true|false
774 Mount the container's root filesystem as read only.
775 By default a container will have its root filesystem writable allowing
778 processes to write files anywhere. By specifying the --read-only flag
779 the container will have its root filesystem mounted as read only pro‐
780 hibiting any writes.
781 --restart policy
784 Restart policy to apply when a container exits. Supported values
785 are:
786 ┌─────────────────────────┬────────────────────────────┐
789 │Policy │ Result │
790 ├─────────────────────────┼────────────────────────────┤
791 │no │ Do not automatically │
792 │ │ restart the container when │
793 │ │ it exits. │
794 ├─────────────────────────┼────────────────────────────┤
795 │on-failure[:max-retries] │ Restart only if the con‐ │
796 │ │ tainer exits with a │
797 │ │ non-zero exit status. Op‐ │
798 │ │ tionally, limit the number │
799 │ │ of restart retries the │
800 │ │ Docker daemon attempts. │
801 ├─────────────────────────┼────────────────────────────┤
802 │always │ Always restart the con‐ │
803 │ │ tainer regardless of the │
804 │ │ exit status. When you │
805 │ │ specify always, the Docker │
806 │ │ daemon will try to restart │
807 │ │ the container indefi‐ │
808 │ │ nitely. The container will │
809 │ │ also always start on dae‐ │
810 │ │ mon startup, regardless of │
811 │ │ the current state of the │
812 │ │ container. │
813 ├─────────────────────────┼────────────────────────────┤
814 │unless-stopped │ Always restart the con‐ │
815 │ │ tainer regardless of the │
816 │ │ exit status, but do not │
817 │ │ start it on daemon startup │
818 │ │ if the container has been │
819 │ │ put to a stopped state be‐ │
820 │ │ fore. │
821 ├─────────────────────────┼────────────────────────────┤
822 │ │ │
823 └─────────────────────────┴────────────────────────────┘
824 Default is no.
826 --rm true|false
829 Automatically remove the container when it exits. The default is
830 false.
831 --rm flag can work together with -d, and auto-removal will be done
832 on daemon side. Note that it's incompatible with any restart policy
833 other than none.
834 --security-opt value[,...]
837 Security Options for the container. The following options can be
838 given:
839 "label=user:USER" : Set the label user for the container
842 "label=role:ROLE" : Set the label role for the container
843 "label=type:TYPE" : Set the label type for the container
844 "label=level:LEVEL" : Set the label level for the container
845 "label=disable" : Turn off label confinement for the container
846 "no-new-privileges" : Disable container processes from gaining additional privileges
847 "seccomp=unconfined" : Turn off seccomp confinement for the container
849 "seccomp=profile.json : White listed syscalls seccomp Json file to be used as a seccomp filter
850 "apparmor=unconfined" : Turn off apparmor confinement for the container
852 "apparmor=your-profile" : Set the apparmor confinement profile for the container
853 --storage-opt
857 Storage driver options per container
858 $ docker run -it --storage-opt size=120G fedora /bin/bash
861 This (size) will allow to set the container rootfs size to 120G at cre‐
864 ation time.
865 This option is only available for the devicemapper, btrfs, overlay2
866 and zfs graph drivers.
867 For the devicemapper, btrfs and zfs storage drivers, user cannot
868 pass a size less than the Default BaseFS Size.
869 For the overlay2 storage driver, the size option is only available
870 if the backing fs is xfs and mounted with the pquota mount option.
871 Under these conditions, user can pass any size less than the backing
872 fs size.
873 --stop-signal=SIGTERM
876 Signal to stop a container. Default is SIGTERM.
877 --stop-timeout=10
880 Timeout (in seconds) to stop a container. Default is 10.
881 --shm-size=""
884 Size of /dev/shm. The format is <number><unit>.
885 number must be greater than 0. Unit is optional and can be b
886 (bytes), k (kilobytes), m(megabytes), or g (gigabytes).
887 If you omit the unit, the system uses bytes. If you omit the size
888 entirely, the system uses 64m.
889 --sysctl=SYSCTL
892 Configure namespaced kernel parameters at runtime
893 IPC Namespace - current sysctls allowed:
896 kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall,
899 kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced
900 Sysctls beginning with fs.mqueue.*
901 If you use the --ipc=host option these sysctls will not be allowed.
904 Network Namespace - current sysctls allowed:
907 Sysctls beginning with net.*
908 If you use the --network=host option these sysctls will not be allowed.
911 --sig-proxy=true|false
914 Proxy received signals to the process (non-TTY mode only). SIGCHLD,
915 SIGSTOP, and SIGKILL are not proxied. The default is true.
916 --memory-swappiness=""
919 Tune a container's memory swappiness behavior. Accepts an integer
920 between 0 and 100.
921 -t, --tty=true|false
924 Allocate a pseudo-TTY. The default is false.
925 When set to true Docker can allocate a pseudo-tty and attach to the
928 standard input of any container. This can be used, for example, to run
929 a throwaway interactive shell. The default is false.
930 The -t option is incompatible with a redirection of the docker client
933 standard input.
934 --tmpfs=[] Create a tmpfs mount
937 Mount a temporary filesystem (tmpfs) mount into a container, for exam‐
940 ple:
941 $ docker run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
944 This command mounts a tmpfs at /tmp within the container. The sup‐
947 ported mount options are the same as the Linux default mount flags. If
948 you do not specify any options, the systems uses the following options:
949 rw,noexec,nosuid,nodev,size=65536k.
950 See also --mount, which is the successor of --tmpfs and --volume.
953 Even though there is no plan to deprecate --tmpfs, usage of --mount
954 is recommended.
955 -u, --user=""
958 Sets the username or UID used and optionally the groupname or GID
959 for the specified command.
960 The followings examples are all valid:
963 --user [user | user:group | uid | uid:gid | user:gid | uid:group ]
964 Without this argument the command will be run as root in the container.
967 --ulimit=[]
970 Ulimit options
971 -v|--volume[=[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]]
974 Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR,
975 Docker
976 bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Docker
977 container. If 'HOST-DIR' is omitted, Docker automatically creates
978 the new
979 volume on the host. The OPTIONS are a comma delimited list and can
980 be:
981 • [rw|ro]
984 • [z|Z]
986 • [[r]shared|[r]slave|[r]private]
988 • [delegated|cached|consistent]
990 • [nocopy]
992 The CONTAINER-DIR must be an absolute path such as /src/docs. The
996 HOST-DIR can be an absolute path or a name value. A name value must
997 start with an alphanumeric character, followed by a-z0-9, _ (under‐
998 score), . (period) or - (hyphen). An absolute path starts with a /
999 (forward slash).
1000 If you supply a HOST-DIR that is an absolute path, Docker bind-mounts
1003 to the path you specify. If you supply a name, Docker creates a named
1004 volume by that name. For example, you can specify either /foo or foo
1005 for a HOST-DIR value. If you supply the /foo value, Docker creates a
1006 bind mount. If you supply the foo specification, Docker creates a named
1007 volume.
1008 You can specify multiple -v options to mount one or more mounts to a
1011 container. To use these same mounts in other containers, specify the
1012 --volumes-from option also.
1013 You can supply additional options for each bind mount following an ad‐
1016 ditional colon. A :ro or :rw suffix mounts a volume in read-only or
1017 read-write mode, respectively. By default, volumes are mounted in
1018 read-write mode. You can also specify the consistency requirement for
1019 the mount, either :consistent (the default), :cached, or :delegated.
1020 Multiple options are separated by commas, e.g. :ro,cached.
1021 Labeling systems like SELinux require that proper labels are placed on
1024 volume content mounted into a container. Without a label, the security
1025 system might prevent the processes running inside the container from
1026 using the content. By default, Docker does not change the labels set by
1027 the OS.
1028 To change a label in the container context, you can add either of two
1031 suffixes :z or :Z to the volume mount. These suffixes tell Docker to
1032 relabel file objects on the shared volumes. The z option tells Docker
1033 that two containers share the volume content. As a result, Docker la‐
1034 bels the content with a shared content label. Shared volume labels al‐
1035 low all containers to read/write content. The Z option tells Docker to
1036 label the content with a private unshared label. Only the current con‐
1037 tainer can use a private volume.
1038 By default bind mounted volumes are private. That means any mounts done
1041 inside container will not be visible on host and vice-a-versa. One can
1042 change this behavior by specifying a volume mount propagation property.
1043 Making a volume shared mounts done under that volume inside container
1044 will be visible on host and vice-a-versa. Making a volume slave enables
1045 only one way mount propagation and that is mounts done on host under
1046 that volume will be visible inside container but not the other way
1047 around.
1048 To control mount propagation property of volume one can use :[r]shared,
1051 :[r]slave or :[r]private propagation flag. Propagation property can be
1052 specified only for bind mounted volumes and not for internal volumes or
1053 named volumes. For mount propagation to work source mount point (mount
1054 point where source dir is mounted on) has to have right propagation
1055 properties. For shared volumes, source mount point has to be shared.
1056 And for slave volumes, source mount has to be either shared or slave.
1057 Use df <source-dir> to figure out the source mount and then use findmnt
1060 -o TARGET,PROPAGATION <source-mount-dir> to figure out propagation
1061 properties of source mount. If findmnt utility is not available, then
1062 one can look at mount entry for source mount point in
1063 /proc/self/mountinfo. Look at optional fields and see if any propaga‐
1064 tion properties are specified. shared:X means mount is shared, mas‐
1065 ter:X means mount is slave and if nothing is there that means mount is
1066 private.
1067 To change propagation properties of a mount point use mount command.
1070 For example, if one wants to bind mount source directory /foo one can
1071 do mount --bind /foo /foo and mount --make-private --make-shared /foo.
1072 This will convert /foo into a shared mount point. Alternatively one can
1073 directly change propagation properties of source mount. Say / is source
1074 mount for /foo, then use mount --make-shared / to convert / into a
1075 shared mount.
1076 Note: When using systemd to manage the Docker daemon's start and
1079 stop, in the systemd unit file there is an option to control
1080 mount propagation for the Docker daemon itself, called Mount‐
1081 Flags. The value of this setting may cause Docker to not see
1082 mount propagation changes made on the mount point. For example,
1083 if this value is slave, you may not be able to use the shared or
1084 rshared propagation on a volume.
1085 To disable automatic copying of data from the container path to the
1089 volume, use the nocopy flag. The nocopy flag can be set on bind mounts
1090 and named volumes.
1091 See also --mount, which is the successor of --tmpfs and --volume. Even
1094 though there is no plan to deprecate --volume, usage of --mount is rec‐
1095 ommended.
1096 --volume-driver=""
1099 Container's volume driver. This driver creates volumes specified ei‐
1100 ther from
1101 a Dockerfile's VOLUME instruction or from the docker run -v flag.
1102 See docker-volume-create(1) for full details.
1103 --volumes-from=[]
1106 Mount volumes from the specified container(s)
1107 Mounts already mounted volumes from a source container onto another
1110 container. You must supply the source's container-id. To share
1111 a volume, use the --volumes-from option when running
1112 the target container. You can share volumes even if the source con‐
1113 tainer
1114 is not running.
1115 By default, Docker mounts the volumes in the same mode (read-write or
1118 read-only) as it is mounted in the source container. Optionally, you
1119 can change this by suffixing the container-id with either the :ro or
1120 :rw keyword.
1121 If the location of the volume from the source container overlaps with
1124 data residing on a target container, then the volume hides
1125 that data on the target.
1126 -w, --workdir=""
1129 Working directory inside the container
1130 The default working directory for running binaries within a container
1133 is the root directory (/). The developer can set a different default
1134 with the Dockerfile WORKDIR instruction. The operator can override the
1135 working directory by using the -w option.
1136
1140 The exit code from docker run gives information about why the container
1141 failed to run or why it exited. When docker run exits with a non-zero
1142 code, the exit codes follow the chroot standard, see below:
1143 125 if the error is with Docker daemon itself
1146 $ docker run --foo busybox; echo $?
1149 # flag provided but not defined: --foo
1150 See 'docker run --help'.
1151 125
1152 126 if the contained command cannot be invoked
1156 $ docker run busybox /etc; echo $?
1159 # exec: "/etc": permission denied
1160 docker: Error response from daemon: Contained command could not be invoked
1161 126
1162 127 if the contained command cannot be found
1166 $ docker run busybox foo; echo $?
1169 # exec: "foo": executable file not found in $PATH
1170 docker: Error response from daemon: Contained command not found or does not exist
1171 127
1172 Exit code of contained command otherwise
1176 $ docker run busybox /bin/sh -c 'exit 3'
1179 # 3
1180
1186 During container image development, containers often need to write to
1187 the image content. Installing packages into /usr, for example. In
1188 production, applications seldom need to write to the image. Container
1189 applications write to volumes if they need to write to file systems at
1190 all. Applications can be made more secure by running them in read-only
1191 mode using the --read-only switch. This protects the containers image
1192 from modification. Read only containers may still need to write tempo‐
1193 rary data. The best way to handle this is to mount tmpfs directories
1194 on /run and /tmp.
1195 # docker run --read-only --tmpfs /run --tmpfs /tmp -i -t fedora /bin/bash
1198
1202 If you want messages that are logged in your container to show up in
1203 the host's syslog/journal then you should bind mount the /dev/log di‐
1204 rectory as follows.
1205 # docker run -v /dev/log:/dev/log -i -t fedora /bin/bash
1208 From inside the container you can test this by sending a message to the
1212 log.
1213 (bash)# logger "Hello from my container"
1216 Then exit and check the journal.
1220 # exit
1223 # journalctl -b | grep Hello
1225 This should list the message sent to logger.
1229
1232 If you do not specify -a then Docker will attach everything (stdin,std‐
1233 out,stderr) you'd like to connect instead, as in:
1234 # docker run -a stdin -a stdout -i -t fedora /bin/bash
1237
1241 Using shm_server.c available here:
1242 https://www.cs.cf.ac.uk/Dave/C/node27.html
1243 Testing --ipc=host mode:
1246 Host shows a shared memory segment with 7 pids attached, happens to be
1249 from httpd:
1250 $ sudo ipcs -m
1253 ------ Shared Memory Segments --------
1255 key shmid owner perms bytes nattch status
1256 0x01128e25 0 root 600 1000 7
1257 Now run a regular container, and it correctly does NOT see the shared
1261 memory segment from the host:
1262 $ docker run -it shm ipcs -m
1265 ------ Shared Memory Segments --------
1267 key shmid owner perms bytes nattch status
1268 Run a container with the new --ipc=host option, and it now sees the
1272 shared memory segment from the host httpd:
1273 $ docker run -it --ipc=host shm ipcs -m
1276 ------ Shared Memory Segments --------
1278 key shmid owner perms bytes nattch status
1279 0x01128e25 0 root 600 1000 7
1280 Testing --ipc=container:CONTAINERID mode:
1284 Start a container with a program to create a shared memory segment:
1287 $ docker run -it shm bash
1290 $ sudo shm/shm_server
1291 $ sudo ipcs -m
1292 ------ Shared Memory Segments --------
1294 key shmid owner perms bytes nattch status
1295 0x0000162e 0 root 666 27 1
1296 Create a 2nd container correctly shows no shared memory segment from
1300 1st container:
1301 $ docker run shm ipcs -m
1304 ------ Shared Memory Segments --------
1306 key shmid owner perms bytes nattch status
1307 Create a 3rd container using the new --ipc=container:CONTAINERID op‐
1311 tion, now it shows the shared memory segment from the first:
1312 $ docker run -it --ipc=container:ed735b2264ac shm ipcs -m
1315 $ sudo ipcs -m
1316 ------ Shared Memory Segments --------
1318 key shmid owner perms bytes nattch status
1319 0x0000162e 0 root 666 27 1
1320
1324 Note: This section describes linking between containers on the
1325 default (bridge) network, also known as "legacy links". Using
1326 --link on user-defined networks uses the DNS-based discovery,
1327 which does not add entries to /etc/hosts, and does not set envi‐
1328 ronment variables for discovery.
1329 The link feature allows multiple containers to communicate with each
1333 other. For example, a container whose Dockerfile has exposed port 80
1334 can be run and named as follows:
1335 # docker run --name=link-test -d -i -t fedora/httpd
1338 A second container, in this case called linker, can communicate with
1342 the httpd container, named link-test, by running with the --link=:
1343 # docker run -t -i --link=link-test:lt --name=linker fedora /bin/bash
1346 Now the container linker is linked to container link-test with the
1350 alias lt. Running the env command in the linker container shows envi‐
1351 ronment variables
1352 with the LT (alias) context (LT_)
1353 # env
1356 HOSTNAME=668231cb0978
1357 TERM=xterm
1358 LT_PORT_80_TCP=tcp://172.17.0.3:80
1359 LT_PORT_80_TCP_PORT=80
1360 LT_PORT_80_TCP_PROTO=tcp
1361 LT_PORT=tcp://172.17.0.3:80
1362 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
1363 PWD=/
1364 LT_NAME=/linker/lt
1365 SHLVL=1
1366 HOME=/
1367 LT_PORT_80_TCP_ADDR=172.17.0.3
1368 _=/usr/bin/env
1369 When linking two containers Docker will use the exposed ports of the
1373 container to create a secure tunnel for the parent to access.
1374 If a container is connected to the default bridge network and linked
1377 with other containers, then the container's /etc/hosts file is updated
1378 with the linked container's name.
1379 Note Since Docker may live update the container's /etc/hosts
1382 file, there may be situations when processes inside the con‐
1383 tainer can end up reading an empty or incomplete /etc/hosts
1384 file. In most cases, retrying the read again should fix the
1385 problem.
1386
1390 The exposed port of an application can be mapped to a host port using
1391 the -p flag. For example, an httpd port 80 can be mapped to the host
1392 port 8080 using the following:
1393 # docker run -p 8080:80 -d -i -t fedora/httpd
1396
1400 Many applications require the sharing of persistent data across several
1401 containers. Docker allows you to create a Data Volume Container that
1402 other containers can mount from. For example, create a named container
1403 that contains directories /var/volume1 and /tmp/volume2. The image will
1404 need to contain these directories so a couple of RUN mkdir instructions
1405 might be required for you fedora-data image:
1406 # docker run --name=data -v /var/volume1 -v /tmp/volume2 -i -t fedora-data true
1409 # docker run --volumes-from=data --name=fedora-container1 -i -t fedora bash
1410 Multiple --volumes-from parameters will bring together multiple data
1414 volumes from multiple containers. And it's possible to mount the vol‐
1415 umes that came from the DATA container in yet another container via the
1416 fedora-container1 intermediary container, allowing to abstract the ac‐
1417 tual data source from users of that data:
1418 # docker run --volumes-from=fedora-container1 --name=fedora-container2 -i -t fedora bash
1421
1425 To mount a host directory as a container volume, specify the absolute
1426 path to the directory and the absolute path for the container directory
1427 separated by a colon:
1428 # docker run -v /var/db:/data1 -i -t fedora bash
1431 When using SELinux, be aware that the host has no knowledge of con‐
1435 tainer SELinux policy. Therefore, in the above example, if SELinux pol‐
1436 icy is enforced, the /var/db directory is not writable to the con‐
1437 tainer. A "Permission Denied" message will occur and an avc: message in
1438 the host's syslog.
1439 To work around this, at time of writing this man page, the following
1442 command needs to be run in order for the proper SELinux policy type la‐
1443 bel to be attached to the host directory:
1444 # chcon -Rt svirt_sandbox_file_t /var/db
1447 Now, writing to the /data1 volume in the container will be allowed and
1451 the changes will also be reflected on the host in /var/db.
1452
1455 You can override the default labeling scheme for each container by
1456 specifying the --security-opt flag. For example, you can specify the
1457 MCS/MLS level, a requirement for MLS systems. Specifying the level in
1458 the following command allows you to share the same content between con‐
1459 tainers.
1460 # docker run --security-opt label=level:s0:c100,c200 -i -t fedora bash
1463 An MLS example might be:
1467 # docker run --security-opt label=level:TopSecret -i -t rhel7 bash
1470 To disable the security labeling for this container versus running with
1474 the --permissive flag, use the following command:
1475 # docker run --security-opt label=disable -i -t fedora bash
1478 If you want a tighter security policy on the processes within a con‐
1482 tainer, you can specify an alternate type for the container. You could
1483 run a container that is only allowed to listen on Apache ports by exe‐
1484 cuting the following command:
1485 # docker run --security-opt label=type:svirt_apache_t -i -t centos bash
1488 Note:
1492 You would have to write policy defining a svirt_apache_t type.
1495
1498 If you want to set /dev/sda device weight to 200, you can specify the
1499 device weight by --blkio-weight-device flag. Use the following command:
1500 # docker run -it --blkio-weight-device "/dev/sda:200" ubuntu
1503
1507 This option is useful in situations where you are running Docker con‐
1508 tainers on Microsoft Windows. The --isolation <value> option sets a
1509 container's isolation technology. On Linux, the only supported is the
1510 default option which uses Linux namespaces. These two commands are
1511 equivalent on Linux:
1512 $ docker run -d busybox top
1515 $ docker run -d --isolation default busybox top
1516 On Microsoft Windows, can take any of these values:
1520 • default: Use the value specified by the Docker daemon's
1523 --exec-opt . If the daemon does not specify an isolation tech‐
1524 nology, Microsoft Windows uses process as its default value.
1525 • process: Namespace isolation only.
1527 • hyperv: Hyper-V hypervisor partition-based isolation.
1529 In practice, when running on Microsoft Windows without a daemon option
1533 set, these two commands are equivalent:
1534 $ docker run -d --isolation default busybox top
1537 $ docker run -d --isolation process busybox top
1538 If you have set the --exec-opt isolation=hyperv option on the Docker
1542 daemon, any of these commands also result in hyperv isolation:
1543 $ docker run -d --isolation default busybox top
1546 $ docker run -d --isolation hyperv busybox top
1547
1551 The --sysctl sets namespaced kernel parameters (sysctls) in the con‐
1552 tainer. For example, to turn on IP forwarding in the containers network
1553 namespace, run this command:
1554 $ docker run --sysctl net.ipv4.ip_forward=1 someimage
1557 Note:
1561 Not all sysctls are namespaced. Docker does not support changing
1564 sysctls inside of a container that also modify the host system. As the
1565 kernel evolves we expect to see more sysctls become namespaced.
1566 See the definition of the --sysctl option above for the current list of
1569 supported sysctls.
1570
1574 April 2014, Originally compiled by William Henry (whenry at redhat dot
1575 com) based on docker.com source material and internal work. June 2014,
1576 updated by Sven Dowideit SvenDowideit@home.org.au ⟨mailto:Sven‐
1577 Dowideit@home.org.au⟩ July 2014, updated by Sven Dowideit Sven‐
1578 Dowideit@home.org.au ⟨mailto:SvenDowideit@home.org.au⟩ November 2015,
1579 updated by Sally O'Malley somalley@redhat.com ⟨mailto:somalley@red‐
1580 hat.com⟩
1581Docker Community JUNE 2014 DOCKER(1)