github.com/netbrain/docker@v1.9.0-rc2/docs/reference/commandline/run.md (about) 1 <!--[metadata]> 2 +++ 3 title = "run" 4 description = "The run command description and usage" 5 keywords = ["run, command, container"] 6 [menu.main] 7 parent = "smn_cli" 8 +++ 9 <![end-metadata]--> 10 11 # run 12 13 Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...] 14 15 Run a command in a new container 16 17 -a, --attach=[] Attach to STDIN, STDOUT or STDERR 18 --add-host=[] Add a custom host-to-IP mapping (host:ip) 19 --blkio-weight=0 Block IO weight (relative weight) 20 --cpu-shares=0 CPU shares (relative weight) 21 --cap-add=[] Add Linux capabilities 22 --cap-drop=[] Drop Linux capabilities 23 --cgroup-parent="" Optional parent cgroup for the container 24 --cidfile="" Write the container ID to the file 25 --cpu-period=0 Limit CPU CFS (Completely Fair Scheduler) period 26 --cpu-quota=0 Limit CPU CFS (Completely Fair Scheduler) quota 27 --cpuset-cpus="" CPUs in which to allow execution (0-3, 0,1) 28 --cpuset-mems="" Memory nodes (MEMs) in which to allow execution (0-3, 0,1) 29 -d, --detach=false Run container in background and print container ID 30 --device=[] Add a host device to the container 31 --disable-content-trust=true Skip image verification 32 --dns=[] Set custom DNS servers 33 --dns-opt=[] Set custom DNS options 34 --dns-search=[] Set custom DNS search domains 35 -e, --env=[] Set environment variables 36 --entrypoint="" Overwrite the default ENTRYPOINT of the image 37 --env-file=[] Read in a file of environment variables 38 --expose=[] Expose a port or a range of ports 39 --group-add=[] Add additional groups to run as 40 -h, --hostname="" Container host name 41 --help=false Print usage 42 -i, --interactive=false Keep STDIN open even if not attached 43 --ipc="" IPC namespace to use 44 --kernel-memory="" Kernel memory limit 45 -l, --label=[] Set metadata on the container (e.g., --label=com.example.key=value) 46 --label-file=[] Read in a file of labels (EOL delimited) 47 --link=[] Add link to another container 48 --log-driver="" Logging driver for container 49 --log-opt=[] Log driver specific options 50 --lxc-conf=[] Add custom lxc options 51 -m, --memory="" Memory limit 52 --mac-address="" Container MAC address (e.g. 92:d0:c6:0a:29:33) 53 --memory-reservation="" Memory soft limit 54 --memory-swap="" Total memory (memory + swap), '-1' to disable swap 55 --memory-swappiness="" Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. 56 --name="" Assign a name to the container 57 --net="default" Set the Network mode for the container 58 --oom-kill-disable=false Whether to disable OOM Killer for the container or not 59 -P, --publish-all=false Publish all exposed ports to random ports 60 -p, --publish=[] Publish a container's port(s) to the host 61 --pid="" PID namespace to use 62 --privileged=false Give extended privileges to this container 63 --read-only=false Mount the container's root filesystem as read only 64 --restart="no" Restart policy (no, on-failure[:max-retry], always, unless-stopped) 65 --rm=false Automatically remove the container when it exits 66 --security-opt=[] Security Options 67 --sig-proxy=true Proxy received signals to the process 68 --stop-signal="SIGTERM" Signal to stop a container 69 -t, --tty=false Allocate a pseudo-TTY 70 -u, --user="" Username or UID (format: <name|uid>[:<group|gid>]) 71 --ulimit=[] Ulimit options 72 --uts="" UTS namespace to use 73 -v, --volume=[] Bind mount a volume 74 --volumes-from=[] Mount volumes from the specified container(s) 75 -w, --workdir="" Working directory inside the container 76 77 The `docker run` command first `creates` a writeable container layer over the 78 specified image, and then `starts` it using the specified command. That is, 79 `docker run` is equivalent to the API `/containers/create` then 80 `/containers/(id)/start`. A stopped container can be restarted with all its 81 previous changes intact using `docker start`. See `docker ps -a` to view a list 82 of all containers. 83 84 There is detailed information about `docker run` in the [Docker run reference](run.md). 85 86 The `docker run` command can be used in combination with `docker commit` to 87 [*change the command that a container runs*](commit.md). 88 89 See the [Docker User Guide](../../userguide/dockerlinks.md) for more detailed 90 information about the `--expose`, `-p`, `-P` and `--link` parameters, 91 and linking containers. 92 93 ## Examples 94 95 ### Assign name and allocate psuedo-TTY (--name, -it) 96 97 $ docker run --name test -it debian 98 root@d6c0fe130dba:/# exit 13 99 $ echo $? 100 13 101 $ docker ps -a | grep test 102 d6c0fe130dba debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test 103 104 This example runs a container named `test` using the `debian:latest` 105 image. The `-it` instructs Docker to allocate a pseudo-TTY connected to 106 the container's stdin; creating an interactive `bash` shell in the container. 107 In the example, the `bash` shell is quit by entering 108 `exit 13`. This exit code is passed on to the caller of 109 `docker run`, and is recorded in the `test` container's metadata. 110 111 ### Capture container ID (--cidfile) 112 113 $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test" 114 115 This will create a container and print `test` to the console. The `cidfile` 116 flag makes Docker attempt to create a new file and write the container ID to it. 117 If the file exists already, Docker will return an error. Docker will close this 118 file when `docker run` exits. 119 120 ### Full container capabilities (--privileged) 121 122 $ docker run -t -i --rm ubuntu bash 123 root@bc338942ef20:/# mount -t tmpfs none /mnt 124 mount: permission denied 125 126 This will *not* work, because by default, most potentially dangerous kernel 127 capabilities are dropped; including `cap_sys_admin` (which is required to mount 128 filesystems). However, the `--privileged` flag will allow it to run: 129 130 $ docker run --privileged ubuntu bash 131 root@50e3f57e16e6:/# mount -t tmpfs none /mnt 132 root@50e3f57e16e6:/# df -h 133 Filesystem Size Used Avail Use% Mounted on 134 none 1.9G 0 1.9G 0% /mnt 135 136 The `--privileged` flag gives *all* capabilities to the container, and it also 137 lifts all the limitations enforced by the `device` cgroup controller. In other 138 words, the container can then do almost everything that the host can do. This 139 flag exists to allow special use-cases, like running Docker within Docker. 140 141 ### Set working directory (-w) 142 143 $ docker run -w /path/to/dir/ -i -t ubuntu pwd 144 145 The `-w` lets the command being executed inside directory given, here 146 `/path/to/dir/`. If the path does not exists it is created inside the container. 147 148 ### Mount volume (-v, --read-only) 149 150 $ docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd 151 152 The `-v` flag mounts the current working directory into the container. The `-w` 153 lets the command being executed inside the current working directory, by 154 changing into the directory to the value returned by `pwd`. So this 155 combination executes the command using the container, but inside the 156 current working directory. 157 158 $ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash 159 160 When the host directory of a bind-mounted volume doesn't exist, Docker 161 will automatically create this directory on the host for you. In the 162 example above, Docker will create the `/doesnt/exist` 163 folder before starting your container. 164 165 $ docker run --read-only -v /icanwrite busybox touch /icanwrite here 166 167 Volumes can be used in combination with `--read-only` to control where 168 a container writes files. The `--read-only` flag mounts the container's root 169 filesystem as read only prohibiting writes to locations other than the 170 specified volumes for the container. 171 172 $ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v ./static-docker:/usr/bin/docker busybox sh 173 174 By bind-mounting the docker unix socket and statically linked docker 175 binary (such as that provided by [https://get.docker.com]( 176 https://get.docker.com)), you give the container the full access to create and 177 manipulate the host's Docker daemon. 178 179 ### Publish or expose port (-p, --expose) 180 181 $ docker run -p 127.0.0.1:80:8080 ubuntu bash 182 183 This binds port `8080` of the container to port `80` on `127.0.0.1` of 184 the host machine. The [Docker User Guide](../../userguide/dockerlinks.md) 185 explains in detail how to manipulate ports in Docker. 186 187 $ docker run --expose 80 ubuntu bash 188 189 This exposes port `80` of the container for use within a link without 190 publishing the port to the host system's interfaces. The [Docker User 191 Guide](../../userguide/dockerlinks.md) explains in detail how to manipulate 192 ports in Docker. 193 194 ### Set environment variables (-e, --env, --env-file) 195 196 $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash 197 198 This sets environmental variables in the container. For illustration all three 199 flags are shown here. Where `-e`, `--env` take an environment variable and 200 value, or if no `=` is provided, then that variable's current value is passed 201 through (i.e. `$MYVAR1` from the host is set to `$MYVAR1` in the container). 202 When no `=` is provided and that variable is not defined in the client's 203 environment then that variable will be removed from the container's list of 204 environment variables. 205 All three flags, `-e`, `--env` and `--env-file` can be repeated. 206 207 Regardless of the order of these three flags, the `--env-file` are processed 208 first, and then `-e`, `--env` flags. This way, the `-e` or `--env` will 209 override variables as needed. 210 211 $ cat ./env.list 212 TEST_FOO=BAR 213 $ docker run --env TEST_FOO="This is a test" --env-file ./env.list busybox env | grep TEST_FOO 214 TEST_FOO=This is a test 215 216 The `--env-file` flag takes a filename as an argument and expects each line 217 to be in the `VAR=VAL` format, mimicking the argument passed to `--env`. Comment 218 lines need only be prefixed with `#` 219 220 An example of a file passed with `--env-file` 221 222 $ cat ./env.list 223 TEST_FOO=BAR 224 225 # this is a comment 226 TEST_APP_DEST_HOST=10.10.0.127 227 TEST_APP_DEST_PORT=8888 228 _TEST_BAR=FOO 229 TEST_APP_42=magic 230 helloWorld=true 231 123qwe=bar 232 org.spring.config=something 233 234 # pass through this variable from the caller 235 TEST_PASSTHROUGH 236 $ TEST_PASSTHROUGH=howdy docker run --env-file ./env.list busybox env 237 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin 238 HOSTNAME=5198e0745561 239 TEST_FOO=BAR 240 TEST_APP_DEST_HOST=10.10.0.127 241 TEST_APP_DEST_PORT=8888 242 _TEST_BAR=FOO 243 TEST_APP_42=magic 244 helloWorld=true 245 TEST_PASSTHROUGH=howdy 246 HOME=/root 247 123qwe=bar 248 org.spring.config=something 249 250 $ docker run --env-file ./env.list busybox env 251 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin 252 HOSTNAME=5198e0745561 253 TEST_FOO=BAR 254 TEST_APP_DEST_HOST=10.10.0.127 255 TEST_APP_DEST_PORT=8888 256 _TEST_BAR=FOO 257 TEST_APP_42=magic 258 helloWorld=true 259 TEST_PASSTHROUGH= 260 HOME=/root 261 123qwe=bar 262 org.spring.config=something 263 264 ### Set metadata on container (-l, --label, --label-file) 265 266 A label is a `key=value` pair that applies metadata to a container. To label a container with two labels: 267 268 $ docker run -l my-label --label com.example.foo=bar ubuntu bash 269 270 The `my-label` key doesn't specify a value so the label defaults to an empty 271 string(`""`). To add multiple labels, repeat the label flag (`-l` or `--label`). 272 273 The `key=value` must be unique to avoid overwriting the label value. If you 274 specify labels with identical keys but different values, each subsequent value 275 overwrites the previous. Docker uses the last `key=value` you supply. 276 277 Use the `--label-file` flag to load multiple labels from a file. Delimit each 278 label in the file with an EOL mark. The example below loads labels from a 279 labels file in the current directory: 280 281 $ docker run --label-file ./labels ubuntu bash 282 283 The label-file format is similar to the format for loading environment 284 variables. (Unlike environment variables, labels are not visible to processes 285 running inside a container.) The following example illustrates a label-file 286 format: 287 288 com.example.label1="a label" 289 290 # this is a comment 291 com.example.label2=another\ label 292 com.example.label3 293 294 You can load multiple label-files by supplying multiple `--label-file` flags. 295 296 For additional information on working with labels, see [*Labels - custom 297 metadata in Docker*](../../userguide/labels-custom-metadata.md) in the Docker User 298 Guide. 299 300 ### Add link to another container (--link) 301 302 $ docker run --link /redis:redis --name console ubuntu bash 303 304 The `--link` flag will link the container named `/redis` into the newly 305 created container with the alias `redis`. The new container can access the 306 network and environment of the `redis` container via environment variables. 307 The `--link` flag will also just accept the form `<name or id>` in which case 308 the alias will match the name. For instance, you could have written the previous 309 example as: 310 311 $ docker run --link redis --name console ubuntu bash 312 313 The `--name` flag will assign the name `console` to the newly created 314 container. 315 316 ### Mount volumes from container (--volumes-from) 317 318 $ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd 319 320 The `--volumes-from` flag mounts all the defined volumes from the referenced 321 containers. Containers can be specified by repetitions of the `--volumes-from` 322 argument. The container ID may be optionally suffixed with `:ro` or `:rw` to 323 mount the volumes in read-only or read-write mode, respectively. By default, 324 the volumes are mounted in the same mode (read write or read only) as 325 the reference container. 326 327 Labeling systems like SELinux require that proper labels are placed on volume 328 content mounted into a container. Without a label, the security system might 329 prevent the processes running inside the container from using the content. By 330 default, Docker does not change the labels set by the OS. 331 332 To change the label in the container context, you can add either of two suffixes 333 `:z` or `:Z` to the volume mount. These suffixes tell Docker to relabel file 334 objects on the shared volumes. The `z` option tells Docker that two containers 335 share the volume content. As a result, Docker labels the content with a shared 336 content label. Shared volume labels allow all containers to read/write content. 337 The `Z` option tells Docker to label the content with a private unshared label. 338 Only the current container can use a private volume. 339 340 ### Attach to STDIN/STDOUT/STDERR (-a) 341 342 The `-a` flag tells `docker run` to bind to the container's `STDIN`, `STDOUT` 343 or `STDERR`. This makes it possible to manipulate the output and input as 344 needed. 345 346 $ echo "test" | docker run -i -a stdin ubuntu cat - 347 348 This pipes data into a container and prints the container's ID by attaching 349 only to the container's `STDIN`. 350 351 $ docker run -a stderr ubuntu echo test 352 353 This isn't going to print anything unless there's an error because we've 354 only attached to the `STDERR` of the container. The container's logs 355 still store what's been written to `STDERR` and `STDOUT`. 356 357 $ cat somefile | docker run -i -a stdin mybuilder dobuild 358 359 This is how piping a file into a container could be done for a build. 360 The container's ID will be printed after the build is done and the build 361 logs could be retrieved using `docker logs`. This is 362 useful if you need to pipe a file or something else into a container and 363 retrieve the container's ID once the container has finished running. 364 365 ### Add host device to container (--device) 366 367 $ docker run --device=/dev/sdc:/dev/xvdc --device=/dev/sdd --device=/dev/zero:/dev/nulo -i -t ubuntu ls -l /dev/{xvdc,sdd,nulo} 368 brw-rw---- 1 root disk 8, 2 Feb 9 16:05 /dev/xvdc 369 brw-rw---- 1 root disk 8, 3 Feb 9 16:05 /dev/sdd 370 crw-rw-rw- 1 root root 1, 5 Feb 9 16:05 /dev/nulo 371 372 It is often necessary to directly expose devices to a container. The `--device` 373 option enables that. For example, a specific block storage device or loop 374 device or audio device can be added to an otherwise unprivileged container 375 (without the `--privileged` flag) and have the application directly access it. 376 377 By default, the container will be able to `read`, `write` and `mknod` these devices. 378 This can be overridden using a third `:rwm` set of options to each `--device` 379 flag: 380 381 382 $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc 383 384 Command (m for help): q 385 $ docker run --device=/dev/sda:/dev/xvdc:ro --rm -it ubuntu fdisk /dev/xvdc 386 You will not be able to write the partition table. 387 388 Command (m for help): q 389 390 $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc 391 392 Command (m for help): q 393 394 $ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc 395 fdisk: unable to open /dev/xvdc: Operation not permitted 396 397 > **Note:** 398 > `--device` cannot be safely used with ephemeral devices. Block devices 399 > that may be removed should not be added to untrusted containers with 400 > `--device`. 401 402 ### Restart policies (--restart) 403 404 Use Docker's `--restart` to specify a container's *restart policy*. A restart 405 policy controls whether the Docker daemon restarts a container after exit. 406 Docker supports the following restart policies: 407 408 <table> 409 <thead> 410 <tr> 411 <th>Policy</th> 412 <th>Result</th> 413 </tr> 414 </thead> 415 <tbody> 416 <tr> 417 <td><strong>no</strong></td> 418 <td> 419 Do not automatically restart the container when it exits. This is the 420 default. 421 </td> 422 </tr> 423 <tr> 424 <td> 425 <span style="white-space: nowrap"> 426 <strong>on-failure</strong>[:max-retries] 427 </span> 428 </td> 429 <td> 430 Restart only if the container exits with a non-zero exit status. 431 Optionally, limit the number of restart retries the Docker 432 daemon attempts. 433 </td> 434 </tr> 435 <tr> 436 <td><strong>always</strong></td> 437 <td> 438 Always restart the container regardless of the exit status. 439 When you specify always, the Docker daemon will try to restart 440 the container indefinitely. The container will also always start 441 on daemon startup, regardless of the current state of the container. 442 </td> 443 </tr> 444 <tr> 445 <td><strong>unless-stopped</strong></td> 446 <td> 447 Always restart the container regardless of the exit status, but 448 do not start it on daemon startup if the container has been put 449 to a stopped state before. 450 </td> 451 </tr> 452 </tbody> 453 </table> 454 455 $ docker run --restart=always redis 456 457 This will run the `redis` container with a restart policy of **always** 458 so that if the container exits, Docker will restart it. 459 460 More detailed information on restart policies can be found in the 461 [Restart Policies (--restart)](../run.md#restart-policies-restart) 462 section of the Docker run reference page. 463 464 ### Add entries to container hosts file (--add-host) 465 466 You can add other hosts into a container's `/etc/hosts` file by using one or 467 more `--add-host` flags. This example adds a static address for a host named 468 `docker`: 469 470 $ docker run --add-host=docker:10.180.0.1 --rm -it debian 471 $$ ping docker 472 PING docker (10.180.0.1): 48 data bytes 473 56 bytes from 10.180.0.1: icmp_seq=0 ttl=254 time=7.600 ms 474 56 bytes from 10.180.0.1: icmp_seq=1 ttl=254 time=30.705 ms 475 ^C--- docker ping statistics --- 476 2 packets transmitted, 2 packets received, 0% packet loss 477 round-trip min/avg/max/stddev = 7.600/19.152/30.705/11.553 ms 478 479 Sometimes you need to connect to the Docker host from within your 480 container. To enable this, pass the Docker host's IP address to 481 the container using the `--add-host` flag. To find the host's address, 482 use the `ip addr show` command. 483 484 The flags you pass to `ip addr show` depend on whether you are 485 using IPv4 or IPv6 networking in your containers. Use the following 486 flags for IPv4 address retrieval for a network device named `eth0`: 487 488 $ HOSTIP=`ip -4 addr show scope global dev eth0 | grep inet | awk '{print \$2}' | cut -d / -f 1` 489 $ docker run --add-host=docker:${HOSTIP} --rm -it debian 490 491 For IPv6 use the `-6` flag instead of the `-4` flag. For other network 492 devices, replace `eth0` with the correct device name (for example `docker0` 493 for the bridge device). 494 495 ### Set ulimits in container (--ulimit) 496 497 Since setting `ulimit` settings in a container requires extra privileges not 498 available in the default container, you can set these using the `--ulimit` flag. 499 `--ulimit` is specified with a soft and hard limit as such: 500 `<type>=<soft limit>[:<hard limit>]`, for example: 501 502 $ docker run --ulimit nofile=1024:1024 --rm debian ulimit -n 503 1024 504 505 > **Note:** 506 > If you do not provide a `hard limit`, the `soft limit` will be used 507 > for both values. If no `ulimits` are set, they will be inherited from 508 > the default `ulimits` set on the daemon. `as` option is disabled now. 509 > In other words, the following script is not supported: 510 > `$ docker run -it --ulimit as=1024 fedora /bin/bash` 511 512 The values are sent to the appropriate `syscall` as they are set. 513 Docker doesn't perform any byte conversion. Take this into account when setting the values. 514 515 #### For `nproc` usage 516 517 Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linux to set the 518 maximum number of processes available to a user, not to a container. For example, start four 519 containers with `daemon` user: 520 521 docker run -d -u daemon --ulimit nproc=3 busybox top 522 docker run -d -u daemon --ulimit nproc=3 busybox top 523 docker run -d -u daemon --ulimit nproc=3 busybox top 524 docker run -d -u daemon --ulimit nproc=3 busybox top 525 526 The 4th container fails and reports "[8] System error: resource temporarily unavailable" error. 527 This fails because the caller set `nproc=3` resulting in the first three containers using up 528 the three processes quota set for the `daemon` user. 529 530 ### Stop container with signal (--stop-signal) 531 532 The `--stop-signal` flag sets the system call signal that will be sent to the container to exit. 533 This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9, 534 or a signal name in the format SIGNAME, for instance SIGKILL. 535 536 ### A complete example 537 538 $ docker run -d --name static static-web-files sh 539 $ docker run -d --expose=8098 --name riak riakserver 540 $ docker run -d -m 100m -e DEVELOPMENT=1 -e BRANCH=example-code -v $(pwd):/app/bin:ro --name app appserver 541 $ docker run -d -p 1443:443 --dns=10.0.0.1 --dns-search=dev.org -v /var/log/httpd --volumes-from static --link riak --link app -h www.sven.dev.org --name web webserver 542 $ docker run -t -i --rm --volumes-from web -w /var/log/httpd busybox tail -f access.log 543 544 This example shows five containers that might be set up to test a web 545 application change: 546 547 1. Start a pre-prepared volume image `static-web-files` (in the background) 548 that has CSS, image and static HTML in it, (with a `VOLUME` instruction in 549 the Dockerfile to allow the web server to use those files); 550 2. Start a pre-prepared `riakserver` image, give the container name `riak` and 551 expose port `8098` to any containers that link to it; 552 3. Start the `appserver` image, restricting its memory usage to 100MB, setting 553 two environment variables `DEVELOPMENT` and `BRANCH` and bind-mounting the 554 current directory (`$(pwd)`) in the container in read-only mode as `/app/bin`; 555 4. Start the `webserver`, mapping port `443` in the container to port `1443` on 556 the Docker server, setting the DNS server to `10.0.0.1` and DNS search 557 domain to `dev.org`, creating a volume to put the log files into (so we can 558 access it from another container), then importing the files from the volume 559 exposed by the `static` container, and linking to all exposed ports from 560 `riak` and `app`. Lastly, we set the hostname to `web.sven.dev.org` so its 561 consistent with the pre-generated SSL certificate; 562 5. Finally, we create a container that runs `tail -f access.log` using the logs 563 volume from the `web` container, setting the workdir to `/var/log/httpd`. The 564 `--rm` option means that when the container exits, the container's layer is 565 removed.