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