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-read-bps[=[]]] [--device-read-iops[=[]]]
20 [--device-write-bps[=[]]] [--device-write-iops[=[]]] [--dns[=[]]]
21 [--dns-option[=[]]] [--dns-search[=[]]] [-e|--env[=[]]]
22 [--entrypoint[=ENTRYPOINT]] [--env-file[=[]]] [--expose[=[]]]
23 [--group-add[=[]]] [-h|--hostname[=HOSTNAME]] [--help] [--init]
24 [--init-path[=[]]] [-i|--interactive] [--ip[=IPv4-ADDRESS]]
25 [--ip6[=IPv6-ADDRESS]] [--ipc[=IPC]] [--isolation[=default]]
26 [--kernel-memory[=KERNEL-MEMORY]] [-l|--label[=[]]] [--label-file[=[]]]
27 [--link[=[]]] [--link-local-ip[=[]]] [--log-driver[=[]]]
28 [--log-opt[=[]]] [-m|--memory[=MEMORY]] [--mac-address[=MAC-ADDRESS]]
29 [--memory-reservation[=MEMORY-RESERVATION]] [--memory-swap[=LIMIT]]
30 [--memory-swappiness[=MEMORY-SWAPPINESS]] [--name[=NAME]]
31 [--network-alias[=[]]] [--network[="bridge"]] [--oom-kill-disable]
32 [--oom-score-adj[=0]] [-P|--publish-all] [-p|--publish[=[]]]
33 [--pid[=[PID]]] [--userns[=[]]] [--pids-limit[=PIDS_LIMIT]]
34 [--privileged] [--read-only] [--restart[=RESTART]] [--rm]
35 [--security-opt[=[]]] [--storage-opt[=[]]] [--stop-signal[=SIGNAL]]
36 [--stop-timeout[=TIMEOUT]] [--shm-size[=[]]] [--sig-proxy[=true]]
37 [--sysctl[=[]]] [-t|--tty] [--tmpfs[=[CONTAINER-DIR[:<OPTIONS>]]]
38 [-u|--user[=USER]] [--ulimit[=[]]] [--uts[=[]]]
39 [-v|--volume[=[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]]]
40 [--volume-driver[=DRIVER]] [--volumes-from[=[]]]
41 [-w|--workdir[=WORKDIR]] IMAGE [COMMAND] [ARG...]
42
46 Run a process in a new container. docker run starts a process with its
47 own file system, its own networking, and its own isolated process tree.
48 The IMAGE which starts the process may define defaults related to the
49 process that will be run in the container, the networking to expose,
50 and more, but docker run gives final control to the operator or
51 administrator who starts the container from the image. For that reason
52 docker run has more options than any other Docker command.
53 If the IMAGE is not already loaded then docker run will pull the IMAGE,
56 and all image dependencies, from the repository in the same way running
57 docker pull IMAGE, before it starts the container from that image.
58
62 -a, --attach=[]
63 Attach to STDIN, STDOUT or STDERR.
64 In foreground mode (the default when -d is not specified), docker run
67 can start the process in the container and attach the console to the
68 process's standard input, output, and standard error. It can even
69 pretend to be a TTY (this is what most commandline executables expect)
70 and pass along signals. The -a option can be set for each of stdin,
71 stdout, and stderr.
72 --add-host=[]
75 Add a custom host-to-IP mapping (host:ip)
76 Add a line to /etc/hosts. The format is hostname:ip. The --add-host
79 option can be set multiple times.
80 --blkio-weight=0
83 Block IO weight (relative weight) accepts a weight value between 10
84 and 1000.
85 --blkio-weight-device=[]
88 Block IO weight (relative device weight, format:
89 DEVICE_NAME:WEIGHT).
90 --cpu-shares=0
93 CPU shares (relative weight)
94 By default, all containers get the same proportion of CPU cycles. This
97 proportion can be modified by changing the container's CPU share
98 weighting relative to the weighting of all other running containers.
99 To modify the proportion from the default of 1024, use the --cpu-shares
102 flag to set the weighting to 2 or higher.
103 The proportion will only apply when CPU-intensive processes are
106 running. When tasks in one container are idle, other containers can
107 use the left-over CPU time. The actual amount of CPU time will vary
108 depending on the number of containers running on the system.
109 For example, consider three containers, one has a cpu-share of 1024 and
112 two others have a cpu-share setting of 512. When processes in all three
113 containers attempt to use 100% of CPU, the first container would
114 receive 50% of the total CPU time. If you add a fourth container with a
115 cpu-share of 1024, the first container only gets 33% of the CPU. The
116 remaining containers receive 16.5%, 16.5% and 33% of the CPU.
117 On a multi-core system, the shares of CPU time are distributed over all
120 CPU cores. Even if a container is limited to less than 100% of CPU
121 time, it can use 100% of each individual CPU core.
122 For example, consider a system with more than three cores. If you start
125 one container {C0} with -c=512 running one process, and another
126 container {C1} with -c=1024 running two processes, this can result in
127 the following division of CPU shares:
128 PID container CPU CPU share
131 100 {C0} 0 100% of CPU0
132 101 {C1} 1 100% of CPU1
133 102 {C1} 2 100% of CPU2
134 --cap-add=[]
138 Add Linux capabilities
139 --cap-drop=[]
142 Drop Linux capabilities
143 --cgroup-parent=""
146 Path to cgroups under which the cgroup for the container will be
147 created. If the path is not absolute, the path is considered to be
148 relative to the cgroups path of the init process. Cgroups will be
149 created if they do not already exist.
150 --cidfile=""
153 Write the container ID to the file
154 --cpu-count=0
157 Limit the number of CPUs available for execution by the container.
158 On Windows Server containers, this is approximated as a percentage of total CPU usage.
161 On Windows Server containers, the processor resource controls are mutually exclusive, the order of precedence is CPUCount first, then CPUShares, and CPUPercent last.
163 --cpu-percent=0
167 Limit the percentage of CPU available for execution by a container
168 running on a Windows daemon.
169 On Windows Server containers, the processor resource controls are mutually exclusive, the order of precedence is CPUCount first, then CPUShares, and CPUPercent last.
172 --cpu-period=0
176 Limit the CPU CFS (Completely Fair Scheduler) period
177 Limit the container's CPU usage. This flag tell the kernel to restrict
180 the container's CPU usage to the period you specify.
181 --cpuset-cpus=""
184 CPUs in which to allow execution (0-3, 0,1)
185 --cpuset-mems=""
188 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only
189 effective on NUMA systems.
190 If you have four memory nodes on your system (0-3), use
193 --cpuset-mems=0,1 then processes in your Docker container will only use
194 memory from the first two memory nodes.
195 --cpu-quota=0
198 Limit the CPU CFS (Completely Fair Scheduler) quota
199 Limit the container's CPU usage. By default, containers run with the
202 full CPU resource. This flag tell the kernel to restrict the
203 container's CPU usage to the quota you specify.
204 --cpu-rt-period=0
207 Limit the CPU real-time period in microseconds
208 Limit the container's Real Time CPU usage. This flag tell the kernel to
211 restrict the container's Real Time CPU usage to the period you specify.
212 --cpu-rt-runtime=0
215 Limit the CPU real-time runtime in microseconds
216 Limit the containers Real Time CPU usage. This flag tells the kernel to
219 limit the amount of time in a given CPU period Real Time tasks may
220 consume. Ex:
221 Period of 1,000,000us and Runtime of 950,000us means that this
222 container could consume 95% of available CPU and leave the remaining 5%
223 to normal priority tasks.
224 The sum of all runtimes across containers cannot exceed the amount
227 allotted to the parent cgroup.
228 --cpus=0.0
231 Number of CPUs. The default is 0.0 which means no limit.
232 -d, --detach=true|false
235 Detached mode: run the container in the background and print the new
236 container ID. The default is false.
237 At any time you can run docker ps in the other shell to view a list of
240 the running containers. You can reattach to a detached container with
241 docker attach. If you choose to run a container in the detached mode,
242 then you cannot use the -rm option.
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=""
253 Override the key sequence for detaching a container. Format is a
254 single character [a-Z] or ctrl-<value> where <value> is one of: a-z, @,
255 ^, [, , or _.
256 --device=[]
259 Add a host device to the container (e.g.
260 --device=/dev/sdc:/dev/xvdc:rwm)
261 --device-read-bps=[]
264 Limit read rate from a device (e.g. --device-read-bps=/dev/sda:1mb)
265 --device-read-iops=[]
268 Limit read rate from a device (e.g.
269 --device-read-iops=/dev/sda:1000)
270 --device-write-bps=[]
273 Limit write rate to a device (e.g. --device-write-bps=/dev/sda:1mb)
274 --device-write-iops=[]
277 Limit write rate to a device (e.g.
278 --device-write-iops=/dev/sda:1000)
279 --dns-search=[]
282 Set custom DNS search domains (Use --dns-search=. if you don't wish
283 to set the search domain)
284 --dns-option=[]
287 Set custom DNS options
288 --dns=[]
291 Set custom DNS servers
292 This option can be used to override the DNS configuration passed to the
295 container. Typically this is necessary when the host DNS configuration
296 is invalid for the container (e.g., 127.0.0.1). When this is the case
297 the --dns flags is necessary for every run.
298 -e, --env=[]
301 Set environment variables
302 This option allows you to specify arbitrary environment variables that
305 are available for the process that will be launched inside of the
306 container.
307 --entrypoint=""
310 Overwrite the default ENTRYPOINT of the image
311 This option allows you to overwrite the default entrypoint of the image
314 that is set in the Dockerfile. The ENTRYPOINT of an image is similar to
315 a COMMAND because it specifies what executable to run when the
316 container starts, but it is (purposely) more difficult to override. The
317 ENTRYPOINT gives a container its default nature or behavior, so that
318 when you set an ENTRYPOINT you can run the container as if it were that
319 binary, complete with default options, and you can pass in more options
320 via the COMMAND. But, sometimes an operator may want to run something
321 else inside the container, so you can override the default ENTRYPOINT
322 at runtime by using a --entrypoint and a string to specify the new
323 ENTRYPOINT.
324 --env-file=[]
327 Read in a line delimited file of environment variables
328 --expose=[]
331 Expose a port, or a range of ports (e.g. --expose=3300-3310) informs
332 Docker that the container listens on the specified network ports at
333 runtime. Docker uses this information to interconnect containers using
334 links and to set up port redirection on the host system.
335 --group-add=[]
338 Add additional groups to run as
339 -h, --hostname=""
342 Container host name
343 Sets the container host name that is available inside the container.
346 --help
349 Print usage statement
350 --init
353 Run an init inside the container that forwards signals and reaps
354 processes
355 --init-path=""
358 Path to the docker-init binary
359 -i, --interactive=true|false
362 Keep STDIN open even if not attached. The default is false.
363 When set to true, keep stdin open even if not attached. The default is
366 false.
367 --ip=""
370 Sets the container's interface IPv4 address (e.g. 172.23.0.9)
371 It can only be used in conjunction with --network for user-defined
374 networks
375 --ip6=""
378 Sets the container's interface IPv6 address (e.g. 2001:db8::1b99)
379 It can only be used in conjunction with --network for user-defined
382 networks
383 --ipc=""
386 Default is to create a private IPC namespace (POSIX SysV IPC) for
387 the container
388 'container:<name|id>': reuses another
389 container shared memory, semaphores and message queues
390 'host': use the host shared
391 memory,semaphores and message queues inside the container. Note: the
392 host mode gives the container full access to local shared memory and is
393 therefore considered insecure.
394 --isolation="default"
397 Isolation specifies the type of isolation technology used by
398 containers. Note that the default on Windows server is process, and the
399 default on Windows client is hyperv. Linux only supports default.
400 -l, --label=[]
403 Set metadata on the container (e.g., --label com.example.key=value)
404 --kernel-memory=""
407 Kernel memory limit (format: <number>[<unit>], where unit = b, k, m
408 or g)
409 Constrains the kernel memory available to a container. If a limit of 0
412 is specified (not using --kernel-memory), the container's kernel memory
413 is not limited. If you specify a limit, it may be rounded up to a
414 multiple of the operating system's page size and the value can be very
415 large, millions of trillions.
416 --label-file=[]
419 Read in a line delimited file of labels
420 --link=[]
423 Add link to another container in the form of <name or id>:alias or
424 just <name or id> in which case the alias will match the name
425 If the operator uses --link when starting the new client container,
428 then the client container can access the exposed port via a private
429 networking interface. Docker will set some environment variables in the
430 client container to help indicate which interface and port to use.
431 --link-local-ip=[]
434 Add one or more link-local IPv4/IPv6 addresses to the container's
435 interface
436 --log-driver="json-file|syslog|journald|gelf|fluentd|awslogs|splunk|etwlogs|gcplogs|none"
439 Logging driver for the container. Default is defined by daemon
440 --log-driver flag.
441 Warning: the docker logs command works only for the json-file and
442 journald logging drivers.
443 --log-opt=[]
446 Logging driver specific options.
447 -m, --memory=""
450 Memory limit (format: <number>[<unit>], where unit = b, k, m or g)
451 Allows you to constrain the memory available to a container. If the
454 host supports swap memory, then the -m memory setting can be larger
455 than physical RAM. If a limit of 0 is specified (not using -m), the
456 container's memory is not limited. The actual limit may be rounded up
457 to a multiple of the operating system's page size (the value would be
458 very large, that's millions of trillions).
459 --memory-reservation=""
462 Memory soft limit (format: <number>[<unit>], where unit = b, k, m or
463 g)
464 After setting memory reservation, when the system detects memory
467 contention or low memory, containers are forced to restrict their
468 consumption to their reservation. So you should always set the value
469 below --memory, otherwise the hard limit will take precedence. By
470 default, memory reservation will be the same as memory limit.
471 --memory-swap="LIMIT"
474 A limit value equal to memory plus swap. Must be used with the -m
475 (--memory) flag. The swap LIMIT should always be larger than -m
476 (--memory) value. By default, the swap LIMIT will be set to double the
477 value of --memory.
478 The format of LIMIT is <number>[<unit>]. Unit can be b (bytes), k
481 (kilobytes), m (megabytes), or g (gigabytes). If you don't specify a
482 unit, b is used. Set LIMIT to -1 to enable unlimited swap.
483 --mac-address=""
486 Container MAC address (e.g. 92:d0:c6:0a:29:33)
487 Remember that the MAC address in an Ethernet network must be unique.
490 The IPv6 link-local address will be based on the device's MAC address
491 according to RFC4862.
492 --name=""
495 Assign a name to the container
496 The operator can identify a container in three ways:
499 UUID long identifier
500 (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”)
501 UUID short identifier (“f78375b1c487”)
502 Name (“jonah”)
503 The UUID identifiers come from the Docker daemon, and if a name is not
506 assigned to the container with --name then the daemon will also
507 generate a random string name. The name is useful when defining links
508 (see --link) (or any other place you need to identify a container).
509 This works for both background and foreground Docker containers.
510 --network="bridge"
513 Set the Network mode for the container
514 'bridge': create a network stack on the
515 default Docker bridge
516 'none': no networking
517 'container:<name|id>': reuse another
518 container's network stack
519 'host': use the Docker host network
520 stack. Note: the host mode gives the container full access to local
521 system services such as D-bus and is therefore considered insecure.
522 '<network-name>|<network-id>': connect
523 to a user-defined network
524 --network-alias=[]
527 Add network-scoped alias for the container
528 --oom-kill-disable=true|false
531 Whether to disable OOM Killer for the container or not.
532 --oom-score-adj=""
535 Tune the host's OOM preferences for containers (accepts -1000 to
536 1000)
537 -P, --publish-all=true|false
540 Publish all exposed ports to random ports on the host interfaces.
541 The default is false.
542 When set to true publish all exposed ports to the host interfaces. The
545 default is false. If the operator uses -P (or -p) then Docker will make
546 the exposed port accessible on the host and the ports will be available
547 to any client that can reach the host. When using -P, Docker will bind
548 any exposed port to a random port on the host within an ephemeral port
549 range defined by /proc/sys/net/ipv4/ip_local_port_range. To find the
550 mapping between the host ports and the exposed ports, use docker port.
551 -p, --publish=[]
554 Publish a container's port, or range of ports, to the host.
555 Format: ip:hostPort:containerPort | ip::containerPort |
558 hostPort:containerPort | containerPort Both hostPort and containerPort
559 can be specified as a range of ports. When specifying ranges for both,
560 the number of container ports in the range must match the number of
561 host ports in the range. (e.g., docker run -p 1234-1236:1222-1224
562 --name thisWorks -t busybox but not docker run -p 1230-1236:1230-1240
563 --name RangeContainerPortsBiggerThanRangeHostPorts -t busybox) With ip:
564 docker run -p 127.0.0.1:$HOSTPORT:$CONTAINERPORT --name CONTAINER -t
565 someimage Use docker port to see the actual mapping: docker port
566 CONTAINER $CONTAINERPORT
567 --pid=""
570 Set the PID mode for the container
571 Default is to create a private PID namespace for the container
572 'container:<name|id>': join another
573 container's PID namespace
574 'host': use the host's PID namespace for
575 the container. Note: the host mode gives the container full access to
576 local PID and is therefore considered insecure.
577 --userns=""
580 Set the usernamespace mode for the container when userns-remap
581 option is enabled.
582 host: use the host usernamespace and enable all privileged options
583 (e.g., pid=host or --privileged).
584 --pids-limit=""
587 Tune the container's pids limit. Set -1 to have unlimited pids for
588 the container.
589 --uts=host
592 Set the UTS mode for the container
593 host: use the host's UTS namespace inside the container.
594 Note: the host mode gives the container access to changing the
595 host's hostname and is therefore considered insecure.
596 --privileged=true|false
599 Give extended privileges to this container. The default is false.
600 By default, Docker containers are “unprivileged” (=false) and cannot,
603 for example, run a Docker daemon inside the Docker container. This is
604 because by default a container is not allowed to access any devices. A
605 “privileged” container is given access to all devices.
606 When the operator executes docker run --privileged, Docker will enable
609 access to all devices on the host as well as set some configuration in
610 AppArmor to allow the container nearly all the same access to the host
611 as processes running outside of a container on the host.
612 --read-only=true|false
615 Mount the container's root filesystem as read only.
616 By default a container will have its root filesystem writable allowing
619 processes to write files anywhere. By specifying the --read-only flag
620 the container will have its root filesystem mounted as read only
621 prohibiting any writes.
622 --restart="no"
625 Restart policy to apply when a container exits (no,
626 on-failure[:max-retry], always, unless-stopped).
627 --rm=true|false
630 Automatically remove the container when it exits. The default is
631 false.
632 --rm flag can work together with -d, and auto-removal will be done
633 on daemon side. Note that it's incompatible with any restart policy
634 other than none.
635 --security-opt=[]
638 Security Options
639 "label=user:USER" : Set the label user for the container
642 "label=role:ROLE" : Set the label role for the container
643 "label=type:TYPE" : Set the label type for the container
644 "label=level:LEVEL" : Set the label level for the container
645 "label=disable" : Turn off label confinement for the container
646 "no-new-privileges" : Disable container processes from gaining additional privileges
647 "seccomp=unconfined" : Turn off seccomp confinement for the container
649 "seccomp=profile.json : White listed syscalls seccomp Json file to be used as a seccomp filter
650 "apparmor=unconfined" : Turn off apparmor confinement for the container
652 "apparmor=your-profile" : Set the apparmor confinement profile for the container
653 --storage-opt=[]
657 Storage driver options per container
658 $ docker run -it --storage-opt size=120G fedora /bin/bash
661 This (size) will allow to set the container rootfs size to 120G at
664 creation time.
665 This option is only available for the devicemapper, btrfs, overlay2
666 and zfs graph drivers.
667 For the devicemapper, btrfs and zfs storage drivers, user cannot
668 pass a size less than the Default BaseFS Size.
669 For the overlay2 storage driver, the size option is only available
670 if the backing fs is xfs and mounted with the pquota mount option.
671 Under these conditions, user can pass any size less then the backing
672 fs size.
673 --stop-signal=SIGTERM
676 Signal to stop a container. Default is SIGTERM.
677 --stop-timeout=10
680 Timeout (in seconds) to stop a container. Default is 10.
681 --shm-size=""
684 Size of /dev/shm. The format is <number><unit>.
685 number must be greater than 0. Unit is optional and can be b
686 (bytes), k (kilobytes), m(megabytes), or g (gigabytes).
687 If you omit the unit, the system uses bytes. If you omit the size
688 entirely, the system uses 64m.
689 --sysctl=SYSCTL
692 Configure namespaced kernel parameters at runtime
693 IPC Namespace - current sysctls allowed:
696 kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall,
699 kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced
700 Sysctls beginning with fs.mqueue.*
701 If you use the --ipc=host option these sysctls will not be allowed.
704 Network Namespace - current sysctls allowed:
707 Sysctls beginning with net.*
708 If you use the --network=host option these sysctls will not be allowed.
711 --sig-proxy=true|false
714 Proxy received signals to the process (non-TTY mode only). SIGCHLD,
715 SIGSTOP, and SIGKILL are not proxied. The default is true.
716 --memory-swappiness=""
719 Tune a container's memory swappiness behavior. Accepts an integer
720 between 0 and 100.
721 -t, --tty=true|false
724 Allocate a pseudo-TTY. The default is false.
725 When set to true Docker can allocate a pseudo-tty and attach to the
728 standard input of any container. This can be used, for example, to run
729 a throwaway interactive shell. The default is false.
730 The -t option is incompatible with a redirection of the docker client
733 standard input.
734 --tmpfs=[] Create a tmpfs mount
737 Mount a temporary filesystem (tmpfs) mount into a container, for
740 example:
741 $ docker run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
744 This command mounts a tmpfs at /tmp within the container. The
747 supported mount options are the same as the Linux default mount flags.
748 If you do not specify any options, the systems uses the following
749 options: rw,noexec,nosuid,nodev,size=65536k.
750 -u, --user=""
753 Sets the username or UID used and optionally the groupname or GID
754 for the specified command.
755 The followings examples are all valid:
758 --user [user | user:group | uid | uid:gid | user:gid | uid:group ]
759 Without this argument the command will be run as root in the container.
762 --ulimit=[]
765 Ulimit options
766 -v|--volume[=[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]]
769 Create a bind mount. If you specify, -v /HOST-DIR:/CONTAINER-DIR,
770 Docker
771 bind mounts /HOST-DIR in the host to /CONTAINER-DIR in the Docker
772 container. If 'HOST-DIR' is omitted, Docker automatically creates
773 the new
774 volume on the host. The OPTIONS are a comma delimited list and can
775 be:
776 · [rw|ro]
779 · [z|Z]
781 · [[r]shared|[r]slave|[r]private]
783 · [nocopy]
785 The CONTAINER-DIR must be an absolute path such as /src/docs. The
789 HOST-DIR can be an absolute path or a name value. A name value must
790 start with an alphanumeric character, followed by a-z0-9, _
791 (underscore), . (period) or - (hyphen). An absolute path starts with a
792 / (forward slash).
793 If you supply a HOST-DIR that is an absolute path, Docker bind-mounts
796 to the path you specify. If you supply a name, Docker creates a named
797 volume by that name. For example, you can specify either /foo or foo
798 for a HOST-DIR value. If you supply the /foo value, Docker creates a
799 bind-mount. If you supply the foo specification, Docker creates a named
800 volume.
801 You can specify multiple -v options to mount one or more mounts to a
804 container. To use these same mounts in other containers, specify the
805 --volumes-from option also.
806 You can add :ro or :rw suffix to a volume to mount it read-only or
809 read-write mode, respectively. By default, the volumes are mounted
810 read-write. See examples.
811 Labeling systems like SELinux require that proper labels are placed on
814 volume content mounted into a container. Without a label, the security
815 system might prevent the processes running inside the container from
816 using the content. By default, Docker does not change the labels set by
817 the OS.
818 To change a label in the container context, you can add either of two
821 suffixes :z or :Z to the volume mount. These suffixes tell Docker to
822 relabel file objects on the shared volumes. The z option tells Docker
823 that two containers share the volume content. As a result, Docker
824 labels the content with a shared content label. Shared volume labels
825 allow all containers to read/write content. The Z option tells Docker
826 to label the content with a private unshared label. Only the current
827 container can use a private volume.
828 By default bind mounted volumes are private. That means any mounts done
831 inside container will not be visible on host and vice-a-versa. One can
832 change this behavior by specifying a volume mount propagation property.
833 Making a volume shared mounts done under that volume inside container
834 will be visible on host and vice-a-versa. Making a volume slave enables
835 only one way mount propagation and that is mounts done on host under
836 that volume will be visible inside container but not the other way
837 around.
838 To control mount propagation property of volume one can use :[r]shared,
841 :[r]slave or :[r]private propagation flag. Propagation property can be
842 specified only for bind mounted volumes and not for internal volumes or
843 named volumes. For mount propagation to work source mount point (mount
844 point where source dir is mounted on) has to have right propagation
845 properties. For shared volumes, source mount point has to be shared.
846 And for slave volumes, source mount has to be either shared or slave.
847 Use df <source-dir> to figure out the source mount and then use findmnt
850 -o TARGET,PROPAGATION <source-mount-dir> to figure out propagation
851 properties of source mount. If findmnt utility is not available, then
852 one can look at mount entry for source mount point in
853 /proc/self/mountinfo. Look at optional fields and see if any propagaion
854 properties are specified. shared:X means mount is shared, master:X
855 means mount is slave and if nothing is there that means mount is
856 private.
857 To change propagation properties of a mount point use mount command.
860 For example, if one wants to bind mount source directory /foo one can
861 do mount --bind /foo /foo and mount --make-private --make-shared /foo.
862 This will convert /foo into a shared mount point. Alternatively one can
863 directly change propagation properties of source mount. Say / is source
864 mount for /foo, then use mount --make-shared / to convert / into a
865 shared mount.
866 Note: When using systemd to manage the Docker daemon's start and
869 stop, in the systemd unit file there is an option to control
870 mount propagation for the Docker daemon itself, called
871 MountFlags. The value of this setting may cause Docker to not
872 see mount propagation changes made on the mount point. For
873 example, if this value is slave, you may not be able to use the
874 shared or rshared propagation on a volume.
875 To disable automatic copying of data from the container path to the
878 volume, use the nocopy flag. The nocopy flag can be set on bind mounts
879 and named volumes.
880 --volume-driver=""
883 Container's volume driver. This driver creates volumes specified
884 either from
885 a Dockerfile's VOLUME instruction or from the docker run -v flag.
886 See docker-volume-create(1) for full details.
887 --volumes-from=[]
890 Mount volumes from the specified container(s)
891 Mounts already mounted volumes from a source container onto another
894 container. You must supply the source's container-id. To share
895 a volume, use the --volumes-from option when running
896 the target container. You can share volumes even if the source
897 container
898 is not running.
899 By default, Docker mounts the volumes in the same mode (read-write or
902 read-only) as it is mounted in the source container. Optionally, you
903 can change this by suffixing the container-id with either the :ro or
904 :rw keyword.
905 If the location of the volume from the source container overlaps with
908 data residing on a target container, then the volume hides
909 that data on the target.
910 -w, --workdir=""
913 Working directory inside the container
914 The default working directory for running binaries within a container
917 is the root directory (/). The developer can set a different default
918 with the Dockerfile WORKDIR instruction. The operator can override the
919 working directory by using the -w option.
920
924 The exit code from docker run gives information about why the container
925 failed to run or why it exited. When docker run exits with a non-zero
926 code, the exit codes follow the chroot standard, see below:
927 125 if the error is with Docker daemon itself
930 $ docker run --foo busybox; echo $?
933 # flag provided but not defined: --foo
934 See 'docker run --help'.
935 125
936 126 if the contained command cannot be invoked
940 $ docker run busybox /etc; echo $?
943 # exec: "/etc": permission denied
944 docker: Error response from daemon: Contained command could not be invoked
945 126
946 127 if the contained command cannot be found
950 $ docker run busybox foo; echo $?
953 # exec: "foo": executable file not found in $PATH
954 docker: Error response from daemon: Contained command not found or does not exist
955 127
956 Exit code of contained command otherwise
960 $ docker run busybox /bin/sh -c 'exit 3'
963 # 3
964
970 During container image development, containers often need to write to
971 the image content. Installing packages into /usr, for example. In
972 production, applications seldom need to write to the image. Container
973 applications write to volumes if they need to write to file systems at
974 all. Applications can be made more secure by running them in read-only
975 mode using the --read-only switch. This protects the containers image
976 from modification. Read only containers may still need to write
977 temporary data. The best way to handle this is to mount tmpfs
978 directories on /run and /tmp.
979 # docker run --read-only --tmpfs /run --tmpfs /tmp -i -t fedora /bin/bash
982
986 If you want messages that are logged in your container to show up in
987 the host's syslog/journal then you should bind mount the /dev/log
988 directory as follows.
989 # docker run -v /dev/log:/dev/log -i -t fedora /bin/bash
992 From inside the container you can test this by sending a message to the
996 log.
997 (bash)# logger "Hello from my container"
1000 Then exit and check the journal.
1004 # exit
1007 # journalctl -b | grep Hello
1009 This should list the message sent to logger.
1013
1016 If you do not specify -a then Docker will attach everything
1017 (stdin,stdout,stderr) you'd like to connect instead, as in:
1018 # docker run -a stdin -a stdout -i -t fedora /bin/bash
1021
1025 Using shm_server.c available here:
1026 ⟨https://www.cs.cf.ac.uk/Dave/C/node27.html⟩
1027 Testing --ipc=host mode:
1030 Host shows a shared memory segment with 7 pids attached, happens to be
1033 from httpd:
1034 $ sudo ipcs -m
1037 ------ Shared Memory Segments --------
1039 key shmid owner perms bytes nattch status
1040 0x01128e25 0 root 600 1000 7
1041 Now run a regular container, and it correctly does NOT see the shared
1045 memory segment from the host:
1046 $ docker run -it shm ipcs -m
1049 ------ Shared Memory Segments --------
1051 key shmid owner perms bytes nattch status
1052 Run a container with the new --ipc=host option, and it now sees the
1056 shared memory segment from the host httpd:
1057 $ docker run -it --ipc=host shm ipcs -m
1060 ------ Shared Memory Segments --------
1062 key shmid owner perms bytes nattch status
1063 0x01128e25 0 root 600 1000 7
1064 Testing --ipc=container:CONTAINERID mode:
1068 Start a container with a program to create a shared memory segment:
1071 $ docker run -it shm bash
1074 $ sudo shm/shm_server
1075 $ sudo ipcs -m
1076 ------ Shared Memory Segments --------
1078 key shmid owner perms bytes nattch status
1079 0x0000162e 0 root 666 27 1
1080 Create a 2nd container correctly shows no shared memory segment from
1084 1st container:
1085 $ docker run shm ipcs -m
1088 ------ Shared Memory Segments --------
1090 key shmid owner perms bytes nattch status
1091 Create a 3rd container using the new --ipc=container:CONTAINERID
1095 option, now it shows the shared memory segment from the first:
1096 $ docker run -it --ipc=container:ed735b2264ac shm ipcs -m
1099 $ sudo ipcs -m
1100 ------ Shared Memory Segments --------
1102 key shmid owner perms bytes nattch status
1103 0x0000162e 0 root 666 27 1
1104
1108 Note: This section describes linking between containers on the
1109 default (bridge) network, also known as "legacy links". Using
1110 --link on user-defined networks uses the DNS-based discovery,
1111 which does not add entries to /etc/hosts, and does not set
1112 environment variables for discovery.
1113 The link feature allows multiple containers to communicate with each
1116 other. For example, a container whose Dockerfile has exposed port 80
1117 can be run and named as follows:
1118 # docker run --name=link-test -d -i -t fedora/httpd
1121 A second container, in this case called linker, can communicate with
1125 the httpd container, named link-test, by running with the
1126 --link=<name>:<alias>
1127 # docker run -t -i --link=link-test:lt --name=linker fedora /bin/bash
1130 Now the container linker is linked to container link-test with the
1134 alias lt. Running the env command in the linker container shows
1135 environment variables
1136 with the LT (alias) context (LT_)
1137 # env
1140 HOSTNAME=668231cb0978
1141 TERM=xterm
1142 LT_PORT_80_TCP=tcp://172.17.0.3:80
1143 LT_PORT_80_TCP_PORT=80
1144 LT_PORT_80_TCP_PROTO=tcp
1145 LT_PORT=tcp://172.17.0.3:80
1146 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
1147 PWD=/
1148 LT_NAME=/linker/lt
1149 SHLVL=1
1150 HOME=/
1151 LT_PORT_80_TCP_ADDR=172.17.0.3
1152 _=/usr/bin/env
1153 When linking two containers Docker will use the exposed ports of the
1157 container to create a secure tunnel for the parent to access.
1158 If a container is connected to the default bridge network and linked
1161 with other containers, then the container's /etc/hosts file is updated
1162 with the linked container's name.
1163 Note Since Docker may live update the container's /etc/hosts
1166 file, there may be situations when processes inside the
1167 container can end up reading an empty or incomplete /etc/hosts
1168 file. In most cases, retrying the read again should fix the
1169 problem.
1170
1173 The exposed port of an application can be mapped to a host port using
1174 the -p flag. For example, an httpd port 80 can be mapped to the host
1175 port 8080 using the following:
1176 # docker run -p 8080:80 -d -i -t fedora/httpd
1179
1183 Many applications require the sharing of persistent data across several
1184 containers. Docker allows you to create a Data Volume Container that
1185 other containers can mount from. For example, create a named container
1186 that contains directories /var/volume1 and /tmp/volume2. The image will
1187 need to contain these directories so a couple of RUN mkdir instructions
1188 might be required for you fedora-data image:
1189 # docker run --name=data -v /var/volume1 -v /tmp/volume2 -i -t fedora-data true
1192 # docker run --volumes-from=data --name=fedora-container1 -i -t fedora bash
1193 Multiple --volumes-from parameters will bring together multiple data
1197 volumes from multiple containers. And it's possible to mount the
1198 volumes that came from the DATA container in yet another container via
1199 the fedora-container1 intermediary container, allowing to abstract the
1200 actual data source from users of that data:
1201 # docker run --volumes-from=fedora-container1 --name=fedora-container2 -i -t fedora bash
1204
1208 To mount a host directory as a container volume, specify the absolute
1209 path to the directory and the absolute path for the container directory
1210 separated by a colon:
1211 # docker run -v /var/db:/data1 -i -t fedora bash
1214 When using SELinux, be aware that the host has no knowledge of
1218 container SELinux policy. Therefore, in the above example, if SELinux
1219 policy is enforced, the /var/db directory is not writable to the
1220 container. A "Permission Denied" message will occur and an avc: message
1221 in the host's syslog.
1222 To work around this, at time of writing this man page, the following
1225 command needs to be run in order for the proper SELinux policy type
1226 label to be attached to the host directory:
1227 # chcon -Rt svirt_sandbox_file_t /var/db
1230 Now, writing to the /data1 volume in the container will be allowed and
1234 the changes will also be reflected on the host in /var/db.
1235
1238 You can override the default labeling scheme for each container by
1239 specifying the --security-opt flag. For example, you can specify the
1240 MCS/MLS level, a requirement for MLS systems. Specifying the level in
1241 the following command allows you to share the same content between
1242 containers.
1243 # docker run --security-opt label=level:s0:c100,c200 -i -t fedora bash
1246 An MLS example might be:
1250 # docker run --security-opt label=level:TopSecret -i -t rhel7 bash
1253 To disable the security labeling for this container versus running with
1257 the --permissive flag, use the following command:
1258 # docker run --security-opt label=disable -i -t fedora bash
1261 If you want a tighter security policy on the processes within a
1265 container, you can specify an alternate type for the container. You
1266 could run a container that is only allowed to listen on Apache ports by
1267 executing the following command:
1268 # docker run --security-opt label=type:svirt_apache_t -i -t centos bash
1271 Note:
1275 You would have to write policy defining a svirt_apache_t type.
1278
1281 If you want to set /dev/sda device weight to 200, you can specify the
1282 device weight by --blkio-weight-device flag. Use the following command:
1283 # docker run -it --blkio-weight-device "/dev/sda:200" ubuntu
1286
1289 This option is useful in situations where you are running Docker
1290 containers on Microsoft Windows. The --isolation <value> option sets a
1291 container's isolation technology. On Linux, the only supported is the
1292 default option which uses Linux namespaces. These two commands are
1293 equivalent on Linux:
1294 $ docker run -d busybox top
1297 $ docker run -d --isolation default busybox top
1298 On Microsoft Windows, can take any of these values:
1302 · default: Use the value specified by the Docker daemon's
1305 --exec-opt . If the daemon does not specify an isolation
1306 technology, Microsoft Windows uses process as its default
1307 value.
1308 · process: Namespace isolation only.
1310 · hyperv: Hyper-V hypervisor partition-based isolation.
1312 In practice, when running on Microsoft Windows without a daemon option
1316 set, these two commands are equivalent:
1317 $ docker run -d --isolation default busybox top
1320 $ docker run -d --isolation process busybox top
1321 If you have set the --exec-opt isolation=hyperv option on the Docker
1325 daemon, any of these commands also result in hyperv isolation:
1326 $ docker run -d --isolation default busybox top
1329 $ docker run -d --isolation hyperv busybox top
1330
1334 The --sysctl sets namespaced kernel parameters (sysctls) in the
1335 container. For example, to turn on IP forwarding in the containers
1336 network namespace, run this command:
1337 $ docker run --sysctl net.ipv4.ip_forward=1 someimage
1340 Note:
1344 Not all sysctls are namespaced. Docker does not support changing
1347 sysctls inside of a container that also modify the host system. As the
1348 kernel evolves we expect to see more sysctls become namespaced.
1349 See the definition of the --sysctl option above for the current list of
1352 supported sysctls.
1353
1357 April 2014, Originally compiled by William Henry (whenry at redhat dot
1358 com) based on docker.com source material and internal work. June 2014,
1359 updated by Sven Dowideit ⟨SvenDowideit@home.org.au⟩ July 2014, updated
1360 by Sven Dowideit ⟨SvenDowideit@home.org.au⟩ November 2015, updated by
1361 Sally O'Malley ⟨somalley@redhat.com⟩
1362Docker Community Docker User Manuals DOCKER(1)