1DOCKER(1) Docker User Manuals DOCKER(1)
2
6 docker-run - Create and run a new container from an image
7
11 docker run [-a|--attach[=[]]] [--add-host[=[]]] [--annotation[=[]]]
12 [--blkio-weight[=[BLKIO-WEIGHT]]] [--blkio-weight-device[=[]]] [--cpu-
13 shares[=0]] [--cap-add[=[]]] [--cap-drop[=[]]] [--cgroupns[=[]]]
14 [--cgroup-parent[=CGROUP-PATH]] [--cidfile[=CIDFILE]] [--cpu-count[=0]]
15 [--cpu-percent[=0]] [--cpu-period[=0]] [--cpu-quota[=0]] [--cpu-rt-pe‐
16 riod[=0]] [--cpu-rt-runtime[=0]] [--cpus[=0.0]] [--cpuset-cpus[=CPUSET-
17 CPUS]] [--cpuset-mems[=CPUSET-MEMS]] [-d|--detach] [--detach-keys[=[]]]
18 [--device[=[]]] [--device-cgroup-rule[=[]]] [--device-read-bps[=[]]]
19 [--device-read-iops[=[]]] [--device-write-bps[=[]]] [--device-write-
20 iops[=[]]] [--dns[=[]]] [--dns-option[=[]]] [--dns-search[=[]]] [--do‐
21 mainname[=DOMAINNAME]] [-e|--env[=[]]] [--entrypoint[=ENTRYPOINT]]
22 [--env-file[=[]]] [--expose[=[]]] [--group-add[=[]]] [-h|--host‐
23 name[=HOSTNAME]] [--help] [--init] [-i|--interactive] [--ip[=IPv4-AD‐
24 DRESS]] [--ip6[=IPv6-ADDRESS]] [--ipc[=IPC]] [--isolation[=default]]
25 [--kernel-memory[=KERNEL-MEMORY]] [-l|--label[=[]]] [--label-file[=[]]]
26 [--link[=[]]] [--link-local-ip[=[]]] [--log-driver[=[]]] [--log-
27 opt[=[]]] [-m|--memory[=MEMORY]] [--mac-address[=MAC-ADDRESS]] [--mem‐
28 ory-reservation[=MEMORY-RESERVATION]] [--memory-swap[=LIMIT]] [--mem‐
29 ory-swappiness[=MEMORY-SWAPPINESS]] [--mount[=[MOUNT]]] [--name[=NAME]]
30 [--network-alias[=[]]] [--network[="bridge"]] [--oom-kill-disable]
31 [--oom-score-adj[=0]] [-P|--publish-all] [-p|--publish[=[]]]
32 [--pid[=[PID]]] [--userns[=[]]] [--pids-limit[=PIDS_LIMIT]] [--privi‐
33 leged] [--read-only] [--restart[=RESTART]] [--rm] [--security-opt[=[]]]
34 [--storage-opt[=[]]] [--stop-signal[=SIGNAL]] [--stop-timeout[=TIME‐
35 OUT]] [--shm-size[=[]]] [--sig-proxy[=true]] [--sysctl[=[]]] [-t|--tty]
36 [--tmpfs[=[CONTAINER-DIR[:OPTIONS]]] [-u|--user[=USER]] [--ulimit[=[]]]
37 [--uts[=[]]] [-v|--volume[=[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]]]
38 [--volume-driver[=DRIVER]] [--volumes-from[=[]]]
39 [-w|--workdir[=WORKDIR]] IMAGE [COMMAND] [ARG...]
40
44 Run a process in a new container. docker run starts a process with its
45 own file system, its own networking, and its own isolated process tree.
46 The IMAGE which starts the process may define defaults related to the
47 process that will be run in the container, the networking to expose,
48 and more, but docker run gives final control to the operator or admin‐
49 istrator who starts the container from the image. For that reason
50 docker run has more options than any other Docker command.
51 If the IMAGE is not already loaded then docker run will pull the IMAGE,
54 and all image dependencies, from the repository in the same way running
55 docker pull IMAGE, before it starts the container from that image.
56
60 -a, --attach=[]
61 Attach to STDIN, STDOUT or STDERR.
62 In foreground mode (the default when -d is not specified), docker run
65 can start the process in the container and attach the console to the
66 process's standard input, output, and standard error. It can even pre‐
67 tend to be a TTY (this is what most commandline executables expect) and
68 pass along signals. The -a option can be set for each of stdin, stdout,
69 and stderr.
70 --add-host=[]
73 Add a custom host-to-IP mapping (host:ip)
74 Add a line to /etc/hosts. The format is hostname:ip. The --add-host
77 option can be set multiple times.
78 --annotation=[]
81 Add an annotation to the container (passed through to the OCI run‐
82 time).
83 The annotations are provided to the OCI runtime.
86 --blkio-weight=0
89 Block IO weight (relative weight) accepts a weight value between 10
90 and 1000.
91 --blkio-weight-device=[]
94 Block IO weight (relative device weight, format: DE‐
95 VICE_NAME:WEIGHT).
96 --cpu-shares=0
99 CPU shares (relative weight)
100 By default, all containers get the same proportion of CPU cycles. This
103 proportion can be modified by changing the container's CPU share
104 weighting relative to the weighting of all other running containers.
105 To modify the proportion from the default of 1024, use the --cpu-shares
108 flag to set the weighting to 2 or higher.
109 The proportion will only apply when CPU-intensive processes are run‐
112 ning. When tasks in one container are idle, other containers can use
113 the left-over CPU time. The actual amount of CPU time will vary depend‐
114 ing on the number of containers running on the system.
115 For example, consider three containers, one has a cpu-share of 1024 and
118 two others have a cpu-share setting of 512. When processes in all three
119 containers attempt to use 100% of CPU, the first container would re‐
120 ceive 50% of the total CPU time. If you add a fourth container with a
121 cpu-share of 1024, the first container only gets 33% of the CPU. The
122 remaining containers receive 16.5%, 16.5% and 33% of the CPU.
123 On a multi-core system, the shares of CPU time are distributed over all
126 CPU cores. Even if a container is limited to less than 100% of CPU
127 time, it can use 100% of each individual CPU core.
128 For example, consider a system with more than three cores. If you start
131 one container {C0} with -c=512 running one process, and another con‐
132 tainer {C1} with -c=1024 running two processes, this can result in the
133 following division of CPU shares:
134 PID container CPU CPU share
137 100 {C0} 0 100% of CPU0
138 101 {C1} 1 100% of CPU1
139 102 {C1} 2 100% of CPU2
140 --cap-add=[]
144 Add Linux capabilities
145 --cap-drop=[]
148 Drop Linux capabilities
149 --cgroupns=""
152 Set the cgroup namespace mode for the container.
153 host: run the container in the host's cgroup namespace
154 private: run the container in its own private cgroup namespace
155 "": (unset) use the daemon's default configuration (host on
156 cgroup v1, private on cgroup v2)
157 --cgroup-parent=""
160 Path to cgroups under which the cgroup for the container will be
161 created. If the path is not absolute, the path is considered to be rel‐
162 ative to the cgroups path of the init process. Cgroups will be created
163 if they do not already exist.
164 --cidfile=""
167 Write the container ID to the file
168 --cpu-count=0
171 Limit the number of CPUs available for execution by the container.
172 On Windows Server containers, this is approximated as a percentage of total CPU usage.
175 On Windows Server containers, the processor resource controls are mutually exclusive, the order of precedence is CPUCount first, then CPUShares, and CPUPercent last.
177 --cpu-percent=0
181 Limit the percentage of CPU available for execution by a container
182 running on a Windows daemon.
183 On Windows Server containers, the processor resource controls are mutually exclusive, the order of precedence is CPUCount first, then CPUShares, and CPUPercent last.
186 --cpu-period=0
190 Limit the CPU CFS (Completely Fair Scheduler) period
191 Limit the container's CPU usage. This flag tell the kernel to restrict
194 the container's CPU usage to the period you specify.
195 --cpuset-cpus=""
198 CPUs in which to allow execution (0-3, 0,1)
199 --cpuset-mems=""
202 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only ef‐
203 fective on NUMA systems.
204 If you have four memory nodes on your system (0-3), use --cpuset-
207 mems=0,1 then processes in your Docker container will only use memory
208 from the first two memory nodes.
209 --cpu-quota=0
212 Limit the CPU CFS (Completely Fair Scheduler) quota
213 Limit the container's CPU usage. By default, containers run with the
216 full CPU resource. This flag tell the kernel to restrict the con‐
217 tainer's CPU usage to the quota you specify.
218 --cpu-rt-period=0
221 Limit the CPU real-time period in microseconds
222 Limit the container's Real Time CPU usage. This flag tell the kernel to
225 restrict the container's Real Time CPU usage to the period you specify.
226 --cpu-rt-runtime=0
229 Limit the CPU real-time runtime in microseconds
230 Limit the containers Real Time CPU usage. This flag tells the kernel to
233 limit the amount of time in a given CPU period Real Time tasks may con‐
234 sume. Ex:
235 Period of 1,000,000us and Runtime of 950,000us means that this con‐
236 tainer could consume 95% of available CPU and leave the remaining 5% to
237 normal priority tasks.
238 The sum of all runtimes across containers cannot exceed the amount al‐
241 lotted to the parent cgroup.
242 --cpus=0.0
245 Number of CPUs. The default is 0.0 which means no limit.
246 -d, --detach=true|false
249 Detached mode: run the container in the background and print the new
250 container ID. The default is false.
251 At any time you can run docker ps in the other shell to view a list of
254 the running containers. You can reattach to a detached container with
255 docker attach.
256 When attached in the tty mode, you can detach from the container (and
259 leave it running) using a configurable key sequence. The default se‐
260 quence is CTRL-p CTRL-q. You configure the key sequence using the
261 --detach-keys option or a configuration file. See config-json(5) for
262 documentation on using a configuration file.
263 --detach-keys=key
266 Override the key sequence for detaching a container; key is a single
267 character from the [a-Z] range, or ctrl-value, where value is one of:
268 a-z, @, ^, [, ,, or _.
269 --device=onhost:incontainer[:mode]
272 Add a host device onhost to the container under the incontainer
273 name. Optional mode parameter can be used to specify device permis‐
274 sions, it is a combination of r (for read), w (for write), and m (for
275 mknod(2)).
276 For example, --device=/dev/sdc:/dev/xvdc:rwm will give a container all
279 permissions for the host device /dev/sdc, seen as /dev/xvdc inside the
280 container.
281 --device-cgroup-rule="type major:minor mode"
284 Add a rule to the cgroup allowed devices list. The rule is expected
285 to be in the format specified in the Linux kernel documentation (Docu‐
286 mentation/cgroup-v1/devices.txt):
287 - type: a (all), c (char), or b (block);
288 - major and minor: either a number, or * for all;
289 - mode: a composition of r (read), w (write), and m (mknod(2)).
290 Example: --device-cgroup-rule "c 1:3 mr": allow for a character device
293 idendified by 1:3 to be created and read.
294 --device-read-bps=[]
297 Limit read rate from a device (e.g. --device-read-bps=/dev/sda:1mb)
298 --device-read-iops=[]
301 Limit read rate from a device (e.g. --device-read-
302 iops=/dev/sda:1000)
303 --device-write-bps=[]
306 Limit write rate to a device (e.g. --device-write-bps=/dev/sda:1mb)
307 --device-write-iops=[]
310 Limit write rate to a device (e.g. --device-write-
311 iops=/dev/sda:1000)
312 --dns-search=[]
315 Set custom DNS search domains (Use --dns-search=. if you don't wish
316 to set the search domain)
317 --dns-option=[]
320 Set custom DNS options
321 --dns=[]
324 Set custom DNS servers
325 This option can be used to override the DNS configuration passed to the
328 container. Typically this is necessary when the host DNS configuration
329 is invalid for the container (e.g., 127.0.0.1). When this is the case
330 the --dns flags is necessary for every run.
331 --domainname=""
334 Container NIS domain name
335 Sets the container's NIS domain name (see also setdomainname(2)) that
338 is
339 available inside the container.
340 -e, --env=[]
343 Set environment variables
344 This option allows you to specify arbitrary environment variables that
347 are available for the process that will be launched inside of the con‐
348 tainer.
349 --entrypoint=""
352 Overwrite the default ENTRYPOINT of the image
353 This option allows you to overwrite the default entrypoint of the image
356 that is set in the Dockerfile. The ENTRYPOINT of an image is similar to
357 a COMMAND because it specifies what executable to run when the con‐
358 tainer starts, but it is (purposely) more difficult to override. The
359 ENTRYPOINT gives a container its default nature or behavior, so that
360 when you set an ENTRYPOINT you can run the container as if it were that
361 binary, complete with default options, and you can pass in more options
362 via the COMMAND. But, sometimes an operator may want to run something
363 else inside the container, so you can override the default ENTRYPOINT
364 at runtime by using a --entrypoint and a string to specify the new EN‐
365 TRYPOINT.
366 --env-file=[]
369 Read in a line delimited file of environment variables
370 --expose=[]
373 Expose a port, or a range of ports (e.g. --expose=3300-3310) informs
374 Docker that the container listens on the specified network ports at
375 runtime. Docker uses this information to interconnect containers using
376 links and to set up port redirection on the host system.
377 --group-add=[]
380 Add additional groups to run as
381 -h, --hostname=""
384 Container host name
385 Sets the container host name that is available inside the container.
388 --help
391 Print usage statement
392 --init
395 Run an init inside the container that forwards signals and reaps
396 processes
397 -i, --interactive=true|false
400 Keep STDIN open even if not attached. The default is false.
401 When set to true, keep stdin open even if not attached.
404 --ip=""
407 Sets the container's interface IPv4 address (e.g., 172.23.0.9)
408 It can only be used in conjunction with --network for user-defined net‐
411 works
412 --ip6=""
415 Sets the container's interface IPv6 address (e.g., 2001:db8::1b99)
416 It can only be used in conjunction with --network for user-defined net‐
419 works
420 --ipc=""
423 Sets the IPC mode for the container. The following values are ac‐
424 cepted:
425 ┌─────────────────────┬────────────────────────────┐
428 │Value │ Description │
429 ├─────────────────────┼────────────────────────────┤
430 │(empty) │ Use daemon's default. │
431 ├─────────────────────┼────────────────────────────┤
432 │none │ Own private IPC namespace, │
433 │ │ with /dev/shm not mounted. │
434 ├─────────────────────┼────────────────────────────┤
435 │private │ Own private IPC namespace. │
436 ├─────────────────────┼────────────────────────────┤
437 │shareable │ Own private IPC namespace, │
438 │ │ with a possibility to │
439 │ │ share it with other con‐ │
440 │ │ tainers. │
441 ├─────────────────────┼────────────────────────────┤
442 │container:name-or-ID │ Join another ("shareable") │
443 │ │ container's IPC namespace. │
444 ├─────────────────────┼────────────────────────────┤
445 │host │ Use the host system's IPC │
446 │ │ namespace. │
447 └─────────────────────┴────────────────────────────┘
448 If not specified, daemon default is used, which can either be private
450 or shareable, depending on the daemon version and configuration.
451 --isolation="default"
454 Isolation specifies the type of isolation technology used by con‐
455 tainers. Note that the default on Windows server is process, and the
456 default on Windows client is hyperv. Linux only supports default.
457 -l, --label key=value
460 Set metadata on the container (for example, --label com.exam‐
461 ple.key=value).
462 --kernel-memory=number[S]
465 Kernel memory limit; S is an optional suffix which can be one of b,
466 k, m, or g.
467 Constrains the kernel memory available to a container. If a limit of 0
470 is specified (not using --kernel-memory), the container's kernel memory
471 is not limited. If you specify a limit, it may be rounded up to a mul‐
472 tiple of the operating system's page size and the value can be very
473 large, millions of trillions.
474 --label-file=[]
477 Read in a line delimited file of labels
478 --link=name-or-id[:alias]
481 Add link to another container.
482 If the operator uses --link when starting the new client container,
485 then the client container can access the exposed port via a private
486 networking interface. Docker will set some environment variables in the
487 client container to help indicate which interface and port to use.
488 --link-local-ip=[]
491 Add one or more link-local IPv4/IPv6 addresses to the container's
492 interface
493 --log-driver="json-file|syslog|journald|gelf|flu‐
496 entd|awslogs|splunk|etwlogs|gcplogs|none"
497 Logging driver for the container. Default is defined by daemon --log-
498 driver flag.
499 Warning: the docker logs command works only for the json-file and
500 journald logging drivers.
501 --log-opt=[]
504 Logging driver specific options.
505 -m, --memory=number[*S]
508 Memory limit; S is an optional suffix which can be one of b, k, m,
509 or g.
510 Allows you to constrain the memory available to a container. If the
513 host supports swap memory, then the -m memory setting can be larger
514 than physical RAM. If a limit of 0 is specified (not using -m), the
515 container's memory is not limited. The actual limit may be rounded up
516 to a multiple of the operating system's page size (the value would be
517 very large, that's millions of trillions).
518 --memory-reservation=number[*S]
521 Memory soft limit; S is an optional suffix which can be one of b, k,
522 m, or g.
523 After setting memory reservation, when the system detects memory con‐
526 tention or low memory, containers are forced to restrict their consump‐
527 tion to their reservation. So you should always set the value below
528 --memory, otherwise the hard limit will take precedence. By default,
529 memory reservation will be the same as memory limit.
530 --memory-swap=number[S]
533 Combined memory plus swap limit; S is an optional suffix which can
534 be one of b, k, m, or g.
535 This option can only be used together with --memory. The argument
538 should always be larger than that of --memory. Default is double the
539 value of --memory. Set to -1 to enable unlimited swap.
540 --mac-address=""
543 Container MAC address (e.g., 92:d0:c6:0a:29:33)
544 Remember that the MAC address in an Ethernet network must be unique.
547 The IPv6 link-local address will be based on the device's MAC address
548 according to RFC4862.
549 --mount type=TYPE,TYPE-SPECIFIC-OPTION[,...]
552 Attach a filesystem mount to the container
553 Current supported mount TYPES are bind, volume, and tmpfs.
556 e.g.
559 type=bind,source=/path/on/host,destination=/path/in/container
562 type=volume,source=my-volume,destination=/path/in/container,volume-la‐
565 bel="color=red",volume-label="shape=round"
566 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
569 Common Options:
572 • src, source: mount source spec for bind and volume. Mandatory
575 for bind.
576 • dst, destination, target: mount destination spec.
578 • ro, readonly: true or false (default).
580 Note: setting readonly for a bind mount does not make its submounts
584 read-only on the current Linux implementation. See also bind-nonre‐
585 cursive.
586 Options specific to bind:
589 • bind-propagation: shared, slave, private, rshared, rslave, or
592 rprivate(default). See also mount(2).
593 • consistency: consistent(default), cached, or delegated. Cur‐
595 rently, only effective for Docker for Mac.
596 • bind-nonrecursive: true or false (default). If set to true,
598 submounts are not recursively bind-mounted. This option is
599 useful for readonly bind mount.
600 Options specific to volume:
604 • volume-driver: Name of the volume-driver plugin.
607 • volume-label: Custom metadata.
609 • volume-nocopy: true(default) or false. If set to false, the
611 Engine copies existing files and directories under the mount-
612 path into the volume, allowing the host to access them.
613 • volume-opt: specific to a given volume driver.
615 Options specific to tmpfs:
619 • tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by de‐
622 fault in Linux.
623 • tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or
625 0700.) Defaults to 1777 in Linux.
626 --name=""
630 Assign a name to the container
631 The operator can identify a container in three ways:
634 ┌──────────────────────┬────────────────────────────────────────────────────────────────────┐
637 │Identifier type │ Example value │
638 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
639 │UUID long identifier │ "f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778" │
640 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
641 │UUID short identifier │ "f78375b1c487" │
642 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
643 │Name │ "evil_ptolemy" │
644 └──────────────────────┴────────────────────────────────────────────────────────────────────┘
645 The UUID identifiers come from the Docker daemon, and if a name is not
647 assigned to the container with --name then the daemon will also gener‐
648 ate a random string name. The name is useful when defining links (see
649 --link) (or any other place you need to identify a container). This
650 works for both background and foreground Docker containers.
651 --network=type
654 Set the Network mode for the container. Supported values are:
655 ┌────────────────────────┬────────────────────────────┐
658 │Value │ Description │
659 ├────────────────────────┼────────────────────────────┤
660 │none │ No networking in the con‐ │
661 │ │ tainer. │
662 ├────────────────────────┼────────────────────────────┤
663 │bridge │ Connect the container to │
664 │ │ the default Docker bridge │
665 │ │ via veth interfaces. │
666 ├────────────────────────┼────────────────────────────┤
667 │host │ Use the host's network │
668 │ │ stack inside the con‐ │
669 │ │ tainer. │
670 ├────────────────────────┼────────────────────────────┤
671 │container:name|id │ Use the network stack of │
672 │ │ another container, speci‐ │
673 │ │ fied via its name or id. │
674 ├────────────────────────┼────────────────────────────┤
675 │network-name|network-id │ Connects the container to │
676 │ │ a user created network │
677 │ │ (using docker network cre‐ │
678 │ │ ate command) │
679 └────────────────────────┴────────────────────────────┘
680 Default is bridge.
682 --network-alias=[]
685 Add network-scoped alias for the container
686 --oom-kill-disable=true|false
689 Whether to disable OOM Killer for the container or not.
690 --oom-score-adj=""
693 Tune the host's OOM preferences for containers (accepts -1000 to
694 1000)
695 -P, --publish-all=true|false
698 Publish all exposed ports to random ports on the host interfaces.
699 The default is false.
700 When set to true publish all exposed ports to the host interfaces. The
703 default is false. If the operator uses -P (or -p) then Docker will make
704 the exposed port accessible on the host and the ports will be available
705 to any client that can reach the host. When using -P, Docker will bind
706 any exposed port to a random port on the host within an ephemeral port
707 range defined by /proc/sys/net/ipv4/ip_local_port_range. To find the
708 mapping between the host ports and the exposed ports, use docker
709 port(1).
710 -p, --publish ip:[hostPort]:containerPort | [hostPort:]containerPort
713 Publish a container's port, or range of ports, to the host.
714 Both hostPort and containerPort can be specified as a range. When
717 specifying ranges for both, the number of ports in ranges should be
718 equal.
719 Examples: -p 1234-1236:1222-1224, -p 127.0.0.1:$HOSTPORT:$CONTAINER‐
722 PORT.
723 Use docker port(1) to see the actual mapping, e.g. docker port CON‐
726 TAINER $CONTAINERPORT.
727 --pid=""
730 Set the PID mode for the container
731 Default is to create a private PID namespace for the container
732 'container:': join another container's
733 PID namespace
734 'host': use the host's PID namespace for
735 the container. Note: the host mode gives the container full access to
736 local PID and is therefore considered insecure.
737 --userns=""
740 Set the usernamespace mode for the container when userns-remap op‐
741 tion is enabled.
742 host: use the host usernamespace and enable all privileged options
743 (e.g., pid=host or --privileged).
744 --pids-limit=""
747 Tune the container's pids (process IDs) limit. Set to -1 to have un‐
748 limited pids for the container.
749 --uts=type
752 Set the UTS mode for the container. The only possible type is host,
753 meaning to use the host's UTS namespace inside the container.
754 Note: the host mode gives the container access to changing the
755 host's hostname and is therefore considered insecure.
756 --privileged [true|false]
759 Give extended privileges to this container. A "privileged" container
760 is given access to all devices.
761 When the operator executes docker run --privileged, Docker will enable
764 access to all devices on the host as well as set some configuration in
765 AppArmor to allow the container nearly all the same access to the host
766 as processes running outside of a container on the host.
767 --read-only=true|false
770 Mount the container's root filesystem as read only.
771 By default a container will have its root filesystem writable allowing
774 processes to write files anywhere. By specifying the --read-only flag
775 the container will have its root filesystem mounted as read only pro‐
776 hibiting any writes.
777 --restart policy
780 Restart policy to apply when a container exits. Supported values
781 are:
782 ┌─────────────────────────┬────────────────────────────┐
785 │Policy │ Result │
786 ├─────────────────────────┼────────────────────────────┤
787 │no │ Do not automatically │
788 │ │ restart the container when │
789 │ │ it exits. │
790 ├─────────────────────────┼────────────────────────────┤
791 │on-failure[:max-retries] │ Restart only if the con‐ │
792 │ │ tainer exits with a non- │
793 │ │ zero exit status. Option‐ │
794 │ │ ally, limit the number of │
795 │ │ restart retries the Docker │
796 │ │ daemon attempts. │
797 ├─────────────────────────┼────────────────────────────┤
798 │always │ Always restart the con‐ │
799 │ │ tainer regardless of the │
800 │ │ exit status. When you │
801 │ │ specify always, the Docker │
802 │ │ daemon will try to restart │
803 │ │ the container indefi‐ │
804 │ │ nitely. The container will │
805 │ │ also always start on dae‐ │
806 │ │ mon startup, regardless of │
807 │ │ the current state of the │
808 │ │ container. │
809 ├─────────────────────────┼────────────────────────────┤
810 │unless-stopped │ Always restart the con‐ │
811 │ │ tainer regardless of the │
812 │ │ exit status, but do not │
813 │ │ start it on daemon startup │
814 │ │ if the container has been │
815 │ │ put to a stopped state be‐ │
816 │ │ fore. │
817 └─────────────────────────┴────────────────────────────┘
818 Default is no.
820 --rm true|false
823 Automatically remove the container when it exits. The default is
824 false.
825 --rm flag can work together with -d, and auto-removal will be done
826 on daemon side. Note that it's incompatible with any restart policy
827 other than none.
828 --security-opt value[,...]
831 Security Options for the container. The following options can be
832 given:
833 "label=user:USER" : Set the label user for the container
836 "label=role:ROLE" : Set the label role for the container
837 "label=type:TYPE" : Set the label type for the container
838 "label=level:LEVEL" : Set the label level for the container
839 "label=disable" : Turn off label confinement for the container
840 "no-new-privileges" : Disable container processes from gaining additional privileges
841 "seccomp=unconfined" : Turn off seccomp confinement for the container
843 "seccomp=profile.json : White listed syscalls seccomp Json file to be used as a seccomp filter
844 "apparmor=unconfined" : Turn off apparmor confinement for the container
846 "apparmor=your-profile" : Set the apparmor confinement profile for the container
847 --storage-opt
851 Storage driver options per container
852 $ docker run -it --storage-opt size=120G fedora /bin/bash
855 This (size) will allow to set the container rootfs size to 120G at cre‐
858 ation time.
859 This option is only available for the devicemapper, btrfs, overlay2
860 and zfs graph drivers.
861 For the devicemapper, btrfs and zfs storage drivers, user cannot
862 pass a size less than the Default BaseFS Size.
863 For the overlay2 storage driver, the size option is only available
864 if the backing fs is xfs and mounted with the pquota mount option.
865 Under these conditions, user can pass any size less than the backing
866 fs size.
867 --stop-signal=""
870 Signal to stop the container.
871 The --stop-signal flag sets the system call signal that will be sent to
874 the
875 container to exit. This signal can be a signal name in the format
876 SIG<NAME>,
877 for instance SIGKILL, or an unsigned number that matches a position
878 in the
879 kernel's syscall table, for instance 9.
880 The default is defined by STOPSIGNAL in the image, or SIGTERM if the
883 image
884 has no STOPSIGNAL defined.
885 --stop-timeout
888 Timeout (in seconds) to stop a container, or -1 to disable timeout.
889 The --stop-timeout flag sets the number of seconds to wait for the con‐
892 tainer
893 to stop after sending the pre-defined (see --stop-signal) system call
894 signal.
895 If the container does not exit after the timeout elapses, it is
896 forcibly killed
897 with a SIGKILL signal.
898 If --stop-timeout is set to -1, no timeout is applied, and the daemon
901 will
902 wait indefinitely for the container to exit.
903 The default is determined by the daemon, and 10 seconds for Linux con‐
906 tainers,
907 and 30 seconds for Windows containers.
908 --shm-size=""
911 Size of /dev/shm. The format is <number><unit>.
912 number must be greater than 0. Unit is optional and can be b
913 (bytes), k (kilobytes), m(megabytes), or g (gigabytes).
914 If you omit the unit, the system uses bytes. If you omit the size
915 entirely, the system uses 64m.
916 --sysctl=SYSCTL
919 Configure namespaced kernel parameters at runtime
920 IPC Namespace - current sysctls allowed:
923 kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall,
926 kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced
927 Sysctls beginning with fs.mqueue.*
928 If you use the --ipc=host option these sysctls will not be allowed.
931 Network Namespace - current sysctls allowed:
934 Sysctls beginning with net.*
935 If you use the --network=host option these sysctls will not be allowed.
938 --sig-proxy=true|false
941 Proxy received signals to the process (non-TTY mode only). SIGCHLD,
942 SIGSTOP, and SIGKILL are not proxied. The default is true.
943 --memory-swappiness=""
946 Tune a container's memory swappiness behavior. Accepts an integer
947 between 0 and 100.
948 -t, --tty=true|false
951 Allocate a pseudo-TTY. The default is false.
952 When set to true Docker can allocate a pseudo-tty and attach to the
955 standard input of any container. This can be used, for example, to run
956 a throwaway interactive shell. The default is false.
957 The -t option is incompatible with a redirection of the docker client
960 standard input.
961 --tmpfs=[] Create a tmpfs mount
964 Mount a temporary filesystem (tmpfs) mount into a container, for exam‐
967 ple:
968 $ docker run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
971 This command mounts a tmpfs at /tmp within the container. The sup‐
974 ported mount options are the same as the Linux default mount flags. If
975 you do not specify any options, the systems uses the following options:
976 rw,noexec,nosuid,nodev,size=65536k.
977 See also --mount, which is the successor of --tmpfs and --volume.
980 Even though there is no plan to deprecate --tmpfs, usage of --mount
981 is recommended.
982 -u, --user=""
985 Sets the username or UID used and optionally the groupname or GID
986 for the specified command.
987 The followings examples are all valid:
990 --user [user | user:group | uid | uid:gid | user:gid | uid:group ]
991 Without this argument the command will be run as root in the container.
994 --ulimit=[]
997 Ulimit options
998 -v|--volume[=[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]]
1001 Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR,
1002 Docker
1003 bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Docker
1004 container. If 'HOST-DIR' is omitted, Docker automatically creates
1005 the new
1006 volume on the host. The OPTIONS are a comma delimited list and can
1007 be:
1008 • [rw|ro]
1011 • [z|Z]
1013 • [[r]shared|[r]slave|[r]private]
1015 • [delegated|cached|consistent]
1017 • [nocopy]
1019 The CONTAINER-DIR must be an absolute path such as /src/docs. The HOST-
1023 DIR can be an absolute path or a name value. A name value must start
1024 with an alphanumeric character, followed by a-z0-9, _ (underscore), .
1025 (period) or - (hyphen). An absolute path starts with a / (forward
1026 slash).
1027 If you supply a HOST-DIR that is an absolute path, Docker bind-mounts
1030 to the path you specify. If you supply a name, Docker creates a named
1031 volume by that name. For example, you can specify either /foo or foo
1032 for a HOST-DIR value. If you supply the /foo value, Docker creates a
1033 bind mount. If you supply the foo specification, Docker creates a named
1034 volume.
1035 You can specify multiple -v options to mount one or more mounts to a
1038 container. To use these same mounts in other containers, specify the
1039 --volumes-from option also.
1040 You can supply additional options for each bind mount following an ad‐
1043 ditional colon. A :ro or :rw suffix mounts a volume in read-only or
1044 read-write mode, respectively. By default, volumes are mounted in read-
1045 write mode. You can also specify the consistency requirement for the
1046 mount, either :consistent (the default), :cached, or :delegated. Mul‐
1047 tiple options are separated by commas, e.g. :ro,cached.
1048 Labeling systems like SELinux require that proper labels are placed on
1051 volume content mounted into a container. Without a label, the security
1052 system might prevent the processes running inside the container from
1053 using the content. By default, Docker does not change the labels set by
1054 the OS.
1055 To change a label in the container context, you can add either of two
1058 suffixes :z or :Z to the volume mount. These suffixes tell Docker to
1059 relabel file objects on the shared volumes. The z option tells Docker
1060 that two containers share the volume content. As a result, Docker la‐
1061 bels the content with a shared content label. Shared volume labels al‐
1062 low all containers to read/write content. The Z option tells Docker to
1063 label the content with a private unshared label. Only the current con‐
1064 tainer can use a private volume.
1065 By default bind mounted volumes are private. That means any mounts done
1068 inside container will not be visible on host and vice-a-versa. One can
1069 change this behavior by specifying a volume mount propagation property.
1070 Making a volume shared mounts done under that volume inside container
1071 will be visible on host and vice-a-versa. Making a volume slave enables
1072 only one way mount propagation and that is mounts done on host under
1073 that volume will be visible inside container but not the other way
1074 around.
1075 To control mount propagation property of volume one can use :[r]shared,
1078 :[r]slave or :[r]private propagation flag. Propagation property can be
1079 specified only for bind mounted volumes and not for internal volumes or
1080 named volumes. For mount propagation to work source mount point (mount
1081 point where source dir is mounted on) has to have right propagation
1082 properties. For shared volumes, source mount point has to be shared.
1083 And for slave volumes, source mount has to be either shared or slave.
1084 Use df <source-dir> to figure out the source mount and then use findmnt
1087 -o TARGET,PROPAGATION <source-mount-dir> to figure out propagation
1088 properties of source mount. If findmnt utility is not available, then
1089 one can look at mount entry for source mount point in
1090 /proc/self/mountinfo. Look at optional fields and see if any propaga‐
1091 tion properties are specified. shared:X means mount is shared, mas‐
1092 ter:X means mount is slave and if nothing is there that means mount is
1093 private.
1094 To change propagation properties of a mount point use mount command.
1097 For example, if one wants to bind mount source directory /foo one can
1098 do mount --bind /foo /foo and mount --make-private --make-shared /foo.
1099 This will convert /foo into a shared mount point. Alternatively one can
1100 directly change propagation properties of source mount. Say / is source
1101 mount for /foo, then use mount --make-shared / to convert / into a
1102 shared mount.
1103 Note: When using systemd to manage the Docker daemon's start and
1106 stop, in the systemd unit file there is an option to control
1107 mount propagation for the Docker daemon itself, called Mount‐
1108 Flags. The value of this setting may cause Docker to not see
1109 mount propagation changes made on the mount point. For example,
1110 if this value is slave, you may not be able to use the shared or
1111 rshared propagation on a volume.
1112 To disable automatic copying of data from the container path to the
1116 volume, use the nocopy flag. The nocopy flag can be set on bind mounts
1117 and named volumes.
1118 See also --mount, which is the successor of --tmpfs and --volume. Even
1121 though there is no plan to deprecate --volume, usage of --mount is rec‐
1122 ommended.
1123 --volume-driver=""
1126 Container's volume driver. This driver creates volumes specified ei‐
1127 ther from
1128 a Dockerfile's VOLUME instruction or from the docker run -v flag.
1129 See docker-volume-create(1) for full details.
1130 --volumes-from=[]
1133 Mount volumes from the specified container(s)
1134 Mounts already mounted volumes from a source container onto another
1137 container. You must supply the source's container-id. To share
1138 a volume, use the --volumes-from option when running
1139 the target container. You can share volumes even if the source con‐
1140 tainer
1141 is not running.
1142 By default, Docker mounts the volumes in the same mode (read-write or
1145 read-only) as it is mounted in the source container. Optionally, you
1146 can change this by suffixing the container-id with either the :ro or
1147 :rw keyword.
1148 If the location of the volume from the source container overlaps with
1151 data residing on a target container, then the volume hides
1152 that data on the target.
1153 -w, --workdir=""
1156 Working directory inside the container
1157 The default working directory for running binaries within a container
1160 is the root directory (/). The developer can set a different default
1161 with the Dockerfile WORKDIR instruction. The operator can override the
1162 working directory by using the -w option.
1163
1167 The exit code from docker run gives information about why the container
1168 failed to run or why it exited. When docker run exits with a non-zero
1169 code, the exit codes follow the chroot standard, see below:
1170 125 if the error is with Docker daemon itself
1173 $ docker run --foo busybox; echo $?
1176 # flag provided but not defined: --foo
1177 See 'docker run --help'.
1178 125
1179 126 if the contained command cannot be invoked
1183 $ docker run busybox /etc; echo $?
1186 # exec: "/etc": permission denied
1187 docker: Error response from daemon: Contained command could not be invoked
1188 126
1189 127 if the contained command cannot be found
1193 $ docker run busybox foo; echo $?
1196 # exec: "foo": executable file not found in $PATH
1197 docker: Error response from daemon: Contained command not found or does not exist
1198 127
1199 Exit code of contained command otherwise
1203 $ docker run busybox /bin/sh -c 'exit 3'
1206 # 3
1207
1213 During container image development, containers often need to write to
1214 the image content. Installing packages into /usr, for example. In
1215 production, applications seldom need to write to the image. Container
1216 applications write to volumes if they need to write to file systems at
1217 all. Applications can be made more secure by running them in read-only
1218 mode using the --read-only switch. This protects the containers image
1219 from modification. Read only containers may still need to write tempo‐
1220 rary data. The best way to handle this is to mount tmpfs directories
1221 on /run and /tmp.
1222 # docker run --read-only --tmpfs /run --tmpfs /tmp -i -t fedora /bin/bash
1225
1229 If you want messages that are logged in your container to show up in
1230 the host's syslog/journal then you should bind mount the /dev/log di‐
1231 rectory as follows.
1232 # docker run -v /dev/log:/dev/log -i -t fedora /bin/bash
1235 From inside the container you can test this by sending a message to the
1239 log.
1240 (bash)# logger "Hello from my container"
1243 Then exit and check the journal.
1247 # exit
1250 # journalctl -b | grep Hello
1252 This should list the message sent to logger.
1256
1259 If you do not specify -a then Docker will attach everything (stdin,std‐
1260 out,stderr) you'd like to connect instead, as in:
1261 # docker run -a stdin -a stdout -i -t fedora /bin/bash
1264
1268 Using shm_server.c available here:
1269 https://www.cs.cf.ac.uk/Dave/C/node27.html
1270 Testing --ipc=host mode:
1273 Host shows a shared memory segment with 7 pids attached, happens to be
1276 from httpd:
1277 $ sudo ipcs -m
1280 ------ Shared Memory Segments --------
1282 key shmid owner perms bytes nattch status
1283 0x01128e25 0 root 600 1000 7
1284 Now run a regular container, and it correctly does NOT see the shared
1288 memory segment from the host:
1289 $ docker run -it shm ipcs -m
1292 ------ Shared Memory Segments --------
1294 key shmid owner perms bytes nattch status
1295 Run a container with the new --ipc=host option, and it now sees the
1299 shared memory segment from the host httpd:
1300 $ docker run -it --ipc=host shm ipcs -m
1303 ------ Shared Memory Segments --------
1305 key shmid owner perms bytes nattch status
1306 0x01128e25 0 root 600 1000 7
1307 Testing --ipc=container:CONTAINERID mode:
1311 Start a container with a program to create a shared memory segment:
1314 $ docker run -it shm bash
1317 $ sudo shm/shm_server &
1318 $ sudo ipcs -m
1319 ------ Shared Memory Segments --------
1321 key shmid owner perms bytes nattch status
1322 0x0000162e 0 root 666 27 1
1323 Create a 2nd container correctly shows no shared memory segment from
1327 1st container:
1328 $ docker run shm ipcs -m
1331 ------ Shared Memory Segments --------
1333 key shmid owner perms bytes nattch status
1334 Create a 3rd container using the new --ipc=container:CONTAINERID op‐
1338 tion, now it shows the shared memory segment from the first:
1339 $ docker run -it --ipc=container:ed735b2264ac shm ipcs -m
1342 $ sudo ipcs -m
1343 ------ Shared Memory Segments --------
1345 key shmid owner perms bytes nattch status
1346 0x0000162e 0 root 666 27 1
1347
1351 Note: This section describes linking between containers on the
1352 default (bridge) network, also known as "legacy links". Using
1353 --link on user-defined networks uses the DNS-based discovery,
1354 which does not add entries to /etc/hosts, and does not set envi‐
1355 ronment variables for discovery.
1356 The link feature allows multiple containers to communicate with each
1360 other. For example, a container whose Dockerfile has exposed port 80
1361 can be run and named as follows:
1362 # docker run --name=link-test -d -i -t fedora/httpd
1365 A second container, in this case called linker, can communicate with
1369 the httpd container, named link-test, by running with the --link=:
1370 # docker run -t -i --link=link-test:lt --name=linker fedora /bin/bash
1373 Now the container linker is linked to container link-test with the
1377 alias lt. Running the env command in the linker container shows envi‐
1378 ronment variables
1379 with the LT (alias) context (LT_)
1380 # env
1383 HOSTNAME=668231cb0978
1384 TERM=xterm
1385 LT_PORT_80_TCP=tcp://172.17.0.3:80
1386 LT_PORT_80_TCP_PORT=80
1387 LT_PORT_80_TCP_PROTO=tcp
1388 LT_PORT=tcp://172.17.0.3:80
1389 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
1390 PWD=/
1391 LT_NAME=/linker/lt
1392 SHLVL=1
1393 HOME=/
1394 LT_PORT_80_TCP_ADDR=172.17.0.3
1395 _=/usr/bin/env
1396 When linking two containers Docker will use the exposed ports of the
1400 container to create a secure tunnel for the parent to access.
1401 If a container is connected to the default bridge network and linked
1404 with other containers, then the container's /etc/hosts file is updated
1405 with the linked container's name.
1406 Note Since Docker may live update the container's /etc/hosts
1409 file, there may be situations when processes inside the con‐
1410 tainer can end up reading an empty or incomplete /etc/hosts
1411 file. In most cases, retrying the read again should fix the
1412 problem.
1413
1417 The exposed port of an application can be mapped to a host port using
1418 the -p flag. For example, an httpd port 80 can be mapped to the host
1419 port 8080 using the following:
1420 # docker run -p 8080:80 -d -i -t fedora/httpd
1423
1427 Many applications require the sharing of persistent data across several
1428 containers. Docker allows you to create a Data Volume Container that
1429 other containers can mount from. For example, create a named container
1430 that contains directories /var/volume1 and /tmp/volume2. The image will
1431 need to contain these directories so a couple of RUN mkdir instructions
1432 might be required for you fedora-data image:
1433 # docker run --name=data -v /var/volume1 -v /tmp/volume2 -i -t fedora-data true
1436 # docker run --volumes-from=data --name=fedora-container1 -i -t fedora bash
1437 Multiple --volumes-from parameters will bring together multiple data
1441 volumes from multiple containers. And it's possible to mount the vol‐
1442 umes that came from the DATA container in yet another container via the
1443 fedora-container1 intermediary container, allowing to abstract the ac‐
1444 tual data source from users of that data:
1445 # docker run --volumes-from=fedora-container1 --name=fedora-container2 -i -t fedora bash
1448
1452 To mount a host directory as a container volume, specify the absolute
1453 path to the directory and the absolute path for the container directory
1454 separated by a colon:
1455 # docker run -v /var/db:/data1 -i -t fedora bash
1458 When using SELinux, be aware that the host has no knowledge of con‐
1462 tainer SELinux policy. Therefore, in the above example, if SELinux pol‐
1463 icy is enforced, the /var/db directory is not writable to the con‐
1464 tainer. A "Permission Denied" message will occur and an avc: message in
1465 the host's syslog.
1466 To work around this, at time of writing this man page, the following
1469 command needs to be run in order for the proper SELinux policy type la‐
1470 bel to be attached to the host directory:
1471 # chcon -Rt svirt_sandbox_file_t /var/db
1474 Now, writing to the /data1 volume in the container will be allowed and
1478 the changes will also be reflected on the host in /var/db.
1479
1482 You can override the default labeling scheme for each container by
1483 specifying the --security-opt flag. For example, you can specify the
1484 MCS/MLS level, a requirement for MLS systems. Specifying the level in
1485 the following command allows you to share the same content between con‐
1486 tainers.
1487 # docker run --security-opt label=level:s0:c100,c200 -i -t fedora bash
1490 An MLS example might be:
1494 # docker run --security-opt label=level:TopSecret -i -t rhel7 bash
1497 To disable the security labeling for this container versus running with
1501 the --permissive flag, use the following command:
1502 # docker run --security-opt label=disable -i -t fedora bash
1505 If you want a tighter security policy on the processes within a con‐
1509 tainer, you can specify an alternate type for the container. You could
1510 run a container that is only allowed to listen on Apache ports by exe‐
1511 cuting the following command:
1512 # docker run --security-opt label=type:svirt_apache_t -i -t centos bash
1515 Note:
1519 You would have to write policy defining a svirt_apache_t type.
1522
1525 If you want to set /dev/sda device weight to 200, you can specify the
1526 device weight by --blkio-weight-device flag. Use the following command:
1527 # docker run -it --blkio-weight-device "/dev/sda:200" ubuntu
1530
1534 This option is useful in situations where you are running Docker con‐
1535 tainers on Microsoft Windows. The --isolation <value> option sets a
1536 container's isolation technology. On Linux, the only supported is the
1537 default option which uses Linux namespaces. These two commands are
1538 equivalent on Linux:
1539 $ docker run -d busybox top
1542 $ docker run -d --isolation default busybox top
1543 On Microsoft Windows, can take any of these values:
1547 • default: Use the value specified by the Docker daemon's
1550 --exec-opt . If the daemon does not specify an isolation tech‐
1551 nology, Microsoft Windows uses process as its default value.
1552 • process: Namespace isolation only.
1554 • hyperv: Hyper-V hypervisor partition-based isolation.
1556 In practice, when running on Microsoft Windows without a daemon option
1560 set, these two commands are equivalent:
1561 $ docker run -d --isolation default busybox top
1564 $ docker run -d --isolation process busybox top
1565 If you have set the --exec-opt isolation=hyperv option on the Docker
1569 daemon, any of these commands also result in hyperv isolation:
1570 $ docker run -d --isolation default busybox top
1573 $ docker run -d --isolation hyperv busybox top
1574
1578 The --sysctl sets namespaced kernel parameters (sysctls) in the con‐
1579 tainer. For example, to turn on IP forwarding in the containers network
1580 namespace, run this command:
1581 $ docker run --sysctl net.ipv4.ip_forward=1 someimage
1584 Note:
1588 Not all sysctls are namespaced. Docker does not support changing
1591 sysctls inside of a container that also modify the host system. As the
1592 kernel evolves we expect to see more sysctls become namespaced.
1593 See the definition of the --sysctl option above for the current list of
1596 supported sysctls.
1597
1601 April 2014, Originally compiled by William Henry (whenry at redhat dot
1602 com) based on docker.com source material and internal work. June 2014,
1603 updated by Sven Dowideit SvenDowideit@home.org.au ⟨mailto:Sven‐
1604 Dowideit@home.org.au⟩ July 2014, updated by Sven Dowideit Sven‐
1605 Dowideit@home.org.au ⟨mailto:SvenDowideit@home.org.au⟩ November 2015,
1606 updated by Sally O'Malley somalley@redhat.com ⟨mailto:somalley@red‐
1607 hat.com⟩
1608Docker Community JUNE 2014 DOCKER(1)