github.com/jogo/docker@v1.7.0-rc1/docs/sources/reference/run.md (about) 1 page_title: Docker run reference 2 page_description: Configure containers at runtime 3 page_keywords: docker, run, configure, runtime 4 5 <!-- TODO (@thaJeztah) define more flexible table/td classes --> 6 <style> 7 .content-body table .no-wrap { 8 white-space: nowrap; 9 } 10 </style> 11 # Docker run reference 12 13 **Docker runs processes in isolated containers**. When an operator 14 executes `docker run`, she starts a process with its own file system, 15 its own networking, and its own isolated process tree. The 16 [*Image*](/terms/image/#image) which starts the process may define 17 defaults related to the binary to run, the networking to expose, and 18 more, but `docker run` gives final control to the operator who starts 19 the container from the image. That's the main reason 20 [*run*](/reference/commandline/cli/#run) has more options than any 21 other `docker` command. 22 23 ## General form 24 25 The basic `docker run` command takes this form: 26 27 $ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...] 28 29 To learn how to interpret the types of `[OPTIONS]`, 30 see [*Option types*](/reference/commandline/cli/#option-types). 31 32 The `run` options control the image's runtime behavior in a container. These 33 settings affect: 34 35 * detached or foreground running 36 * container identification 37 * network settings 38 * runtime constraints on CPU and memory 39 * privileges and LXC configuration 40 41 An image developer may set defaults for these same settings when they create the 42 image using the `docker build` command. Operators, however, can override all 43 defaults set by the developer using the `run` options. And, operators can also 44 override nearly all the defaults set by the Docker runtime itself. 45 46 Finally, depending on your Docker system configuration, you may be required to 47 preface each `docker` command with `sudo`. To avoid having to use `sudo` with 48 the `docker` command, your system administrator can create a Unix group called 49 `docker` and add users to it. For more information about this configuration, 50 refer to the Docker installation documentation for your operating system. 51 52 ## Operator exclusive options 53 54 Only the operator (the person executing `docker run`) can set the 55 following options. 56 57 - [Detached vs Foreground](#detached-vs-foreground) 58 - [Detached (-d)](#detached-d) 59 - [Foreground](#foreground) 60 - [Container Identification](#container-identification) 61 - [Name (--name)](#name-name) 62 - [PID Equivalent](#pid-equivalent) 63 - [IPC Settings (--ipc)](#ipc-settings-ipc) 64 - [Network Settings](#network-settings) 65 - [Restart Policies (--restart)](#restart-policies-restart) 66 - [Clean Up (--rm)](#clean-up-rm) 67 - [Runtime Constraints on CPU and Memory](#runtime-constraints-on-cpu-and-memory) 68 - [Runtime Privilege, Linux Capabilities, and LXC Configuration](#runtime-privilege-linux-capabilities-and-lxc-configuration) 69 70 ## Detached vs foreground 71 72 When starting a Docker container, you must first decide if you want to 73 run the container in the background in a "detached" mode or in the 74 default foreground mode: 75 76 -d=false: Detached mode: Run container in the background, print new container id 77 78 ### Detached (-d) 79 80 In detached mode (`-d=true` or just `-d`), all I/O should be done 81 through network connections or shared volumes because the container is 82 no longer listening to the command line where you executed `docker run`. 83 You can reattach to a detached container with `docker` 84 [*attach*](/reference/commandline/cli/#attach). If you choose to run a 85 container in the detached mode, then you cannot use the `--rm` option. 86 87 ### Foreground 88 89 In foreground mode (the default when `-d` is not specified), `docker 90 run` can start the process in the container and attach the console to 91 the process's standard input, output, and standard error. It can even 92 pretend to be a TTY (this is what most command line executables expect) 93 and pass along signals. All of that is configurable: 94 95 -a=[] : Attach to `STDIN`, `STDOUT` and/or `STDERR` 96 -t=false : Allocate a pseudo-tty 97 --sig-proxy=true: Proxify all received signal to the process (non-TTY mode only) 98 -i=false : Keep STDIN open even if not attached 99 100 If you do not specify `-a` then Docker will [attach all standard 101 streams]( https://github.com/docker/docker/blob/ 102 75a7f4d90cde0295bcfb7213004abce8d4779b75/commands.go#L1797). You can 103 specify to which of the three standard streams (`STDIN`, `STDOUT`, 104 `STDERR`) you'd like to connect instead, as in: 105 106 $ docker run -a stdin -a stdout -i -t ubuntu /bin/bash 107 108 For interactive processes (like a shell), you must use `-i -t` together in 109 order to allocate a tty for the container process. `-i -t` is often written `-it` 110 as you'll see in later examples. Specifying `-t` is forbidden when the client 111 standard output is redirected or piped, such as in: 112 `echo test | docker run -i busybox cat`. 113 114 >**Note**: A process running as PID 1 inside a container is treated 115 >specially by Linux: it ignores any signal with the default action. 116 >So, the process will not terminate on `SIGINT` or `SIGTERM` unless it is 117 >coded to do so. 118 119 ## Container identification 120 121 ### Name (--name) 122 123 The operator can identify a container in three ways: 124 125 - UUID long identifier 126 ("f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778") 127 - UUID short identifier ("f78375b1c487") 128 - Name ("evil_ptolemy") 129 130 The UUID identifiers come from the Docker daemon, and if you do not 131 assign a name to the container with `--name` then the daemon will also 132 generate a random string name too. The name can become a handy way to 133 add meaning to a container since you can use this name when defining 134 [*links*](/userguide/dockerlinks) (or any 135 other place you need to identify a container). This works for both 136 background and foreground Docker containers. 137 138 ### PID equivalent 139 140 Finally, to help with automation, you can have Docker write the 141 container ID out to a file of your choosing. This is similar to how some 142 programs might write out their process ID to a file (you've seen them as 143 PID files): 144 145 --cidfile="": Write the container ID to the file 146 147 ### Image[:tag] 148 149 While not strictly a means of identifying a container, you can specify a version of an 150 image you'd like to run the container with by adding `image[:tag]` to the command. For 151 example, `docker run ubuntu:14.04`. 152 153 ### Image[@digest] 154 155 Images using the v2 or later image format have a content-addressable identifier 156 called a digest. As long as the input used to generate the image is unchanged, 157 the digest value is predictable and referenceable. 158 159 ## PID settings (--pid) 160 161 --pid="" : Set the PID (Process) Namespace mode for the container, 162 'host': use the host's PID namespace inside the container 163 164 By default, all containers have the PID namespace enabled. 165 166 PID namespace provides separation of processes. The PID Namespace removes the 167 view of the system processes, and allows process ids to be reused including 168 pid 1. 169 170 In certain cases you want your container to share the host's process namespace, 171 basically allowing processes within the container to see all of the processes 172 on the system. For example, you could build a container with debugging tools 173 like `strace` or `gdb`, but want to use these tools when debugging processes 174 within the container. 175 176 $ docker run --pid=host rhel7 strace -p 1234 177 178 This command would allow you to use `strace` inside the container on pid 1234 on 179 the host. 180 181 ## UTS settings (--uts) 182 183 --uts="" : Set the UTS namespace mode for the container, 184 'host': use the host's UTS namespace inside the container 185 186 The UTS namespace is for setting the hostname and the domain that is visible 187 to running processes in that namespace. By default, all containers, including 188 those with `--net=host`, have their own UTS namespace. The `host` setting will 189 result in the container using the same UTS namespace as the host. 190 191 You may wish to share the UTS namespace with the host if you would like the 192 hostname of the container to change as the hostname of the host changes. A 193 more advanced use case would be changing the host's hostname from a container. 194 195 > **Note**: `--uts="host"` gives the container full access to change the 196 > hostname of the host and is therefore considered insecure. 197 198 ## IPC settings (--ipc) 199 200 --ipc="" : Set the IPC mode for the container, 201 'container:<name|id>': reuses another container's IPC namespace 202 'host': use the host's IPC namespace inside the container 203 204 By default, all containers have the IPC namespace enabled. 205 206 IPC (POSIX/SysV IPC) namespace provides separation of named shared memory 207 segments, semaphores and message queues. 208 209 Shared memory segments are used to accelerate inter-process communication at 210 memory speed, rather than through pipes or through the network stack. Shared 211 memory is commonly used by databases and custom-built (typically C/OpenMPI, 212 C++/using boost libraries) high performance applications for scientific 213 computing and financial services industries. If these types of applications 214 are broken into multiple containers, you might need to share the IPC mechanisms 215 of the containers. 216 217 ## Network settings 218 219 --dns=[] : Set custom dns servers for the container 220 --net="bridge" : Set the Network mode for the container 221 'bridge': creates a new network stack for the container on the docker bridge 222 'none': no networking for this container 223 'container:<name|id>': reuses another container network stack 224 'host': use the host network stack inside the container 225 --add-host="" : Add a line to /etc/hosts (host:IP) 226 --mac-address="" : Sets the container's Ethernet device's MAC address 227 228 By default, all containers have networking enabled and they can make any 229 outgoing connections. The operator can completely disable networking 230 with `docker run --net none` which disables all incoming and outgoing 231 networking. In cases like this, you would perform I/O through files or 232 `STDIN` and `STDOUT` only. 233 234 Your container will use the same DNS servers as the host by default, but 235 you can override this with `--dns`. 236 237 By default, the MAC address is generated using the IP address allocated to the 238 container. You can set the container's MAC address explicitly by providing a 239 MAC address via the `--mac-address` parameter (format:`12:34:56:78:9a:bc`). 240 241 Supported networking modes are: 242 243 <table> 244 <thead> 245 <tr> 246 <th class="no-wrap">Mode</th> 247 <th>Description</th> 248 </tr> 249 </thead> 250 <tbody> 251 <tr> 252 <td class="no-wrap"><strong>none</strong></td> 253 <td> 254 No networking in the container. 255 </td> 256 </tr> 257 <tr> 258 <td class="no-wrap"><strong>bridge</strong> (default)</td> 259 <td> 260 Connect the container to the bridge via veth interfaces. 261 </td> 262 </tr> 263 <tr> 264 <td class="no-wrap"><strong>host</strong></td> 265 <td> 266 Use the host's network stack inside the container. 267 </td> 268 </tr> 269 <tr> 270 <td class="no-wrap"><strong>container</strong>:<name|id></td> 271 <td> 272 Use the network stack of another container, specified via 273 its *name* or *id*. 274 </td> 275 </tr> 276 </tbody> 277 </table> 278 279 #### Mode: none 280 281 With the networking mode set to `none` a container will not have a 282 access to any external routes. The container will still have a 283 `loopback` interface enabled in the container but it does not have any 284 routes to external traffic. 285 286 #### Mode: bridge 287 288 With the networking mode set to `bridge` a container will use docker's 289 default networking setup. A bridge is setup on the host, commonly named 290 `docker0`, and a pair of `veth` interfaces will be created for the 291 container. One side of the `veth` pair will remain on the host attached 292 to the bridge while the other side of the pair will be placed inside the 293 container's namespaces in addition to the `loopback` interface. An IP 294 address will be allocated for containers on the bridge's network and 295 traffic will be routed though this bridge to the container. 296 297 #### Mode: host 298 299 With the networking mode set to `host` a container will share the host's 300 network stack and all interfaces from the host will be available to the 301 container. The container's hostname will match the hostname on the host 302 system. Publishing ports and linking to other containers will not work 303 when sharing the host's network stack. Note that `--add-host` `--hostname` 304 `--dns` `--dns-search` and `--mac-address` is invalid in `host` netmode. 305 306 Compared to the default `bridge` mode, the `host` mode gives *significantly* 307 better networking performance since it uses the host's native networking stack 308 whereas the bridge has to go through one level of virtualization through the 309 docker daemon. It is recommended to run containers in this mode when their 310 networking performance is critical, for example, a production Load Balancer 311 or a High Performance Web Server. 312 313 > **Note**: `--net="host"` gives the container full access to local system 314 > services such as D-bus and is therefore considered insecure. 315 316 #### Mode: container 317 318 With the networking mode set to `container` a container will share the 319 network stack of another container. The other container's name must be 320 provided in the format of `--net container:<name|id>`. Note that `--add-host` 321 `--hostname` `--dns` `--dns-search` and `--mac-address` is invalid 322 in `container` netmode. 323 324 Example running a Redis container with Redis binding to `localhost` then 325 running the `redis-cli` command and connecting to the Redis server over the 326 `localhost` interface. 327 328 $ docker run -d --name redis example/redis --bind 127.0.0.1 329 $ # use the redis container's network stack to access localhost 330 $ docker run --rm -it --net container:redis example/redis-cli -h 127.0.0.1 331 332 ### Managing /etc/hosts 333 334 Your container will have lines in `/etc/hosts` which define the hostname of the 335 container itself as well as `localhost` and a few other common things. The 336 `--add-host` flag can be used to add additional lines to `/etc/hosts`. 337 338 $ docker run -it --add-host db-static:86.75.30.9 ubuntu cat /etc/hosts 339 172.17.0.22 09d03f76bf2c 340 fe00::0 ip6-localnet 341 ff00::0 ip6-mcastprefix 342 ff02::1 ip6-allnodes 343 ff02::2 ip6-allrouters 344 127.0.0.1 localhost 345 ::1 localhost ip6-localhost ip6-loopback 346 86.75.30.9 db-static 347 348 ## Restart policies (--restart) 349 350 Using the `--restart` flag on Docker run you can specify a restart policy for 351 how a container should or should not be restarted on exit. 352 353 When a restart policy is active on a container, it will be shown as either `Up` 354 or `Restarting` in [`docker ps`](/reference/commandline/cli/#ps). It can also be 355 useful to use [`docker events`](/reference/commandline/cli/#events) to see the 356 restart policy in effect. 357 358 Docker supports the following restart policies: 359 360 <table> 361 <thead> 362 <tr> 363 <th>Policy</th> 364 <th>Result</th> 365 </tr> 366 </thead> 367 <tbody> 368 <tr> 369 <td><strong>no</strong></td> 370 <td> 371 Do not automatically restart the container when it exits. This is the 372 default. 373 </td> 374 </tr> 375 <tr> 376 <td> 377 <span style="white-space: nowrap"> 378 <strong>on-failure</strong>[:max-retries] 379 </span> 380 </td> 381 <td> 382 Restart only if the container exits with a non-zero exit status. 383 Optionally, limit the number of restart retries the Docker 384 daemon attempts. 385 </td> 386 </tr> 387 <tr> 388 <td><strong>always</strong></td> 389 <td> 390 Always restart the container regardless of the exit status. 391 When you specify always, the Docker daemon will try to restart 392 the container indefinitely. 393 </td> 394 </tr> 395 </tbody> 396 </table> 397 398 An ever increasing delay (double the previous delay, starting at 100 399 milliseconds) is added before each restart to prevent flooding the server. 400 This means the daemon will wait for 100 ms, then 200 ms, 400, 800, 1600, 401 and so on until either the `on-failure` limit is hit, or when you `docker stop` 402 or `docker rm -f` the container. 403 404 If a container is successfully restarted (the container is started and runs 405 for at least 10 seconds), the delay is reset to its default value of 100 ms. 406 407 You can specify the maximum amount of times Docker will try to restart the 408 container when using the **on-failure** policy. The default is that Docker 409 will try forever to restart the container. The number of (attempted) restarts 410 for a container can be obtained via [`docker inspect`]( 411 /reference/commandline/cli/#inspect). For example, to get the number of restarts 412 for container "my-container"; 413 414 $ docker inspect -f "{{ .RestartCount }}" my-container 415 # 2 416 417 Or, to get the last time the container was (re)started; 418 419 $ docker inspect -f "{{ .State.StartedAt }}" my-container 420 # 2015-03-04T23:47:07.691840179Z 421 422 You cannot set any restart policy in combination with 423 ["clean up (--rm)"](#clean-up-rm). Setting both `--restart` and `--rm` 424 results in an error. 425 426 ###Examples 427 428 $ docker run --restart=always redis 429 430 This will run the `redis` container with a restart policy of **always** 431 so that if the container exits, Docker will restart it. 432 433 $ docker run --restart=on-failure:10 redis 434 435 This will run the `redis` container with a restart policy of **on-failure** 436 and a maximum restart count of 10. If the `redis` container exits with a 437 non-zero exit status more than 10 times in a row Docker will abort trying to 438 restart the container. Providing a maximum restart limit is only valid for the 439 **on-failure** policy. 440 441 ## Clean up (--rm) 442 443 By default a container's file system persists even after the container 444 exits. This makes debugging a lot easier (since you can inspect the 445 final state) and you retain all your data by default. But if you are 446 running short-term **foreground** processes, these container file 447 systems can really pile up. If instead you'd like Docker to 448 **automatically clean up the container and remove the file system when 449 the container exits**, you can add the `--rm` flag: 450 451 --rm=false: Automatically remove the container when it exits (incompatible with -d) 452 453 ## Security configuration 454 --security-opt="label:user:USER" : Set the label user for the container 455 --security-opt="label:role:ROLE" : Set the label role for the container 456 --security-opt="label:type:TYPE" : Set the label type for the container 457 --security-opt="label:level:LEVEL" : Set the label level for the container 458 --security-opt="label:disable" : Turn off label confinement for the container 459 --security-opt="apparmor:PROFILE" : Set the apparmor profile to be applied 460 to the container 461 462 You can override the default labeling scheme for each container by specifying 463 the `--security-opt` flag. For example, you can specify the MCS/MLS level, a 464 requirement for MLS systems. Specifying the level in the following command 465 allows you to share the same content between containers. 466 467 $ docker run --security-opt label:level:s0:c100,c200 -i -t fedora bash 468 469 An MLS example might be: 470 471 $ docker run --security-opt label:level:TopSecret -i -t rhel7 bash 472 473 To disable the security labeling for this container versus running with the 474 `--permissive` flag, use the following command: 475 476 $ docker run --security-opt label:disable -i -t fedora bash 477 478 If you want a tighter security policy on the processes within a container, 479 you can specify an alternate type for the container. You could run a container 480 that is only allowed to listen on Apache ports by executing the following 481 command: 482 483 $ docker run --security-opt label:type:svirt_apache_t -i -t centos bash 484 485 Note: 486 487 You would have to write policy defining a `svirt_apache_t` type. 488 489 ## Specifying custom cgroups 490 491 Using the `--cgroup-parent` flag, you can pass a specific cgroup to run a 492 container in. This allows you to create and manage cgroups on their own. You can 493 define custom resources for those cgroups and put containers under a common 494 parent group. 495 496 ## Runtime constraints on resources 497 498 The operator can also adjust the performance parameters of the 499 container: 500 501 -m, --memory="": Memory limit (format: <number><optional unit>, where unit = b, k, m or g) 502 -memory-swap="": Total memory limit (memory + swap, format: <number><optional unit>, where unit = b, k, m or g) 503 -c, --cpu-shares=0: CPU shares (relative weight) 504 --cpu-period=0: Limit the CPU CFS (Completely Fair Scheduler) period 505 --cpuset-cpus="": CPUs in which to allow execution (0-3, 0,1) 506 --cpuset-mems="": Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. 507 --cpu-quota=0: Limit the CPU CFS (Completely Fair Scheduler) quota 508 --blkio-weight=0: Block IO weight (relative weight) accepts a weight value between 10 and 1000. 509 --oom-kill-disable=true|false: Whether to disable OOM Killer for the container or not. 510 511 ### Memory constraints 512 513 We have four ways to set memory usage: 514 515 <table> 516 <thead> 517 <tr> 518 <th>Option</th> 519 <th>Result</th> 520 </tr> 521 </thead> 522 <tbody> 523 <tr> 524 <td class="no-wrap"> 525 <strong>memory=inf, memory-swap=inf</strong> (default) 526 </td> 527 <td> 528 There is no memory limit for the container. The container can use 529 as much memory as needed. 530 </td> 531 </tr> 532 <tr> 533 <td class="no-wrap"><strong>memory=L<inf, memory-swap=inf</strong></td> 534 <td> 535 (specify memory and set memory-swap as <code>-1</code>) The container is 536 not allowed to use more than L bytes of memory, but can use as much swap 537 as is needed (if the host supports swap memory). 538 </td> 539 </tr> 540 <tr> 541 <td class="no-wrap"><strong>memory=L<inf, memory-swap=2*L</strong></td> 542 <td> 543 (specify memory without memory-swap) The container is not allowed to 544 use more than L bytes of memory, swap *plus* memory usage is double 545 of that. 546 </td> 547 </tr> 548 <tr> 549 <td class="no-wrap"> 550 <strong>memory=L<inf, memory-swap=S<inf, L<=S</strong> 551 </td> 552 <td> 553 (specify both memory and memory-swap) The container is not allowed to 554 use more than L bytes of memory, swap *plus* memory usage is limited 555 by S. 556 </td> 557 </tr> 558 </tbody> 559 </table> 560 561 Examples: 562 563 $ docker run -ti ubuntu:14.04 /bin/bash 564 565 We set nothing about memory, this means the processes in the container can use 566 as much memory and swap memory as they need. 567 568 $ docker run -ti -m 300M --memory-swap -1 ubuntu:14.04 /bin/bash 569 570 We set memory limit and disabled swap memory limit, this means the processes in 571 the container can use 300M memory and as much swap memory as they need (if the 572 host supports swap memory). 573 574 $ docker run -ti -m 300M ubuntu:14.04 /bin/bash 575 576 We set memory limit only, this means the processes in the container can use 577 300M memory and 300M swap memory, by default, the total virtual memory size 578 (--memory-swap) will be set as double of memory, in this case, memory + swap 579 would be 2*300M, so processes can use 300M swap memory as well. 580 581 $ docker run -ti -m 300M --memory-swap 1G ubuntu:14.04 /bin/bash 582 583 We set both memory and swap memory, so the processes in the container can use 584 300M memory and 700M swap memory. 585 586 By default, Docker kills processes in a container if an out-of-memory (OOM) 587 error occurs. To change this behaviour, use the `--oom-kill-disable` option. 588 Only disable the OOM killer on containers where you have also set the 589 `-m/--memory` option. If the `-m` flag is not set, this can result in the host 590 running out of memory and require killing the host's system processes to free 591 memory. 592 593 Examples: 594 595 The following example limits the memory to 100M and disables the OOM killer for 596 this container: 597 598 $ docker run -ti -m 100M --oom-kill-disable ubuntu:14.04 /bin/bash 599 600 The following example, illustrates a dangerous way to use the flag: 601 602 $ docker run -ti --oom-kill-disable ubuntu:14.04 /bin/bash 603 604 The container has unlimited memory which can cause the host to run out memory 605 and require killing system processes to free memory. 606 607 ### CPU share constraint 608 609 By default, all containers get the same proportion of CPU cycles. This proportion 610 can be modified by changing the container's CPU share weighting relative 611 to the weighting of all other running containers. 612 613 To modify the proportion from the default of 1024, use the `-c` or `--cpu-shares` 614 flag to set the weighting to 2 or higher. 615 616 The proportion will only apply when CPU-intensive processes are running. 617 When tasks in one container are idle, other containers can use the 618 left-over CPU time. The actual amount of CPU time will vary depending on 619 the number of containers running on the system. 620 621 For example, consider three containers, one has a cpu-share of 1024 and 622 two others have a cpu-share setting of 512. When processes in all three 623 containers attempt to use 100% of CPU, the first container would receive 624 50% of the total CPU time. If you add a fourth container with a cpu-share 625 of 1024, the first container only gets 33% of the CPU. The remaining containers 626 receive 16.5%, 16.5% and 33% of the CPU. 627 628 On a multi-core system, the shares of CPU time are distributed over all CPU 629 cores. Even if a container is limited to less than 100% of CPU time, it can 630 use 100% of each individual CPU core. 631 632 For example, consider a system with more than three cores. If you start one 633 container `{C0}` with `-c=512` running one process, and another container 634 `{C1}` with `-c=1024` running two processes, this can result in the following 635 division of CPU shares: 636 637 PID container CPU CPU share 638 100 {C0} 0 100% of CPU0 639 101 {C1} 1 100% of CPU1 640 102 {C1} 2 100% of CPU2 641 642 ### CPU period constraint 643 644 The default CPU CFS (Completely Fair Scheduler) period is 100ms. We can use 645 `--cpu-period` to set the period of CPUs to limit the container's CPU usage. 646 And usually `--cpu-period` should work with `--cpu-quota`. 647 648 Examples: 649 650 $ docker run -ti --cpu-period=50000 --cpu-quota=25000 ubuntu:14.04 /bin/bash 651 652 If there is 1 CPU, this means the container can get 50% CPU worth of run-time every 50ms. 653 654 For more information, see the [CFS documentation on bandwidth limiting](https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt). 655 656 ### Cpuset constraint 657 658 We can set cpus in which to allow execution for containers. 659 660 Examples: 661 662 $ docker run -ti --cpuset-cpus="1,3" ubuntu:14.04 /bin/bash 663 664 This means processes in container can be executed on cpu 1 and cpu 3. 665 666 $ docker run -ti --cpuset-cpus="0-2" ubuntu:14.04 /bin/bash 667 668 This means processes in container can be executed on cpu 0, cpu 1 and cpu 2. 669 670 We can set mems in which to allow execution for containers. Only effective 671 on NUMA systems. 672 673 Examples: 674 675 $ docker run -ti --cpuset-mems="1,3" ubuntu:14.04 /bin/bash 676 677 This example restricts the processes in the container to only use memory from 678 memory nodes 1 and 3. 679 680 $ docker run -ti --cpuset-mems="0-2" ubuntu:14.04 /bin/bash 681 682 This example restricts the processes in the container to only use memory from 683 memory nodes 0, 1 and 2. 684 685 ### CPU quota constraint 686 687 The `--cpu-quota` flag limits the container's CPU usage. The default 0 value 688 allows the container to take 100% of a CPU resource (1 CPU). The CFS (Completely Fair 689 Scheduler) handles resource allocation for executing processes and is default 690 Linux Scheduler used by the kernel. Set this value to 50000 to limit the container 691 to 50% of a CPU resource. For multiple CPUs, adjust the `--cpu-quota` as necessary. 692 For more information, see the [CFS documentation on bandwidth limiting](https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt). 693 694 ### Block IO bandwidth (Blkio) constraint 695 696 By default, all containers get the same proportion of block IO bandwidth 697 (blkio). This proportion is 500. To modify this proportion, change the 698 container's blkio weight relative to the weighting of all other running 699 containers using the `--blkio-weight` flag. 700 701 The `--blkio-weight` flag can set the weighting to a value between 10 to 1000. 702 For example, the commands below create two containers with different blkio 703 weight: 704 705 $ docker run -ti --name c1 --blkio-weight 300 ubuntu:14.04 /bin/bash 706 $ docker run -ti --name c2 --blkio-weight 600 ubuntu:14.04 /bin/bash 707 708 If you do block IO in the two containers at the same time, by, for example: 709 710 $ time dd if=/mnt/zerofile of=test.out bs=1M count=1024 oflag=direct 711 712 You'll find that the proportion of time is the same as the proportion of blkio 713 weights of the two containers. 714 715 > **Note:** The blkio weight setting is only available for direct IO. Buffered IO 716 > is not currently supported. 717 718 ## Runtime privilege, Linux capabilities, and LXC configuration 719 720 --cap-add: Add Linux capabilities 721 --cap-drop: Drop Linux capabilities 722 --privileged=false: Give extended privileges to this container 723 --device=[]: Allows you to run devices inside the container without the --privileged flag. 724 --lxc-conf=[]: Add custom lxc options 725 726 By default, Docker containers are "unprivileged" and cannot, for 727 example, run a Docker daemon inside a Docker container. This is because 728 by default a container is not allowed to access any devices, but a 729 "privileged" container is given access to all devices (see [lxc-template.go]( 730 https://github.com/docker/docker/blob/master/daemon/execdriver/lxc/lxc_template.go) 731 and documentation on [cgroups devices]( 732 https://www.kernel.org/doc/Documentation/cgroups/devices.txt)). 733 734 When the operator executes `docker run --privileged`, Docker will enable 735 to access to all devices on the host as well as set some configuration 736 in AppArmor or SELinux to allow the container nearly all the same access to the 737 host as processes running outside containers on the host. Additional 738 information about running with `--privileged` is available on the 739 [Docker Blog](http://blog.docker.com/2013/09/docker-can-now-run-within-docker/). 740 741 If you want to limit access to a specific device or devices you can use 742 the `--device` flag. It allows you to specify one or more devices that 743 will be accessible within the container. 744 745 $ docker run --device=/dev/snd:/dev/snd ... 746 747 By default, the container will be able to `read`, `write`, and `mknod` these devices. 748 This can be overridden using a third `:rwm` set of options to each `--device` flag: 749 750 $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc 751 752 Command (m for help): q 753 $ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk /dev/xvdc 754 You will not be able to write the partition table. 755 756 Command (m for help): q 757 758 $ docker run --device=/dev/sda:/dev/xvdc:w --rm -it ubuntu fdisk /dev/xvdc 759 crash.... 760 761 $ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc 762 fdisk: unable to open /dev/xvdc: Operation not permitted 763 764 In addition to `--privileged`, the operator can have fine grain control over the 765 capabilities using `--cap-add` and `--cap-drop`. By default, Docker has a default 766 list of capabilities that are kept. The following table lists the Linux capability options which can be added or dropped. 767 768 | Capability Key | Capability Description | 769 | :----------------- | :---------------| :-------------------- | 770 | SETPCAP | Modify process capabilities. | 771 | SYS_MODULE| Load and unload kernel modules. | 772 | SYS_RAWIO | Perform I/O port operations (iopl(2) and ioperm(2)). | 773 | SYS_PACCT | Use acct(2), switch process accounting on or off. | 774 | SYS_ADMIN | Perform a range of system administration operations. | 775 | SYS_NICE | Raise process nice value (nice(2), setpriority(2)) and change the nice value for arbitrary processes. | 776 | SYS_RESOURCE | Override resource Limits. | 777 | SYS_TIME | Set system clock (settimeofday(2), stime(2), adjtimex(2)); set real-time (hardware) clock. | 778 | SYS_TTY_CONFIG | Use vhangup(2); employ various privileged ioctl(2) operations on virtual terminals. | 779 | MKNOD | Create special files using mknod(2). | 780 | AUDIT_WRITE | Write records to kernel auditing log. | 781 | AUDIT_CONTROL | Enable and disable kernel auditing; change auditing filter rules; retrieve auditing status and filtering rules. | 782 | MAC_OVERRIDE | Allow MAC configuration or state changes. Implemented for the Smack LSM. | 783 | MAC_ADMIN | Override Mandatory Access Control (MAC). Implemented for the Smack Linux Security Module (LSM). | 784 | NET_ADMIN | Perform various network-related operations. | 785 | SYSLOG | Perform privileged syslog(2) operations. | 786 | CHOWN | Make arbitrary changes to file UIDs and GIDs (see chown(2)). | 787 | NET_RAW | Use RAW and PACKET sockets. | 788 | DAC_OVERRIDE | Bypass file read, write, and execute permission checks. | 789 | FOWNER | Bypass permission checks on operations that normally require the file system UID of the process to match the UID of the file. | 790 | DAC_READ_SEARCH | Bypass file read permission checks and directory read and execute permission checks. | 791 | FSETID | Don't clear set-user-ID and set-group-ID permission bits when a file is modified. | 792 | KILL | Bypass permission checks for sending signals. | 793 | SETGID | Make arbitrary manipulations of process GIDs and supplementary GID list. | 794 | SETUID | Make arbitrary manipulations of process UIDs. | 795 | LINUX_IMMUTABLE | Set the FS_APPEND_FL and FS_IMMUTABLE_FL i-node flags. | 796 | NET_BIND_SERVICE | Bind a socket to internet domain privileged ports (port numbers less than 1024). | 797 | NET_BROADCAST | Make socket broadcasts, and listen to multicasts. | 798 | IPC_LOCK | Lock memory (mlock(2), mlockall(2), mmap(2), shmctl(2)). | 799 | IPC_OWNER | Bypass permission checks for operations on System V IPC objects. | 800 | SYS_CHROOT | Use chroot(2), change root directory. | 801 | SYS_PTRACE | Trace arbitrary processes using ptrace(2). | 802 | SYS_BOOT | Use reboot(2) and kexec_load(2), reboot and load a new kernel for later execution. | 803 | LEASE | Establish leases on arbitrary files (see fcntl(2)). | 804 | SETFCAP | Set file capabilities.| 805 | WAKE_ALARM | Trigger something that will wake up the system. | 806 | BLOCK_SUSPEND | Employ features that can block system suspend. | 807 808 Further reference information is available on the [capabilities(7) - Linux man page](http://linux.die.net/man/7/capabilities) 809 810 Both flags support the value `all`, so if the 811 operator wants to have all capabilities but `MKNOD` they could use: 812 813 $ docker run --cap-add=ALL --cap-drop=MKNOD ... 814 815 For interacting with the network stack, instead of using `--privileged` they 816 should use `--cap-add=NET_ADMIN` to modify the network interfaces. 817 818 $ docker run -t -i --rm ubuntu:14.04 ip link add dummy0 type dummy 819 RTNETLINK answers: Operation not permitted 820 $ docker run -t -i --rm --cap-add=NET_ADMIN ubuntu:14.04 ip link add dummy0 type dummy 821 822 To mount a FUSE based filesystem, you need to combine both `--cap-add` and 823 `--device`: 824 825 $ docker run --rm -it --cap-add SYS_ADMIN sshfs sshfs sven@10.10.10.20:/home/sven /mnt 826 fuse: failed to open /dev/fuse: Operation not permitted 827 $ docker run --rm -it --device /dev/fuse sshfs sshfs sven@10.10.10.20:/home/sven /mnt 828 fusermount: mount failed: Operation not permitted 829 $ docker run --rm -it --cap-add SYS_ADMIN --device /dev/fuse sshfs 830 # sshfs sven@10.10.10.20:/home/sven /mnt 831 The authenticity of host '10.10.10.20 (10.10.10.20)' can't be established. 832 ECDSA key fingerprint is 25:34:85:75:25:b0:17:46:05:19:04:93:b5:dd:5f:c6. 833 Are you sure you want to continue connecting (yes/no)? yes 834 sven@10.10.10.20's password: 835 root@30aa0cfaf1b5:/# ls -la /mnt/src/docker 836 total 1516 837 drwxrwxr-x 1 1000 1000 4096 Dec 4 06:08 . 838 drwxrwxr-x 1 1000 1000 4096 Dec 4 11:46 .. 839 -rw-rw-r-- 1 1000 1000 16 Oct 8 00:09 .dockerignore 840 -rwxrwxr-x 1 1000 1000 464 Oct 8 00:09 .drone.yml 841 drwxrwxr-x 1 1000 1000 4096 Dec 4 06:11 .git 842 -rw-rw-r-- 1 1000 1000 461 Dec 4 06:08 .gitignore 843 .... 844 845 846 If the Docker daemon was started using the `lxc` exec-driver 847 (`docker -d --exec-driver=lxc`) then the operator can also specify LXC options 848 using one or more `--lxc-conf` parameters. These can be new parameters or 849 override existing parameters from the [lxc-template.go]( 850 https://github.com/docker/docker/blob/master/daemon/execdriver/lxc/lxc_template.go). 851 Note that in the future, a given host's docker daemon may not use LXC, so this 852 is an implementation-specific configuration meant for operators already 853 familiar with using LXC directly. 854 855 > **Note:** 856 > If you use `--lxc-conf` to modify a container's configuration which is also 857 > managed by the Docker daemon, then the Docker daemon will not know about this 858 > modification, and you will need to manage any conflicts yourself. For example, 859 > you can use `--lxc-conf` to set a container's IP address, but this will not be 860 > reflected in the `/etc/hosts` file. 861 862 ## Logging drivers (--log-driver) 863 864 You can specify a different logging driver for the container than for the daemon. 865 866 #### Logging driver: none 867 868 Disables any logging for the container. `docker logs` won't be available with 869 this driver. 870 871 #### Logging driver: json-file 872 873 Default logging driver for Docker. Writes JSON messages to file. `docker logs` 874 command is available only for this logging driver 875 876 #### Logging driver: syslog 877 878 Syslog logging driver for Docker. Writes log messages to syslog. `docker logs` 879 command is not available for this logging driver 880 881 #### Logging driver: journald 882 883 Journald logging driver for Docker. Writes log messages to journald; the container id will be stored in the journal's `CONTAINER_ID` field. `docker logs` command is not available for this logging driver. For detailed information on working with this logging driver, see [the journald logging driver](reference/logging/journald) reference documentation. 884 885 #### Log Opts : 886 887 Logging options for configuring a log driver. The following log options are supported: [none] 888 889 ## Overriding Dockerfile image defaults 890 891 When a developer builds an image from a [*Dockerfile*](/reference/builder) 892 or when she commits it, the developer can set a number of default parameters 893 that take effect when the image starts up as a container. 894 895 Four of the Dockerfile commands cannot be overridden at runtime: `FROM`, 896 `MAINTAINER`, `RUN`, and `ADD`. Everything else has a corresponding override 897 in `docker run`. We'll go through what the developer might have set in each 898 Dockerfile instruction and how the operator can override that setting. 899 900 - [CMD (Default Command or Options)](#cmd-default-command-or-options) 901 - [ENTRYPOINT (Default Command to Execute at Runtime)]( 902 #entrypoint-default-command-to-execute-at-runtime) 903 - [EXPOSE (Incoming Ports)](#expose-incoming-ports) 904 - [ENV (Environment Variables)](#env-environment-variables) 905 - [VOLUME (Shared Filesystems)](#volume-shared-filesystems) 906 - [USER](#user) 907 - [WORKDIR](#workdir) 908 909 ## CMD (default command or options) 910 911 Recall the optional `COMMAND` in the Docker 912 commandline: 913 914 $ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...] 915 916 This command is optional because the person who created the `IMAGE` may 917 have already provided a default `COMMAND` using the Dockerfile `CMD` 918 instruction. As the operator (the person running a container from the 919 image), you can override that `CMD` instruction just by specifying a new 920 `COMMAND`. 921 922 If the image also specifies an `ENTRYPOINT` then the `CMD` or `COMMAND` 923 get appended as arguments to the `ENTRYPOINT`. 924 925 ## ENTRYPOINT (default command to execute at runtime) 926 927 --entrypoint="": Overwrite the default entrypoint set by the image 928 929 The `ENTRYPOINT` of an image is similar to a `COMMAND` because it 930 specifies what executable to run when the container starts, but it is 931 (purposely) more difficult to override. The `ENTRYPOINT` gives a 932 container its default nature or behavior, so that when you set an 933 `ENTRYPOINT` you can run the container *as if it were that binary*, 934 complete with default options, and you can pass in more options via the 935 `COMMAND`. But, sometimes an operator may want to run something else 936 inside the container, so you can override the default `ENTRYPOINT` at 937 runtime by using a string to specify the new `ENTRYPOINT`. Here is an 938 example of how to run a shell in a container that has been set up to 939 automatically run something else (like `/usr/bin/redis-server`): 940 941 $ docker run -i -t --entrypoint /bin/bash example/redis 942 943 or two examples of how to pass more parameters to that ENTRYPOINT: 944 945 $ docker run -i -t --entrypoint /bin/bash example/redis -c ls -l 946 $ docker run -i -t --entrypoint /usr/bin/redis-cli example/redis --help 947 948 ## EXPOSE (incoming ports) 949 950 The Dockerfile doesn't give much control over networking, only providing 951 the `EXPOSE` instruction to give a hint to the operator about what 952 incoming ports might provide services. The following options work with 953 or override the Dockerfile's exposed defaults: 954 955 --expose=[]: Expose a port or a range of ports from the container 956 without publishing it to your host 957 -P=false : Publish all exposed ports to the host interfaces 958 -p=[] : Publish a container᾿s port or a range of ports to the host 959 format: ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort 960 Both hostPort and containerPort can be specified as a range of ports. 961 When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. (e.g., `-p 1234-1236:1234-1236/tcp`) 962 (use 'docker port' to see the actual mapping) 963 --link="" : Add link to another container (<name or id>:alias or <name or id>) 964 965 As mentioned previously, `EXPOSE` (and `--expose`) makes ports available 966 **in** a container for incoming connections. The port number on the 967 inside of the container (where the service listens) does not need to be 968 the same number as the port exposed on the outside of the container 969 (where clients connect), so inside the container you might have an HTTP 970 service listening on port 80 (and so you `EXPOSE 80` in the Dockerfile), 971 but outside the container the port might be 42800. 972 973 To help a new client container reach the server container's internal 974 port operator `--expose`'d by the operator or `EXPOSE`'d by the 975 developer, the operator has three choices: start the server container 976 with `-P` or `-p,` or start the client container with `--link`. 977 978 If the operator uses `-P` or `-p` then Docker will make the exposed port 979 accessible on the host and the ports will be available to any client that can 980 reach the host. When using `-P`, Docker will bind the exposed port to a random 981 port on the host within an *ephemeral port range* defined by 982 `/proc/sys/net/ipv4/ip_local_port_range`. To find the mapping between the host 983 ports and the exposed ports, use `docker port`. 984 985 If the operator uses `--link` when starting the new client container, 986 then the client container can access the exposed port via a private 987 networking interface. Docker will set some environment variables in the 988 client container to help indicate which interface and port to use. 989 990 ## ENV (environment variables) 991 992 When a new container is created, Docker will set the following environment 993 variables automatically: 994 995 <table> 996 <tr> 997 <th>Variable</th> 998 <th>Value</th> 999 </tr> 1000 <tr> 1001 <td><code>HOME</code></td> 1002 <td> 1003 Set based on the value of <code>USER</code> 1004 </td> 1005 </tr> 1006 <tr> 1007 <td><code>HOSTNAME</code></td> 1008 <td> 1009 The hostname associated with the container 1010 </td> 1011 </tr> 1012 <tr> 1013 <td><code>PATH</code></td> 1014 <td> 1015 Includes popular directories, such as :<br> 1016 <code>/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin</code> 1017 </td> 1018 <tr> 1019 <td><code>TERM</code></td> 1020 <td><code>xterm</code> if the container is allocated a psuedo-TTY</td> 1021 </tr> 1022 </table> 1023 1024 The container may also include environment variables defined 1025 as a result of the container being linked with another container. See 1026 the [*Container Links*](/userguide/dockerlinks/#container-linking) 1027 section for more details. 1028 1029 Additionally, the operator can **set any environment variable** in the 1030 container by using one or more `-e` flags, even overriding those mentioned 1031 above, or already defined by the developer with a Dockerfile `ENV`: 1032 1033 $ docker run -e "deep=purple" --rm ubuntu /bin/bash -c export 1034 declare -x HOME="/" 1035 declare -x HOSTNAME="85bc26a0e200" 1036 declare -x OLDPWD 1037 declare -x PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 1038 declare -x PWD="/" 1039 declare -x SHLVL="1" 1040 declare -x container="lxc" 1041 declare -x deep="purple" 1042 1043 Similarly the operator can set the **hostname** with `-h`. 1044 1045 `--link <name or id>:alias` also sets environment variables, using the *alias* string to 1046 define environment variables within the container that give the IP and PORT 1047 information for connecting to the service container. Let's imagine we have a 1048 container running Redis: 1049 1050 # Start the service container, named redis-name 1051 $ docker run -d --name redis-name dockerfiles/redis 1052 4241164edf6f5aca5b0e9e4c9eccd899b0b8080c64c0cd26efe02166c73208f3 1053 1054 # The redis-name container exposed port 6379 1055 $ docker ps 1056 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 1057 4241164edf6f $ dockerfiles/redis:latest /redis-stable/src/re 5 seconds ago Up 4 seconds 6379/tcp redis-name 1058 1059 # Note that there are no public ports exposed since we didn᾿t use -p or -P 1060 $ docker port 4241164edf6f 6379 1061 2014/01/25 00:55:38 Error: No public port '6379' published for 4241164edf6f 1062 1063 Yet we can get information about the Redis container's exposed ports 1064 with `--link`. Choose an alias that will form a 1065 valid environment variable! 1066 1067 $ docker run --rm --link redis-name:redis_alias --entrypoint /bin/bash dockerfiles/redis -c export 1068 declare -x HOME="/" 1069 declare -x HOSTNAME="acda7f7b1cdc" 1070 declare -x OLDPWD 1071 declare -x PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 1072 declare -x PWD="/" 1073 declare -x REDIS_ALIAS_NAME="/distracted_wright/redis" 1074 declare -x REDIS_ALIAS_PORT="tcp://172.17.0.32:6379" 1075 declare -x REDIS_ALIAS_PORT_6379_TCP="tcp://172.17.0.32:6379" 1076 declare -x REDIS_ALIAS_PORT_6379_TCP_ADDR="172.17.0.32" 1077 declare -x REDIS_ALIAS_PORT_6379_TCP_PORT="6379" 1078 declare -x REDIS_ALIAS_PORT_6379_TCP_PROTO="tcp" 1079 declare -x SHLVL="1" 1080 declare -x container="lxc" 1081 1082 And we can use that information to connect from another container as a client: 1083 1084 $ docker run -i -t --rm --link redis-name:redis_alias --entrypoint /bin/bash dockerfiles/redis -c '/redis-stable/src/redis-cli -h $REDIS_ALIAS_PORT_6379_TCP_ADDR -p $REDIS_ALIAS_PORT_6379_TCP_PORT' 1085 172.17.0.32:6379> 1086 1087 Docker will also map the private IP address to the alias of a linked 1088 container by inserting an entry into `/etc/hosts`. You can use this 1089 mechanism to communicate with a linked container by its alias: 1090 1091 $ docker run -d --name servicename busybox sleep 30 1092 $ docker run -i -t --link servicename:servicealias busybox ping -c 1 servicealias 1093 1094 If you restart the source container (`servicename` in this case), the recipient 1095 container's `/etc/hosts` entry will be automatically updated. 1096 1097 > **Note**: 1098 > Unlike host entries in the `/etc/hosts` file, IP addresses stored in the 1099 > environment variables are not automatically updated if the source container is 1100 > restarted. We recommend using the host entries in `/etc/hosts` to resolve the 1101 > IP address of linked containers. 1102 1103 ## VOLUME (shared filesystems) 1104 1105 -v=[]: Create a bind mount with: [host-dir]:[container-dir]:[rw|ro]. 1106 If "container-dir" is missing, then docker creates a new volume. 1107 --volumes-from="": Mount all volumes from the given container(s) 1108 1109 The volumes commands are complex enough to have their own documentation 1110 in section [*Managing data in 1111 containers*](/userguide/dockervolumes). A developer can define 1112 one or more `VOLUME`'s associated with an image, but only the operator 1113 can give access from one container to another (or from a container to a 1114 volume mounted on the host). 1115 1116 ## USER 1117 1118 The default user within a container is `root` (id = 0), but if the 1119 developer created additional users, those are accessible too. The 1120 developer can set a default user to run the first process with the 1121 Dockerfile `USER` instruction, but the operator can override it: 1122 1123 -u="": Username or UID 1124 1125 > **Note:** if you pass numeric uid, it must be in range 0-2147483647. 1126 1127 ## WORKDIR 1128 1129 The default working directory for running binaries within a container is the 1130 root directory (`/`), but the developer can set a different default with the 1131 Dockerfile `WORKDIR` command. The operator can override this with: 1132 1133 -w="": Working directory inside the container