github.com/sijibomii/docker@v0.0.0-20231230191044-5cf6ca554647/man/docker-run.1.md (about) 1 % DOCKER(1) Docker User Manuals 2 % Docker Community 3 % JUNE 2014 4 # NAME 5 docker-run - Run a command in a new container 6 7 # SYNOPSIS 8 **docker run** 9 [**-a**|**--attach**[=*[]*]] 10 [**--add-host**[=*[]*]] 11 [**--blkio-weight**[=*[BLKIO-WEIGHT]*]] 12 [**--blkio-weight-device**[=*[]*]] 13 [**--cpu-shares**[=*0*]] 14 [**--cap-add**[=*[]*]] 15 [**--cap-drop**[=*[]*]] 16 [**--cgroup-parent**[=*CGROUP-PATH*]] 17 [**--cidfile**[=*CIDFILE*]] 18 [**--cpu-period**[=*0*]] 19 [**--cpu-quota**[=*0*]] 20 [**--cpuset-cpus**[=*CPUSET-CPUS*]] 21 [**--cpuset-mems**[=*CPUSET-MEMS*]] 22 [**-d**|**--detach**] 23 [**--detach-keys**[=*[]*]] 24 [**--device**[=*[]*]] 25 [**--device-read-bps**[=*[]*]] 26 [**--device-read-iops**[=*[]*]] 27 [**--device-write-bps**[=*[]*]] 28 [**--device-write-iops**[=*[]*]] 29 [**--dns**[=*[]*]] 30 [**--dns-opt**[=*[]*]] 31 [**--dns-search**[=*[]*]] 32 [**-e**|**--env**[=*[]*]] 33 [**--entrypoint**[=*ENTRYPOINT*]] 34 [**--env-file**[=*[]*]] 35 [**--expose**[=*[]*]] 36 [**--group-add**[=*[]*]] 37 [**-h**|**--hostname**[=*HOSTNAME*]] 38 [**--help**] 39 [**-i**|**--interactive**] 40 [**--ip**[=*IPv4-ADDRESS*]] 41 [**--ip6**[=*IPv6-ADDRESS*]] 42 [**--ipc**[=*IPC*]] 43 [**--isolation**[=*default*]] 44 [**--kernel-memory**[=*KERNEL-MEMORY*]] 45 [**-l**|**--label**[=*[]*]] 46 [**--label-file**[=*[]*]] 47 [**--link**[=*[]*]] 48 [**--log-driver**[=*[]*]] 49 [**--log-opt**[=*[]*]] 50 [**-m**|**--memory**[=*MEMORY*]] 51 [**--mac-address**[=*MAC-ADDRESS*]] 52 [**--memory-reservation**[=*MEMORY-RESERVATION*]] 53 [**--memory-swap**[=*LIMIT*]] 54 [**--memory-swappiness**[=*MEMORY-SWAPPINESS*]] 55 [**--name**[=*NAME*]] 56 [**--net**[=*"bridge"*]] 57 [**--net-alias**[=*[]*]] 58 [**--oom-kill-disable**] 59 [**--oom-score-adj**[=*0*]] 60 [**-P**|**--publish-all**] 61 [**-p**|**--publish**[=*[]*]] 62 [**--pid**[=*[]*]] 63 [**--userns**[=*[]*]] 64 [**--pids-limit**[=*PIDS_LIMIT*]] 65 [**--privileged**] 66 [**--read-only**] 67 [**--restart**[=*RESTART*]] 68 [**--rm**] 69 [**--security-opt**[=*[]*]] 70 [**--storage-opt**[=*[]*]] 71 [**--stop-signal**[=*SIGNAL*]] 72 [**--shm-size**[=*[]*]] 73 [**--sig-proxy**[=*true*]] 74 [**--sysctl**[=*[]*]] 75 [**-t**|**--tty**] 76 [**--tmpfs**[=*[CONTAINER-DIR[:<OPTIONS>]*]] 77 [**-u**|**--user**[=*USER*]] 78 [**--ulimit**[=*[]*]] 79 [**--uts**[=*[]*]] 80 [**-v**|**--volume**[=*[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*]] 81 [**--volume-driver**[=*DRIVER*]] 82 [**--volumes-from**[=*[]*]] 83 [**-w**|**--workdir**[=*WORKDIR*]] 84 IMAGE [COMMAND] [ARG...] 85 86 # DESCRIPTION 87 88 Run a process in a new container. **docker run** starts a process with its own 89 file system, its own networking, and its own isolated process tree. The IMAGE 90 which starts the process may define defaults related to the process that will be 91 run in the container, the networking to expose, and more, but **docker run** 92 gives final control to the operator or administrator who starts the container 93 from the image. For that reason **docker run** has more options than any other 94 Docker command. 95 96 If the IMAGE is not already loaded then **docker run** will pull the IMAGE, and 97 all image dependencies, from the repository in the same way running **docker 98 pull** IMAGE, before it starts the container from that image. 99 100 # OPTIONS 101 **-a**, **--attach**=[] 102 Attach to STDIN, STDOUT or STDERR. 103 104 In foreground mode (the default when **-d** 105 is not specified), **docker run** can start the process in the container 106 and attach the console to the process’s standard input, output, and standard 107 error. It can even pretend to be a TTY (this is what most commandline 108 executables expect) and pass along signals. The **-a** option can be set for 109 each of stdin, stdout, and stderr. 110 111 **--add-host**=[] 112 Add a custom host-to-IP mapping (host:ip) 113 114 Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** 115 option can be set multiple times. 116 117 **--blkio-weight**=*0* 118 Block IO weight (relative weight) accepts a weight value between 10 and 1000. 119 120 **--blkio-weight-device**=[] 121 Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`). 122 123 **--cpu-shares**=*0* 124 CPU shares (relative weight) 125 126 By default, all containers get the same proportion of CPU cycles. This proportion 127 can be modified by changing the container's CPU share weighting relative 128 to the weighting of all other running containers. 129 130 To modify the proportion from the default of 1024, use the **--cpu-shares** 131 flag to set the weighting to 2 or higher. 132 133 The proportion will only apply when CPU-intensive processes are running. 134 When tasks in one container are idle, other containers can use the 135 left-over CPU time. The actual amount of CPU time will vary depending on 136 the number of containers running on the system. 137 138 For example, consider three containers, one has a cpu-share of 1024 and 139 two others have a cpu-share setting of 512. When processes in all three 140 containers attempt to use 100% of CPU, the first container would receive 141 50% of the total CPU time. If you add a fourth container with a cpu-share 142 of 1024, the first container only gets 33% of the CPU. The remaining containers 143 receive 16.5%, 16.5% and 33% of the CPU. 144 145 On a multi-core system, the shares of CPU time are distributed over all CPU 146 cores. Even if a container is limited to less than 100% of CPU time, it can 147 use 100% of each individual CPU core. 148 149 For example, consider a system with more than three cores. If you start one 150 container **{C0}** with **-c=512** running one process, and another container 151 **{C1}** with **-c=1024** running two processes, this can result in the following 152 division of CPU shares: 153 154 PID container CPU CPU share 155 100 {C0} 0 100% of CPU0 156 101 {C1} 1 100% of CPU1 157 102 {C1} 2 100% of CPU2 158 159 **--cap-add**=[] 160 Add Linux capabilities 161 162 **--cap-drop**=[] 163 Drop Linux capabilities 164 165 **--cgroup-parent**="" 166 Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. 167 168 **--cidfile**="" 169 Write the container ID to the file 170 171 **--cpu-period**=*0* 172 Limit the CPU CFS (Completely Fair Scheduler) period 173 174 Limit the container's CPU usage. This flag tell the kernel to restrict the container's CPU usage to the period you specify. 175 176 **--cpuset-cpus**="" 177 CPUs in which to allow execution (0-3, 0,1) 178 179 **--cpuset-mems**="" 180 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. 181 182 If you have four memory nodes on your system (0-3), use `--cpuset-mems=0,1` 183 then processes in your Docker container will only use memory from the first 184 two memory nodes. 185 186 **--cpu-quota**=*0* 187 Limit the CPU CFS (Completely Fair Scheduler) quota 188 189 Limit the container's CPU usage. By default, containers run with the full 190 CPU resource. This flag tell the kernel to restrict the container's CPU usage 191 to the quota you specify. 192 193 **-d**, **--detach**=*true*|*false* 194 Detached mode: run the container in the background and print the new container ID. The default is *false*. 195 196 At any time you can run **docker ps** in 197 the other shell to view a list of the running containers. You can reattach to a 198 detached container with **docker attach**. If you choose to run a container in 199 the detached mode, then you cannot use the **-rm** option. 200 201 When attached in the tty mode, you can detach from the container (and leave it 202 running) using a configurable key sequence. The default sequence is `CTRL-p CTRL-q`. 203 You configure the key sequence using the **--detach-keys** option or a configuration file. 204 See **config-json(5)** for documentation on using a configuration file. 205 206 **--detach-keys**="" 207 Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. 208 209 **--device**=[] 210 Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc:rwm) 211 212 **--device-read-bps**=[] 213 Limit read rate from a device (e.g. --device-read-bps=/dev/sda:1mb) 214 215 **--device-read-iops**=[] 216 Limit read rate from a device (e.g. --device-read-iops=/dev/sda:1000) 217 218 **--device-write-bps**=[] 219 Limit write rate to a device (e.g. --device-write-bps=/dev/sda:1mb) 220 221 **--device-write-iops**=[] 222 Limit write rate a a device (e.g. --device-write-iops=/dev/sda:1000) 223 224 **--dns-search**=[] 225 Set custom DNS search domains (Use --dns-search=. if you don't wish to set the search domain) 226 227 **--dns-opt**=[] 228 Set custom DNS options 229 230 **--dns**=[] 231 Set custom DNS servers 232 233 This option can be used to override the DNS 234 configuration passed to the container. Typically this is necessary when the 235 host DNS configuration is invalid for the container (e.g., 127.0.0.1). When this 236 is the case the **--dns** flags is necessary for every run. 237 238 **-e**, **--env**=[] 239 Set environment variables 240 241 This option allows you to specify arbitrary 242 environment variables that are available for the process that will be launched 243 inside of the container. 244 245 **--entrypoint**="" 246 Overwrite the default ENTRYPOINT of the image 247 248 This option allows you to overwrite the default entrypoint of the image that 249 is set in the Dockerfile. The ENTRYPOINT of an image is similar to a COMMAND 250 because it specifies what executable to run when the container starts, but it is 251 (purposely) more difficult to override. The ENTRYPOINT gives a container its 252 default nature or behavior, so that when you set an ENTRYPOINT you can run the 253 container as if it were that binary, complete with default options, and you can 254 pass in more options via the COMMAND. But, sometimes an operator may want to run 255 something else inside the container, so you can override the default ENTRYPOINT 256 at runtime by using a **--entrypoint** and a string to specify the new 257 ENTRYPOINT. 258 259 **--env-file**=[] 260 Read in a line delimited file of environment variables 261 262 **--expose**=[] 263 Expose a port, or a range of ports (e.g. --expose=3300-3310) informs Docker 264 that the container listens on the specified network ports at runtime. Docker 265 uses this information to interconnect containers using links and to set up port 266 redirection on the host system. 267 268 **--group-add**=[] 269 Add additional groups to run as 270 271 **-h**, **--hostname**="" 272 Container host name 273 274 Sets the container host name that is available inside the container. 275 276 **--help** 277 Print usage statement 278 279 **-i**, **--interactive**=*true*|*false* 280 Keep STDIN open even if not attached. The default is *false*. 281 282 When set to true, keep stdin open even if not attached. The default is false. 283 284 **--ip**="" 285 Sets the container's interface IPv4 address (e.g. 172.23.0.9) 286 287 It can only be used in conjunction with **--net** for user-defined networks 288 289 **--ip6**="" 290 Sets the container's interface IPv6 address (e.g. 2001:db8::1b99) 291 292 It can only be used in conjunction with **--net** for user-defined networks 293 294 **--ipc**="" 295 Default is to create a private IPC namespace (POSIX SysV IPC) for the container 296 'container:<name|id>': reuses another container shared memory, semaphores and message queues 297 'host': use the host shared memory,semaphores and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. 298 299 **--isolation**="*default*" 300 Isolation specifies the type of isolation technology used by containers. 301 302 **-l**, **--label**=[] 303 Set metadata on the container (e.g., --label com.example.key=value) 304 305 **--kernel-memory**="" 306 Kernel memory limit (format: `<number>[<unit>]`, where unit = b, k, m or g) 307 308 Constrains the kernel memory available to a container. If a limit of 0 309 is specified (not using `--kernel-memory`), the container's kernel memory 310 is not limited. If you specify a limit, it may be rounded up to a multiple 311 of the operating system's page size and the value can be very large, 312 millions of trillions. 313 314 **--label-file**=[] 315 Read in a line delimited file of labels 316 317 **--link**=[] 318 Add link to another container in the form of <name or id>:alias or just <name or id> 319 in which case the alias will match the name 320 321 If the operator 322 uses **--link** when starting the new client container, then the client 323 container can access the exposed port via a private networking interface. Docker 324 will set some environment variables in the client container to help indicate 325 which interface and port to use. 326 327 **--log-driver**="*json-file*|*syslog*|*journald*|*gelf*|*fluentd*|*awslogs*|*splunk*|*etwlogs*|*gcplogs*|*none*" 328 Logging driver for container. Default is defined by daemon `--log-driver` flag. 329 **Warning**: the `docker logs` command works only for the `json-file` and 330 `journald` logging drivers. 331 332 **--log-opt**=[] 333 Logging driver specific options. 334 335 **-m**, **--memory**="" 336 Memory limit (format: <number>[<unit>], where unit = b, k, m or g) 337 338 Allows you to constrain the memory available to a container. If the host 339 supports swap memory, then the **-m** memory setting can be larger than physical 340 RAM. If a limit of 0 is specified (not using **-m**), the container's memory is 341 not limited. The actual limit may be rounded up to a multiple of the operating 342 system's page size (the value would be very large, that's millions of trillions). 343 344 **--memory-reservation**="" 345 Memory soft limit (format: <number>[<unit>], where unit = b, k, m or g) 346 347 After setting memory reservation, when the system detects memory contention 348 or low memory, containers are forced to restrict their consumption to their 349 reservation. So you should always set the value below **--memory**, otherwise the 350 hard limit will take precedence. By default, memory reservation will be the same 351 as memory limit. 352 353 **--memory-swap**="LIMIT" 354 A limit value equal to memory plus swap. Must be used with the **-m** 355 (**--memory**) flag. The swap `LIMIT` should always be larger than **-m** 356 (**--memory**) value. 357 358 The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes), 359 `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you don't specify a 360 unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap. 361 362 **--mac-address**="" 363 Container MAC address (e.g. 92:d0:c6:0a:29:33) 364 365 Remember that the MAC address in an Ethernet network must be unique. 366 The IPv6 link-local address will be based on the device's MAC address 367 according to RFC4862. 368 369 **--name**="" 370 Assign a name to the container 371 372 The operator can identify a container in three ways: 373 UUID long identifier (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”) 374 UUID short identifier (“f78375b1c487”) 375 Name (“jonah”) 376 377 The UUID identifiers come from the Docker daemon, and if a name is not assigned 378 to the container with **--name** then the daemon will also generate a random 379 string name. The name is useful when defining links (see **--link**) (or any 380 other place you need to identify a container). This works for both background 381 and foreground Docker containers. 382 383 **--net**="*bridge*" 384 Set the Network mode for the container 385 'bridge': create a network stack on the default Docker bridge 386 'none': no networking 387 'container:<name|id>': reuse another container's network stack 388 'host': use the Docker host network stack. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure. 389 '<network-name>|<network-id>': connect to a user-defined network 390 391 **--net-alias**=[] 392 Add network-scoped alias for the container 393 394 **--oom-kill-disable**=*true*|*false* 395 Whether to disable OOM Killer for the container or not. 396 397 **--oom-score-adj**="" 398 Tune the host's OOM preferences for containers (accepts -1000 to 1000) 399 400 **-P**, **--publish-all**=*true*|*false* 401 Publish all exposed ports to random ports on the host interfaces. The default is *false*. 402 403 When set to true publish all exposed ports to the host interfaces. The 404 default is false. If the operator uses -P (or -p) then Docker will make the 405 exposed port accessible on the host and the ports will be available to any 406 client that can reach the host. When using -P, Docker will bind any exposed 407 port to a random port on the host within an *ephemeral port range* defined by 408 `/proc/sys/net/ipv4/ip_local_port_range`. To find the mapping between the host 409 ports and the exposed ports, use `docker port`. 410 411 **-p**, **--publish**=[] 412 Publish a container's port, or range of ports, to the host. 413 414 Format: `ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort` 415 Both hostPort and containerPort can be specified as a range of ports. 416 When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. 417 (e.g., `docker run -p 1234-1236:1222-1224 --name thisWorks -t busybox` 418 but not `docker run -p 1230-1236:1230-1240 --name RangeContainerPortsBiggerThanRangeHostPorts -t busybox`) 419 With ip: `docker run -p 127.0.0.1:$HOSTPORT:$CONTAINERPORT --name CONTAINER -t someimage` 420 Use `docker port` to see the actual mapping: `docker port CONTAINER $CONTAINERPORT` 421 422 **--pid**=*host* 423 Set the PID mode for the container 424 **host**: use the host's PID namespace inside the container. 425 Note: the host mode gives the container full access to local PID and is therefore considered insecure. 426 427 **--userns**="" 428 Set the usernamespace mode for the container when `userns-remap` option is enabled. 429 **host**: use the host usernamespace and enable all privileged options (e.g., `pid=host` or `--privileged`). 430 431 **--pids-limit**="" 432 Tune the container's pids limit. Set `-1` to have unlimited pids for the container. 433 434 **--uts**=*host* 435 Set the UTS mode for the container 436 **host**: use the host's UTS namespace inside the container. 437 Note: the host mode gives the container access to changing the host's hostname and is therefore considered insecure. 438 439 **--privileged**=*true*|*false* 440 Give extended privileges to this container. The default is *false*. 441 442 By default, Docker containers are 443 “unprivileged” (=false) and cannot, for example, run a Docker daemon inside the 444 Docker container. This is because by default a container is not allowed to 445 access any devices. A “privileged” container is given access to all devices. 446 447 When the operator executes **docker run --privileged**, Docker will enable access 448 to all devices on the host as well as set some configuration in AppArmor to 449 allow the container nearly all the same access to the host as processes running 450 outside of a container on the host. 451 452 **--read-only**=*true*|*false* 453 Mount the container's root filesystem as read only. 454 455 By default a container will have its root filesystem writable allowing processes 456 to write files anywhere. By specifying the `--read-only` flag the container will have 457 its root filesystem mounted as read only prohibiting any writes. 458 459 **--restart**="*no*" 460 Restart policy to apply when a container exits (no, on-failure[:max-retry], always, unless-stopped). 461 462 **--rm**=*true*|*false* 463 Automatically remove the container when it exits (incompatible with -d). The default is *false*. 464 465 **--security-opt**=[] 466 Security Options 467 468 "label=user:USER" : Set the label user for the container 469 "label=role:ROLE" : Set the label role for the container 470 "label=type:TYPE" : Set the label type for the container 471 "label=level:LEVEL" : Set the label level for the container 472 "label=disable" : Turn off label confinement for the container 473 "no-new-privileges" : Disable container processes from gaining additional privileges 474 475 "seccomp=unconfined" : Turn off seccomp confinement for the container 476 "seccomp=profile.json : White listed syscalls seccomp Json file to be used as a seccomp filter 477 478 "apparmor=unconfined" : Turn off apparmor confinement for the container 479 "apparmor=your-profile" : Set the apparmor confinement profile for the container 480 481 **--storage-opt**=[] 482 Storage driver options per container 483 484 $ docker run -it --storage-opt size=120G fedora /bin/bash 485 486 This (size) will allow to set the container rootfs size to 120G at creation time. User cannot pass a size less than the Default BaseFS Size. 487 488 **--stop-signal**=*SIGTERM* 489 Signal to stop a container. Default is SIGTERM. 490 491 **--shm-size**="" 492 Size of `/dev/shm`. The format is `<number><unit>`. 493 `number` must be greater than `0`. Unit is optional and can be `b` (bytes), `k` (kilobytes), `m`(megabytes), or `g` (gigabytes). 494 If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`. 495 496 **--sysctl**=SYSCTL 497 Configure namespaced kernel parameters at runtime 498 499 IPC Namespace - current sysctls allowed: 500 501 kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced 502 Sysctls beginning with fs.mqueue.* 503 504 If you use the `--ipc=host` option these sysctls will not be allowed. 505 506 Network Namespace - current sysctls allowed: 507 Sysctls beginning with net.* 508 509 If you use the `--net=host` option these sysctls will not be allowed. 510 511 **--sig-proxy**=*true*|*false* 512 Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is *true*. 513 514 **--memory-swappiness**="" 515 Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. 516 517 **-t**, **--tty**=*true*|*false* 518 Allocate a pseudo-TTY. The default is *false*. 519 520 When set to true Docker can allocate a pseudo-tty and attach to the standard 521 input of any container. This can be used, for example, to run a throwaway 522 interactive shell. The default is false. 523 524 The **-t** option is incompatible with a redirection of the docker client 525 standard input. 526 527 **--tmpfs**=[] Create a tmpfs mount 528 529 Mount a temporary filesystem (`tmpfs`) mount into a container, for example: 530 531 $ docker run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image 532 533 This command mounts a `tmpfs` at `/tmp` within the container. The supported mount 534 options are the same as the Linux default `mount` flags. If you do not specify 535 any options, the systems uses the following options: 536 `rw,noexec,nosuid,nodev,size=65536k`. 537 538 **-u**, **--user**="" 539 Sets the username or UID used and optionally the groupname or GID for the specified command. 540 541 The followings examples are all valid: 542 --user [user | user:group | uid | uid:gid | user:gid | uid:group ] 543 544 Without this argument the command will be run as root in the container. 545 546 **--ulimit**=[] 547 Ulimit options 548 549 **-v**|**--volume**[=*[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*] 550 Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Docker 551 bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Docker 552 container. If 'HOST-DIR' is omitted, Docker automatically creates the new 553 volume on the host. The `OPTIONS` are a comma delimited list and can be: 554 555 * [rw|ro] 556 * [z|Z] 557 * [`[r]shared`|`[r]slave`|`[r]private`] 558 * [nocopy] 559 560 The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The `HOST-DIR` 561 can be an absolute path or a `name` value. A `name` value must start with an 562 alphanumeric character, followed by `a-z0-9`, `_` (underscore), `.` (period) or 563 `-` (hyphen). An absolute path starts with a `/` (forward slash). 564 565 If you supply a `HOST-DIR` that is an absolute path, Docker bind-mounts to the 566 path you specify. If you supply a `name`, Docker creates a named volume by that 567 `name`. For example, you can specify either `/foo` or `foo` for a `HOST-DIR` 568 value. If you supply the `/foo` value, Docker creates a bind-mount. If you 569 supply the `foo` specification, Docker creates a named volume. 570 571 You can specify multiple **-v** options to mount one or more mounts to a 572 container. To use these same mounts in other containers, specify the 573 **--volumes-from** option also. 574 575 You can add `:ro` or `:rw` suffix to a volume to mount it read-only or 576 read-write mode, respectively. By default, the volumes are mounted read-write. 577 See examples. 578 579 Labeling systems like SELinux require that proper labels are placed on volume 580 content mounted into a container. Without a label, the security system might 581 prevent the processes running inside the container from using the content. By 582 default, Docker does not change the labels set by the OS. 583 584 To change a label in the container context, you can add either of two suffixes 585 `:z` or `:Z` to the volume mount. These suffixes tell Docker to relabel file 586 objects on the shared volumes. The `z` option tells Docker that two containers 587 share the volume content. As a result, Docker labels the content with a shared 588 content label. Shared volume labels allow all containers to read/write content. 589 The `Z` option tells Docker to label the content with a private unshared label. 590 Only the current container can use a private volume. 591 592 By default bind mounted volumes are `private`. That means any mounts done 593 inside container will not be visible on host and vice-a-versa. One can change 594 this behavior by specifying a volume mount propagation property. Making a 595 volume `shared` mounts done under that volume inside container will be 596 visible on host and vice-a-versa. Making a volume `slave` enables only one 597 way mount propagation and that is mounts done on host under that volume 598 will be visible inside container but not the other way around. 599 600 To control mount propagation property of volume one can use `:[r]shared`, 601 `:[r]slave` or `:[r]private` propagation flag. Propagation property can 602 be specified only for bind mounted volumes and not for internal volumes or 603 named volumes. For mount propagation to work source mount point (mount point 604 where source dir is mounted on) has to have right propagation properties. For 605 shared volumes, source mount point has to be shared. And for slave volumes, 606 source mount has to be either shared or slave. 607 608 Use `df <source-dir>` to figure out the source mount and then use 609 `findmnt -o TARGET,PROPAGATION <source-mount-dir>` to figure out propagation 610 properties of source mount. If `findmnt` utility is not available, then one 611 can look at mount entry for source mount point in `/proc/self/mountinfo`. Look 612 at `optional fields` and see if any propagaion properties are specified. 613 `shared:X` means mount is `shared`, `master:X` means mount is `slave` and if 614 nothing is there that means mount is `private`. 615 616 To change propagation properties of a mount point use `mount` command. For 617 example, if one wants to bind mount source directory `/foo` one can do 618 `mount --bind /foo /foo` and `mount --make-private --make-shared /foo`. This 619 will convert /foo into a `shared` mount point. Alternatively one can directly 620 change propagation properties of source mount. Say `/` is source mount for 621 `/foo`, then use `mount --make-shared /` to convert `/` into a `shared` mount. 622 623 > **Note**: 624 > When using systemd to manage the Docker daemon's start and stop, in the systemd 625 > unit file there is an option to control mount propagation for the Docker daemon 626 > itself, called `MountFlags`. The value of this setting may cause Docker to not 627 > see mount propagation changes made on the mount point. For example, if this value 628 > is `slave`, you may not be able to use the `shared` or `rshared` propagation on 629 > a volume. 630 631 To disable automatic copying of data from the container path to the volume, use 632 the `nocopy` flag. The `nocopy` flag can be set on bind mounts and named volumes. 633 634 **--volume-driver**="" 635 Container's volume driver. This driver creates volumes specified either from 636 a Dockerfile's `VOLUME` instruction or from the `docker run -v` flag. 637 See **docker-volume-create(1)** for full details. 638 639 **--volumes-from**=[] 640 Mount volumes from the specified container(s) 641 642 Mounts already mounted volumes from a source container onto another 643 container. You must supply the source's container-id. To share 644 a volume, use the **--volumes-from** option when running 645 the target container. You can share volumes even if the source container 646 is not running. 647 648 By default, Docker mounts the volumes in the same mode (read-write or 649 read-only) as it is mounted in the source container. Optionally, you 650 can change this by suffixing the container-id with either the `:ro` or 651 `:rw ` keyword. 652 653 If the location of the volume from the source container overlaps with 654 data residing on a target container, then the volume hides 655 that data on the target. 656 657 **-w**, **--workdir**="" 658 Working directory inside the container 659 660 The default working directory for 661 running binaries within a container is the root directory (/). The developer can 662 set a different default with the Dockerfile WORKDIR instruction. The operator 663 can override the working directory by using the **-w** option. 664 665 # Exit Status 666 667 The exit code from `docker run` gives information about why the container 668 failed to run or why it exited. When `docker run` exits with a non-zero code, 669 the exit codes follow the `chroot` standard, see below: 670 671 **_125_** if the error is with Docker daemon **_itself_** 672 673 $ docker run --foo busybox; echo $? 674 # flag provided but not defined: --foo 675 See 'docker run --help'. 676 125 677 678 **_126_** if the **_contained command_** cannot be invoked 679 680 $ docker run busybox /etc; echo $? 681 # exec: "/etc": permission denied 682 docker: Error response from daemon: Contained command could not be invoked 683 126 684 685 **_127_** if the **_contained command_** cannot be found 686 687 $ docker run busybox foo; echo $? 688 # exec: "foo": executable file not found in $PATH 689 docker: Error response from daemon: Contained command not found or does not exist 690 127 691 692 **_Exit code_** of **_contained command_** otherwise 693 694 $ docker run busybox /bin/sh -c 'exit 3' 695 # 3 696 697 # EXAMPLES 698 699 ## Running container in read-only mode 700 701 During container image development, containers often need to write to the image 702 content. Installing packages into /usr, for example. In production, 703 applications seldom need to write to the image. Container applications write 704 to volumes if they need to write to file systems at all. Applications can be 705 made more secure by running them in read-only mode using the --read-only switch. 706 This protects the containers image from modification. Read only containers may 707 still need to write temporary data. The best way to handle this is to mount 708 tmpfs directories on /run and /tmp. 709 710 # docker run --read-only --tmpfs /run --tmpfs /tmp -i -t fedora /bin/bash 711 712 ## Exposing log messages from the container to the host's log 713 714 If you want messages that are logged in your container to show up in the host's 715 syslog/journal then you should bind mount the /dev/log directory as follows. 716 717 # docker run -v /dev/log:/dev/log -i -t fedora /bin/bash 718 719 From inside the container you can test this by sending a message to the log. 720 721 (bash)# logger "Hello from my container" 722 723 Then exit and check the journal. 724 725 # exit 726 727 # journalctl -b | grep Hello 728 729 This should list the message sent to logger. 730 731 ## Attaching to one or more from STDIN, STDOUT, STDERR 732 733 If you do not specify -a then Docker will attach everything (stdin,stdout,stderr) 734 . You can specify to which of the three standard streams (stdin, stdout, stderr) 735 you’d like to connect instead, as in: 736 737 # docker run -a stdin -a stdout -i -t fedora /bin/bash 738 739 ## Sharing IPC between containers 740 741 Using shm_server.c available here: https://www.cs.cf.ac.uk/Dave/C/node27.html 742 743 Testing `--ipc=host` mode: 744 745 Host shows a shared memory segment with 7 pids attached, happens to be from httpd: 746 747 ``` 748 $ sudo ipcs -m 749 750 ------ Shared Memory Segments -------- 751 key shmid owner perms bytes nattch status 752 0x01128e25 0 root 600 1000 7 753 ``` 754 755 Now run a regular container, and it correctly does NOT see the shared memory segment from the host: 756 757 ``` 758 $ docker run -it shm ipcs -m 759 760 ------ Shared Memory Segments -------- 761 key shmid owner perms bytes nattch status 762 ``` 763 764 Run a container with the new `--ipc=host` option, and it now sees the shared memory segment from the host httpd: 765 766 ``` 767 $ docker run -it --ipc=host shm ipcs -m 768 769 ------ Shared Memory Segments -------- 770 key shmid owner perms bytes nattch status 771 0x01128e25 0 root 600 1000 7 772 ``` 773 Testing `--ipc=container:CONTAINERID` mode: 774 775 Start a container with a program to create a shared memory segment: 776 ``` 777 $ docker run -it shm bash 778 $ sudo shm/shm_server & 779 $ sudo ipcs -m 780 781 ------ Shared Memory Segments -------- 782 key shmid owner perms bytes nattch status 783 0x0000162e 0 root 666 27 1 784 ``` 785 Create a 2nd container correctly shows no shared memory segment from 1st container: 786 ``` 787 $ docker run shm ipcs -m 788 789 ------ Shared Memory Segments -------- 790 key shmid owner perms bytes nattch status 791 ``` 792 793 Create a 3rd container using the new --ipc=container:CONTAINERID option, now it shows the shared memory segment from the first: 794 795 ``` 796 $ docker run -it --ipc=container:ed735b2264ac shm ipcs -m 797 $ sudo ipcs -m 798 799 ------ Shared Memory Segments -------- 800 key shmid owner perms bytes nattch status 801 0x0000162e 0 root 666 27 1 802 ``` 803 804 ## Linking Containers 805 806 > **Note**: This section describes linking between containers on the 807 > default (bridge) network, also known as "legacy links". Using `--link` 808 > on user-defined networks uses the DNS-based discovery, which does not add 809 > entries to `/etc/hosts`, and does not set environment variables for 810 > discovery. 811 812 The link feature allows multiple containers to communicate with each other. For 813 example, a container whose Dockerfile has exposed port 80 can be run and named 814 as follows: 815 816 # docker run --name=link-test -d -i -t fedora/httpd 817 818 A second container, in this case called linker, can communicate with the httpd 819 container, named link-test, by running with the **--link=<name>:<alias>** 820 821 # docker run -t -i --link=link-test:lt --name=linker fedora /bin/bash 822 823 Now the container linker is linked to container link-test with the alias lt. 824 Running the **env** command in the linker container shows environment variables 825 with the LT (alias) context (**LT_**) 826 827 # env 828 HOSTNAME=668231cb0978 829 TERM=xterm 830 LT_PORT_80_TCP=tcp://172.17.0.3:80 831 LT_PORT_80_TCP_PORT=80 832 LT_PORT_80_TCP_PROTO=tcp 833 LT_PORT=tcp://172.17.0.3:80 834 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin 835 PWD=/ 836 LT_NAME=/linker/lt 837 SHLVL=1 838 HOME=/ 839 LT_PORT_80_TCP_ADDR=172.17.0.3 840 _=/usr/bin/env 841 842 When linking two containers Docker will use the exposed ports of the container 843 to create a secure tunnel for the parent to access. 844 845 If a container is connected to the default bridge network and `linked` 846 with other containers, then the container's `/etc/hosts` file is updated 847 with the linked container's name. 848 849 > **Note** Since Docker may live update the container’s `/etc/hosts` file, there 850 may be situations when processes inside the container can end up reading an 851 empty or incomplete `/etc/hosts` file. In most cases, retrying the read again 852 should fix the problem. 853 854 855 ## Mapping Ports for External Usage 856 857 The exposed port of an application can be mapped to a host port using the **-p** 858 flag. For example, a httpd port 80 can be mapped to the host port 8080 using the 859 following: 860 861 # docker run -p 8080:80 -d -i -t fedora/httpd 862 863 ## Creating and Mounting a Data Volume Container 864 865 Many applications require the sharing of persistent data across several 866 containers. Docker allows you to create a Data Volume Container that other 867 containers can mount from. For example, create a named container that contains 868 directories /var/volume1 and /tmp/volume2. The image will need to contain these 869 directories so a couple of RUN mkdir instructions might be required for you 870 fedora-data image: 871 872 # docker run --name=data -v /var/volume1 -v /tmp/volume2 -i -t fedora-data true 873 # docker run --volumes-from=data --name=fedora-container1 -i -t fedora bash 874 875 Multiple --volumes-from parameters will bring together multiple data volumes from 876 multiple containers. And it's possible to mount the volumes that came from the 877 DATA container in yet another container via the fedora-container1 intermediary 878 container, allowing to abstract the actual data source from users of that data: 879 880 # docker run --volumes-from=fedora-container1 --name=fedora-container2 -i -t fedora bash 881 882 ## Mounting External Volumes 883 884 To mount a host directory as a container volume, specify the absolute path to 885 the directory and the absolute path for the container directory separated by a 886 colon: 887 888 # docker run -v /var/db:/data1 -i -t fedora bash 889 890 When using SELinux, be aware that the host has no knowledge of container SELinux 891 policy. Therefore, in the above example, if SELinux policy is enforced, the 892 `/var/db` directory is not writable to the container. A "Permission Denied" 893 message will occur and an avc: message in the host's syslog. 894 895 896 To work around this, at time of writing this man page, the following command 897 needs to be run in order for the proper SELinux policy type label to be attached 898 to the host directory: 899 900 # chcon -Rt svirt_sandbox_file_t /var/db 901 902 903 Now, writing to the /data1 volume in the container will be allowed and the 904 changes will also be reflected on the host in /var/db. 905 906 ## Using alternative security labeling 907 908 You can override the default labeling scheme for each container by specifying 909 the `--security-opt` flag. For example, you can specify the MCS/MLS level, a 910 requirement for MLS systems. Specifying the level in the following command 911 allows you to share the same content between containers. 912 913 # docker run --security-opt label=level:s0:c100,c200 -i -t fedora bash 914 915 An MLS example might be: 916 917 # docker run --security-opt label=level:TopSecret -i -t rhel7 bash 918 919 To disable the security labeling for this container versus running with the 920 `--permissive` flag, use the following command: 921 922 # docker run --security-opt label=disable -i -t fedora bash 923 924 If you want a tighter security policy on the processes within a container, 925 you can specify an alternate type for the container. You could run a container 926 that is only allowed to listen on Apache ports by executing the following 927 command: 928 929 # docker run --security-opt label=type:svirt_apache_t -i -t centos bash 930 931 Note: 932 933 You would have to write policy defining a `svirt_apache_t` type. 934 935 ## Setting device weight 936 937 If you want to set `/dev/sda` device weight to `200`, you can specify the device 938 weight by `--blkio-weight-device` flag. Use the following command: 939 940 # docker run -it --blkio-weight-device "/dev/sda:200" ubuntu 941 942 ## Specify isolation technology for container (--isolation) 943 944 This option is useful in situations where you are running Docker containers on 945 Microsoft Windows. The `--isolation <value>` option sets a container's isolation 946 technology. On Linux, the only supported is the `default` option which uses 947 Linux namespaces. These two commands are equivalent on Linux: 948 949 ``` 950 $ docker run -d busybox top 951 $ docker run -d --isolation default busybox top 952 ``` 953 954 On Microsoft Windows, can take any of these values: 955 956 * `default`: Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. 957 * `process`: Namespace isolation only. 958 * `hyperv`: Hyper-V hypervisor partition-based isolation. 959 960 In practice, when running on Microsoft Windows without a `daemon` option set, these two commands are equivalent: 961 962 ``` 963 $ docker run -d --isolation default busybox top 964 $ docker run -d --isolation process busybox top 965 ``` 966 967 If you have set the `--exec-opt isolation=hyperv` option on the Docker `daemon`, any of these commands also result in `hyperv` isolation: 968 969 ``` 970 $ docker run -d --isolation default busybox top 971 $ docker run -d --isolation hyperv busybox top 972 ``` 973 974 ## Setting Namespaced Kernel Parameters (Sysctls) 975 976 The `--sysctl` sets namespaced kernel parameters (sysctls) in the 977 container. For example, to turn on IP forwarding in the containers 978 network namespace, run this command: 979 980 $ docker run --sysctl net.ipv4.ip_forward=1 someimage 981 982 Note: 983 984 Not all sysctls are namespaced. docker does not support changing sysctls 985 inside of a container that also modify the host system. As the kernel 986 evolves we expect to see more sysctls become namespaced. 987 988 See the definition of the `--sysctl` option above for the current list of 989 supported sysctls. 990 991 # HISTORY 992 April 2014, Originally compiled by William Henry (whenry at redhat dot com) 993 based on docker.com source material and internal work. 994 June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> 995 July 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> 996 November 2015, updated by Sally O'Malley <somalley@redhat.com>