github.com/caseyhadden/docker@v1.6.2/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 $ sudo 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 list of `[OPTIONS]` breaks down into two groups: 33 34 1. Settings exclusive to operators, including: 35 * Detached or Foreground running, 36 * Container Identification, 37 * Network settings, and 38 * Runtime Constraints on CPU and Memory 39 * Privileges and LXC Configuration 40 2. Settings shared between operators and developers, where operators can 41 override defaults developers set in images at build time. 42 43 Together, the `docker run [OPTIONS]` give the operator complete control over runtime 44 behavior, allowing them to override all defaults set by 45 the developer during `docker build` and nearly all the defaults set by 46 the Docker runtime itself. 47 48 ## Operator exclusive options 49 50 Only the operator (the person executing `docker run`) can set the 51 following options. 52 53 - [Detached vs Foreground](#detached-vs-foreground) 54 - [Detached (-d)](#detached-d) 55 - [Foreground](#foreground) 56 - [Container Identification](#container-identification) 57 - [Name (--name)](#name-name) 58 - [PID Equivalent](#pid-equivalent) 59 - [IPC Settings (--ipc)](#ipc-settings-ipc) 60 - [Network Settings](#network-settings) 61 - [Restart Policies (--restart)](#restart-policies-restart) 62 - [Clean Up (--rm)](#clean-up-rm) 63 - [Runtime Constraints on CPU and Memory](#runtime-constraints-on-cpu-and-memory) 64 - [Runtime Privilege, Linux Capabilities, and LXC Configuration](#runtime-privilege-linux-capabilities-and-lxc-configuration) 65 66 ## Detached vs foreground 67 68 When starting a Docker container, you must first decide if you want to 69 run the container in the background in a "detached" mode or in the 70 default foreground mode: 71 72 -d=false: Detached mode: Run container in the background, print new container id 73 74 ### Detached (-d) 75 76 In detached mode (`-d=true` or just `-d`), all I/O should be done 77 through network connections or shared volumes because the container is 78 no longer listening to the command line where you executed `docker run`. 79 You can reattach to a detached container with `docker` 80 [*attach*](/reference/commandline/cli/#attach). If you choose to run a 81 container in the detached mode, then you cannot use the `--rm` option. 82 83 ### Foreground 84 85 In foreground mode (the default when `-d` is not specified), `docker 86 run` can start the process in the container and attach the console to 87 the process's standard input, output, and standard error. It can even 88 pretend to be a TTY (this is what most command line executables expect) 89 and pass along signals. All of that is configurable: 90 91 -a=[] : Attach to `STDIN`, `STDOUT` and/or `STDERR` 92 -t=false : Allocate a pseudo-tty 93 --sig-proxy=true: Proxify all received signal to the process (non-TTY mode only) 94 -i=false : Keep STDIN open even if not attached 95 96 If you do not specify `-a` then Docker will [attach all standard 97 streams]( https://github.com/docker/docker/blob/ 98 75a7f4d90cde0295bcfb7213004abce8d4779b75/commands.go#L1797). You can 99 specify to which of the three standard streams (`STDIN`, `STDOUT`, 100 `STDERR`) you'd like to connect instead, as in: 101 102 $ sudo docker run -a stdin -a stdout -i -t ubuntu /bin/bash 103 104 For interactive processes (like a shell), you must use `-i -t` together in 105 order to allocate a tty for the container process. `-i -t` is often written `-it` 106 as you'll see in later examples. Specifying `-t` is forbidden when the client 107 standard output is redirected or piped, such as in: 108 `echo test | sudo docker run -i busybox cat`. 109 110 ## Container identification 111 112 ### Name (--name) 113 114 The operator can identify a container in three ways: 115 116 - UUID long identifier 117 ("f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778") 118 - UUID short identifier ("f78375b1c487") 119 - Name ("evil_ptolemy") 120 121 The UUID identifiers come from the Docker daemon, and if you do not 122 assign a name to the container with `--name` then the daemon will also 123 generate a random string name too. The name can become a handy way to 124 add meaning to a container since you can use this name when defining 125 [*links*](/userguide/dockerlinks) (or any 126 other place you need to identify a container). This works for both 127 background and foreground Docker containers. 128 129 ### PID equivalent 130 131 Finally, to help with automation, you can have Docker write the 132 container ID out to a file of your choosing. This is similar to how some 133 programs might write out their process ID to a file (you've seen them as 134 PID files): 135 136 --cidfile="": Write the container ID to the file 137 138 ### Image[:tag] 139 140 While not strictly a means of identifying a container, you can specify a version of an 141 image you'd like to run the container with by adding `image[:tag]` to the command. For 142 example, `docker run ubuntu:14.04`. 143 144 ### Image[@digest] 145 146 Images using the v2 or later image format have a content-addressable identifier 147 called a digest. As long as the input used to generate the image is unchanged, 148 the digest value is predictable and referenceable. 149 150 ## PID Settings (--pid) 151 --pid="" : Set the PID (Process) Namespace mode for the container, 152 'host': use the host's PID namespace inside the container 153 154 By default, all containers have the PID namespace enabled. 155 156 PID namespace provides separation of processes. The PID Namespace removes the 157 view of the system processes, and allows process ids to be reused including 158 pid 1. 159 160 In certain cases you want your container to share the host's process namespace, 161 basically allowing processes within the container to see all of the processes 162 on the system. For example, you could build a container with debugging tools 163 like `strace` or `gdb`, but want to use these tools when debugging processes 164 within the container. 165 166 $ sudo docker run --pid=host rhel7 strace -p 1234 167 168 This command would allow you to use `strace` inside the container on pid 1234 on 169 the host. 170 171 ## IPC Settings (--ipc) 172 173 --ipc="" : Set the IPC mode for the container, 174 'container:<name|id>': reuses another container's IPC namespace 175 'host': use the host's IPC namespace inside the container 176 177 By default, all containers have the IPC namespace enabled. 178 179 IPC (POSIX/SysV IPC) namespace provides separation of named shared memory 180 segments, semaphores and message queues. 181 182 Shared memory segments are used to accelerate inter-process communication at 183 memory speed, rather than through pipes or through the network stack. Shared 184 memory is commonly used by databases and custom-built (typically C/OpenMPI, 185 C++/using boost libraries) high performance applications for scientific 186 computing and financial services industries. If these types of applications 187 are broken into multiple containers, you might need to share the IPC mechanisms 188 of the containers. 189 190 ## Network settings 191 192 --dns=[] : Set custom dns servers for the container 193 --net="bridge" : Set the Network mode for the container 194 'bridge': creates a new network stack for the container on the docker bridge 195 'none': no networking for this container 196 'container:<name|id>': reuses another container network stack 197 'host': use the host network stack inside the container 198 --add-host="" : Add a line to /etc/hosts (host:IP) 199 --mac-address="" : Sets the container's Ethernet device's MAC address 200 201 By default, all containers have networking enabled and they can make any 202 outgoing connections. The operator can completely disable networking 203 with `docker run --net none` which disables all incoming and outgoing 204 networking. In cases like this, you would perform I/O through files or 205 `STDIN` and `STDOUT` only. 206 207 Your container will use the same DNS servers as the host by default, but 208 you can override this with `--dns`. 209 210 By default a random MAC is generated. You can set the container's MAC address 211 explicitly by providing a MAC via the `--mac-address` parameter (format: 212 `12:34:56:78:9a:bc`). 213 214 Supported networking modes are: 215 216 <table> 217 <thead> 218 <tr> 219 <th class="no-wrap">Mode</th> 220 <th>Description</th> 221 </tr> 222 </thead> 223 <tbody> 224 <tr> 225 <td class="no-wrap"><strong>none</strong></td> 226 <td> 227 No networking in the container. 228 </td> 229 </tr> 230 <tr> 231 <td class="no-wrap"><strong>bridge</strong> (default)</td> 232 <td> 233 Connect the container to the bridge via veth interfaces. 234 </td> 235 </tr> 236 <tr> 237 <td class="no-wrap"><strong>host</strong></td> 238 <td> 239 Use the host's network stack inside the container. 240 </td> 241 </tr> 242 <tr> 243 <td class="no-wrap"><strong>container</strong>:<name|id></td> 244 <td> 245 Use the network stack of another container, specified via 246 its *name* or *id*. 247 </td> 248 </tr> 249 </tbody> 250 </table> 251 252 #### Mode: none 253 254 With the networking mode set to `none` a container will not have a 255 access to any external routes. The container will still have a 256 `loopback` interface enabled in the container but it does not have any 257 routes to external traffic. 258 259 #### Mode: bridge 260 261 With the networking mode set to `bridge` a container will use docker's 262 default networking setup. A bridge is setup on the host, commonly named 263 `docker0`, and a pair of `veth` interfaces will be created for the 264 container. One side of the `veth` pair will remain on the host attached 265 to the bridge while the other side of the pair will be placed inside the 266 container's namespaces in addition to the `loopback` interface. An IP 267 address will be allocated for containers on the bridge's network and 268 traffic will be routed though this bridge to the container. 269 270 #### Mode: host 271 272 With the networking mode set to `host` a container will share the host's 273 network stack and all interfaces from the host will be available to the 274 container. The container's hostname will match the hostname on the host 275 system. Publishing ports and linking to other containers will not work 276 when sharing the host's network stack. 277 278 > **Note**: `--net="host"` gives the container full access to local system 279 > services such as D-bus and is therefore considered insecure. 280 281 #### Mode: container 282 283 With the networking mode set to `container` a container will share the 284 network stack of another container. The other container's name must be 285 provided in the format of `--net container:<name|id>`. 286 287 Example running a Redis container with Redis binding to `localhost` then 288 running the `redis-cli` command and connecting to the Redis server over the 289 `localhost` interface. 290 291 $ sudo docker run -d --name redis example/redis --bind 127.0.0.1 292 $ # use the redis container's network stack to access localhost 293 $ sudo docker run --rm -it --net container:redis example/redis-cli -h 127.0.0.1 294 295 ### Managing /etc/hosts 296 297 Your container will have lines in `/etc/hosts` which define the hostname of the 298 container itself as well as `localhost` and a few other common things. The 299 `--add-host` flag can be used to add additional lines to `/etc/hosts`. 300 301 $ sudo docker run -it --add-host db-static:86.75.30.9 ubuntu cat /etc/hosts 302 172.17.0.22 09d03f76bf2c 303 fe00::0 ip6-localnet 304 ff00::0 ip6-mcastprefix 305 ff02::1 ip6-allnodes 306 ff02::2 ip6-allrouters 307 127.0.0.1 localhost 308 ::1 localhost ip6-localhost ip6-loopback 309 86.75.30.9 db-static 310 311 ## Restart policies (--restart) 312 313 Using the `--restart` flag on Docker run you can specify a restart policy for 314 how a container should or should not be restarted on exit. 315 316 When a restart policy is active on a container, it will be shown as either `Up` 317 or `Restarting` in [`docker ps`](/reference/commandline/cli/#ps). It can also be 318 useful to use [`docker events`](/reference/commandline/cli/#events) to see the 319 restart policy in effect. 320 321 Docker supports the following restart policies: 322 323 <table> 324 <thead> 325 <tr> 326 <th>Policy</th> 327 <th>Result</th> 328 </tr> 329 </thead> 330 <tbody> 331 <tr> 332 <td><strong>no</strong></td> 333 <td> 334 Do not automatically restart the container when it exits. This is the 335 default. 336 </td> 337 </tr> 338 <tr> 339 <td> 340 <span style="white-space: nowrap"> 341 <strong>on-failure</strong>[:max-retries] 342 </span> 343 </td> 344 <td> 345 Restart only if the container exits with a non-zero exit status. 346 Optionally, limit the number of restart retries the Docker 347 daemon attempts. 348 </td> 349 </tr> 350 <tr> 351 <td><strong>always</strong></td> 352 <td> 353 Always restart the container regardless of the exit status. 354 When you specify always, the Docker daemon will try to restart 355 the container indefinitely. 356 </td> 357 </tr> 358 </tbody> 359 </table> 360 361 An ever increasing delay (double the previous delay, starting at 100 362 milliseconds) is added before each restart to prevent flooding the server. 363 This means the daemon will wait for 100 ms, then 200 ms, 400, 800, 1600, 364 and so on until either the `on-failure` limit is hit, or when you `docker stop` 365 or `docker rm -f` the container. 366 367 If a container is succesfully restarted (the container is started and runs 368 for at least 10 seconds), the delay is reset to its default value of 100 ms. 369 370 You can specify the maximum amount of times Docker will try to restart the 371 container when using the **on-failure** policy. The default is that Docker 372 will try forever to restart the container. The number of (attempted) restarts 373 for a container can be obtained via [`docker inspect`]( 374 /reference/commandline/cli/#inspect). For example, to get the number of restarts 375 for container "my-container"; 376 377 $ sudo docker inspect -f "{{ .RestartCount }}" my-container 378 # 2 379 380 Or, to get the last time the container was (re)started; 381 382 $ docker inspect -f "{{ .State.StartedAt }}" my-container 383 # 2015-03-04T23:47:07.691840179Z 384 385 You cannot set any restart policy in combination with 386 ["clean up (--rm)"](#clean-up-rm). Setting both `--restart` and `--rm` 387 results in an error. 388 389 ###Examples 390 391 $ sudo docker run --restart=always redis 392 393 This will run the `redis` container with a restart policy of **always** 394 so that if the container exits, Docker will restart it. 395 396 $ sudo docker run --restart=on-failure:10 redis 397 398 This will run the `redis` container with a restart policy of **on-failure** 399 and a maximum restart count of 10. If the `redis` container exits with a 400 non-zero exit status more than 10 times in a row Docker will abort trying to 401 restart the container. Providing a maximum restart limit is only valid for the 402 **on-failure** policy. 403 404 ## Clean up (--rm) 405 406 By default a container's file system persists even after the container 407 exits. This makes debugging a lot easier (since you can inspect the 408 final state) and you retain all your data by default. But if you are 409 running short-term **foreground** processes, these container file 410 systems can really pile up. If instead you'd like Docker to 411 **automatically clean up the container and remove the file system when 412 the container exits**, you can add the `--rm` flag: 413 414 --rm=false: Automatically remove the container when it exits (incompatible with -d) 415 416 ## Security configuration 417 --security-opt="label:user:USER" : Set the label user for the container 418 --security-opt="label:role:ROLE" : Set the label role for the container 419 --security-opt="label:type:TYPE" : Set the label type for the container 420 --security-opt="label:level:LEVEL" : Set the label level for the container 421 --security-opt="label:disable" : Turn off label confinement for the container 422 --security-opt="apparmor:PROFILE" : Set the apparmor profile to be applied 423 to the container 424 425 You can override the default labeling scheme for each container by specifying 426 the `--security-opt` flag. For example, you can specify the MCS/MLS level, a 427 requirement for MLS systems. Specifying the level in the following command 428 allows you to share the same content between containers. 429 430 # docker run --security-opt label:level:s0:c100,c200 -i -t fedora bash 431 432 An MLS example might be: 433 434 # docker run --security-opt label:level:TopSecret -i -t rhel7 bash 435 436 To disable the security labeling for this container versus running with the 437 `--permissive` flag, use the following command: 438 439 # docker run --security-opt label:disable -i -t fedora bash 440 441 If you want a tighter security policy on the processes within a container, 442 you can specify an alternate type for the container. You could run a container 443 that is only allowed to listen on Apache ports by executing the following 444 command: 445 446 # docker run --security-opt label:type:svirt_apache_t -i -t centos bash 447 448 Note: 449 450 You would have to write policy defining a `svirt_apache_t` type. 451 452 ## Runtime constraints on CPU and memory 453 454 The operator can also adjust the performance parameters of the 455 container: 456 457 -m="": Memory limit (format: <number><optional unit>, where unit = b, k, m or g) 458 -memory-swap="": Total memory limit (memory + swap, format: <number><optional unit>, where unit = b, k, m or g) 459 -c, --cpu-shares=0 CPU shares (relative weight) 460 461 ### Memory constraints 462 463 We have four ways to set memory usage: 464 465 <table> 466 <thead> 467 <tr> 468 <th>Option</th> 469 <th>Result</th> 470 </tr> 471 </thead> 472 <tbody> 473 <tr> 474 <td class="no-wrap"> 475 <strong>memory=inf, memory-swap=inf</strong> (default) 476 </td> 477 <td> 478 There is no memory limit for the container. The container can use 479 as much memory as needed. 480 </td> 481 </tr> 482 <tr> 483 <td class="no-wrap"><strong>memory=L<inf, memory-swap=inf</strong></td> 484 <td> 485 (specify memory and set memory-swap as <code>-1</code>) The container is 486 not allowed to use more than L bytes of memory, but can use as much swap 487 as is needed (if the host supports swap memory). 488 </td> 489 </tr> 490 <tr> 491 <td class="no-wrap"><strong>memory=L<inf, memory-swap=2*L</strong></td> 492 <td> 493 (specify memory without memory-swap) The container is not allowed to 494 use more than L bytes of memory, swap *plus* memory usage is double 495 of that. 496 </td> 497 </tr> 498 <tr> 499 <td class="no-wrap"> 500 <strong>memory=L<inf, memory-swap=S<inf, L<=S</strong> 501 </td> 502 <td> 503 (specify both memory and memory-swap) The container is not allowed to 504 use more than L bytes of memory, swap *plus* memory usage is limited 505 by S. 506 </td> 507 </tr> 508 </tbody> 509 </table> 510 511 ### CPU share constraint 512 513 By default, all containers get the same proportion of CPU cycles. This proportion 514 can be modified by changing the container's CPU share weighting relative 515 to the weighting of all other running containers. 516 517 To modify the proportion from the default of 1024, use the `-c` or `--cpu-shares` 518 flag to set the weighting to 2 or higher. 519 520 The proportion will only apply when CPU-intensive processes are running. 521 When tasks in one container are idle, other containers can use the 522 left-over CPU time. The actual amount of CPU time will vary depending on 523 the number of containers running on the system. 524 525 For example, consider three containers, one has a cpu-share of 1024 and 526 two others have a cpu-share setting of 512. When processes in all three 527 containers attempt to use 100% of CPU, the first container would receive 528 50% of the total CPU time. If you add a fouth container with a cpu-share 529 of 1024, the first container only gets 33% of the CPU. The remaining containers 530 receive 16.5%, 16.5% and 33% of the CPU. 531 532 On a multi-core system, the shares of CPU time are distributed over all CPU 533 cores. Even if a container is limited to less than 100% of CPU time, it can 534 use 100% of each individual CPU core. 535 536 For example, consider a system with more than three cores. If you start one 537 container `{C0}` with `-c=512` running one process, and another container 538 `{C1}` with `-c=1024` running two processes, this can result in the following 539 division of CPU shares: 540 541 PID container CPU CPU share 542 100 {C0} 0 100% of CPU0 543 101 {C1} 1 100% of CPU1 544 102 {C1} 2 100% of CPU2 545 546 ## Runtime privilege, Linux capabilities, and LXC configuration 547 548 --cap-add: Add Linux capabilities 549 --cap-drop: Drop Linux capabilities 550 --privileged=false: Give extended privileges to this container 551 --device=[]: Allows you to run devices inside the container without the --privileged flag. 552 --lxc-conf=[]: Add custom lxc options 553 554 By default, Docker containers are "unprivileged" and cannot, for 555 example, run a Docker daemon inside a Docker container. This is because 556 by default a container is not allowed to access any devices, but a 557 "privileged" container is given access to all devices (see [lxc-template.go]( 558 https://github.com/docker/docker/blob/master/daemon/execdriver/lxc/lxc_template.go) 559 and documentation on [cgroups devices]( 560 https://www.kernel.org/doc/Documentation/cgroups/devices.txt)). 561 562 When the operator executes `docker run --privileged`, Docker will enable 563 to access to all devices on the host as well as set some configuration 564 in AppArmor or SELinux to allow the container nearly all the same access to the 565 host as processes running outside containers on the host. Additional 566 information about running with `--privileged` is available on the 567 [Docker Blog](http://blog.docker.com/2013/09/docker-can-now-run-within-docker/). 568 569 If you want to limit access to a specific device or devices you can use 570 the `--device` flag. It allows you to specify one or more devices that 571 will be accessible within the container. 572 573 $ sudo docker run --device=/dev/snd:/dev/snd ... 574 575 By default, the container will be able to `read`, `write`, and `mknod` these devices. 576 This can be overridden using a third `:rwm` set of options to each `--device` flag: 577 578 $ sudo docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc 579 580 Command (m for help): q 581 $ sudo docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk /dev/xvdc 582 You will not be able to write the partition table. 583 584 Command (m for help): q 585 586 $ sudo docker run --device=/dev/sda:/dev/xvdc:w --rm -it ubuntu fdisk /dev/xvdc 587 crash.... 588 589 $ sudo docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc 590 fdisk: unable to open /dev/xvdc: Operation not permitted 591 592 In addition to `--privileged`, the operator can have fine grain control over the 593 capabilities using `--cap-add` and `--cap-drop`. By default, Docker has a default 594 list of capabilities that are kept. Both flags support the value `all`, so if the 595 operator wants to have all capabilities but `MKNOD` they could use: 596 597 $ sudo docker run --cap-add=ALL --cap-drop=MKNOD ... 598 599 For interacting with the network stack, instead of using `--privileged` they 600 should use `--cap-add=NET_ADMIN` to modify the network interfaces. 601 602 $ docker run -t -i --rm ubuntu:14.04 ip link add dummy0 type dummy 603 RTNETLINK answers: Operation not permitted 604 $ docker run -t -i --rm --cap-add=NET_ADMIN ubuntu:14.04 ip link add dummy0 type dummy 605 606 To mount a FUSE based filesystem, you need to combine both `--cap-add` and 607 `--device`: 608 609 $ docker run --rm -it --cap-add SYS_ADMIN sshfs sshfs sven@10.10.10.20:/home/sven /mnt 610 fuse: failed to open /dev/fuse: Operation not permitted 611 $ docker run --rm -it --device /dev/fuse sshfs sshfs sven@10.10.10.20:/home/sven /mnt 612 fusermount: mount failed: Operation not permitted 613 $ docker run --rm -it --cap-add SYS_ADMIN --device /dev/fuse sshfs 614 # sshfs sven@10.10.10.20:/home/sven /mnt 615 The authenticity of host '10.10.10.20 (10.10.10.20)' can't be established. 616 ECDSA key fingerprint is 25:34:85:75:25:b0:17:46:05:19:04:93:b5:dd:5f:c6. 617 Are you sure you want to continue connecting (yes/no)? yes 618 sven@10.10.10.20's password: 619 root@30aa0cfaf1b5:/# ls -la /mnt/src/docker 620 total 1516 621 drwxrwxr-x 1 1000 1000 4096 Dec 4 06:08 . 622 drwxrwxr-x 1 1000 1000 4096 Dec 4 11:46 .. 623 -rw-rw-r-- 1 1000 1000 16 Oct 8 00:09 .dockerignore 624 -rwxrwxr-x 1 1000 1000 464 Oct 8 00:09 .drone.yml 625 drwxrwxr-x 1 1000 1000 4096 Dec 4 06:11 .git 626 -rw-rw-r-- 1 1000 1000 461 Dec 4 06:08 .gitignore 627 .... 628 629 630 If the Docker daemon was started using the `lxc` exec-driver 631 (`docker -d --exec-driver=lxc`) then the operator can also specify LXC options 632 using one or more `--lxc-conf` parameters. These can be new parameters or 633 override existing parameters from the [lxc-template.go]( 634 https://github.com/docker/docker/blob/master/daemon/execdriver/lxc/lxc_template.go). 635 Note that in the future, a given host's docker daemon may not use LXC, so this 636 is an implementation-specific configuration meant for operators already 637 familiar with using LXC directly. 638 639 > **Note:** 640 > If you use `--lxc-conf` to modify a container's configuration which is also 641 > managed by the Docker daemon, then the Docker daemon will not know about this 642 > modification, and you will need to manage any conflicts yourself. For example, 643 > you can use `--lxc-conf` to set a container's IP address, but this will not be 644 > reflected in the `/etc/hosts` file. 645 646 ## Logging drivers (--log-driver) 647 648 You can specify a different logging driver for the container than for the daemon. 649 650 ### Logging driver: none 651 652 Disables any logging for the container. `docker logs` won't be available with 653 this driver. 654 655 ### Log driver: json-file 656 657 Default logging driver for Docker. Writes JSON messages to file. `docker logs` 658 command is available only for this logging driver 659 660 ## Logging driver: syslog 661 662 Syslog logging driver for Docker. Writes log messages to syslog. `docker logs` 663 command is not available for this logging driver 664 665 ## Overriding Dockerfile image defaults 666 667 When a developer builds an image from a [*Dockerfile*](/reference/builder) 668 or when she commits it, the developer can set a number of default parameters 669 that take effect when the image starts up as a container. 670 671 Four of the Dockerfile commands cannot be overridden at runtime: `FROM`, 672 `MAINTAINER`, `RUN`, and `ADD`. Everything else has a corresponding override 673 in `docker run`. We'll go through what the developer might have set in each 674 Dockerfile instruction and how the operator can override that setting. 675 676 - [CMD (Default Command or Options)](#cmd-default-command-or-options) 677 - [ENTRYPOINT (Default Command to Execute at Runtime)]( 678 #entrypoint-default-command-to-execute-at-runtime) 679 - [EXPOSE (Incoming Ports)](#expose-incoming-ports) 680 - [ENV (Environment Variables)](#env-environment-variables) 681 - [VOLUME (Shared Filesystems)](#volume-shared-filesystems) 682 - [USER](#user) 683 - [WORKDIR](#workdir) 684 685 ## CMD (default command or options) 686 687 Recall the optional `COMMAND` in the Docker 688 commandline: 689 690 $ sudo docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...] 691 692 This command is optional because the person who created the `IMAGE` may 693 have already provided a default `COMMAND` using the Dockerfile `CMD` 694 instruction. As the operator (the person running a container from the 695 image), you can override that `CMD` instruction just by specifying a new 696 `COMMAND`. 697 698 If the image also specifies an `ENTRYPOINT` then the `CMD` or `COMMAND` 699 get appended as arguments to the `ENTRYPOINT`. 700 701 ## ENTRYPOINT (default command to execute at runtime) 702 703 --entrypoint="": Overwrite the default entrypoint set by the image 704 705 The `ENTRYPOINT` of an image is similar to a `COMMAND` because it 706 specifies what executable to run when the container starts, but it is 707 (purposely) more difficult to override. The `ENTRYPOINT` gives a 708 container its default nature or behavior, so that when you set an 709 `ENTRYPOINT` you can run the container *as if it were that binary*, 710 complete with default options, and you can pass in more options via the 711 `COMMAND`. But, sometimes an operator may want to run something else 712 inside the container, so you can override the default `ENTRYPOINT` at 713 runtime by using a string to specify the new `ENTRYPOINT`. Here is an 714 example of how to run a shell in a container that has been set up to 715 automatically run something else (like `/usr/bin/redis-server`): 716 717 $ sudo docker run -i -t --entrypoint /bin/bash example/redis 718 719 or two examples of how to pass more parameters to that ENTRYPOINT: 720 721 $ sudo docker run -i -t --entrypoint /bin/bash example/redis -c ls -l 722 $ sudo docker run -i -t --entrypoint /usr/bin/redis-cli example/redis --help 723 724 ## EXPOSE (incoming ports) 725 726 The Dockerfile doesn't give much control over networking, only providing 727 the `EXPOSE` instruction to give a hint to the operator about what 728 incoming ports might provide services. The following options work with 729 or override the Dockerfile's exposed defaults: 730 731 --expose=[]: Expose a port or a range of ports from the container 732 without publishing it to your host 733 -P=false : Publish all exposed ports to the host interfaces 734 -p=[] : Publish a container᾿s port or a range of ports to the host 735 format: ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort 736 Both hostPort and containerPort can be specified as a range of ports. 737 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`) 738 (use 'docker port' to see the actual mapping) 739 --link="" : Add link to another container (<name or id>:alias) 740 741 As mentioned previously, `EXPOSE` (and `--expose`) makes ports available 742 **in** a container for incoming connections. The port number on the 743 inside of the container (where the service listens) does not need to be 744 the same number as the port exposed on the outside of the container 745 (where clients connect), so inside the container you might have an HTTP 746 service listening on port 80 (and so you `EXPOSE 80` in the Dockerfile), 747 but outside the container the port might be 42800. 748 749 To help a new client container reach the server container's internal 750 port operator `--expose`'d by the operator or `EXPOSE`'d by the 751 developer, the operator has three choices: start the server container 752 with `-P` or `-p,` or start the client container with `--link`. 753 754 If the operator uses `-P` or `-p` then Docker will make the exposed port 755 accessible on the host and the ports will be available to any client that can 756 reach the host. When using `-P`, Docker will bind the exposed port to a random 757 port on the host within an *ephemeral port range* defined by 758 `/proc/sys/net/ipv4/ip_local_port_range`. To find the mapping between the host 759 ports and the exposed ports, use `docker port`. 760 761 If the operator uses `--link` when starting the new client container, 762 then the client container can access the exposed port via a private 763 networking interface. Docker will set some environment variables in the 764 client container to help indicate which interface and port to use. 765 766 ## ENV (environment variables) 767 768 When a new container is created, Docker will set the following environment 769 variables automatically: 770 771 <table> 772 <tr> 773 <th>Variable</th> 774 <th>Value</th> 775 </tr> 776 <tr> 777 <td><code>HOME</code></td> 778 <td> 779 Set based on the value of <code>USER</code> 780 </td> 781 </tr> 782 <tr> 783 <td><code>HOSTNAME</code></td> 784 <td> 785 The hostname associated with the container 786 </td> 787 </tr> 788 <tr> 789 <td><code>PATH</code></td> 790 <td> 791 Includes popular directories, such as :<br> 792 <code>/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin</code> 793 </td> 794 <tr> 795 <td><code>TERM</code></td> 796 <td><code>xterm</code> if the container is allocated a psuedo-TTY</td> 797 </tr> 798 </table> 799 800 The container may also include environment variables defined 801 as a result of the container being linked with another container. See 802 the [*Container Links*](/userguide/dockerlinks/#container-linking) 803 section for more details. 804 805 Additionally, the operator can **set any environment variable** in the 806 container by using one or more `-e` flags, even overriding those mentioned 807 above, or already defined by the developer with a Dockerfile `ENV`: 808 809 $ sudo docker run -e "deep=purple" --rm ubuntu /bin/bash -c export 810 declare -x HOME="/" 811 declare -x HOSTNAME="85bc26a0e200" 812 declare -x OLDPWD 813 declare -x PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 814 declare -x PWD="/" 815 declare -x SHLVL="1" 816 declare -x container="lxc" 817 declare -x deep="purple" 818 819 Similarly the operator can set the **hostname** with `-h`. 820 821 `--link <name or id>:alias` also sets environment variables, using the *alias* string to 822 define environment variables within the container that give the IP and PORT 823 information for connecting to the service container. Let's imagine we have a 824 container running Redis: 825 826 # Start the service container, named redis-name 827 $ sudo docker run -d --name redis-name dockerfiles/redis 828 4241164edf6f5aca5b0e9e4c9eccd899b0b8080c64c0cd26efe02166c73208f3 829 830 # The redis-name container exposed port 6379 831 $ sudo docker ps 832 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 833 4241164edf6f $ dockerfiles/redis:latest /redis-stable/src/re 5 seconds ago Up 4 seconds 6379/tcp redis-name 834 835 # Note that there are no public ports exposed since we didn᾿t use -p or -P 836 $ sudo docker port 4241164edf6f 6379 837 2014/01/25 00:55:38 Error: No public port '6379' published for 4241164edf6f 838 839 Yet we can get information about the Redis container's exposed ports 840 with `--link`. Choose an alias that will form a 841 valid environment variable! 842 843 $ sudo docker run --rm --link redis-name:redis_alias --entrypoint /bin/bash dockerfiles/redis -c export 844 declare -x HOME="/" 845 declare -x HOSTNAME="acda7f7b1cdc" 846 declare -x OLDPWD 847 declare -x PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 848 declare -x PWD="/" 849 declare -x REDIS_ALIAS_NAME="/distracted_wright/redis" 850 declare -x REDIS_ALIAS_PORT="tcp://172.17.0.32:6379" 851 declare -x REDIS_ALIAS_PORT_6379_TCP="tcp://172.17.0.32:6379" 852 declare -x REDIS_ALIAS_PORT_6379_TCP_ADDR="172.17.0.32" 853 declare -x REDIS_ALIAS_PORT_6379_TCP_PORT="6379" 854 declare -x REDIS_ALIAS_PORT_6379_TCP_PROTO="tcp" 855 declare -x SHLVL="1" 856 declare -x container="lxc" 857 858 And we can use that information to connect from another container as a client: 859 860 $ sudo 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' 861 172.17.0.32:6379> 862 863 Docker will also map the private IP address to the alias of a linked 864 container by inserting an entry into `/etc/hosts`. You can use this 865 mechanism to communicate with a linked container by its alias: 866 867 $ sudo docker run -d --name servicename busybox sleep 30 868 $ sudo docker run -i -t --link servicename:servicealias busybox ping -c 1 servicealias 869 870 If you restart the source container (`servicename` in this case), the recipient 871 container's `/etc/hosts` entry will be automatically updated. 872 873 > **Note**: 874 > Unlike host entries in the `/etc/hosts` file, IP addresses stored in the 875 > environment variables are not automatically updated if the source container is 876 > restarted. We recommend using the host entries in `/etc/hosts` to resolve the 877 > IP address of linked containers. 878 879 ## VOLUME (shared filesystems) 880 881 -v=[]: Create a bind mount with: [host-dir]:[container-dir]:[rw|ro]. 882 If "container-dir" is missing, then docker creates a new volume. 883 --volumes-from="": Mount all volumes from the given container(s) 884 885 The volumes commands are complex enough to have their own documentation 886 in section [*Managing data in 887 containers*](/userguide/dockervolumes). A developer can define 888 one or more `VOLUME`'s associated with an image, but only the operator 889 can give access from one container to another (or from a container to a 890 volume mounted on the host). 891 892 ## USER 893 894 The default user within a container is `root` (id = 0), but if the 895 developer created additional users, those are accessible too. The 896 developer can set a default user to run the first process with the 897 Dockerfile `USER` instruction, but the operator can override it: 898 899 -u="": Username or UID 900 901 > **Note:** if you pass numeric uid, it must be in range 0-2147483647. 902 903 ## WORKDIR 904 905 The default working directory for running binaries within a container is the 906 root directory (`/`), but the developer can set a different default with the 907 Dockerfile `WORKDIR` command. The operator can override this with: 908 909 -w="": Working directory inside the container