github.com/lmars/docker@v1.6.0-rc2/docs/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 [**-c**|**--cpu-shares**[=*0*]] 12 [**--cap-add**[=*[]*]] 13 [**--cap-drop**[=*[]*]] 14 [**--cidfile**[=*CIDFILE*]] 15 [**--cpuset-cpus**[=*CPUSET-CPUS*]] 16 [**-d**|**--detach**[=*false*]] 17 [**--device**[=*[]*]] 18 [**--dns-search**[=*[]*]] 19 [**--dns**[=*[]*]] 20 [**-e**|**--env**[=*[]*]] 21 [**--entrypoint**[=*ENTRYPOINT*]] 22 [**--env-file**[=*[]*]] 23 [**--expose**[=*[]*]] 24 [**-h**|**--hostname**[=*HOSTNAME*]] 25 [**--help**] 26 [**-i**|**--interactive**[=*false*]] 27 [**--ipc**[=*IPC*]] 28 [**-l**|**--label**[=*[]*]] 29 [**--label-file**[=*[]*]] 30 [**--link**[=*[]*]] 31 [**--lxc-conf**[=*[]*]] 32 [**--log-driver**[=*[]*]] 33 [**-m**|**--memory**[=*MEMORY*]] 34 [**--memory-swap**[=*MEMORY-SWAP*]] 35 [**--mac-address**[=*MAC-ADDRESS*]] 36 [**--name**[=*NAME*]] 37 [**--net**[=*"bridge"*]] 38 [**-P**|**--publish-all**[=*false*]] 39 [**-p**|**--publish**[=*[]*]] 40 [**--pid**[=*[]*]] 41 [**--privileged**[=*false*]] 42 [**--read-only**[=*false*]] 43 [**--restart**[=*RESTART*]] 44 [**--rm**[=*false*]] 45 [**--security-opt**[=*[]*]] 46 [**--sig-proxy**[=*true*]] 47 [**-t**|**--tty**[=*false*]] 48 [**-u**|**--user**[=*USER*]] 49 [**-v**|**--volume**[=*[]*]] 50 [**--volumes-from**[=*[]*]] 51 [**-w**|**--workdir**[=*WORKDIR*]] 52 [**--cgroup-parent**[=*CGROUP-PATH*]] 53 IMAGE [COMMAND] [ARG...] 54 55 # DESCRIPTION 56 57 Run a process in a new container. **docker run** starts a process with its own 58 file system, its own networking, and its own isolated process tree. The IMAGE 59 which starts the process may define defaults related to the process that will be 60 run in the container, the networking to expose, and more, but **docker run** 61 gives final control to the operator or administrator who starts the container 62 from the image. For that reason **docker run** has more options than any other 63 Docker command. 64 65 If the IMAGE is not already loaded then **docker run** will pull the IMAGE, and 66 all image dependencies, from the repository in the same way running **docker 67 pull** IMAGE, before it starts the container from that image. 68 69 # OPTIONS 70 **-a**, **--attach**=[] 71 Attach to STDIN, STDOUT or STDERR. 72 73 In foreground mode (the default when **-d** 74 is not specified), **docker run** can start the process in the container 75 and attach the console to the process’s standard input, output, and standard 76 error. It can even pretend to be a TTY (this is what most commandline 77 executables expect) and pass along signals. The **-a** option can be set for 78 each of stdin, stdout, and stderr. 79 80 **--add-host**=[] 81 Add a custom host-to-IP mapping (host:ip) 82 83 Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** 84 option can be set multiple times. 85 86 **-c**, **--cpu-shares**=0 87 CPU shares (relative weight) 88 89 By default, all containers get the same proportion of CPU cycles. This proportion 90 can be modified by changing the container's CPU share weighting relative 91 to the weighting of all other running containers. 92 93 To modify the proportion from the default of 1024, use the **-c** or **--cpu-shares** 94 flag to set the weighting to 2 or higher. 95 96 The proportion will only apply when CPU-intensive processes are running. 97 When tasks in one container are idle, other containers can use the 98 left-over CPU time. The actual amount of CPU time will vary depending on 99 the number of containers running on the system. 100 101 For example, consider three containers, one has a cpu-share of 1024 and 102 two others have a cpu-share setting of 512. When processes in all three 103 containers attempt to use 100% of CPU, the first container would receive 104 50% of the total CPU time. If you add a fouth container with a cpu-share 105 of 1024, the first container only gets 33% of the CPU. The remaining containers 106 receive 16.5%, 16.5% and 33% of the CPU. 107 108 On a multi-core system, the shares of CPU time are distributed over all CPU 109 cores. Even if a container is limited to less than 100% of CPU time, it can 110 use 100% of each individual CPU core. 111 112 For example, consider a system with more than three cores. If you start one 113 container **{C0}** with **-c=512** running one process, and another container 114 **{C1}** with **-c=1024** running two processes, this can result in the following 115 division of CPU shares: 116 117 PID container CPU CPU share 118 100 {C0} 0 100% of CPU0 119 101 {C1} 1 100% of CPU1 120 102 {C1} 2 100% of CPU2 121 122 **--cap-add**=[] 123 Add Linux capabilities 124 125 **--cap-drop**=[] 126 Drop Linux capabilities 127 128 **--cgroup-parent**="" 129 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. 130 131 **--cidfile**="" 132 Write the container ID to the file 133 134 **--cpuset-cpus**="" 135 CPUs in which to allow execution (0-3, 0,1) 136 137 **-d**, **--detach**=*true*|*false* 138 Detached mode: run the container in the background and print the new container ID. The default is *false*. 139 140 At any time you can run **docker ps** in 141 the other shell to view a list of the running containers. You can reattach to a 142 detached container with **docker attach**. If you choose to run a container in 143 the detached mode, then you cannot use the **-rm** option. 144 145 When attached in the tty mode, you can detach from a running container without 146 stopping the process by pressing the keys CTRL-P CTRL-Q. 147 148 **--device**=[] 149 Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc:rwm) 150 151 **--dns-search**=[] 152 Set custom DNS search domains (Use --dns-search=. if you don't wish to set the search domain) 153 154 **--dns**=[] 155 Set custom DNS servers 156 157 This option can be used to override the DNS 158 configuration passed to the container. Typically this is necessary when the 159 host DNS configuration is invalid for the container (e.g., 127.0.0.1). When this 160 is the case the **--dns** flags is necessary for every run. 161 162 **-e**, **--env**=[] 163 Set environment variables 164 165 This option allows you to specify arbitrary 166 environment variables that are available for the process that will be launched 167 inside of the container. 168 169 **--entrypoint**="" 170 Overwrite the default ENTRYPOINT of the image 171 172 This option allows you to overwrite the default entrypoint of the image that 173 is set in the Dockerfile. The ENTRYPOINT of an image is similar to a COMMAND 174 because it specifies what executable to run when the container starts, but it is 175 (purposely) more difficult to override. The ENTRYPOINT gives a container its 176 default nature or behavior, so that when you set an ENTRYPOINT you can run the 177 container as if it were that binary, complete with default options, and you can 178 pass in more options via the COMMAND. But, sometimes an operator may want to run 179 something else inside the container, so you can override the default ENTRYPOINT 180 at runtime by using a **--entrypoint** and a string to specify the new 181 ENTRYPOINT. 182 183 **--env-file**=[] 184 Read in a line delimited file of environment variables 185 186 **--expose**=[] 187 Expose a port, or a range of ports (e.g. --expose=3300-3310), from the container without publishing it to your host 188 189 **-h**, **--hostname**="" 190 Container host name 191 192 Sets the container host name that is available inside the container. 193 194 **--help** 195 Print usage statement 196 197 **-i**, **--interactive**=*true*|*false* 198 Keep STDIN open even if not attached. The default is *false*. 199 200 When set to true, keep stdin open even if not attached. The default is false. 201 202 **--ipc**="" 203 Default is to create a private IPC namespace (POSIX SysV IPC) for the container 204 'container:<name|id>': reuses another container shared memory, semaphores and message queues 205 '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. 206 207 **-l**, **--label**=[] 208 Set metadata on the container (e.g., --label com.example.key=value) 209 210 **--label-file**=[] 211 Read in a line delimited file of labels 212 213 **--link**=[] 214 Add link to another container in the form of <name or id>:alias 215 216 If the operator 217 uses **--link** when starting the new client container, then the client 218 container can access the exposed port via a private networking interface. Docker 219 will set some environment variables in the client container to help indicate 220 which interface and port to use. 221 222 **--lxc-conf**=[] 223 (lxc exec-driver only) Add custom lxc options --lxc-conf="lxc.cgroup.cpuset.cpus = 0,1" 224 225 **--log-driver**="|*json-file*|*syslog*|*none*" 226 Logging driver for container. Default is defined by daemon `--log-driver` flag. 227 **Warning**: `docker logs` command works only for `json-file` logging driver. 228 229 **-m**, **--memory**="" 230 Memory limit (format: <number><optional unit>, where unit = b, k, m or g) 231 232 Allows you to constrain the memory available to a container. If the host 233 supports swap memory, then the **-m** memory setting can be larger than physical 234 RAM. If a limit of 0 is specified (not using **-m**), the container's memory is 235 not limited. The actual limit may be rounded up to a multiple of the operating 236 system's page size (the value would be very large, that's millions of trillions). 237 238 **--memory-swap**="" 239 Total memory limit (memory + swap) 240 241 Set `-1` to disable swap (format: <number><optional unit>, where unit = b, k, m or g). 242 This value should always larger than **-m**, so you should alway use this with **-m**. 243 244 **--mac-address**="" 245 Container MAC address (e.g. 92:d0:c6:0a:29:33) 246 247 Remember that the MAC address in an Ethernet network must be unique. 248 The IPv6 link-local address will be based on the device's MAC address 249 according to RFC4862. 250 251 **--name**="" 252 Assign a name to the container 253 254 The operator can identify a container in three ways: 255 UUID long identifier (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”) 256 UUID short identifier (“f78375b1c487”) 257 Name (“jonah”) 258 259 The UUID identifiers come from the Docker daemon, and if a name is not assigned 260 to the container with **--name** then the daemon will also generate a random 261 string name. The name is useful when defining links (see **--link**) (or any 262 other place you need to identify a container). This works for both background 263 and foreground Docker containers. 264 265 **--net**="bridge" 266 Set the Network mode for the container 267 'bridge': creates a new network stack for the container on the docker bridge 268 'none': no networking for this container 269 'container:<name|id>': reuses another container network stack 270 'host': use the host network stack inside the container. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure. 271 272 **-P**, **--publish-all**=*true*|*false* 273 Publish all exposed ports to random ports on the host interfaces. The default is *false*. 274 275 When set to true publish all exposed ports to the host interfaces. The 276 default is false. If the operator uses -P (or -p) then Docker will make the 277 exposed port accessible on the host and the ports will be available to any 278 client that can reach the host. When using -P, Docker will bind any exposed 279 port to a random port on the host within an *ephemeral port range* defined by 280 `/proc/sys/net/ipv4/ip_local_port_range`. To find the mapping between the host 281 ports and the exposed ports, use `docker port`. 282 283 **-p**, **--publish**=[] 284 Publish a container's port, or range of ports, to the host. 285 format: ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort 286 Both hostPort and containerPort can be specified as a range of ports. 287 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`) 288 (use 'docker port' to see the actual mapping) 289 290 **--pid**=host 291 Set the PID mode for the container 292 **host**: use the host's PID namespace inside the container. 293 Note: the host mode gives the container full access to local PID and is therefore considered insecure. 294 295 **--privileged**=*true*|*false* 296 Give extended privileges to this container. The default is *false*. 297 298 By default, Docker containers are 299 “unprivileged” (=false) and cannot, for example, run a Docker daemon inside the 300 Docker container. This is because by default a container is not allowed to 301 access any devices. A “privileged” container is given access to all devices. 302 303 When the operator executes **docker run --privileged**, Docker will enable access 304 to all devices on the host as well as set some configuration in AppArmor to 305 allow the container nearly all the same access to the host as processes running 306 outside of a container on the host. 307 308 **--read-only**=*true*|*false* 309 Mount the container's root filesystem as read only. 310 311 By default a container will have its root filesystem writable allowing processes 312 to write files anywhere. By specifying the `--read-only` flag the container will have 313 its root filesystem mounted as read only prohibiting any writes. 314 315 **--restart**="no" 316 Restart policy to apply when a container exits (no, on-failure[:max-retry], always) 317 318 **--rm**=*true*|*false* 319 Automatically remove the container when it exits (incompatible with -d). The default is *false*. 320 321 **--security-opt**=[] 322 Security Options 323 324 "label:user:USER" : Set the label user for the container 325 "label:role:ROLE" : Set the label role for the container 326 "label:type:TYPE" : Set the label type for the container 327 "label:level:LEVEL" : Set the label level for the container 328 "label:disable" : Turn off label confinement for the container 329 330 **--sig-proxy**=*true*|*false* 331 Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is *true*. 332 333 **-t**, **--tty**=*true*|*false* 334 Allocate a pseudo-TTY. The default is *false*. 335 336 When set to true Docker can allocate a pseudo-tty and attach to the standard 337 input of any container. This can be used, for example, to run a throwaway 338 interactive shell. The default is value is false. 339 340 The **-t** option is incompatible with a redirection of the docker client 341 standard input. 342 343 **-u**, **--user**="" 344 Username or UID 345 346 **-v**, **--volume**=[] 347 Bind mount a volume (e.g., from the host: -v /host:/container, from Docker: -v /container) 348 349 The **-v** option can be used one or 350 more times to add one or more mounts to a container. These mounts can then be 351 used in other containers using the **--volumes-from** option. 352 353 The volume may be optionally suffixed with :ro or :rw to mount the volumes in 354 read-only or read-write mode, respectively. By default, the volumes are mounted 355 read-write. See examples. 356 357 **--volumes-from**=[] 358 Mount volumes from the specified container(s) 359 360 Mounts already mounted volumes from a source container onto another 361 container. You must supply the source's container-id. To share 362 a volume, use the **--volumes-from** option when running 363 the target container. You can share volumes even if the source container 364 is not running. 365 366 By default, Docker mounts the volumes in the same mode (read-write or 367 read-only) as it is mounted in the source container. Optionally, you 368 can change this by suffixing the container-id with either the `:ro` or 369 `:rw ` keyword. 370 371 If the location of the volume from the source container overlaps with 372 data residing on a target container, then the volume hides 373 that data on the target. 374 375 **-w**, **--workdir**="" 376 Working directory inside the container 377 378 The default working directory for 379 running binaries within a container is the root directory (/). The developer can 380 set a different default with the Dockerfile WORKDIR instruction. The operator 381 can override the working directory by using the **-w** option. 382 383 # EXAMPLES 384 385 ## Exposing log messages from the container to the host's log 386 387 If you want messages that are logged in your container to show up in the host's 388 syslog/journal then you should bind mount the /dev/log directory as follows. 389 390 # docker run -v /dev/log:/dev/log -i -t fedora /bin/bash 391 392 From inside the container you can test this by sending a message to the log. 393 394 (bash)# logger "Hello from my container" 395 396 Then exit and check the journal. 397 398 # exit 399 400 # journalctl -b | grep Hello 401 402 This should list the message sent to logger. 403 404 ## Attaching to one or more from STDIN, STDOUT, STDERR 405 406 If you do not specify -a then Docker will attach everything (stdin,stdout,stderr) 407 . You can specify to which of the three standard streams (stdin, stdout, stderr) 408 you’d like to connect instead, as in: 409 410 # docker run -a stdin -a stdout -i -t fedora /bin/bash 411 412 ## Sharing IPC between containers 413 414 Using shm_server.c available here: http://www.cs.cf.ac.uk/Dave/C/node27.html 415 416 Testing `--ipc=host` mode: 417 418 Host shows a shared memory segment with 7 pids attached, happens to be from httpd: 419 420 ``` 421 $ sudo ipcs -m 422 423 ------ Shared Memory Segments -------- 424 key shmid owner perms bytes nattch status 425 0x01128e25 0 root 600 1000 7 426 ``` 427 428 Now run a regular container, and it correctly does NOT see the shared memory segment from the host: 429 430 ``` 431 $ sudo docker run -it shm ipcs -m 432 433 ------ Shared Memory Segments -------- 434 key shmid owner perms bytes nattch status 435 ``` 436 437 Run a container with the new `--ipc=host` option, and it now sees the shared memory segment from the host httpd: 438 439 ``` 440 $ sudo docker run -it --ipc=host shm ipcs -m 441 442 ------ Shared Memory Segments -------- 443 key shmid owner perms bytes nattch status 444 0x01128e25 0 root 600 1000 7 445 ``` 446 Testing `--ipc=container:CONTAINERID` mode: 447 448 Start a container with a program to create a shared memory segment: 449 ``` 450 sudo docker run -it shm bash 451 $ sudo shm/shm_server & 452 $ sudo ipcs -m 453 454 ------ Shared Memory Segments -------- 455 key shmid owner perms bytes nattch status 456 0x0000162e 0 root 666 27 1 457 ``` 458 Create a 2nd container correctly shows no shared memory segment from 1st container: 459 ``` 460 $ sudo docker run shm ipcs -m 461 462 ------ Shared Memory Segments -------- 463 key shmid owner perms bytes nattch status 464 ``` 465 466 Create a 3rd container using the new --ipc=container:CONTAINERID option, now it shows the shared memory segment from the first: 467 468 ``` 469 $ sudo docker run -it --ipc=container:ed735b2264ac shm ipcs -m 470 $ sudo ipcs -m 471 472 ------ Shared Memory Segments -------- 473 key shmid owner perms bytes nattch status 474 0x0000162e 0 root 666 27 1 475 ``` 476 477 ## Linking Containers 478 479 The link feature allows multiple containers to communicate with each other. For 480 example, a container whose Dockerfile has exposed port 80 can be run and named 481 as follows: 482 483 # docker run --name=link-test -d -i -t fedora/httpd 484 485 A second container, in this case called linker, can communicate with the httpd 486 container, named link-test, by running with the **--link=<name>:<alias>** 487 488 # docker run -t -i --link=link-test:lt --name=linker fedora /bin/bash 489 490 Now the container linker is linked to container link-test with the alias lt. 491 Running the **env** command in the linker container shows environment variables 492 with the LT (alias) context (**LT_**) 493 494 # env 495 HOSTNAME=668231cb0978 496 TERM=xterm 497 LT_PORT_80_TCP=tcp://172.17.0.3:80 498 LT_PORT_80_TCP_PORT=80 499 LT_PORT_80_TCP_PROTO=tcp 500 LT_PORT=tcp://172.17.0.3:80 501 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin 502 PWD=/ 503 LT_NAME=/linker/lt 504 SHLVL=1 505 HOME=/ 506 LT_PORT_80_TCP_ADDR=172.17.0.3 507 _=/usr/bin/env 508 509 When linking two containers Docker will use the exposed ports of the container 510 to create a secure tunnel for the parent to access. 511 512 513 ## Mapping Ports for External Usage 514 515 The exposed port of an application can be mapped to a host port using the **-p** 516 flag. For example, a httpd port 80 can be mapped to the host port 8080 using the 517 following: 518 519 # docker run -p 8080:80 -d -i -t fedora/httpd 520 521 ## Creating and Mounting a Data Volume Container 522 523 Many applications require the sharing of persistent data across several 524 containers. Docker allows you to create a Data Volume Container that other 525 containers can mount from. For example, create a named container that contains 526 directories /var/volume1 and /tmp/volume2. The image will need to contain these 527 directories so a couple of RUN mkdir instructions might be required for you 528 fedora-data image: 529 530 # docker run --name=data -v /var/volume1 -v /tmp/volume2 -i -t fedora-data true 531 # docker run --volumes-from=data --name=fedora-container1 -i -t fedora bash 532 533 Multiple --volumes-from parameters will bring together multiple data volumes from 534 multiple containers. And it's possible to mount the volumes that came from the 535 DATA container in yet another container via the fedora-container1 intermediary 536 container, allowing to abstract the actual data source from users of that data: 537 538 # docker run --volumes-from=fedora-container1 --name=fedora-container2 -i -t fedora bash 539 540 ## Mounting External Volumes 541 542 To mount a host directory as a container volume, specify the absolute path to 543 the directory and the absolute path for the container directory separated by a 544 colon: 545 546 # docker run -v /var/db:/data1 -i -t fedora bash 547 548 When using SELinux, be aware that the host has no knowledge of container SELinux 549 policy. Therefore, in the above example, if SELinux policy is enforced, the 550 `/var/db` directory is not writable to the container. A "Permission Denied" 551 message will occur and an avc: message in the host's syslog. 552 553 554 To work around this, at time of writing this man page, the following command 555 needs to be run in order for the proper SELinux policy type label to be attached 556 to the host directory: 557 558 # chcon -Rt svirt_sandbox_file_t /var/db 559 560 561 Now, writing to the /data1 volume in the container will be allowed and the 562 changes will also be reflected on the host in /var/db. 563 564 ## Using alternative security labeling 565 566 You can override the default labeling scheme for each container by specifying 567 the `--security-opt` flag. For example, you can specify the MCS/MLS level, a 568 requirement for MLS systems. Specifying the level in the following command 569 allows you to share the same content between containers. 570 571 # docker run --security-opt label:level:s0:c100,c200 -i -t fedora bash 572 573 An MLS example might be: 574 575 # docker run --security-opt label:level:TopSecret -i -t rhel7 bash 576 577 To disable the security labeling for this container versus running with the 578 `--permissive` flag, use the following command: 579 580 # docker run --security-opt label:disable -i -t fedora bash 581 582 If you want a tighter security policy on the processes within a container, 583 you can specify an alternate type for the container. You could run a container 584 that is only allowed to listen on Apache ports by executing the following 585 command: 586 587 # docker run --security-opt label:type:svirt_apache_t -i -t centos bash 588 589 Note: 590 591 You would have to write policy defining a `svirt_apache_t` type. 592 593 # HISTORY 594 April 2014, Originally compiled by William Henry (whenry at redhat dot com) 595 based on docker.com source material and internal work. 596 June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> 597 July 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>