github.com/pwn-term/docker@v0.0.0-20210616085119-6e977cce2565/cli/docs/reference/run.md (about) 1 --- 2 description: "Configure containers at runtime" 3 keywords: "docker, run, configure, runtime" 4 --- 5 6 <!-- This file is maintained within the docker/cli GitHub 7 repository at https://github.com/docker/cli/. Make all 8 pull requests against that repo. If you see this file in 9 another repository, consider it read-only there, as it will 10 periodically be overwritten by the definitive file. Pull 11 requests which include edits to this file in other repositories 12 will be rejected. 13 --> 14 15 # Docker run reference 16 17 Docker runs processes in isolated containers. A container is a process 18 which runs on a host. The host may be local or remote. When an operator 19 executes `docker run`, the container process that runs is isolated in 20 that it has its own file system, its own networking, and its own 21 isolated process tree separate from the host. 22 23 This page details how to use the `docker run` command to define the 24 container's resources at runtime. 25 26 ## General form 27 28 The basic `docker run` command takes this form: 29 30 $ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...] 31 32 The `docker run` command must specify an [*IMAGE*](https://docs.docker.com/glossary/#image) 33 to derive the container from. An image developer can define image 34 defaults related to: 35 36 * detached or foreground running 37 * container identification 38 * network settings 39 * runtime constraints on CPU and memory 40 41 With the `docker run [OPTIONS]` an operator can add to or override the 42 image defaults set by a developer. And, additionally, operators can 43 override nearly all the defaults set by the Docker runtime itself. The 44 operator's ability to override image and Docker runtime defaults is why 45 [*run*](commandline/run.md) has more options than any 46 other `docker` command. 47 48 To learn how to interpret the types of `[OPTIONS]`, see 49 [*Option types*](commandline/cli.md#option-types). 50 51 > **Note** 52 > 53 > Depending on your Docker system configuration, you may be 54 > required to preface the `docker run` command with `sudo`. To avoid 55 > having to use `sudo` with the `docker` command, your system 56 > administrator can create a Unix group called `docker` and add users to 57 > it. For more information about this configuration, refer to the Docker 58 > installation documentation for your operating system. 59 60 61 ## Operator exclusive options 62 63 Only the operator (the person executing `docker run`) can set the 64 following options. 65 66 - [Detached vs foreground](#detached-vs-foreground) 67 - [Detached (-d)](#detached--d) 68 - [Foreground](#foreground) 69 - [Container identification](#container-identification) 70 - [Name (--name)](#name---name) 71 - [PID equivalent](#pid-equivalent) 72 - [IPC settings (--ipc)](#ipc-settings---ipc) 73 - [Network settings](#network-settings) 74 - [Restart policies (--restart)](#restart-policies---restart) 75 - [Clean up (--rm)](#clean-up---rm) 76 - [Runtime constraints on resources](#runtime-constraints-on-resources) 77 - [Runtime privilege and Linux capabilities](#runtime-privilege-and-linux-capabilities) 78 79 ## Detached vs foreground 80 81 When starting a Docker container, you must first decide if you want to 82 run the container in the background in a "detached" mode or in the 83 default foreground mode: 84 85 -d=false: Detached mode: Run container in the background, print new container id 86 87 ### Detached (-d) 88 89 To start a container in detached mode, you use `-d=true` or just `-d` option. By 90 design, containers started in detached mode exit when the root process used to 91 run the container exits, unless you also specify the `--rm` option. If you use 92 `-d` with `--rm`, the container is removed when it exits **or** when the daemon 93 exits, whichever happens first. 94 95 Do not pass a `service x start` command to a detached container. For example, this 96 command attempts to start the `nginx` service. 97 98 $ docker run -d -p 80:80 my_image service nginx start 99 100 This succeeds in starting the `nginx` service inside the container. However, it 101 fails the detached container paradigm in that, the root process (`service nginx 102 start`) returns and the detached container stops as designed. As a result, the 103 `nginx` service is started but could not be used. Instead, to start a process 104 such as the `nginx` web server do the following: 105 106 $ docker run -d -p 80:80 my_image nginx -g 'daemon off;' 107 108 To do input/output with a detached container use network connections or shared 109 volumes. These are required because the container is no longer listening to the 110 command line where `docker run` was run. 111 112 To reattach to a detached container, use `docker` 113 [*attach*](commandline/attach.md) command. 114 115 ### Foreground 116 117 In foreground mode (the default when `-d` is not specified), `docker 118 run` can start the process in the container and attach the console to 119 the process's standard input, output, and standard error. It can even 120 pretend to be a TTY (this is what most command line executables expect) 121 and pass along signals. All of that is configurable: 122 123 -a=[] : Attach to `STDIN`, `STDOUT` and/or `STDERR` 124 -t : Allocate a pseudo-tty 125 --sig-proxy=true: Proxy all received signals to the process (non-TTY mode only) 126 -i : Keep STDIN open even if not attached 127 128 If you do not specify `-a` then Docker will [attach to both stdout and stderr 129 ]( https://github.com/docker/docker/blob/4118e0c9eebda2412a09ae66e90c34b85fae3275/runconfig/opts/parse.go#L267). 130 You can specify to which of the three standard streams (`STDIN`, `STDOUT`, 131 `STDERR`) you'd like to connect instead, as in: 132 133 ```bash 134 $ docker run -a stdin -a stdout -i -t ubuntu /bin/bash 135 ``` 136 137 For interactive processes (like a shell), you must use `-i -t` together in 138 order to allocate a tty for the container process. `-i -t` is often written `-it` 139 as you'll see in later examples. Specifying `-t` is forbidden when the client 140 is receiving its standard input from a pipe, as in: 141 142 ```bash 143 $ echo test | docker run -i busybox cat 144 ``` 145 146 > **Note** 147 > 148 > A process running as PID 1 inside a container is treated specially by Linux: 149 > it ignores any signal with the default action. As a result, the process will 150 > not terminate on `SIGINT` or `SIGTERM` unless it is coded to do so. 151 152 ## Container identification 153 154 ### Name (--name) 155 156 The operator can identify a container in three ways: 157 158 | Identifier type | Example value | 159 |:----------------------|:-------------------------------------------------------------------| 160 | UUID long identifier | "f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778" | 161 | UUID short identifier | "f78375b1c487" | 162 | Name | "evil_ptolemy" | 163 164 The UUID identifiers come from the Docker daemon. If you do not assign a 165 container name with the `--name` option, then the daemon generates a random 166 string name for you. Defining a `name` can be a handy way to add meaning to a 167 container. If you specify a `name`, you can use it when referencing the 168 container within a Docker network. This works for both background and foreground 169 Docker containers. 170 171 > **Note** 172 > 173 > Containers on the default bridge network must be linked to communicate by name. 174 175 ### PID equivalent 176 177 Finally, to help with automation, you can have Docker write the 178 container ID out to a file of your choosing. This is similar to how some 179 programs might write out their process ID to a file (you've seen them as 180 PID files): 181 182 --cidfile="": Write the container ID to the file 183 184 ### Image[:tag] 185 186 While not strictly a means of identifying a container, you can specify a version of an 187 image you'd like to run the container with by adding `image[:tag]` to the command. For 188 example, `docker run ubuntu:14.04`. 189 190 ### Image[@digest] 191 192 Images using the v2 or later image format have a content-addressable identifier 193 called a digest. As long as the input used to generate the image is unchanged, 194 the digest value is predictable and referenceable. 195 196 The following example runs a container from the `alpine` image with the 197 `sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0` digest: 198 199 ```bash 200 $ docker run alpine@sha256:9cacb71397b640eca97488cf08582ae4e4068513101088e9f96c9814bfda95e0 date 201 ``` 202 203 ## PID settings (--pid) 204 205 --pid="" : Set the PID (Process) Namespace mode for the container, 206 'container:<name|id>': joins another container's PID namespace 207 'host': use the host's PID namespace inside the container 208 209 By default, all containers have the PID namespace enabled. 210 211 PID namespace provides separation of processes. The PID Namespace removes the 212 view of the system processes, and allows process ids to be reused including 213 pid 1. 214 215 In certain cases you want your container to share the host's process namespace, 216 basically allowing processes within the container to see all of the processes 217 on the system. For example, you could build a container with debugging tools 218 like `strace` or `gdb`, but want to use these tools when debugging processes 219 within the container. 220 221 ### Example: run htop inside a container 222 223 Create this Dockerfile: 224 225 ```dockerfile 226 FROM alpine:latest 227 RUN apk add --update htop && rm -rf /var/cache/apk/* 228 CMD ["htop"] 229 ``` 230 231 Build the Dockerfile and tag the image as `myhtop`: 232 233 ```bash 234 $ docker build -t myhtop . 235 ``` 236 237 Use the following command to run `htop` inside a container: 238 239 ```bash 240 $ docker run -it --rm --pid=host myhtop 241 ``` 242 243 Joining another container's pid namespace can be used for debugging that container. 244 245 ### Example 246 247 Start a container running a redis server: 248 249 ```bash 250 $ docker run --name my-redis -d redis 251 ``` 252 253 Debug the redis container by running another container that has strace in it: 254 255 ```bash 256 $ docker run -it --pid=container:my-redis my_strace_docker_image bash 257 $ strace -p 1 258 ``` 259 260 ## UTS settings (--uts) 261 262 --uts="" : Set the UTS namespace mode for the container, 263 'host': use the host's UTS namespace inside the container 264 265 The UTS namespace is for setting the hostname and the domain that is visible 266 to running processes in that namespace. By default, all containers, including 267 those with `--network=host`, have their own UTS namespace. The `host` setting will 268 result in the container using the same UTS namespace as the host. Note that 269 `--hostname` and `--domainname` are invalid in `host` UTS mode. 270 271 You may wish to share the UTS namespace with the host if you would like the 272 hostname of the container to change as the hostname of the host changes. A 273 more advanced use case would be changing the host's hostname from a container. 274 275 ## IPC settings (--ipc) 276 277 --ipc="MODE" : Set the IPC mode for the container 278 279 The following values are accepted: 280 281 | Value | Description | 282 |:---------------------------|:----------------------------------------------------------------------------------| 283 | "" | Use daemon's default. | 284 | "none" | Own private IPC namespace, with /dev/shm not mounted. | 285 | "private" | Own private IPC namespace. | 286 | "shareable" | Own private IPC namespace, with a possibility to share it with other containers. | 287 | "container:<_name-or-ID_>" | Join another ("shareable") container's IPC namespace. | 288 | "host" | Use the host system's IPC namespace. | 289 290 If not specified, daemon default is used, which can either be `"private"` 291 or `"shareable"`, depending on the daemon version and configuration. 292 293 IPC (POSIX/SysV IPC) namespace provides separation of named shared memory 294 segments, semaphores and message queues. 295 296 Shared memory segments are used to accelerate inter-process communication at 297 memory speed, rather than through pipes or through the network stack. Shared 298 memory is commonly used by databases and custom-built (typically C/OpenMPI, 299 C++/using boost libraries) high performance applications for scientific 300 computing and financial services industries. If these types of applications 301 are broken into multiple containers, you might need to share the IPC mechanisms 302 of the containers, using `"shareable"` mode for the main (i.e. "donor") 303 container, and `"container:<donor-name-or-ID>"` for other containers. 304 305 ## Network settings 306 307 --dns=[] : Set custom dns servers for the container 308 --network="bridge" : Connect a container to a network 309 'bridge': create a network stack on the default Docker bridge 310 'none': no networking 311 'container:<name|id>': reuse another container's network stack 312 'host': use the Docker host network stack 313 '<network-name>|<network-id>': connect to a user-defined network 314 --network-alias=[] : Add network-scoped alias for the container 315 --add-host="" : Add a line to /data/data/hilled.pwnterm/files/usr/etc/hosts (host:IP) 316 --mac-address="" : Sets the container's Ethernet device's MAC address 317 --ip="" : Sets the container's Ethernet device's IPv4 address 318 --ip6="" : Sets the container's Ethernet device's IPv6 address 319 --link-local-ip=[] : Sets one or more container's Ethernet device's link local IPv4/IPv6 addresses 320 321 By default, all containers have networking enabled and they can make any 322 outgoing connections. The operator can completely disable networking 323 with `docker run --network none` which disables all incoming and outgoing 324 networking. In cases like this, you would perform I/O through files or 325 `STDIN` and `STDOUT` only. 326 327 Publishing ports and linking to other containers only works with the default (bridge). The linking feature is a legacy feature. You should always prefer using Docker network drivers over linking. 328 329 Your container will use the same DNS servers as the host by default, but 330 you can override this with `--dns`. 331 332 By default, the MAC address is generated using the IP address allocated to the 333 container. You can set the container's MAC address explicitly by providing a 334 MAC address via the `--mac-address` parameter (format:`12:34:56:78:9a:bc`).Be 335 aware that Docker does not check if manually specified MAC addresses are unique. 336 337 Supported networks : 338 339 <table> 340 <thead> 341 <tr> 342 <th class="no-wrap">Network</th> 343 <th>Description</th> 344 </tr> 345 </thead> 346 <tbody> 347 <tr> 348 <td class="no-wrap"><strong>none</strong></td> 349 <td> 350 No networking in the container. 351 </td> 352 </tr> 353 <tr> 354 <td class="no-wrap"><strong>bridge</strong> (default)</td> 355 <td> 356 Connect the container to the bridge via veth interfaces. 357 </td> 358 </tr> 359 <tr> 360 <td class="no-wrap"><strong>host</strong></td> 361 <td> 362 Use the host's network stack inside the container. 363 </td> 364 </tr> 365 <tr> 366 <td class="no-wrap"><strong>container</strong>:<name|id></td> 367 <td> 368 Use the network stack of another container, specified via 369 its <i>name</i> or <i>id</i>. 370 </td> 371 </tr> 372 <tr> 373 <td class="no-wrap"><strong>NETWORK</strong></td> 374 <td> 375 Connects the container to a user created network (using <code>docker network create</code> command) 376 </td> 377 </tr> 378 </tbody> 379 </table> 380 381 #### Network: none 382 383 With the network is `none` a container will not have 384 access to any external routes. The container will still have a 385 `loopback` interface enabled in the container but it does not have any 386 routes to external traffic. 387 388 #### Network: bridge 389 390 With the network set to `bridge` a container will use docker's 391 default networking setup. A bridge is setup on the host, commonly named 392 `docker0`, and a pair of `veth` interfaces will be created for the 393 container. One side of the `veth` pair will remain on the host attached 394 to the bridge while the other side of the pair will be placed inside the 395 container's namespaces in addition to the `loopback` interface. An IP 396 address will be allocated for containers on the bridge's network and 397 traffic will be routed though this bridge to the container. 398 399 Containers can communicate via their IP addresses by default. To communicate by 400 name, they must be linked. 401 402 #### Network: host 403 404 With the network set to `host` a container will share the host's 405 network stack and all interfaces from the host will be available to the 406 container. The container's hostname will match the hostname on the host 407 system. Note that `--mac-address` is invalid in `host` netmode. Even in `host` 408 network mode a container has its own UTS namespace by default. As such 409 `--hostname` and `--domainname` are allowed in `host` network mode and will 410 only change the hostname and domain name inside the container. 411 Similar to `--hostname`, the `--add-host`, `--dns`, `--dns-search`, and 412 `--dns-option` options can be used in `host` network mode. These options update 413 `/data/data/hilled.pwnterm/files/usr/etc/hosts` or `/etc/resolv.conf` inside the container. No change are made to 414 `/data/data/hilled.pwnterm/files/usr/etc/hosts` and `/etc/resolv.conf` on the host. 415 416 Compared to the default `bridge` mode, the `host` mode gives *significantly* 417 better networking performance since it uses the host's native networking stack 418 whereas the bridge has to go through one level of virtualization through the 419 docker daemon. It is recommended to run containers in this mode when their 420 networking performance is critical, for example, a production Load Balancer 421 or a High Performance Web Server. 422 423 > **Note** 424 > 425 > `--network="host"` gives the container full access to local system services 426 > such as D-bus and is therefore considered insecure. 427 428 #### Network: container 429 430 With the network set to `container` a container will share the 431 network stack of another container. The other container's name must be 432 provided in the format of `--network container:<name|id>`. Note that `--add-host` 433 `--hostname` `--dns` `--dns-search` `--dns-option` and `--mac-address` are 434 invalid in `container` netmode, and `--publish` `--publish-all` `--expose` are 435 also invalid in `container` netmode. 436 437 Example running a Redis container with Redis binding to `localhost` then 438 running the `redis-cli` command and connecting to the Redis server over the 439 `localhost` interface. 440 441 ```bash 442 $ docker run -d --name redis example/redis --bind 127.0.0.1 443 $ # use the redis container's network stack to access localhost 444 $ docker run --rm -it --network container:redis example/redis-cli -h 127.0.0.1 445 ``` 446 447 #### User-defined network 448 449 You can create a network using a Docker network driver or an external network 450 driver plugin. You can connect multiple containers to the same network. Once 451 connected to a user-defined network, the containers can communicate easily using 452 only another container's IP address or name. 453 454 For `overlay` networks or custom plugins that support multi-host connectivity, 455 containers connected to the same multi-host network but launched from different 456 Engines can also communicate in this way. 457 458 The following example creates a network using the built-in `bridge` network 459 driver and running a container in the created network 460 461 ```bash 462 $ docker network create -d bridge my-net 463 $ docker run --network=my-net -itd --name=container3 busybox 464 ``` 465 466 ### Managing /data/data/hilled.pwnterm/files/usr/etc/hosts 467 468 Your container will have lines in `/data/data/hilled.pwnterm/files/usr/etc/hosts` which define the hostname of the 469 container itself as well as `localhost` and a few other common things. The 470 `--add-host` flag can be used to add additional lines to `/data/data/hilled.pwnterm/files/usr/etc/hosts`. 471 472 ```bash 473 $ docker run -it --add-host db-static:86.75.30.9 ubuntu cat /data/data/hilled.pwnterm/files/usr/etc/hosts 474 475 172.17.0.22 09d03f76bf2c 476 fe00::0 ip6-localnet 477 ff00::0 ip6-mcastprefix 478 ff02::1 ip6-allnodes 479 ff02::2 ip6-allrouters 480 127.0.0.1 localhost 481 ::1 localhost ip6-localhost ip6-loopback 482 86.75.30.9 db-static 483 ``` 484 485 If a container is connected to the default bridge network and `linked` 486 with other containers, then the container's `/data/data/hilled.pwnterm/files/usr/etc/hosts` file is updated 487 with the linked container's name. 488 489 > **Note** 490 > 491 > Since Docker may live update the container’s `/data/data/hilled.pwnterm/files/usr/etc/hosts` file, there 492 > may be situations when processes inside the container can end up reading an 493 > empty or incomplete `/data/data/hilled.pwnterm/files/usr/etc/hosts` file. In most cases, retrying the read again 494 > should fix the problem. 495 496 ## Restart policies (--restart) 497 498 Using the `--restart` flag on Docker run you can specify a restart policy for 499 how a container should or should not be restarted on exit. 500 501 When a restart policy is active on a container, it will be shown as either `Up` 502 or `Restarting` in [`docker ps`](commandline/ps.md). It can also be 503 useful to use [`docker events`](commandline/events.md) to see the 504 restart policy in effect. 505 506 Docker supports the following restart policies: 507 508 <table> 509 <thead> 510 <tr> 511 <th>Policy</th> 512 <th>Result</th> 513 </tr> 514 </thead> 515 <tbody> 516 <tr> 517 <td><strong>no</strong></td> 518 <td> 519 Do not automatically restart the container when it exits. This is the 520 default. 521 </td> 522 </tr> 523 <tr> 524 <td> 525 <span style="white-space: nowrap"> 526 <strong>on-failure</strong>[:max-retries] 527 </span> 528 </td> 529 <td> 530 Restart only if the container exits with a non-zero exit status. 531 Optionally, limit the number of restart retries the Docker 532 daemon attempts. 533 </td> 534 </tr> 535 <tr> 536 <td><strong>always</strong></td> 537 <td> 538 Always restart the container regardless of the exit status. 539 When you specify always, the Docker daemon will try to restart 540 the container indefinitely. The container will also always start 541 on daemon startup, regardless of the current state of the container. 542 </td> 543 </tr> 544 <tr> 545 <td><strong>unless-stopped</strong></td> 546 <td> 547 Always restart the container regardless of the exit status, 548 including on daemon startup, except if the container was put 549 into a stopped state before the Docker daemon was stopped. 550 </td> 551 </tr> 552 </tbody> 553 </table> 554 555 An ever increasing delay (double the previous delay, starting at 100 556 milliseconds) is added before each restart to prevent flooding the server. 557 This means the daemon will wait for 100 ms, then 200 ms, 400, 800, 1600, 558 and so on until either the `on-failure` limit is hit, or when you `docker stop` 559 or `docker rm -f` the container. 560 561 If a container is successfully restarted (the container is started and runs 562 for at least 10 seconds), the delay is reset to its default value of 100 ms. 563 564 You can specify the maximum amount of times Docker will try to restart the 565 container when using the **on-failure** policy. The default is that Docker 566 will try forever to restart the container. The number of (attempted) restarts 567 for a container can be obtained via [`docker inspect`](commandline/inspect.md). For example, to get the number of restarts 568 for container "my-container"; 569 570 ```bash 571 {% raw %} 572 $ docker inspect -f "{{ .RestartCount }}" my-container 573 # 2 574 {% endraw %} 575 ``` 576 577 Or, to get the last time the container was (re)started; 578 579 ```bash 580 {% raw %} 581 $ docker inspect -f "{{ .State.StartedAt }}" my-container 582 # 2015-03-04T23:47:07.691840179Z 583 {% endraw %} 584 ``` 585 586 Combining `--restart` (restart policy) with the `--rm` (clean up) flag results 587 in an error. On container restart, attached clients are disconnected. See the 588 examples on using the [`--rm` (clean up)](#clean-up-rm) flag later in this page. 589 590 ### Examples 591 592 ```bash 593 $ docker run --restart=always redis 594 ``` 595 596 This will run the `redis` container with a restart policy of **always** 597 so that if the container exits, Docker will restart it. 598 599 ```bash 600 $ docker run --restart=on-failure:10 redis 601 ``` 602 603 This will run the `redis` container with a restart policy of **on-failure** 604 and a maximum restart count of 10. If the `redis` container exits with a 605 non-zero exit status more than 10 times in a row Docker will abort trying to 606 restart the container. Providing a maximum restart limit is only valid for the 607 **on-failure** policy. 608 609 ## Exit Status 610 611 The exit code from `docker run` gives information about why the container 612 failed to run or why it exited. When `docker run` exits with a non-zero code, 613 the exit codes follow the `chroot` standard, see below: 614 615 **_125_** if the error is with Docker daemon **_itself_** 616 617 ```bash 618 $ docker run --foo busybox; echo $? 619 620 flag provided but not defined: --foo 621 See 'docker run --help'. 622 125 623 ``` 624 625 **_126_** if the **_contained command_** cannot be invoked 626 627 ```bash 628 $ docker run busybox /etc; echo $? 629 630 docker: Error response from daemon: Container command '/etc' could not be invoked. 631 126 632 ``` 633 634 **_127_** if the **_contained command_** cannot be found 635 636 ```bash 637 $ docker run busybox foo; echo $? 638 639 docker: Error response from daemon: Container command 'foo' not found or does not exist. 640 127 641 ``` 642 643 **_Exit code_** of **_contained command_** otherwise 644 645 ```bash 646 $ docker run busybox /bin/sh -c 'exit 3'; echo $? 647 648 3 649 ``` 650 651 ## Clean up (--rm) 652 653 By default a container's file system persists even after the container 654 exits. This makes debugging a lot easier (since you can inspect the 655 final state) and you retain all your data by default. But if you are 656 running short-term **foreground** processes, these container file 657 systems can really pile up. If instead you'd like Docker to 658 **automatically clean up the container and remove the file system when 659 the container exits**, you can add the `--rm` flag: 660 661 --rm=false: Automatically remove the container when it exits 662 663 > **Note** 664 > 665 > If you set the `--rm` flag, Docker also removes the anonymous volumes 666 > associated with the container when the container is removed. This is similar 667 > to running `docker rm -v my-container`. Only volumes that are specified without 668 > a name are removed. For example, when running: 669 > 670 > ```bash 671 > docker run --rm -v /foo -v awesome:/bar busybox top 672 > ``` 673 > 674 > the volume for `/foo` will be removed, but the volume for `/bar` will not. 675 > Volumes inherited via `--volumes-from` will be removed with the same logic: if 676 > the original volume was specified with a name it will **not** be removed. 677 678 ## Security configuration 679 680 | Option | Description | 681 |:------------------------------------------|:--------------------------------------------------------------------------| 682 | `--security-opt="label=user:USER"` | Set the label user for the container | 683 | `--security-opt="label=role:ROLE"` | Set the label role for the container | 684 | `--security-opt="label=type:TYPE"` | Set the label type for the container | 685 | `--security-opt="label=level:LEVEL"` | Set the label level for the container | 686 | `--security-opt="label=disable"` | Turn off label confinement for the container | 687 | `--security-opt="apparmor=PROFILE"` | Set the apparmor profile to be applied to the container | 688 | `--security-opt="no-new-privileges:true"` | Disable container processes from gaining new privileges | 689 | `--security-opt="seccomp=unconfined"` | Turn off seccomp confinement for the container | 690 | `--security-opt="seccomp=profile.json"` | White-listed syscalls seccomp Json file to be used as a seccomp filter | 691 692 693 You can override the default labeling scheme for each container by specifying 694 the `--security-opt` flag. Specifying the level in the following command 695 allows you to share the same content between containers. 696 697 ```bash 698 $ docker run --security-opt label=level:s0:c100,c200 -it fedora bash 699 ``` 700 701 > **Note** 702 > 703 > Automatic translation of MLS labels is not currently supported. 704 705 To disable the security labeling for this container versus running with the 706 `--privileged` flag, use the following command: 707 708 ```bash 709 $ docker run --security-opt label=disable -it fedora bash 710 ``` 711 712 If you want a tighter security policy on the processes within a container, 713 you can specify an alternate type for the container. You could run a container 714 that is only allowed to listen on Apache ports by executing the following 715 command: 716 717 ```bash 718 $ docker run --security-opt label=type:svirt_apache_t -it centos bash 719 ``` 720 721 > **Note** 722 > 723 > You would have to write policy defining a `svirt_apache_t` type. 724 725 If you want to prevent your container processes from gaining additional 726 privileges, you can execute the following command: 727 728 ```bash 729 $ docker run --security-opt no-new-privileges -it centos bash 730 ``` 731 732 This means that commands that raise privileges such as `su` or `sudo` will no longer work. 733 It also causes any seccomp filters to be applied later, after privileges have been dropped 734 which may mean you can have a more restrictive set of filters. 735 For more details, see the [kernel documentation](https://www.kernel.org/doc/Documentation/prctl/no_new_privs.txt). 736 737 ## Specify an init process 738 739 You can use the `--init` flag to indicate that an init process should be used as 740 the PID 1 in the container. Specifying an init process ensures the usual 741 responsibilities of an init system, such as reaping zombie processes, are 742 performed inside the created container. 743 744 The default init process used is the first `docker-init` executable found in the 745 system path of the Docker daemon process. This `docker-init` binary, included in 746 the default installation, is backed by [tini](https://github.com/krallin/tini). 747 748 ## Specify custom cgroups 749 750 Using the `--cgroup-parent` flag, you can pass a specific cgroup to run a 751 container in. This allows you to create and manage cgroups on their own. You can 752 define custom resources for those cgroups and put containers under a common 753 parent group. 754 755 ## Runtime constraints on resources 756 757 The operator can also adjust the performance parameters of the 758 container: 759 760 | Option | Description | 761 |:---------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 762 | `-m`, `--memory=""` | Memory limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. Minimum is 4M. | 763 | `--memory-swap=""` | Total memory limit (memory + swap, format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. | 764 | `--memory-reservation=""` | Memory soft limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. | 765 | `--kernel-memory=""` | Kernel memory limit (format: `<number>[<unit>]`). Number is a positive integer. Unit can be one of `b`, `k`, `m`, or `g`. Minimum is 4M. | 766 | `-c`, `--cpu-shares=0` | CPU shares (relative weight) | 767 | `--cpus=0.000` | Number of CPUs. Number is a fractional number. 0.000 means no limit. | 768 | `--cpu-period=0` | Limit the CPU CFS (Completely Fair Scheduler) period | 769 | `--cpuset-cpus=""` | CPUs in which to allow execution (0-3, 0,1) | 770 | `--cpuset-mems=""` | Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. | 771 | `--cpu-quota=0` | Limit the CPU CFS (Completely Fair Scheduler) quota | 772 | `--cpu-rt-period=0` | Limit the CPU real-time period. In microseconds. Requires parent cgroups be set and cannot be higher than parent. Also check rtprio ulimits. | 773 | `--cpu-rt-runtime=0` | Limit the CPU real-time runtime. In microseconds. Requires parent cgroups be set and cannot be higher than parent. Also check rtprio ulimits. | 774 | `--blkio-weight=0` | Block IO weight (relative weight) accepts a weight value between 10 and 1000. | 775 | `--blkio-weight-device=""` | Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`) | 776 | `--device-read-bps=""` | Limit read rate from a device (format: `<device-path>:<number>[<unit>]`). Number is a positive integer. Unit can be one of `kb`, `mb`, or `gb`. | 777 | `--device-write-bps=""` | Limit write rate to a device (format: `<device-path>:<number>[<unit>]`). Number is a positive integer. Unit can be one of `kb`, `mb`, or `gb`. | 778 | `--device-read-iops="" ` | Limit read rate (IO per second) from a device (format: `<device-path>:<number>`). Number is a positive integer. | 779 | `--device-write-iops="" ` | Limit write rate (IO per second) to a device (format: `<device-path>:<number>`). Number is a positive integer. | 780 | `--oom-kill-disable=false` | Whether to disable OOM Killer for the container or not. | 781 | `--oom-score-adj=0` | Tune container's OOM preferences (-1000 to 1000) | 782 | `--memory-swappiness=""` | Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. | 783 | `--shm-size=""` | Size of `/dev/shm`. The format is `<number><unit>`. `number` must be greater than `0`. Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`. | 784 785 ### User memory constraints 786 787 We have four ways to set user memory usage: 788 789 <table> 790 <thead> 791 <tr> 792 <th>Option</th> 793 <th>Result</th> 794 </tr> 795 </thead> 796 <tbody> 797 <tr> 798 <td class="no-wrap"> 799 <strong>memory=inf, memory-swap=inf</strong> (default) 800 </td> 801 <td> 802 There is no memory limit for the container. The container can use 803 as much memory as needed. 804 </td> 805 </tr> 806 <tr> 807 <td class="no-wrap"><strong>memory=L<inf, memory-swap=inf</strong></td> 808 <td> 809 (specify memory and set memory-swap as <code>-1</code>) The container is 810 not allowed to use more than L bytes of memory, but can use as much swap 811 as is needed (if the host supports swap memory). 812 </td> 813 </tr> 814 <tr> 815 <td class="no-wrap"><strong>memory=L<inf, memory-swap=2*L</strong></td> 816 <td> 817 (specify memory without memory-swap) The container is not allowed to 818 use more than L bytes of memory, swap <i>plus</i> memory usage is double 819 of that. 820 </td> 821 </tr> 822 <tr> 823 <td class="no-wrap"> 824 <strong>memory=L<inf, memory-swap=S<inf, L<=S</strong> 825 </td> 826 <td> 827 (specify both memory and memory-swap) The container is not allowed to 828 use more than L bytes of memory, swap <i>plus</i> memory usage is limited 829 by S. 830 </td> 831 </tr> 832 </tbody> 833 </table> 834 835 Examples: 836 837 ```bash 838 $ docker run -it ubuntu:14.04 /bin/bash 839 ``` 840 841 We set nothing about memory, this means the processes in the container can use 842 as much memory and swap memory as they need. 843 844 ```bash 845 $ docker run -it -m 300M --memory-swap -1 ubuntu:14.04 /bin/bash 846 ``` 847 848 We set memory limit and disabled swap memory limit, this means the processes in 849 the container can use 300M memory and as much swap memory as they need (if the 850 host supports swap memory). 851 852 ```bash 853 $ docker run -it -m 300M ubuntu:14.04 /bin/bash 854 ``` 855 856 We set memory limit only, this means the processes in the container can use 857 300M memory and 300M swap memory, by default, the total virtual memory size 858 (--memory-swap) will be set as double of memory, in this case, memory + swap 859 would be 2*300M, so processes can use 300M swap memory as well. 860 861 ```bash 862 $ docker run -it -m 300M --memory-swap 1G ubuntu:14.04 /bin/bash 863 ``` 864 865 We set both memory and swap memory, so the processes in the container can use 866 300M memory and 700M swap memory. 867 868 Memory reservation is a kind of memory soft limit that allows for greater 869 sharing of memory. Under normal circumstances, containers can use as much of 870 the memory as needed and are constrained only by the hard limits set with the 871 `-m`/`--memory` option. When memory reservation is set, Docker detects memory 872 contention or low memory and forces containers to restrict their consumption to 873 a reservation limit. 874 875 Always set the memory reservation value below the hard limit, otherwise the hard 876 limit takes precedence. A reservation of 0 is the same as setting no 877 reservation. By default (without reservation set), memory reservation is the 878 same as the hard memory limit. 879 880 Memory reservation is a soft-limit feature and does not guarantee the limit 881 won't be exceeded. Instead, the feature attempts to ensure that, when memory is 882 heavily contended for, memory is allocated based on the reservation hints/setup. 883 884 The following example limits the memory (`-m`) to 500M and sets the memory 885 reservation to 200M. 886 887 ```bash 888 $ docker run -it -m 500M --memory-reservation 200M ubuntu:14.04 /bin/bash 889 ``` 890 891 Under this configuration, when the container consumes memory more than 200M and 892 less than 500M, the next system memory reclaim attempts to shrink container 893 memory below 200M. 894 895 The following example set memory reservation to 1G without a hard memory limit. 896 897 ```bash 898 $ docker run -it --memory-reservation 1G ubuntu:14.04 /bin/bash 899 ``` 900 901 The container can use as much memory as it needs. The memory reservation setting 902 ensures the container doesn't consume too much memory for long time, because 903 every memory reclaim shrinks the container's consumption to the reservation. 904 905 By default, kernel kills processes in a container if an out-of-memory (OOM) 906 error occurs. To change this behaviour, use the `--oom-kill-disable` option. 907 Only disable the OOM killer on containers where you have also set the 908 `-m/--memory` option. If the `-m` flag is not set, this can result in the host 909 running out of memory and require killing the host's system processes to free 910 memory. 911 912 The following example limits the memory to 100M and disables the OOM killer for 913 this container: 914 915 ```bash 916 $ docker run -it -m 100M --oom-kill-disable ubuntu:14.04 /bin/bash 917 ``` 918 919 The following example, illustrates a dangerous way to use the flag: 920 921 ```bash 922 $ docker run -it --oom-kill-disable ubuntu:14.04 /bin/bash 923 ``` 924 925 The container has unlimited memory which can cause the host to run out memory 926 and require killing system processes to free memory. The `--oom-score-adj` 927 parameter can be changed to select the priority of which containers will 928 be killed when the system is out of memory, with negative scores making them 929 less likely to be killed, and positive scores more likely. 930 931 ### Kernel memory constraints 932 933 Kernel memory is fundamentally different than user memory as kernel memory can't 934 be swapped out. The inability to swap makes it possible for the container to 935 block system services by consuming too much kernel memory. Kernel memory includes： 936 937 - stack pages 938 - slab pages 939 - sockets memory pressure 940 - tcp memory pressure 941 942 You can setup kernel memory limit to constrain these kinds of memory. For example, 943 every process consumes some stack pages. By limiting kernel memory, you can 944 prevent new processes from being created when the kernel memory usage is too high. 945 946 Kernel memory is never completely independent of user memory. Instead, you limit 947 kernel memory in the context of the user memory limit. Assume "U" is the user memory 948 limit and "K" the kernel limit. There are three possible ways to set limits: 949 950 <table> 951 <thead> 952 <tr> 953 <th>Option</th> 954 <th>Result</th> 955 </tr> 956 </thead> 957 <tbody> 958 <tr> 959 <td class="no-wrap"><strong>U != 0, K = inf</strong> (default)</td> 960 <td> 961 This is the standard memory limitation mechanism already present before using 962 kernel memory. Kernel memory is completely ignored. 963 </td> 964 </tr> 965 <tr> 966 <td class="no-wrap"><strong>U != 0, K < U</strong></td> 967 <td> 968 Kernel memory is a subset of the user memory. This setup is useful in 969 deployments where the total amount of memory per-cgroup is overcommitted. 970 Overcommitting kernel memory limits is definitely not recommended, since the 971 box can still run out of non-reclaimable memory. 972 In this case, you can configure K so that the sum of all groups is 973 never greater than the total memory. Then, freely set U at the expense of 974 the system's service quality. 975 </td> 976 </tr> 977 <tr> 978 <td class="no-wrap"><strong>U != 0, K > U</strong></td> 979 <td> 980 Since kernel memory charges are also fed to the user counter and reclamation 981 is triggered for the container for both kinds of memory. This configuration 982 gives the admin a unified view of memory. It is also useful for people 983 who just want to track kernel memory usage. 984 </td> 985 </tr> 986 </tbody> 987 </table> 988 989 Examples: 990 991 ```bash 992 $ docker run -it -m 500M --kernel-memory 50M ubuntu:14.04 /bin/bash 993 ``` 994 995 We set memory and kernel memory, so the processes in the container can use 996 500M memory in total, in this 500M memory, it can be 50M kernel memory tops. 997 998 ```bash 999 $ docker run -it --kernel-memory 50M ubuntu:14.04 /bin/bash 1000 ``` 1001 1002 We set kernel memory without **-m**, so the processes in the container can 1003 use as much memory as they want, but they can only use 50M kernel memory. 1004 1005 ### Swappiness constraint 1006 1007 By default, a container's kernel can swap out a percentage of anonymous pages. 1008 To set this percentage for a container, specify a `--memory-swappiness` value 1009 between 0 and 100. A value of 0 turns off anonymous page swapping. A value of 1010 100 sets all anonymous pages as swappable. By default, if you are not using 1011 `--memory-swappiness`, memory swappiness value will be inherited from the parent. 1012 1013 For example, you can set: 1014 1015 ```bash 1016 $ docker run -it --memory-swappiness=0 ubuntu:14.04 /bin/bash 1017 ``` 1018 1019 Setting the `--memory-swappiness` option is helpful when you want to retain the 1020 container's working set and to avoid swapping performance penalties. 1021 1022 ### CPU share constraint 1023 1024 By default, all containers get the same proportion of CPU cycles. This proportion 1025 can be modified by changing the container's CPU share weighting relative 1026 to the weighting of all other running containers. 1027 1028 To modify the proportion from the default of 1024, use the `-c` or `--cpu-shares` 1029 flag to set the weighting to 2 or higher. If 0 is set, the system will ignore the 1030 value and use the default of 1024. 1031 1032 The proportion will only apply when CPU-intensive processes are running. 1033 When tasks in one container are idle, other containers can use the 1034 left-over CPU time. The actual amount of CPU time will vary depending on 1035 the number of containers running on the system. 1036 1037 For example, consider three containers, one has a cpu-share of 1024 and 1038 two others have a cpu-share setting of 512. When processes in all three 1039 containers attempt to use 100% of CPU, the first container would receive 1040 50% of the total CPU time. If you add a fourth container with a cpu-share 1041 of 1024, the first container only gets 33% of the CPU. The remaining containers 1042 receive 16.5%, 16.5% and 33% of the CPU. 1043 1044 On a multi-core system, the shares of CPU time are distributed over all CPU 1045 cores. Even if a container is limited to less than 100% of CPU time, it can 1046 use 100% of each individual CPU core. 1047 1048 For example, consider a system with more than three cores. If you start one 1049 container `{C0}` with `-c=512` running one process, and another container 1050 `{C1}` with `-c=1024` running two processes, this can result in the following 1051 division of CPU shares: 1052 1053 PID container CPU CPU share 1054 100 {C0} 0 100% of CPU0 1055 101 {C1} 1 100% of CPU1 1056 102 {C1} 2 100% of CPU2 1057 1058 ### CPU period constraint 1059 1060 The default CPU CFS (Completely Fair Scheduler) period is 100ms. We can use 1061 `--cpu-period` to set the period of CPUs to limit the container's CPU usage. 1062 And usually `--cpu-period` should work with `--cpu-quota`. 1063 1064 Examples: 1065 1066 ```bash 1067 $ docker run -it --cpu-period=50000 --cpu-quota=25000 ubuntu:14.04 /bin/bash 1068 ``` 1069 1070 If there is 1 CPU, this means the container can get 50% CPU worth of run-time every 50ms. 1071 1072 In addition to use `--cpu-period` and `--cpu-quota` for setting CPU period constraints, 1073 it is possible to specify `--cpus` with a float number to achieve the same purpose. 1074 For example, if there is 1 CPU, then `--cpus=0.5` will achieve the same result as 1075 setting `--cpu-period=50000` and `--cpu-quota=25000` (50% CPU). 1076 1077 The default value for `--cpus` is `0.000`, which means there is no limit. 1078 1079 For more information, see the [CFS documentation on bandwidth limiting](https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt). 1080 1081 ### Cpuset constraint 1082 1083 We can set cpus in which to allow execution for containers. 1084 1085 Examples: 1086 1087 ```bash 1088 $ docker run -it --cpuset-cpus="1,3" ubuntu:14.04 /bin/bash 1089 ``` 1090 1091 This means processes in container can be executed on cpu 1 and cpu 3. 1092 1093 ```bash 1094 $ docker run -it --cpuset-cpus="0-2" ubuntu:14.04 /bin/bash 1095 ``` 1096 1097 This means processes in container can be executed on cpu 0, cpu 1 and cpu 2. 1098 1099 We can set mems in which to allow execution for containers. Only effective 1100 on NUMA systems. 1101 1102 Examples: 1103 1104 ```bash 1105 $ docker run -it --cpuset-mems="1,3" ubuntu:14.04 /bin/bash 1106 ``` 1107 1108 This example restricts the processes in the container to only use memory from 1109 memory nodes 1 and 3. 1110 1111 ```bash 1112 $ docker run -it --cpuset-mems="0-2" ubuntu:14.04 /bin/bash 1113 ``` 1114 1115 This example restricts the processes in the container to only use memory from 1116 memory nodes 0, 1 and 2. 1117 1118 ### CPU quota constraint 1119 1120 The `--cpu-quota` flag limits the container's CPU usage. The default 0 value 1121 allows the container to take 100% of a CPU resource (1 CPU). The CFS (Completely Fair 1122 Scheduler) handles resource allocation for executing processes and is default 1123 Linux Scheduler used by the kernel. Set this value to 50000 to limit the container 1124 to 50% of a CPU resource. For multiple CPUs, adjust the `--cpu-quota` as necessary. 1125 For more information, see the [CFS documentation on bandwidth limiting](https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt). 1126 1127 ### Block IO bandwidth (Blkio) constraint 1128 1129 By default, all containers get the same proportion of block IO bandwidth 1130 (blkio). This proportion is 500. To modify this proportion, change the 1131 container's blkio weight relative to the weighting of all other running 1132 containers using the `--blkio-weight` flag. 1133 1134 > **Note:** 1135 > 1136 > The blkio weight setting is only available for direct IO. Buffered IO is not 1137 > currently supported. 1138 1139 The `--blkio-weight` flag can set the weighting to a value between 10 to 1000. 1140 For example, the commands below create two containers with different blkio 1141 weight: 1142 1143 ```bash 1144 $ docker run -it --name c1 --blkio-weight 300 ubuntu:14.04 /bin/bash 1145 $ docker run -it --name c2 --blkio-weight 600 ubuntu:14.04 /bin/bash 1146 ``` 1147 1148 If you do block IO in the two containers at the same time, by, for example: 1149 1150 ```bash 1151 $ time dd if=/mnt/zerofile of=test.out bs=1M count=1024 oflag=direct 1152 ``` 1153 1154 You'll find that the proportion of time is the same as the proportion of blkio 1155 weights of the two containers. 1156 1157 The `--blkio-weight-device="DEVICE_NAME:WEIGHT"` flag sets a specific device weight. 1158 The `DEVICE_NAME:WEIGHT` is a string containing a colon-separated device name and weight. 1159 For example, to set `/dev/sda` device weight to `200`: 1160 1161 ```bash 1162 $ docker run -it \ 1163 --blkio-weight-device "/dev/sda:200" \ 1164 ubuntu 1165 ``` 1166 1167 If you specify both the `--blkio-weight` and `--blkio-weight-device`, Docker 1168 uses the `--blkio-weight` as the default weight and uses `--blkio-weight-device` 1169 to override this default with a new value on a specific device. 1170 The following example uses a default weight of `300` and overrides this default 1171 on `/dev/sda` setting that weight to `200`: 1172 1173 ```bash 1174 $ docker run -it \ 1175 --blkio-weight 300 \ 1176 --blkio-weight-device "/dev/sda:200" \ 1177 ubuntu 1178 ``` 1179 1180 The `--device-read-bps` flag limits the read rate (bytes per second) from a device. 1181 For example, this command creates a container and limits the read rate to `1mb` 1182 per second from `/dev/sda`: 1183 1184 ```bash 1185 $ docker run -it --device-read-bps /dev/sda:1mb ubuntu 1186 ``` 1187 1188 The `--device-write-bps` flag limits the write rate (bytes per second) to a device. 1189 For example, this command creates a container and limits the write rate to `1mb` 1190 per second for `/dev/sda`: 1191 1192 ```bash 1193 $ docker run -it --device-write-bps /dev/sda:1mb ubuntu 1194 ``` 1195 1196 Both flags take limits in the `<device-path>:<limit>[unit]` format. Both read 1197 and write rates must be a positive integer. You can specify the rate in `kb` 1198 (kilobytes), `mb` (megabytes), or `gb` (gigabytes). 1199 1200 The `--device-read-iops` flag limits read rate (IO per second) from a device. 1201 For example, this command creates a container and limits the read rate to 1202 `1000` IO per second from `/dev/sda`: 1203 1204 ```bash 1205 $ docker run -ti --device-read-iops /dev/sda:1000 ubuntu 1206 ``` 1207 1208 The `--device-write-iops` flag limits write rate (IO per second) to a device. 1209 For example, this command creates a container and limits the write rate to 1210 `1000` IO per second to `/dev/sda`: 1211 1212 ```bash 1213 $ docker run -ti --device-write-iops /dev/sda:1000 ubuntu 1214 ``` 1215 1216 Both flags take limits in the `<device-path>:<limit>` format. Both read and 1217 write rates must be a positive integer. 1218 1219 ## Additional groups 1220 1221 ```bash 1222 --group-add: Add additional groups to run as 1223 ``` 1224 1225 By default, the docker container process runs with the supplementary groups looked 1226 up for the specified user. If one wants to add more to that list of groups, then 1227 one can use this flag: 1228 1229 ```bash 1230 $ docker run --rm --group-add audio --group-add nogroup --group-add 777 busybox id 1231 1232 uid=0(root) gid=0(root) groups=10(wheel),29(audio),99(nogroup),777 1233 ``` 1234 ## Runtime privilege and Linux capabilities 1235 1236 | Option | Description | 1237 |:---------------|:------------------------------------------------------------------------------| 1238 | `--cap-add` | Add Linux capabilities | 1239 | `--cap-drop` | Drop Linux capabilities | 1240 | `--privileged` | Give extended privileges to this container | 1241 | `--device=[]` | Allows you to run devices inside the container without the --privileged flag. | 1242 1243 By default, Docker containers are "unprivileged" and cannot, for 1244 example, run a Docker daemon inside a Docker container. This is because 1245 by default a container is not allowed to access any devices, but a 1246 "privileged" container is given access to all devices (see 1247 the documentation on [cgroups devices](https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt)). 1248 1249 When the operator executes `docker run --privileged`, Docker will enable 1250 access to all devices on the host as well as set some configuration 1251 in AppArmor or SELinux to allow the container nearly all the same access to the 1252 host as processes running outside containers on the host. Additional 1253 information about running with `--privileged` is available on the 1254 [Docker Blog](http://blog.docker.com/2013/09/docker-can-now-run-within-docker/). 1255 1256 If you want to limit access to a specific device or devices you can use 1257 the `--device` flag. It allows you to specify one or more devices that 1258 will be accessible within the container. 1259 1260 ```bash 1261 $ docker run --device=/dev/snd:/dev/snd ... 1262 ``` 1263 1264 By default, the container will be able to `read`, `write`, and `mknod` these devices. 1265 This can be overridden using a third `:rwm` set of options to each `--device` flag: 1266 1267 ```bash 1268 $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc 1269 1270 Command (m for help): q 1271 $ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk /dev/xvdc 1272 You will not be able to write the partition table. 1273 1274 Command (m for help): q 1275 1276 $ docker run --device=/dev/sda:/dev/xvdc:w --rm -it ubuntu fdisk /dev/xvdc 1277 crash.... 1278 1279 $ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc 1280 fdisk: unable to open /dev/xvdc: Operation not permitted 1281 ``` 1282 1283 In addition to `--privileged`, the operator can have fine grain control over the 1284 capabilities using `--cap-add` and `--cap-drop`. By default, Docker has a default 1285 list of capabilities that are kept. The following table lists the Linux capability 1286 options which are allowed by default and can be dropped. 1287 1288 | Capability Key | Capability Description | 1289 |:----------------------|:-------------------------------------------------------------------------------------------------------------------------------| 1290 | AUDIT_WRITE | Write records to kernel auditing log. | 1291 | CHOWN | Make arbitrary changes to file UIDs and GIDs (see chown(2)). | 1292 | DAC_OVERRIDE | Bypass file read, write, and execute permission checks. | 1293 | FOWNER | Bypass permission checks on operations that normally require the file system UID of the process to match the UID of the file. | 1294 | FSETID | Don't clear set-user-ID and set-group-ID permission bits when a file is modified. | 1295 | KILL | Bypass permission checks for sending signals. | 1296 | MKNOD | Create special files using mknod(2). | 1297 | NET_BIND_SERVICE | Bind a socket to internet domain privileged ports (port numbers less than 1024). | 1298 | NET_RAW | Use RAW and PACKET sockets. | 1299 | SETFCAP | Set file capabilities. | 1300 | SETGID | Make arbitrary manipulations of process GIDs and supplementary GID list. | 1301 | SETPCAP | Modify process capabilities. | 1302 | SETUID | Make arbitrary manipulations of process UIDs. | 1303 | SYS_CHROOT | Use chroot(2), change root directory. | 1304 1305 The next table shows the capabilities which are not granted by default and may be added. 1306 1307 | Capability Key | Capability Description | 1308 |:----------------------|:-------------------------------------------------------------------------------------------------------------------------------| 1309 | AUDIT_CONTROL | Enable and disable kernel auditing; change auditing filter rules; retrieve auditing status and filtering rules. | 1310 | AUDIT_READ | Allow reading the audit log via multicast netlink socket. | 1311 | BLOCK_SUSPEND | Allow preventing system suspends. | 1312 | BPF | Allow creating BPF maps, loading BPF Type Format (BTF) data, retrieve JITed code of BPF programs, and more. | 1313 | CHECKPOINT_RESTORE | Allow checkpoint/restore related operations. Introduced in kernel 5.9. | 1314 | DAC_READ_SEARCH | Bypass file read permission checks and directory read and execute permission checks. | 1315 | IPC_LOCK | Lock memory (mlock(2), mlockall(2), mmap(2), shmctl(2)). | 1316 | IPC_OWNER | Bypass permission checks for operations on System V IPC objects. | 1317 | LEASE | Establish leases on arbitrary files (see fcntl(2)). | 1318 | LINUX_IMMUTABLE | Set the FS_APPEND_FL and FS_IMMUTABLE_FL i-node flags. | 1319 | MAC_ADMIN | Allow MAC configuration or state changes. Implemented for the Smack LSM. | 1320 | MAC_OVERRIDE | Override Mandatory Access Control (MAC). Implemented for the Smack Linux Security Module (LSM). | 1321 | NET_ADMIN | Perform various network-related operations. | 1322 | NET_BROADCAST | Make socket broadcasts, and listen to multicasts. | 1323 | PERFMON | Allow system performance and observability privileged operations using perf_events, i915_perf and other kernel subsystems | 1324 | SYS_ADMIN | Perform a range of system administration operations. | 1325 | SYS_BOOT | Use reboot(2) and kexec_load(2), reboot and load a new kernel for later execution. | 1326 | SYS_MODULE | Load and unload kernel modules. | 1327 | SYS_NICE | Raise process nice value (nice(2), setpriority(2)) and change the nice value for arbitrary processes. | 1328 | SYS_PACCT | Use acct(2), switch process accounting on or off. | 1329 | SYS_PTRACE | Trace arbitrary processes using ptrace(2). | 1330 | SYS_RAWIO | Perform I/O port operations (iopl(2) and ioperm(2)). | 1331 | SYS_RESOURCE | Override resource Limits. | 1332 | SYS_TIME | Set system clock (settimeofday(2), stime(2), adjtimex(2)); set real-time (hardware) clock. | 1333 | SYS_TTY_CONFIG | Use vhangup(2); employ various privileged ioctl(2) operations on virtual terminals. | 1334 | SYSLOG | Perform privileged syslog(2) operations. | 1335 | WAKE_ALARM | Trigger something that will wake up the system. | 1336 1337 Further reference information is available on the [capabilities(7) - Linux man page](http://man7.org/linux/man-pages/man7/capabilities.7.html), 1338 and in the [Linux kernel source code](https://github.com/torvalds/linux/blob/124ea650d3072b005457faed69909221c2905a1f/include/uapi/linux/capability.h). 1339 1340 Both flags support the value `ALL`, so to allow a container to use all capabilities 1341 except for `MKNOD`: 1342 1343 ```bash 1344 $ docker run --cap-add=ALL --cap-drop=MKNOD ... 1345 ``` 1346 1347 The `--cap-add` and `--cap-drop` flags accept capabilities to be specified with 1348 a `CAP_` prefix. The following examples are therefore equivalent: 1349 1350 ```bash 1351 $ docker run --cap-add=SYS_ADMIN ... 1352 $ docker run --cap-add=CAP_SYS_ADMIN ... 1353 ``` 1354 1355 For interacting with the network stack, instead of using `--privileged` they 1356 should use `--cap-add=NET_ADMIN` to modify the network interfaces. 1357 1358 ```bash 1359 $ docker run -it --rm ubuntu:14.04 ip link add dummy0 type dummy 1360 1361 RTNETLINK answers: Operation not permitted 1362 1363 $ docker run -it --rm --cap-add=NET_ADMIN ubuntu:14.04 ip link add dummy0 type dummy 1364 ``` 1365 1366 To mount a FUSE based filesystem, you need to combine both `--cap-add` and 1367 `--device`: 1368 1369 ```bash 1370 $ docker run --rm -it --cap-add SYS_ADMIN sshfs sshfs sven@10.10.10.20:/home/sven /mnt 1371 1372 fuse: failed to open /dev/fuse: Operation not permitted 1373 1374 $ docker run --rm -it --device /dev/fuse sshfs sshfs sven@10.10.10.20:/home/sven /mnt 1375 1376 fusermount: mount failed: Operation not permitted 1377 1378 $ docker run --rm -it --cap-add SYS_ADMIN --device /dev/fuse sshfs 1379 1380 # sshfs sven@10.10.10.20:/home/sven /mnt 1381 The authenticity of host '10.10.10.20 (10.10.10.20)' can't be established. 1382 ECDSA key fingerprint is 25:34:85:75:25:b0:17:46:05:19:04:93:b5:dd:5f:c6. 1383 Are you sure you want to continue connecting (yes/no)? yes 1384 sven@10.10.10.20's password: 1385 1386 root@30aa0cfaf1b5:/# ls -la /mnt/src/docker 1387 1388 total 1516 1389 drwxrwxr-x 1 1000 1000 4096 Dec 4 06:08 . 1390 drwxrwxr-x 1 1000 1000 4096 Dec 4 11:46 .. 1391 -rw-rw-r-- 1 1000 1000 16 Oct 8 00:09 .dockerignore 1392 -rwxrwxr-x 1 1000 1000 464 Oct 8 00:09 .drone.yml 1393 drwxrwxr-x 1 1000 1000 4096 Dec 4 06:11 .git 1394 -rw-rw-r-- 1 1000 1000 461 Dec 4 06:08 .gitignore 1395 .... 1396 ``` 1397 1398 The default seccomp profile will adjust to the selected capabilities, in order to allow 1399 use of facilities allowed by the capabilities, so you should not have to adjust this. 1400 1401 ## Logging drivers (--log-driver) 1402 1403 The container can have a different logging driver than the Docker daemon. Use 1404 the `--log-driver=VALUE` with the `docker run` command to configure the 1405 container's logging driver. The following options are supported: 1406 1407 | Driver | Description | 1408 |:------------|:------------------------------------------------------------------------------------------------------------------------------| 1409 | `none` | Disables any logging for the container. `docker logs` won't be available with this driver. | 1410 | `json-file` | Default logging driver for Docker. Writes JSON messages to file. No logging options are supported for this driver. | 1411 | `syslog` | Syslog logging driver for Docker. Writes log messages to syslog. | 1412 | `journald` | Journald logging driver for Docker. Writes log messages to `journald`. | 1413 | `gelf` | Graylog Extended Log Format (GELF) logging driver for Docker. Writes log messages to a GELF endpoint likeGraylog or Logstash. | 1414 | `fluentd` | Fluentd logging driver for Docker. Writes log messages to `fluentd` (forward input). | 1415 | `awslogs` | Amazon CloudWatch Logs logging driver for Docker. Writes log messages to Amazon CloudWatch Logs | 1416 | `splunk` | Splunk logging driver for Docker. Writes log messages to `splunk` using Event Http Collector. | 1417 1418 The `docker logs` command is available only for the `json-file` and `journald` 1419 logging drivers. For detailed information on working with logging drivers, see 1420 [Configure logging drivers](https://docs.docker.com/config/containers/logging/configure/). 1421 1422 1423 ## Overriding Dockerfile image defaults 1424 1425 When a developer builds an image from a [*Dockerfile*](builder.md) 1426 or when she commits it, the developer can set a number of default parameters 1427 that take effect when the image starts up as a container. 1428 1429 Four of the Dockerfile commands cannot be overridden at runtime: `FROM`, 1430 `MAINTAINER`, `RUN`, and `ADD`. Everything else has a corresponding override 1431 in `docker run`. We'll go through what the developer might have set in each 1432 Dockerfile instruction and how the operator can override that setting. 1433 1434 - [CMD (Default Command or Options)](#cmd-default-command-or-options) 1435 - [ENTRYPOINT (Default Command to Execute at Runtime)]( 1436 #entrypoint-default-command-to-execute-at-runtime) 1437 - [EXPOSE (Incoming Ports)](#expose-incoming-ports) 1438 - [ENV (Environment Variables)](#env-environment-variables) 1439 - [HEALTHCHECK](#healthcheck) 1440 - [VOLUME (Shared Filesystems)](#volume-shared-filesystems) 1441 - [USER](#user) 1442 - [WORKDIR](#workdir) 1443 1444 ### CMD (default command or options) 1445 1446 Recall the optional `COMMAND` in the Docker 1447 commandline: 1448 1449 ```bash 1450 $ docker run [OPTIONS] IMAGE[:TAG|@DIGEST] [COMMAND] [ARG...] 1451 ``` 1452 1453 This command is optional because the person who created the `IMAGE` may 1454 have already provided a default `COMMAND` using the Dockerfile `CMD` 1455 instruction. As the operator (the person running a container from the 1456 image), you can override that `CMD` instruction just by specifying a new 1457 `COMMAND`. 1458 1459 If the image also specifies an `ENTRYPOINT` then the `CMD` or `COMMAND` 1460 get appended as arguments to the `ENTRYPOINT`. 1461 1462 ### ENTRYPOINT (default command to execute at runtime) 1463 1464 ```bash 1465 --entrypoint="": Overwrite the default entrypoint set by the image 1466 ``` 1467 1468 The `ENTRYPOINT` of an image is similar to a `COMMAND` because it 1469 specifies what executable to run when the container starts, but it is 1470 (purposely) more difficult to override. The `ENTRYPOINT` gives a 1471 container its default nature or behavior, so that when you set an 1472 `ENTRYPOINT` you can run the container *as if it were that binary*, 1473 complete with default options, and you can pass in more options via the 1474 `COMMAND`. But, sometimes an operator may want to run something else 1475 inside the container, so you can override the default `ENTRYPOINT` at 1476 runtime by using a string to specify the new `ENTRYPOINT`. Here is an 1477 example of how to run a shell in a container that has been set up to 1478 automatically run something else (like `/usr/bin/redis-server`): 1479 1480 ```bash 1481 $ docker run -it --entrypoint /bin/bash example/redis 1482 ``` 1483 1484 or two examples of how to pass more parameters to that ENTRYPOINT: 1485 1486 ```bash 1487 $ docker run -it --entrypoint /bin/bash example/redis -c ls -l 1488 $ docker run -it --entrypoint /usr/bin/redis-cli example/redis --help 1489 ``` 1490 1491 You can reset a containers entrypoint by passing an empty string, for example: 1492 1493 ```bash 1494 $ docker run -it --entrypoint="" mysql bash 1495 ``` 1496 1497 > **Note** 1498 > 1499 > Passing `--entrypoint` will clear out any default command set on the 1500 > image (i.e. any `CMD` instruction in the Dockerfile used to build it). 1501 1502 ### EXPOSE (incoming ports) 1503 1504 The following `run` command options work with container networking: 1505 1506 --expose=[]: Expose a port or a range of ports inside the container. 1507 These are additional to those exposed by the `EXPOSE` instruction 1508 -P : Publish all exposed ports to the host interfaces 1509 -p=[] : Publish a container's port or a range of ports to the host 1510 format: ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort 1511 Both hostPort and containerPort can be specified as a 1512 range of ports. When specifying ranges for both, the 1513 number of container ports in the range must match the 1514 number of host ports in the range, for example: 1515 -p 1234-1236:1234-1236/tcp 1516 1517 When specifying a range for hostPort only, the 1518 containerPort must not be a range. In this case the 1519 container port is published somewhere within the 1520 specified hostPort range. (e.g., `-p 1234-1236:1234/tcp`) 1521 1522 (use 'docker port' to see the actual mapping) 1523 1524 --link="" : Add link to another container (<name or id>:alias or <name or id>) 1525 1526 With the exception of the `EXPOSE` directive, an image developer hasn't 1527 got much control over networking. The `EXPOSE` instruction defines the 1528 initial incoming ports that provide services. These ports are available 1529 to processes inside the container. An operator can use the `--expose` 1530 option to add to the exposed ports. 1531 1532 To expose a container's internal port, an operator can start the 1533 container with the `-P` or `-p` flag. The exposed port is accessible on 1534 the host and the ports are available to any client that can reach the 1535 host. 1536 1537 The `-P` option publishes all the ports to the host interfaces. Docker 1538 binds each exposed port to a random port on the host. The range of 1539 ports are within an *ephemeral port range* defined by 1540 `/proc/sys/net/ipv4/ip_local_port_range`. Use the `-p` flag to 1541 explicitly map a single port or range of ports. 1542 1543 The port number inside the container (where the service listens) does 1544 not need to match the port number exposed on the outside of the 1545 container (where clients connect). For example, inside the container an 1546 HTTP service is listening on port 80 (and so the image developer 1547 specifies `EXPOSE 80` in the Dockerfile). At runtime, the port might be 1548 bound to 42800 on the host. To find the mapping between the host ports 1549 and the exposed ports, use `docker port`. 1550 1551 If the operator uses `--link` when starting a new client container in the 1552 default bridge network, then the client container can access the exposed 1553 port via a private networking interface. 1554 If `--link` is used when starting a container in a user-defined network as 1555 described in [*Networking overview*](https://docs.docker.com/network/), 1556 it will provide a named alias for the container being linked to. 1557 1558 ### ENV (environment variables) 1559 1560 Docker automatically sets some environment variables when creating a Linux 1561 container. Docker does not set any environment variables when creating a Windows 1562 container. 1563 1564 The following environment variables are set for Linux containers: 1565 1566 | Variable | Value | 1567 |:-----------|:-----------------------------------------------------------------------------------------------------| 1568 | `HOME` | Set based on the value of `USER` | 1569 | `HOSTNAME` | The hostname associated with the container | 1570 | `PATH` | Includes popular directories, such as `/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin` | 1571 | `TERM` | `xterm` if the container is allocated a pseudo-TTY | 1572 1573 1574 Additionally, the operator can **set any environment variable** in the 1575 container by using one or more `-e` flags, even overriding those mentioned 1576 above, or already defined by the developer with a Dockerfile `ENV`. If the 1577 operator names an environment variable without specifying a value, then the 1578 current value of the named variable is propagated into the container's environment: 1579 1580 ```bash 1581 $ export today=Wednesday 1582 $ docker run -e "deep=purple" -e today --rm alpine env 1583 1584 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin 1585 HOSTNAME=d2219b854598 1586 deep=purple 1587 today=Wednesday 1588 HOME=/root 1589 ``` 1590 1591 ```powershell 1592 PS C:\> docker run --rm -e "foo=bar" microsoft/nanoserver cmd /s /c set 1593 ALLUSERSPROFILE=C:\ProgramData 1594 APPDATA=C:\Users\ContainerAdministrator\AppData\Roaming 1595 CommonProgramFiles=C:\Program Files\Common Files 1596 CommonProgramFiles(x86)=C:\Program Files (x86)\Common Files 1597 CommonProgramW6432=C:\Program Files\Common Files 1598 COMPUTERNAME=C2FAEFCC8253 1599 ComSpec=C:\Windows\system32\cmd.exe 1600 foo=bar 1601 LOCALAPPDATA=C:\Users\ContainerAdministrator\AppData\Local 1602 NUMBER_OF_PROCESSORS=8 1603 OS=Windows_NT 1604 Path=C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\System32\WindowsPowerShell\v1.0\;C:\Users\ContainerAdministrator\AppData\Local\Microsoft\WindowsApps 1605 PATHEXT=.COM;.EXE;.BAT;.CMD 1606 PROCESSOR_ARCHITECTURE=AMD64 1607 PROCESSOR_IDENTIFIER=Intel64 Family 6 Model 62 Stepping 4, GenuineIntel 1608 PROCESSOR_LEVEL=6 1609 PROCESSOR_REVISION=3e04 1610 ProgramData=C:\ProgramData 1611 ProgramFiles=C:\Program Files 1612 ProgramFiles(x86)=C:\Program Files (x86) 1613 ProgramW6432=C:\Program Files 1614 PROMPT=$P$G 1615 PUBLIC=C:\Users\Public 1616 SystemDrive=C: 1617 SystemRoot=C:\Windows 1618 TEMP=C:\Users\ContainerAdministrator\AppData\Local\Temp 1619 TMP=C:\Users\ContainerAdministrator\AppData\Local\Temp 1620 USERDOMAIN=User Manager 1621 USERNAME=ContainerAdministrator 1622 USERPROFILE=C:\Users\ContainerAdministrator 1623 windir=C:\Windows 1624 ``` 1625 1626 Similarly the operator can set the **HOSTNAME** (Linux) or **COMPUTERNAME** (Windows) with `-h`. 1627 1628 ### HEALTHCHECK 1629 1630 ``` 1631 --health-cmd Command to run to check health 1632 --health-interval Time between running the check 1633 --health-retries Consecutive failures needed to report unhealthy 1634 --health-timeout Maximum time to allow one check to run 1635 --health-start-period Start period for the container to initialize before starting health-retries countdown 1636 --no-healthcheck Disable any container-specified HEALTHCHECK 1637 ``` 1638 1639 Example: 1640 1641 ```bash 1642 {% raw %} 1643 $ docker run --name=test -d \ 1644 --health-cmd='stat /etc/passwd || exit 1' \ 1645 --health-interval=2s \ 1646 busybox sleep 1d 1647 $ sleep 2; docker inspect --format='{{.State.Health.Status}}' test 1648 healthy 1649 $ docker exec test rm /etc/passwd 1650 $ sleep 2; docker inspect --format='{{json .State.Health}}' test 1651 { 1652 "Status": "unhealthy", 1653 "FailingStreak": 3, 1654 "Log": [ 1655 { 1656 "Start": "2016-05-25T17:22:04.635478668Z", 1657 "End": "2016-05-25T17:22:04.7272552Z", 1658 "ExitCode": 0, 1659 "Output": " File: /etc/passwd\n Size: 334 \tBlocks: 8 IO Block: 4096 regular file\nDevice: 32h/50d\tInode: 12 Links: 1\nAccess: (0664/-rw-rw-r--) Uid: ( 0/ root) Gid: ( 0/ root)\nAccess: 2015-12-05 22:05:32.000000000\nModify: 2015..." 1660 }, 1661 { 1662 "Start": "2016-05-25T17:22:06.732900633Z", 1663 "End": "2016-05-25T17:22:06.822168935Z", 1664 "ExitCode": 0, 1665 "Output": " File: /etc/passwd\n Size: 334 \tBlocks: 8 IO Block: 4096 regular file\nDevice: 32h/50d\tInode: 12 Links: 1\nAccess: (0664/-rw-rw-r--) Uid: ( 0/ root) Gid: ( 0/ root)\nAccess: 2015-12-05 22:05:32.000000000\nModify: 2015..." 1666 }, 1667 { 1668 "Start": "2016-05-25T17:22:08.823956535Z", 1669 "End": "2016-05-25T17:22:08.897359124Z", 1670 "ExitCode": 1, 1671 "Output": "stat: can't stat '/etc/passwd': No such file or directory\n" 1672 }, 1673 { 1674 "Start": "2016-05-25T17:22:10.898802931Z", 1675 "End": "2016-05-25T17:22:10.969631866Z", 1676 "ExitCode": 1, 1677 "Output": "stat: can't stat '/etc/passwd': No such file or directory\n" 1678 }, 1679 { 1680 "Start": "2016-05-25T17:22:12.971033523Z", 1681 "End": "2016-05-25T17:22:13.082015516Z", 1682 "ExitCode": 1, 1683 "Output": "stat: can't stat '/etc/passwd': No such file or directory\n" 1684 } 1685 ] 1686 } 1687 {% endraw %} 1688 ``` 1689 1690 The health status is also displayed in the `docker ps` output. 1691 1692 ### TMPFS (mount tmpfs filesystems) 1693 1694 ```bash 1695 --tmpfs=[]: Create a tmpfs mount with: container-dir[:<options>], 1696 where the options are identical to the Linux 1697 'mount -t tmpfs -o' command. 1698 ``` 1699 1700 The example below mounts an empty tmpfs into the container with the `rw`, 1701 `noexec`, `nosuid`, and `size=65536k` options. 1702 1703 ```bash 1704 $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image 1705 ``` 1706 1707 ### VOLUME (shared filesystems) 1708 1709 -v, --volume=[host-src:]container-dest[:<options>]: Bind mount a volume. 1710 The comma-delimited `options` are [rw|ro], [z|Z], 1711 [[r]shared|[r]slave|[r]private], and [nocopy]. 1712 The 'host-src' is an absolute path or a name value. 1713 1714 If neither 'rw' or 'ro' is specified then the volume is mounted in 1715 read-write mode. 1716 1717 The `nocopy` mode is used to disable automatically copying the requested volume 1718 path in the container to the volume storage location. 1719 For named volumes, `copy` is the default mode. Copy modes are not supported 1720 for bind-mounted volumes. 1721 1722 --volumes-from="": Mount all volumes from the given container(s) 1723 1724 > **Note** 1725 > 1726 > When using systemd to manage the Docker daemon's start and stop, in the systemd 1727 > unit file there is an option to control mount propagation for the Docker daemon 1728 > itself, called `MountFlags`. The value of this setting may cause Docker to not 1729 > see mount propagation changes made on the mount point. For example, if this value 1730 > is `slave`, you may not be able to use the `shared` or `rshared` propagation on 1731 > a volume. 1732 1733 The volumes commands are complex enough to have their own documentation 1734 in section [*Use volumes*](https://docs.docker.com/storage/volumes/). A developer can define 1735 one or more `VOLUME`'s associated with an image, but only the operator 1736 can give access from one container to another (or from a container to a 1737 volume mounted on the host). 1738 1739 The `container-dest` must always be an absolute path such as `/src/docs`. 1740 The `host-src` can either be an absolute path or a `name` value. If you 1741 supply an absolute path for the `host-dir`, Docker bind-mounts to the path 1742 you specify. If you supply a `name`, Docker creates a named volume by that `name`. 1743 1744 A `name` value must start with an alphanumeric character, 1745 followed by `a-z0-9`, `_` (underscore), `.` (period) or `-` (hyphen). 1746 An absolute path starts with a `/` (forward slash). 1747 1748 For example, you can specify either `/foo` or `foo` for a `host-src` value. 1749 If you supply the `/foo` value, Docker creates a bind mount. If you supply 1750 the `foo` specification, Docker creates a named volume. 1751 1752 ### USER 1753 1754 `root` (id = 0) is the default user within a container. The image developer can 1755 create additional users. Those users are accessible by name. When passing a numeric 1756 ID, the user does not have to exist in the container. 1757 1758 The developer can set a default user to run the first process with the 1759 Dockerfile `USER` instruction. When starting a container, the operator can override 1760 the `USER` instruction by passing the `-u` option. 1761 1762 -u="", --user="": Sets the username or UID used and optionally the groupname or GID for the specified command. 1763 1764 The followings examples are all valid: 1765 --user=[ user | user:group | uid | uid:gid | user:gid | uid:group ] 1766 1767 > **Note:** if you pass a numeric uid, it must be in the range of 0-2147483647. 1768 1769 ### WORKDIR 1770 1771 The default working directory for running binaries within a container is the 1772 root directory (`/`). It is possible to set a different working directory with the 1773 Dockerfile `WORKDIR` command. The operator can override this with: 1774 1775 -w="", --workdir="": Working directory inside the container