github.com/panekj/cli@v0.0.0-20230304125325-467dd2f3797e/docs/reference/commandline/run.md (about) 1 # run 2 3 <!---MARKER_GEN_START--> 4 Create and run a new container from an image 5 6 ### Aliases 7 8 `docker container run`, `docker run` 9 10 ### Options 11 12 | Name | Type | Default | Description | 13 |:----------------------------------------------|:--------------|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 14 | [`--add-host`](#add-host) | `list` | | Add a custom host-to-IP mapping (host:ip) | 15 | [`-a`](#attach), [`--attach`](#attach) | `list` | | Attach to STDIN, STDOUT or STDERR | 16 | `--blkio-weight` | `uint16` | `0` | Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) | 17 | `--blkio-weight-device` | `list` | | Block IO weight (relative device weight) | 18 | `--cap-add` | `list` | | Add Linux capabilities | 19 | `--cap-drop` | `list` | | Drop Linux capabilities | 20 | `--cgroup-parent` | `string` | | Optional parent cgroup for the container | 21 | `--cgroupns` | `string` | | Cgroup namespace to use (host\|private)<br>'host': Run the container in the Docker host's cgroup namespace<br>'private': Run the container in its own private cgroup namespace<br>'': Use the cgroup namespace as configured by the<br> default-cgroupns-mode option on the daemon (default) | 22 | [`--cidfile`](#cidfile) | `string` | | Write the container ID to the file | 23 | `--cpu-count` | `int64` | `0` | CPU count (Windows only) | 24 | `--cpu-percent` | `int64` | `0` | CPU percent (Windows only) | 25 | `--cpu-period` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) period | 26 | `--cpu-quota` | `int64` | `0` | Limit CPU CFS (Completely Fair Scheduler) quota | 27 | `--cpu-rt-period` | `int64` | `0` | Limit CPU real-time period in microseconds | 28 | `--cpu-rt-runtime` | `int64` | `0` | Limit CPU real-time runtime in microseconds | 29 | `-c`, `--cpu-shares` | `int64` | `0` | CPU shares (relative weight) | 30 | `--cpus` | `decimal` | | Number of CPUs | 31 | `--cpuset-cpus` | `string` | | CPUs in which to allow execution (0-3, 0,1) | 32 | `--cpuset-mems` | `string` | | MEMs in which to allow execution (0-3, 0,1) | 33 | `-d`, `--detach` | | | Run container in background and print container ID | 34 | `--detach-keys` | `string` | | Override the key sequence for detaching a container | 35 | [`--device`](#device) | `list` | | Add a host device to the container | 36 | [`--device-cgroup-rule`](#device-cgroup-rule) | `list` | | Add a rule to the cgroup allowed devices list | 37 | `--device-read-bps` | `list` | | Limit read rate (bytes per second) from a device | 38 | `--device-read-iops` | `list` | | Limit read rate (IO per second) from a device | 39 | `--device-write-bps` | `list` | | Limit write rate (bytes per second) to a device | 40 | `--device-write-iops` | `list` | | Limit write rate (IO per second) to a device | 41 | `--disable-content-trust` | | | Skip image verification | 42 | `--dns` | `list` | | Set custom DNS servers | 43 | `--dns-option` | `list` | | Set DNS options | 44 | `--dns-search` | `list` | | Set custom DNS search domains | 45 | `--domainname` | `string` | | Container NIS domain name | 46 | `--entrypoint` | `string` | | Overwrite the default ENTRYPOINT of the image | 47 | [`-e`](#env), [`--env`](#env) | `list` | | Set environment variables | 48 | `--env-file` | `list` | | Read in a file of environment variables | 49 | `--expose` | `list` | | Expose a port or a range of ports | 50 | [`--gpus`](#gpus) | `gpu-request` | | GPU devices to add to the container ('all' to pass all GPUs) | 51 | `--group-add` | `list` | | Add additional groups to join | 52 | `--health-cmd` | `string` | | Command to run to check health | 53 | `--health-interval` | `duration` | `0s` | Time between running the check (ms\|s\|m\|h) (default 0s) | 54 | `--health-retries` | `int` | `0` | Consecutive failures needed to report unhealthy | 55 | `--health-start-period` | `duration` | `0s` | Start period for the container to initialize before starting health-retries countdown (ms\|s\|m\|h) (default 0s) | 56 | `--health-timeout` | `duration` | `0s` | Maximum time to allow one check to run (ms\|s\|m\|h) (default 0s) | 57 | `--help` | | | Print usage | 58 | `-h`, `--hostname` | `string` | | Container host name | 59 | `--init` | | | Run an init inside the container that forwards signals and reaps processes | 60 | `-i`, `--interactive` | | | Keep STDIN open even if not attached | 61 | `--io-maxbandwidth` | `bytes` | `0` | Maximum IO bandwidth limit for the system drive (Windows only) | 62 | `--io-maxiops` | `uint64` | `0` | Maximum IOps limit for the system drive (Windows only) | 63 | `--ip` | `string` | | IPv4 address (e.g., 172.30.100.104) | 64 | `--ip6` | `string` | | IPv6 address (e.g., 2001:db8::33) | 65 | `--ipc` | `string` | | IPC mode to use | 66 | [`--isolation`](#isolation) | `string` | | Container isolation technology | 67 | `--kernel-memory` | `bytes` | `0` | Kernel memory limit | 68 | [`-l`](#label), [`--label`](#label) | `list` | | Set meta data on a container | 69 | `--label-file` | `list` | | Read in a line delimited file of labels | 70 | `--link` | `list` | | Add link to another container | 71 | `--link-local-ip` | `list` | | Container IPv4/IPv6 link-local addresses | 72 | `--log-driver` | `string` | | Logging driver for the container | 73 | `--log-opt` | `list` | | Log driver options | 74 | `--mac-address` | `string` | | Container MAC address (e.g., 92:d0:c6:0a:29:33) | 75 | [`-m`](#memory), [`--memory`](#memory) | `bytes` | `0` | Memory limit | 76 | `--memory-reservation` | `bytes` | `0` | Memory soft limit | 77 | `--memory-swap` | `bytes` | `0` | Swap limit equal to memory plus swap: '-1' to enable unlimited swap | 78 | `--memory-swappiness` | `int64` | `-1` | Tune container memory swappiness (0 to 100) | 79 | [`--mount`](#mount) | `mount` | | Attach a filesystem mount to the container | 80 | [`--name`](#name) | `string` | | Assign a name to the container | 81 | [`--network`](#network) | `network` | | Connect a container to a network | 82 | `--network-alias` | `list` | | Add network-scoped alias for the container | 83 | `--no-healthcheck` | | | Disable any container-specified HEALTHCHECK | 84 | `--oom-kill-disable` | | | Disable OOM Killer | 85 | `--oom-score-adj` | `int` | `0` | Tune host's OOM preferences (-1000 to 1000) | 86 | `--pid` | `string` | | PID namespace to use | 87 | `--pids-limit` | `int64` | `0` | Tune container pids limit (set -1 for unlimited) | 88 | `--platform` | `string` | | Set platform if server is multi-platform capable | 89 | [`--privileged`](#privileged) | | | Give extended privileges to this container | 90 | [`-p`](#publish), [`--publish`](#publish) | `list` | | Publish a container's port(s) to the host | 91 | `-P`, `--publish-all` | | | Publish all exposed ports to random ports | 92 | [`--pull`](#pull) | `string` | `missing` | Pull image before running (`always`, `missing`, `never`) | 93 | `-q`, `--quiet` | | | Suppress the pull output | 94 | `--read-only` | | | Mount the container's root filesystem as read only | 95 | [`--restart`](#restart) | `string` | `no` | Restart policy to apply when a container exits | 96 | `--rm` | | | Automatically remove the container when it exits | 97 | `--runtime` | `string` | | Runtime to use for this container | 98 | [`--security-opt`](#security-opt) | `list` | | Security Options | 99 | `--shm-size` | `bytes` | `0` | Size of /dev/shm | 100 | `--sig-proxy` | | | Proxy received signals to the process | 101 | [`--stop-signal`](#stop-signal) | `string` | | Signal to stop the container | 102 | [`--stop-timeout`](#stop-timeout) | `int` | `0` | Timeout (in seconds) to stop a container | 103 | [`--storage-opt`](#storage-opt) | `list` | | Storage driver options for the container | 104 | [`--sysctl`](#sysctl) | `map` | `map[]` | Sysctl options | 105 | [`--tmpfs`](#tmpfs) | `list` | | Mount a tmpfs directory | 106 | `-t`, `--tty` | | | Allocate a pseudo-TTY | 107 | [`--ulimit`](#ulimit) | `ulimit` | | Ulimit options | 108 | `-u`, `--user` | `string` | | Username or UID (format: <name\|uid>[:<group\|gid>]) | 109 | `--userns` | `string` | | User namespace to use | 110 | `--uts` | `string` | | UTS namespace to use | 111 | [`-v`](#volume), [`--volume`](#volume) | `list` | | Bind mount a volume | 112 | `--volume-driver` | `string` | | Optional volume driver for the container | 113 | [`--volumes-from`](#volumes-from) | `list` | | Mount volumes from the specified container(s) | 114 | [`-w`](#workdir), [`--workdir`](#workdir) | `string` | | Working directory inside the container | 115 116 117 <!---MARKER_GEN_END--> 118 119 ## Description 120 121 The `docker run` command first `creates` a writeable container layer over the 122 specified image, and then `starts` it using the specified command. That is, 123 `docker run` is equivalent to the API `/containers/create` then 124 `/containers/(id)/start`. A stopped container can be restarted with all its 125 previous changes intact using `docker start`. See `docker ps -a` to view a list 126 of all containers. 127 128 For information on connecting a container to a network, see the ["*Docker network overview*"](https://docs.docker.com/network/). 129 130 ## Examples 131 132 ### <a name="name"></a> Assign name and allocate pseudo-TTY (--name, -it) 133 134 ```console 135 $ docker run --name test -it debian 136 137 root@d6c0fe130dba:/# exit 13 138 $ echo $? 139 13 140 $ docker ps -a | grep test 141 d6c0fe130dba debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test 142 ``` 143 144 This example runs a container named `test` using the `debian:latest` 145 image. The `-it` instructs Docker to allocate a pseudo-TTY connected to 146 the container's stdin; creating an interactive `bash` shell in the container. 147 In the example, the `bash` shell is quit by entering 148 `exit 13`. This exit code is passed on to the caller of 149 `docker run`, and is recorded in the `test` container's metadata. 150 151 ### <a name="cidfile"></a> Capture container ID (--cidfile) 152 153 ```console 154 $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test" 155 ``` 156 157 This will create a container and print `test` to the console. The `cidfile` 158 flag makes Docker attempt to create a new file and write the container ID to it. 159 If the file exists already, Docker will return an error. Docker will close this 160 file when `docker run` exits. 161 162 ### <a name="privileged"></a> Full container capabilities (--privileged) 163 164 ```console 165 $ docker run -t -i --rm ubuntu bash 166 root@bc338942ef20:/# mount -t tmpfs none /mnt 167 mount: permission denied 168 ``` 169 170 This will *not* work, because by default, most potentially dangerous kernel 171 capabilities are dropped; including `cap_sys_admin` (which is required to mount 172 filesystems). However, the `--privileged` flag will allow it to run: 173 174 ```console 175 $ docker run -t -i --privileged ubuntu bash 176 root@50e3f57e16e6:/# mount -t tmpfs none /mnt 177 root@50e3f57e16e6:/# df -h 178 Filesystem Size Used Avail Use% Mounted on 179 none 1.9G 0 1.9G 0% /mnt 180 ``` 181 182 The `--privileged` flag gives *all* capabilities to the container, and it also 183 lifts all the limitations enforced by the `device` cgroup controller. In other 184 words, the container can then do almost everything that the host can do. This 185 flag exists to allow special use-cases, like running Docker within Docker. 186 187 ### <a name="workdir"></a> Set working directory (-w, --workdir) 188 189 ```console 190 $ docker run -w /path/to/dir/ -i -t ubuntu pwd 191 ``` 192 193 The `-w` lets the command being executed inside directory given, here 194 `/path/to/dir/`. If the path does not exist it is created inside the container. 195 196 ### <a name="storage-opt"></a> Set storage driver options per container (--storage-opt) 197 198 ```console 199 $ docker run -it --storage-opt size=120G fedora /bin/bash 200 ``` 201 202 This (size) will allow to set the container filesystem size to 120G at creation time. 203 This option is only available for the `devicemapper`, `btrfs`, `overlay2`, 204 `windowsfilter` and `zfs` graph drivers. 205 For the `devicemapper`, `btrfs`, `windowsfilter` and `zfs` graph drivers, 206 user cannot pass a size less than the Default BaseFS Size. 207 For the `overlay2` storage driver, the size option is only available if the 208 backing filesystem is `xfs` and mounted with the `pquota` mount option. 209 Under these conditions, user can pass any size less than the backing filesystem size. 210 211 ### <a name="tmpfs"></a> Mount tmpfs (--tmpfs) 212 213 ```console 214 $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image 215 ``` 216 217 The `--tmpfs` flag mounts an empty tmpfs into the container with the `rw`, 218 `noexec`, `nosuid`, `size=65536k` options. 219 220 ### <a name="volume"></a> Mount volume (-v, --read-only) 221 222 ```console 223 $ docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd 224 ``` 225 226 The `-v` flag mounts the current working directory into the container. The `-w` 227 lets the command being executed inside the current working directory, by 228 changing into the directory to the value returned by `pwd`. So this 229 combination executes the command using the container, but inside the 230 current working directory. 231 232 ```console 233 $ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash 234 ``` 235 236 When the host directory of a bind-mounted volume doesn't exist, Docker 237 will automatically create this directory on the host for you. In the 238 example above, Docker will create the `/doesnt/exist` 239 folder before starting your container. 240 241 ```console 242 $ docker run --read-only -v /icanwrite busybox touch /icanwrite/here 243 ``` 244 245 Volumes can be used in combination with `--read-only` to control where 246 a container writes files. The `--read-only` flag mounts the container's root 247 filesystem as read only prohibiting writes to locations other than the 248 specified volumes for the container. 249 250 ```console 251 $ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/static-docker-binary:/usr/bin/docker busybox sh 252 ``` 253 254 By bind-mounting the Docker Unix socket and statically linked Docker 255 binary (refer to [get the Linux binary](https://docs.docker.com/engine/install/binaries/#install-static-binaries)), 256 you give the container the full access to create and manipulate the host's 257 Docker daemon. 258 259 On Windows, the paths must be specified using Windows-style semantics. 260 261 ```powershell 262 PS C:\> docker run -v c:\foo:c:\dest microsoft/nanoserver cmd /s /c type c:\dest\somefile.txt 263 Contents of file 264 265 PS C:\> docker run -v c:\foo:d: microsoft/nanoserver cmd /s /c type d:\somefile.txt 266 Contents of file 267 ``` 268 269 The following examples will fail when using Windows-based containers, as the 270 destination of a volume or bind mount inside the container must be one of: 271 a non-existing or empty directory; or a drive other than C:. Further, the source 272 of a bind mount must be a local directory, not a file. 273 274 ```powershell 275 net use z: \\remotemachine\share 276 docker run -v z:\foo:c:\dest ... 277 docker run -v \\uncpath\to\directory:c:\dest ... 278 docker run -v c:\foo\somefile.txt:c:\dest ... 279 docker run -v c:\foo:c: ... 280 docker run -v c:\foo:c:\existing-directory-with-contents ... 281 ``` 282 283 For in-depth information about volumes, refer to [manage data in containers](https://docs.docker.com/storage/volumes/) 284 285 286 ### <a name="mount"></a> Add bind mounts or volumes using the --mount flag 287 288 The `--mount` flag allows you to mount volumes, host-directories and `tmpfs` 289 mounts in a container. 290 291 The `--mount` flag supports most options that are supported by the `-v` or the 292 `--volume` flag, but uses a different syntax. For in-depth information on the 293 `--mount` flag, and a comparison between `--volume` and `--mount`, refer to 294 [Bind mounts](https://docs.docker.com/storage/bind-mounts/). 295 296 Even though there is no plan to deprecate `--volume`, usage of `--mount` is recommended. 297 298 Examples: 299 300 ```console 301 $ docker run --read-only --mount type=volume,target=/icanwrite busybox touch /icanwrite/here 302 ``` 303 304 ```console 305 $ docker run -t -i --mount type=bind,src=/data,dst=/data busybox sh 306 ``` 307 308 ### <a name="publish"></a> Publish or expose port (-p, --expose) 309 310 ```console 311 $ docker run -p 127.0.0.1:80:8080/tcp ubuntu bash 312 ``` 313 314 This binds port `8080` of the container to TCP port `80` on `127.0.0.1` of the host 315 machine. You can also specify `udp` and `sctp` ports. 316 The [Docker User Guide](https://docs.docker.com/network/links/) 317 explains in detail how to manipulate ports in Docker. 318 319 Note that ports which are not bound to the host (i.e., `-p 80:80` instead of 320 `-p 127.0.0.1:80:80`) will be accessible from the outside. This also applies if 321 you configured UFW to block this specific port, as Docker manages its 322 own iptables rules. [Read more](https://docs.docker.com/network/iptables/) 323 324 ```console 325 $ docker run --expose 80 ubuntu bash 326 ``` 327 328 This exposes port `80` of the container without publishing the port to the host 329 system's interfaces. 330 331 ### <a name="pull"></a> Set the pull policy (--pull) 332 333 Use the `--pull` flag to set the image pull policy when creating (and running) 334 the container. 335 336 The `--pull` flag can take one of these values: 337 338 | Value | Description | 339 |:--------------------|:------------------------------------------------------------------------------------------------------------------| 340 | `missing` (default) | Pull the image if it was not found in the image cache, or use the cached image otherwise. | 341 | `never` | Do not pull the image, even if it's missing, and produce an error if the image does not exist in the image cache. | 342 | `always` | Always perform a pull before creating the container. | 343 344 When creating (and running) a container from an image, the daemon checks if the 345 image exists in the local image cache. If the image is missing, an error is 346 returned to the CLI, allowing it to initiate a pull. 347 348 The default (`missing`) is to only pull the image if it is not present in the 349 daemon's image cache. This default allows you to run images that only exist 350 locally (for example, images you built from a Dockerfile, but that have not 351 been pushed to a registry), and reduces networking. 352 353 The `always` option always initiates a pull before creating the container. This 354 option makes sure the image is up-to-date, and prevents you from using outdated 355 images, but may not be suitable in situations where you want to test a locally 356 built image before pushing (as pulling the image overwrites the existing image 357 in the image cache). 358 359 The `never` option disables (implicit) pulling images when creating containers, 360 and only uses images that are available in the image cache. If the specified 361 image is not found, an error is produced, and the container is not created. 362 This option is useful in situations where networking is not available, or to 363 prevent images from being pulled implicitly when creating containers. 364 365 The following example shows `docker run` with the `--pull=never` option set, 366 which produces en error as the image is missing in the image-cache: 367 368 ```console 369 $ docker run --pull=never hello-world 370 docker: Error response from daemon: No such image: hello-world:latest. 371 ``` 372 373 ### <a name="env"></a> Set environment variables (-e, --env, --env-file) 374 375 ```console 376 $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash 377 ``` 378 379 Use the `-e`, `--env`, and `--env-file` flags to set simple (non-array) 380 environment variables in the container you're running, or overwrite variables 381 that are defined in the Dockerfile of the image you're running. 382 383 You can define the variable and its value when running the container: 384 385 ```console 386 $ docker run --env VAR1=value1 --env VAR2=value2 ubuntu env | grep VAR 387 VAR1=value1 388 VAR2=value2 389 ``` 390 391 You can also use variables that you've exported to your local environment: 392 393 ```console 394 export VAR1=value1 395 export VAR2=value2 396 397 $ docker run --env VAR1 --env VAR2 ubuntu env | grep VAR 398 VAR1=value1 399 VAR2=value2 400 ``` 401 402 When running the command, the Docker CLI client checks the value the variable 403 has in your local environment and passes it to the container. 404 If no `=` is provided and that variable is not exported in your local 405 environment, the variable won't be set in the container. 406 407 You can also load the environment variables from a file. This file should use 408 the syntax `<variable>=value` (which sets the variable to the given value) or 409 `<variable>` (which takes the value from the local environment), and `#` for comments. 410 411 ```console 412 $ cat env.list 413 # This is a comment 414 VAR1=value1 415 VAR2=value2 416 USER 417 418 $ docker run --env-file env.list ubuntu env | grep -E 'VAR|USER' 419 VAR1=value1 420 VAR2=value2 421 USER=jonzeolla 422 ``` 423 424 ### <a name="label"></a> Set metadata on container (-l, --label, --label-file) 425 426 A label is a `key=value` pair that applies metadata to a container. To label a container with two labels: 427 428 ```console 429 $ docker run -l my-label --label com.example.foo=bar ubuntu bash 430 ``` 431 432 The `my-label` key doesn't specify a value so the label defaults to an empty 433 string (`""`). To add multiple labels, repeat the label flag (`-l` or `--label`). 434 435 The `key=value` must be unique to avoid overwriting the label value. If you 436 specify labels with identical keys but different values, each subsequent value 437 overwrites the previous. Docker uses the last `key=value` you supply. 438 439 Use the `--label-file` flag to load multiple labels from a file. Delimit each 440 label in the file with an EOL mark. The example below loads labels from a 441 labels file in the current directory: 442 443 ```console 444 $ docker run --label-file ./labels ubuntu bash 445 ``` 446 447 The label-file format is similar to the format for loading environment 448 variables. (Unlike environment variables, labels are not visible to processes 449 running inside a container.) The following example illustrates a label-file 450 format: 451 452 ```console 453 com.example.label1="a label" 454 455 # this is a comment 456 com.example.label2=another\ label 457 com.example.label3 458 ``` 459 460 You can load multiple label-files by supplying multiple `--label-file` flags. 461 462 For additional information on working with labels, see [*Labels - custom 463 metadata in Docker*](https://docs.docker.com/config/labels-custom-metadata/) in 464 the Docker User Guide. 465 466 ### <a name="network"></a> Connect a container to a network (--network) 467 468 When you start a container use the `--network` flag to connect it to a network. 469 The following commands create a network named `my-net`, and adds a `busybox` container 470 to the `my-net` network. 471 472 ```console 473 $ docker network create my-net 474 $ docker run -itd --network=my-net busybox 475 ``` 476 477 You can also choose the IP addresses for the container with `--ip` and `--ip6` 478 flags when you start the container on a user-defined network. 479 480 ```console 481 $ docker run -itd --network=my-net --ip=10.10.9.75 busybox 482 ``` 483 484 If you want to add a running container to a network use the `docker network connect` subcommand. 485 486 You can connect multiple containers to the same network. Once connected, the 487 containers can communicate easily using only another container's IP address 488 or name. For `overlay` networks or custom plugins that support multi-host 489 connectivity, containers connected to the same multi-host network but launched 490 from different Engines can also communicate in this way. 491 492 > **Note** 493 > 494 > The default bridge network only allow containers to communicate with each other using 495 > internal IP addresses. User-created bridge networks provide DNS resolution between 496 > containers using container names. 497 498 You can disconnect a container from a network using the `docker network 499 disconnect` command. 500 501 ### <a name="volumes-from"></a> Mount volumes from container (--volumes-from) 502 503 ```console 504 $ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd 505 ``` 506 507 The `--volumes-from` flag mounts all the defined volumes from the referenced 508 containers. Containers can be specified by repetitions of the `--volumes-from` 509 argument. The container ID may be optionally suffixed with `:ro` or `:rw` to 510 mount the volumes in read-only or read-write mode, respectively. By default, 511 the volumes are mounted in the same mode (read write or read only) as 512 the reference container. 513 514 Labeling systems like SELinux require that proper labels are placed on volume 515 content mounted into a container. Without a label, the security system might 516 prevent the processes running inside the container from using the content. By 517 default, Docker does not change the labels set by the OS. 518 519 To change the label in the container context, you can add either of two suffixes 520 `:z` or `:Z` to the volume mount. These suffixes tell Docker to relabel file 521 objects on the shared volumes. The `z` option tells Docker that two containers 522 share the volume content. As a result, Docker labels the content with a shared 523 content label. Shared volume labels allow all containers to read/write content. 524 The `Z` option tells Docker to label the content with a private unshared label. 525 Only the current container can use a private volume. 526 527 ### <a name="attach"></a> Attach to STDIN/STDOUT/STDERR (-a, --attach) 528 529 The `--attach` (or `-a`) flag tells `docker run` to bind to the container's 530 `STDIN`, `STDOUT` or `STDERR`. This makes it possible to manipulate the output 531 and input as needed. 532 533 ```console 534 $ echo "test" | docker run -i -a stdin ubuntu cat - 535 ``` 536 537 This pipes data into a container and prints the container's ID by attaching 538 only to the container's `STDIN`. 539 540 ```console 541 $ docker run -a stderr ubuntu echo test 542 ``` 543 544 This isn't going to print anything unless there's an error because we've 545 only attached to the `STDERR` of the container. The container's logs 546 still store what's been written to `STDERR` and `STDOUT`. 547 548 ```console 549 $ cat somefile | docker run -i -a stdin mybuilder dobuild 550 ``` 551 552 This is a way of using `--attach` to pipe a build file into a container. 553 The container's ID will be printed after the build is done and the build 554 logs could be retrieved using `docker logs`. This is 555 useful if you need to pipe a file or something else into a container and 556 retrieve the container's ID once the container has finished running. 557 558 See also [the `docker cp` command](cp.md). 559 560 ### <a name="device"></a> Add host device to container (--device) 561 562 ```console 563 $ docker run -it --rm \ 564 --device=/dev/sdc:/dev/xvdc \ 565 --device=/dev/sdd \ 566 --device=/dev/zero:/dev/foobar \ 567 ubuntu ls -l /dev/{xvdc,sdd,foobar} 568 569 brw-rw---- 1 root disk 8, 2 Feb 9 16:05 /dev/xvdc 570 brw-rw---- 1 root disk 8, 3 Feb 9 16:05 /dev/sdd 571 crw-rw-rw- 1 root root 1, 5 Feb 9 16:05 /dev/foobar 572 ``` 573 574 It is often necessary to directly expose devices to a container. The `--device` 575 option enables that. For example, a specific block storage device or loop 576 device or audio device can be added to an otherwise unprivileged container 577 (without the `--privileged` flag) and have the application directly access it. 578 579 By default, the container will be able to `read`, `write` and `mknod` these devices. 580 This can be overridden using a third `:rwm` set of options to each `--device` 581 flag. If the container is running in privileged mode, then the permissions specified 582 will be ignored. 583 584 ```console 585 $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc 586 587 Command (m for help): q 588 $ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk /dev/xvdc 589 You will not be able to write the partition table. 590 591 Command (m for help): q 592 593 $ docker run --device=/dev/sda:/dev/xvdc:rw --rm -it ubuntu fdisk /dev/xvdc 594 595 Command (m for help): q 596 597 $ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc 598 fdisk: unable to open /dev/xvdc: Operation not permitted 599 ``` 600 601 > **Note** 602 > 603 > The `--device` option cannot be safely used with ephemeral devices. Block devices 604 > that may be removed should not be added to untrusted containers with `--device`. 605 606 For Windows, the format of the string passed to the `--device` option is in 607 the form of `--device=<IdType>/<Id>`. Beginning with Windows Server 2019 608 and Windows 10 October 2018 Update, Windows only supports an IdType of 609 `class` and the Id as a [device interface class 610 GUID](https://docs.microsoft.com/en-us/windows-hardware/drivers/install/overview-of-device-interface-classes). 611 Refer to the table defined in the [Windows container 612 docs](https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/hardware-devices-in-containers) 613 for a list of container-supported device interface class GUIDs. 614 615 If this option is specified for a process-isolated Windows container, _all_ 616 devices that implement the requested device interface class GUID are made 617 available in the container. For example, the command below makes all COM 618 ports on the host visible in the container. 619 620 ```powershell 621 PS C:\> docker run --device=class/86E0D1E0-8089-11D0-9CE4-08003E301F73 mcr.microsoft.com/windows/servercore:ltsc2019 622 ``` 623 624 > **Note** 625 > 626 > The `--device` option is only supported on process-isolated Windows containers, 627 > and produces an error if the container isolation is `hyperv`. 628 629 ### <a name="device-cgroup-rule"></a> Using dynamically created devices (--device-cgroup-rule) 630 631 Devices available to a container are assigned at creation time. The 632 assigned devices will both be added to the cgroup.allow file and 633 created into the container once it is run. This poses a problem when 634 a new device needs to be added to running container. 635 636 One of the solutions is to add a more permissive rule to a container 637 allowing it access to a wider range of devices. For example, supposing 638 our container needs access to a character device with major `42` and 639 any number of minor number (added as new devices appear), the 640 following rule would be added: 641 642 ```console 643 $ docker run -d --device-cgroup-rule='c 42:* rmw' -name my-container my-image 644 ``` 645 646 Then, a user could ask `udev` to execute a script that would `docker exec my-container mknod newDevX c 42 <minor>` 647 the required device when it is added. 648 649 > **Note**: initially present devices still need to be explicitly added to the 650 > `docker run` / `docker create` command. 651 652 ### <a name="gpus"></a> Access an NVIDIA GPU 653 654 The `--gpus` flag allows you to access NVIDIA GPU resources. First you need to 655 install [nvidia-container-runtime](https://nvidia.github.io/nvidia-container-runtime/). 656 Visit [Specify a container's resources](https://docs.docker.com/config/containers/resource_constraints/) 657 for more information. 658 659 To use `--gpus`, specify which GPUs (or all) to use. If no value is provided, all 660 available GPUs are used. The example below exposes all available GPUs. 661 662 ```console 663 $ docker run -it --rm --gpus all ubuntu nvidia-smi 664 ``` 665 666 Use the `device` option to specify GPUs. The example below exposes a specific 667 GPU. 668 669 ```console 670 $ docker run -it --rm --gpus device=GPU-3a23c669-1f69-c64e-cf85-44e9b07e7a2a ubuntu nvidia-smi 671 ``` 672 673 The example below exposes the first and third GPUs. 674 675 ```console 676 $ docker run -it --rm --gpus '"device=0,2"' nvidia-smi 677 ``` 678 679 ### <a name="restart"></a> Restart policies (--restart) 680 681 Use Docker's `--restart` to specify a container's *restart policy*. A restart 682 policy controls whether the Docker daemon restarts a container after exit. 683 Docker supports the following restart policies: 684 685 | Policy | Result | 686 |:---------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 687 | `no` | Do not automatically restart the container when it exits. This is the default. | 688 | `on-failure[:max-retries]` | Restart only if the container exits with a non-zero exit status. Optionally, limit the number of restart retries the Docker daemon attempts. | 689 | `unless-stopped` | Restart the container unless it is explicitly stopped or Docker itself is stopped or restarted. | 690 | `always` | Always restart the container regardless of the exit status. When you specify always, the Docker daemon will try to restart the container indefinitely. The container will also always start on daemon startup, regardless of the current state of the container. | 691 692 ```console 693 $ docker run --restart=always redis 694 ``` 695 696 This will run the `redis` container with a restart policy of **always** 697 so that if the container exits, Docker will restart it. 698 699 More detailed information on restart policies can be found in the 700 [Restart Policies (--restart)](../run.md#restart-policies---restart) 701 section of the Docker run reference page. 702 703 ### <a name="add-host"></a> Add entries to container hosts file (--add-host) 704 705 You can add other hosts into a container's `/etc/hosts` file by using one or 706 more `--add-host` flags. This example adds a static address for a host named 707 `docker`: 708 709 ```console 710 $ docker run --add-host=docker:93.184.216.34 --rm -it alpine 711 712 / # ping docker 713 PING docker (93.184.216.34): 56 data bytes 714 64 bytes from 93.184.216.34: seq=0 ttl=37 time=93.052 ms 715 64 bytes from 93.184.216.34: seq=1 ttl=37 time=92.467 ms 716 64 bytes from 93.184.216.34: seq=2 ttl=37 time=92.252 ms 717 ^C 718 --- docker ping statistics --- 719 4 packets transmitted, 4 packets received, 0% packet loss 720 round-trip min/avg/max = 92.209/92.495/93.052 ms 721 ``` 722 723 Sometimes you need to connect to the Docker host from within your 724 container. To enable this, pass the Docker host's IP address to 725 the container using the `--add-host` flag. To find the host's address, 726 use the `ip addr show` command. 727 728 The flags you pass to `ip addr show` depend on whether you are 729 using IPv4 or IPv6 networking in your containers. Use the following 730 flags for IPv4 address retrieval for a network device named `eth0`: 731 732 ```console 733 $ HOSTIP=`ip -4 addr show scope global dev eth0 | grep inet | awk '{print $2}' | cut -d / -f 1 | sed -n 1p` 734 $ docker run --add-host=docker:${HOSTIP} --rm -it debian 735 ``` 736 737 For IPv6 use the `-6` flag instead of the `-4` flag. For other network 738 devices, replace `eth0` with the correct device name (for example `docker0` 739 for the bridge device). 740 741 ### <a name="ulimit"></a> Set ulimits in container (--ulimit) 742 743 Since setting `ulimit` settings in a container requires extra privileges not 744 available in the default container, you can set these using the `--ulimit` flag. 745 `--ulimit` is specified with a soft and hard limit as such: 746 `<type>=<soft limit>[:<hard limit>]`, for example: 747 748 ```console 749 $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n" 750 1024 751 ``` 752 753 > **Note** 754 > 755 > If you do not provide a `hard limit`, the `soft limit` is used 756 > for both values. If no `ulimits` are set, they are inherited from 757 > the default `ulimits` set on the daemon. The `as` option is disabled now. 758 > In other words, the following script is not supported: 759 > 760 > ```console 761 > $ docker run -it --ulimit as=1024 fedora /bin/bash 762 > ``` 763 764 The values are sent to the appropriate `syscall` as they are set. 765 Docker doesn't perform any byte conversion. Take this into account when setting the values. 766 767 #### For `nproc` usage 768 769 Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linux to set the 770 maximum number of processes available to a user, not to a container. For example, start four 771 containers with `daemon` user: 772 773 ```console 774 $ docker run -d -u daemon --ulimit nproc=3 busybox top 775 776 $ docker run -d -u daemon --ulimit nproc=3 busybox top 777 778 $ docker run -d -u daemon --ulimit nproc=3 busybox top 779 780 $ docker run -d -u daemon --ulimit nproc=3 busybox top 781 ``` 782 783 The 4th container fails and reports "[8] System error: resource temporarily unavailable" error. 784 This fails because the caller set `nproc=3` resulting in the first three containers using up 785 the three processes quota set for the `daemon` user. 786 787 ### <a name="stop-signal"></a> Stop container with signal (--stop-signal) 788 789 The `--stop-signal` flag sets the system call signal that will be sent to the 790 container to exit. This signal can be a signal name in the format `SIG<NAME>`, 791 for instance `SIGKILL`, or an unsigned number that matches a position in the 792 kernel's syscall table, for instance `9`. 793 794 The default is defined by [`STOPSIGNAL`](https://docs.docker.com/engine/reference/builder/#stopsignal) 795 in the image, or `SIGTERM` if the image has no `STOPSIGNAL` defined. 796 797 ### <a name="security-opt"></a> Optional security options (--security-opt) 798 799 On Windows, this flag can be used to specify the `credentialspec` option. 800 The `credentialspec` must be in the format `file://spec.txt` or `registry://keyname`. 801 802 ### <a name="stop-timeout"></a> Stop container with timeout (--stop-timeout) 803 804 The `--stop-timeout` flag sets the number of seconds to wait for the container 805 to stop after sending the pre-defined (see `--stop-signal`) system call signal. 806 If the container does not exit after the timeout elapses, it is forcibly killed 807 with a `SIGKILL` signal. 808 809 If `--stop-timeout` is set to `-1`, no timeout is applied, and the daemon will 810 wait indefinitely for the container to exit. 811 812 The default is determined by the daemon, and is 10 seconds for Linux containers, 813 and 30 seconds for Windows containers. 814 815 ### <a name="isolation"></a> Specify isolation technology for container (--isolation) 816 817 This option is useful in situations where you are running Docker containers on 818 Windows. The `--isolation=<value>` option sets a container's isolation technology. 819 On Linux, the only supported is the `default` option which uses Linux namespaces. 820 These two commands are equivalent on Linux: 821 822 ```console 823 $ docker run -d busybox top 824 $ docker run -d --isolation default busybox top 825 ``` 826 827 On Windows, `--isolation` can take one of these values: 828 829 | Value | Description | 830 |:----------|:-------------------------------------------------------------------------------------------| 831 | `default` | Use the value specified by the Docker daemon's `--exec-opt` or system default (see below). | 832 | `process` | Shared-kernel namespace isolation. | 833 | `hyperv` | Hyper-V hypervisor partition-based isolation. | 834 835 The default isolation on Windows server operating systems is `process`, and `hyperv` 836 on Windows client operating systems, such as Windows 10. Process isolation has better 837 performance, but requires that the image and host use the same kernel version. 838 839 On Windows server, assuming the default configuration, these commands are equivalent 840 and result in `process` isolation: 841 842 ```powershell 843 PS C:\> docker run -d microsoft/nanoserver powershell echo process 844 PS C:\> docker run -d --isolation default microsoft/nanoserver powershell echo process 845 PS C:\> docker run -d --isolation process microsoft/nanoserver powershell echo process 846 ``` 847 848 If you have set the `--exec-opt isolation=hyperv` option on the Docker `daemon`, or 849 are running against a Windows client-based daemon, these commands are equivalent and 850 result in `hyperv` isolation: 851 852 ```powershell 853 PS C:\> docker run -d microsoft/nanoserver powershell echo hyperv 854 PS C:\> docker run -d --isolation default microsoft/nanoserver powershell echo hyperv 855 PS C:\> docker run -d --isolation hyperv microsoft/nanoserver powershell echo hyperv 856 ``` 857 858 ### <a name="memory"></a> Specify hard limits on memory available to containers (-m, --memory) 859 860 These parameters always set an upper limit on the memory available to the container. On Linux, this 861 is set on the cgroup and applications in a container can query it at `/sys/fs/cgroup/memory/memory.limit_in_bytes`. 862 863 On Windows, this will affect containers differently depending on what type of isolation is used. 864 865 - With `process` isolation, Windows will report the full memory of the host system, not the limit to applications running inside the container 866 867 ```powershell 868 PS C:\> docker run -it -m 2GB --isolation=process microsoft/nanoserver powershell Get-ComputerInfo *memory* 869 870 CsTotalPhysicalMemory : 17064509440 871 CsPhyicallyInstalledMemory : 16777216 872 OsTotalVisibleMemorySize : 16664560 873 OsFreePhysicalMemory : 14646720 874 OsTotalVirtualMemorySize : 19154928 875 OsFreeVirtualMemory : 17197440 876 OsInUseVirtualMemory : 1957488 877 OsMaxProcessMemorySize : 137438953344 878 ``` 879 880 - With `hyperv` isolation, Windows will create a utility VM that is big enough to hold the memory limit, plus the minimal OS needed to host the container. That size is reported as "Total Physical Memory." 881 882 ```powershell 883 PS C:\> docker run -it -m 2GB --isolation=hyperv microsoft/nanoserver powershell Get-ComputerInfo *memory* 884 885 CsTotalPhysicalMemory : 2683355136 886 CsPhyicallyInstalledMemory : 887 OsTotalVisibleMemorySize : 2620464 888 OsFreePhysicalMemory : 2306552 889 OsTotalVirtualMemorySize : 2620464 890 OsFreeVirtualMemory : 2356692 891 OsInUseVirtualMemory : 263772 892 OsMaxProcessMemorySize : 137438953344 893 ``` 894 895 896 ### <a name="sysctl"></a> Configure namespaced kernel parameters (sysctls) at runtime (--sysctl) 897 898 The `--sysctl` sets namespaced kernel parameters (sysctls) in the 899 container. For example, to turn on IP forwarding in the containers 900 network namespace, run this command: 901 902 ```console 903 $ docker run --sysctl net.ipv4.ip_forward=1 someimage 904 ``` 905 906 > **Note** 907 > 908 > Not all sysctls are namespaced. Docker does not support changing sysctls 909 > inside of a container that also modify the host system. As the kernel 910 > evolves we expect to see more sysctls become namespaced. 911 912 #### Currently supported sysctls 913 914 IPC Namespace: 915 916 - `kernel.msgmax`, `kernel.msgmnb`, `kernel.msgmni`, `kernel.sem`, 917 `kernel.shmall`, `kernel.shmmax`, `kernel.shmmni`, `kernel.shm_rmid_forced`. 918 - Sysctls beginning with `fs.mqueue.*` 919 - If you use the `--ipc=host` option these sysctls are not allowed. 920 921 Network Namespace: 922 923 - Sysctls beginning with `net.*` 924 - If you use the `--network=host` option using these sysctls are not allowed.