1DOCKER(1) JUNE 2014 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[=[]]]
14 [--cgroup-parent[=CGROUP-PATH]] [--cidfile[=CIDFILE]] [--cpu-count[=0]]
15 [--cpu-percent[=0]] [--cpu-period[=0]] [--cpu-quota[=0]]
16 [--cpu-rt-period[=0]] [--cpu-rt-runtime[=0]] [--cpus[=0.0]]
17 [--cpuset-cpus[=CPUSET-CPUS]] [--cpuset-mems[=CPUSET-MEMS]]
18 [-d|--detach] [--detach-keys[=[]]] [--device[=[]]]
19 [--device-cgroup-rule[=[]]] [--device-read-bps[=[]]]
20 [--device-read-iops[=[]]] [--device-write-bps[=[]]]
21 [--device-write-iops[=[]]] [--dns[=[]]] [--dns-option[=[]]]
22 [--dns-search[=[]]] [-e|--env[=[]]] [--entrypoint[=ENTRYPOINT]]
23 [--env-file[=[]]] [--expose[=[]]] [--group-add[=[]]]
24 [-h|--hostname[=HOSTNAME]] [--help] [--init] [-i|--interactive]
25 [--ip[=IPv4-ADDRESS]] [--ip6[=IPv6-ADDRESS]] [--ipc[=IPC]]
26 [--isolation[=default]] [--kernel-memory[=KERNEL-MEMORY]]
27 [-l|--label[=[]]] [--label-file[=[]]] [--link[=[]]]
28 [--link-local-ip[=[]]] [--log-driver[=[]]] [--log-opt[=[]]]
29 [-m|--memory[=MEMORY]] [--mac-address[=MAC-ADDRESS]]
30 [--memory-reservation[=MEMORY-RESERVATION]] [--memory-swap[=LIMIT]]
31 [--memory-swappiness[=MEMORY-SWAPPINESS]] [--mount[=[MOUNT]]]
32 [--name[=NAME]] [--network-alias[=[]]] [--network[="bridge"]]
33 [--oom-kill-disable] [--oom-score-adj[=0]] [-P|--publish-all]
34 [-p|--publish[=[]]] [--pid[=[PID]]] [--userns[=[]]]
35 [--pids-limit[=PIDS_LIMIT]] [--privileged] [--read-only]
36 [--restart[=RESTART]] [--rm] [--security-opt[=[]]] [--storage-opt[=[]]]
37 [--stop-signal[=SIGNAL]] [--stop-timeout[=TIMEOUT]] [--shm-size[=[]]]
38 [--sig-proxy[=true]] [--sysctl[=[]]] [-t|--tty]
39 [--tmpfs[=[CONTAINER-DIR[:OPTIONS]]] [-u|--user[=USER]] [--ulimit[=[]]]
40 [--uts[=[]]] [-v|--volume[=[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]]]
41 [--volume-driver[=DRIVER]] [--volumes-from[=[]]]
42 [-w|--workdir[=WORKDIR]] IMAGE [COMMAND] [ARG...]
43
47 Run a process in a new container. docker run starts a process with its
48 own file system, its own networking, and its own isolated process tree.
49 The IMAGE which starts the process may define defaults related to the
50 process that will be run in the container, the networking to expose,
51 and more, but docker run gives final control to the operator or
52 administrator who starts the container from the image. For that reason
53 docker run has more options than any other Docker command.
54 If the IMAGE is not already loaded then docker run will pull the IMAGE,
57 and all image dependencies, from the repository in the same way running
58 docker pull IMAGE, before it starts the container from that image.
59
63 -a, --attach=[]
64 Attach to STDIN, STDOUT or STDERR.
65 In foreground mode (the default when -d is not specified), docker run
68 can start the process in the container and attach the console to the
69 process's standard input, output, and standard error. It can even
70 pretend to be a TTY (this is what most commandline executables expect)
71 and pass along signals. The -a option can be set for each of stdin,
72 stdout, and stderr.
73 --add-host=[]
76 Add a custom host-to-IP mapping (host:ip)
77 Add a line to /etc/hosts. The format is hostname:ip. The --add-host
80 option can be set multiple times.
81 --blkio-weight=0
84 Block IO weight (relative weight) accepts a weight value between 10
85 and 1000.
86 --blkio-weight-device=[]
89 Block IO weight (relative device weight, format:
90 DEVICE_NAME:WEIGHT).
91 --cpu-shares=0
94 CPU shares (relative weight)
95 By default, all containers get the same proportion of CPU cycles. This
98 proportion can be modified by changing the container's CPU share
99 weighting relative to the weighting of all other running containers.
100 To modify the proportion from the default of 1024, use the --cpu-shares
103 flag to set the weighting to 2 or higher.
104 The proportion will only apply when CPU-intensive processes are
107 running. When tasks in one container are idle, other containers can
108 use the left-over CPU time. The actual amount of CPU time will vary
109 depending on the number of containers running on the system.
110 For example, consider three containers, one has a cpu-share of 1024 and
113 two others have a cpu-share setting of 512. When processes in all three
114 containers attempt to use 100% of CPU, the first container would
115 receive 50% of the total CPU time. If you add a fourth container with a
116 cpu-share of 1024, the first container only gets 33% of the CPU. The
117 remaining containers receive 16.5%, 16.5% and 33% of the CPU.
118 On a multi-core system, the shares of CPU time are distributed over all
121 CPU cores. Even if a container is limited to less than 100% of CPU
122 time, it can use 100% of each individual CPU core.
123 For example, consider a system with more than three cores. If you start
126 one container {C0} with -c=512 running one process, and another
127 container {C1} with -c=1024 running two processes, this can result in
128 the following division of CPU shares:
129 PID container CPU CPU share
132 100 {C0} 0 100% of CPU0
133 101 {C1} 1 100% of CPU1
134 102 {C1} 2 100% of CPU2
135 --cap-add=[]
139 Add Linux capabilities
140 --cap-drop=[]
143 Drop Linux capabilities
144 --cgroup-parent=""
147 Path to cgroups under which the cgroup for the container will be
148 created. If the path is not absolute, the path is considered to be
149 relative to the cgroups path of the init process. Cgroups will be
150 created if they do not already exist.
151 --cidfile=""
154 Write the container ID to the file
155 --cpu-count=0
158 Limit the number of CPUs available for execution by the container.
159 On Windows Server containers, this is approximated as a percentage of total CPU usage.
162 On Windows Server containers, the processor resource controls are mutually exclusive, the order of precedence is CPUCount first, then CPUShares, and CPUPercent last.
164 --cpu-percent=0
168 Limit the percentage of CPU available for execution by a container
169 running on a Windows daemon.
170 On Windows Server containers, the processor resource controls are mutually exclusive, the order of precedence is CPUCount first, then CPUShares, and CPUPercent last.
173 --cpu-period=0
177 Limit the CPU CFS (Completely Fair Scheduler) period
178 Limit the container's CPU usage. This flag tell the kernel to restrict
181 the container's CPU usage to the period you specify.
182 --cpuset-cpus=""
185 CPUs in which to allow execution (0-3, 0,1)
186 --cpuset-mems=""
189 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only
190 effective on NUMA systems.
191 If you have four memory nodes on your system (0-3), use
194 --cpuset-mems=0,1 then processes in your Docker container will only use
195 memory from the first two memory nodes.
196 --cpu-quota=0
199 Limit the CPU CFS (Completely Fair Scheduler) quota
200 Limit the container's CPU usage. By default, containers run with the
203 full CPU resource. This flag tell the kernel to restrict the
204 container's CPU usage to the quota you specify.
205 --cpu-rt-period=0
208 Limit the CPU real-time period in microseconds
209 Limit the container's Real Time CPU usage. This flag tell the kernel to
212 restrict the container's Real Time CPU usage to the period you specify.
213 --cpu-rt-runtime=0
216 Limit the CPU real-time runtime in microseconds
217 Limit the containers Real Time CPU usage. This flag tells the kernel to
220 limit the amount of time in a given CPU period Real Time tasks may
221 consume. Ex:
222 Period of 1,000,000us and Runtime of 950,000us means that this
223 container could consume 95% of available CPU and leave the remaining 5%
224 to normal priority tasks.
225 The sum of all runtimes across containers cannot exceed the amount
228 allotted to the parent cgroup.
229 --cpus=0.0
232 Number of CPUs. The default is 0.0 which means no limit.
233 -d, --detach=true|false
236 Detached mode: run the container in the background and print the new
237 container ID. The default is false.
238 At any time you can run docker ps in the other shell to view a list of
241 the running containers. You can reattach to a detached container with
242 docker attach.
243 When attached in the tty mode, you can detach from the container (and
246 leave it running) using a configurable key sequence. The default
247 sequence is CTRL-p CTRL-q. You configure the key sequence using the
248 --detach-keys option or a configuration file. See config-json(5) for
249 documentation on using a configuration file.
250 --detach-keys=key
253 Override the key sequence for detaching a container; key is a single
254 character from the [a-Z] range, or ctrl-value, where value is one of:
255 a-z, @, ^, [, ,, or _.
256 --device=onhost:incontainer[:mode]
259 Add a host device onhost to the container under the incontainer
260 name. Optional mode parameter can be used to specify device
261 permissions, it is a combination of r (for read), w (for write), and m
262 (for mknod(2)).
263 For example, --device=/dev/sdc:/dev/xvdc:rwm will give a container all
266 permissions for the host device /dev/sdc, seen as /dev/xvdc inside the
267 container.
268 --device-cgroup-rule="type major:minor mode"
271 Add a rule to the cgroup allowed devices list. The rule is expected
272 to be in the format specified in the Linux kernel documentation
273 (Documentation/cgroup-v1/devices.txt):
274 - type: a (all), c (char), or b (block);
275 - major and minor: either a number, or * for all;
276 - mode: a composition of r (read), w (write), and m (mknod(2)).
277 Example: --device-cgroup-rule "c 1:3 mr": allow for a character device
280 idendified by 1:3 to be created and read.
281 --device-read-bps=[]
284 Limit read rate from a device (e.g. --device-read-bps=/dev/sda:1mb)
285 --device-read-iops=[]
288 Limit read rate from a device (e.g.
289 --device-read-iops=/dev/sda:1000)
290 --device-write-bps=[]
293 Limit write rate to a device (e.g. --device-write-bps=/dev/sda:1mb)
294 --device-write-iops=[]
297 Limit write rate to a device (e.g.
298 --device-write-iops=/dev/sda:1000)
299 --dns-search=[]
302 Set custom DNS search domains (Use --dns-search=. if you don't wish
303 to set the search domain)
304 --dns-option=[]
307 Set custom DNS options
308 --dns=[]
311 Set custom DNS servers
312 This option can be used to override the DNS configuration passed to the
315 container. Typically this is necessary when the host DNS configuration
316 is invalid for the container (e.g., 127.0.0.1). When this is the case
317 the --dns flags is necessary for every run.
318 -e, --env=[]
321 Set environment variables
322 This option allows you to specify arbitrary environment variables that
325 are available for the process that will be launched inside of the
326 container.
327 --entrypoint=""
330 Overwrite the default ENTRYPOINT of the image
331 This option allows you to overwrite the default entrypoint of the image
334 that is set in the Dockerfile. The ENTRYPOINT of an image is similar to
335 a COMMAND because it specifies what executable to run when the
336 container starts, but it is (purposely) more difficult to override. The
337 ENTRYPOINT gives a container its default nature or behavior, so that
338 when you set an ENTRYPOINT you can run the container as if it were that
339 binary, complete with default options, and you can pass in more options
340 via the COMMAND. But, sometimes an operator may want to run something
341 else inside the container, so you can override the default ENTRYPOINT
342 at runtime by using a --entrypoint and a string to specify the new
343 ENTRYPOINT.
344 --env-file=[]
347 Read in a line delimited file of environment variables
348 --expose=[]
351 Expose a port, or a range of ports (e.g. --expose=3300-3310) informs
352 Docker that the container listens on the specified network ports at
353 runtime. Docker uses this information to interconnect containers using
354 links and to set up port redirection on the host system.
355 --group-add=[]
358 Add additional groups to run as
359 -h, --hostname=""
362 Container host name
363 Sets the container host name that is available inside the container.
366 --help
369 Print usage statement
370 --init
373 Run an init inside the container that forwards signals and reaps
374 processes
375 -i, --interactive=true|false
378 Keep STDIN open even if not attached. The default is false.
379 When set to true, keep stdin open even if not attached.
382 --ip=""
385 Sets the container's interface IPv4 address (e.g., 172.23.0.9)
386 It can only be used in conjunction with --network for user-defined
389 networks
390 --ip6=""
393 Sets the container's interface IPv6 address (e.g., 2001:db8::1b99)
394 It can only be used in conjunction with --network for user-defined
397 networks
398 --ipc=""
401 Sets the IPC mode for the container. The following values are
402 accepted:
403 ┌─────────────────────┬────────────────────────────┐
406 │Value │ Description │
407 ├─────────────────────┼────────────────────────────┤
408 │(empty) │ Use daemon's default. │
409 ├─────────────────────┼────────────────────────────┤
410 │none │ Own private IPC namespace, │
411 │ │ with /dev/shm not mounted. │
412 ├─────────────────────┼────────────────────────────┤
413 │private │ Own private IPC namespace. │
414 ├─────────────────────┼────────────────────────────┤
415 │shareable │ Own private IPC namespace, │
416 │ │ with a possibility to │
417 │ │ share it with other │
418 │ │ containers. │
419 ├─────────────────────┼────────────────────────────┤
420 │container:name-or-ID │ Join another ("shareable") │
421 │ │ container's IPC namespace. │
422 ├─────────────────────┼────────────────────────────┤
423 │host │ Use the host system's IPC │
424 │ │ namespace. │
425 └─────────────────────┴────────────────────────────┘
426 If not specified, daemon default is used, which can either be private
428 or shareable, depending on the daemon version and configuration.
429 --isolation="default"
432 Isolation specifies the type of isolation technology used by
433 containers. Note that the default on Windows server is process, and the
434 default on Windows client is hyperv. Linux only supports default.
435 -l, --label key=value
438 Set metadata on the container (for example, --label
439 com.example.key=value).
440 --kernel-memory=number[S]
443 Kernel memory limit; S is an optional suffix which can be one of b,
444 k, m, or g.
445 Constrains the kernel memory available to a container. If a limit of 0
448 is specified (not using --kernel-memory), the container's kernel memory
449 is not limited. If you specify a limit, it may be rounded up to a
450 multiple of the operating system's page size and the value can be very
451 large, millions of trillions.
452 --label-file=[]
455 Read in a line delimited file of labels
456 --link=name-or-id[:alias]
459 Add link to another container.
460 If the operator uses --link when starting the new client container,
463 then the client container can access the exposed port via a private
464 networking interface. Docker will set some environment variables in the
465 client container to help indicate which interface and port to use.
466 --link-local-ip=[]
469 Add one or more link-local IPv4/IPv6 addresses to the container's
470 interface
471 --log-driver="json-file|syslog|journald|gelf|fluentd|awslogs|splunk|etwlogs|gcplogs|none"
474 Logging driver for the container. Default is defined by daemon
475 --log-driver flag.
476 Warning: the docker logs command works only for the json-file and
477 journald logging drivers.
478 --log-opt=[]
481 Logging driver specific options.
482 -m, --memory=number[*S]
485 Memory limit; S is an optional suffix which can be one of b, k, m,
486 or g.
487 Allows you to constrain the memory available to a container. If the
490 host supports swap memory, then the -m memory setting can be larger
491 than physical RAM. If a limit of 0 is specified (not using -m), the
492 container's memory is not limited. The actual limit may be rounded up
493 to a multiple of the operating system's page size (the value would be
494 very large, that's millions of trillions).
495 --memory-reservation=number[*S]
498 Memory soft limit; S is an optional suffix which can be one of b, k,
499 m, or g.
500 After setting memory reservation, when the system detects memory
503 contention or low memory, containers are forced to restrict their
504 consumption to their reservation. So you should always set the value
505 below --memory, otherwise the hard limit will take precedence. By
506 default, memory reservation will be the same as memory limit.
507 --memory-swap=number[S]
510 Combined memory plus swap limit; S is an optional suffix which can
511 be one of b, k, m, or g.
512 This option can only be used together with --memory. The argument
515 should always be larger than that of --memory. Default is double the
516 value of --memory. Set to -1 to enable unlimited swap.
517 --mac-address=""
520 Container MAC address (e.g., 92:d0:c6:0a:29:33)
521 Remember that the MAC address in an Ethernet network must be unique.
524 The IPv6 link-local address will be based on the device's MAC address
525 according to RFC4862.
526 --mount type=TYPE,TYPE-SPECIFIC-OPTION[,...]
529 Attach a filesystem mount to the container
530 Current supported mount TYPES are bind, volume, and tmpfs.
533 e.g.
536 type=bind,source=/path/on/host,destination=/path/in/container
539 type=volume,source=my-volume,destination=/path/in/container,volume-label="color=red",volume-label="shape=round"
542 type=tmpfs,tmpfs-size=512M,destination=/path/in/container
545 Common Options:
548 · src, source: mount source spec for bind and volume. Mandatory
551 for bind.
552 · dst, destination, target: mount destination spec.
554 · ro, read-only: true or false (default).
556 Options specific to bind:
560 · bind-propagation: shared, slave, private, rshared, rslave, or
563 rprivate(default). See also mount(2).
564 · consistency: consistent(default), cached, or delegated.
566 Currently, only effective for Docker for Mac.
567 Options specific to volume:
571 · volume-driver: Name of the volume-driver plugin.
574 · volume-label: Custom metadata.
576 · volume-nocopy: true(default) or false. If set to false, the
578 Engine copies existing files and directories under the
579 mount-path into the volume, allowing the host to access them.
580 · volume-opt: specific to a given volume driver.
582 Options specific to tmpfs:
586 · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by
589 default in Linux.
590 · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or
592 0700.) Defaults to 1777 in Linux.
593 --name=""
597 Assign a name to the container
598 The operator can identify a container in three ways:
601 ┌──────────────────────┬────────────────────────────────────────────────────────────────────┐
604 │Identifier type │ Example value │
605 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
606 │UUID long identifier │ "f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778" │
607 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
608 │UUID short identifier │ "f78375b1c487" │
609 ├──────────────────────┼────────────────────────────────────────────────────────────────────┤
610 │Name │ "evil_ptolemy" │
611 └──────────────────────┴────────────────────────────────────────────────────────────────────┘
612 The UUID identifiers come from the Docker daemon, and if a name is not
614 assigned to the container with --name then the daemon will also
615 generate a random string name. The name is useful when defining links
616 (see --link) (or any other place you need to identify a container).
617 This works for both background and foreground Docker containers.
618 --network=type
621 Set the Network mode for the container. Supported values are:
622 ┌───────────────┬───────────────────────────┐
625 │Value │ Description │
626 ├───────────────┼───────────────────────────┤
627 │none │ No networking in the │
628 │ │ container. │
629 ├───────────────┼───────────────────────────┤
630 │bridge │ Connect the container to │
631 │ │ the default Docker bridge │
632 │ │ via veth interfaces. │
633 ├───────────────┼───────────────────────────┤
634 │host │ Use the host's network │
635 │ │ stack inside the │
636 │ │ container. │
637 ├───────────────┼───────────────────────────┤
638 │container:name │ id │
639 ├───────────────┼───────────────────────────┤
640 │network-name │ network-id │
641 └───────────────┴───────────────────────────┘
642 Default is bridge.
644 --network-alias=[]
647 Add network-scoped alias for the container
648 --oom-kill-disable=true|false
651 Whether to disable OOM Killer for the container or not.
652 --oom-score-adj=""
655 Tune the host's OOM preferences for containers (accepts -1000 to
656 1000)
657 -P, --publish-all=true|false
660 Publish all exposed ports to random ports on the host interfaces.
661 The default is false.
662 When set to true publish all exposed ports to the host interfaces. The
665 default is false. If the operator uses -P (or -p) then Docker will make
666 the exposed port accessible on the host and the ports will be available
667 to any client that can reach the host. When using -P, Docker will bind
668 any exposed port to a random port on the host within an ephemeral port
669 range defined by /proc/sys/net/ipv4/ip_local_port_range. To find the
670 mapping between the host ports and the exposed ports, use docker
671 port(1).
672 -p, --publish ip:[hostPort]:containerPort | [hostPort:]containerPort
675 Publish a container's port, or range of ports, to the host.
676 Both hostPort and containerPort can be specified as a range. When
679 specifying ranges for both, the number of ports in ranges should be
680 equal.
681 Examples: -p 1234-1236:1222-1224, -p
684 127.0.0.1:$HOSTPORT:$CONTAINERPORT.
685 Use docker port(1) to see the actual mapping, e.g. docker port
688 CONTAINER $CONTAINERPORT.
689 --pid=""
692 Set the PID mode for the container
693 Default is to create a private PID namespace for the container
694 'container:<name|id>': join another
695 container's PID namespace
696 'host': use the host's PID namespace for
697 the container. Note: the host mode gives the container full access to
698 local PID and is therefore considered insecure.
699 --userns=""
702 Set the usernamespace mode for the container when userns-remap
703 option is enabled.
704 host: use the host usernamespace and enable all privileged options
705 (e.g., pid=host or --privileged).
706 --pids-limit=""
709 Tune the container's pids (process IDs) limit. Set to -1 to have
710 unlimited pids for the container.
711 --uts=type
714 Set the UTS mode for the container. The only possible type is host,
715 meaning to use the host's UTS namespace inside the container.
716 Note: the host mode gives the container access to changing the
717 host's hostname and is therefore considered insecure.
718 --privileged [true|false]
721 Give extended privileges to this container. A "privileged" container
722 is given access to all devices.
723 When the operator executes docker run --privileged, Docker will enable
726 access to all devices on the host as well as set some configuration in
727 AppArmor to allow the container nearly all the same access to the host
728 as processes running outside of a container on the host.
729 --read-only=true|false
732 Mount the container's root filesystem as read only.
733 By default a container will have its root filesystem writable allowing
736 processes to write files anywhere. By specifying the --read-only flag
737 the container will have its root filesystem mounted as read only
738 prohibiting any writes.
739 --restart policy
742 Restart policy to apply when a container exits. Supported values
743 are:
744 ┌─────────────────────────┬────────────────────────────┐
747 │Policy │ Result │
748 ├─────────────────────────┼────────────────────────────┤
749 │no │ Do not automatically │
750 │ │ restart the container when │
751 │ │ it exits. │
752 ├─────────────────────────┼────────────────────────────┤
753 │on-failure[:max-retries] │ Restart only if the │
754 │ │ container exits with a │
755 │ │ non-zero exit status. │
756 │ │ Optionally, limit the │
757 │ │ number of restart retries │
758 │ │ the Docker daemon │
759 │ │ attempts. │
760 ├─────────────────────────┼────────────────────────────┤
761 │always │ Always restart the │
762 │ │ container regardless of │
763 │ │ the exit status. When you │
764 │ │ specify always, the Docker │
765 │ │ daemon will try to restart │
766 │ │ the container │
767 │ │ indefinitely. The │
768 │ │ container will also always │
769 │ │ start on daemon startup, │
770 │ │ regardless of the current │
771 │ │ state of the container. │
772 ├─────────────────────────┼────────────────────────────┤
773 │unless-stopped │ Always restart the │
774 │ │ container regardless of │
775 │ │ the exit status, but do │
776 │ │ not start it on daemon │
777 │ │ startup if the container │
778 │ │ has been put to a stopped │
779 │ │ state before. │
780 └─────────────────────────┴────────────────────────────┘
781 Default is no.
783 --rm true|false
786 Automatically remove the container when it exits. The default is
787 false.
788 --rm flag can work together with -d, and auto-removal will be done
789 on daemon side. Note that it's incompatible with any restart policy
790 other than none.
791 --security-opt value[,...]
794 Security Options for the container. The following options can be
795 given:
796 "label=user:USER" : Set the label user for the container
799 "label=role:ROLE" : Set the label role for the container
800 "label=type:TYPE" : Set the label type for the container
801 "label=level:LEVEL" : Set the label level for the container
802 "label=disable" : Turn off label confinement for the container
803 "no-new-privileges" : Disable container processes from gaining additional privileges
804 "seccomp=unconfined" : Turn off seccomp confinement for the container
806 "seccomp=profile.json : White listed syscalls seccomp Json file to be used as a seccomp filter
807 "apparmor=unconfined" : Turn off apparmor confinement for the container
809 "apparmor=your-profile" : Set the apparmor confinement profile for the container
810 --storage-opt
814 Storage driver options per container
815 $ docker run -it --storage-opt size=120G fedora /bin/bash
818 This (size) will allow to set the container rootfs size to 120G at
821 creation time.
822 This option is only available for the devicemapper, btrfs, overlay2
823 and zfs graph drivers.
824 For the devicemapper, btrfs and zfs storage drivers, user cannot
825 pass a size less than the Default BaseFS Size.
826 For the overlay2 storage driver, the size option is only available
827 if the backing fs is xfs and mounted with the pquota mount option.
828 Under these conditions, user can pass any size less than the backing
829 fs size.
830 --stop-signal=SIGTERM
833 Signal to stop a container. Default is SIGTERM.
834 --stop-timeout=10
837 Timeout (in seconds) to stop a container. Default is 10.
838 --shm-size=""
841 Size of /dev/shm. The format is <number><unit>.
842 number must be greater than 0. Unit is optional and can be b
843 (bytes), k (kilobytes), m(megabytes), or g (gigabytes).
844 If you omit the unit, the system uses bytes. If you omit the size
845 entirely, the system uses 64m.
846 --sysctl=SYSCTL
849 Configure namespaced kernel parameters at runtime
850 IPC Namespace - current sysctls allowed:
853 kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall,
856 kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced
857 Sysctls beginning with fs.mqueue.*
858 If you use the --ipc=host option these sysctls will not be allowed.
861 Network Namespace - current sysctls allowed:
864 Sysctls beginning with net.*
865 If you use the --network=host option these sysctls will not be allowed.
868 --sig-proxy=true|false
871 Proxy received signals to the process (non-TTY mode only). SIGCHLD,
872 SIGSTOP, and SIGKILL are not proxied. The default is true.
873 --memory-swappiness=""
876 Tune a container's memory swappiness behavior. Accepts an integer
877 between 0 and 100.
878 -t, --tty=true|false
881 Allocate a pseudo-TTY. The default is false.
882 When set to true Docker can allocate a pseudo-tty and attach to the
885 standard input of any container. This can be used, for example, to run
886 a throwaway interactive shell. The default is false.
887 The -t option is incompatible with a redirection of the docker client
890 standard input.
891 --tmpfs=[] Create a tmpfs mount
894 Mount a temporary filesystem (tmpfs) mount into a container, for
897 example:
898 $ docker run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
901 This command mounts a tmpfs at /tmp within the container. The
904 supported mount options are the same as the Linux default mount flags.
905 If you do not specify any options, the systems uses the following
906 options: rw,noexec,nosuid,nodev,size=65536k.
907 See also --mount, which is the successor of --tmpfs and --volume.
910 Even though there is no plan to deprecate --tmpfs, usage of --mount
911 is recommended.
912 -u, --user=""
915 Sets the username or UID used and optionally the groupname or GID
916 for the specified command.
917 The followings examples are all valid:
920 --user [user | user:group | uid | uid:gid | user:gid | uid:group ]
921 Without this argument the command will be run as root in the container.
924 --ulimit=[]
927 Ulimit options
928 -v|--volume[=[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]]
931 Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR,
932 Docker
933 bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Docker
934 container. If 'HOST-DIR' is omitted, Docker automatically creates
935 the new
936 volume on the host. The OPTIONS are a comma delimited list and can
937 be:
938 · [rw|ro]
941 · [z|Z]
943 · [[r]shared|[r]slave|[r]private]
945 · [delegated|cached|consistent]
947 · [nocopy]
949 The CONTAINER-DIR must be an absolute path such as /src/docs. The
953 HOST-DIR can be an absolute path or a name value. A name value must
954 start with an alphanumeric character, followed by a-z0-9, _
955 (underscore), . (period) or - (hyphen). An absolute path starts with a
956 / (forward slash).
957 If you supply a HOST-DIR that is an absolute path, Docker bind-mounts
960 to the path you specify. If you supply a name, Docker creates a named
961 volume by that name. For example, you can specify either /foo or foo
962 for a HOST-DIR value. If you supply the /foo value, Docker creates a
963 bind mount. If you supply the foo specification, Docker creates a named
964 volume.
965 You can specify multiple -v options to mount one or more mounts to a
968 container. To use these same mounts in other containers, specify the
969 --volumes-from option also.
970 You can supply additional options for each bind mount following an
973 additional colon. A :ro or :rw suffix mounts a volume in read-only or
974 read-write mode, respectively. By default, volumes are mounted in
975 read-write mode. You can also specify the consistency requirement for
976 the mount, either :consistent (the default), :cached, or :delegated.
977 Multiple options are separated by commas, e.g. :ro,cached.
978 Labeling systems like SELinux require that proper labels are placed on
981 volume content mounted into a container. Without a label, the security
982 system might prevent the processes running inside the container from
983 using the content. By default, Docker does not change the labels set by
984 the OS.
985 To change a label in the container context, you can add either of two
988 suffixes :z or :Z to the volume mount. These suffixes tell Docker to
989 relabel file objects on the shared volumes. The z option tells Docker
990 that two containers share the volume content. As a result, Docker
991 labels the content with a shared content label. Shared volume labels
992 allow all containers to read/write content. The Z option tells Docker
993 to label the content with a private unshared label. Only the current
994 container can use a private volume.
995 By default bind mounted volumes are private. That means any mounts done
998 inside container will not be visible on host and vice-a-versa. One can
999 change this behavior by specifying a volume mount propagation property.
1000 Making a volume shared mounts done under that volume inside container
1001 will be visible on host and vice-a-versa. Making a volume slave enables
1002 only one way mount propagation and that is mounts done on host under
1003 that volume will be visible inside container but not the other way
1004 around.
1005 To control mount propagation property of volume one can use :[r]shared,
1008 :[r]slave or :[r]private propagation flag. Propagation property can be
1009 specified only for bind mounted volumes and not for internal volumes or
1010 named volumes. For mount propagation to work source mount point (mount
1011 point where source dir is mounted on) has to have right propagation
1012 properties. For shared volumes, source mount point has to be shared.
1013 And for slave volumes, source mount has to be either shared or slave.
1014 Use df <source-dir> to figure out the source mount and then use findmnt
1017 -o TARGET,PROPAGATION <source-mount-dir> to figure out propagation
1018 properties of source mount. If findmnt utility is not available, then
1019 one can look at mount entry for source mount point in
1020 /proc/self/mountinfo. Look at optional fields and see if any
1021 propagation properties are specified. shared:X means mount is shared,
1022 master:X means mount is slave and if nothing is there that means mount
1023 is private.
1024 To change propagation properties of a mount point use mount command.
1027 For example, if one wants to bind mount source directory /foo one can
1028 do mount --bind /foo /foo and mount --make-private --make-shared /foo.
1029 This will convert /foo into a shared mount point. Alternatively one can
1030 directly change propagation properties of source mount. Say / is source
1031 mount for /foo, then use mount --make-shared / to convert / into a
1032 shared mount.
1033 Note: When using systemd to manage the Docker daemon's start and
1036 stop, in the systemd unit file there is an option to control
1037 mount propagation for the Docker daemon itself, called
1038 MountFlags. The value of this setting may cause Docker to not
1039 see mount propagation changes made on the mount point. For
1040 example, if this value is slave, you may not be able to use the
1041 shared or rshared propagation on a volume.
1042 To disable automatic copying of data from the container path to the
1045 volume, use the nocopy flag. The nocopy flag can be set on bind mounts
1046 and named volumes.
1047 See also --mount, which is the successor of --tmpfs and --volume. Even
1050 though there is no plan to deprecate --volume, usage of --mount is
1051 recommended.
1052 --volume-driver=""
1055 Container's volume driver. This driver creates volumes specified
1056 either from
1057 a Dockerfile's VOLUME instruction or from the docker run -v flag.
1058 See docker-volume-create(1) for full details.
1059 --volumes-from=[]
1062 Mount volumes from the specified container(s)
1063 Mounts already mounted volumes from a source container onto another
1066 container. You must supply the source's container-id. To share
1067 a volume, use the --volumes-from option when running
1068 the target container. You can share volumes even if the source
1069 container
1070 is not running.
1071 By default, Docker mounts the volumes in the same mode (read-write or
1074 read-only) as it is mounted in the source container. Optionally, you
1075 can change this by suffixing the container-id with either the :ro or
1076 :rw keyword.
1077 If the location of the volume from the source container overlaps with
1080 data residing on a target container, then the volume hides
1081 that data on the target.
1082 -w, --workdir=""
1085 Working directory inside the container
1086 The default working directory for running binaries within a container
1089 is the root directory (/). The developer can set a different default
1090 with the Dockerfile WORKDIR instruction. The operator can override the
1091 working directory by using the -w option.
1092
1096 The exit code from docker run gives information about why the container
1097 failed to run or why it exited. When docker run exits with a non-zero
1098 code, the exit codes follow the chroot standard, see below:
1099 125 if the error is with Docker daemon itself
1102 $ docker run --foo busybox; echo $?
1105 # flag provided but not defined: --foo
1106 See 'docker run --help'.
1107 125
1108 126 if the contained command cannot be invoked
1112 $ docker run busybox /etc; echo $?
1115 # exec: "/etc": permission denied
1116 docker: Error response from daemon: Contained command could not be invoked
1117 126
1118 127 if the contained command cannot be found
1122 $ docker run busybox foo; echo $?
1125 # exec: "foo": executable file not found in $PATH
1126 docker: Error response from daemon: Contained command not found or does not exist
1127 127
1128 Exit code of contained command otherwise
1132 $ docker run busybox /bin/sh -c 'exit 3'
1135 # 3
1136
1142 During container image development, containers often need to write to
1143 the image content. Installing packages into /usr, for example. In
1144 production, applications seldom need to write to the image. Container
1145 applications write to volumes if they need to write to file systems at
1146 all. Applications can be made more secure by running them in read-only
1147 mode using the --read-only switch. This protects the containers image
1148 from modification. Read only containers may still need to write
1149 temporary data. The best way to handle this is to mount tmpfs
1150 directories on /run and /tmp.
1151 # docker run --read-only --tmpfs /run --tmpfs /tmp -i -t fedora /bin/bash
1154
1158 If you want messages that are logged in your container to show up in
1159 the host's syslog/journal then you should bind mount the /dev/log
1160 directory as follows.
1161 # docker run -v /dev/log:/dev/log -i -t fedora /bin/bash
1164 From inside the container you can test this by sending a message to the
1168 log.
1169 (bash)# logger "Hello from my container"
1172 Then exit and check the journal.
1176 # exit
1179 # journalctl -b | grep Hello
1181 This should list the message sent to logger.
1185
1188 If you do not specify -a then Docker will attach everything
1189 (stdin,stdout,stderr) you'd like to connect instead, as in:
1190 # docker run -a stdin -a stdout -i -t fedora /bin/bash
1193
1197 Using shm_server.c available here:
1198 ⟨https://www.cs.cf.ac.uk/Dave/C/node27.html⟩
1199 Testing --ipc=host mode:
1202 Host shows a shared memory segment with 7 pids attached, happens to be
1205 from httpd:
1206 $ sudo ipcs -m
1209 ------ Shared Memory Segments --------
1211 key shmid owner perms bytes nattch status
1212 0x01128e25 0 root 600 1000 7
1213 Now run a regular container, and it correctly does NOT see the shared
1217 memory segment from the host:
1218 $ docker run -it shm ipcs -m
1221 ------ Shared Memory Segments --------
1223 key shmid owner perms bytes nattch status
1224 Run a container with the new --ipc=host option, and it now sees the
1228 shared memory segment from the host httpd:
1229 $ docker run -it --ipc=host shm ipcs -m
1232 ------ Shared Memory Segments --------
1234 key shmid owner perms bytes nattch status
1235 0x01128e25 0 root 600 1000 7
1236 Testing --ipc=container:CONTAINERID mode:
1240 Start a container with a program to create a shared memory segment:
1243 $ docker run -it shm bash
1246 $ sudo shm/shm_server
1247 $ sudo ipcs -m
1248 ------ Shared Memory Segments --------
1250 key shmid owner perms bytes nattch status
1251 0x0000162e 0 root 666 27 1
1252 Create a 2nd container correctly shows no shared memory segment from
1256 1st container:
1257 $ docker run shm ipcs -m
1260 ------ Shared Memory Segments --------
1262 key shmid owner perms bytes nattch status
1263 Create a 3rd container using the new --ipc=container:CONTAINERID
1267 option, now it shows the shared memory segment from the first:
1268 $ docker run -it --ipc=container:ed735b2264ac shm ipcs -m
1271 $ sudo ipcs -m
1272 ------ Shared Memory Segments --------
1274 key shmid owner perms bytes nattch status
1275 0x0000162e 0 root 666 27 1
1276
1280 Note: This section describes linking between containers on the
1281 default (bridge) network, also known as "legacy links". Using
1282 --link on user-defined networks uses the DNS-based discovery,
1283 which does not add entries to /etc/hosts, and does not set
1284 environment variables for discovery.
1285 The link feature allows multiple containers to communicate with each
1288 other. For example, a container whose Dockerfile has exposed port 80
1289 can be run and named as follows:
1290 # docker run --name=link-test -d -i -t fedora/httpd
1293 A second container, in this case called linker, can communicate with
1297 the httpd container, named link-test, by running with the
1298 --link=<name>:<alias>
1299 # docker run -t -i --link=link-test:lt --name=linker fedora /bin/bash
1302 Now the container linker is linked to container link-test with the
1306 alias lt. Running the env command in the linker container shows
1307 environment variables
1308 with the LT (alias) context (LT_)
1309 # env
1312 HOSTNAME=668231cb0978
1313 TERM=xterm
1314 LT_PORT_80_TCP=tcp://172.17.0.3:80
1315 LT_PORT_80_TCP_PORT=80
1316 LT_PORT_80_TCP_PROTO=tcp
1317 LT_PORT=tcp://172.17.0.3:80
1318 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
1319 PWD=/
1320 LT_NAME=/linker/lt
1321 SHLVL=1
1322 HOME=/
1323 LT_PORT_80_TCP_ADDR=172.17.0.3
1324 _=/usr/bin/env
1325 When linking two containers Docker will use the exposed ports of the
1329 container to create a secure tunnel for the parent to access.
1330 If a container is connected to the default bridge network and linked
1333 with other containers, then the container's /etc/hosts file is updated
1334 with the linked container's name.
1335 Note Since Docker may live update the container's /etc/hosts
1338 file, there may be situations when processes inside the
1339 container can end up reading an empty or incomplete /etc/hosts
1340 file. In most cases, retrying the read again should fix the
1341 problem.
1342
1345 The exposed port of an application can be mapped to a host port using
1346 the -p flag. For example, an httpd port 80 can be mapped to the host
1347 port 8080 using the following:
1348 # docker run -p 8080:80 -d -i -t fedora/httpd
1351
1355 Many applications require the sharing of persistent data across several
1356 containers. Docker allows you to create a Data Volume Container that
1357 other containers can mount from. For example, create a named container
1358 that contains directories /var/volume1 and /tmp/volume2. The image will
1359 need to contain these directories so a couple of RUN mkdir instructions
1360 might be required for you fedora-data image:
1361 # docker run --name=data -v /var/volume1 -v /tmp/volume2 -i -t fedora-data true
1364 # docker run --volumes-from=data --name=fedora-container1 -i -t fedora bash
1365 Multiple --volumes-from parameters will bring together multiple data
1369 volumes from multiple containers. And it's possible to mount the
1370 volumes that came from the DATA container in yet another container via
1371 the fedora-container1 intermediary container, allowing to abstract the
1372 actual data source from users of that data:
1373 # docker run --volumes-from=fedora-container1 --name=fedora-container2 -i -t fedora bash
1376
1380 To mount a host directory as a container volume, specify the absolute
1381 path to the directory and the absolute path for the container directory
1382 separated by a colon:
1383 # docker run -v /var/db:/data1 -i -t fedora bash
1386 When using SELinux, be aware that the host has no knowledge of
1390 container SELinux policy. Therefore, in the above example, if SELinux
1391 policy is enforced, the /var/db directory is not writable to the
1392 container. A "Permission Denied" message will occur and an avc: message
1393 in the host's syslog.
1394 To work around this, at time of writing this man page, the following
1397 command needs to be run in order for the proper SELinux policy type
1398 label to be attached to the host directory:
1399 # chcon -Rt svirt_sandbox_file_t /var/db
1402 Now, writing to the /data1 volume in the container will be allowed and
1406 the changes will also be reflected on the host in /var/db.
1407
1410 You can override the default labeling scheme for each container by
1411 specifying the --security-opt flag. For example, you can specify the
1412 MCS/MLS level, a requirement for MLS systems. Specifying the level in
1413 the following command allows you to share the same content between
1414 containers.
1415 # docker run --security-opt label=level:s0:c100,c200 -i -t fedora bash
1418 An MLS example might be:
1422 # docker run --security-opt label=level:TopSecret -i -t rhel7 bash
1425 To disable the security labeling for this container versus running with
1429 the --permissive flag, use the following command:
1430 # docker run --security-opt label=disable -i -t fedora bash
1433 If you want a tighter security policy on the processes within a
1437 container, you can specify an alternate type for the container. You
1438 could run a container that is only allowed to listen on Apache ports by
1439 executing the following command:
1440 # docker run --security-opt label=type:svirt_apache_t -i -t centos bash
1443 Note:
1447 You would have to write policy defining a svirt_apache_t type.
1450
1453 If you want to set /dev/sda device weight to 200, you can specify the
1454 device weight by --blkio-weight-device flag. Use the following command:
1455 # docker run -it --blkio-weight-device "/dev/sda:200" ubuntu
1458
1462 This option is useful in situations where you are running Docker
1463 containers on Microsoft Windows. The --isolation <value> option sets a
1464 container's isolation technology. On Linux, the only supported is the
1465 default option which uses Linux namespaces. These two commands are
1466 equivalent on Linux:
1467 $ docker run -d busybox top
1470 $ docker run -d --isolation default busybox top
1471 On Microsoft Windows, can take any of these values:
1475 · default: Use the value specified by the Docker daemon's
1478 --exec-opt . If the daemon does not specify an isolation
1479 technology, Microsoft Windows uses process as its default
1480 value.
1481 · process: Namespace isolation only.
1483 · hyperv: Hyper-V hypervisor partition-based isolation.
1485 In practice, when running on Microsoft Windows without a daemon option
1489 set, these two commands are equivalent:
1490 $ docker run -d --isolation default busybox top
1493 $ docker run -d --isolation process busybox top
1494 If you have set the --exec-opt isolation=hyperv option on the Docker
1498 daemon, any of these commands also result in hyperv isolation:
1499 $ docker run -d --isolation default busybox top
1502 $ docker run -d --isolation hyperv busybox top
1503
1507 The --sysctl sets namespaced kernel parameters (sysctls) in the
1508 container. For example, to turn on IP forwarding in the containers
1509 network namespace, run this command:
1510 $ docker run --sysctl net.ipv4.ip_forward=1 someimage
1513 Note:
1517 Not all sysctls are namespaced. Docker does not support changing
1520 sysctls inside of a container that also modify the host system. As the
1521 kernel evolves we expect to see more sysctls become namespaced.
1522 See the definition of the --sysctl option above for the current list of
1525 supported sysctls.
1526
1530 April 2014, Originally compiled by William Henry (whenry at redhat dot
1531 com) based on docker.com source material and internal work. June 2014,
1532 updated by Sven Dowideit ⟨SvenDowideit@home.org.au⟩ July 2014, updated
1533 by Sven Dowideit ⟨SvenDowideit@home.org.au⟩ November 2015, updated by
1534 Sally O'Malley ⟨somalley@redhat.com⟩
1535Docker Community Docker User Manuals DOCKER(1)