github.com/kelda-inc/moby@v1.13.1/docs/reference/commandline/run.md (about) 1 --- 2 title: "run" 3 description: "The run command description and usage" 4 keywords: "run, command, container" 5 --- 6 7 <!-- This file is maintained within the docker/docker Github 8 repository at https://github.com/docker/docker/. Make all 9 pull requests against that repo. If you see this file in 10 another repository, consider it read-only there, as it will 11 periodically be overwritten by the definitive file. Pull 12 requests which include edits to this file in other repositories 13 will be rejected. 14 --> 15 16 # run 17 18 ```markdown 19 Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...] 20 21 Run a command in a new container 22 23 Options: 24 --add-host value Add a custom host-to-IP mapping (host:ip) (default []) 25 -a, --attach value Attach to STDIN, STDOUT or STDERR (default []) 26 --blkio-weight value Block IO (relative weight), between 10 and 1000 27 --blkio-weight-device value Block IO weight (relative device weight) (default []) 28 --cap-add value Add Linux capabilities (default []) 29 --cap-drop value Drop Linux capabilities (default []) 30 --cgroup-parent string Optional parent cgroup for the container 31 --cidfile string Write the container ID to the file 32 --cpu-count int The number of CPUs available for execution by the container. 33 Windows daemon only. On Windows Server containers, this is 34 approximated as a percentage of total CPU usage. 35 --cpu-percent int Limit percentage of CPU available for execution 36 by the container. Windows daemon only. 37 The processor resource controls are mutually 38 exclusive, the order of precedence is CPUCount 39 first, then CPUShares, and CPUPercent last. 40 --cpu-period int Limit CPU CFS (Completely Fair Scheduler) period 41 --cpu-quota int Limit CPU CFS (Completely Fair Scheduler) quota 42 -c, --cpu-shares int CPU shares (relative weight) 43 --cpus NanoCPUs Number of CPUs (default 0.000) 44 --cpu-rt-period int Limit the CPU real-time period in microseconds 45 --cpu-rt-runtime int Limit the CPU real-time runtime in microseconds 46 --cpuset-cpus string CPUs in which to allow execution (0-3, 0,1) 47 --cpuset-mems string MEMs in which to allow execution (0-3, 0,1) 48 -d, --detach Run container in background and print container ID 49 --detach-keys string Override the key sequence for detaching a container 50 --device value Add a host device to the container (default []) 51 --device-read-bps value Limit read rate (bytes per second) from a device (default []) 52 --device-read-iops value Limit read rate (IO per second) from a device (default []) 53 --device-write-bps value Limit write rate (bytes per second) to a device (default []) 54 --device-write-iops value Limit write rate (IO per second) to a device (default []) 55 --disable-content-trust Skip image verification (default true) 56 --dns value Set custom DNS servers (default []) 57 --dns-option value Set DNS options (default []) 58 --dns-search value Set custom DNS search domains (default []) 59 --entrypoint string Overwrite the default ENTRYPOINT of the image 60 -e, --env value Set environment variables (default []) 61 --env-file value Read in a file of environment variables (default []) 62 --expose value Expose a port or a range of ports (default []) 63 --group-add value Add additional groups to join (default []) 64 --health-cmd string Command to run to check health 65 --health-interval duration Time between running the check (ns|us|ms|s|m|h) (default 0s) 66 --health-retries int Consecutive failures needed to report unhealthy 67 --health-timeout duration Maximum time to allow one check to run (ns|us|ms|s|m|h) (default 0s) 68 --help Print usage 69 -h, --hostname string Container host name 70 --init Run an init inside the container that forwards signals and reaps processes 71 --init-path string Path to the docker-init binary 72 -i, --interactive Keep STDIN open even if not attached 73 --io-maxbandwidth string Maximum IO bandwidth limit for the system drive (Windows only) 74 (Windows only). The format is `<number><unit>`. 75 Unit is optional and can be `b` (bytes per second), 76 `k` (kilobytes per second), `m` (megabytes per second), 77 or `g` (gigabytes per second). If you omit the unit, 78 the system uses bytes per second. 79 --io-maxbandwidth and --io-maxiops are mutually exclusive options. 80 --io-maxiops uint Maximum IOps limit for the system drive (Windows only) 81 --ip string Container IPv4 address (e.g. 172.30.100.104) 82 --ip6 string Container IPv6 address (e.g. 2001:db8::33) 83 --ipc string IPC namespace to use 84 --isolation string Container isolation technology 85 --kernel-memory string Kernel memory limit 86 -l, --label value Set meta data on a container (default []) 87 --label-file value Read in a line delimited file of labels (default []) 88 --link value Add link to another container (default []) 89 --link-local-ip value Container IPv4/IPv6 link-local addresses (default []) 90 --log-driver string Logging driver for the container 91 --log-opt value Log driver options (default []) 92 --mac-address string Container MAC address (e.g. 92:d0:c6:0a:29:33) 93 -m, --memory string Memory limit 94 --memory-reservation string Memory soft limit 95 --memory-swap string Swap limit equal to memory plus swap: '-1' to enable unlimited swap 96 --memory-swappiness int Tune container memory swappiness (0 to 100) (default -1) 97 --name string Assign a name to the container 98 --network-alias value Add network-scoped alias for the container (default []) 99 --network string Connect a container to a network 100 'bridge': create a network stack on the default Docker bridge 101 'none': no networking 102 'container:<name|id>': reuse another container's network stack 103 'host': use the Docker host network stack 104 '<network-name>|<network-id>': connect to a user-defined network 105 --no-healthcheck Disable any container-specified HEALTHCHECK 106 --oom-kill-disable Disable OOM Killer 107 --oom-score-adj int Tune host's OOM preferences (-1000 to 1000) 108 --pid string PID namespace to use 109 --pids-limit int Tune container pids limit (set -1 for unlimited) 110 --privileged Give extended privileges to this container 111 -p, --publish value Publish a container's port(s) to the host (default []) 112 -P, --publish-all Publish all exposed ports to random ports 113 --read-only Mount the container's root filesystem as read only 114 --restart string Restart policy to apply when a container exits (default "no") 115 Possible values are : no, on-failure[:max-retry], always, unless-stopped 116 --rm Automatically remove the container when it exits 117 --runtime string Runtime to use for this container 118 --security-opt value Security Options (default []) 119 --shm-size string Size of /dev/shm, default value is 64MB. 120 The format is `<number><unit>`. `number` must be greater than `0`. 121 Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), 122 or `g` (gigabytes). If you omit the unit, the system uses bytes. 123 --sig-proxy Proxy received signals to the process (default true) 124 --stop-signal string Signal to stop a container, SIGTERM by default (default "SIGTERM") 125 --stop-timeout=10 Timeout (in seconds) to stop a container 126 --storage-opt value Storage driver options for the container (default []) 127 --sysctl value Sysctl options (default map[]) 128 --tmpfs value Mount a tmpfs directory (default []) 129 -t, --tty Allocate a pseudo-TTY 130 --ulimit value Ulimit options (default []) 131 -u, --user string Username or UID (format: <name|uid>[:<group|gid>]) 132 --userns string User namespace to use 133 'host': Use the Docker host user namespace 134 '': Use the Docker daemon user namespace specified by `--userns-remap` option. 135 --uts string UTS namespace to use 136 -v, --volume value Bind mount a volume (default []). The format 137 is `[host-src:]container-dest[:<options>]`. 138 The comma-delimited `options` are [rw|ro], 139 [z|Z], [[r]shared|[r]slave|[r]private], and 140 [nocopy]. The 'host-src' is an absolute path 141 or a name value. 142 --volume-driver string Optional volume driver for the container 143 --volumes-from value Mount volumes from the specified container(s) (default []) 144 -w, --workdir string Working directory inside the container 145 ``` 146 147 The `docker run` command first `creates` a writeable container layer over the 148 specified image, and then `starts` it using the specified command. That is, 149 `docker run` is equivalent to the API `/containers/create` then 150 `/containers/(id)/start`. A stopped container can be restarted with all its 151 previous changes intact using `docker start`. See `docker ps -a` to view a list 152 of all containers. 153 154 The `docker run` command can be used in combination with `docker commit` to 155 [*change the command that a container runs*](commit.md). There is additional detailed information about `docker run` in the [Docker run reference](../run.md). 156 157 For information on connecting a container to a network, see the ["*Docker network overview*"](https://docs.docker.com/engine/userguide/networking/). 158 159 ## Examples 160 161 ### Assign name and allocate pseudo-TTY (--name, -it) 162 163 $ docker run --name test -it debian 164 root@d6c0fe130dba:/# exit 13 165 $ echo $? 166 13 167 $ docker ps -a | grep test 168 d6c0fe130dba debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test 169 170 This example runs a container named `test` using the `debian:latest` 171 image. The `-it` instructs Docker to allocate a pseudo-TTY connected to 172 the container's stdin; creating an interactive `bash` shell in the container. 173 In the example, the `bash` shell is quit by entering 174 `exit 13`. This exit code is passed on to the caller of 175 `docker run`, and is recorded in the `test` container's metadata. 176 177 ### Capture container ID (--cidfile) 178 179 $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test" 180 181 This will create a container and print `test` to the console. The `cidfile` 182 flag makes Docker attempt to create a new file and write the container ID to it. 183 If the file exists already, Docker will return an error. Docker will close this 184 file when `docker run` exits. 185 186 ### Full container capabilities (--privileged) 187 188 $ docker run -t -i --rm ubuntu bash 189 root@bc338942ef20:/# mount -t tmpfs none /mnt 190 mount: permission denied 191 192 This will *not* work, because by default, most potentially dangerous kernel 193 capabilities are dropped; including `cap_sys_admin` (which is required to mount 194 filesystems). However, the `--privileged` flag will allow it to run: 195 196 $ docker run -t -i --privileged ubuntu bash 197 root@50e3f57e16e6:/# mount -t tmpfs none /mnt 198 root@50e3f57e16e6:/# df -h 199 Filesystem Size Used Avail Use% Mounted on 200 none 1.9G 0 1.9G 0% /mnt 201 202 The `--privileged` flag gives *all* capabilities to the container, and it also 203 lifts all the limitations enforced by the `device` cgroup controller. In other 204 words, the container can then do almost everything that the host can do. This 205 flag exists to allow special use-cases, like running Docker within Docker. 206 207 ### Set working directory (-w) 208 209 $ docker run -w /path/to/dir/ -i -t ubuntu pwd 210 211 The `-w` lets the command being executed inside directory given, here 212 `/path/to/dir/`. If the path does not exist it is created inside the container. 213 214 ### Set storage driver options per container 215 216 $ docker run -it --storage-opt size=120G fedora /bin/bash 217 218 This (size) will allow to set the container rootfs size to 120G at creation time. 219 This option is only available for the `devicemapper`, `btrfs`, `overlay2`, 220 `windowsfilter` and `zfs` graph drivers. 221 For the `devicemapper`, `btrfs`, `windowsfilter` and `zfs` graph drivers, 222 user cannot pass a size less than the Default BaseFS Size. 223 For the `overlay2` storage driver, the size option is only available if the 224 backing fs is `xfs` and mounted with the `pquota` mount option. 225 Under these conditions, user can pass any size less then the backing fs size. 226 227 ### Mount tmpfs (--tmpfs) 228 229 $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image 230 231 The `--tmpfs` flag mounts an empty tmpfs into the container with the `rw`, 232 `noexec`, `nosuid`, `size=65536k` options. 233 234 ### Mount volume (-v, --read-only) 235 236 $ docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd 237 238 The `-v` flag mounts the current working directory into the container. The `-w` 239 lets the command being executed inside the current working directory, by 240 changing into the directory to the value returned by `pwd`. So this 241 combination executes the command using the container, but inside the 242 current working directory. 243 244 $ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash 245 246 When the host directory of a bind-mounted volume doesn't exist, Docker 247 will automatically create this directory on the host for you. In the 248 example above, Docker will create the `/doesnt/exist` 249 folder before starting your container. 250 251 $ docker run --read-only -v /icanwrite busybox touch /icanwrite/here 252 253 Volumes can be used in combination with `--read-only` to control where 254 a container writes files. The `--read-only` flag mounts the container's root 255 filesystem as read only prohibiting writes to locations other than the 256 specified volumes for the container. 257 258 $ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/static-docker-binary:/usr/bin/docker busybox sh 259 260 By bind-mounting the docker unix socket and statically linked docker 261 binary (refer to [get the linux binary]( 262 https://docs.docker.com/engine/installation/binaries/#/get-the-linux-binary)), 263 you give the container the full access to create and manipulate the host's 264 Docker daemon. 265 266 On Windows, the paths must be specified using Windows-style semantics. 267 268 PS C:\> docker run -v c:\foo:c:\dest microsoft/nanoserver cmd /s /c type c:\dest\somefile.txt 269 Contents of file 270 271 PS C:\> docker run -v c:\foo:d: microsoft/nanoserver cmd /s /c type d:\somefile.txt 272 Contents of file 273 274 The following examples will fail when using Windows-based containers, as the 275 destination of a volume or bind-mount inside the container must be one of: 276 a non-existing or empty directory; or a drive other than C:. Further, the source 277 of a bind mount must be a local directory, not a file. 278 279 net use z: \\remotemachine\share 280 docker run -v z:\foo:c:\dest ... 281 docker run -v \\uncpath\to\directory:c:\dest ... 282 docker run -v c:\foo\somefile.txt:c:\dest ... 283 docker run -v c:\foo:c: ... 284 docker run -v c:\foo:c:\existing-directory-with-contents ... 285 286 For in-depth information about volumes, refer to [manage data in containers](https://docs.docker.com/engine/tutorials/dockervolumes/) 287 288 ### Publish or expose port (-p, --expose) 289 290 $ docker run -p 127.0.0.1:80:8080 ubuntu bash 291 292 This binds port `8080` of the container to port `80` on `127.0.0.1` of the host 293 machine. The [Docker User 294 Guide](https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/) 295 explains in detail how to manipulate ports in Docker. 296 297 $ docker run --expose 80 ubuntu bash 298 299 This exposes port `80` of the container without publishing the port to the host 300 system's interfaces. 301 302 ### Set environment variables (-e, --env, --env-file) 303 304 $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash 305 306 This sets simple (non-array) environmental variables in the container. For 307 illustration all three 308 flags are shown here. Where `-e`, `--env` take an environment variable and 309 value, or if no `=` is provided, then that variable's current value, set via 310 `export`, is passed through (i.e. `$MYVAR1` from the host is set to `$MYVAR1` 311 in the container). When no `=` is provided and that variable is not defined 312 in the client's environment then that variable will be removed from the 313 container's list of environment variables. All three flags, `-e`, `--env` and 314 `--env-file` can be repeated. 315 316 Regardless of the order of these three flags, the `--env-file` are processed 317 first, and then `-e`, `--env` flags. This way, the `-e` or `--env` will 318 override variables as needed. 319 320 $ cat ./env.list 321 TEST_FOO=BAR 322 $ docker run --env TEST_FOO="This is a test" --env-file ./env.list busybox env | grep TEST_FOO 323 TEST_FOO=This is a test 324 325 The `--env-file` flag takes a filename as an argument and expects each line 326 to be in the `VAR=VAL` format, mimicking the argument passed to `--env`. Comment 327 lines need only be prefixed with `#` 328 329 An example of a file passed with `--env-file` 330 331 $ cat ./env.list 332 TEST_FOO=BAR 333 334 # this is a comment 335 TEST_APP_DEST_HOST=10.10.0.127 336 TEST_APP_DEST_PORT=8888 337 _TEST_BAR=FOO 338 TEST_APP_42=magic 339 helloWorld=true 340 123qwe=bar 341 org.spring.config=something 342 343 # pass through this variable from the caller 344 TEST_PASSTHROUGH 345 $ TEST_PASSTHROUGH=howdy docker run --env-file ./env.list busybox env 346 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin 347 HOSTNAME=5198e0745561 348 TEST_FOO=BAR 349 TEST_APP_DEST_HOST=10.10.0.127 350 TEST_APP_DEST_PORT=8888 351 _TEST_BAR=FOO 352 TEST_APP_42=magic 353 helloWorld=true 354 TEST_PASSTHROUGH=howdy 355 HOME=/root 356 123qwe=bar 357 org.spring.config=something 358 359 $ docker run --env-file ./env.list busybox env 360 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin 361 HOSTNAME=5198e0745561 362 TEST_FOO=BAR 363 TEST_APP_DEST_HOST=10.10.0.127 364 TEST_APP_DEST_PORT=8888 365 _TEST_BAR=FOO 366 TEST_APP_42=magic 367 helloWorld=true 368 TEST_PASSTHROUGH= 369 HOME=/root 370 123qwe=bar 371 org.spring.config=something 372 373 ### Set metadata on container (-l, --label, --label-file) 374 375 A label is a `key=value` pair that applies metadata to a container. To label a container with two labels: 376 377 $ docker run -l my-label --label com.example.foo=bar ubuntu bash 378 379 The `my-label` key doesn't specify a value so the label defaults to an empty 380 string(`""`). To add multiple labels, repeat the label flag (`-l` or `--label`). 381 382 The `key=value` must be unique to avoid overwriting the label value. If you 383 specify labels with identical keys but different values, each subsequent value 384 overwrites the previous. Docker uses the last `key=value` you supply. 385 386 Use the `--label-file` flag to load multiple labels from a file. Delimit each 387 label in the file with an EOL mark. The example below loads labels from a 388 labels file in the current directory: 389 390 $ docker run --label-file ./labels ubuntu bash 391 392 The label-file format is similar to the format for loading environment 393 variables. (Unlike environment variables, labels are not visible to processes 394 running inside a container.) The following example illustrates a label-file 395 format: 396 397 com.example.label1="a label" 398 399 # this is a comment 400 com.example.label2=another\ label 401 com.example.label3 402 403 You can load multiple label-files by supplying multiple `--label-file` flags. 404 405 For additional information on working with labels, see [*Labels - custom 406 metadata in Docker*](https://docs.docker.com/engine/userguide/labels-custom-metadata/) in the Docker User 407 Guide. 408 409 ### Connect a container to a network (--network) 410 411 When you start a container use the `--network` flag to connect it to a network. 412 This adds the `busybox` container to the `my-net` network. 413 414 ```bash 415 $ docker run -itd --network=my-net busybox 416 ``` 417 418 You can also choose the IP addresses for the container with `--ip` and `--ip6` 419 flags when you start the container on a user-defined network. 420 421 ```bash 422 $ docker run -itd --network=my-net --ip=10.10.9.75 busybox 423 ``` 424 425 If you want to add a running container to a network use the `docker network connect` subcommand. 426 427 You can connect multiple containers to the same network. Once connected, the 428 containers can communicate easily need only another container's IP address 429 or name. For `overlay` networks or custom plugins that support multi-host 430 connectivity, containers connected to the same multi-host network but launched 431 from different Engines can also communicate in this way. 432 433 **Note**: Service discovery is unavailable on the default bridge network. 434 Containers can communicate via their IP addresses by default. To communicate 435 by name, they must be linked. 436 437 You can disconnect a container from a network using the `docker network 438 disconnect` command. 439 440 ### Mount volumes from container (--volumes-from) 441 442 $ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd 443 444 The `--volumes-from` flag mounts all the defined volumes from the referenced 445 containers. Containers can be specified by repetitions of the `--volumes-from` 446 argument. The container ID may be optionally suffixed with `:ro` or `:rw` to 447 mount the volumes in read-only or read-write mode, respectively. By default, 448 the volumes are mounted in the same mode (read write or read only) as 449 the reference container. 450 451 Labeling systems like SELinux require that proper labels are placed on volume 452 content mounted into a container. Without a label, the security system might 453 prevent the processes running inside the container from using the content. By 454 default, Docker does not change the labels set by the OS. 455 456 To change the label in the container context, you can add either of two suffixes 457 `:z` or `:Z` to the volume mount. These suffixes tell Docker to relabel file 458 objects on the shared volumes. The `z` option tells Docker that two containers 459 share the volume content. As a result, Docker labels the content with a shared 460 content label. Shared volume labels allow all containers to read/write content. 461 The `Z` option tells Docker to label the content with a private unshared label. 462 Only the current container can use a private volume. 463 464 ### Attach to STDIN/STDOUT/STDERR (-a) 465 466 The `-a` flag tells `docker run` to bind to the container's `STDIN`, `STDOUT` 467 or `STDERR`. This makes it possible to manipulate the output and input as 468 needed. 469 470 $ echo "test" | docker run -i -a stdin ubuntu cat - 471 472 This pipes data into a container and prints the container's ID by attaching 473 only to the container's `STDIN`. 474 475 $ docker run -a stderr ubuntu echo test 476 477 This isn't going to print anything unless there's an error because we've 478 only attached to the `STDERR` of the container. The container's logs 479 still store what's been written to `STDERR` and `STDOUT`. 480 481 $ cat somefile | docker run -i -a stdin mybuilder dobuild 482 483 This is how piping a file into a container could be done for a build. 484 The container's ID will be printed after the build is done and the build 485 logs could be retrieved using `docker logs`. This is 486 useful if you need to pipe a file or something else into a container and 487 retrieve the container's ID once the container has finished running. 488 489 ### Add host device to container (--device) 490 491 $ docker run --device=/dev/sdc:/dev/xvdc --device=/dev/sdd --device=/dev/zero:/dev/nulo -i -t ubuntu ls -l /dev/{xvdc,sdd,nulo} 492 brw-rw---- 1 root disk 8, 2 Feb 9 16:05 /dev/xvdc 493 brw-rw---- 1 root disk 8, 3 Feb 9 16:05 /dev/sdd 494 crw-rw-rw- 1 root root 1, 5 Feb 9 16:05 /dev/nulo 495 496 It is often necessary to directly expose devices to a container. The `--device` 497 option enables that. For example, a specific block storage device or loop 498 device or audio device can be added to an otherwise unprivileged container 499 (without the `--privileged` flag) and have the application directly access it. 500 501 By default, the container will be able to `read`, `write` and `mknod` these devices. 502 This can be overridden using a third `:rwm` set of options to each `--device` 503 flag: 504 505 506 $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc 507 508 Command (m for help): q 509 $ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk /dev/xvdc 510 You will not be able to write the partition table. 511 512 Command (m for help): q 513 514 $ docker run --device=/dev/sda:/dev/xvdc:rw --rm -it ubuntu fdisk /dev/xvdc 515 516 Command (m for help): q 517 518 $ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc 519 fdisk: unable to open /dev/xvdc: Operation not permitted 520 521 > **Note:** 522 > `--device` cannot be safely used with ephemeral devices. Block devices 523 > that may be removed should not be added to untrusted containers with 524 > `--device`. 525 526 ### Restart policies (--restart) 527 528 Use Docker's `--restart` to specify a container's *restart policy*. A restart 529 policy controls whether the Docker daemon restarts a container after exit. 530 Docker supports the following restart policies: 531 532 <table> 533 <thead> 534 <tr> 535 <th>Policy</th> 536 <th>Result</th> 537 </tr> 538 </thead> 539 <tbody> 540 <tr> 541 <td><strong>no</strong></td> 542 <td> 543 Do not automatically restart the container when it exits. This is the 544 default. 545 </td> 546 </tr> 547 <tr> 548 <td> 549 <span style="white-space: nowrap"> 550 <strong>on-failure</strong>[:max-retries] 551 </span> 552 </td> 553 <td> 554 Restart only if the container exits with a non-zero exit status. 555 Optionally, limit the number of restart retries the Docker 556 daemon attempts. 557 </td> 558 </tr> 559 <tr> 560 <td><strong>always</strong></td> 561 <td> 562 Always restart the container regardless of the exit status. 563 When you specify always, the Docker daemon will try to restart 564 the container indefinitely. The container will also always start 565 on daemon startup, regardless of the current state of the container. 566 </td> 567 </tr> 568 <tr> 569 <td><strong>unless-stopped</strong></td> 570 <td> 571 Always restart the container regardless of the exit status, but 572 do not start it on daemon startup if the container has been put 573 to a stopped state before. 574 </td> 575 </tr> 576 </tbody> 577 </table> 578 579 $ docker run --restart=always redis 580 581 This will run the `redis` container with a restart policy of **always** 582 so that if the container exits, Docker will restart it. 583 584 More detailed information on restart policies can be found in the 585 [Restart Policies (--restart)](../run.md#restart-policies-restart) 586 section of the Docker run reference page. 587 588 ### Add entries to container hosts file (--add-host) 589 590 You can add other hosts into a container's `/etc/hosts` file by using one or 591 more `--add-host` flags. This example adds a static address for a host named 592 `docker`: 593 594 $ docker run --add-host=docker:10.180.0.1 --rm -it debian 595 root@f38c87f2a42d:/# ping docker 596 PING docker (10.180.0.1): 48 data bytes 597 56 bytes from 10.180.0.1: icmp_seq=0 ttl=254 time=7.600 ms 598 56 bytes from 10.180.0.1: icmp_seq=1 ttl=254 time=30.705 ms 599 ^C--- docker ping statistics --- 600 2 packets transmitted, 2 packets received, 0% packet loss 601 round-trip min/avg/max/stddev = 7.600/19.152/30.705/11.553 ms 602 603 Sometimes you need to connect to the Docker host from within your 604 container. To enable this, pass the Docker host's IP address to 605 the container using the `--add-host` flag. To find the host's address, 606 use the `ip addr show` command. 607 608 The flags you pass to `ip addr show` depend on whether you are 609 using IPv4 or IPv6 networking in your containers. Use the following 610 flags for IPv4 address retrieval for a network device named `eth0`: 611 612 $ HOSTIP=`ip -4 addr show scope global dev eth0 | grep inet | awk '{print \$2}' | cut -d / -f 1` 613 $ docker run --add-host=docker:${HOSTIP} --rm -it debian 614 615 For IPv6 use the `-6` flag instead of the `-4` flag. For other network 616 devices, replace `eth0` with the correct device name (for example `docker0` 617 for the bridge device). 618 619 ### Set ulimits in container (--ulimit) 620 621 Since setting `ulimit` settings in a container requires extra privileges not 622 available in the default container, you can set these using the `--ulimit` flag. 623 `--ulimit` is specified with a soft and hard limit as such: 624 `<type>=<soft limit>[:<hard limit>]`, for example: 625 626 $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n" 627 1024 628 629 > **Note:** 630 > If you do not provide a `hard limit`, the `soft limit` will be used 631 > for both values. If no `ulimits` are set, they will be inherited from 632 > the default `ulimits` set on the daemon. `as` option is disabled now. 633 > In other words, the following script is not supported: 634 > `$ docker run -it --ulimit as=1024 fedora /bin/bash` 635 636 The values are sent to the appropriate `syscall` as they are set. 637 Docker doesn't perform any byte conversion. Take this into account when setting the values. 638 639 #### For `nproc` usage 640 641 Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linux to set the 642 maximum number of processes available to a user, not to a container. For example, start four 643 containers with `daemon` user: 644 645 docker run -d -u daemon --ulimit nproc=3 busybox top 646 docker run -d -u daemon --ulimit nproc=3 busybox top 647 docker run -d -u daemon --ulimit nproc=3 busybox top 648 docker run -d -u daemon --ulimit nproc=3 busybox top 649 650 The 4th container fails and reports "[8] System error: resource temporarily unavailable" error. 651 This fails because the caller set `nproc=3` resulting in the first three containers using up 652 the three processes quota set for the `daemon` user. 653 654 ### Stop container with signal (--stop-signal) 655 656 The `--stop-signal` flag sets the system call signal that will be sent to the container to exit. 657 This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9, 658 or a signal name in the format SIGNAME, for instance SIGKILL. 659 660 ### Optional security options (--security-opt) 661 662 On Windows, this flag can be used to specify the `credentialspec` option. 663 The `credentialspec` must be in the format `file://spec.txt` or `registry://keyname`. 664 665 ### Stop container with timeout (--stop-timeout) 666 667 The `--stop-timeout` flag sets the timeout (in seconds) that a pre-defined (see `--stop-signal`) system call 668 signal that will be sent to the container to exit. After timeout elapses the container will be killed with SIGKILL. 669 670 ### Specify isolation technology for container (--isolation) 671 672 This option is useful in situations where you are running Docker containers on 673 Microsoft Windows. The `--isolation <value>` option sets a container's isolation 674 technology. On Linux, the only supported is the `default` option which uses 675 Linux namespaces. These two commands are equivalent on Linux: 676 677 ``` 678 $ docker run -d busybox top 679 $ docker run -d --isolation default busybox top 680 ``` 681 682 On Microsoft Windows, can take any of these values: 683 684 685 | Value | Description | 686 |-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| 687 | `default` | Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. | 688 | `process` | Namespace isolation only. | 689 | `hyperv` | Hyper-V hypervisor partition-based isolation. | 690 691 On Windows, the default isolation for client is `hyperv`, and for server is 692 `process`. Therefore when running on Windows server without a `daemon` option 693 set, these two commands are equivalent: 694 ``` 695 $ docker run -d --isolation default busybox top 696 $ docker run -d --isolation process busybox top 697 ``` 698 699 If you have set the `--exec-opt isolation=hyperv` option on the Docker `daemon`, 700 if running on Windows server, any of these commands also result in `hyperv` isolation: 701 702 ``` 703 $ docker run -d --isolation default busybox top 704 $ docker run -d --isolation hyperv busybox top 705 ``` 706 707 ### Configure namespaced kernel parameters (sysctls) at runtime 708 709 The `--sysctl` sets namespaced kernel parameters (sysctls) in the 710 container. For example, to turn on IP forwarding in the containers 711 network namespace, run this command: 712 713 $ docker run --sysctl net.ipv4.ip_forward=1 someimage 714 715 716 > **Note**: Not all sysctls are namespaced. Docker does not support changing sysctls 717 > inside of a container that also modify the host system. As the kernel 718 > evolves we expect to see more sysctls become namespaced. 719 720 #### Currently supported sysctls 721 722 `IPC Namespace`: 723 724 kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced 725 Sysctls beginning with fs.mqueue.* 726 727 If you use the `--ipc=host` option these sysctls will not be allowed. 728 729 `Network Namespace`: 730 Sysctls beginning with net.* 731 732 If you use the `--network=host` option using these sysctls will not be allowed.