github.com/fcwu/docker@v1.4.2-0.20150115145920-2a69ca89f0df/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  # Command Line
     6  
     7  To list available commands, either run `docker` with no parameters
     8  or execute `docker help`:
     9  
    10      $ sudo docker
    11        Usage: docker [OPTIONS] COMMAND [arg...]
    12          -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.
    13  
    14        A self-sufficient runtime for Linux containers.
    15  
    16        ...
    17  
    18  ## Help
    19  To list the help on any command just execute the command, followed by the `--help` option.
    20  
    21      $ sudo docker run --help
    22  
    23      Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
    24  
    25      Run a command in a new container
    26  
    27        -a, --attach=[]            Attach to STDIN, STDOUT or STDERR.
    28        -c, --cpu-shares=0         CPU shares (relative weight)
    29      ...
    30  
    31  ## Option types
    32  
    33  Single character commandline options can be combined, so rather than
    34  typing `docker run -t -i --name test busybox sh`,
    35  you can write `docker run -ti --name test busybox sh`.
    36  
    37  ### Boolean
    38  
    39  Boolean options look like `-d=false`. The value you
    40  see is the default value which gets set if you do **not** use the
    41  boolean flag. If you do call `run -d`, that sets the
    42  opposite boolean value, so in this case, `true`, and
    43  so `docker run -d` **will** run in "detached" mode,
    44  in the background. Other boolean options are similar – specifying them
    45  will set the value to the opposite of the default value.
    46  
    47  ### Multi
    48  
    49  Options like `-a=[]` indicate they can be specified multiple times:
    50  
    51      $ sudo docker run -a stdin -a stdout -a stderr -i -t ubuntu /bin/bash
    52  
    53  Sometimes this can use a more complex value string, as for `-v`:
    54  
    55      $ sudo docker run -v /host:/container example/mysql
    56  
    57  ### Strings and Integers
    58  
    59  Options like `--name=""` expect a string, and they
    60  can only be specified once. Options like `-c=0`
    61  expect an integer, and they can only be specified once.
    62  
    63  ## daemon
    64  
    65      Usage: docker [OPTIONS] COMMAND [arg...]
    66  
    67      A self-sufficient runtime for linux containers.
    68  
    69      Options:
    70        --api-enable-cors=false                    Enable CORS headers in the remote API
    71        -b, --bridge=""                            Attach containers to a pre-existing network bridge
    72                                                     use 'none' to disable container networking
    73        --bip=""                                   Use this CIDR notation address for the network bridge's IP, not compatible with -b
    74        -D, --debug=false                          Enable debug mode
    75        -d, --daemon=false                         Enable daemon mode
    76        --dns=[]                                   Force Docker to use specific DNS servers
    77        --dns-search=[]                            Force Docker to use specific DNS search domains
    78        -e, --exec-driver="native"                 Force the Docker runtime to use a specific exec driver
    79        --fixed-cidr=""                            IPv4 subnet for fixed IPs (ex: 10.20.0.0/16)
    80                                                     this subnet must be nested in the bridge subnet (which is defined by -b or --bip)
    81        -G, --group="docker"                       Group to assign the unix socket specified by -H when running in daemon mode
    82                                                     use '' (the empty string) to disable setting of a group
    83        -g, --graph="/var/lib/docker"              Path to use as the root of the Docker runtime
    84        -H, --host=[]                              The socket(s) to bind to in daemon mode or connect to in client mode, specified using one or more tcp://host:port, unix:///path/to/socket, fd://* or fd://socketfd.
    85        --icc=true                                 Allow unrestricted inter-container and Docker daemon host communication
    86        --insecure-registry=[]                     Enable insecure communication with specified registries (disables certificate verification for HTTPS and enables HTTP fallback) (e.g., localhost:5000 or 10.20.0.0/16)
    87        --ip=0.0.0.0                               Default IP address to use when binding container ports
    88        --ip-forward=true                          Enable net.ipv4.ip_forward
    89        --ip-masq=true                             Enable IP masquerading for bridge's IP range
    90        --iptables=true                            Enable Docker's addition of iptables rules
    91         -l, --log-level="info"                    Set the logging level
    92        --label=[]                                 Set key=value labels to the daemon (displayed in `docker info`)
    93        --mtu=0                                    Set the containers network MTU
    94                                                     if no value is provided: default to the default route MTU or 1500 if no default route is available
    95        -p, --pidfile="/var/run/docker.pid"        Path to use for daemon PID file
    96        --registry-mirror=[]                       Specify a preferred Docker registry mirror
    97        -s, --storage-driver=""                    Force the Docker runtime to use a specific storage driver
    98        --selinux-enabled=false                    Enable selinux support. SELinux does not presently support the BTRFS storage driver
    99        --storage-opt=[]                           Set storage driver options
   100        --tls=false                                Use TLS; implied by --tlsverify flag
   101        --tlscacert="/home/sven/.docker/ca.pem"    Trust only remotes providing a certificate signed by the CA given here
   102        --tlscert="/home/sven/.docker/cert.pem"    Path to TLS certificate file
   103        --tlskey="/home/sven/.docker/key.pem"      Path to TLS key file
   104        --tlsverify=false                          Use TLS and verify the remote (daemon: verify client, client: verify daemon)
   105        -v, --version=false                        Print version information and quit
   106  
   107  Options with [] may be specified multiple times.
   108  
   109  The Docker daemon is the persistent process that manages containers.
   110  Docker uses the same binary for both the daemon and client. To run the
   111  daemon you provide the `-d` flag.
   112  
   113  
   114  To run the daemon with debug output, use `docker -d -D`.
   115  
   116  ### Daemon socket option
   117  
   118  The Docker daemon can listen for [Docker Remote API](/reference/api/docker_remote_api/)
   119  requests via three different types of Socket: `unix`, `tcp`, and `fd`.
   120  
   121  By default, a `unix` domain socket (or IPC socket) is created at `/var/run/docker.sock`,
   122  requiring either `root` permission, or `docker` group membership.
   123  
   124  If you need to access the Docker daemon remotely, you need to enable the `tcp`
   125  Socket. Beware that the default setup provides un-encrypted and un-authenticated
   126  direct access to the Docker daemon - and should be secured either using the
   127  [built in HTTPS encrypted socket](/articles/https/), or by putting a secure web
   128  proxy in front of it. You can listen on port `2375` on all network interfaces
   129  with `-H tcp://0.0.0.0:2375`, or on a particular network interface using its IP
   130  address: `-H tcp://192.168.59.103:2375`. It is conventional to use port `2375`
   131  for un-encrypted, and port `2376` for encrypted communication with the daemon.
   132  
   133  > **Note** If you're using an HTTPS encrypted socket, keep in mind that only TLS1.0
   134  > and greater are supported. Protocols SSLv3 and under are not supported anymore
   135  > for security reasons.
   136  
   137  On Systemd based systems, you can communicate with the daemon via
   138  [systemd socket activation](http://0pointer.de/blog/projects/socket-activation.html), use
   139  `docker -d -H fd://`. Using `fd://` will work perfectly for most setups but
   140  you can also specify individual sockets: `docker -d -H fd://3`. If the
   141  specified socket activated files aren't found, then Docker will exit. You
   142  can find examples of using Systemd socket activation with Docker and
   143  Systemd in the [Docker source tree](
   144  https://github.com/docker/docker/tree/master/contrib/init/systemd/).
   145  
   146  You can configure the Docker daemon to listen to multiple sockets at the same
   147  time using multiple `-H` options:
   148  
   149      # listen using the default unix socket, and on 2 specific IP addresses on this host.
   150      docker -d -H unix:///var/run/docker.sock -H tcp://192.168.59.106 -H tcp://10.10.10.2
   151  
   152  The Docker client will honor the `DOCKER_HOST` environment variable to set
   153  the `-H` flag for the client.
   154  
   155      $ sudo docker -H tcp://0.0.0.0:2375 ps
   156      # or
   157      $ export DOCKER_HOST="tcp://0.0.0.0:2375"
   158      $ sudo docker ps
   159      # both are equal
   160  
   161  Setting the `DOCKER_TLS_VERIFY` environment variable to any value other than the empty
   162  string is equivalent to setting the `--tlsverify` flag. The following are equivalent:
   163  
   164      $ sudo docker --tlsverify ps
   165      # or
   166      $ export DOCKER_TLS_VERIFY=1
   167      $ sudo docker ps
   168  
   169  ### Daemon storage-driver option
   170  
   171  The Docker daemon has support for several different image layer storage drivers: `aufs`,
   172  `devicemapper`, `btrfs` and `overlay`.
   173  
   174  The `aufs` driver is the oldest, but is based on a Linux kernel patch-set that
   175  is unlikely to be merged into the main kernel. These are also known to cause some
   176  serious kernel crashes. However, `aufs` is also the only storage driver that allows
   177  containers to share executable and shared library memory, so is a useful choice
   178  when running thousands of containers with the same program or libraries.
   179  
   180  The `devicemapper` driver uses thin provisioning and Copy on Write (CoW)
   181  snapshots. For each devicemapper graph location – typically
   182  `/var/lib/docker/devicemapper` – a thin pool is created based on two block
   183  devices, one for data and one for metadata.  By default, these block devices
   184  are created automatically by using loopback mounts of automatically created
   185  sparse files. Refer to [Storage driver options](#storage-driver-options) below
   186  for a way how to customize this setup.
   187  [~jpetazzo/Resizing Docker containers with the Device Mapper plugin](
   188  http://jpetazzo.github.io/2014/01/29/docker-device-mapper-resize/) article
   189  explains how to tune your existing setup without the use of options.
   190  
   191  The `btrfs` driver is very fast for `docker build` - but like `devicemapper` does not
   192  share executable memory between devices. Use `docker -d -s btrfs -g /mnt/btrfs_partition`.
   193  
   194  The `overlay` is a very fast union filesystem. It is now merged in the main
   195  Linux kernel as of [3.18.0](https://lkml.org/lkml/2014/10/26/137).
   196  Call `docker -d -s overlay` to use it. 
   197  > **Note:** 
   198  > It is currently unsupported on `btrfs` or any Copy on Write filesystem
   199  > and should only be used over `ext4` partitions.
   200  
   201  #### Storage driver options
   202  
   203  Particular storage-driver can be configured with options specified with
   204  `--storage-opt` flags. The only driver accepting options is `devicemapper` as
   205  of now. All its options are prefixed with `dm`.
   206  
   207  Currently supported options are:
   208  
   209   *  `dm.basesize`
   210  
   211      Specifies the size to use when creating the base device, which limits the
   212      size of images and containers. The default value is 10G. Note, thin devices
   213      are inherently "sparse", so a 10G device which is mostly empty doesn't use
   214      10 GB of space on the pool. However, the filesystem will use more space for
   215      the empty case the larger the device is.
   216      
   217       **Warning**: This value affects the system-wide "base" empty filesystem
   218       that may already be initialized and inherited by pulled images. Typically,
   219       a change to this value will require additional steps to take effect:
   220      
   221          $ sudo service docker stop
   222          $ sudo rm -rf /var/lib/docker
   223          $ sudo service docker start
   224  
   225      Example use:
   226  
   227          $ sudo docker -d --storage-opt dm.basesize=20G
   228  
   229   *  `dm.loopdatasize`
   230  
   231      Specifies the size to use when creating the loopback file for the "data"
   232      device which is used for the thin pool. The default size is 100G. Note that
   233      the file is sparse, so it will not initially take up this much space.
   234  
   235      Example use:
   236  
   237          $ sudo docker -d --storage-opt dm.loopdatasize=200G
   238  
   239   *  `dm.loopmetadatasize`
   240  
   241      Specifies the size to use when creating the loopback file for the
   242      "metadata" device which is used for the thin pool. The default size is 2G.
   243      Note that the file is sparse, so it will not initially take up this much
   244      space.
   245  
   246      Example use:
   247  
   248          $ sudo docker -d --storage-opt dm.loopmetadatasize=4G
   249  
   250   *  `dm.fs`
   251  
   252      Specifies the filesystem type to use for the base device. The supported
   253      options are "ext4" and "xfs". The default is "ext4"
   254  
   255      Example use:
   256  
   257          $ sudo docker -d --storage-opt dm.fs=xfs
   258  
   259   *  `dm.mkfsarg`
   260  
   261      Specifies extra mkfs arguments to be used when creating the base device.
   262  
   263      Example use:
   264  
   265          $ sudo docker -d --storage-opt "dm.mkfsarg=-O ^has_journal"
   266  
   267   *  `dm.mountopt`
   268  
   269      Specifies extra mount options used when mounting the thin devices.
   270  
   271      Example use:
   272  
   273          $ sudo docker -d --storage-opt dm.mountopt=nodiscard
   274  
   275   *  `dm.datadev`
   276  
   277      Specifies a custom blockdevice to use for data for the thin pool.
   278  
   279      If using a block device for device mapper storage, ideally both datadev and
   280      metadatadev should be specified to completely avoid using the loopback
   281      device.
   282  
   283      Example use:
   284  
   285          $ sudo docker -d \
   286              --storage-opt dm.datadev=/dev/sdb1 \
   287              --storage-opt dm.metadatadev=/dev/sdc1
   288  
   289   *  `dm.metadatadev`
   290  
   291      Specifies a custom blockdevice to use for metadata for the thin pool.
   292  
   293      For best performance the metadata should be on a different spindle than the
   294      data, or even better on an SSD.
   295  
   296      If setting up a new metadata pool it is required to be valid. This can be
   297      achieved by zeroing the first 4k to indicate empty metadata, like this:
   298  
   299          $ dd if=/dev/zero of=$metadata_dev bs=4096 count=1
   300  
   301      Example use:
   302  
   303          $ sudo docker -d \
   304              --storage-opt dm.datadev=/dev/sdb1 \
   305              --storage-opt dm.metadatadev=/dev/sdc1
   306  
   307   *  `dm.blocksize`
   308  
   309      Specifies a custom blocksize to use for the thin pool. The default
   310      blocksize is 64K.
   311  
   312      Example use:
   313  
   314          $ sudo docker -d --storage-opt dm.blocksize=512K
   315  
   316   *  `dm.blkdiscard`
   317  
   318      Enables or disables the use of blkdiscard when removing devicemapper
   319      devices. This is enabled by default (only) if using loopback devices and is
   320      required to res-parsify the loopback file on image/container removal.
   321  
   322      Disabling this on loopback can lead to *much* faster container removal
   323      times, but will make the space used in `/var/lib/docker` directory not be
   324      returned to the system for other use when containers are removed.
   325  
   326      Example use:
   327  
   328          $ sudo docker -d --storage-opt dm.blkdiscard=false
   329  
   330  ### Docker exec-driver option
   331  
   332  The Docker daemon uses a specifically built `libcontainer` execution driver as its
   333  interface to the Linux kernel `namespaces`, `cgroups`, and `SELinux`.
   334  
   335  There is still legacy support for the original [LXC userspace tools](
   336  https://linuxcontainers.org/) via the `lxc` execution driver, however, this is
   337  not where the primary development of new functionality is taking place.
   338  Add `-e lxc` to the daemon flags to use the `lxc` execution driver.
   339  
   340  
   341  ### Daemon DNS options
   342  
   343  To set the DNS server for all Docker containers, use
   344  `docker -d --dns 8.8.8.8`.
   345  
   346  To set the DNS search domain for all Docker containers, use
   347  `docker -d --dns-search example.com`.
   348  
   349  ### Insecure registries
   350  
   351  Docker considers a private registry either secure or insecure.
   352  In the rest of this section, *registry* is used for *private registry*, and `myregistry:5000`
   353  is a placeholder example for a private registry.
   354  
   355  A secure registry uses TLS and a copy of its CA certificate is placed on the Docker host at
   356  `/etc/docker/certs.d/myregistry:5000/ca.crt`.
   357  An insecure registry is either not using TLS (i.e., listening on plain text HTTP), or is using
   358  TLS with a CA certificate not known by the Docker daemon. The latter can happen when the
   359  certificate was not found under `/etc/docker/certs.d/myregistry:5000/`, or if the certificate
   360  verification failed (i.e., wrong CA).
   361  
   362  By default, Docker assumes all, but local (see local registries below), registries are secure.
   363  Communicating with an insecure registry is not possible if Docker assumes that registry is secure.
   364  In order to communicate with an insecure registry, the Docker daemon requires `--insecure-registry`
   365  in one of the following two forms: 
   366  
   367  * `--insecure-registry myregistry:5000` tells the Docker daemon that myregistry:5000 should be considered insecure.
   368  * `--insecure-registry 10.1.0.0/16` tells the Docker daemon that all registries whose domain resolve to an IP address is part
   369  of the subnet described by the CIDR syntax, should be considered insecure.
   370  
   371  The flag can be used multiple times to allow multiple registries to be marked as insecure.
   372  
   373  If an insecure registry is not marked as insecure, `docker pull`, `docker push`, and `docker search`
   374  will result in an error message prompting the user to either secure or pass the `--insecure-registry`
   375  flag to the Docker daemon as described above.
   376  
   377  Local registries, whose IP address falls in the 127.0.0.0/8 range, are automatically marked as insecure
   378  as of Docker 1.3.2. It is not recommended to rely on this, as it may change in the future.
   379  
   380  
   381  ### Miscellaneous options
   382  
   383  IP masquerading uses address translation to allow containers without a public IP to talk
   384  to other machines on the Internet. This may interfere with some network topologies and
   385  can be disabled with --ip-masq=false.
   386  
   387  Docker supports softlinks for the Docker data directory
   388  (`/var/lib/docker`) and for `/var/lib/docker/tmp`. The `DOCKER_TMPDIR` and the data directory can be set like this:
   389  
   390      DOCKER_TMPDIR=/mnt/disk2/tmp /usr/local/bin/docker -d -D -g /var/lib/docker -H unix:// > /var/lib/boot2docker/docker.log 2>&1
   391      # or
   392      export DOCKER_TMPDIR=/mnt/disk2/tmp
   393      /usr/local/bin/docker -d -D -g /var/lib/docker -H unix:// > /var/lib/boot2docker/docker.log 2>&1
   394  
   395  
   396  ## attach
   397  
   398      Usage: docker attach [OPTIONS] CONTAINER
   399  
   400      Attach to a running container
   401  
   402        --no-stdin=false    Do not attach STDIN
   403        --sig-proxy=true    Proxy all received signals to the process (non-TTY mode only). SIGCHLD, SIGKILL, and SIGSTOP are not proxied.
   404  
   405  The `attach` command lets you view or interact with any running container's
   406  primary process (`pid 1`).
   407  
   408  You can attach to the same contained process multiple times simultaneously, screen
   409  sharing style, or quickly view the progress of your daemonized process.
   410  
   411  > **Note:** This command is not for running a new process in a container.
   412  > See: [`docker exec`](#exec).
   413  
   414  You can detach from the container again (and leave it running) with
   415  `CTRL-p CTRL-q` (for a quiet exit), or `CTRL-c`  which will send a
   416  SIGKILL to the container, or `CTRL-\` to get a stacktrace of the
   417  Docker client when it quits. When you detach from the container's
   418  process the exit code will be returned to the client.
   419  
   420  To stop a container, use `docker stop`.
   421  
   422  To kill the container, use `docker kill`.
   423  
   424  #### Examples
   425  
   426      $ ID=$(sudo docker run -d ubuntu /usr/bin/top -b)
   427      $ sudo docker attach $ID
   428      top - 02:05:52 up  3:05,  0 users,  load average: 0.01, 0.02, 0.05
   429      Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
   430      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
   431      Mem:    373572k total,   355560k used,    18012k free,    27872k buffers
   432      Swap:   786428k total,        0k used,   786428k free,   221740k cached
   433  
   434      PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
   435       1 root      20   0 17200 1116  912 R    0  0.3   0:00.03 top
   436  
   437       top - 02:05:55 up  3:05,  0 users,  load average: 0.01, 0.02, 0.05
   438       Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
   439       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
   440       Mem:    373572k total,   355244k used,    18328k free,    27872k buffers
   441       Swap:   786428k total,        0k used,   786428k free,   221776k cached
   442  
   443         PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
   444             1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
   445  
   446  
   447       top - 02:05:58 up  3:06,  0 users,  load average: 0.01, 0.02, 0.05
   448       Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
   449       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
   450       Mem:    373572k total,   355780k used,    17792k free,    27880k buffers
   451       Swap:   786428k total,        0k used,   786428k free,   221776k cached
   452  
   453       PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
   454            1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
   455      ^C$
   456      $ sudo docker stop $ID
   457  
   458  ## build
   459  
   460      Usage: docker build [OPTIONS] PATH | URL | -
   461  
   462      Build a new image from the source code at PATH
   463  
   464        -f, --file=""            Location of the Dockerfile to use. Default is 'Dockerfile' at the root of the build context
   465        --force-rm=false         Always remove intermediate containers, even after unsuccessful builds
   466        --no-cache=false         Do not use cache when building the image
   467        -q, --quiet=false        Suppress the verbose output generated by the containers
   468        --rm=true                Remove intermediate containers after a successful build
   469        -t, --tag=""             Repository name (and optionally a tag) to be applied to the resulting image in case of success
   470  
   471  Use this command to build Docker images from a Dockerfile and a
   472  "context".
   473  
   474  The files at `PATH` or `URL` are called the "context" of the build. The
   475  build process may refer to any of the files in the context, for example
   476  when using an [*ADD*](/reference/builder/#add) instruction.
   477  When a single Dockerfile is given as `URL` or is piped through `STDIN`
   478  (`docker build - < Dockerfile`), then no context is set.
   479  
   480  When a Git repository is set as `URL`, then the repository is used as
   481  the context. The Git repository is cloned with its submodules
   482  (`git clone -recursive`). A fresh `git clone` occurs in a temporary directory
   483  on your local host, and then this is sent to the Docker daemon as the
   484  context.  This way, your local user credentials and VPN's etc can be
   485  used to access private repositories.
   486  
   487  If a file named `.dockerignore` exists in the root of `PATH` then it
   488  is interpreted as a newline-separated list of exclusion patterns.
   489  Exclusion patterns match files or directories relative to `PATH` that
   490  will be excluded from the context. Globbing is done using Go's
   491  [filepath.Match](http://golang.org/pkg/path/filepath#Match) rules.
   492  
   493  Please note that `.dockerignore` files in other subdirectories are
   494  considered as normal files. Filepaths in .dockerignore are absolute with
   495  the current directory as the root. Wildcards are allowed but the search
   496  is not recursive.
   497  
   498  #### Example .dockerignore file
   499      */temp*
   500      */*/temp*
   501      temp?
   502  
   503  The first line above `*/temp*`, would ignore all files with names starting with
   504  `temp` from any subdirectory below the root directory. For example, a file named
   505  `/somedir/temporary.txt` would be ignored. The second line `*/*/temp*`, will
   506  ignore files starting with name `temp` from any subdirectory that is two levels
   507  below the root directory. For example, the file `/somedir/subdir/temporary.txt`
   508  would get ignored in this case. The last line in the above example `temp?`
   509  will ignore the files that match the pattern from the root directory.
   510  For example, the files `tempa`, `tempb` are ignored from the root directory.
   511  Currently there is no support for regular expressions. Formats
   512  like `[^temp*]` are ignored.
   513  
   514  By default the `docker build` command will look for a `Dockerfile` at the
   515  root of the build context. The `-f`, `--file`, option lets you specify
   516  the path to an alternative file to use instead.  This is useful
   517  in cases where the same set of files are used for multiple builds. The path
   518  must be to a file within the build context. If a relative path is specified
   519  then it must to be relative to the current directory.
   520  
   521  
   522  See also:
   523  
   524  [*Dockerfile Reference*](/reference/builder).
   525  
   526  #### Examples
   527  
   528      $ sudo docker build .
   529      Uploading context 10240 bytes
   530      Step 1 : FROM busybox
   531      Pulling repository busybox
   532       ---> e9aa60c60128MB/2.284 MB (100%) endpoint: https://cdn-registry-1.docker.io/v1/
   533      Step 2 : RUN ls -lh /
   534       ---> Running in 9c9e81692ae9
   535      total 24
   536      drwxr-xr-x    2 root     root        4.0K Mar 12  2013 bin
   537      drwxr-xr-x    5 root     root        4.0K Oct 19 00:19 dev
   538      drwxr-xr-x    2 root     root        4.0K Oct 19 00:19 etc
   539      drwxr-xr-x    2 root     root        4.0K Nov 15 23:34 lib
   540      lrwxrwxrwx    1 root     root           3 Mar 12  2013 lib64 -> lib
   541      dr-xr-xr-x  116 root     root           0 Nov 15 23:34 proc
   542      lrwxrwxrwx    1 root     root           3 Mar 12  2013 sbin -> bin
   543      dr-xr-xr-x   13 root     root           0 Nov 15 23:34 sys
   544      drwxr-xr-x    2 root     root        4.0K Mar 12  2013 tmp
   545      drwxr-xr-x    2 root     root        4.0K Nov 15 23:34 usr
   546       ---> b35f4035db3f
   547      Step 3 : CMD echo Hello world
   548       ---> Running in 02071fceb21b
   549       ---> f52f38b7823e
   550      Successfully built f52f38b7823e
   551      Removing intermediate container 9c9e81692ae9
   552      Removing intermediate container 02071fceb21b
   553  
   554  This example specifies that the `PATH` is
   555  `.`, and so all the files in the local directory get
   556  `tar`d and sent to the Docker daemon. The `PATH`
   557  specifies where to find the files for the "context" of the build on the
   558  Docker daemon. Remember that the daemon could be running on a remote
   559  machine and that no parsing of the Dockerfile
   560  happens at the client side (where you're running
   561  `docker build`). That means that *all* the files at
   562  `PATH` get sent, not just the ones listed to
   563  [*ADD*](/reference/builder/#add) in the Dockerfile.
   564  
   565  The transfer of context from the local machine to the Docker daemon is
   566  what the `docker` client means when you see the
   567  "Sending build context" message.
   568  
   569  If you wish to keep the intermediate containers after the build is
   570  complete, you must use `--rm=false`. This does not
   571  affect the build cache.
   572  
   573      $ sudo docker build .
   574      Uploading context 18.829 MB
   575      Uploading context
   576      Step 0 : FROM busybox
   577       ---> 769b9341d937
   578      Step 1 : CMD echo Hello world
   579       ---> Using cache
   580       ---> 99cc1ad10469
   581      Successfully built 99cc1ad10469
   582      $ echo ".git" > .dockerignore
   583      $ sudo docker build .
   584      Uploading context  6.76 MB
   585      Uploading context
   586      Step 0 : FROM busybox
   587       ---> 769b9341d937
   588      Step 1 : CMD echo Hello world
   589       ---> Using cache
   590       ---> 99cc1ad10469
   591      Successfully built 99cc1ad10469
   592  
   593  This example shows the use of the `.dockerignore` file to exclude the `.git`
   594  directory from the context. Its effect can be seen in the changed size of the
   595  uploaded context.
   596  
   597      $ sudo docker build -t vieux/apache:2.0 .
   598  
   599  This will build like the previous example, but it will then tag the
   600  resulting image. The repository name will be `vieux/apache`
   601  and the tag will be `2.0`
   602  
   603      $ sudo docker build - < Dockerfile
   604  
   605  This will read a Dockerfile from `STDIN` without context. Due to the
   606  lack of a context, no contents of any local directory will be sent to
   607  the Docker daemon. Since there is no context, a Dockerfile `ADD` only
   608  works if it refers to a remote URL.
   609  
   610      $ sudo docker build - < context.tar.gz
   611  
   612  This will build an image for a compressed context read from `STDIN`.
   613  Supported formats are: bzip2, gzip and xz.
   614  
   615      $ sudo docker build github.com/creack/docker-firefox
   616  
   617  This will clone the GitHub repository and use the cloned repository as
   618  context. The Dockerfile at the root of the
   619  repository is used as Dockerfile. Note that you
   620  can specify an arbitrary Git repository by using the `git://` or `git@`
   621  schema.
   622  
   623      $ sudo docker build -f Dockerfile.debug .
   624  
   625  This will use a file called `Dockerfile.debug` for the build
   626  instructions instead of `Dockerfile`.
   627  
   628      $ sudo docker build -f dockerfiles/Dockerfile.debug -t myapp_debug .
   629      $ sudo docker build -f dockerfiles/Dockerfile.prod  -t myapp_prod .
   630  
   631  The above commands will build the current build context (as specified by 
   632  the `.`) twice, once using a debug version of a `Dockerfile` and once using 
   633  a production version.
   634  
   635      $ cd /home/me/myapp/some/dir/really/deep
   636      $ sudo docker build -f /home/me/myapp/dockerfiles/debug /home/me/myapp
   637      $ sudo docker build -f ../../../../dockerfiles/debug /home/me/myapp
   638  
   639  These two `docker build` commands do the exact same thing. They both
   640  use the contents of the `debug` file instead of looking for a `Dockerfile` 
   641  and will use `/home/me/myapp` as the root of the build context. Note that 
   642  `debug` is in the directory structure of the build context, regardless of how 
   643  you refer to it on the command line.
   644  
   645  > **Note:** `docker build` will return a `no such file or directory` error
   646  > if the file or directory does not exist in the uploaded context. This may
   647  > happen if there is no context, or if you specify a file that is elsewhere
   648  > on the Host system. The context is limited to the current directory (and its
   649  > children) for security reasons, and to ensure repeatable builds on remote
   650  > Docker hosts. This is also the reason why `ADD ../file` will not work.
   651  
   652  ## commit
   653  
   654      Usage: docker commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]]
   655  
   656      Create a new image from a container's changes
   657  
   658        -a, --author=""     Author (e.g., "John Hannibal Smith <hannibal@a-team.com>")
   659        -m, --message=""    Commit message
   660        -p, --pause=true    Pause container during commit
   661  
   662  It can be useful to commit a container's file changes or settings into a
   663  new image. This allows you debug a container by running an interactive
   664  shell, or to export a working dataset to another server. Generally, it
   665  is better to use Dockerfiles to manage your images in a documented and
   666  maintainable way.
   667  
   668  By default, the container being committed and its processes will be paused
   669  while the image is committed. This reduces the likelihood of
   670  encountering data corruption during the process of creating the commit.
   671  If this behavior is undesired, set the 'p' option to false.
   672  
   673  #### Commit an existing container
   674  
   675      $ sudo docker ps
   676      ID                  IMAGE               COMMAND             CREATED             STATUS              PORTS
   677      c3f279d17e0a        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours
   678      197387f1b436        ubuntu:12.04        /bin/bash           7 days ago          Up 25 hours
   679      $ sudo docker commit c3f279d17e0a  SvenDowideit/testimage:version3
   680      f5283438590d
   681      $ sudo docker images | head
   682      REPOSITORY                        TAG                 ID                  CREATED             VIRTUAL SIZE
   683      SvenDowideit/testimage            version3            f5283438590d        16 seconds ago      335.7 MB
   684  
   685  ## cp
   686  
   687  Copy files/folders from a container's filesystem to the host
   688  path.  Paths are relative to the root of the filesystem.
   689  
   690      Usage: docker cp CONTAINER:PATH HOSTPATH
   691  
   692      Copy files/folders from the PATH to the HOSTPATH
   693  
   694  ## create
   695  
   696  Creates a new container.
   697  
   698      Usage: docker create [OPTIONS] IMAGE [COMMAND] [ARG...]
   699  
   700      Create a new container
   701  
   702        -a, --attach=[]            Attach to STDIN, STDOUT or STDERR.
   703        --add-host=[]              Add a custom host-to-IP mapping (host:ip)
   704        -c, --cpu-shares=0         CPU shares (relative weight)
   705        --cap-add=[]               Add Linux capabilities
   706        --cap-drop=[]              Drop Linux capabilities
   707        --cidfile=""               Write the container ID to the file
   708        --cpuset=""                CPUs in which to allow execution (0-3, 0,1)
   709        --device=[]                Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc:rwm)
   710        --dns=[]                   Set custom DNS servers
   711        --dns-search=[]            Set custom DNS search domains (Use --dns-search=. if you don't wish to set the search domain)
   712        -e, --env=[]               Set environment variables
   713        --entrypoint=""            Overwrite the default ENTRYPOINT of the image
   714        --env-file=[]              Read in a line delimited file of environment variables
   715        --expose=[]                Expose a port or a range of ports (e.g. --expose=3300-3310) from the container without publishing it to your host
   716        -h, --hostname=""          Container host name
   717        -i, --interactive=false    Keep STDIN open even if not attached
   718        --ipc=""                   Default is to create a private IPC namespace (POSIX SysV IPC) for the container
   719                                     'container:<name|id>': reuses another container shared memory, semaphores and message queues
   720                                     'host': use the host shared memory,semaphores and message queues inside the container.  Note: the host mode gives the container full access to local shared memory and is therefore considered insecure.
   721        --link=[]                  Add link to another container in the form of name:alias
   722        --lxc-conf=[]              (lxc exec-driver only) Add custom lxc options --lxc-conf="lxc.cgroup.cpuset.cpus = 0,1"
   723        -m, --memory=""            Memory limit (format: <number><optional unit>, where unit = b, k, m or g)
   724        --mac-address=""           Container MAC address (e.g. 92:d0:c6:0a:29:33)
   725        --name=""                  Assign a name to the container
   726        --net="bridge"             Set the Network mode for the container
   727                                     'bridge': creates a new network stack for the container on the docker bridge
   728                                     'none': no networking for this container
   729                                     'container:<name|id>': reuses another container network stack
   730                                     'host': use the host network stack inside the container.  Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure.
   731        -P, --publish-all=false    Publish all exposed ports to random ports on the host interfaces
   732        -p, --publish=[]           Publish a container's port, or a range of ports (e.g., `-p 3300-3310`), to the host
   733                                     format: ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort
   734                                     Both hostPort and containerPort can be specified as a range of ports. 
   735                                     When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. (e.g., `-p 1234-1236:1234-1236/tcp`)
   736                                     (use 'docker port' to see the actual mapping)
   737        --privileged=false         Give extended privileges to this container
   738        --restart=""               Restart policy to apply when a container exits (no, on-failure[:max-retry], always)
   739        --security-opt=[]          Security Options
   740        -t, --tty=false            Allocate a pseudo-TTY
   741        -u, --user=""              Username or UID
   742        -v, --volume=[]            Bind mount a volume (e.g., from the host: -v /host:/container, from Docker: -v /container)
   743        --volumes-from=[]          Mount volumes from the specified container(s)
   744        -w, --workdir=""           Working directory inside the container
   745  
   746  The `docker create` command creates a writeable container layer over
   747  the specified image and prepares it for running the specified command.
   748  The container ID is then printed to `STDOUT`.
   749  This is similar to `docker run -d` except the container is never started.
   750  You can then use the `docker start <container_id>` command to start the
   751  container at any point.
   752  
   753  This is useful when you want to set up a container configuration ahead
   754  of time so that it is ready to start when you need it.
   755  
   756  Note that volumes set by `create` may be over-ridden by options set with
   757  `start`.
   758  
   759  Please see the [run command](#run) section for more details.
   760  
   761  #### Examples
   762  
   763      $ sudo docker create -t -i fedora bash
   764      6d8af538ec541dd581ebc2a24153a28329acb5268abe5ef868c1f1a261221752
   765      $ sudo docker start -a -i 6d8af538ec5
   766      bash-4.2#
   767  
   768  As of v1.4.0 container volumes are initialized during the `docker create`
   769  phase (i.e., `docker run` too). For example, this allows you to `create` the
   770  `data` volume container, and then use it from another container:
   771  
   772      $ docker create -v /data --name data ubuntu
   773      240633dfbb98128fa77473d3d9018f6123b99c454b3251427ae190a7d951ad57
   774      $ docker run --rm --volumes-from data ubuntu ls -la /data
   775      total 8
   776      drwxr-xr-x  2 root root 4096 Dec  5 04:10 .
   777      drwxr-xr-x 48 root root 4096 Dec  5 04:11 ..
   778  
   779  Similarly, `create` a host directory bind mounted volume container, which
   780  can then be used from the subsequent container:
   781  
   782      $ docker create -v /home/docker:/docker --name docker ubuntu
   783      9aa88c08f319cd1e4515c3c46b0de7cc9aa75e878357b1e96f91e2c773029f03
   784      $ docker run --rm --volumes-from docker ubuntu ls -la /docker
   785      total 20
   786      drwxr-sr-x  5 1000 staff  180 Dec  5 04:00 .
   787      drwxr-xr-x 48 root root  4096 Dec  5 04:13 ..
   788      -rw-rw-r--  1 1000 staff 3833 Dec  5 04:01 .ash_history
   789      -rw-r--r--  1 1000 staff  446 Nov 28 11:51 .ashrc
   790      -rw-r--r--  1 1000 staff   25 Dec  5 04:00 .gitconfig
   791      drwxr-sr-x  3 1000 staff   60 Dec  1 03:28 .local
   792      -rw-r--r--  1 1000 staff  920 Nov 28 11:51 .profile
   793      drwx--S---  2 1000 staff  460 Dec  5 00:51 .ssh
   794      drwxr-xr-x 32 1000 staff 1140 Dec  5 04:01 docker
   795  
   796  
   797  ## diff
   798  
   799  List the changed files and directories in a container᾿s filesystem
   800  
   801      Usage: docker diff CONTAINER
   802  
   803      Inspect changes on a container's filesystem
   804  
   805  There are 3 events that are listed in the `diff`:
   806  
   807  1.  `A` - Add
   808  2.  `D` - Delete
   809  3.  `C` - Change
   810  
   811  For example:
   812  
   813      $ sudo docker diff 7bb0e258aefe
   814  
   815      C /dev
   816      A /dev/kmsg
   817      C /etc
   818      A /etc/mtab
   819      A /go
   820      A /go/src
   821      A /go/src/github.com
   822      A /go/src/github.com/docker
   823      A /go/src/github.com/docker/docker
   824      A /go/src/github.com/docker/docker/.git
   825      ....
   826  
   827  ## events
   828  
   829      Usage: docker events [OPTIONS]
   830  
   831      Get real time events from the server
   832  
   833        --since=""         Show all events created since timestamp
   834        --until=""         Stream events until this timestamp
   835  
   836  Docker containers will report the following events:
   837  
   838      create, destroy, die, export, kill, oom, pause, restart, start, stop, unpause
   839  
   840  and Docker images will report:
   841  
   842      untag, delete
   843  
   844  #### Filtering
   845  
   846  The filtering flag (`-f` or `--filter`) format is of "key=value". If you would like to use
   847  multiple filters, pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)
   848  
   849  Using the same filter multiple times will be handled as a *OR*; for example
   850  `--filter container=588a23dac085 --filter container=a8f7720b8c22` will display events for
   851  container 588a23dac085 *OR* container a8f7720b8c22
   852  
   853  Using multiple filters will be handled as a *AND*; for example
   854  `--filter container=588a23dac085 --filter event=start` will display events for container
   855  container 588a23dac085 *AND* the event type is *start*
   856  
   857  Current filters:
   858   * event
   859   * image
   860   * container
   861  
   862  #### Examples
   863  
   864  You'll need two shells for this example.
   865  
   866  **Shell 1: Listening for events:**
   867  
   868      $ sudo docker events
   869  
   870  **Shell 2: Start and Stop containers:**
   871  
   872      $ sudo docker start 4386fb97867d
   873      $ sudo docker stop 4386fb97867d
   874      $ sudo docker stop 7805c1d35632
   875  
   876  **Shell 1: (Again .. now showing events):**
   877  
   878      2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) start
   879      2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) die
   880      2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) stop
   881      2014-05-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) die
   882      2014-05-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) stop
   883  
   884  **Show events in the past from a specified time:**
   885  
   886      $ sudo docker events --since 1378216169
   887      2014-03-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) die
   888      2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) stop
   889      2014-05-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) die
   890      2014-03-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) stop
   891  
   892      $ sudo docker events --since '2013-09-03'
   893      2014-09-03T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) start
   894      2014-09-03T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) die
   895      2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) stop
   896      2014-05-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) die
   897      2014-09-03T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) stop
   898  
   899      $ sudo docker events --since '2013-09-03 15:49:29 +0200 CEST'
   900      2014-09-03T15:49:29.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) die
   901      2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) stop
   902      2014-05-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) die
   903      2014-09-03T15:49:29.999999999Z07:00 7805c1d35632: (from redis:2.8) stop
   904  
   905  **Filter events:**
   906  
   907      $ sudo docker events --filter 'event=stop'
   908      2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) stop
   909      2014-09-03T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) stop
   910  
   911      $ sudo docker events --filter 'image=ubuntu-1:14.04'
   912      2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) start
   913      2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) die
   914      2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) stop
   915  
   916      $ sudo docker events --filter 'container=7805c1d35632'
   917      2014-05-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) die
   918      2014-09-03T15:49:29.999999999Z07:00 7805c1d35632: (from redis:2.8) stop
   919  
   920      $ sudo docker events --filter 'container=7805c1d35632' --filter 'container=4386fb97867d'
   921      2014-09-03T15:49:29.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) die
   922      2014-05-10T17:42:14.999999999Z07:00 4386fb97867d: (from ubuntu-1:14.04) stop
   923      2014-05-10T17:42:14.999999999Z07:00 7805c1d35632: (from redis:2.8) die
   924      2014-09-03T15:49:29.999999999Z07:00 7805c1d35632: (from redis:2.8) stop
   925  
   926      $ sudo docker events --filter 'container=7805c1d35632' --filter 'event=stop'
   927      2014-09-03T15:49:29.999999999Z07:00 7805c1d35632: (from redis:2.8) stop
   928  
   929  ## exec
   930  
   931      Usage: docker exec [OPTIONS] CONTAINER COMMAND [ARG...]
   932  
   933      Run a command in a running container
   934  
   935        -d, --detach=false         Detached mode: run command in the background
   936        -i, --interactive=false    Keep STDIN open even if not attached
   937        -t, --tty=false            Allocate a pseudo-TTY
   938  
   939  The `docker exec` command runs a new command in a running container.
   940  
   941  The command started using `docker exec` will only run while the container's primary
   942  process (`PID 1`) is running, and will not be restarted if the container is restarted.
   943  
   944  If the container is paused, then the `docker exec` command will fail with an error:
   945  
   946      $ docker pause test
   947      test
   948      $ docker ps
   949      CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS                   PORTS               NAMES
   950      1ae3b36715d2        ubuntu:latest       "bash"              17 seconds ago      Up 16 seconds (Paused)                       test
   951      $ docker exec test ls
   952      FATA[0000] Error response from daemon: Container test is paused, unpause the container before exec
   953      $ echo $?
   954      1
   955  
   956  #### Examples
   957  
   958      $ sudo docker run --name ubuntu_bash --rm -i -t ubuntu bash
   959  
   960  This will create a container named `ubuntu_bash` and start a Bash session.
   961  
   962      $ sudo docker exec -d ubuntu_bash touch /tmp/execWorks
   963  
   964  This will create a new file `/tmp/execWorks` inside the running container
   965  `ubuntu_bash`, in the background.
   966  
   967      $ sudo docker exec -it ubuntu_bash bash
   968  
   969  This will create a new Bash session in the container `ubuntu_bash`.
   970  
   971  ## export
   972  
   973      Usage: docker export CONTAINER
   974  
   975      Export the contents of a filesystem as a tar archive to STDOUT
   976  
   977  For example:
   978  
   979      $ sudo docker export red_panda > latest.tar
   980  
   981  ## history
   982  
   983      Usage: docker history [OPTIONS] IMAGE
   984  
   985      Show the history of an image
   986  
   987        --no-trunc=false     Don't truncate output
   988        -q, --quiet=false    Only show numeric IDs
   989  
   990  To see how the `docker:latest` image was built:
   991  
   992      $ sudo docker history docker
   993      IMAGE                                                              CREATED             CREATED BY                                                                                                                                                 SIZE
   994      3e23a5875458790b7a806f95f7ec0d0b2a5c1659bfc899c89f939f6d5b8f7094   8 days ago          /bin/sh -c #(nop) ENV LC_ALL=C.UTF-8                                                                                                                       0 B
   995      8578938dd17054dce7993d21de79e96a037400e8d28e15e7290fea4f65128a36   8 days ago          /bin/sh -c dpkg-reconfigure locales &&    locale-gen C.UTF-8 &&    /usr/sbin/update-locale LANG=C.UTF-8                                                    1.245 MB
   996      be51b77efb42f67a5e96437b3e102f81e0a1399038f77bf28cea0ed23a65cf60   8 days ago          /bin/sh -c apt-get update && apt-get install -y    git    libxml2-dev    python    build-essential    make    gcc    python-dev    locales    python-pip   338.3 MB
   997      4b137612be55ca69776c7f30c2d2dd0aa2e7d72059820abf3e25b629f887a084   6 weeks ago         /bin/sh -c #(nop) ADD jessie.tar.xz in /                                                                                                                   121 MB
   998      750d58736b4b6cc0f9a9abe8f258cef269e3e9dceced1146503522be9f985ada   6 weeks ago         /bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -t jessie.tar.xz jessie http://http.debian.net/debian             0 B
   999      511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158   9 months ago                                                                                                                                                                   0 B
  1000  
  1001  ## images
  1002  
  1003      Usage: docker images [OPTIONS] [REPOSITORY]
  1004  
  1005      List images
  1006  
  1007        -a, --all=false      Show all images (by default filter out the intermediate image layers)
  1008        -f, --filter=[]      Provide filter values (i.e. 'dangling=true')
  1009        --no-trunc=false     Don't truncate output
  1010        -q, --quiet=false    Only show numeric IDs
  1011  
  1012  The default `docker images` will show all top level
  1013  images, their repository and tags, and their virtual size.
  1014  
  1015  Docker images have intermediate layers that increase reusability,
  1016  decrease disk usage, and speed up `docker build` by
  1017  allowing each step to be cached. These intermediate layers are not shown
  1018  by default.
  1019  
  1020  The `VIRTUAL SIZE` is the cumulative space taken up by the image and all
  1021  its parent images. This is also the disk space used by the contents of the
  1022  Tar file created when you `docker save` an image.
  1023  
  1024  An image will be listed more than once if it has multiple repository names
  1025  or tags. This single image (identifiable by its matching `IMAGE ID`)
  1026  uses up the `VIRTUAL SIZE` listed only once.
  1027  
  1028  #### Listing the most recently created images
  1029  
  1030      $ sudo docker images | head
  1031      REPOSITORY                TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
  1032      <none>                    <none>              77af4d6b9913        19 hours ago        1.089 GB
  1033      committ                   latest              b6fa739cedf5        19 hours ago        1.089 GB
  1034      <none>                    <none>              78a85c484f71        19 hours ago        1.089 GB
  1035      docker                    latest              30557a29d5ab        20 hours ago        1.089 GB
  1036      <none>                    <none>              5ed6274db6ce        24 hours ago        1.089 GB
  1037      postgres                  9                   746b819f315e        4 days ago          213.4 MB
  1038      postgres                  9.3                 746b819f315e        4 days ago          213.4 MB
  1039      postgres                  9.3.5               746b819f315e        4 days ago          213.4 MB
  1040      postgres                  latest              746b819f315e        4 days ago          213.4 MB
  1041  
  1042  
  1043  #### Listing the full length image IDs
  1044  
  1045      $ sudo docker images --no-trunc | head
  1046      REPOSITORY                    TAG                 IMAGE ID                                                           CREATED             VIRTUAL SIZE
  1047      <none>                        <none>              77af4d6b9913e693e8d0b4b294fa62ade6054e6b2f1ffb617ac955dd63fb0182   19 hours ago        1.089 GB
  1048      committest                    latest              b6fa739cedf5ea12a620a439402b6004d057da800f91c7524b5086a5e4749c9f   19 hours ago        1.089 GB
  1049      <none>                        <none>              78a85c484f71509adeaace20e72e941f6bdd2b25b4c75da8693efd9f61a37921   19 hours ago        1.089 GB
  1050      docker                        latest              30557a29d5abc51e5f1d5b472e79b7e296f595abcf19fe6b9199dbbc809c6ff4   20 hours ago        1.089 GB
  1051      <none>                        <none>              0124422dd9f9cf7ef15c0617cda3931ee68346455441d66ab8bdc5b05e9fdce5   20 hours ago        1.089 GB
  1052      <none>                        <none>              18ad6fad340262ac2a636efd98a6d1f0ea775ae3d45240d3418466495a19a81b   22 hours ago        1.082 GB
  1053      <none>                        <none>              f9f1e26352f0a3ba6a0ff68167559f64f3e21ff7ada60366e2d44a04befd1d3a   23 hours ago        1.089 GB
  1054      tryout                        latest              2629d1fa0b81b222fca63371ca16cbf6a0772d07759ff80e8d1369b926940074   23 hours ago        131.5 MB
  1055      <none>                        <none>              5ed6274db6ceb2397844896966ea239290555e74ef307030ebb01ff91b1914df   24 hours ago        1.089 GB
  1056  
  1057  #### Filtering
  1058  
  1059  The filtering flag (`-f` or `--filter`) format is of "key=value". If there is more
  1060  than one filter, then pass multiple flags (e.g., `--filter "foo=bar" --filter "bif=baz"`)
  1061  
  1062  Current filters:
  1063   * dangling (boolean - true or false)
  1064  
  1065  ##### Untagged images
  1066  
  1067      $ sudo docker images --filter "dangling=true"
  1068  
  1069      REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
  1070      <none>              <none>              8abc22fbb042        4 weeks ago         0 B
  1071      <none>              <none>              48e5f45168b9        4 weeks ago         2.489 MB
  1072      <none>              <none>              bf747efa0e2f        4 weeks ago         0 B
  1073      <none>              <none>              980fe10e5736        12 weeks ago        101.4 MB
  1074      <none>              <none>              dea752e4e117        12 weeks ago        101.4 MB
  1075      <none>              <none>              511136ea3c5a        8 months ago        0 B
  1076  
  1077  This will display untagged images, that are the leaves of the images tree (not
  1078  intermediary layers). These images occur when a new build of an image takes the
  1079  `repo:tag` away from the image ID, leaving it untagged. A warning will be issued
  1080  if trying to remove an image when a container is presently using it.
  1081  By having this flag it allows for batch cleanup.
  1082  
  1083  Ready for use by `docker rmi ...`, like:
  1084  
  1085      $ sudo docker rmi $(sudo docker images -f "dangling=true" -q)
  1086  
  1087      8abc22fbb042
  1088      48e5f45168b9
  1089      bf747efa0e2f
  1090      980fe10e5736
  1091      dea752e4e117
  1092      511136ea3c5a
  1093  
  1094  NOTE: Docker will warn you if any containers exist that are using these untagged images.
  1095  
  1096  ## import
  1097  
  1098      Usage: docker import URL|- [REPOSITORY[:TAG]]
  1099  
  1100      Create an empty filesystem image and import the contents of the tarball (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz) into it, then optionally tag it.
  1101  
  1102  URLs must start with `http` and point to a single file archive (.tar,
  1103  .tar.gz, .tgz, .bzip, .tar.xz, or .txz) containing a root filesystem. If
  1104  you would like to import from a local directory or archive, you can use
  1105  the `-` parameter to take the data from `STDIN`.
  1106  
  1107  #### Examples
  1108  
  1109  **Import from a remote location:**
  1110  
  1111  This will create a new untagged image.
  1112  
  1113      $ sudo docker import http://example.com/exampleimage.tgz
  1114  
  1115  **Import from a local file:**
  1116  
  1117  Import to docker via pipe and `STDIN`.
  1118  
  1119      $ cat exampleimage.tgz | sudo docker import - exampleimagelocal:new
  1120  
  1121  **Import from a local directory:**
  1122  
  1123      $ sudo tar -c . | sudo docker import - exampleimagedir
  1124  
  1125  Note the `sudo` in this example – you must preserve
  1126  the ownership of the files (especially root ownership) during the
  1127  archiving with tar. If you are not root (or the sudo command) when you
  1128  tar, then the ownerships might not get preserved.
  1129  
  1130  ## info
  1131  
  1132  
  1133      Usage: docker info
  1134  
  1135      Display system-wide information
  1136  
  1137  For example:
  1138  
  1139      $ sudo docker -D info
  1140      Containers: 14
  1141      Images: 52
  1142      Storage Driver: aufs
  1143       Root Dir: /var/lib/docker/aufs
  1144       Dirs: 545
  1145      Execution Driver: native-0.2
  1146      Kernel Version: 3.13.0-24-generic
  1147      Operating System: Ubuntu 14.04 LTS
  1148      CPUs: 1
  1149      Name: prod-server-42
  1150      ID: 7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS
  1151      Total Memory: 2 GiB
  1152      Debug mode (server): false
  1153      Debug mode (client): true
  1154      Fds: 10
  1155      Goroutines: 9
  1156      EventsListeners: 0
  1157      Init Path: /usr/bin/docker
  1158      Docker Root Dir: /var/lib/docker
  1159      Username: svendowideit
  1160      Registry: [https://index.docker.io/v1/]
  1161      Labels:
  1162       storage=ssd
  1163  
  1164  The global `-D` option tells all `docker` commands to output debug information.
  1165  
  1166  When sending issue reports, please use `docker version` and `docker -D info` to
  1167  ensure we know how your setup is configured.
  1168  
  1169  ## inspect
  1170  
  1171      Usage: docker inspect [OPTIONS] CONTAINER|IMAGE [CONTAINER|IMAGE...]
  1172  
  1173      Return low-level information on a container or image
  1174  
  1175        -f, --format=""    Format the output using the given go template.
  1176  
  1177  By default, this will render all results in a JSON array. If a format is
  1178  specified, the given template will be executed for each result.
  1179  
  1180  Go's [text/template](http://golang.org/pkg/text/template/) package
  1181  describes all the details of the format.
  1182  
  1183  #### Examples
  1184  
  1185  **Get an instance's IP address:**
  1186  
  1187  For the most part, you can pick out any field from the JSON in a fairly
  1188  straightforward manner.
  1189  
  1190      $ sudo docker inspect --format='{{.NetworkSettings.IPAddress}}' $INSTANCE_ID
  1191  
  1192  **Get an instance's MAC Address:**
  1193  
  1194  For the most part, you can pick out any field from the JSON in a fairly
  1195  straightforward manner.
  1196  
  1197      $ sudo docker inspect --format='{{.NetworkSettings.MacAddress}}' $INSTANCE_ID
  1198  
  1199  **List All Port Bindings:**
  1200  
  1201  One can loop over arrays and maps in the results to produce simple text
  1202  output:
  1203  
  1204      $ sudo docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}} {{$p}} -> {{(index $conf 0).HostPort}} {{end}}' $INSTANCE_ID
  1205  
  1206  **Find a Specific Port Mapping:**
  1207  
  1208  The `.Field` syntax doesn't work when the field name begins with a
  1209  number, but the template language's `index` function does. The
  1210  `.NetworkSettings.Ports` section contains a map of the internal port
  1211  mappings to a list of external address/port objects, so to grab just the
  1212  numeric public port, you use `index` to find the specific port map, and
  1213  then `index` 0 contains the first object inside of that. Then we ask for
  1214  the `HostPort` field to get the public address.
  1215  
  1216      $ sudo docker inspect --format='{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}' $INSTANCE_ID
  1217  
  1218  **Get config:**
  1219  
  1220  The `.Field` syntax doesn't work when the field contains JSON data, but
  1221  the template language's custom `json` function does. The `.config`
  1222  section contains complex JSON object, so to grab it as JSON, you use
  1223  `json` to convert the configuration object into JSON.
  1224  
  1225      $ sudo docker inspect --format='{{json .config}}' $INSTANCE_ID
  1226  
  1227  ## kill
  1228  
  1229      Usage: docker kill [OPTIONS] CONTAINER [CONTAINER...]
  1230  
  1231      Kill a running container using SIGKILL or a specified signal
  1232  
  1233        -s, --signal="KILL"    Signal to send to the container
  1234  
  1235  The main process inside the container will be sent `SIGKILL`, or any
  1236  signal specified with option `--signal`.
  1237  
  1238  ## load
  1239  
  1240      Usage: docker load [OPTIONS]
  1241  
  1242      Load an image from a tar archive on STDIN
  1243  
  1244        -i, --input=""     Read from a tar archive file, instead of STDIN
  1245  
  1246  Loads a tarred repository from a file or the standard input stream.
  1247  Restores both images and tags.
  1248  
  1249      $ sudo docker images
  1250      REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
  1251      $ sudo docker load < busybox.tar
  1252      $ sudo docker images
  1253      REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
  1254      busybox             latest              769b9341d937        7 weeks ago         2.489 MB
  1255      $ sudo docker load --input fedora.tar
  1256      $ sudo docker images
  1257      REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
  1258      busybox             latest              769b9341d937        7 weeks ago         2.489 MB
  1259      fedora              rawhide             0d20aec6529d        7 weeks ago         387 MB
  1260      fedora              20                  58394af37342        7 weeks ago         385.5 MB
  1261      fedora              heisenbug           58394af37342        7 weeks ago         385.5 MB
  1262      fedora              latest              58394af37342        7 weeks ago         385.5 MB
  1263  
  1264  ## login
  1265  
  1266      Usage: docker login [OPTIONS] [SERVER]
  1267  
  1268      Register or log in to a Docker registry server, if no server is specified "https://index.docker.io/v1/" is the default.
  1269  
  1270        -e, --email=""       Email
  1271        -p, --password=""    Password
  1272        -u, --username=""    Username
  1273  
  1274  If you want to login to a self-hosted registry you can specify this by
  1275  adding the server name.
  1276  
  1277      example:
  1278      $ sudo docker login localhost:8080
  1279  
  1280  ## logout
  1281  
  1282      Usage: docker logout [SERVER]
  1283  
  1284      Log out from a Docker registry, if no server is specified "https://index.docker.io/v1/" is the default.
  1285  
  1286  For example:
  1287  
  1288      $ sudo docker logout localhost:8080
  1289  
  1290  ## logs
  1291  
  1292      Usage: docker logs [OPTIONS] CONTAINER
  1293  
  1294      Fetch the logs of a container
  1295  
  1296        -f, --follow=false        Follow log output
  1297        -t, --timestamps=false    Show timestamps
  1298        --tail="all"              Output the specified number of lines at the end of logs (defaults to all logs)
  1299  
  1300  The `docker logs` command batch-retrieves logs present at the time of execution.
  1301  
  1302  The `docker logs --follow` command will continue streaming the new output from
  1303  the container's `STDOUT` and `STDERR`.
  1304  
  1305  Passing a negative number or a non-integer to `--tail` is invalid and the
  1306  value is set to `all` in that case. This behavior may change in the future.
  1307  
  1308  The `docker logs --timestamp` commands will add an RFC3339Nano
  1309  timestamp, for example `2014-09-16T06:17:46.000000000Z`, to each
  1310  log entry. To ensure that the timestamps for are aligned the
  1311  nano-second part of the timestamp will be padded with zero when necessary.
  1312  
  1313  ## port
  1314  
  1315      Usage: docker port CONTAINER [PRIVATE_PORT[/PROTO]]
  1316  
  1317      List port mappings for the CONTAINER, or lookup the public-facing port that is NAT-ed to the PRIVATE_PORT
  1318  
  1319  You can find out all the ports mapped by not specifying a `PRIVATE_PORT`, or
  1320  just a specific mapping:
  1321  
  1322      $ sudo docker ps test
  1323      CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS                                            NAMES
  1324      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
  1325      $ sudo docker port test
  1326      7890/tcp -> 0.0.0.0:4321
  1327      9876/tcp -> 0.0.0.0:1234
  1328      $ sudo docker port test 7890/tcp
  1329      0.0.0.0:4321
  1330      $ sudo docker port test 7890/udp
  1331      2014/06/24 11:53:36 Error: No public port '7890/udp' published for test
  1332      $ sudo docker port test 7890
  1333      0.0.0.0:4321
  1334  
  1335  ## pause
  1336  
  1337      Usage: docker pause CONTAINER
  1338  
  1339      Pause all processes within a container
  1340  
  1341  The `docker pause` command uses the cgroups freezer to suspend all processes in
  1342  a container.  Traditionally when suspending a process the `SIGSTOP` signal is
  1343  used, which is observable by the process being suspended. With the cgroups freezer
  1344  the process is unaware, and unable to capture, that it is being suspended,
  1345  and subsequently resumed.
  1346  
  1347  See the
  1348  [cgroups freezer documentation](https://www.kernel.org/doc/Documentation/cgroups/freezer-subsystem.txt)
  1349  for further details.
  1350  
  1351  ## ps
  1352  
  1353      Usage: docker ps [OPTIONS]
  1354  
  1355      List containers
  1356  
  1357        -a, --all=false       Show all containers. Only running containers are shown by default.
  1358        --before=""           Show only container created before Id or Name, include non-running ones.
  1359        -f, --filter=[]       Provide filter values. Valid filters:
  1360                                exited=<int> - containers with exit code of <int>
  1361                                status=(restarting|running|paused|exited)
  1362        -l, --latest=false    Show only the latest created container, include non-running ones.
  1363        -n=-1                 Show n last created containers, include non-running ones.
  1364        --no-trunc=false      Don't truncate output
  1365        -q, --quiet=false     Only display numeric IDs
  1366        -s, --size=false      Display total file sizes
  1367        --since=""            Show only containers created since Id or Name, include non-running ones.
  1368  
  1369  Running `docker ps` showing 2 linked containers.
  1370  
  1371      $ sudo docker ps
  1372      CONTAINER ID        IMAGE                        COMMAND                CREATED              STATUS              PORTS               NAMES
  1373      4c01db0b339c        ubuntu:12.04                 bash                   17 seconds ago       Up 16 seconds                           webapp
  1374      d7886598dbe2        crosbymichael/redis:latest   /redis-server --dir    33 minutes ago       Up 33 minutes       6379/tcp            redis,webapp/db
  1375  
  1376  `docker ps` will show only running containers by default. To see all containers:
  1377  `docker ps -a`
  1378  
  1379  #### Filtering
  1380  
  1381  The filtering flag (`-f` or `--filter)` format is a `key=value` pair. If there is more
  1382  than one filter, then pass multiple flags (e.g. `--filter "foo=bar" --filter "bif=baz"`)
  1383  
  1384  Current filters:
  1385   * exited (int - the code of exited containers. Only useful with '--all')
  1386   * status (restarting|running|paused|exited)
  1387  
  1388  ##### Successfully exited containers
  1389  
  1390      $ sudo docker ps -a --filter 'exited=0'
  1391      CONTAINER ID        IMAGE             COMMAND                CREATED             STATUS                   PORTS                      NAMES
  1392      ea09c3c82f6e        registry:latest   /srv/run.sh            2 weeks ago         Exited (0) 2 weeks ago   127.0.0.1:5000->5000/tcp   desperate_leakey
  1393      106ea823fe4e        fedora:latest     /bin/sh -c 'bash -l'   2 weeks ago         Exited (0) 2 weeks ago                              determined_albattani
  1394      48ee228c9464        fedora:20         bash                   2 weeks ago         Exited (0) 2 weeks ago                              tender_torvalds
  1395  
  1396  This shows all the containers that have exited with status of '0'
  1397  
  1398  ## pull
  1399  
  1400      Usage: docker pull [OPTIONS] NAME[:TAG]
  1401  
  1402      Pull an image or a repository from the registry
  1403  
  1404        -a, --all-tags=false    Download all tagged images in the repository
  1405  
  1406  Most of your images will be created on top of a base image from the
  1407  [Docker Hub](https://hub.docker.com) registry.
  1408  
  1409  [Docker Hub](https://hub.docker.com) contains many pre-built images that you
  1410  can `pull` and try without needing to define and configure your own.
  1411  
  1412  It is also possible to manually specify the path of a registry to pull from.
  1413  For example, if you have set up a local registry, you can specify its path to
  1414  pull from it. A repository path is similar to a URL, but does not contain
  1415  a protocol specifier (`https://`, for example).
  1416  
  1417  To download a particular image, or set of images (i.e., a repository),
  1418  use `docker pull`:
  1419  
  1420      $ sudo docker pull debian
  1421      # will pull the debian:latest image, its intermediate layers
  1422      # and any aliases of the same id
  1423      $ sudo docker pull debian:testing
  1424      # will pull the image named debian:testing and any intermediate
  1425      # layers it is based on.
  1426      # (Typically the empty `scratch` image, a MAINTAINER layer,
  1427      # and the un-tarred base).
  1428      $ sudo docker pull --all-tags centos
  1429      # will pull all the images from the centos repository
  1430      $ sudo docker pull registry.hub.docker.com/debian
  1431      # manually specifies the path to the default Docker registry. This could
  1432      # be replaced with the path to a local registry to pull from another source.
  1433  
  1434  ## push
  1435  
  1436      Usage: docker push NAME[:TAG]
  1437  
  1438      Push an image or a repository to the registry
  1439  
  1440  Use `docker push` to share your images to the [Docker Hub](https://hub.docker.com)
  1441  registry or to a self-hosted one.
  1442  
  1443  ## restart
  1444  
  1445      Usage: docker restart [OPTIONS] CONTAINER [CONTAINER...]
  1446  
  1447      Restart a running container
  1448  
  1449        -t, --time=10      Number of seconds to try to stop for before killing the container. Once killed it will then be restarted. Default is 10 seconds.
  1450  
  1451  ## rm
  1452  
  1453      Usage: docker rm [OPTIONS] CONTAINER [CONTAINER...]
  1454  
  1455      Remove one or more containers
  1456  
  1457        -f, --force=false      Force the removal of a running container (uses SIGKILL)
  1458        -l, --link=false       Remove the specified link and not the underlying container
  1459        -v, --volumes=false    Remove the volumes associated with the container
  1460  
  1461  #### Examples
  1462  
  1463      $ sudo docker rm /redis
  1464      /redis
  1465  
  1466  This will remove the container referenced under the link
  1467  `/redis`.
  1468  
  1469      $ sudo docker rm --link /webapp/redis
  1470      /webapp/redis
  1471  
  1472  This will remove the underlying link between `/webapp` and the `/redis`
  1473  containers removing all network communication.
  1474  
  1475      $ sudo docker rm --force redis
  1476      redis
  1477  
  1478  The main process inside the container referenced under the link `/redis` will receive
  1479  `SIGKILL`, then the container will be removed.
  1480  
  1481  This command will delete all stopped containers. The command `docker ps
  1482  -a -q` will return all existing container IDs and pass them to the `rm`
  1483  command which will delete them. Any running containers will not be
  1484  deleted.
  1485  
  1486  ## rmi
  1487  
  1488      Usage: docker rmi [OPTIONS] IMAGE [IMAGE...]
  1489  
  1490      Remove one or more images
  1491  
  1492        -f, --force=false    Force removal of the image
  1493        --no-prune=false     Do not delete untagged parents
  1494  
  1495  #### Removing tagged images
  1496  
  1497  Images can be removed either by their short or long IDs, or their image
  1498  names. If an image has more than one name, each of them needs to be
  1499  removed before the image is removed.
  1500  
  1501      $ sudo docker images
  1502      REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
  1503      test1                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
  1504      test                      latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
  1505      test2                     latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
  1506  
  1507      $ sudo docker rmi fd484f19954f
  1508      Error: Conflict, cannot delete image fd484f19954f because it is tagged in multiple repositories
  1509      2013/12/11 05:47:16 Error: failed to remove one or more images
  1510  
  1511      $ sudo docker rmi test1
  1512      Untagged: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
  1513      $ sudo docker rmi test2
  1514      Untagged: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
  1515  
  1516      $ sudo docker images
  1517      REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
  1518      test                      latest              fd484f19954f        23 seconds ago      7 B (virtual 4.964 MB)
  1519      $ sudo docker rmi test
  1520      Untagged: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
  1521      Deleted: fd484f19954f4920da7ff372b5067f5b7ddb2fd3830cecd17b96ea9e286ba5b8
  1522  
  1523  ## run
  1524  
  1525      Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
  1526  
  1527      Run a command in a new container
  1528  
  1529        -a, --attach=[]            Attach to STDIN, STDOUT or STDERR.
  1530        --add-host=[]              Add a custom host-to-IP mapping (host:ip)
  1531        -c, --cpu-shares=0         CPU shares (relative weight)
  1532        --cap-add=[]               Add Linux capabilities
  1533        --cap-drop=[]              Drop Linux capabilities
  1534        --cidfile=""               Write the container ID to the file
  1535        --cpuset=""                CPUs in which to allow execution (0-3, 0,1)
  1536        -d, --detach=false         Detached mode: run the container in the background and print the new container ID
  1537        --device=[]                Add a host device to the container (e.g. --device=/dev/sdc:/dev/xvdc:rwm)
  1538        --dns=[]                   Set custom DNS servers
  1539        --dns-search=[]            Set custom DNS search domains (Use --dns-search=. if you don't wish to set the search domain)
  1540        -e, --env=[]               Set environment variables
  1541        --entrypoint=""            Overwrite the default ENTRYPOINT of the image
  1542        --env-file=[]              Read in a line delimited file of environment variables
  1543        --expose=[]                Expose a port or a range of ports (e.g. --expose=3300-3310) from the container without publishing it to your host
  1544        -h, --hostname=""          Container host name
  1545        -i, --interactive=false    Keep STDIN open even if not attached
  1546        --ipc=""                   Default is to create a private IPC namespace (POSIX SysV IPC) for the container
  1547                                     'container:<name|id>': reuses another container shared memory, semaphores and message queues
  1548                                     'host': use the host shared memory,semaphores and message queues inside the container.  Note: the host mode gives the container full access to local shared memory and is therefore considered insecure.
  1549        --link=[]                  Add link to another container in the form of name:alias
  1550        --lxc-conf=[]              (lxc exec-driver only) Add custom lxc options --lxc-conf="lxc.cgroup.cpuset.cpus = 0,1"
  1551        -m, --memory=""            Memory limit (format: <number><optional unit>, where unit = b, k, m or g)
  1552        --mac-address=""           Container MAC address (e.g. 92:d0:c6:0a:29:33)
  1553        --name=""                  Assign a name to the container
  1554        --net="bridge"             Set the Network mode for the container
  1555                                     'bridge': creates a new network stack for the container on the docker bridge
  1556                                     'none': no networking for this container
  1557                                     'container:<name|id>': reuses another container network stack
  1558                                     'host': use the host network stack inside the container.  Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure.
  1559        -P, --publish-all=false    Publish all exposed ports to random ports on the host interfaces
  1560        -p, --publish=[]           Publish a container's port to the host
  1561                                     format: ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort
  1562                                     Both hostPort and containerPort can be specified as a range of ports. 
  1563                                     When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. (e.g., `-p 1234-1236:1234-1236/tcp`)
  1564                                     (use 'docker port' to see the actual mapping)
  1565        --privileged=false         Give extended privileges to this container
  1566        --restart=""               Restart policy to apply when a container exits (no, on-failure[:max-retry], always)
  1567        --rm=false                 Automatically remove the container when it exits (incompatible with -d)
  1568        --security-opt=[]          Security Options
  1569        --sig-proxy=true           Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied.
  1570        -t, --tty=false            Allocate a pseudo-TTY
  1571        -u, --user=""              Username or UID
  1572        -v, --volume=[]            Bind mount a volume (e.g., from the host: -v /host:/container, from Docker: -v /container)
  1573        --volumes-from=[]          Mount volumes from the specified container(s)
  1574        -w, --workdir=""           Working directory inside the container
  1575  
  1576  The `docker run` command first `creates` a writeable container layer over the
  1577  specified image, and then `starts` it using the specified command. That is,
  1578  `docker run` is equivalent to the API `/containers/create` then
  1579  `/containers/(id)/start`. A stopped container can be restarted with all its
  1580  previous changes intact using `docker start`. See `docker ps -a` to view a list
  1581  of all containers.
  1582  
  1583  There is detailed information about `docker run` in the [Docker run reference](
  1584  /reference/run/).
  1585  
  1586  The `docker run` command can be used in combination with `docker commit` to
  1587  [*change the command that a container runs*](#commit-an-existing-container).
  1588  
  1589  See the [Docker User Guide](/userguide/dockerlinks/) for more detailed
  1590  information about the `--expose`, `-p`, `-P` and `--link` parameters,
  1591  and linking containers.
  1592  
  1593  #### Examples
  1594  
  1595      $ sudo docker run --cidfile /tmp/docker_test.cid ubuntu echo "test"
  1596  
  1597  This will create a container and print `test` to the console. The `cidfile`
  1598  flag makes Docker attempt to create a new file and write the container ID to it.
  1599  If the file exists already, Docker will return an error. Docker will close this
  1600  file when `docker run` exits.
  1601  
  1602      $ sudo docker run -t -i --rm ubuntu bash
  1603      root@bc338942ef20:/# mount -t tmpfs none /mnt
  1604      mount: permission denied
  1605  
  1606  This will *not* work, because by default, most potentially dangerous kernel
  1607  capabilities are dropped; including `cap_sys_admin` (which is required to mount
  1608  filesystems). However, the `--privileged` flag will allow it to run:
  1609  
  1610      $ sudo docker run --privileged ubuntu bash
  1611      root@50e3f57e16e6:/# mount -t tmpfs none /mnt
  1612      root@50e3f57e16e6:/# df -h
  1613      Filesystem      Size  Used Avail Use% Mounted on
  1614      none            1.9G     0  1.9G   0% /mnt
  1615  
  1616  The `--privileged` flag gives *all* capabilities to the container, and it also
  1617  lifts all the limitations enforced by the `device` cgroup controller. In other
  1618  words, the container can then do almost everything that the host can do. This
  1619  flag exists to allow special use-cases, like running Docker within Docker.
  1620  
  1621      $ sudo docker  run -w /path/to/dir/ -i -t  ubuntu pwd
  1622  
  1623  The `-w` lets the command being executed inside directory given, here
  1624  `/path/to/dir/`. If the path does not exists it is created inside the container.
  1625  
  1626      $ sudo docker  run  -v `pwd`:`pwd` -w `pwd` -i -t  ubuntu pwd
  1627  
  1628  The `-v` flag mounts the current working directory into the container. The `-w`
  1629  lets the command being executed inside the current working directory, by
  1630  changing into the directory to the value returned by `pwd`. So this
  1631  combination executes the command using the container, but inside the
  1632  current working directory.
  1633  
  1634      $ sudo docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash
  1635  
  1636  When the host directory of a bind-mounted volume doesn't exist, Docker
  1637  will automatically create this directory on the host for you. In the
  1638  example above, Docker will create the `/doesnt/exist`
  1639  folder before starting your container.
  1640  
  1641      $ sudo docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v ./static-docker:/usr/bin/docker busybox sh
  1642  
  1643  By bind-mounting the docker unix socket and statically linked docker
  1644  binary (such as that provided by [https://get.docker.com](
  1645  https://get.docker.com)), you give the container the full access to create and
  1646  manipulate the host's Docker daemon.
  1647  
  1648      $ sudo docker run -p 127.0.0.1:80:8080 ubuntu bash
  1649  
  1650  This binds port `8080` of the container to port `80` on `127.0.0.1` of
  1651  the host machine. The [Docker User Guide](/userguide/dockerlinks/)
  1652  explains in detail how to manipulate ports in Docker.
  1653  
  1654      $ sudo docker run --expose 80 ubuntu bash
  1655  
  1656  This exposes port `80` of the container for use within a link without
  1657  publishing the port to the host system's interfaces. The [Docker User
  1658  Guide](/userguide/dockerlinks) explains in detail how to manipulate
  1659  ports in Docker.
  1660  
  1661      $ sudo docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash
  1662  
  1663  This sets environmental variables in the container. For illustration all three
  1664  flags are shown here. Where `-e`, `--env` take an environment variable and
  1665  value, or if no "=" is provided, then that variable's current value is passed
  1666  through (i.e. `$MYVAR1` from the host is set to `$MYVAR1` in the container). All
  1667  three flags, `-e`, `--env` and `--env-file` can be repeated.
  1668  
  1669  Regardless of the order of these three flags, the `--env-file` are processed
  1670  first, and then `-e`, `--env` flags. This way, the `-e` or `--env` will
  1671  override variables as needed.
  1672  
  1673      $ cat ./env.list
  1674      TEST_FOO=BAR
  1675      $ sudo docker run --env TEST_FOO="This is a test" --env-file ./env.list busybox env | grep TEST_FOO
  1676      TEST_FOO=This is a test
  1677  
  1678  The `--env-file` flag takes a filename as an argument and expects each line
  1679  to be in the `VAR=VAL` format, mimicking the argument passed to `--env`. Comment
  1680  lines need only be prefixed with `#`
  1681  
  1682  An example of a file passed with `--env-file`
  1683  
  1684      $ cat ./env.list
  1685      TEST_FOO=BAR
  1686  
  1687      # this is a comment
  1688      TEST_APP_DEST_HOST=10.10.0.127
  1689      TEST_APP_DEST_PORT=8888
  1690  
  1691      # pass through this variable from the caller
  1692      TEST_PASSTHROUGH
  1693      $ sudo TEST_PASSTHROUGH=howdy docker run --env-file ./env.list busybox env
  1694      HOME=/
  1695      PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
  1696      HOSTNAME=5198e0745561
  1697      TEST_FOO=BAR
  1698      TEST_APP_DEST_HOST=10.10.0.127
  1699      TEST_APP_DEST_PORT=8888
  1700      TEST_PASSTHROUGH=howdy
  1701  
  1702      $ sudo docker run --name console -t -i ubuntu bash
  1703  
  1704  This will create and run a new container with the container name being
  1705  `console`.
  1706  
  1707      $ sudo docker run --link /redis:redis --name console ubuntu bash
  1708  
  1709  The `--link` flag will link the container named `/redis` into the newly
  1710  created container with the alias `redis`. The new container can access the
  1711  network and environment of the `redis` container via environment variables.
  1712  The `--name` flag will assign the name `console` to the newly created
  1713  container.
  1714  
  1715      $ sudo docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd
  1716  
  1717  The `--volumes-from` flag mounts all the defined volumes from the referenced
  1718  containers. Containers can be specified by repetitions of the `--volumes-from`
  1719  argument. The container ID may be optionally suffixed with `:ro` or `:rw` to
  1720  mount the volumes in read-only or read-write mode, respectively. By default,
  1721  the volumes are mounted in the same mode (read write or read only) as
  1722  the reference container.
  1723  
  1724  The `-a` flag tells `docker run` to bind to the container's `STDIN`, `STDOUT` or
  1725  `STDERR`. This makes it possible to manipulate the output and input as needed.
  1726  
  1727      $ echo "test" | sudo docker run -i -a stdin ubuntu cat -
  1728  
  1729  This pipes data into a container and prints the container's ID by attaching
  1730  only to the container's `STDIN`.
  1731  
  1732      $ sudo docker run -a stderr ubuntu echo test
  1733  
  1734  This isn't going to print anything unless there's an error because we've
  1735  only attached to the `STDERR` of the container. The container's logs
  1736  still store what's been written to `STDERR` and `STDOUT`.
  1737  
  1738      $ cat somefile | sudo docker run -i -a stdin mybuilder dobuild
  1739  
  1740  This is how piping a file into a container could be done for a build.
  1741  The container's ID will be printed after the build is done and the build
  1742  logs could be retrieved using `docker logs`. This is
  1743  useful if you need to pipe a file or something else into a container and
  1744  retrieve the container's ID once the container has finished running.
  1745  
  1746     $ sudo docker run --device=/dev/sdc:/dev/xvdc --device=/dev/sdd --device=/dev/zero:/dev/nulo -i -t ubuntu ls -l /dev/{xvdc,sdd,nulo}
  1747     brw-rw---- 1 root disk 8, 2 Feb  9 16:05 /dev/xvdc
  1748     brw-rw---- 1 root disk 8, 3 Feb  9 16:05 /dev/sdd
  1749     crw-rw-rw- 1 root root 1, 5 Feb  9 16:05 /dev/nulo
  1750  
  1751  It is often necessary to directly expose devices to a container. The `--device`
  1752  option enables that.  For example, a specific block storage device or loop
  1753  device or audio device can be added to an otherwise unprivileged container
  1754  (without the `--privileged` flag) and have the application directly access it.
  1755  
  1756  By default, the container will be able to `read`, `write` and `mknod` these devices.
  1757  This can be overridden using a third `:rwm` set of options to each `--device`
  1758  flag:
  1759  
  1760  
  1761  ```
  1762  	$ sudo docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk  /dev/xvdc
  1763  
  1764  	Command (m for help): q
  1765  	$ sudo docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk  /dev/xvdc
  1766  	You will not be able to write the partition table.
  1767  
  1768  	Command (m for help): q
  1769  
  1770  	$ sudo docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk  /dev/xvdc
  1771  
  1772  	Command (m for help): q
  1773  
  1774  	$ sudo docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk  /dev/xvdc
  1775  	fdisk: unable to open /dev/xvdc: Operation not permitted
  1776  ```
  1777  
  1778  **Note:**
  1779  > `--device` cannot be safely used with ephemeral devices. Block devices that
  1780  > may be removed should not be added to untrusted containers with `--device`.
  1781  
  1782  **A complete example:**
  1783  
  1784      $ sudo docker run -d --name static static-web-files sh
  1785      $ sudo docker run -d --expose=8098 --name riak riakserver
  1786      $ sudo docker run -d -m 100m -e DEVELOPMENT=1 -e BRANCH=example-code -v $(pwd):/app/bin:ro --name app appserver
  1787      $ sudo 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
  1788      $ sudo docker run -t -i --rm --volumes-from web -w /var/log/httpd busybox tail -f access.log
  1789  
  1790  This example shows five containers that might be set up to test a web
  1791  application change:
  1792  
  1793  1. Start a pre-prepared volume image `static-web-files` (in the background)
  1794     that has CSS, image and static HTML in it, (with a `VOLUME` instruction in
  1795     the Dockerfile to allow the web server to use those files);
  1796  2. Start a pre-prepared `riakserver` image, give the container name `riak` and
  1797     expose port `8098` to any containers that link to it;
  1798  3. Start the `appserver` image, restricting its memory usage to 100MB, setting
  1799     two environment variables `DEVELOPMENT` and `BRANCH` and bind-mounting the
  1800     current directory (`$(pwd)`) in the container in read-only mode as `/app/bin`;
  1801  4. Start the `webserver`, mapping port `443` in the container to port `1443` on
  1802     the Docker server, setting the DNS server to `10.0.0.1` and DNS search
  1803     domain to `dev.org`, creating a volume to put the log files into (so we can
  1804     access it from another container), then importing the files from the volume
  1805     exposed by the `static` container, and linking to all exposed ports from
  1806     `riak` and `app`. Lastly, we set the hostname to `web.sven.dev.org` so its
  1807     consistent with the pre-generated SSL certificate;
  1808  5. Finally, we create a container that runs `tail -f access.log` using the logs
  1809     volume from the `web` container, setting the workdir to `/var/log/httpd`. The
  1810     `--rm` option means that when the container exits, the container's layer is
  1811     removed.
  1812  
  1813  #### Restart Policies
  1814  
  1815  Using the `--restart` flag on Docker run you can specify a restart policy for
  1816  how a container should or should not be restarted on exit.
  1817  
  1818  An ever increasing delay (double the previous delay, starting at 100 milliseconds)
  1819  is added before each restart to prevent flooding the server. This means the daemaon
  1820  will wait for 100 mS, then 200 mS, 400, 800, 1600, and so on until either the
  1821  `on-failure` limit is hit, or when you `docker stop` or even `docker rm -f`
  1822  the container.
  1823  
  1824  When a restart policy is active on a container, it will be shown in `docker ps`
  1825  as either `Up` or `Restarting` in `docker ps`. It can also be useful to use
  1826  `docker events` to see the restart policy in effect.
  1827  
  1828  ** no ** - Do not restart the container when it exits.
  1829  
  1830  ** on-failure ** - Restart the container only if it exits with a non zero exit status.
  1831  
  1832  ** always ** - Always restart the container regardless of the exit status.
  1833  
  1834  You can also specify the maximum amount of times Docker will try to
  1835  restart the container when using the ** on-failure ** policy.  The
  1836  default is that Docker will try forever to restart the container.
  1837  
  1838      $ sudo docker run --restart=always redis
  1839  
  1840  This will run the `redis` container with a restart policy of ** always ** so that if
  1841  the container exits, Docker will restart it.
  1842  
  1843      $ sudo docker run --restart=on-failure:10 redis
  1844  
  1845  This will run the `redis` container with a restart policy of **
  1846  on-failure ** and a maximum restart count of 10.  If the `redis`
  1847  container exits with a non-zero exit status more than 10 times in a row
  1848  Docker will abort trying to restart the container.  Providing a maximum
  1849  restart limit is only valid for the ** on-failure ** policy.
  1850  
  1851  ### Adding entries to a container hosts file
  1852  
  1853  You can add other hosts into a container's `/etc/hosts` file by using one or more
  1854  `--add-host` flags. This example adds a static address for a host named `docker`:
  1855  
  1856  ```
  1857      $ docker run --add-host=docker:10.180.0.1 --rm -it debian
  1858      $$ ping docker
  1859      PING docker (10.180.0.1): 48 data bytes
  1860      56 bytes from 10.180.0.1: icmp_seq=0 ttl=254 time=7.600 ms
  1861      56 bytes from 10.180.0.1: icmp_seq=1 ttl=254 time=30.705 ms
  1862      ^C--- docker ping statistics ---
  1863      2 packets transmitted, 2 packets received, 0% packet loss
  1864      round-trip min/avg/max/stddev = 7.600/19.152/30.705/11.553 ms
  1865  ```
  1866  
  1867  > **Note:**
  1868  > Sometimes you need to connect to the Docker host, which means getting the IP
  1869  > address of the host. You can use the following shell commands to simplify this
  1870  > process:
  1871  >
  1872  >      $ alias hostip="ip route show 0.0.0.0/0 | grep -Eo 'via \S+' | awk '{ print \$2 }'"
  1873  >      $ docker run  --add-host=docker:$(hostip) --rm -it debian
  1874  
  1875  ## save
  1876  
  1877      Usage: docker save [OPTIONS] IMAGE [IMAGE...]
  1878  
  1879      Save an image(s) to a tar archive (streamed to STDOUT by default)
  1880  
  1881        -o, --output=""    Write to a file, instead of STDOUT
  1882  
  1883  Produces a tarred repository to the standard output stream.
  1884  Contains all parent layers, and all tags + versions, or specified `repo:tag`, for
  1885  each argument provided.
  1886  
  1887  It is used to create a backup that can then be used with `docker load`
  1888  
  1889      $ sudo docker save busybox > busybox.tar
  1890      $ ls -sh busybox.tar
  1891      2.7M busybox.tar
  1892      $ sudo docker save --output busybox.tar busybox
  1893      $ ls -sh busybox.tar
  1894      2.7M busybox.tar
  1895      $ sudo docker save -o fedora-all.tar fedora
  1896      $ sudo docker save -o fedora-latest.tar fedora:latest
  1897  
  1898  It is even useful to cherry-pick particular tags of an image repository
  1899  
  1900     $ sudo docker save -o ubuntu.tar ubuntu:lucid ubuntu:saucy
  1901  
  1902  ## search
  1903  
  1904  Search [Docker Hub](https://hub.docker.com) for images
  1905  
  1906      Usage: docker search [OPTIONS] TERM
  1907  
  1908      Search the Docker Hub for images
  1909  
  1910        --automated=false    Only show automated builds
  1911        --no-trunc=false     Don't truncate output
  1912        -s, --stars=0        Only displays with at least x stars
  1913  
  1914  See [*Find Public Images on Docker Hub*](
  1915  /userguide/dockerrepos/#searching-for-images) for
  1916  more details on finding shared images from the command line.
  1917  
  1918  ## start
  1919  
  1920      Usage: docker start [OPTIONS] CONTAINER [CONTAINER...]
  1921  
  1922      Restart a stopped container
  1923  
  1924        -a, --attach=false         Attach container's STDOUT and STDERR and forward all signals to the process
  1925        -i, --interactive=false    Attach container's STDIN
  1926  
  1927  When run on a container that has already been started,
  1928  takes no action and succeeds unconditionally.
  1929  
  1930  ## stop
  1931  
  1932      Usage: docker stop [OPTIONS] CONTAINER [CONTAINER...]
  1933  
  1934      Stop a running container by sending SIGTERM and then SIGKILL after a grace period
  1935  
  1936        -t, --time=10      Number of seconds to wait for the container to stop before killing it. Default is 10 seconds.
  1937  
  1938  The main process inside the container will receive `SIGTERM`, and after a
  1939  grace period, `SIGKILL`.
  1940  
  1941  ## tag
  1942  
  1943      Usage: docker tag [OPTIONS] IMAGE[:TAG] [REGISTRYHOST/][USERNAME/]NAME[:TAG]
  1944  
  1945      Tag an image into a repository
  1946  
  1947        -f, --force=false    Force
  1948  
  1949  You can group your images together using names and tags, and then upload
  1950  them to [*Share Images via Repositories*](
  1951  /userguide/dockerrepos/#contributing-to-docker-hub).
  1952  
  1953  ## top
  1954  
  1955      Usage: docker top CONTAINER [ps OPTIONS]
  1956  
  1957      Display the running processes of a container
  1958  
  1959  ## unpause
  1960  
  1961      Usage: docker unpause CONTAINER
  1962  
  1963      Unpause all processes within a container
  1964  
  1965  The `docker unpause` command uses the cgroups freezer to un-suspend all
  1966  processes in a container.
  1967  
  1968  See the
  1969  [cgroups freezer documentation](https://www.kernel.org/doc/Documentation/cgroups/freezer-subsystem.txt)
  1970  for further details.
  1971  
  1972  ## version
  1973  
  1974      Usage: docker version
  1975  
  1976      Show the Docker version information.
  1977  
  1978  Show the Docker version, API version, Git commit, and Go version of
  1979  both Docker client and daemon.
  1980  
  1981  ## wait
  1982  
  1983      Usage: docker wait CONTAINER [CONTAINER...]
  1984  
  1985      Block until a container stops, then print its exit code.
  1986