github.com/zhuohuang-hust/src-cbuild@v0.0.0-20230105071821-c7aab3e7c840/man/docker-run.1.md (about) 1 % DOCKER(1) Docker User Manuals 2 % Docker Community 3 % JUNE 2014 4 # NAME 5 docker-run - Run a command in a new container 6 7 # SYNOPSIS 8 **docker run** 9 [**-a**|**--attach**[=*[]*]] 10 [**--add-host**[=*[]*]] 11 [**--blkio-weight**[=*[BLKIO-WEIGHT]*]] 12 [**--blkio-weight-device**[=*[]*]] 13 [**--cpu-shares**[=*0*]] 14 [**--cap-add**[=*[]*]] 15 [**--cap-drop**[=*[]*]] 16 [**--cgroup-parent**[=*CGROUP-PATH*]] 17 [**--cidfile**[=*CIDFILE*]] 18 [**--cpu-count**[=*0*]] 19 [**--cpu-percent**[=*0*]] 20 [**--cpu-period**[=*0*]] 21 [**--cpu-quota**[=*0*]] 22 [**--cpu-rt-period**[=*0*]] 23 [**--cpu-rt-runtime**[=*0*]] 24 [**--cpus**[=*0.0*]] 25 [**--cpuset-cpus**[=*CPUSET-CPUS*]] 26 [**--cpuset-mems**[=*CPUSET-MEMS*]] 27 [**-d**|**--detach**] 28 [**--detach-keys**[=*[]*]] 29 [**--device**[=*[]*]] 30 [**--device-read-bps**[=*[]*]] 31 [**--device-read-iops**[=*[]*]] 32 [**--device-write-bps**[=*[]*]] 33 [**--device-write-iops**[=*[]*]] 34 [**--dns**[=*[]*]] 35 [**--dns-option**[=*[]*]] 36 [**--dns-search**[=*[]*]] 37 [**-e**|**--env**[=*[]*]] 38 [**--entrypoint**[=*ENTRYPOINT*]] 39 [**--env-file**[=*[]*]] 40 [**--expose**[=*[]*]] 41 [**--group-add**[=*[]*]] 42 [**-h**|**--hostname**[=*HOSTNAME*]] 43 [**--help**] 44 [**-i**|**--interactive**] 45 [**--ip**[=*IPv4-ADDRESS*]] 46 [**--ip6**[=*IPv6-ADDRESS*]] 47 [**--ipc**[=*IPC*]] 48 [**--isolation**[=*default*]] 49 [**--kernel-memory**[=*KERNEL-MEMORY*]] 50 [**-l**|**--label**[=*[]*]] 51 [**--label-file**[=*[]*]] 52 [**--link**[=*[]*]] 53 [**--link-local-ip**[=*[]*]] 54 [**--log-driver**[=*[]*]] 55 [**--log-opt**[=*[]*]] 56 [**-m**|**--memory**[=*MEMORY*]] 57 [**--mac-address**[=*MAC-ADDRESS*]] 58 [**--memory-reservation**[=*MEMORY-RESERVATION*]] 59 [**--memory-swap**[=*LIMIT*]] 60 [**--memory-swappiness**[=*MEMORY-SWAPPINESS*]] 61 [**--name**[=*NAME*]] 62 [**--network-alias**[=*[]*]] 63 [**--network**[=*"bridge"*]] 64 [**--oom-kill-disable**] 65 [**--oom-score-adj**[=*0*]] 66 [**-P**|**--publish-all**] 67 [**-p**|**--publish**[=*[]*]] 68 [**--pid**[=*[PID]*]] 69 [**--userns**[=*[]*]] 70 [**--pids-limit**[=*PIDS_LIMIT*]] 71 [**--privileged**] 72 [**--read-only**] 73 [**--restart**[=*RESTART*]] 74 [**--rm**] 75 [**--security-opt**[=*[]*]] 76 [**--storage-opt**[=*[]*]] 77 [**--stop-signal**[=*SIGNAL*]] 78 [**--stop-timeout**[=*TIMEOUT*]] 79 [**--shm-size**[=*[]*]] 80 [**--sig-proxy**[=*true*]] 81 [**--sysctl**[=*[]*]] 82 [**-t**|**--tty**] 83 [**--tmpfs**[=*[CONTAINER-DIR[:<OPTIONS>]*]] 84 [**-u**|**--user**[=*USER*]] 85 [**--ulimit**[=*[]*]] 86 [**--uts**[=*[]*]] 87 [**-v**|**--volume**[=*[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*]] 88 [**--volume-driver**[=*DRIVER*]] 89 [**--volumes-from**[=*[]*]] 90 [**-w**|**--workdir**[=*WORKDIR*]] 91 IMAGE [COMMAND] [ARG...] 92 93 # DESCRIPTION 94 95 Run a process in a new container. **docker run** starts a process with its own 96 file system, its own networking, and its own isolated process tree. The IMAGE 97 which starts the process may define defaults related to the process that will be 98 run in the container, the networking to expose, and more, but **docker run** 99 gives final control to the operator or administrator who starts the container 100 from the image. For that reason **docker run** has more options than any other 101 Docker command. 102 103 If the IMAGE is not already loaded then **docker run** will pull the IMAGE, and 104 all image dependencies, from the repository in the same way running **docker 105 pull** IMAGE, before it starts the container from that image. 106 107 # OPTIONS 108 **-a**, **--attach**=[] 109 Attach to STDIN, STDOUT or STDERR. 110 111 In foreground mode (the default when **-d** 112 is not specified), **docker run** can start the process in the container 113 and attach the console to the process's standard input, output, and standard 114 error. It can even pretend to be a TTY (this is what most commandline 115 executables expect) and pass along signals. The **-a** option can be set for 116 each of stdin, stdout, and stderr. 117 118 **--add-host**=[] 119 Add a custom host-to-IP mapping (host:ip) 120 121 Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** 122 option can be set multiple times. 123 124 **--blkio-weight**=*0* 125 Block IO weight (relative weight) accepts a weight value between 10 and 1000. 126 127 **--blkio-weight-device**=[] 128 Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`). 129 130 **--cpu-shares**=*0* 131 CPU shares (relative weight) 132 133 By default, all containers get the same proportion of CPU cycles. This proportion 134 can be modified by changing the container's CPU share weighting relative 135 to the weighting of all other running containers. 136 137 To modify the proportion from the default of 1024, use the **--cpu-shares** 138 flag to set the weighting to 2 or higher. 139 140 The proportion will only apply when CPU-intensive processes are running. 141 When tasks in one container are idle, other containers can use the 142 left-over CPU time. The actual amount of CPU time will vary depending on 143 the number of containers running on the system. 144 145 For example, consider three containers, one has a cpu-share of 1024 and 146 two others have a cpu-share setting of 512. When processes in all three 147 containers attempt to use 100% of CPU, the first container would receive 148 50% of the total CPU time. If you add a fourth container with a cpu-share 149 of 1024, the first container only gets 33% of the CPU. The remaining containers 150 receive 16.5%, 16.5% and 33% of the CPU. 151 152 On a multi-core system, the shares of CPU time are distributed over all CPU 153 cores. Even if a container is limited to less than 100% of CPU time, it can 154 use 100% of each individual CPU core. 155 156 For example, consider a system with more than three cores. If you start one 157 container **{C0}** with **-c=512** running one process, and another container 158 **{C1}** with **-c=1024** running two processes, this can result in the following 159 division of CPU shares: 160 161 PID container CPU CPU share 162 100 {C0} 0 100% of CPU0 163 101 {C1} 1 100% of CPU1 164 102 {C1} 2 100% of CPU2 165 166 **--cap-add**=[] 167 Add Linux capabilities 168 169 **--cap-drop**=[] 170 Drop Linux capabilities 171 172 **--cgroup-parent**="" 173 Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. 174 175 **--cidfile**="" 176 Write the container ID to the file 177 178 **--cpu-count**=*0* 179 Limit the number of CPUs available for execution by the container. 180 181 On Windows Server containers, this is approximated as a percentage of total CPU usage. 182 183 On Windows Server containers, the processor resource controls are mutually exclusive, the order of precedence is CPUCount first, then CPUShares, and CPUPercent last. 184 185 **--cpu-percent**=*0* 186 Limit the percentage of CPU available for execution by a container running on a Windows daemon. 187 188 On Windows Server containers, the processor resource controls are mutually exclusive, the order of precedence is CPUCount first, then CPUShares, and CPUPercent last. 189 190 **--cpu-period**=*0* 191 Limit the CPU CFS (Completely Fair Scheduler) period 192 193 Limit the container's CPU usage. This flag tell the kernel to restrict the container's CPU usage to the period you specify. 194 195 **--cpuset-cpus**="" 196 CPUs in which to allow execution (0-3, 0,1) 197 198 **--cpuset-mems**="" 199 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. 200 201 If you have four memory nodes on your system (0-3), use `--cpuset-mems=0,1` 202 then processes in your Docker container will only use memory from the first 203 two memory nodes. 204 205 **--cpu-quota**=*0* 206 Limit the CPU CFS (Completely Fair Scheduler) quota 207 208 Limit the container's CPU usage. By default, containers run with the full 209 CPU resource. This flag tell the kernel to restrict the container's CPU usage 210 to the quota you specify. 211 212 **--cpu-rt-period**=0 213 Limit the CPU real-time period in microseconds 214 215 Limit the container's Real Time CPU usage. This flag tell the kernel to restrict the container's Real Time CPU usage to the period you specify. 216 217 **--cpu-rt-runtime**=0 218 Limit the CPU real-time runtime in microseconds 219 220 Limit the containers Real Time CPU usage. This flag tells the kernel to limit the amount of time in a given CPU period Real Time tasks may consume. Ex: 221 Period of 1,000,000us and Runtime of 950,000us means that this container could consume 95% of available CPU and leave the remaining 5% to normal priority tasks. 222 223 The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup. 224 225 **--cpus**=0.0 226 Number of CPUs. The default is *0.0* which means no limit. 227 228 **-d**, **--detach**=*true*|*false* 229 Detached mode: run the container in the background and print the new container ID. The default is *false*. 230 231 At any time you can run **docker ps** in 232 the other shell to view a list of the running containers. You can reattach to a 233 detached container with **docker attach**. If you choose to run a container in 234 the detached mode, then you cannot use the **-rm** option. 235 236 When attached in the tty mode, you can detach from the container (and leave it 237 running) using a configurable key sequence. The default sequence is `CTRL-p CTRL-q`. 238 You configure the key sequence using the **--detach-keys** option or a configuration file. 239 See **config-json(5)** for documentation on using a configuration file. 240 241 **--detach-keys**="" 242 Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. 243 244 **--device**=[] 245 Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc:rwm) 246 247 **--device-read-bps**=[] 248 Limit read rate from a device (e.g. --device-read-bps=/dev/sda:1mb) 249 250 **--device-read-iops**=[] 251 Limit read rate from a device (e.g. --device-read-iops=/dev/sda:1000) 252 253 **--device-write-bps**=[] 254 Limit write rate to a device (e.g. --device-write-bps=/dev/sda:1mb) 255 256 **--device-write-iops**=[] 257 Limit write rate to a device (e.g. --device-write-iops=/dev/sda:1000) 258 259 **--dns-search**=[] 260 Set custom DNS search domains (Use --dns-search=. if you don't wish to set the search domain) 261 262 **--dns-option**=[] 263 Set custom DNS options 264 265 **--dns**=[] 266 Set custom DNS servers 267 268 This option can be used to override the DNS 269 configuration passed to the container. Typically this is necessary when the 270 host DNS configuration is invalid for the container (e.g., 127.0.0.1). When this 271 is the case the **--dns** flags is necessary for every run. 272 273 **-e**, **--env**=[] 274 Set environment variables 275 276 This option allows you to specify arbitrary 277 environment variables that are available for the process that will be launched 278 inside of the container. 279 280 **--entrypoint**="" 281 Overwrite the default ENTRYPOINT of the image 282 283 This option allows you to overwrite the default entrypoint of the image that 284 is set in the Dockerfile. The ENTRYPOINT of an image is similar to a COMMAND 285 because it specifies what executable to run when the container starts, but it is 286 (purposely) more difficult to override. The ENTRYPOINT gives a container its 287 default nature or behavior, so that when you set an ENTRYPOINT you can run the 288 container as if it were that binary, complete with default options, and you can 289 pass in more options via the COMMAND. But, sometimes an operator may want to run 290 something else inside the container, so you can override the default ENTRYPOINT 291 at runtime by using a **--entrypoint** and a string to specify the new 292 ENTRYPOINT. 293 294 **--env-file**=[] 295 Read in a line delimited file of environment variables 296 297 **--expose**=[] 298 Expose a port, or a range of ports (e.g. --expose=3300-3310) informs Docker 299 that the container listens on the specified network ports at runtime. Docker 300 uses this information to interconnect containers using links and to set up port 301 redirection on the host system. 302 303 **--group-add**=[] 304 Add additional groups to run as 305 306 **-h**, **--hostname**="" 307 Container host name 308 309 Sets the container host name that is available inside the container. 310 311 **--help** 312 Print usage statement 313 314 **-i**, **--interactive**=*true*|*false* 315 Keep STDIN open even if not attached. The default is *false*. 316 317 When set to true, keep stdin open even if not attached. The default is false. 318 319 **--ip**="" 320 Sets the container's interface IPv4 address (e.g. 172.23.0.9) 321 322 It can only be used in conjunction with **--net** for user-defined networks 323 324 **--ip6**="" 325 Sets the container's interface IPv6 address (e.g. 2001:db8::1b99) 326 327 It can only be used in conjunction with **--net** for user-defined networks 328 329 **--ipc**="" 330 Default is to create a private IPC namespace (POSIX SysV IPC) for the container 331 'container:<name|id>': reuses another container shared memory, semaphores and message queues 332 'host': use the host shared memory,semaphores and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. 333 334 **--isolation**="*default*" 335 Isolation specifies the type of isolation technology used by containers. Note 336 that the default on Windows server is `process`, and the default on Windows client 337 is `hyperv`. Linux only supports `default`. 338 339 **-l**, **--label**=[] 340 Set metadata on the container (e.g., --label com.example.key=value) 341 342 **--kernel-memory**="" 343 Kernel memory limit (format: `<number>[<unit>]`, where unit = b, k, m or g) 344 345 Constrains the kernel memory available to a container. If a limit of 0 346 is specified (not using `--kernel-memory`), the container's kernel memory 347 is not limited. If you specify a limit, it may be rounded up to a multiple 348 of the operating system's page size and the value can be very large, 349 millions of trillions. 350 351 **--label-file**=[] 352 Read in a line delimited file of labels 353 354 **--link**=[] 355 Add link to another container in the form of <name or id>:alias or just <name or id> 356 in which case the alias will match the name 357 358 If the operator 359 uses **--link** when starting the new client container, then the client 360 container can access the exposed port via a private networking interface. Docker 361 will set some environment variables in the client container to help indicate 362 which interface and port to use. 363 364 **--link-local-ip**=[] 365 Add one or more link-local IPv4/IPv6 addresses to the container's interface 366 367 **--log-driver**="*json-file*|*syslog*|*journald*|*gelf*|*fluentd*|*awslogs*|*splunk*|*etwlogs*|*gcplogs*|*none*" 368 Logging driver for the container. Default is defined by daemon `--log-driver` flag. 369 **Warning**: the `docker logs` command works only for the `json-file` and 370 `journald` logging drivers. 371 372 **--log-opt**=[] 373 Logging driver specific options. 374 375 **-m**, **--memory**="" 376 Memory limit (format: <number>[<unit>], where unit = b, k, m or g) 377 378 Allows you to constrain the memory available to a container. If the host 379 supports swap memory, then the **-m** memory setting can be larger than physical 380 RAM. If a limit of 0 is specified (not using **-m**), the container's memory is 381 not limited. The actual limit may be rounded up to a multiple of the operating 382 system's page size (the value would be very large, that's millions of trillions). 383 384 **--memory-reservation**="" 385 Memory soft limit (format: <number>[<unit>], where unit = b, k, m or g) 386 387 After setting memory reservation, when the system detects memory contention 388 or low memory, containers are forced to restrict their consumption to their 389 reservation. So you should always set the value below **--memory**, otherwise the 390 hard limit will take precedence. By default, memory reservation will be the same 391 as memory limit. 392 393 **--memory-swap**="LIMIT" 394 A limit value equal to memory plus swap. Must be used with the **-m** 395 (**--memory**) flag. The swap `LIMIT` should always be larger than **-m** 396 (**--memory**) value. By default, the swap `LIMIT` will be set to double 397 the value of --memory. 398 399 The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes), 400 `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you don't specify a 401 unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap. 402 403 **--mac-address**="" 404 Container MAC address (e.g. 92:d0:c6:0a:29:33) 405 406 Remember that the MAC address in an Ethernet network must be unique. 407 The IPv6 link-local address will be based on the device's MAC address 408 according to RFC4862. 409 410 **--name**="" 411 Assign a name to the container 412 413 The operator can identify a container in three ways: 414 UUID long identifier (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”) 415 UUID short identifier (“f78375b1c487”) 416 Name (“jonah”) 417 418 The UUID identifiers come from the Docker daemon, and if a name is not assigned 419 to the container with **--name** then the daemon will also generate a random 420 string name. The name is useful when defining links (see **--link**) (or any 421 other place you need to identify a container). This works for both background 422 and foreground Docker containers. 423 424 **--network**="*bridge*" 425 Set the Network mode for the container 426 'bridge': create a network stack on the default Docker bridge 427 'none': no networking 428 'container:<name|id>': reuse another container's network stack 429 'host': use the Docker host network stack. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure. 430 '<network-name>|<network-id>': connect to a user-defined network 431 432 **--network-alias**=[] 433 Add network-scoped alias for the container 434 435 **--oom-kill-disable**=*true*|*false* 436 Whether to disable OOM Killer for the container or not. 437 438 **--oom-score-adj**="" 439 Tune the host's OOM preferences for containers (accepts -1000 to 1000) 440 441 **-P**, **--publish-all**=*true*|*false* 442 Publish all exposed ports to random ports on the host interfaces. The default is *false*. 443 444 When set to true publish all exposed ports to the host interfaces. The 445 default is false. If the operator uses -P (or -p) then Docker will make the 446 exposed port accessible on the host and the ports will be available to any 447 client that can reach the host. When using -P, Docker will bind any exposed 448 port to a random port on the host within an *ephemeral port range* defined by 449 `/proc/sys/net/ipv4/ip_local_port_range`. To find the mapping between the host 450 ports and the exposed ports, use `docker port`. 451 452 **-p**, **--publish**=[] 453 Publish a container's port, or range of ports, to the host. 454 455 Format: `ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort` 456 Both hostPort and containerPort can be specified as a range of ports. 457 When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. 458 (e.g., `docker run -p 1234-1236:1222-1224 --name thisWorks -t busybox` 459 but not `docker run -p 1230-1236:1230-1240 --name RangeContainerPortsBiggerThanRangeHostPorts -t busybox`) 460 With ip: `docker run -p 127.0.0.1:$HOSTPORT:$CONTAINERPORT --name CONTAINER -t someimage` 461 Use `docker port` to see the actual mapping: `docker port CONTAINER $CONTAINERPORT` 462 463 **--pid**="" 464 Set the PID mode for the container 465 Default is to create a private PID namespace for the container 466 'container:<name|id>': join another container's PID namespace 467 'host': use the host's PID namespace for the container. Note: the host mode gives the container full access to local PID and is therefore considered insecure. 468 469 **--userns**="" 470 Set the usernamespace mode for the container when `userns-remap` option is enabled. 471 **host**: use the host usernamespace and enable all privileged options (e.g., `pid=host` or `--privileged`). 472 473 **--pids-limit**="" 474 Tune the container's pids limit. Set `-1` to have unlimited pids for the container. 475 476 **--uts**=*host* 477 Set the UTS mode for the container 478 **host**: use the host's UTS namespace inside the container. 479 Note: the host mode gives the container access to changing the host's hostname and is therefore considered insecure. 480 481 **--privileged**=*true*|*false* 482 Give extended privileges to this container. The default is *false*. 483 484 By default, Docker containers are 485 “unprivileged” (=false) and cannot, for example, run a Docker daemon inside the 486 Docker container. This is because by default a container is not allowed to 487 access any devices. A “privileged” container is given access to all devices. 488 489 When the operator executes **docker run --privileged**, Docker will enable access 490 to all devices on the host as well as set some configuration in AppArmor to 491 allow the container nearly all the same access to the host as processes running 492 outside of a container on the host. 493 494 **--read-only**=*true*|*false* 495 Mount the container's root filesystem as read only. 496 497 By default a container will have its root filesystem writable allowing processes 498 to write files anywhere. By specifying the `--read-only` flag the container will have 499 its root filesystem mounted as read only prohibiting any writes. 500 501 **--restart**="*no*" 502 Restart policy to apply when a container exits (no, on-failure[:max-retry], always, unless-stopped). 503 504 **--rm**=*true*|*false* 505 Automatically remove the container when it exits. The default is *false*. 506 `--rm` flag can work together with `-d`, and auto-removal will be done on daemon side. Note that it's 507 incompatible with any restart policy other than `none`. 508 509 **--security-opt**=[] 510 Security Options 511 512 "label=user:USER" : Set the label user for the container 513 "label=role:ROLE" : Set the label role for the container 514 "label=type:TYPE" : Set the label type for the container 515 "label=level:LEVEL" : Set the label level for the container 516 "label=disable" : Turn off label confinement for the container 517 "no-new-privileges" : Disable container processes from gaining additional privileges 518 519 "seccomp=unconfined" : Turn off seccomp confinement for the container 520 "seccomp=profile.json : White listed syscalls seccomp Json file to be used as a seccomp filter 521 522 "apparmor=unconfined" : Turn off apparmor confinement for the container 523 "apparmor=your-profile" : Set the apparmor confinement profile for the container 524 525 **--storage-opt**=[] 526 Storage driver options per container 527 528 $ docker run -it --storage-opt size=120G fedora /bin/bash 529 530 This (size) will allow to set the container rootfs size to 120G at creation time. 531 This option is only available for the `devicemapper`, `btrfs`, `overlay2` and `zfs` graph drivers. 532 For the `devicemapper`, `btrfs` and `zfs` storage drivers, user cannot pass a size less than the Default BaseFS Size. 533 For the `overlay2` storage driver, the size option is only available if the backing fs is `xfs` and mounted with the `pquota` mount option. 534 Under these conditions, user can pass any size less then the backing fs size. 535 536 **--stop-signal**=*SIGTERM* 537 Signal to stop a container. Default is SIGTERM. 538 539 **--stop-timeout**=*10* 540 Timeout (in seconds) to stop a container. Default is 10. 541 542 **--shm-size**="" 543 Size of `/dev/shm`. The format is `<number><unit>`. 544 `number` must be greater than `0`. Unit is optional and can be `b` (bytes), `k` (kilobytes), `m`(megabytes), or `g` (gigabytes). 545 If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`. 546 547 **--sysctl**=SYSCTL 548 Configure namespaced kernel parameters at runtime 549 550 IPC Namespace - current sysctls allowed: 551 552 kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced 553 Sysctls beginning with fs.mqueue.* 554 555 If you use the `--ipc=host` option these sysctls will not be allowed. 556 557 Network Namespace - current sysctls allowed: 558 Sysctls beginning with net.* 559 560 If you use the `--net=host` option these sysctls will not be allowed. 561 562 **--sig-proxy**=*true*|*false* 563 Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is *true*. 564 565 **--memory-swappiness**="" 566 Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. 567 568 **-t**, **--tty**=*true*|*false* 569 Allocate a pseudo-TTY. The default is *false*. 570 571 When set to true Docker can allocate a pseudo-tty and attach to the standard 572 input of any container. This can be used, for example, to run a throwaway 573 interactive shell. The default is false. 574 575 The **-t** option is incompatible with a redirection of the docker client 576 standard input. 577 578 **--tmpfs**=[] Create a tmpfs mount 579 580 Mount a temporary filesystem (`tmpfs`) mount into a container, for example: 581 582 $ docker run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image 583 584 This command mounts a `tmpfs` at `/tmp` within the container. The supported mount 585 options are the same as the Linux default `mount` flags. If you do not specify 586 any options, the systems uses the following options: 587 `rw,noexec,nosuid,nodev,size=65536k`. 588 589 **-u**, **--user**="" 590 Sets the username or UID used and optionally the groupname or GID for the specified command. 591 592 The followings examples are all valid: 593 --user [user | user:group | uid | uid:gid | user:gid | uid:group ] 594 595 Without this argument the command will be run as root in the container. 596 597 **--ulimit**=[] 598 Ulimit options 599 600 **-v**|**--volume**[=*[[HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*] 601 Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Docker 602 bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Docker 603 container. If 'HOST-DIR' is omitted, Docker automatically creates the new 604 volume on the host. The `OPTIONS` are a comma delimited list and can be: 605 606 * [rw|ro] 607 * [z|Z] 608 * [`[r]shared`|`[r]slave`|`[r]private`] 609 * [nocopy] 610 611 The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The `HOST-DIR` 612 can be an absolute path or a `name` value. A `name` value must start with an 613 alphanumeric character, followed by `a-z0-9`, `_` (underscore), `.` (period) or 614 `-` (hyphen). An absolute path starts with a `/` (forward slash). 615 616 If you supply a `HOST-DIR` that is an absolute path, Docker bind-mounts to the 617 path you specify. If you supply a `name`, Docker creates a named volume by that 618 `name`. For example, you can specify either `/foo` or `foo` for a `HOST-DIR` 619 value. If you supply the `/foo` value, Docker creates a bind-mount. If you 620 supply the `foo` specification, Docker creates a named volume. 621 622 You can specify multiple **-v** options to mount one or more mounts to a 623 container. To use these same mounts in other containers, specify the 624 **--volumes-from** option also. 625 626 You can add `:ro` or `:rw` suffix to a volume to mount it read-only or 627 read-write mode, respectively. By default, the volumes are mounted read-write. 628 See examples. 629 630 Labeling systems like SELinux require that proper labels are placed on volume 631 content mounted into a container. Without a label, the security system might 632 prevent the processes running inside the container from using the content. By 633 default, Docker does not change the labels set by the OS. 634 635 To change a label in the container context, you can add either of two suffixes 636 `:z` or `:Z` to the volume mount. These suffixes tell Docker to relabel file 637 objects on the shared volumes. The `z` option tells Docker that two containers 638 share the volume content. As a result, Docker labels the content with a shared 639 content label. Shared volume labels allow all containers to read/write content. 640 The `Z` option tells Docker to label the content with a private unshared label. 641 Only the current container can use a private volume. 642 643 By default bind mounted volumes are `private`. That means any mounts done 644 inside container will not be visible on host and vice-a-versa. One can change 645 this behavior by specifying a volume mount propagation property. Making a 646 volume `shared` mounts done under that volume inside container will be 647 visible on host and vice-a-versa. Making a volume `slave` enables only one 648 way mount propagation and that is mounts done on host under that volume 649 will be visible inside container but not the other way around. 650 651 To control mount propagation property of volume one can use `:[r]shared`, 652 `:[r]slave` or `:[r]private` propagation flag. Propagation property can 653 be specified only for bind mounted volumes and not for internal volumes or 654 named volumes. For mount propagation to work source mount point (mount point 655 where source dir is mounted on) has to have right propagation properties. For 656 shared volumes, source mount point has to be shared. And for slave volumes, 657 source mount has to be either shared or slave. 658 659 Use `df <source-dir>` to figure out the source mount and then use 660 `findmnt -o TARGET,PROPAGATION <source-mount-dir>` to figure out propagation 661 properties of source mount. If `findmnt` utility is not available, then one 662 can look at mount entry for source mount point in `/proc/self/mountinfo`. Look 663 at `optional fields` and see if any propagaion properties are specified. 664 `shared:X` means mount is `shared`, `master:X` means mount is `slave` and if 665 nothing is there that means mount is `private`. 666 667 To change propagation properties of a mount point use `mount` command. For 668 example, if one wants to bind mount source directory `/foo` one can do 669 `mount --bind /foo /foo` and `mount --make-private --make-shared /foo`. This 670 will convert /foo into a `shared` mount point. Alternatively one can directly 671 change propagation properties of source mount. Say `/` is source mount for 672 `/foo`, then use `mount --make-shared /` to convert `/` into a `shared` mount. 673 674 > **Note**: 675 > When using systemd to manage the Docker daemon's start and stop, in the systemd 676 > unit file there is an option to control mount propagation for the Docker daemon 677 > itself, called `MountFlags`. The value of this setting may cause Docker to not 678 > see mount propagation changes made on the mount point. For example, if this value 679 > is `slave`, you may not be able to use the `shared` or `rshared` propagation on 680 > a volume. 681 682 To disable automatic copying of data from the container path to the volume, use 683 the `nocopy` flag. The `nocopy` flag can be set on bind mounts and named volumes. 684 685 **--volume-driver**="" 686 Container's volume driver. This driver creates volumes specified either from 687 a Dockerfile's `VOLUME` instruction or from the `docker run -v` flag. 688 See **docker-volume-create(1)** for full details. 689 690 **--volumes-from**=[] 691 Mount volumes from the specified container(s) 692 693 Mounts already mounted volumes from a source container onto another 694 container. You must supply the source's container-id. To share 695 a volume, use the **--volumes-from** option when running 696 the target container. You can share volumes even if the source container 697 is not running. 698 699 By default, Docker mounts the volumes in the same mode (read-write or 700 read-only) as it is mounted in the source container. Optionally, you 701 can change this by suffixing the container-id with either the `:ro` or 702 `:rw ` keyword. 703 704 If the location of the volume from the source container overlaps with 705 data residing on a target container, then the volume hides 706 that data on the target. 707 708 **-w**, **--workdir**="" 709 Working directory inside the container 710 711 The default working directory for 712 running binaries within a container is the root directory (/). The developer can 713 set a different default with the Dockerfile WORKDIR instruction. The operator 714 can override the working directory by using the **-w** option. 715 716 # Exit Status 717 718 The exit code from `docker run` gives information about why the container 719 failed to run or why it exited. When `docker run` exits with a non-zero code, 720 the exit codes follow the `chroot` standard, see below: 721 722 **_125_** if the error is with Docker daemon **_itself_** 723 724 $ docker run --foo busybox; echo $? 725 # flag provided but not defined: --foo 726 See 'docker run --help'. 727 125 728 729 **_126_** if the **_contained command_** cannot be invoked 730 731 $ docker run busybox /etc; echo $? 732 # exec: "/etc": permission denied 733 docker: Error response from daemon: Contained command could not be invoked 734 126 735 736 **_127_** if the **_contained command_** cannot be found 737 738 $ docker run busybox foo; echo $? 739 # exec: "foo": executable file not found in $PATH 740 docker: Error response from daemon: Contained command not found or does not exist 741 127 742 743 **_Exit code_** of **_contained command_** otherwise 744 745 $ docker run busybox /bin/sh -c 'exit 3' 746 # 3 747 748 # EXAMPLES 749 750 ## Running container in read-only mode 751 752 During container image development, containers often need to write to the image 753 content. Installing packages into /usr, for example. In production, 754 applications seldom need to write to the image. Container applications write 755 to volumes if they need to write to file systems at all. Applications can be 756 made more secure by running them in read-only mode using the --read-only switch. 757 This protects the containers image from modification. Read only containers may 758 still need to write temporary data. The best way to handle this is to mount 759 tmpfs directories on /run and /tmp. 760 761 # docker run --read-only --tmpfs /run --tmpfs /tmp -i -t fedora /bin/bash 762 763 ## Exposing log messages from the container to the host's log 764 765 If you want messages that are logged in your container to show up in the host's 766 syslog/journal then you should bind mount the /dev/log directory as follows. 767 768 # docker run -v /dev/log:/dev/log -i -t fedora /bin/bash 769 770 From inside the container you can test this by sending a message to the log. 771 772 (bash)# logger "Hello from my container" 773 774 Then exit and check the journal. 775 776 # exit 777 778 # journalctl -b | grep Hello 779 780 This should list the message sent to logger. 781 782 ## Attaching to one or more from STDIN, STDOUT, STDERR 783 784 If you do not specify -a then Docker will attach everything (stdin,stdout,stderr) 785 . You can specify to which of the three standard streams (stdin, stdout, stderr) 786 you'd like to connect instead, as in: 787 788 # docker run -a stdin -a stdout -i -t fedora /bin/bash 789 790 ## Sharing IPC between containers 791 792 Using shm_server.c available here: https://www.cs.cf.ac.uk/Dave/C/node27.html 793 794 Testing `--ipc=host` mode: 795 796 Host shows a shared memory segment with 7 pids attached, happens to be from httpd: 797 798 ``` 799 $ sudo ipcs -m 800 801 ------ Shared Memory Segments -------- 802 key shmid owner perms bytes nattch status 803 0x01128e25 0 root 600 1000 7 804 ``` 805 806 Now run a regular container, and it correctly does NOT see the shared memory segment from the host: 807 808 ``` 809 $ docker run -it shm ipcs -m 810 811 ------ Shared Memory Segments -------- 812 key shmid owner perms bytes nattch status 813 ``` 814 815 Run a container with the new `--ipc=host` option, and it now sees the shared memory segment from the host httpd: 816 817 ``` 818 $ docker run -it --ipc=host shm ipcs -m 819 820 ------ Shared Memory Segments -------- 821 key shmid owner perms bytes nattch status 822 0x01128e25 0 root 600 1000 7 823 ``` 824 Testing `--ipc=container:CONTAINERID` mode: 825 826 Start a container with a program to create a shared memory segment: 827 ``` 828 $ docker run -it shm bash 829 $ sudo shm/shm_server & 830 $ sudo ipcs -m 831 832 ------ Shared Memory Segments -------- 833 key shmid owner perms bytes nattch status 834 0x0000162e 0 root 666 27 1 835 ``` 836 Create a 2nd container correctly shows no shared memory segment from 1st container: 837 ``` 838 $ docker run shm ipcs -m 839 840 ------ Shared Memory Segments -------- 841 key shmid owner perms bytes nattch status 842 ``` 843 844 Create a 3rd container using the new --ipc=container:CONTAINERID option, now it shows the shared memory segment from the first: 845 846 ``` 847 $ docker run -it --ipc=container:ed735b2264ac shm ipcs -m 848 $ sudo ipcs -m 849 850 ------ Shared Memory Segments -------- 851 key shmid owner perms bytes nattch status 852 0x0000162e 0 root 666 27 1 853 ``` 854 855 ## Linking Containers 856 857 > **Note**: This section describes linking between containers on the 858 > default (bridge) network, also known as "legacy links". Using `--link` 859 > on user-defined networks uses the DNS-based discovery, which does not add 860 > entries to `/etc/hosts`, and does not set environment variables for 861 > discovery. 862 863 The link feature allows multiple containers to communicate with each other. For 864 example, a container whose Dockerfile has exposed port 80 can be run and named 865 as follows: 866 867 # docker run --name=link-test -d -i -t fedora/httpd 868 869 A second container, in this case called linker, can communicate with the httpd 870 container, named link-test, by running with the **--link=<name>:<alias>** 871 872 # docker run -t -i --link=link-test:lt --name=linker fedora /bin/bash 873 874 Now the container linker is linked to container link-test with the alias lt. 875 Running the **env** command in the linker container shows environment variables 876 with the LT (alias) context (**LT_**) 877 878 # env 879 HOSTNAME=668231cb0978 880 TERM=xterm 881 LT_PORT_80_TCP=tcp://172.17.0.3:80 882 LT_PORT_80_TCP_PORT=80 883 LT_PORT_80_TCP_PROTO=tcp 884 LT_PORT=tcp://172.17.0.3:80 885 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin 886 PWD=/ 887 LT_NAME=/linker/lt 888 SHLVL=1 889 HOME=/ 890 LT_PORT_80_TCP_ADDR=172.17.0.3 891 _=/usr/bin/env 892 893 When linking two containers Docker will use the exposed ports of the container 894 to create a secure tunnel for the parent to access. 895 896 If a container is connected to the default bridge network and `linked` 897 with other containers, then the container's `/etc/hosts` file is updated 898 with the linked container's name. 899 900 > **Note** Since Docker may live update the container's `/etc/hosts` file, there 901 may be situations when processes inside the container can end up reading an 902 empty or incomplete `/etc/hosts` file. In most cases, retrying the read again 903 should fix the problem. 904 905 906 ## Mapping Ports for External Usage 907 908 The exposed port of an application can be mapped to a host port using the **-p** 909 flag. For example, an httpd port 80 can be mapped to the host port 8080 using the 910 following: 911 912 # docker run -p 8080:80 -d -i -t fedora/httpd 913 914 ## Creating and Mounting a Data Volume Container 915 916 Many applications require the sharing of persistent data across several 917 containers. Docker allows you to create a Data Volume Container that other 918 containers can mount from. For example, create a named container that contains 919 directories /var/volume1 and /tmp/volume2. The image will need to contain these 920 directories so a couple of RUN mkdir instructions might be required for you 921 fedora-data image: 922 923 # docker run --name=data -v /var/volume1 -v /tmp/volume2 -i -t fedora-data true 924 # docker run --volumes-from=data --name=fedora-container1 -i -t fedora bash 925 926 Multiple --volumes-from parameters will bring together multiple data volumes from 927 multiple containers. And it's possible to mount the volumes that came from the 928 DATA container in yet another container via the fedora-container1 intermediary 929 container, allowing to abstract the actual data source from users of that data: 930 931 # docker run --volumes-from=fedora-container1 --name=fedora-container2 -i -t fedora bash 932 933 ## Mounting External Volumes 934 935 To mount a host directory as a container volume, specify the absolute path to 936 the directory and the absolute path for the container directory separated by a 937 colon: 938 939 # docker run -v /var/db:/data1 -i -t fedora bash 940 941 When using SELinux, be aware that the host has no knowledge of container SELinux 942 policy. Therefore, in the above example, if SELinux policy is enforced, the 943 `/var/db` directory is not writable to the container. A "Permission Denied" 944 message will occur and an avc: message in the host's syslog. 945 946 947 To work around this, at time of writing this man page, the following command 948 needs to be run in order for the proper SELinux policy type label to be attached 949 to the host directory: 950 951 # chcon -Rt svirt_sandbox_file_t /var/db 952 953 954 Now, writing to the /data1 volume in the container will be allowed and the 955 changes will also be reflected on the host in /var/db. 956 957 ## Using alternative security labeling 958 959 You can override the default labeling scheme for each container by specifying 960 the `--security-opt` flag. For example, you can specify the MCS/MLS level, a 961 requirement for MLS systems. Specifying the level in the following command 962 allows you to share the same content between containers. 963 964 # docker run --security-opt label=level:s0:c100,c200 -i -t fedora bash 965 966 An MLS example might be: 967 968 # docker run --security-opt label=level:TopSecret -i -t rhel7 bash 969 970 To disable the security labeling for this container versus running with the 971 `--permissive` flag, use the following command: 972 973 # docker run --security-opt label=disable -i -t fedora bash 974 975 If you want a tighter security policy on the processes within a container, 976 you can specify an alternate type for the container. You could run a container 977 that is only allowed to listen on Apache ports by executing the following 978 command: 979 980 # docker run --security-opt label=type:svirt_apache_t -i -t centos bash 981 982 Note: 983 984 You would have to write policy defining a `svirt_apache_t` type. 985 986 ## Setting device weight 987 988 If you want to set `/dev/sda` device weight to `200`, you can specify the device 989 weight by `--blkio-weight-device` flag. Use the following command: 990 991 # docker run -it --blkio-weight-device "/dev/sda:200" ubuntu 992 993 ## Specify isolation technology for container (--isolation) 994 995 This option is useful in situations where you are running Docker containers on 996 Microsoft Windows. The `--isolation <value>` option sets a container's isolation 997 technology. On Linux, the only supported is the `default` option which uses 998 Linux namespaces. These two commands are equivalent on Linux: 999 1000 ``` 1001 $ docker run -d busybox top 1002 $ docker run -d --isolation default busybox top 1003 ``` 1004 1005 On Microsoft Windows, can take any of these values: 1006 1007 * `default`: Use the value specified by the Docker daemon's `--exec-opt` . If the `daemon` does not specify an isolation technology, Microsoft Windows uses `process` as its default value. 1008 * `process`: Namespace isolation only. 1009 * `hyperv`: Hyper-V hypervisor partition-based isolation. 1010 1011 In practice, when running on Microsoft Windows without a `daemon` option set, these two commands are equivalent: 1012 1013 ``` 1014 $ docker run -d --isolation default busybox top 1015 $ docker run -d --isolation process busybox top 1016 ``` 1017 1018 If you have set the `--exec-opt isolation=hyperv` option on the Docker `daemon`, any of these commands also result in `hyperv` isolation: 1019 1020 ``` 1021 $ docker run -d --isolation default busybox top 1022 $ docker run -d --isolation hyperv busybox top 1023 ``` 1024 1025 ## Setting Namespaced Kernel Parameters (Sysctls) 1026 1027 The `--sysctl` sets namespaced kernel parameters (sysctls) in the 1028 container. For example, to turn on IP forwarding in the containers 1029 network namespace, run this command: 1030 1031 $ docker run --sysctl net.ipv4.ip_forward=1 someimage 1032 1033 Note: 1034 1035 Not all sysctls are namespaced. Docker does not support changing sysctls 1036 inside of a container that also modify the host system. As the kernel 1037 evolves we expect to see more sysctls become namespaced. 1038 1039 See the definition of the `--sysctl` option above for the current list of 1040 supported sysctls. 1041 1042 # HISTORY 1043 April 2014, Originally compiled by William Henry (whenry at redhat dot com) 1044 based on docker.com source material and internal work. 1045 June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> 1046 July 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> 1047 November 2015, updated by Sally O'Malley <somalley@redhat.com>