github.com/vincentwoo/docker@v0.7.3-0.20160116130405-82401a4b13c0/man/docker-run.1.md (about)

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