github.com/jogo/docker@v1.7.0-rc1/docs/sources/reference/commandline/cli.md (about) 1 page_title: Command Line Interface 2 page_description: Docker's CLI command description and usage 3 page_keywords: Docker, Docker documentation, CLI, command line 4 5 # Docker Command Line 6 7 {{ include "no-remote-sudo.md" }} 8 9 To list available commands, either run `docker` with no parameters 10 or execute `docker help`: 11 12 $ docker 13 Usage: docker [OPTIONS] COMMAND [arg...] 14 -H, --host=[]: The socket(s) to bind to in daemon mode, specified using one or more tcp://host:port, unix:///path/to/socket, fd://* or fd://socketfd. 15 16 A self-sufficient runtime for Linux containers. 17 18 ... 19 Depending on your Docker system configuration, you may be required 20 to preface each `docker` command with `sudo`. To avoid having to use `sudo` with 21 the `docker` command, your system administrator can create a Unix group called 22 `docker` and add users to it. 23 24 For more information about installing Docker or `sudo` configuration, refer to 25 the [installation](/installation) instructions for your operating system. 26 27 ## Environment variables 28 29 For easy reference, the following list of environment variables are supported 30 by the `docker` command line: 31 32 * `DOCKER_CERT_PATH` The location of your authentication keys. 33 * `DOCKER_DRIVER` The graph driver to use. 34 * `DOCKER_HOST` Daemon socket to connect to. 35 * `DOCKER_NOWARN_KERNEL_VERSION` Prevent warnings that your Linux kernel is unsuitable for Docker. 36 * `DOCKER_RAMDISK` If set this will disable 'pivot_root'. 37 * `DOCKER_TLS_VERIFY` When set Docker uses TLS and verifies the remote. 38 * `DOCKER_TMPDIR` Location for temporary Docker files. 39 40 Because Docker is developed using 'Go', you can also use any environment 41 variables used by the 'Go' runtime. In particular, you may find these useful: 42 43 * `HTTP_PROXY` 44 * `HTTPS_PROXY` 45 * `NO_PROXY` 46 47 These Go environment variables are case-insensitive. See the 48 [Go specification](http://golang.org/pkg/net/http/) for details on these 49 variables. 50 51 ## Configuration files 52 53 The Docker command line stores its configuration files in a directory called 54 `.docker` within your `HOME` directory. Docker manages most of the files in 55 `.docker` and you should not modify them. However, you *can modify* the 56 `.docker/config.json` file to control certain aspects of how the `docker` 57 command behaves. 58 59 Currently, you can modify the `docker` command behavior using environment 60 variables or command-line options. You can also use options within 61 `config.json` to modify some of the same behavior. When using these 62 mechanisms, you must keep in mind the order of precedence among them. Command 63 line options override environment variables and environment variables override 64 properties you specify in a `config.json` file. 65 66 The `config.json` file stores a JSON encoding of a single `HttpHeaders` 67 property. The property specifies a set of headers to include in all 68 messages sent from the Docker client to the daemon. Docker does not try to 69 interpret or understand these header; it simply puts them into the messages. 70 Docker does not allow these headers to change any headers it sets for itself. 71 72 Following is a sample `config.json` file: 73 74 { 75 "HttpHeaders: { 76 "MyHeader": "MyValue" 77 } 78 } 79 80 ## Help 81 To list the help on any command just execute the command, followed by the `--help` option. 82 83 $ docker run --help 84 85 Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...] 86 87 Run a command in a new container 88 89 -a, --attach=[] Attach to STDIN, STDOUT or STDERR 90 -c, --cpu-shares=0 CPU shares (relative weight) 91 ... 92 93 ## Option types 94 95 Single character command line options can be combined, so rather than 96 typing `docker run -i -t --name test busybox sh`, 97 you can write `docker run -it --name test busybox sh`. 98 99 ### Boolean 100 101 Boolean options take the form `-d=false`. The value you see in the help text is the 102 default value which is set if you do **not** specify that flag. If you specify 103 a Boolean flag without a value, this will set the flag to `true`, irrespective 104 of the default value. 105 106 For example, running `docker run -d` will set the value to `true`, so 107 your container **will** run in "detached" mode, in the background. 108 109 Options which default to `true` (e.g., `docker build --rm=true`) can only 110 be set to the non-default value by explicitly setting them to `false`: 111 112 $ docker build --rm=false . 113 114 ### Multi 115 116 You can specify options like `-a=[]` multiple times in a single command line, 117 for example in these commands: 118 119 $ docker run -a stdin -a stdout -i -t ubuntu /bin/bash 120 $ docker run -a stdin -a stdout -a stderr ubuntu /bin/ls 121 122 Sometimes, multiple options can call for a more complex value string as for `-v`: 123 124 $ docker run -v /host:/container example/mysql 125 126 > **Note**: 127 > Do not use the `-t` and `-a stderr` options together due to limitations 128 > in the `pty` implementation. All `stderr` in `pty` mode simply goes to `stdout`. 129 130 ### Strings and Integers 131 132 Options like `--name=""` expect a string, and they 133 can only be specified once. Options like `-c=0` 134 expect an integer, and they can only be specified once. 135 136 ## daemon 137 138 Usage: docker [OPTIONS] COMMAND [arg...] 139 140 A self-sufficient runtime for linux containers. 141 142 Options: 143 --api-cors-header="" Set CORS headers in the remote API 144 -b, --bridge="" Attach containers to a network bridge 145 --bip="" Specify network bridge IP 146 -D, --debug=false Enable debug mode 147 -d, --daemon=false Enable daemon mode 148 --default-gateway="" Container default gateway IPv4 address 149 --default-gateway-v6="" Container default gateway IPv6 address 150 --dns=[] DNS server to use 151 --dns-search=[] DNS search domains to use 152 --default-ulimit=[] Set default ulimit settings for containers 153 -e, --exec-driver="native" Exec driver to use 154 --exec-opt=[] Set exec driver options 155 --exec-root="/var/run/docker" Root of the Docker execdriver 156 --fixed-cidr="" IPv4 subnet for fixed IPs 157 --fixed-cidr-v6="" IPv6 subnet for fixed IPs 158 -G, --group="docker" Group for the unix socket 159 -g, --graph="/var/lib/docker" Root of the Docker runtime 160 -H, --host=[] Daemon socket(s) to connect to 161 -h, --help=false Print usage 162 --icc=true Enable inter-container communication 163 --insecure-registry=[] Enable insecure registry communication 164 --ip=0.0.0.0 Default IP when binding container ports 165 --ip-forward=true Enable net.ipv4.ip_forward 166 --ip-masq=true Enable IP masquerading 167 --iptables=true Enable addition of iptables rules 168 --ipv6=false Enable IPv6 networking 169 -l, --log-level="info" Set the logging level 170 --label=[] Set key=value labels to the daemon 171 --log-driver="json-file" Default driver for container logs 172 --mtu=0 Set the containers network MTU 173 -p, --pidfile="/var/run/docker.pid" Path to use for daemon PID file 174 --registry-mirror=[] Preferred Docker registry mirror 175 -s, --storage-driver="" Storage driver to use 176 --selinux-enabled=false Enable selinux support 177 --storage-opt=[] Set storage driver options 178 --tls=false Use TLS; implied by --tlsverify 179 --tlscacert="~/.docker/ca.pem" Trust certs signed only by this CA 180 --tlscert="~/.docker/cert.pem" Path to TLS certificate file 181 --tlskey="~/.docker/key.pem" Path to TLS key file 182 --tlsverify=false Use TLS and verify the remote 183 --userland-proxy=true Use userland proxy for loopback traffic 184 -v, --version=false Print version information and quit 185 186 Options with [] may be specified multiple times. 187 188 The Docker daemon is the persistent process that manages containers. 189 Docker uses the same binary for both the daemon and client. To run the 190 daemon you provide the `-d` flag. 191 192 193 To run the daemon with debug output, use `docker -d -D`. 194 195 ### Daemon socket option 196 197 The Docker daemon can listen for [Docker Remote API](/reference/api/docker_remote_api/) 198 requests via three different types of Socket: `unix`, `tcp`, and `fd`. 199 200 By default, a `unix` domain socket (or IPC socket) is created at `/var/run/docker.sock`, 201 requiring either `root` permission, or `docker` group membership. 202 203 If you need to access the Docker daemon remotely, you need to enable the `tcp` 204 Socket. Beware that the default setup provides un-encrypted and un-authenticated 205 direct access to the Docker daemon - and should be secured either using the 206 [built in HTTPS encrypted socket](/articles/https/), or by putting a secure web 207 proxy in front of it. You can listen on port `2375` on all network interfaces 208 with `-H tcp://0.0.0.0:2375`, or on a particular network interface using its IP 209 address: `-H tcp://192.168.59.103:2375`. It is conventional to use port `2375` 210 for un-encrypted, and port `2376` for encrypted communication with the daemon. 211 212 > **Note** If you're using an HTTPS encrypted socket, keep in mind that only TLS1.0 213 > and greater are supported. Protocols SSLv3 and under are not supported anymore 214 > for security reasons. 215 216 On Systemd based systems, you can communicate with the daemon via 217 [Systemd socket activation](http://0pointer.de/blog/projects/socket-activation.html), use 218 `docker -d -H fd://`. Using `fd://` will work perfectly for most setups but 219 you can also specify individual sockets: `docker -d -H fd://3`. If the 220 specified socket activated files aren't found, then Docker will exit. You 221 can find examples of using Systemd socket activation with Docker and 222 Systemd in the [Docker source tree]( 223 https://github.com/docker/docker/tree/master/contrib/init/systemd/). 224 225 You can configure the Docker daemon to listen to multiple sockets at the same 226 time using multiple `-H` options: 227 228 # listen using the default unix socket, and on 2 specific IP addresses on this host. 229 docker -d -H unix:///var/run/docker.sock -H tcp://192.168.59.106 -H tcp://10.10.10.2 230 231 The Docker client will honor the `DOCKER_HOST` environment variable to set 232 the `-H` flag for the client. 233 234 $ docker -H tcp://0.0.0.0:2375 ps 235 # or 236 $ export DOCKER_HOST="tcp://0.0.0.0:2375" 237 $ docker ps 238 # both are equal 239 240 Setting the `DOCKER_TLS_VERIFY` environment variable to any value other than the empty 241 string is equivalent to setting the `--tlsverify` flag. The following are equivalent: 242 243 $ docker --tlsverify ps 244 # or 245 $ export DOCKER_TLS_VERIFY=1 246 $ docker ps 247 248 The Docker client will honor the `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` 249 environment variables (or the lowercase versions thereof). `HTTPS_PROXY` takes 250 precedence over `HTTP_PROXY`. 251 252 ### Daemon storage-driver option 253 254 The Docker daemon has support for several different image layer storage drivers: `aufs`, 255 `devicemapper`, `btrfs`, `zfs` and `overlay`. 256 257 The `aufs` driver is the oldest, but is based on a Linux kernel patch-set that 258 is unlikely to be merged into the main kernel. These are also known to cause some 259 serious kernel crashes. However, `aufs` is also the only storage driver that allows 260 containers to share executable and shared library memory, so is a useful choice 261 when running thousands of containers with the same program or libraries. 262 263 The `devicemapper` driver uses thin provisioning and Copy on Write (CoW) 264 snapshots. For each devicemapper graph location – typically 265 `/var/lib/docker/devicemapper` – a thin pool is created based on two block 266 devices, one for data and one for metadata. By default, these block devices 267 are created automatically by using loopback mounts of automatically created 268 sparse files. Refer to [Storage driver options](#storage-driver-options) below 269 for a way how to customize this setup. 270 [~jpetazzo/Resizing Docker containers with the Device Mapper plugin]( 271 http://jpetazzo.github.io/2014/01/29/docker-device-mapper-resize/) article 272 explains how to tune your existing setup without the use of options. 273 274 The `btrfs` driver is very fast for `docker build` - but like `devicemapper` does not 275 share executable memory between devices. Use `docker -d -s btrfs -g /mnt/btrfs_partition`. 276 277 The `zfs` driver is probably not fast as `btrfs` but has a longer track record 278 on stability. Thanks to `Single Copy ARC` shared blocks between clones will be 279 cached only once. Use `docker -d -s zfs`. To select a different zfs filesystem 280 set `zfs.fsname` option as described in [Storage driver options](#storage-driver-options): 281 282 The `overlay` is a very fast union filesystem. It is now merged in the main 283 Linux kernel as of [3.18.0](https://lkml.org/lkml/2014/10/26/137). 284 Call `docker -d -s overlay` to use it. 285 > **Note:** 286 > It is currently unsupported on `btrfs` or any Copy on Write filesystem 287 > and should only be used over `ext4` partitions. 288 289 #### Storage driver options 290 291 Particular storage-driver can be configured with options specified with 292 `--storage-opt` flags. Options for `devicemapper` are prefixed with `dm` and 293 options for `zfs` start with `zfs`. 294 295 Currently supported options of `devicemapper`: 296 297 * `dm.basesize` 298 299 Specifies the size to use when creating the base device, which limits the 300 size of images and containers. The default value is 10G. Note, thin devices 301 are inherently "sparse", so a 10G device which is mostly empty doesn't use 302 10 GB of space on the pool. However, the filesystem will use more space for 303 the empty case the larger the device is. 304 305 **Warning**: This value affects the system-wide "base" empty filesystem 306 that may already be initialized and inherited by pulled images. Typically, 307 a change to this value will require additional steps to take effect: 308 309 $ sudo service docker stop 310 $ sudo rm -rf /var/lib/docker 311 $ sudo service docker start 312 313 Example use: 314 315 $ docker -d --storage-opt dm.basesize=20G 316 317 * `dm.loopdatasize` 318 319 Specifies the size to use when creating the loopback file for the "data" 320 device which is used for the thin pool. The default size is 100G. Note that 321 the file is sparse, so it will not initially take up this much space. 322 323 Example use: 324 325 $ docker -d --storage-opt dm.loopdatasize=200G 326 327 * `dm.loopmetadatasize` 328 329 Specifies the size to use when creating the loopback file for the 330 "metadata" device which is used for the thin pool. The default size is 2G. 331 Note that the file is sparse, so it will not initially take up this much 332 space. 333 334 Example use: 335 336 $ docker -d --storage-opt dm.loopmetadatasize=4G 337 338 * `dm.fs` 339 340 Specifies the filesystem type to use for the base device. The supported 341 options are "ext4" and "xfs". The default is "ext4" 342 343 Example use: 344 345 $ docker -d --storage-opt dm.fs=xfs 346 347 * `dm.mkfsarg` 348 349 Specifies extra mkfs arguments to be used when creating the base device. 350 351 Example use: 352 353 $ docker -d --storage-opt "dm.mkfsarg=-O ^has_journal" 354 355 * `dm.mountopt` 356 357 Specifies extra mount options used when mounting the thin devices. 358 359 Example use: 360 361 $ docker -d --storage-opt dm.mountopt=nodiscard 362 363 * `dm.datadev` 364 365 Specifies a custom blockdevice to use for data for the thin pool. 366 367 If using a block device for device mapper storage, ideally both datadev and 368 metadatadev should be specified to completely avoid using the loopback 369 device. 370 371 Example use: 372 373 $ docker -d \ 374 --storage-opt dm.datadev=/dev/sdb1 \ 375 --storage-opt dm.metadatadev=/dev/sdc1 376 377 * `dm.metadatadev` 378 379 Specifies a custom blockdevice to use for metadata for the thin pool. 380 381 For best performance the metadata should be on a different spindle than the 382 data, or even better on an SSD. 383 384 If setting up a new metadata pool it is required to be valid. This can be 385 achieved by zeroing the first 4k to indicate empty metadata, like this: 386 387 $ dd if=/dev/zero of=$metadata_dev bs=4096 count=1 388 389 Example use: 390 391 $ docker -d \ 392 --storage-opt dm.datadev=/dev/sdb1 \ 393 --storage-opt dm.metadatadev=/dev/sdc1 394 395 * `dm.blocksize` 396 397 Specifies a custom blocksize to use for the thin pool. The default 398 blocksize is 64K. 399 400 Example use: 401 402 $ docker -d --storage-opt dm.blocksize=512K 403 404 * `dm.blkdiscard` 405 406 Enables or disables the use of blkdiscard when removing devicemapper 407 devices. This is enabled by default (only) if using loopback devices and is 408 required to resparsify the loopback file on image/container removal. 409 410 Disabling this on loopback can lead to *much* faster container removal 411 times, but will make the space used in `/var/lib/docker` directory not be 412 returned to the system for other use when containers are removed. 413 414 Example use: 415 416 $ docker -d --storage-opt dm.blkdiscard=false 417 418 * `dm.override_udev_sync_check` 419 420 Overrides the `udev` synchronization checks between `devicemapper` and `udev`. 421 `udev` is the device manager for the Linux kernel. 422 423 To view the `udev` sync support of a Docker daemon that is using the 424 `devicemapper` driver, run: 425 426 $ docker info 427 [...] 428 Udev Sync Supported: true 429 [...] 430 431 When `udev` sync support is `true`, then `devicemapper` and udev can 432 coordinate the activation and deactivation of devices for containers. 433 434 When `udev` sync support is `false`, a race condition occurs between 435 the`devicemapper` and `udev` during create and cleanup. The race condition 436 results in errors and failures. (For information on these failures, see 437 [docker#4036](https://github.com/docker/docker/issues/4036)) 438 439 To allow the `docker` daemon to start, regardless of `udev` sync not being 440 supported, set `dm.override_udev_sync_check` to true: 441 442 $ docker -d --storage-opt dm.override_udev_sync_check=true 443 444 When this value is `true`, the `devicemapper` continues and simply warns 445 you the errors are happening. 446 447 > **Note**: The ideal is to pursue a `docker` daemon and environment that 448 > does support synchronizing with `udev`. For further discussion on this 449 > topic, see [docker#4036](https://github.com/docker/docker/issues/4036). 450 > Otherwise, set this flag for migrating existing Docker daemons to a 451 > daemon with a supported environment. 452 453 ### Docker execdriver option 454 Currently supported options of `zfs`: 455 456 * `zfs.fsname` 457 458 Set zfs filesystem under which docker will create its own datasets. 459 By default docker will pick up the zfs filesystem where docker graph 460 (`/var/lib/docker`) is located. 461 462 Example use: 463 464 $ docker -d -s zfs --storage-opt zfs.fsname=zroot/docker 465 466 The Docker daemon uses a specifically built `libcontainer` execution driver as its 467 interface to the Linux kernel `namespaces`, `cgroups`, and `SELinux`. 468 469 There is still legacy support for the original [LXC userspace tools]( 470 https://linuxcontainers.org/) via the `lxc` execution driver, however, this is 471 not where the primary development of new functionality is taking place. 472 Add `-e lxc` to the daemon flags to use the `lxc` execution driver. 473 474 #### Options for the native execdriver 475 476 You can configure the `native` (libcontainer) execdriver using options specified 477 with the `--exec-opt` flag. All the flag's options have the `native` prefix. A 478 single `native.cgroupdriver` option is available. 479 480 The `native.cgroupdriver` option specifies the management of the container's 481 cgroups. You can specify `cgroupfs` or `systemd`. If you specify `systemd` and 482 it is not available, the system uses `cgroupfs`. By default, if no option is 483 specified, the execdriver first tries `systemd` and falls back to `cgroupfs`. 484 This example sets the execdriver to `cgroupfs`: 485 486 $ sudo docker -d --exec-opt native.cgroupdriver=cgroupfs 487 488 Setting this option applies to all containers the daemon launches. 489 490 ### Daemon DNS options 491 492 To set the DNS server for all Docker containers, use 493 `docker -d --dns 8.8.8.8`. 494 495 To set the DNS search domain for all Docker containers, use 496 `docker -d --dns-search example.com`. 497 498 ### Insecure registries 499 500 Docker considers a private registry either secure or insecure. 501 In the rest of this section, *registry* is used for *private registry*, and `myregistry:5000` 502 is a placeholder example for a private registry. 503 504 A secure registry uses TLS and a copy of its CA certificate is placed on the Docker host at 505 `/etc/docker/certs.d/myregistry:5000/ca.crt`. 506 An insecure registry is either not using TLS (i.e., listening on plain text HTTP), or is using 507 TLS with a CA certificate not known by the Docker daemon. The latter can happen when the 508 certificate was not found under `/etc/docker/certs.d/myregistry:5000/`, or if the certificate 509 verification failed (i.e., wrong CA). 510 511 By default, Docker assumes all, but local (see local registries below), registries are secure. 512 Communicating with an insecure registry is not possible if Docker assumes that registry is secure. 513 In order to communicate with an insecure registry, the Docker daemon requires `--insecure-registry` 514 in one of the following two forms: 515 516 * `--insecure-registry myregistry:5000` tells the Docker daemon that myregistry:5000 should be considered insecure. 517 * `--insecure-registry 10.1.0.0/16` tells the Docker daemon that all registries whose domain resolve to an IP address is part 518 of the subnet described by the CIDR syntax, should be considered insecure. 519 520 The flag can be used multiple times to allow multiple registries to be marked as insecure. 521 522 If an insecure registry is not marked as insecure, `docker pull`, `docker push`, and `docker search` 523 will result in an error message prompting the user to either secure or pass the `--insecure-registry` 524 flag to the Docker daemon as described above. 525 526 Local registries, whose IP address falls in the 127.0.0.0/8 range, are automatically marked as insecure 527 as of Docker 1.3.2. It is not recommended to rely on this, as it may change in the future. 528 529 ### Running a Docker daemon behind a HTTPS_PROXY 530 531 When running inside a LAN that uses a `HTTPS` proxy, the Docker Hub certificates 532 will be replaced by the proxy's certificates. These certificates need to be added 533 to your Docker host's configuration: 534 535 1. Install the `ca-certificates` package for your distribution 536 2. Ask your network admin for the proxy's CA certificate and append them to 537 `/etc/pki/tls/certs/ca-bundle.crt` 538 3. Then start your Docker daemon with `HTTPS_PROXY=http://username:password@proxy:port/ docker -d`. 539 The `username:` and `password@` are optional - and are only needed if your proxy 540 is set up to require authentication. 541 542 This will only add the proxy and authentication to the Docker daemon's requests - 543 your `docker build`s and running containers will need extra configuration to use 544 the proxy 545 546 ### Default Ulimits 547 548 `--default-ulimit` allows you to set the default `ulimit` options to use for all 549 containers. It takes the same options as `--ulimit` for `docker run`. If these 550 defaults are not set, `ulimit` settings will be inherited, if not set on 551 `docker run`, from the Docker daemon. Any `--ulimit` options passed to 552 `docker run` will overwrite these defaults. 553 554 ### Miscellaneous options 555 556 IP masquerading uses address translation to allow containers without a public IP to talk 557 to other machines on the Internet. This may interfere with some network topologies and 558 can be disabled with --ip-masq=false. 559 560 Docker supports softlinks for the Docker data directory 561 (`/var/lib/docker`) and for `/var/lib/docker/tmp`. The `DOCKER_TMPDIR` and the data directory can be set like this: 562 563 DOCKER_TMPDIR=/mnt/disk2/tmp /usr/local/bin/docker -d -D -g /var/lib/docker -H unix:// > /var/lib/boot2docker/docker.log 2>&1 564 # or 565 export DOCKER_TMPDIR=/mnt/disk2/tmp 566 /usr/local/bin/docker -d -D -g /var/lib/docker -H unix:// > /var/lib/boot2docker/docker.log 2>&1 567 568 569 ## attach 570 571 Usage: docker attach [OPTIONS] CONTAINER 572 573 Attach to a running container 574 575 --no-stdin=false Do not attach STDIN 576 --sig-proxy=true Proxy all received signals to the process 577 578 The `docker attach` command allows you to attach to a running container using 579 the container's ID or name, either to view its ongoing output or to control it 580 interactively. You can attach to the same contained process multiple times 581 simultaneously, screen sharing style, or quickly view the progress of your 582 daemonized process. 583 584 You can detach from the container and leave it running with `CTRL-p 585 CTRL-q` (for a quiet exit) or with `CTRL-c` if `--sig-proxy` is false. 586 587 If `--sig-proxy` is true (the default),`CTRL-c` sends a `SIGINT` 588 to the container. 589 590 >**Note**: A process running as PID 1 inside a container is treated 591 >specially by Linux: it ignores any signal with the default action. 592 >So, the process will not terminate on `SIGINT` or `SIGTERM` unless it is 593 >coded to do so. 594 595 It is forbidden to redirect the standard input of a `docker attach` command while 596 attaching to a tty-enabled container (i.e.: launched with `-t`). 597 598 #### Examples 599 600 $ docker run -d --name topdemo ubuntu /usr/bin/top -b 601 $ docker attach topdemo 602 top - 02:05:52 up 3:05, 0 users, load average: 0.01, 0.02, 0.05 603 Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie 604 Cpu(s): 0.1%us, 0.2%sy, 0.0%ni, 99.7%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st 605 Mem: 373572k total, 355560k used, 18012k free, 27872k buffers 606 Swap: 786428k total, 0k used, 786428k free, 221740k cached 607 608 PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND 609 1 root 20 0 17200 1116 912 R 0 0.3 0:00.03 top 610 611 top - 02:05:55 up 3:05, 0 users, load average: 0.01, 0.02, 0.05 612 Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie 613 Cpu(s): 0.0%us, 0.2%sy, 0.0%ni, 99.8%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st 614 Mem: 373572k total, 355244k used, 18328k free, 27872k buffers 615 Swap: 786428k total, 0k used, 786428k free, 221776k cached 616 617 PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND 618 1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top 619 620 621 top - 02:05:58 up 3:06, 0 users, load average: 0.01, 0.02, 0.05 622 Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie 623 Cpu(s): 0.2%us, 0.3%sy, 0.0%ni, 99.5%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st 624 Mem: 373572k total, 355780k used, 17792k free, 27880k buffers 625 Swap: 786428k total, 0k used, 786428k free, 221776k cached 626 627 PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND 628 1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top 629 ^C$ 630 $ echo $? 631 0 632 $ docker ps -a | grep topdemo 633 7998ac8581f9 ubuntu:14.04 "/usr/bin/top -b" 38 seconds ago Exited (0) 21 seconds ago topdemo 634 635 And in this second example, you can see the exit code returned by the `bash` process 636 is returned by the `docker attach` command to its caller too: 637 638 $ docker run --name test -d -it debian 639 275c44472aebd77c926d4527885bb09f2f6db21d878c75f0a1c212c03d3bcfab 640 $ docker attach test 641 $$ exit 13 642 exit 643 $ echo $? 644 13 645 $ docker ps -a | grep test 646 275c44472aeb debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test 647 648 ## build 649 650 Usage: docker build [OPTIONS] PATH | URL | - 651 652 Build a new image from the source code at PATH 653 654 -f, --file="" Name of the Dockerfile (Default is 'PATH/Dockerfile') 655 --force-rm=false Always remove intermediate containers 656 --no-cache=false Do not use cache when building the image 657 --pull=false Always attempt to pull a newer version of the image 658 -q, --quiet=false Suppress the verbose output generated by the containers 659 --rm=true Remove intermediate containers after a successful build 660 -t, --tag="" Repository name (and optionally a tag) for the image 661 -m, --memory="" Memory limit for all build containers 662 --memory-swap="" Total memory (memory + swap), `-1` to disable swap 663 -c, --cpu-shares CPU Shares (relative weight) 664 --cpuset-mems="" MEMs in which to allow execution, e.g. `0-3`, `0,1` 665 --cpuset-cpus="" CPUs in which to allow exection, e.g. `0-3`, `0,1` 666 --cgroup-parent="" Optional parent cgroup for the container 667 668 Builds Docker images from a Dockerfile and a "context". A build's context is 669 the files located in the specified `PATH` or `URL`. The build process can 670 refer to any of the files in the context. For example, your build can use 671 an [*ADD*](/reference/builder/#add) instruction to reference a file in the 672 context. 673 674 The `URL` parameter can specify the location of a Git repository; 675 the repository acts as the build context. The system recursively clones the repository 676 and its submodules using a `git clone --depth 1 --recursive` command. 677 This command runs in a temporary directory on your local host. 678 After the command succeeds, the directory is sent to the Docker daemon as the context. 679 Local clones give you the ability to access private repositories using 680 local user credentials, VPN's, and so forth. 681 682 Git URLs accept context configuration in their fragment section, separated by a colon `:`. 683 The first part represents the reference that Git will check out, this can be either 684 a branch, a tag, or a commit SHA. The second part represents a subdirectory 685 inside the repository that will be used as a build context. 686 687 For example, run this command to use a directory called `docker` in the branch `container`: 688 689 $ docker build https://github.com/docker/rootfs.git#container:docker 690 691 The following table represents all the valid suffixes with their build contexts: 692 693 Build Syntax Suffix | Commit Used | Build Context Used 694 --------------------|-------------|------------------- 695 `myrepo.git` | `refs/heads/master` | `/` 696 `myrepo.git#mytag` | `refs/tags/mytag` | `/` 697 `myrepo.git#mybranch` | `refs/heads/mybranch` | `/` 698 `myrepo.git#abcdef` | `sha1 = abcdef` | `/` 699 `myrepo.git#:myfolder` | `refs/heads/master` | `/myfolder` 700 `myrepo.git#master:myfolder` | `refs/heads/master` | `/myfolder` 701 `myrepo.git#mytag:myfolder` | `refs/tags/mytag` | `/myfolder` 702 `myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder` 703 `myrepo.git#abcdef:myfolder` | `sha1 = abcdef` | `/myfolder` 704 705 Instead of specifying a context, you can pass a single Dockerfile in the 706 `URL` or pipe the file in via `STDIN`. To pipe a Dockerfile from `STDIN`: 707 708 docker build - < Dockerfile 709 710 If you use STDIN or specify a `URL`, the system places the contents into a 711 file called `Dockerfile`, and any `-f`, `--file` option is ignored. In this 712 scenario, there is no context. 713 714 By default the `docker build` command will look for a `Dockerfile` at the 715 root of the build context. The `-f`, `--file`, option lets you specify 716 the path to an alternative file to use instead. This is useful 717 in cases where the same set of files are used for multiple builds. The path 718 must be to a file within the build context. If a relative path is specified 719 then it must to be relative to the current directory. 720 721 In most cases, it's best to put each Dockerfile in an empty directory. Then, add 722 to that directory only the files needed for building the Dockerfile. To increase 723 the build's performance, you can exclude files and directories by adding a 724 `.dockerignore` file to that directory as well. For information on creating one, 725 see the [.dockerignore file](../../reference/builder/#dockerignore-file). 726 727 If the Docker client loses connection to the daemon, the build is canceled. 728 This happens if you interrupt the Docker client with `ctrl-c` or if the Docker 729 client is killed for any reason. 730 731 > **Note:** Currently only the "run" phase of the build can be canceled until 732 > pull cancelation is implemented). 733 734 ### Return code 735 736 On a successful build, a return code of success `0` will be returned. 737 When the build fails, a non-zero failure code will be returned. 738 739 There should be informational output of the reason for failure output 740 to `STDERR`: 741 742 ``` 743 $ docker build -t fail . 744 Sending build context to Docker daemon 2.048 kB 745 Sending build context to Docker daemon 746 Step 0 : FROM busybox 747 ---> 4986bf8c1536 748 Step 1 : RUN exit 13 749 ---> Running in e26670ec7a0a 750 INFO[0000] The command [/bin/sh -c exit 13] returned a non-zero code: 13 751 $ echo $? 752 1 753 ``` 754 See also: 755 756 [*Dockerfile Reference*](/reference/builder). 757 758 ### Examples 759 760 $ docker build . 761 Uploading context 10240 bytes 762 Step 1 : FROM busybox 763 Pulling repository busybox 764 ---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/ 765 Step 2 : RUN ls -lh / 766 ---> Running in 9c9e81692ae9 767 total 24 768 drwxr-xr-x 2 root root 4.0K Mar 12 2013 bin 769 drwxr-xr-x 5 root root 4.0K Oct 19 00:19 dev 770 drwxr-xr-x 2 root root 4.0K Oct 19 00:19 etc 771 drwxr-xr-x 2 root root 4.0K Nov 15 23:34 lib 772 lrwxrwxrwx 1 root root 3 Mar 12 2013 lib64 -> lib 773 dr-xr-xr-x 116 root root 0 Nov 15 23:34 proc 774 lrwxrwxrwx 1 root root 3 Mar 12 2013 sbin -> bin 775 dr-xr-xr-x 13 root root 0 Nov 15 23:34 sys 776 drwxr-xr-x 2 root root 4.0K Mar 12 2013 tmp 777 drwxr-xr-x 2 root root 4.0K Nov 15 23:34 usr 778 ---> b35f4035db3f 779 Step 3 : CMD echo Hello world 780 ---> Running in 02071fceb21b 781 ---> f52f38b7823e 782 Successfully built f52f38b7823e 783 Removing intermediate container 9c9e81692ae9 784 Removing intermediate container 02071fceb21b 785 786 This example specifies that the `PATH` is 787 `.`, and so all the files in the local directory get 788 `tar`d and sent to the Docker daemon. The `PATH` 789 specifies where to find the files for the "context" of the build on the 790 Docker daemon. Remember that the daemon could be running on a remote 791 machine and that no parsing of the Dockerfile 792 happens at the client side (where you're running 793 `docker build`). That means that *all* the files at 794 `PATH` get sent, not just the ones listed to 795 [*ADD*](/reference/builder/#add) in the Dockerfile. 796 797 The transfer of context from the local machine to the Docker daemon is 798 what the `docker` client means when you see the 799 "Sending build context" message. 800 801 If you wish to keep the intermediate containers after the build is 802 complete, you must use `--rm=false`. This does not 803 affect the build cache. 804 805 $ docker build . 806 Uploading context 18.829 MB 807 Uploading context 808 Step 0 : FROM busybox 809 ---> 769b9341d937 810 Step 1 : CMD echo Hello world 811 ---> Using cache 812 ---> 99cc1ad10469 813 Successfully built 99cc1ad10469 814 $ echo ".git" > .dockerignore 815 $ docker build . 816 Uploading context 6.76 MB 817 Uploading context 818 Step 0 : FROM busybox 819 ---> 769b9341d937 820 Step 1 : CMD echo Hello world 821 ---> Using cache 822 ---> 99cc1ad10469 823 Successfully built 99cc1ad10469 824 825 This example shows the use of the `.dockerignore` file to exclude the `.git` 826 directory from the context. Its effect can be seen in the changed size of the 827 uploaded context. The builder reference contains detailed information on 828 [creating a .dockerignore file](../../builder/#dockerignore-file) 829 830 $ docker build -t vieux/apache:2.0 . 831 832 This will build like the previous example, but it will then tag the 833 resulting image. The repository name will be `vieux/apache` 834 and the tag will be `2.0` 835 836 $ docker build - < Dockerfile 837 838 This will read a Dockerfile from `STDIN` without context. Due to the 839 lack of a context, no contents of any local directory will be sent to 840 the Docker daemon. Since there is no context, a Dockerfile `ADD` only 841 works if it refers to a remote URL. 842 843 $ docker build - < context.tar.gz 844 845 This will build an image for a compressed context read from `STDIN`. 846 Supported formats are: bzip2, gzip and xz. 847 848 $ docker build github.com/creack/docker-firefox 849 850 This will clone the GitHub repository and use the cloned repository as 851 context. The Dockerfile at the root of the 852 repository is used as Dockerfile. Note that you 853 can specify an arbitrary Git repository by using the `git://` or `git@` 854 schema. 855 856 $ docker build -f Dockerfile.debug . 857 858 This will use a file called `Dockerfile.debug` for the build 859 instructions instead of `Dockerfile`. 860 861 $ docker build -f dockerfiles/Dockerfile.debug -t myapp_debug . 862 $ docker build -f dockerfiles/Dockerfile.prod -t myapp_prod . 863 864 The above commands will build the current build context (as specified by 865 the `.`) twice, once using a debug version of a `Dockerfile` and once using 866 a production version. 867 868 $ cd /home/me/myapp/some/dir/really/deep 869 $ docker build -f /home/me/myapp/dockerfiles/debug /home/me/myapp 870 $ docker build -f ../../../../dockerfiles/debug /home/me/myapp 871 872 These two `docker build` commands do the exact same thing. They both 873 use the contents of the `debug` file instead of looking for a `Dockerfile` 874 and will use `/home/me/myapp` as the root of the build context. Note that 875 `debug` is in the directory structure of the build context, regardless of how 876 you refer to it on the command line. 877 878 > **Note:** `docker build` will return a `no such file or directory` error 879 > if the file or directory does not exist in the uploaded context. This may 880 > happen if there is no context, or if you specify a file that is elsewhere 881 > on the Host system. The context is limited to the current directory (and its 882 > children) for security reasons, and to ensure repeatable builds on remote 883 > Docker hosts. This is also the reason why `ADD ../file` will not work. 884 885 When `docker build` is run with the `--cgroup-parent` option the containers used 886 in the build will be run with the [corresponding `docker run` 887 flag](/reference/run/#specifying-custom-cgroups). 888 889 890 ## commit 891 892 Usage: docker commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]] 893 894 Create a new image from a container's changes 895 896 -a, --author="" Author (e.g., "John Hannibal Smith <hannibal@a-team.com>") 897 -c, --change=[] Apply specified Dockerfile instructions while committing the image 898 -m, --message="" Commit message 899 -p, --pause=true Pause container during commit 900 901 It can be useful to commit a container's file changes or settings into a 902 new image. This allows you debug a container by running an interactive 903 shell, or to export a working dataset to another server. Generally, it 904 is better to use Dockerfiles to manage your images in a documented and 905 maintainable way. 906 907 By default, the container being committed and its processes will be paused 908 while the image is committed. This reduces the likelihood of 909 encountering data corruption during the process of creating the commit. 910 If this behavior is undesired, set the 'p' option to false. 911 912 The `--change` option will apply `Dockerfile` instructions to the image 913 that is created. 914 Supported `Dockerfile` instructions: 915 `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` 916 917 #### Commit a container 918 919 $ docker ps 920 ID IMAGE COMMAND CREATED STATUS PORTS 921 c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours 922 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours 923 $ docker commit c3f279d17e0a SvenDowideit/testimage:version3 924 f5283438590d 925 $ docker images 926 REPOSITORY TAG ID CREATED VIRTUAL SIZE 927 SvenDowideit/testimage version3 f5283438590d 16 seconds ago 335.7 MB 928 929 #### Commit a container with new configurations 930 931 $ docker ps 932 ID IMAGE COMMAND CREATED STATUS PORTS 933 c3f279d17e0a ubuntu:12.04 /bin/bash 7 days ago Up 25 hours 934 197387f1b436 ubuntu:12.04 /bin/bash 7 days ago Up 25 hours 935 $ docker inspect -f "{{ .Config.Env }}" c3f279d17e0a 936 [HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin] 937 $ docker commit --change "ENV DEBUG true" c3f279d17e0a SvenDowideit/testimage:version3 938 f5283438590d 939 $ docker inspect -f "{{ .Config.Env }}" f5283438590d 940 [HOME=/ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin DEBUG=true] 941 942 ## cp 943 944 Copy files or folders from a container's filesystem to the directory on the 945 host. Use '-' to write the data as a tar file to `STDOUT`. `CONTAINER:PATH` is 946 relative to the root of the container's filesystem. 947 948 Usage: docker cp CONTAINER:PATH HOSTDIR|- 949 950 Copy files/folders from the PATH to the HOSTDIR. 951 952 953 ## create 954 955 Creates a new container. 956 957 Usage: docker create [OPTIONS] IMAGE [COMMAND] [ARG...] 958 959 Create a new container 960 961 -a, --attach=[] Attach to STDIN, STDOUT or STDERR 962 --add-host=[] Add a custom host-to-IP mapping (host:ip) 963 --blkio-weight=0 Block IO weight (relative weight) 964 -c, --cpu-shares=0 CPU shares (relative weight) 965 --cap-add=[] Add Linux capabilities 966 --cap-drop=[] Drop Linux capabilities 967 --cgroup-parent="" Optional parent cgroup for the container 968 --cidfile="" Write the container ID to the file 969 --cpuset-cpus="" CPUs in which to allow execution (0-3, 0,1) 970 --cpuset-mems="" Memory nodes (MEMs) in which to allow execution (0-3, 0,1) 971 --cpu-period=0 Limit the CPU CFS (Completely Fair Scheduler) period 972 --cpu-quota=0 Limit the CPU CFS (Completely Fair Scheduler) quota 973 --device=[] Add a host device to the container 974 --dns=[] Set custom DNS servers 975 --dns-search=[] Set custom DNS search domains 976 -e, --env=[] Set environment variables 977 --entrypoint="" Overwrite the default ENTRYPOINT of the image 978 --env-file=[] Read in a file of environment variables 979 --expose=[] Expose a port or a range of ports 980 -h, --hostname="" Container host name 981 -i, --interactive=false Keep STDIN open even if not attached 982 --ipc="" IPC namespace to use 983 -l, --label=[] Set metadata on the container (e.g., --label=com.example.key=value) 984 --label-file=[] Read in a line delimited file of labels 985 --link=[] Add link to another container 986 --log-driver="" Logging driver for container 987 --lxc-conf=[] Add custom lxc options 988 -m, --memory="" Memory limit 989 --mac-address="" Container MAC address (e.g. 92:d0:c6:0a:29:33) 990 --name="" Assign a name to the container 991 --net="bridge" Set the Network mode for the container 992 --oom-kill-disable=false Whether to disable OOM Killer for the container or not 993 -P, --publish-all=false Publish all exposed ports to random ports 994 -p, --publish=[] Publish a container's port(s) to the host 995 --pid="" PID namespace to use 996 --uts="" UTS namespace to use 997 --privileged=false Give extended privileges to this container 998 --read-only=false Mount the container's root filesystem as read only 999 --restart="no" Restart policy (no, on-failure[:max-retry], always) 1000 --security-opt=[] Security options 1001 -t, --tty=false Allocate a pseudo-TTY 1002 -u, --user="" Username or UID 1003 -v, --volume=[] Bind mount a volume 1004 --volumes-from=[] Mount volumes from the specified container(s) 1005 -w, --workdir="" Working directory inside the container 1006 1007 The `docker create` command creates a writeable container layer over 1008 the specified image and prepares it for running the specified command. 1009 The container ID is then printed to `STDOUT`. 1010 This is similar to `docker run -d` except the container is never started. 1011 You can then use the `docker start <container_id>` command to start the 1012 container at any point. 1013 1014 This is useful when you want to set up a container configuration ahead 1015 of time so that it is ready to start when you need it. 1016 1017 Please see the [run command](#run) section and the [Docker run reference]( 1018 /reference/run/) for more details. 1019 1020 #### Examples 1021 1022 $ docker create -t -i fedora bash 1023 6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752 1024 $ docker start -a -i 6d8af538ec5 1025 bash-4.2# 1026 1027 As of v1.4.0 container volumes are initialized during the `docker create` 1028 phase (i.e., `docker run` too). For example, this allows you to `create` the 1029 `data` volume container, and then use it from another container: 1030 1031 $ docker create -v /data --name data ubuntu 1032 240633dfbb98128fa77473d3d9018f6123b99c454b3251427ae190a7d951ad57 1033 $ docker run --rm --volumes-from data ubuntu ls -la /data 1034 total 8 1035 drwxr-xr-x 2 root root 4096 Dec 5 04:10 . 1036 drwxr-xr-x 48 root root 4096 Dec 5 04:11 .. 1037 1038 Similarly, `create` a host directory bind mounted volume container, which 1039 can then be used from the subsequent container: 1040 1041 $ docker create -v /home/docker:/docker --name docker ubuntu 1042 9aa88c08f319cd1e4515c3c46b0de7cc9aa75e878357b1e96f91e2c773029f03 1043 $ docker run --rm --volumes-from docker ubuntu ls -la /docker 1044 total 20 1045 drwxr-sr-x 5 1000 staff 180 Dec 5 04:00 . 1046 drwxr-xr-x 48 root root 4096 Dec 5 04:13 .. 1047 -rw-rw-r-- 1 1000 staff 3833 Dec 5 04:01 .ash_history 1048 -rw-r--r-- 1 1000 staff 446 Nov 28 11:51 .ashrc 1049 -rw-r--r-- 1 1000 staff 25 Dec 5 04:00 .gitconfig 1050 drwxr-sr-x 3 1000 staff 60 Dec 1 03:28 .local 1051 -rw-r--r-- 1 1000 staff 920 Nov 28 11:51 .profile 1052 drwx--S--- 2 1000 staff 460 Dec 5 00:51 .ssh 1053 drwxr-xr-x 32 1000 staff 1140 Dec 5 04:01 docker 1054 1055 1056 ## diff 1057 1058 List the changed files and directories in a container᾿s filesystem 1059 1060 Usage: docker diff CONTAINER 1061 1062 Inspect changes on a container's filesystem 1063 1064 There are 3 events that are listed in the `diff`: 1065 1066 1. `A` - Add 1067 2. `D` - Delete 1068 3. `C` - Change 1069 1070 For example: 1071 1072 $ docker diff 7bb0e258aefe 1073 1074 C /dev 1075 A /dev/kmsg 1076 C /etc 1077 A /etc/mtab 1078 A /go 1079 A /go/src 1080 A /go/src/github.com 1081 A /go/src/github.com/docker 1082 A /go/src/github.com/docker/docker 1083 A /go/src/github.com/docker/docker/.git 1084 .... 1085 1086 ## events 1087 1088 Usage: docker events [OPTIONS] 1089 1090 Get real time events from the server 1091 1092 -f, --filter=[] Filter output based on conditions provided 1093 --since="" Show all events created since timestamp 1094 --until="" Stream events until this timestamp 1095 1096 Docker containers will report the following events: 1097 1098 create, destroy, die, export, kill, oom, pause, restart, start, stop, unpause 1099 1100 and Docker images will report: 1101 1102 untag, delete 1103 1104 #### Filtering 1105 1106 The filtering flag (`-f` or `--filter`) format is of "key=value". If you would like to use 1107 multiple filters, pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) 1108 1109 Using the same filter multiple times will be handled as a *OR*; for example 1110 `--filter container=588a23dac085 --filter container=a8f7720b8c22` will display events for 1111 container 588a23dac085 *OR* container a8f7720b8c22 1112 1113 Using multiple filters will be handled as a *AND*; for example 1114 `--filter container=588a23dac085 --filter event=start` will display events for container 1115 container 588a23dac085 *AND* the event type is *start* 1116 1117 The currently supported filters are: 1118 1119 * container 1120 * event 1121 * image 1122 1123 #### Examples 1124 1125 You'll need two shells for this example. 1126 1127 **Shell 1: Listening for events:** 1128 1129 $ docker events 1130 1131 **Shell 2: Start and Stop containers:** 1132 1133 $ docker start 4386fb97867d 1134 $ docker stop 4386fb97867d 1135 $ docker stop 7805c1d35632 1136 1137 **Shell 1: (Again .. now showing events):** 1138 1139 2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) start 1140 2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) die 1141 2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) stop 1142 2014-05-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) die 1143 2014-05-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) stop 1144 1145 **Show events in the past from a specified time:** 1146 1147 $ docker events --since 1378216169 1148 2014-03-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) die 1149 2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) stop 1150 2014-05-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) die 1151 2014-03-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) stop 1152 1153 $ docker events --since '2013-09-03' 1154 2014-09-03T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) start 1155 2014-09-03T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) die 1156 2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) stop 1157 2014-05-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) die 1158 2014-09-03T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) stop 1159 1160 $ docker events --since '2013-09-03T15:49:29' 1161 2014-09-03T15:49:29.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) die 1162 2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) stop 1163 2014-05-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) die 1164 2014-09-03T15:49:29.999999999Z07:00 7805c1d35632: (from redis:2.8) stop 1165 1166 **Filter events:** 1167 1168 $ docker events --filter 'event=stop' 1169 2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) stop 1170 2014-09-03T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) stop 1171 1172 $ docker events --filter 'image=ubuntu-1:14.04' 1173 2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) start 1174 2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) die 1175 2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) stop 1176 1177 $ docker events --filter 'container=7805c1d35632' 1178 2014-05-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) die 1179 2014-09-03T15:49:29.999999999Z07:00 7805c1d35632: (from redis:2.8) stop 1180 1181 $ docker events --filter 'container=7805c1d35632' --filter 'container=4386fb97867d' 1182 2014-09-03T15:49:29.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) die 1183 2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) stop 1184 2014-05-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) die 1185 2014-09-03T15:49:29.999999999Z07:00 7805c1d35632: (from redis:2.8) stop 1186 1187 $ docker events --filter 'container=7805c1d35632' --filter 'event=stop' 1188 2014-09-03T15:49:29.999999999Z07:00 7805c1d35632: (from redis:2.8) stop 1189 1190 $ docker events --filter 'container=container_1' --filter 'container=container_2' 1191 2014-09-03T15:49:29.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) die 1192 2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) stop 1193 2014-05-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) die 1194 2014-09-03T15:49:29.999999999Z07:00 7805c1d35632: (from redis:2.8) stop 1195 1196 ## exec 1197 1198 Usage: docker exec [OPTIONS] CONTAINER COMMAND [ARG...] 1199 1200 Run a command in a running container 1201 1202 -d, --detach=false Detached mode: run command in the background 1203 -i, --interactive=false Keep STDIN open even if not attached 1204 -t, --tty=false Allocate a pseudo-TTY 1205 -u, --user= Username or UID (format: <name|uid>[:<group|gid>]) 1206 1207 The `docker exec` command runs a new command in a running container. 1208 1209 The command started using `docker exec` only runs while the container's primary 1210 process (`PID 1`) is running, and it is not restarted if the container is restarted. 1211 1212 If the container is paused, then the `docker exec` command will fail with an error: 1213 1214 $ docker pause test 1215 test 1216 $ docker ps 1217 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 1218 1ae3b36715d2 ubuntu:latest "bash" 17 seconds ago Up 16 seconds (Paused) test 1219 $ docker exec test ls 1220 FATA[0000] Error response from daemon: Container test is paused, unpause the container before exec 1221 $ echo $? 1222 1 1223 1224 #### Examples 1225 1226 $ docker run --name ubuntu_bash --rm -i -t ubuntu bash 1227 1228 This will create a container named `ubuntu_bash` and start a Bash session. 1229 1230 $ docker exec -d ubuntu_bash touch /tmp/execWorks 1231 1232 This will create a new file `/tmp/execWorks` inside the running container 1233 `ubuntu_bash`, in the background. 1234 1235 $ docker exec -it ubuntu_bash bash 1236 1237 This will create a new Bash session in the container `ubuntu_bash`. 1238 1239 ## export 1240 1241 Usage: docker export [OPTIONS] CONTAINER 1242 1243 Export the contents of a filesystem to a tar archive (streamed to STDOUT by default) 1244 1245 -o, --output="" Write to a file, instead of STDOUT 1246 1247 Produces a tarred repository to the standard output stream. 1248 1249 For example: 1250 1251 $ docker export red_panda > latest.tar 1252 1253 Or 1254 1255 $ docker export --output="latest.tar" red_panda 1256 1257 > **Note:** 1258 > `docker export` does not export the contents of volumes associated with the 1259 > container. If a volume is mounted on top of an existing directory in the 1260 > container, `docker export` will export the contents of the *underlying* 1261 > directory, not the contents of the volume. 1262 > 1263 > Refer to [Backup, restore, or migrate data volumes](/userguide/dockervolumes/#backup-restore-or-migrate-data-volumes) 1264 > in the user guide for examples on exporting data in a volume. 1265 1266 ## history 1267 1268 Usage: docker history [OPTIONS] IMAGE 1269 1270 Show the history of an image 1271 1272 -H, --human=true Print sizes and dates in human readable format 1273 --no-trunc=false Don't truncate output 1274 -q, --quiet=false Only show numeric IDs 1275 1276 To see how the `docker:latest` image was built: 1277 1278 $ docker history docker 1279 IMAGE CREATED CREATED BY SIZE COMMENT 1280 3e23a5875458 8 days ago /bin/sh -c #(nop) ENV LC_ALL=C.UTF-8 0 B 1281 8578938dd170 8 days ago /bin/sh -c dpkg-reconfigure locales && loc 1.245 MB 1282 be51b77efb42 8 days ago /bin/sh -c apt-get update && apt-get install 338.3 MB 1283 4b137612be55 6 weeks ago /bin/sh -c #(nop) ADD jessie.tar.xz in / 121 MB 1284 750d58736b4b 6 weeks ago /bin/sh -c #(nop) MAINTAINER Tianon Gravi <ad 0 B 1285 511136ea3c5a 9 months ago 0 B Imported from - 1286 1287 To see how the `docker:apache` image was added to a container's base image: 1288 1289 $ docker history docker:scm 1290 IMAGE CREATED CREATED BY SIZE COMMENT 1291 2ac9d1098bf1 3 months ago /bin/bash 241.4 MB Added Apache to Fedora base image 1292 88b42ffd1f7c 5 months ago /bin/sh -c #(nop) ADD file:1fd8d7f9f6557cafc7 373.7 MB 1293 c69cab00d6ef 5 months ago /bin/sh -c #(nop) MAINTAINER Lokesh Mandvekar 0 B 1294 511136ea3c5a 19 months ago 0 B Imported from - 1295 1296 1297 ## images 1298 1299 Usage: docker images [OPTIONS] [REPOSITORY] 1300 1301 List images 1302 1303 -a, --all=false Show all images (default hides intermediate images) 1304 --digests=false Show digests 1305 -f, --filter=[] Filter output based on conditions provided 1306 --help=false Print usage 1307 --no-trunc=false Don't truncate output 1308 -q, --quiet=false Only show numeric IDs 1309 1310 The default `docker images` will show all top level 1311 images, their repository and tags, and their virtual size. 1312 1313 Docker images have intermediate layers that increase reusability, 1314 decrease disk usage, and speed up `docker build` by 1315 allowing each step to be cached. These intermediate layers are not shown 1316 by default. 1317 1318 The `VIRTUAL SIZE` is the cumulative space taken up by the image and all 1319 its parent images. This is also the disk space used by the contents of the 1320 Tar file created when you `docker save` an image. 1321 1322 An image will be listed more than once if it has multiple repository names 1323 or tags. This single image (identifiable by its matching `IMAGE ID`) 1324 uses up the `VIRTUAL SIZE` listed only once. 1325 1326 #### Listing the most recently created images 1327 1328 $ docker images 1329 REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE 1330 <none> <none> 77af4d6b9913 19 hours ago 1.089 GB 1331 committ latest b6fa739cedf5 19 hours ago 1.089 GB 1332 <none> <none> 78a85c484f71 19 hours ago 1.089 GB 1333 docker latest 30557a29d5ab 20 hours ago 1.089 GB 1334 <none> <none> 5ed6274db6ce 24 hours ago 1.089 GB 1335 postgres 9 746b819f315e 4 days ago 213.4 MB 1336 postgres 9.3 746b819f315e 4 days ago 213.4 MB 1337 postgres 9.3.5 746b819f315e 4 days ago 213.4 MB 1338 postgres latest 746b819f315e 4 days ago 213.4 MB 1339 1340 1341 #### Listing the full length image IDs 1342 1343 $ docker images --no-trunc 1344 REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE 1345 <none> <none> 77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182 19 hours ago 1.089 GB 1346 committest latest b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f 19 hours ago 1.089 GB 1347 <none> <none> 78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921 19 hours ago 1.089 GB 1348 docker latest 30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4 20 hours ago 1.089 GB 1349 <none> <none> 0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5 20 hours ago 1.089 GB 1350 <none> <none> 18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b 22 hours ago 1.082 GB 1351 <none> <none> f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a 23 hours ago 1.089 GB 1352 tryout latest 2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074 23 hours ago 131.5 MB 1353 <none> <none> 5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df 24 hours ago 1.089 GB 1354 1355 #### Listing image digests 1356 1357 Images that use the v2 or later format have a content-addressable identifier 1358 called a `digest`. As long as the input used to generate the image is 1359 unchanged, the digest value is predictable. To list image digest values, use 1360 the `--digests` flag: 1361 1362 $ docker images --digests 1363 REPOSITORY TAG DIGEST IMAGE ID CREATED VIRTUAL SIZE 1364 localhost:5000/test/busybox <none> sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB 1365 1366 When pushing or pulling to a 2.0 registry, the `push` or `pull` command 1367 output includes the image digest. You can `pull` using a digest value. You can 1368 also reference by digest in `create`, `run`, and `rmi` commands, as well as the 1369 `FROM` image reference in a Dockerfile. 1370 1371 #### Filtering 1372 1373 The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more 1374 than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`) 1375 1376 The currently supported filters are: 1377 1378 * dangling (boolean - true or false) 1379 * label (`label=<key>` or `label=<key>=<value>`) 1380 1381 ##### Untagged images 1382 1383 $ docker images --filter "dangling=true" 1384 1385 REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE 1386 <none> <none> 8abc22fbb042 4 weeks ago 0 B 1387 <none> <none> 48e5f45168b9 4 weeks ago 2.489 MB 1388 <none> <none> bf747efa0e2f 4 weeks ago 0 B 1389 <none> <none> 980fe10e5736 12 weeks ago 101.4 MB 1390 <none> <none> dea752e4e117 12 weeks ago 101.4 MB 1391 <none> <none> 511136ea3c5a 8 months ago 0 B 1392 1393 This will display untagged images, that are the leaves of the images tree (not 1394 intermediary layers). These images occur when a new build of an image takes the 1395 `repo:tag` away from the image ID, leaving it untagged. A warning will be issued 1396 if trying to remove an image when a container is presently using it. 1397 By having this flag it allows for batch cleanup. 1398 1399 Ready for use by `docker rmi ...`, like: 1400 1401 $ docker rmi $(docker images -f "dangling=true" -q) 1402 1403 8abc22fbb042 1404 48e5f45168b9 1405 bf747efa0e2f 1406 980fe10e5736 1407 dea752e4e117 1408 511136ea3c5a 1409 1410 NOTE: Docker will warn you if any containers exist that are using these untagged images. 1411 1412 ## import 1413 1414 Usage: docker import URL|- [REPOSITORY[:TAG]] 1415 1416 Create an empty filesystem image and import the contents of the 1417 tarball (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz) into it, then 1418 optionally tag it. 1419 1420 -c, --change=[] Apply specified Dockerfile instructions while importing the image 1421 1422 URLs must start with `http` and point to a single file archive (.tar, 1423 .tar.gz, .tgz, .bzip, .tar.xz, or .txz) containing a root filesystem. If 1424 you would like to import from a local directory or archive, you can use 1425 the `-` parameter to take the data from `STDIN`. 1426 1427 The `--change` option will apply `Dockerfile` instructions to the image 1428 that is created. 1429 Supported `Dockerfile` instructions: 1430 `CMD`|`ENTRYPOINT`|`ENV`|`EXPOSE`|`ONBUILD`|`USER`|`VOLUME`|`WORKDIR` 1431 1432 #### Examples 1433 1434 **Import from a remote location:** 1435 1436 This will create a new untagged image. 1437 1438 $ docker import http://example.com/exampleimage.tgz 1439 1440 **Import from a local file:** 1441 1442 Import to docker via pipe and `STDIN`. 1443 1444 $ cat exampleimage.tgz | docker import - exampleimagelocal:new 1445 1446 **Import from a local directory:** 1447 1448 $ sudo tar -c . | docker import - exampleimagedir 1449 1450 **Import from a local directory with new configurations:** 1451 1452 $ sudo tar -c . | docker import --change "ENV DEBUG true" - exampleimagedir 1453 1454 Note the `sudo` in this example – you must preserve 1455 the ownership of the files (especially root ownership) during the 1456 archiving with tar. If you are not root (or the sudo command) when you 1457 tar, then the ownerships might not get preserved. 1458 1459 ## info 1460 1461 1462 Usage: docker info 1463 1464 Display system-wide information 1465 1466 For example: 1467 1468 $ docker -D info 1469 Containers: 14 1470 Images: 52 1471 Storage Driver: aufs 1472 Root Dir: /var/lib/docker/aufs 1473 Backing Filesystem: extfs 1474 Dirs: 545 1475 Execution Driver: native-0.2 1476 Logging Driver: json-file 1477 Kernel Version: 3.13.0-24-generic 1478 Operating System: Ubuntu 14.04 LTS 1479 CPUs: 1 1480 Name: prod-server-42 1481 ID: 7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS 1482 Total Memory: 2 GiB 1483 Debug mode (server): false 1484 Debug mode (client): true 1485 File Descriptors: 10 1486 Goroutines: 9 1487 System Time: Tue Mar 10 18:38:57 UTC 2015 1488 EventsListeners: 0 1489 Init Path: /usr/bin/docker 1490 Docker Root Dir: /var/lib/docker 1491 Http Proxy: http://test:test@localhost:8080 1492 Https Proxy: https://test:test@localhost:8080 1493 No Proxy: 9.81.1.160 1494 Username: svendowideit 1495 Registry: [https://index.docker.io/v1/] 1496 Labels: 1497 storage=ssd 1498 1499 The global `-D` option tells all `docker` commands to output debug information. 1500 1501 When sending issue reports, please use `docker version` and `docker -D info` to 1502 ensure we know how your setup is configured. 1503 1504 ## inspect 1505 1506 Usage: docker inspect [OPTIONS] CONTAINER|IMAGE [CONTAINER|IMAGE...] 1507 1508 Return low-level information on a container or image 1509 1510 -f, --format="" Format the output using the given go template 1511 1512 By default, this will render all results in a JSON array. If a format is 1513 specified, the given template will be executed for each result. 1514 1515 Go's [text/template](http://golang.org/pkg/text/template/) package 1516 describes all the details of the format. 1517 1518 #### Examples 1519 1520 **Get an instance's IP address:** 1521 1522 For the most part, you can pick out any field from the JSON in a fairly 1523 straightforward manner. 1524 1525 $ docker inspect --format='{{.NetworkSettings.IPAddress}}' $INSTANCE_ID 1526 1527 **Get an instance's MAC Address:** 1528 1529 For the most part, you can pick out any field from the JSON in a fairly 1530 straightforward manner. 1531 1532 $ docker inspect --format='{{.NetworkSettings.MacAddress}}' $INSTANCE_ID 1533 1534 **Get an instance's log path:** 1535 1536 $ docker inspect --format='{{.LogPath}}' $INSTANCE_ID 1537 1538 **List All Port Bindings:** 1539 1540 One can loop over arrays and maps in the results to produce simple text 1541 output: 1542 1543 $ docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}} {{$p}} -> {{(index $conf 0).HostPort}} {{end}}' $INSTANCE_ID 1544 1545 **Find a Specific Port Mapping:** 1546 1547 The `.Field` syntax doesn't work when the field name begins with a 1548 number, but the template language's `index` function does. The 1549 `.NetworkSettings.Ports` section contains a map of the internal port 1550 mappings to a list of external address/port objects, so to grab just the 1551 numeric public port, you use `index` to find the specific port map, and 1552 then `index` 0 contains the first object inside of that. Then we ask for 1553 the `HostPort` field to get the public address. 1554 1555 $ docker inspect --format='{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}' $INSTANCE_ID 1556 1557 **Get config:** 1558 1559 The `.Field` syntax doesn't work when the field contains JSON data, but 1560 the template language's custom `json` function does. The `.config` 1561 section contains complex JSON object, so to grab it as JSON, you use 1562 `json` to convert the configuration object into JSON. 1563 1564 $ docker inspect --format='{{json .config}}' $INSTANCE_ID 1565 1566 ## kill 1567 1568 Usage: docker kill [OPTIONS] CONTAINER [CONTAINER...] 1569 1570 Kill a running container using SIGKILL or a specified signal 1571 1572 -s, --signal="KILL" Signal to send to the container 1573 1574 The main process inside the container will be sent `SIGKILL`, or any 1575 signal specified with option `--signal`. 1576 1577 ## load 1578 1579 Usage: docker load [OPTIONS] 1580 1581 Load an image from a tar archive on STDIN 1582 1583 -i, --input="" Read from a tar archive file, instead of STDIN 1584 1585 Loads a tarred repository from a file or the standard input stream. 1586 Restores both images and tags. 1587 1588 $ docker images 1589 REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE 1590 $ docker load < busybox.tar 1591 $ docker images 1592 REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE 1593 busybox latest 769b9341d937 7 weeks ago 2.489 MB 1594 $ docker load --input fedora.tar 1595 $ docker images 1596 REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE 1597 busybox latest 769b9341d937 7 weeks ago 2.489 MB 1598 fedora rawhide 0d20aec6529d 7 weeks ago 387 MB 1599 fedora 20 58394af37342 7 weeks ago 385.5 MB 1600 fedora heisenbug 58394af37342 7 weeks ago 385.5 MB 1601 fedora latest 58394af37342 7 weeks ago 385.5 MB 1602 1603 ## login 1604 1605 Usage: docker login [OPTIONS] [SERVER] 1606 1607 Register or log in to a Docker registry server, if no server is 1608 specified "https://index.docker.io/v1/" is the default. 1609 1610 -e, --email="" Email 1611 -p, --password="" Password 1612 -u, --username="" Username 1613 1614 If you want to login to a self-hosted registry you can specify this by 1615 adding the server name. 1616 1617 example: 1618 $ docker login localhost:8080 1619 1620 ## logout 1621 1622 Usage: docker logout [SERVER] 1623 1624 Log out from a Docker registry, if no server is 1625 specified "https://index.docker.io/v1/" is the default. 1626 1627 For example: 1628 1629 $ docker logout localhost:8080 1630 1631 ## logs 1632 1633 Usage: docker logs [OPTIONS] CONTAINER 1634 1635 Fetch the logs of a container 1636 1637 -f, --follow=false Follow log output 1638 --since="" Show logs since timestamp 1639 -t, --timestamps=false Show timestamps 1640 --tail="all" Number of lines to show from the end of the logs 1641 1642 NOTE: this command is available only for containers with `json-file` logging 1643 driver. 1644 1645 The `docker logs` command batch-retrieves logs present at the time of execution. 1646 1647 The `docker logs --follow` command will continue streaming the new output from 1648 the container's `STDOUT` and `STDERR`. 1649 1650 Passing a negative number or a non-integer to `--tail` is invalid and the 1651 value is set to `all` in that case. This behavior may change in the future. 1652 1653 The `docker logs --timestamp` commands will add an RFC3339Nano 1654 timestamp, for example `2014-09-16T06:17:46.000000000Z`, to each 1655 log entry. To ensure that the timestamps for are aligned the 1656 nano-second part of the timestamp will be padded with zero when necessary. 1657 1658 The `--since` option shows logs of a container generated only after 1659 the given date, specified as RFC 3339 or UNIX timestamp. The `--since` option 1660 can be combined with the `--follow` and `--tail` options. 1661 1662 ## pause 1663 1664 Usage: docker pause CONTAINER [CONTAINER...] 1665 1666 Pause all processes within a container 1667 1668 The `docker pause` command uses the cgroups freezer to suspend all processes in 1669 a container. Traditionally, when suspending a process the `SIGSTOP` signal is 1670 used, which is observable by the process being suspended. With the cgroups freezer 1671 the process is unaware, and unable to capture, that it is being suspended, 1672 and subsequently resumed. 1673 1674 See the 1675 [cgroups freezer documentation](https://www.kernel.org/doc/Documentation/cgroups/freezer-subsystem.txt) 1676 for further details. 1677 1678 ## port 1679 1680 Usage: docker port CONTAINER [PRIVATE_PORT[/PROTO]] 1681 1682 List port mappings for the CONTAINER, or lookup the public-facing port that is 1683 NAT-ed to the PRIVATE_PORT 1684 1685 You can find out all the ports mapped by not specifying a `PRIVATE_PORT`, or 1686 just a specific mapping: 1687 1688 $ docker ps test 1689 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 1690 b650456536c7 busybox:latest top 54 minutes ago Up 54 minutes 0.0.0.0:1234->9876/tcp, 0.0.0.0:4321->7890/tcp test 1691 $ docker port test 1692 7890/tcp -> 0.0.0.0:4321 1693 9876/tcp -> 0.0.0.0:1234 1694 $ docker port test 7890/tcp 1695 0.0.0.0:4321 1696 $ docker port test 7890/udp 1697 2014/06/24 11:53:36 Error: No public port '7890/udp' published for test 1698 $ docker port test 7890 1699 0.0.0.0:4321 1700 1701 ## ps 1702 1703 Usage: docker ps [OPTIONS] 1704 1705 List containers 1706 1707 -a, --all=false Show all containers (default shows just running) 1708 --before="" Show only container created before Id or Name 1709 -f, --filter=[] Filter output based on conditions provided 1710 -l, --latest=false Show the latest created container, include non-running 1711 -n=-1 Show n last created containers, include non-running 1712 --no-trunc=false Don't truncate output 1713 -q, --quiet=false Only display numeric IDs 1714 -s, --size=false Display total file sizes 1715 --since="" Show created since Id or Name, include non-running 1716 1717 Running `docker ps --no-trunc` showing 2 linked containers. 1718 1719 $ docker ps 1720 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 1721 4c01db0b339c ubuntu:12.04 bash 17 seconds ago Up 16 seconds 3300-3310/tcp webapp 1722 d7886598dbe2 crosbymichael/redis:latest /redis-server --dir 33 minutes ago Up 33 minutes 6379/tcp redis,webapp/db 1723 1724 `docker ps` will show only running containers by default. To see all containers: 1725 `docker ps -a` 1726 1727 `docker ps` will group exposed ports into a single range if possible. E.g., a container that exposes TCP ports `100, 101, 102` will display `100-102/tcp` in the `PORTS` column. 1728 1729 #### Filtering 1730 1731 The filtering flag (`-f` or `--filter)` format is a `key=value` pair. If there is more 1732 than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`) 1733 1734 The currently supported filters are: 1735 1736 * id (container's id) 1737 * label (`label=<key>` or `label=<key>=<value>`) 1738 * name (container's name) 1739 * exited (int - the code of exited containers. Only useful with `--all`) 1740 * status (restarting|running|paused|exited) 1741 1742 ##### Successfully exited containers 1743 1744 $ docker ps -a --filter 'exited=0' 1745 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 1746 ea09c3c82f6e registry:latest /srv/run.sh 2 weeks ago Exited (0) 2 weeks ago 127.0.0.1:5000->5000/tcp desperate_leakey 1747 106ea823fe4e fedora:latest /bin/sh -c 'bash -l' 2 weeks ago Exited (0) 2 weeks ago determined_albattani 1748 48ee228c9464 fedora:20 bash 2 weeks ago Exited (0) 2 weeks ago tender_torvalds 1749 1750 This shows all the containers that have exited with status of '0' 1751 1752 ## pull 1753 1754 Usage: docker pull [OPTIONS] NAME[:TAG] | [REGISTRY_HOST[:REGISTRY_PORT]/]NAME[:TAG] 1755 1756 Pull an image or a repository from the registry 1757 1758 -a, --all-tags=false Download all tagged images in the repository 1759 1760 Most of your images will be created on top of a base image from the 1761 [Docker Hub](https://hub.docker.com) registry. 1762 1763 [Docker Hub](https://hub.docker.com) contains many pre-built images that you 1764 can `pull` and try without needing to define and configure your own. 1765 1766 It is also possible to manually specify the path of a registry to pull from. 1767 For example, if you have set up a local registry, you can specify its path to 1768 pull from it. A repository path is similar to a URL, but does not contain 1769 a protocol specifier (`https://`, for example). 1770 1771 To download a particular image, or set of images (i.e., a repository), 1772 use `docker pull`: 1773 1774 $ docker pull debian 1775 # will pull the debian:latest image and its intermediate layers 1776 $ docker pull debian:testing 1777 # will pull the image named debian:testing and any intermediate 1778 # layers it is based on. 1779 $ docker pull debian@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 1780 # will pull the image from the debian repository with the digest 1781 # sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 1782 # and any intermediate layers it is based on. 1783 # (Typically the empty `scratch` image, a MAINTAINER layer, 1784 # and the un-tarred base). 1785 $ docker pull --all-tags centos 1786 # will pull all the images from the centos repository 1787 $ docker pull registry.hub.docker.com/debian 1788 # manually specifies the path to the default Docker registry. This could 1789 # be replaced with the path to a local registry to pull from another source. 1790 # sudo docker pull myhub.com:8080/test-image 1791 1792 ## push 1793 1794 Usage: docker push NAME[:TAG] 1795 1796 Push an image or a repository to the registry 1797 1798 Use `docker push` to share your images to the [Docker Hub](https://hub.docker.com) 1799 registry or to a self-hosted one. 1800 1801 ## rename 1802 1803 Usage: docker rename OLD_NAME NEW_NAME 1804 1805 rename a existing container to a NEW_NAME 1806 1807 The `docker rename` command allows the container to be renamed to a different name. 1808 1809 ## restart 1810 1811 Usage: docker restart [OPTIONS] CONTAINER [CONTAINER...] 1812 1813 Restart a running container 1814 1815 -t, --time=10 Seconds to wait for stop before killing the container 1816 1817 ## rm 1818 1819 Usage: docker rm [OPTIONS] CONTAINER [CONTAINER...] 1820 1821 Remove one or more containers 1822 1823 -f, --force=false Force the removal of a running container (uses SIGKILL) 1824 -l, --link=false Remove the specified link 1825 -v, --volumes=false Remove the volumes associated with the container 1826 1827 #### Examples 1828 1829 $ docker rm /redis 1830 /redis 1831 1832 This will remove the container referenced under the link 1833 `/redis`. 1834 1835 $ docker rm --link /webapp/redis 1836 /webapp/redis 1837 1838 This will remove the underlying link between `/webapp` and the `/redis` 1839 containers removing all network communication. 1840 1841 $ docker rm --force redis 1842 redis 1843 1844 The main process inside the container referenced under the link `/redis` will receive 1845 `SIGKILL`, then the container will be removed. 1846 1847 $ docker rm $(docker ps -a -q) 1848 1849 This command will delete all stopped containers. The command `docker ps 1850 -a -q` will return all existing container IDs and pass them to the `rm` 1851 command which will delete them. Any running containers will not be 1852 deleted. 1853 1854 ## rmi 1855 1856 Usage: docker rmi [OPTIONS] IMAGE [IMAGE...] 1857 1858 Remove one or more images 1859 1860 -f, --force=false Force removal of the image 1861 --no-prune=false Do not delete untagged parents 1862 1863 #### Removing tagged images 1864 1865 You can remove an image using its short or long ID, its tag, or its digest. If 1866 an image has one or more tag or digest reference, you must remove all of them 1867 before the image is removed. 1868 1869 $ docker images 1870 REPOSITORY TAG IMAGE ID CREATED SIZE 1871 test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) 1872 test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) 1873 test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) 1874 1875 $ docker rmi fd484f19954f 1876 Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories, use -f to force 1877 2013/12/11 05:47:16 Error: failed to remove one or more images 1878 1879 $ docker rmi test1 1880 Untagged: test1:latest 1881 $ docker rmi test2 1882 Untagged: test2:latest 1883 1884 $ docker images 1885 REPOSITORY TAG IMAGE ID CREATED SIZE 1886 test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) 1887 $ docker rmi test 1888 Untagged: test:latest 1889 Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 1890 1891 If you use the `-f` flag and specify the image's short or long ID, then this 1892 command untags and removes all images that match the specified ID. 1893 1894 $ docker images 1895 REPOSITORY TAG IMAGE ID CREATED SIZE 1896 test1 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) 1897 test latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) 1898 test2 latest fd484f19954f 23 seconds ago 7 B (virtual 4.964 MB) 1899 1900 $ docker rmi -f fd484f19954f 1901 Untagged: test1:latest 1902 Untagged: test:latest 1903 Untagged: test2:latest 1904 Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8 1905 1906 An image pulled by digest has no tag associated with it: 1907 1908 $ docker images --digests 1909 REPOSITORY TAG DIGEST IMAGE ID CREATED VIRTUAL SIZE 1910 localhost:5000/test/busybox <none> sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 4986bf8c1536 9 weeks ago 2.43 MB 1911 1912 To remove an image using its digest: 1913 1914 $ docker rmi localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 1915 Untagged: localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf 1916 Deleted: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125 1917 Deleted: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2 1918 Deleted: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b 1919 1920 ## run 1921 1922 Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...] 1923 1924 Run a command in a new container 1925 1926 -a, --attach=[] Attach to STDIN, STDOUT or STDERR 1927 --add-host=[] Add a custom host-to-IP mapping (host:ip) 1928 --blkio-weight=0 Block IO weight (relative weight) 1929 -c, --cpu-shares=0 CPU shares (relative weight) 1930 --cap-add=[] Add Linux capabilities 1931 --cap-drop=[] Drop Linux capabilities 1932 --cidfile="" Write the container ID to the file 1933 --cpuset-cpus="" CPUs in which to allow execution (0-3, 0,1) 1934 --cpuset-mems="" Memory nodes (MEMs) in which to allow execution (0-3, 0,1) 1935 --cpu-period=0 Limit the CPU CFS (Completely Fair Scheduler) period 1936 --cpu-quota=0 Limit the CPU CFS (Completely Fair Scheduler) quota 1937 -d, --detach=false Run container in background and print container ID 1938 --device=[] Add a host device to the container 1939 --dns=[] Set custom DNS servers 1940 --dns-search=[] Set custom DNS search domains 1941 -e, --env=[] Set environment variables 1942 --entrypoint="" Overwrite the default ENTRYPOINT of the image 1943 --env-file=[] Read in a file of environment variables 1944 --expose=[] Expose a port or a range of ports 1945 -h, --hostname="" Container host name 1946 --help=false Print usage 1947 -i, --interactive=false Keep STDIN open even if not attached 1948 --ipc="" IPC namespace to use 1949 --link=[] Add link to another container 1950 --log-driver="" Logging driver for container 1951 --lxc-conf=[] Add custom lxc options 1952 -m, --memory="" Memory limit 1953 -l, --label=[] Set metadata on the container (e.g., --label=com.example.key=value) 1954 --label-file=[] Read in a file of labels (EOL delimited) 1955 --mac-address="" Container MAC address (e.g. 92:d0:c6:0a:29:33) 1956 --memory-swap="" Total memory (memory + swap), '-1' to disable swap 1957 --name="" Assign a name to the container 1958 --net="bridge" Set the Network mode for the container 1959 --oom-kill-disable=false Whether to disable OOM Killer for the container or not 1960 -P, --publish-all=false Publish all exposed ports to random ports 1961 -p, --publish=[] Publish a container's port(s) to the host 1962 --pid="" PID namespace to use 1963 --uts="" UTS namespace to use 1964 --privileged=false Give extended privileges to this container 1965 --read-only=false Mount the container's root filesystem as read only 1966 --restart="no" Restart policy (no, on-failure[:max-retry], always) 1967 --rm=false Automatically remove the container when it exits 1968 --security-opt=[] Security Options 1969 --sig-proxy=true Proxy received signals to the process 1970 -t, --tty=false Allocate a pseudo-TTY 1971 -u, --user="" Username or UID (format: <name|uid>[:<group|gid>]) 1972 -v, --volume=[] Bind mount a volume 1973 --volumes-from=[] Mount volumes from the specified container(s) 1974 -w, --workdir="" Working directory inside the container 1975 1976 The `docker run` command first `creates` a writeable container layer over the 1977 specified image, and then `starts` it using the specified command. That is, 1978 `docker run` is equivalent to the API `/containers/create` then 1979 `/containers/(id)/start`. A stopped container can be restarted with all its 1980 previous changes intact using `docker start`. See `docker ps -a` to view a list 1981 of all containers. 1982 1983 There is detailed information about `docker run` in the [Docker run reference]( 1984 /reference/run/). 1985 1986 The `docker run` command can be used in combination with `docker commit` to 1987 [*change the command that a container runs*](#commit-an-existing-container). 1988 1989 See the [Docker User Guide](/userguide/dockerlinks/) for more detailed 1990 information about the `--expose`, `-p`, `-P` and `--link` parameters, 1991 and linking containers. 1992 1993 #### Examples 1994 1995 $ docker run --name test -it debian 1996 $$ exit 13 1997 exit 1998 $ echo $? 1999 13 2000 $ docker ps -a | grep test 2001 275c44472aeb debian:7 "/bin/bash" 26 seconds ago Exited (13) 17 seconds ago test 2002 2003 In this example, we are running `bash` interactively in the `debian:latest` image, and giving 2004 the container the name `test`. We then quit `bash` by running `exit 13`, which means `bash` 2005 will have an exit code of `13`. This is then passed on to the caller of `docker run`, and 2006 is recorded in the `test` container metadata. 2007 2008 $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test" 2009 2010 This will create a container and print `test` to the console. The `cidfile` 2011 flag makes Docker attempt to create a new file and write the container ID to it. 2012 If the file exists already, Docker will return an error. Docker will close this 2013 file when `docker run` exits. 2014 2015 $ docker run -t -i --rm ubuntu bash 2016 root@bc338942ef20:/# mount -t tmpfs none /mnt 2017 mount: permission denied 2018 2019 This will *not* work, because by default, most potentially dangerous kernel 2020 capabilities are dropped; including `cap_sys_admin` (which is required to mount 2021 filesystems). However, the `--privileged` flag will allow it to run: 2022 2023 $ docker run --privileged ubuntu bash 2024 root@50e3f57e16e6:/# mount -t tmpfs none /mnt 2025 root@50e3f57e16e6:/# df -h 2026 Filesystem Size Used Avail Use% Mounted on 2027 none 1.9G 0 1.9G 0% /mnt 2028 2029 The `--privileged` flag gives *all* capabilities to the container, and it also 2030 lifts all the limitations enforced by the `device` cgroup controller. In other 2031 words, the container can then do almost everything that the host can do. This 2032 flag exists to allow special use-cases, like running Docker within Docker. 2033 2034 $ docker run -w /path/to/dir/ -i -t ubuntu pwd 2035 2036 The `-w` lets the command being executed inside directory given, here 2037 `/path/to/dir/`. If the path does not exists it is created inside the container. 2038 2039 $ docker run -v `pwd`:`pwd` -w `pwd` -i -t ubuntu pwd 2040 2041 The `-v` flag mounts the current working directory into the container. The `-w` 2042 lets the command being executed inside the current working directory, by 2043 changing into the directory to the value returned by `pwd`. So this 2044 combination executes the command using the container, but inside the 2045 current working directory. 2046 2047 $ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash 2048 2049 When the host directory of a bind-mounted volume doesn't exist, Docker 2050 will automatically create this directory on the host for you. In the 2051 example above, Docker will create the `/doesnt/exist` 2052 folder before starting your container. 2053 2054 $ docker run --read-only -v /icanwrite busybox touch /icanwrite here 2055 2056 Volumes can be used in combination with `--read-only` to control where 2057 a container writes files. The `--read-only` flag mounts the container's root 2058 filesystem as read only prohibiting writes to locations other than the 2059 specified volumes for the container. 2060 2061 $ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v ./static-docker:/usr/bin/docker busybox sh 2062 2063 By bind-mounting the docker unix socket and statically linked docker 2064 binary (such as that provided by [https://get.docker.com]( 2065 https://get.docker.com)), you give the container the full access to create and 2066 manipulate the host's Docker daemon. 2067 2068 $ docker run -p 127.0.0.1:80:8080 ubuntu bash 2069 2070 This binds port `8080` of the container to port `80` on `127.0.0.1` of 2071 the host machine. The [Docker User Guide](/userguide/dockerlinks/) 2072 explains in detail how to manipulate ports in Docker. 2073 2074 $ docker run --expose 80 ubuntu bash 2075 2076 This exposes port `80` of the container for use within a link without 2077 publishing the port to the host system's interfaces. The [Docker User 2078 Guide](/userguide/dockerlinks) explains in detail how to manipulate 2079 ports in Docker. 2080 2081 $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash 2082 2083 This sets environmental variables in the container. For illustration all three 2084 flags are shown here. Where `-e`, `--env` take an environment variable and 2085 value, or if no `=` is provided, then that variable's current value is passed 2086 through (i.e. `$MYVAR1` from the host is set to `$MYVAR1` in the container). 2087 When no `=` is provided and that variable is not defined in the client's 2088 environment then that variable will be removed from the container's list of 2089 environment variables. 2090 All three flags, `-e`, `--env` and `--env-file` can be repeated. 2091 2092 Regardless of the order of these three flags, the `--env-file` are processed 2093 first, and then `-e`, `--env` flags. This way, the `-e` or `--env` will 2094 override variables as needed. 2095 2096 $ cat ./env.list 2097 TEST_FOO=BAR 2098 $ docker run --env TEST_FOO="This is a test" --env-file ./env.list busybox env | grep TEST_FOO 2099 TEST_FOO=This is a test 2100 2101 The `--env-file` flag takes a filename as an argument and expects each line 2102 to be in the `VAR=VAL` format, mimicking the argument passed to `--env`. Comment 2103 lines need only be prefixed with `#` 2104 2105 An example of a file passed with `--env-file` 2106 2107 $ cat ./env.list 2108 TEST_FOO=BAR 2109 2110 # this is a comment 2111 TEST_APP_DEST_HOST=10.10.0.127 2112 TEST_APP_DEST_PORT=8888 2113 2114 # pass through this variable from the caller 2115 TEST_PASSTHROUGH 2116 $ sudo TEST_PASSTHROUGH=howdy docker run --env-file ./env.list busybox env 2117 HOME=/ 2118 PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin 2119 HOSTNAME=5198e0745561 2120 TEST_FOO=BAR 2121 TEST_APP_DEST_HOST=10.10.0.127 2122 TEST_APP_DEST_PORT=8888 2123 TEST_PASSTHROUGH=howdy 2124 2125 $ docker run --name console -t -i ubuntu bash 2126 2127 A label is a a `key=value` pair that applies metadata to a container. To label a container with two labels: 2128 2129 $ docker run -l my-label --label com.example.foo=bar ubuntu bash 2130 2131 The `my-label` key doesn't specify a value so the label defaults to an empty 2132 string(`""`). To add multiple labels, repeat the label flag (`-l` or `--label`). 2133 2134 The `key=value` must be unique to avoid overwriting the label value. If you 2135 specify labels with identical keys but different values, each subsequent value 2136 overwrites the previous. Docker uses the last `key=value` you supply. 2137 2138 Use the `--label-file` flag to load multiple labels from a file. Delimit each 2139 label in the file with an EOL mark. The example below loads labels from a 2140 labels file in the current directory: 2141 2142 $ docker run --label-file ./labels ubuntu bash 2143 2144 The label-file format is similar to the format for loading environment 2145 variables. (Unlike environment variables, labels are not visible to processes 2146 running inside a container.) The following example illustrates a label-file 2147 format: 2148 2149 com.example.label1="a label" 2150 2151 # this is a comment 2152 com.example.label2=another\ label 2153 com.example.label3 2154 2155 You can load multiple label-files by supplying multiple `--label-file` flags. 2156 2157 For additional information on working with labels, see [*Labels - custom 2158 metadata in Docker*](/userguide/labels-custom-metadata/) in the Docker User 2159 Guide. 2160 2161 $ docker run --link /redis:redis --name console ubuntu bash 2162 2163 The `--link` flag will link the container named `/redis` into the newly 2164 created container with the alias `redis`. The new container can access the 2165 network and environment of the `redis` container via environment variables. 2166 The `--link` flag will also just accept the form `<name or id>` in which case 2167 the alias will match the name. For instance, you could have written the previous 2168 example as: 2169 2170 $ docker run --link redis --name console ubuntu bash 2171 2172 The `--name` flag will assign the name `console` to the newly created 2173 container. 2174 2175 $ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd 2176 2177 The `--volumes-from` flag mounts all the defined volumes from the referenced 2178 containers. Containers can be specified by repetitions of the `--volumes-from` 2179 argument. The container ID may be optionally suffixed with `:ro` or `:rw` to 2180 mount the volumes in read-only or read-write mode, respectively. By default, 2181 the volumes are mounted in the same mode (read write or read only) as 2182 the reference container. 2183 2184 Labeling systems like SELinux require proper labels be placed on volume content 2185 mounted into a container, otherwise the security system might prevent the 2186 processes running inside the container from using the content. By default, 2187 volumes are not relabeled. 2188 2189 Two suffixes :z or :Z can be added to the volume mount. These suffixes tell 2190 Docker to relabel file objects on the shared volumes. The 'z' option tells 2191 Docker that the volume content will be shared between containers. Docker will 2192 label the content with a shared content label. Shared volumes labels allow all 2193 containers to read/write content. The 'Z' option tells Docker to label the 2194 content with a private unshared label. Private volumes can only be used by the 2195 current container. 2196 2197 The `-a` flag tells `docker run` to bind to the container's `STDIN`, `STDOUT` or 2198 `STDERR`. This makes it possible to manipulate the output and input as needed. 2199 2200 $ echo "test" | docker run -i -a stdin ubuntu cat - 2201 2202 This pipes data into a container and prints the container's ID by attaching 2203 only to the container's `STDIN`. 2204 2205 $ docker run -a stderr ubuntu echo test 2206 2207 This isn't going to print anything unless there's an error because we've 2208 only attached to the `STDERR` of the container. The container's logs 2209 still store what's been written to `STDERR` and `STDOUT`. 2210 2211 $ cat somefile | docker run -i -a stdin mybuilder dobuild 2212 2213 This is how piping a file into a container could be done for a build. 2214 The container's ID will be printed after the build is done and the build 2215 logs could be retrieved using `docker logs`. This is 2216 useful if you need to pipe a file or something else into a container and 2217 retrieve the container's ID once the container has finished running. 2218 2219 $ docker run --device=/dev/sdc:/dev/xvdc --device=/dev/sdd --device=/dev/zero:/dev/nulo -i -t ubuntu ls -l /dev/{xvdc,sdd,nulo} 2220 brw-rw---- 1 root disk 8, 2 Feb 9 16:05 /dev/xvdc 2221 brw-rw---- 1 root disk 8, 3 Feb 9 16:05 /dev/sdd 2222 crw-rw-rw- 1 root root 1, 5 Feb 9 16:05 /dev/nulo 2223 2224 It is often necessary to directly expose devices to a container. The `--device` 2225 option enables that. For example, a specific block storage device or loop 2226 device or audio device can be added to an otherwise unprivileged container 2227 (without the `--privileged` flag) and have the application directly access it. 2228 2229 By default, the container will be able to `read`, `write` and `mknod` these devices. 2230 This can be overridden using a third `:rwm` set of options to each `--device` 2231 flag: 2232 2233 2234 ``` 2235 $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc 2236 2237 Command (m for help): q 2238 $ docker run --device=/dev/sda:/dev/xvdc:ro --rm -it ubuntu fdisk /dev/xvdc 2239 You will not be able to write the partition table. 2240 2241 Command (m for help): q 2242 2243 $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk /dev/xvdc 2244 2245 Command (m for help): q 2246 2247 $ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk /dev/xvdc 2248 fdisk: unable to open /dev/xvdc: Operation not permitted 2249 ``` 2250 2251 > **Note:** 2252 > `--device` cannot be safely used with ephemeral devices. Block devices that 2253 > may be removed should not be added to untrusted containers with `--device`. 2254 2255 **A complete example:** 2256 2257 $ docker run -d --name static static-web-files sh 2258 $ docker run -d --expose=8098 --name riak riakserver 2259 $ docker run -d -m 100m -e DEVELOPMENT=1 -e BRANCH=example-code -v $(pwd):/app/bin:ro --name app appserver 2260 $ docker run -d -p 1443:443 --dns=10.0.0.1 --dns-search=dev.org -v /var/log/httpd --volumes-from static --link riak --link app -h www.sven.dev.org --name web webserver 2261 $ docker run -t -i --rm --volumes-from web -w /var/log/httpd busybox tail -f access.log 2262 2263 This example shows five containers that might be set up to test a web 2264 application change: 2265 2266 1. Start a pre-prepared volume image `static-web-files` (in the background) 2267 that has CSS, image and static HTML in it, (with a `VOLUME` instruction in 2268 the Dockerfile to allow the web server to use those files); 2269 2. Start a pre-prepared `riakserver` image, give the container name `riak` and 2270 expose port `8098` to any containers that link to it; 2271 3. Start the `appserver` image, restricting its memory usage to 100MB, setting 2272 two environment variables `DEVELOPMENT` and `BRANCH` and bind-mounting the 2273 current directory (`$(pwd)`) in the container in read-only mode as `/app/bin`; 2274 4. Start the `webserver`, mapping port `443` in the container to port `1443` on 2275 the Docker server, setting the DNS server to `10.0.0.1` and DNS search 2276 domain to `dev.org`, creating a volume to put the log files into (so we can 2277 access it from another container), then importing the files from the volume 2278 exposed by the `static` container, and linking to all exposed ports from 2279 `riak` and `app`. Lastly, we set the hostname to `web.sven.dev.org` so its 2280 consistent with the pre-generated SSL certificate; 2281 5. Finally, we create a container that runs `tail -f access.log` using the logs 2282 volume from the `web` container, setting the workdir to `/var/log/httpd`. The 2283 `--rm` option means that when the container exits, the container's layer is 2284 removed. 2285 2286 #### Restart policies 2287 2288 Use Docker's `--restart` to specify a container's *restart policy*. A restart 2289 policy controls whether the Docker daemon restarts a container after exit. 2290 Docker supports the following restart policies: 2291 2292 <table> 2293 <thead> 2294 <tr> 2295 <th>Policy</th> 2296 <th>Result</th> 2297 </tr> 2298 </thead> 2299 <tbody> 2300 <tr> 2301 <td><strong>no</strong></td> 2302 <td> 2303 Do not automatically restart the container when it exits. This is the 2304 default. 2305 </td> 2306 </tr> 2307 <tr> 2308 <td> 2309 <span style="white-space: nowrap"> 2310 <strong>on-failure</strong>[:max-retries] 2311 </span> 2312 </td> 2313 <td> 2314 Restart only if the container exits with a non-zero exit status. 2315 Optionally, limit the number of restart retries the Docker 2316 daemon attempts. 2317 </td> 2318 </tr> 2319 <tr> 2320 <td><strong>always</strong></td> 2321 <td> 2322 Always restart the container regardless of the exit status. 2323 When you specify always, the Docker daemon will try to restart 2324 the container indefinitely. 2325 </td> 2326 </tr> 2327 </tbody> 2328 </table> 2329 2330 $ docker run --restart=always redis 2331 2332 This will run the `redis` container with a restart policy of **always** 2333 so that if the container exits, Docker will restart it. 2334 2335 More detailed information on restart policies can be found in the 2336 [Restart Policies (--restart)](/reference/run/#restart-policies-restart) section 2337 of the Docker run reference page. 2338 2339 ### Adding entries to a container hosts file 2340 2341 You can add other hosts into a container's `/etc/hosts` file by using one or more 2342 `--add-host` flags. This example adds a static address for a host named `docker`: 2343 2344 ``` 2345 $ docker run --add-host=docker:10.180.0.1 --rm -it debian 2346 $$ ping docker 2347 PING docker (10.180.0.1): 48 data bytes 2348 56 bytes from 10.180.0.1: icmp_seq=0 ttl=254 time=7.600 ms 2349 56 bytes from 10.180.0.1: icmp_seq=1 ttl=254 time=30.705 ms 2350 ^C--- docker ping statistics --- 2351 2 packets transmitted, 2 packets received, 0% packet loss 2352 round-trip min/avg/max/stddev = 7.600/19.152/30.705/11.553 ms 2353 ``` 2354 2355 Sometimes you need to connect to the Docker host from within your 2356 container. To enable this, pass the Docker host's IP address to 2357 the container using the `--add-host` flag. To find the host's address, 2358 use the `ip addr show` command. 2359 2360 The flags you pass to `ip addr show` depend on whether you are 2361 using IPv4 or IPv6 networking in your containers. Use the following 2362 flags for IPv4 address retrieval for a network device named `eth0`: 2363 2364 $ HOSTIP=`ip -4 addr show scope global dev eth0 | grep inet | awk '{print \$2}' | cut -d / -f 1` 2365 $ docker run --add-host=docker:${HOSTIP} --rm -it debian 2366 2367 For IPv6 use the `-6` flag instead of the `-4` flag. For other network 2368 devices, replace `eth0` with the correct device name (for example `docker0` 2369 for the bridge device). 2370 2371 ### Setting ulimits in a container 2372 2373 Since setting `ulimit` settings in a container requires extra privileges not 2374 available in the default container, you can set these using the `--ulimit` flag. 2375 `--ulimit` is specified with a soft and hard limit as such: 2376 `<type>=<soft limit>[:<hard limit>]`, for example: 2377 2378 ``` 2379 $ docker run --ulimit nofile=1024:1024 --rm debian ulimit -n 2380 1024 2381 ``` 2382 2383 >**Note:** 2384 > If you do not provide a `hard limit`, the `soft limit` will be used for both 2385 values. If no `ulimits` are set, they will be inherited from the default `ulimits` 2386 set on the daemon. 2387 > `as` option is disabled now. In other words, the following script is not supported: 2388 > `$ docker run -it --ulimit as=1024 fedora /bin/bash` 2389 2390 ## save 2391 2392 Usage: docker save [OPTIONS] IMAGE [IMAGE...] 2393 2394 Save an image(s) to a tar archive (streamed to STDOUT by default) 2395 2396 -o, --output="" Write to a file, instead of STDOUT 2397 2398 Produces a tarred repository to the standard output stream. 2399 Contains all parent layers, and all tags + versions, or specified `repo:tag`, for 2400 each argument provided. 2401 2402 It is used to create a backup that can then be used with `docker load` 2403 2404 $ docker save busybox > busybox.tar 2405 $ ls -sh busybox.tar 2406 2.7M busybox.tar 2407 $ docker save --output busybox.tar busybox 2408 $ ls -sh busybox.tar 2409 2.7M busybox.tar 2410 $ docker save -o fedora-all.tar fedora 2411 $ docker save -o fedora-latest.tar fedora:latest 2412 2413 It is even useful to cherry-pick particular tags of an image repository 2414 2415 $ docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy 2416 2417 ## search 2418 2419 Search [Docker Hub](https://hub.docker.com) for images 2420 2421 Usage: docker search [OPTIONS] TERM 2422 2423 Search the Docker Hub for images 2424 2425 --automated=false Only show automated builds 2426 --no-trunc=false Don't truncate output 2427 -s, --stars=0 Only displays with at least x stars 2428 2429 See [*Find Public Images on Docker Hub*]( 2430 /userguide/dockerrepos/#searching-for-images) for 2431 more details on finding shared images from the command line. 2432 2433 > **Note:** 2434 > Search queries will only return up to 25 results 2435 2436 ## start 2437 2438 Usage: docker start [OPTIONS] CONTAINER [CONTAINER...] 2439 2440 Start one or more stopped containers 2441 2442 -a, --attach=false Attach STDOUT/STDERR and forward signals 2443 -i, --interactive=false Attach container's STDIN 2444 2445 ## stats 2446 2447 Usage: docker stats CONTAINER [CONTAINER...] 2448 2449 Display a live stream of one or more containers' resource usage statistics 2450 2451 --help=false Print usage 2452 --no-stream=false Disable streaming stats and only pull the first result 2453 2454 Running `docker stats` on multiple containers 2455 2456 $ docker stats redis1 redis2 2457 CONTAINER CPU % MEM USAGE/LIMIT MEM % NET I/O 2458 redis1 0.07% 796 KB/64 MB 1.21% 788 B/648 B 2459 redis2 0.07% 2.746 MB/64 MB 4.29% 1.266 KB/648 B 2460 2461 2462 The `docker stats` command will only return a live stream of data for running 2463 containers. Stopped containers will not return any data. 2464 2465 > **Note:** 2466 > If you want more detailed information about a container's resource usage, use the API endpoint. 2467 2468 ## stop 2469 2470 Usage: docker stop [OPTIONS] CONTAINER [CONTAINER...] 2471 2472 Stop a running container by sending SIGTERM and then SIGKILL after a 2473 grace period 2474 2475 -t, --time=10 Seconds to wait for stop before killing it 2476 2477 The main process inside the container will receive `SIGTERM`, and after a 2478 grace period, `SIGKILL`. 2479 2480 ## tag 2481 2482 Usage: docker tag [OPTIONS] IMAGE[:TAG] [REGISTRYHOST/][USERNAME/]NAME[:TAG] 2483 2484 Tag an image into a repository 2485 2486 -f, --force=false Force 2487 2488 You can group your images together using names and tags, and then upload 2489 them to [*Share Images via Repositories*]( 2490 /userguide/dockerrepos/#contributing-to-docker-hub). 2491 2492 ## top 2493 2494 Usage: docker top CONTAINER [ps OPTIONS] 2495 2496 Display the running processes of a container 2497 2498 ## unpause 2499 2500 Usage: docker unpause CONTAINER [CONTAINER...] 2501 2502 Unpause all processes within a container 2503 2504 The `docker unpause` command uses the cgroups freezer to un-suspend all 2505 processes in a container. 2506 2507 See the 2508 [cgroups freezer documentation](https://www.kernel.org/doc/Documentation/cgroups/freezer-subsystem.txt) 2509 for further details. 2510 2511 ## version 2512 2513 Usage: docker version 2514 2515 Show the Docker version information. 2516 2517 Show the Docker version, API version, Git commit, Go version and OS/architecture 2518 of both Docker client and daemon. Example use: 2519 2520 $ docker version 2521 Client version: 1.5.0 2522 Client API version: 1.17 2523 Go version (client): go1.4.1 2524 Git commit (client): a8a31ef 2525 OS/Arch (client): darwin/amd64 2526 Server version: 1.5.0 2527 Server API version: 1.17 2528 Go version (server): go1.4.1 2529 Git commit (server): a8a31ef 2530 OS/Arch (server): linux/amd64 2531 2532 2533 ## wait 2534 2535 Usage: docker wait CONTAINER [CONTAINER...] 2536 2537 Block until a container stops, then print its exit code. 2538