github.com/kim0/docker@v0.6.2-0.20161130212042-4addda3f07e7/docs/reference/commandline/run.md (about)

     1  ---
     2  title: "run"
     3  description: "The run command description and usage"
     4  keywords: ["run, command, container"]
     5  ---
     6  
     7  <!-- This file is maintained within the docker/docker Github
     8       repository at https://github.com/docker/docker/. Make all
     9       pull requests against that repo. If you see this file in
    10       another repository, consider it read-only there, as it will
    11       periodically be overwritten by the definitive file. Pull
    12       requests which include edits to this file in other repositories
    13       will be rejected.
    14  -->
    15  
    16  # run
    17  
    18  ```markdown
    19  Usage:  docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
    20  
    21  Run a command in a new container
    22  
    23  Options:
    24        --add-host value              Add a custom host-to-IP mapping (host:ip) (default [])
    25    -a, --attach value                Attach to STDIN, STDOUT or STDERR (default [])
    26        --blkio-weight value          Block IO (relative weight), between 10 and 1000
    27        --blkio-weight-device value   Block IO weight (relative device weight) (default [])
    28        --cap-add value               Add Linux capabilities (default [])
    29        --cap-drop value              Drop Linux capabilities (default [])
    30        --cgroup-parent string        Optional parent cgroup for the container
    31        --cidfile string              Write the container ID to the file
    32        --cpu-percent int             CPU percent (Windows only)
    33        --cpu-period int              Limit CPU CFS (Completely Fair Scheduler) period
    34        --cpu-quota int               Limit CPU CFS (Completely Fair Scheduler) quota
    35    -c, --cpu-shares int              CPU shares (relative weight)
    36        --cpu-rt-period int           Limit the CPU real-time period in microseconds
    37        --cpu-rt-runtime int          Limit the CPU real-time runtime in microseconds
    38        --cpuset-cpus string          CPUs in which to allow execution (0-3, 0,1)
    39        --cpuset-mems string          MEMs in which to allow execution (0-3, 0,1)
    40    -d, --detach                      Run container in background and print container ID
    41        --detach-keys string          Override the key sequence for detaching a container
    42        --device value                Add a host device to the container (default [])
    43        --device-read-bps value       Limit read rate (bytes per second) from a device (default [])
    44        --device-read-iops value      Limit read rate (IO per second) from a device (default [])
    45        --device-write-bps value      Limit write rate (bytes per second) to a device (default [])
    46        --device-write-iops value     Limit write rate (IO per second) to a device (default [])
    47        --disable-content-trust       Skip image verification (default true)
    48        --dns value                   Set custom DNS servers (default [])
    49        --dns-opt value               Set DNS options (default [])
    50        --dns-search value            Set custom DNS search domains (default [])
    51        --entrypoint string           Overwrite the default ENTRYPOINT of the image
    52    -e, --env value                   Set environment variables (default [])
    53        --env-file value              Read in a file of environment variables (default [])
    54        --expose value                Expose a port or a range of ports (default [])
    55        --group-add value             Add additional groups to join (default [])
    56        --health-cmd string           Command to run to check health
    57        --health-interval duration    Time between running the check
    58        --health-retries int          Consecutive failures needed to report unhealthy
    59        --health-timeout duration     Maximum time to allow one check to run
    60        --help                        Print usage
    61    -h, --hostname string             Container host name
    62    -i, --interactive                 Keep STDIN open even if not attached
    63        --io-maxbandwidth string      Maximum IO bandwidth limit for the system drive (Windows only)
    64                                      (Windows only). The format is `<number><unit>`.
    65                                      Unit is optional and can be `b` (bytes per second),
    66                                      `k` (kilobytes per second), `m` (megabytes per second),
    67                                      or `g` (gigabytes per second). If you omit the unit,
    68                                      the system uses bytes per second.
    69                                      --io-maxbandwidth and --io-maxiops are mutually exclusive options.
    70        --io-maxiops uint             Maximum IOps limit for the system drive (Windows only)
    71        --ip string                   Container IPv4 address (e.g. 172.30.100.104)
    72        --ip6 string                  Container IPv6 address (e.g. 2001:db8::33)
    73        --ipc string                  IPC namespace to use
    74        --isolation string            Container isolation technology
    75        --kernel-memory string        Kernel memory limit
    76    -l, --label value                 Set meta data on a container (default [])
    77        --label-file value            Read in a line delimited file of labels (default [])
    78        --link value                  Add link to another container (default [])
    79        --link-local-ip value         Container IPv4/IPv6 link-local addresses (default [])
    80        --log-driver string           Logging driver for the container
    81        --log-opt value               Log driver options (default [])
    82        --mac-address string          Container MAC address (e.g. 92:d0:c6:0a:29:33)
    83    -m, --memory string               Memory limit
    84        --memory-reservation string   Memory soft limit
    85        --memory-swap string          Swap limit equal to memory plus swap: '-1' to enable unlimited swap
    86        --memory-swappiness int       Tune container memory swappiness (0 to 100) (default -1)
    87        --name string                 Assign a name to the container
    88        --network-alias value         Add network-scoped alias for the container (default [])
    89        --network string              Connect a container to a network
    90                                      'bridge': create a network stack on the default Docker bridge
    91                                      'none': no networking
    92                                      'container:<name|id>': reuse another container's network stack
    93                                      'host': use the Docker host network stack
    94                                      '<network-name>|<network-id>': connect to a user-defined network
    95        --no-healthcheck              Disable any container-specified HEALTHCHECK
    96        --oom-kill-disable            Disable OOM Killer
    97        --oom-score-adj int           Tune host's OOM preferences (-1000 to 1000)
    98        --pid string                  PID namespace to use
    99        --pids-limit int              Tune container pids limit (set -1 for unlimited)
   100        --privileged                  Give extended privileges to this container
   101    -p, --publish value               Publish a container's port(s) to the host (default [])
   102    -P, --publish-all                 Publish all exposed ports to random ports
   103        --read-only                   Mount the container's root filesystem as read only
   104        --restart string              Restart policy to apply when a container exits (default "no")
   105                                      Possible values are : no, on-failure[:max-retry], always, unless-stopped
   106        --rm                          Automatically remove the container when it exits
   107        --runtime string              Runtime to use for this container
   108        --security-opt value          Security Options (default [])
   109        --shm-size string             Size of /dev/shm, default value is 64MB.
   110                                      The format is `<number><unit>`. `number` must be greater than `0`.
   111                                      Unit is optional and can be `b` (bytes), `k` (kilobytes), `m` (megabytes),
   112                                      or `g` (gigabytes). If you omit the unit, the system uses bytes.
   113        --sig-proxy                   Proxy received signals to the process (default true)
   114        --stop-signal string          Signal to stop a container, SIGTERM by default (default "SIGTERM")
   115        --stop-timeout=10             Timeout (in seconds) to stop a container
   116        --storage-opt value           Storage driver options for the container (default [])
   117        --sysctl value                Sysctl options (default map[])
   118        --tmpfs value                 Mount a tmpfs directory (default [])
   119    -t, --tty                         Allocate a pseudo-TTY
   120        --ulimit value                Ulimit options (default [])
   121    -u, --user string                 Username or UID (format: <name|uid>[:<group|gid>])
   122        --userns string               User namespace to use
   123                                      'host': Use the Docker host user namespace
   124                                      '': Use the Docker daemon user namespace specified by `--userns-remap` option.
   125        --uts string                  UTS namespace to use
   126    -v, --volume value                Bind mount a volume (default []). The format
   127                                      is `[host-src:]container-dest[:<options>]`.
   128                                      The comma-delimited `options` are [rw|ro],
   129                                      [z|Z], [[r]shared|[r]slave|[r]private], and
   130                                      [nocopy]. The 'host-src' is an absolute path
   131                                      or a name value.
   132        --volume-driver string        Optional volume driver for the container
   133        --volumes-from value          Mount volumes from the specified container(s) (default [])
   134    -w, --workdir string              Working directory inside the container
   135  ```
   136  
   137  The `docker run` command first `creates` a writeable container layer over the
   138  specified image, and then `starts` it using the specified command. That is,
   139  `docker run` is equivalent to the API `/containers/create` then
   140  `/containers/(id)/start`. A stopped container can be restarted with all its
   141  previous changes intact using `docker start`. See `docker ps -a` to view a list
   142  of all containers.
   143  
   144  The `docker run` command can be used in combination with `docker commit` to
   145  [*change the command that a container runs*](commit.md). There is additional detailed information about `docker run` in the [Docker run reference](../run.md).
   146  
   147  For information on connecting a container to a network, see the ["*Docker network overview*"](https://docs.docker.com/engine/userguide/networking/).
   148  
   149  ## Examples
   150  
   151  ### Assign name and allocate pseudo-TTY (--name, -it)
   152  
   153      $ docker run --name test -it debian
   154      root@d6c0fe130dba:/# exit 13
   155      $ echo $?
   156      13
   157      $ docker ps -a | grep test
   158      d6c0fe130dba        debian:7            "/bin/bash"         26 seconds ago      Exited (13) 17 seconds ago                         test
   159  
   160  This example runs a container named `test` using the `debian:latest`
   161  image. The `-it` instructs Docker to allocate a pseudo-TTY connected to
   162  the container's stdin; creating an interactive `bash` shell in the container.
   163  In the example, the `bash` shell is quit by entering
   164  `exit 13`. This exit code is passed on to the caller of
   165  `docker run`, and is recorded in the `test` container's metadata.
   166  
   167  ### Capture container ID (--cidfile)
   168  
   169      $ docker run --cidfile /tmp/docker_test.cid ubuntu echo "test"
   170  
   171  This will create a container and print `test` to the console. The `cidfile`
   172  flag makes Docker attempt to create a new file and write the container ID to it.
   173  If the file exists already, Docker will return an error. Docker will close this
   174  file when `docker run` exits.
   175  
   176  ### Full container capabilities (--privileged)
   177  
   178      $ docker run -t -i --rm ubuntu bash
   179      root@bc338942ef20:/# mount -t tmpfs none /mnt
   180      mount: permission denied
   181  
   182  This will *not* work, because by default, most potentially dangerous kernel
   183  capabilities are dropped; including `cap_sys_admin` (which is required to mount
   184  filesystems). However, the `--privileged` flag will allow it to run:
   185  
   186      $ docker run -t -i --privileged ubuntu bash
   187      root@50e3f57e16e6:/# mount -t tmpfs none /mnt
   188      root@50e3f57e16e6:/# df -h
   189      Filesystem      Size  Used Avail Use% Mounted on
   190      none            1.9G     0  1.9G   0% /mnt
   191  
   192  The `--privileged` flag gives *all* capabilities to the container, and it also
   193  lifts all the limitations enforced by the `device` cgroup controller. In other
   194  words, the container can then do almost everything that the host can do. This
   195  flag exists to allow special use-cases, like running Docker within Docker.
   196  
   197  ### Set working directory (-w)
   198  
   199      $ docker  run -w /path/to/dir/ -i -t  ubuntu pwd
   200  
   201  The `-w` lets the command being executed inside directory given, here
   202  `/path/to/dir/`. If the path does not exist it is created inside the container.
   203  
   204  ### Set storage driver options per container
   205  
   206      $ docker run -it --storage-opt size=120G fedora /bin/bash
   207  
   208  This (size) will allow to set the container rootfs size to 120G at creation time.
   209  This option is only available for the `devicemapper`, `btrfs`, `overlay2`,
   210  `windowsfilter` and `zfs` graph drivers.
   211  For the `devicemapper`, `btrfs`, `windowsfilter` and `zfs` graph drivers,
   212  user cannot pass a size less than the Default BaseFS Size.
   213  For the `overlay2` storage driver, the size option is only available if the
   214  backing fs is `xfs` and mounted with the `pquota` mount option.
   215  Under these conditions, user can pass any size less then the backing fs size.
   216  
   217  ### Mount tmpfs (--tmpfs)
   218  
   219      $ docker run -d --tmpfs /run:rw,noexec,nosuid,size=65536k my_image
   220  
   221  The `--tmpfs` flag mounts an empty tmpfs into the container with the `rw`,
   222  `noexec`, `nosuid`, `size=65536k` options.
   223  
   224  ### Mount volume (-v, --read-only)
   225  
   226      $ docker  run  -v `pwd`:`pwd` -w `pwd` -i -t  ubuntu pwd
   227  
   228  The `-v` flag mounts the current working directory into the container. The `-w`
   229  lets the command being executed inside the current working directory, by
   230  changing into the directory to the value returned by `pwd`. So this
   231  combination executes the command using the container, but inside the
   232  current working directory.
   233  
   234      $ docker run -v /doesnt/exist:/foo -w /foo -i -t ubuntu bash
   235  
   236  When the host directory of a bind-mounted volume doesn't exist, Docker
   237  will automatically create this directory on the host for you. In the
   238  example above, Docker will create the `/doesnt/exist`
   239  folder before starting your container.
   240  
   241      $ docker run --read-only -v /icanwrite busybox touch /icanwrite/here
   242  
   243  Volumes can be used in combination with `--read-only` to control where
   244  a container writes files. The `--read-only` flag mounts the container's root
   245  filesystem as read only prohibiting writes to locations other than the
   246  specified volumes for the container.
   247  
   248      $ docker run -t -i -v /var/run/docker.sock:/var/run/docker.sock -v /path/to/static-docker-binary:/usr/bin/docker busybox sh
   249  
   250  By bind-mounting the docker unix socket and statically linked docker
   251  binary (refer to [get the linux binary](
   252  ../../installation/binaries.md#get-the-linux-binary)),
   253  you give the container the full access to create and manipulate the host's
   254  Docker daemon.
   255  
   256  For in-depth information about volumes, refer to [manage data in containers](https://docs.docker.com/engine/tutorials/dockervolumes/)
   257  
   258  ### Publish or expose port (-p, --expose)
   259  
   260      $ docker run -p 127.0.0.1:80:8080 ubuntu bash
   261  
   262  This binds port `8080` of the container to port `80` on `127.0.0.1` of the host
   263  machine. The [Docker User
   264  Guide](https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/)
   265  explains in detail how to manipulate ports in Docker.
   266  
   267      $ docker run --expose 80 ubuntu bash
   268  
   269  This exposes port `80` of the container without publishing the port to the host
   270  system's interfaces.
   271  
   272  ### Set environment variables (-e, --env, --env-file)
   273  
   274      $ docker run -e MYVAR1 --env MYVAR2=foo --env-file ./env.list ubuntu bash
   275  
   276  This sets simple (non-array) environmental variables in the container. For
   277  illustration all three
   278  flags are shown here. Where `-e`, `--env` take an environment variable and
   279  value, or if no `=` is provided, then that variable's current value, set via
   280  `export`, is passed through (i.e. `$MYVAR1` from the host is set to `$MYVAR1`
   281  in the container). When no `=` is provided and that variable is not defined
   282  in the client's environment then that variable will be removed from the
   283  container's list of environment variables. All three flags, `-e`, `--env` and
   284  `--env-file` can be repeated.
   285  
   286  Regardless of the order of these three flags, the `--env-file` are processed
   287  first, and then `-e`, `--env` flags. This way, the `-e` or `--env` will
   288  override variables as needed.
   289  
   290      $ cat ./env.list
   291      TEST_FOO=BAR
   292      $ docker run --env TEST_FOO="This is a test" --env-file ./env.list busybox env | grep TEST_FOO
   293      TEST_FOO=This is a test
   294  
   295  The `--env-file` flag takes a filename as an argument and expects each line
   296  to be in the `VAR=VAL` format, mimicking the argument passed to `--env`. Comment
   297  lines need only be prefixed with `#`
   298  
   299  An example of a file passed with `--env-file`
   300  
   301      $ cat ./env.list
   302      TEST_FOO=BAR
   303  
   304      # this is a comment
   305      TEST_APP_DEST_HOST=10.10.0.127
   306      TEST_APP_DEST_PORT=8888
   307      _TEST_BAR=FOO
   308      TEST_APP_42=magic
   309      helloWorld=true
   310      123qwe=bar
   311      org.spring.config=something
   312  
   313      # pass through this variable from the caller
   314      TEST_PASSTHROUGH
   315      $ TEST_PASSTHROUGH=howdy docker run --env-file ./env.list busybox env
   316      PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
   317      HOSTNAME=5198e0745561
   318      TEST_FOO=BAR
   319      TEST_APP_DEST_HOST=10.10.0.127
   320      TEST_APP_DEST_PORT=8888
   321      _TEST_BAR=FOO
   322      TEST_APP_42=magic
   323      helloWorld=true
   324      TEST_PASSTHROUGH=howdy
   325      HOME=/root
   326      123qwe=bar
   327      org.spring.config=something
   328  
   329      $ docker run --env-file ./env.list busybox env
   330      PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
   331      HOSTNAME=5198e0745561
   332      TEST_FOO=BAR
   333      TEST_APP_DEST_HOST=10.10.0.127
   334      TEST_APP_DEST_PORT=8888
   335      _TEST_BAR=FOO
   336      TEST_APP_42=magic
   337      helloWorld=true
   338      TEST_PASSTHROUGH=
   339      HOME=/root
   340      123qwe=bar
   341      org.spring.config=something
   342  
   343  ### Set metadata on container (-l, --label, --label-file)
   344  
   345  A label is a `key=value` pair that applies metadata to a container. To label a container with two labels:
   346  
   347      $ docker run -l my-label --label com.example.foo=bar ubuntu bash
   348  
   349  The `my-label` key doesn't specify a value so the label defaults to an empty
   350  string(`""`). To add multiple labels, repeat the label flag (`-l` or `--label`).
   351  
   352  The `key=value` must be unique to avoid overwriting the label value. If you
   353  specify labels with identical keys but different values, each subsequent value
   354  overwrites the previous. Docker uses the last `key=value` you supply.
   355  
   356  Use the `--label-file` flag to load multiple labels from a file. Delimit each
   357  label in the file with an EOL mark. The example below loads labels from a
   358  labels file in the current directory:
   359  
   360      $ docker run --label-file ./labels ubuntu bash
   361  
   362  The label-file format is similar to the format for loading environment
   363  variables. (Unlike environment variables, labels are not visible to processes
   364  running inside a container.) The following example illustrates a label-file
   365  format:
   366  
   367      com.example.label1="a label"
   368  
   369      # this is a comment
   370      com.example.label2=another\ label
   371      com.example.label3
   372  
   373  You can load multiple label-files by supplying multiple  `--label-file` flags.
   374  
   375  For additional information on working with labels, see [*Labels - custom
   376  metadata in Docker*](https://docs.docker.com/engine/userguide/labels-custom-metadata/) in the Docker User
   377  Guide.
   378  
   379  ### Connect a container to a network (--network)
   380  
   381  When you start a container use the `--network` flag to connect it to a network.
   382  This adds the `busybox` container to the `my-net` network.
   383  
   384  ```bash
   385  $ docker run -itd --network=my-net busybox
   386  ```
   387  
   388  You can also choose the IP addresses for the container with `--ip` and `--ip6`
   389  flags when you start the container on a user-defined network.
   390  
   391  ```bash
   392  $ docker run -itd --network=my-net --ip=10.10.9.75 busybox
   393  ```
   394  
   395  If you want to add a running container to a network use the `docker network connect` subcommand.
   396  
   397  You can connect multiple containers to the same network. Once connected, the
   398  containers can communicate easily need only another container's IP address
   399  or name. For `overlay` networks or custom plugins that support multi-host
   400  connectivity, containers connected to the same multi-host network but launched
   401  from different Engines can also communicate in this way.
   402  
   403  **Note**: Service discovery is unavailable on the default bridge network.
   404  Containers can communicate via their IP addresses by default. To communicate
   405  by name, they must be linked.
   406  
   407  You can disconnect a container from a network using the `docker network
   408  disconnect` command.
   409  
   410  ### Mount volumes from container (--volumes-from)
   411  
   412      $ docker run --volumes-from 777f7dc92da7 --volumes-from ba8c0c54f0f2:ro -i -t ubuntu pwd
   413  
   414  The `--volumes-from` flag mounts all the defined volumes from the referenced
   415  containers. Containers can be specified by repetitions of the `--volumes-from`
   416  argument. The container ID may be optionally suffixed with `:ro` or `:rw` to
   417  mount the volumes in read-only or read-write mode, respectively. By default,
   418  the volumes are mounted in the same mode (read write or read only) as
   419  the reference container.
   420  
   421  Labeling systems like SELinux require that proper labels are placed on volume
   422  content mounted into a container. Without a label, the security system might
   423  prevent the processes running inside the container from using the content. By
   424  default, Docker does not change the labels set by the OS.
   425  
   426  To change the label in the container context, you can add either of two suffixes
   427  `:z` or `:Z` to the volume mount. These suffixes tell Docker to relabel file
   428  objects on the shared volumes. The `z` option tells Docker that two containers
   429  share the volume content. As a result, Docker labels the content with a shared
   430  content label. Shared volume labels allow all containers to read/write content.
   431  The `Z` option tells Docker to label the content with a private unshared label.
   432  Only the current container can use a private volume.
   433  
   434  ### Attach to STDIN/STDOUT/STDERR (-a)
   435  
   436  The `-a` flag tells `docker run` to bind to the container's `STDIN`, `STDOUT`
   437  or `STDERR`. This makes it possible to manipulate the output and input as
   438  needed.
   439  
   440      $ echo "test" | docker run -i -a stdin ubuntu cat -
   441  
   442  This pipes data into a container and prints the container's ID by attaching
   443  only to the container's `STDIN`.
   444  
   445      $ docker run -a stderr ubuntu echo test
   446  
   447  This isn't going to print anything unless there's an error because we've
   448  only attached to the `STDERR` of the container. The container's logs
   449  still store what's been written to `STDERR` and `STDOUT`.
   450  
   451      $ cat somefile | docker run -i -a stdin mybuilder dobuild
   452  
   453  This is how piping a file into a container could be done for a build.
   454  The container's ID will be printed after the build is done and the build
   455  logs could be retrieved using `docker logs`. This is
   456  useful if you need to pipe a file or something else into a container and
   457  retrieve the container's ID once the container has finished running.
   458  
   459  ### Add host device to container (--device)
   460  
   461      $ docker run --device=/dev/sdc:/dev/xvdc --device=/dev/sdd --device=/dev/zero:/dev/nulo -i -t ubuntu ls -l /dev/{xvdc,sdd,nulo}
   462      brw-rw---- 1 root disk 8, 2 Feb  9 16:05 /dev/xvdc
   463      brw-rw---- 1 root disk 8, 3 Feb  9 16:05 /dev/sdd
   464      crw-rw-rw- 1 root root 1, 5 Feb  9 16:05 /dev/nulo
   465  
   466  It is often necessary to directly expose devices to a container. The `--device`
   467  option enables that. For example, a specific block storage device or loop
   468  device or audio device can be added to an otherwise unprivileged container
   469  (without the `--privileged` flag) and have the application directly access it.
   470  
   471  By default, the container will be able to `read`, `write` and `mknod` these devices.
   472  This can be overridden using a third `:rwm` set of options to each `--device`
   473  flag:
   474  
   475  
   476      $ docker run --device=/dev/sda:/dev/xvdc --rm -it ubuntu fdisk  /dev/xvdc
   477  
   478      Command (m for help): q
   479      $ docker run --device=/dev/sda:/dev/xvdc:r --rm -it ubuntu fdisk  /dev/xvdc
   480      You will not be able to write the partition table.
   481  
   482      Command (m for help): q
   483  
   484      $ docker run --device=/dev/sda:/dev/xvdc:rw --rm -it ubuntu fdisk  /dev/xvdc
   485  
   486      Command (m for help): q
   487  
   488      $ docker run --device=/dev/sda:/dev/xvdc:m --rm -it ubuntu fdisk  /dev/xvdc
   489      fdisk: unable to open /dev/xvdc: Operation not permitted
   490  
   491  > **Note:**
   492  > `--device` cannot be safely used with ephemeral devices. Block devices
   493  > that may be removed should not be added to untrusted containers with
   494  > `--device`.
   495  
   496  ### Restart policies (--restart)
   497  
   498  Use Docker's `--restart` to specify a container's *restart policy*. A restart
   499  policy controls whether the Docker daemon restarts a container after exit.
   500  Docker supports the following restart policies:
   501  
   502  <table>
   503    <thead>
   504      <tr>
   505        <th>Policy</th>
   506        <th>Result</th>
   507      </tr>
   508    </thead>
   509    <tbody>
   510      <tr>
   511        <td><strong>no</strong></td>
   512        <td>
   513          Do not automatically restart the container when it exits. This is the
   514          default.
   515        </td>
   516      </tr>
   517      <tr>
   518        <td>
   519          <span style="white-space: nowrap">
   520            <strong>on-failure</strong>[:max-retries]
   521          </span>
   522        </td>
   523        <td>
   524          Restart only if the container exits with a non-zero exit status.
   525          Optionally, limit the number of restart retries the Docker
   526          daemon attempts.
   527        </td>
   528      </tr>
   529      <tr>
   530        <td><strong>always</strong></td>
   531        <td>
   532          Always restart the container regardless of the exit status.
   533          When you specify always, the Docker daemon will try to restart
   534          the container indefinitely. The container will also always start
   535          on daemon startup, regardless of the current state of the container.
   536        </td>
   537      </tr>
   538      <tr>
   539        <td><strong>unless-stopped</strong></td>
   540        <td>
   541          Always restart the container regardless of the exit status, but
   542          do not start it on daemon startup if the container has been put
   543          to a stopped state before.
   544        </td>
   545      </tr>
   546    </tbody>
   547  </table>
   548  
   549      $ docker run --restart=always redis
   550  
   551  This will run the `redis` container with a restart policy of **always**
   552  so that if the container exits, Docker will restart it.
   553  
   554  More detailed information on restart policies can be found in the
   555  [Restart Policies (--restart)](../run.md#restart-policies-restart)
   556  section of the Docker run reference page.
   557  
   558  ### Add entries to container hosts file (--add-host)
   559  
   560  You can add other hosts into a container's `/etc/hosts` file by using one or
   561  more `--add-host` flags. This example adds a static address for a host named
   562  `docker`:
   563  
   564      $ docker run --add-host=docker:10.180.0.1 --rm -it debian
   565      root@f38c87f2a42d:/# ping docker
   566      PING docker (10.180.0.1): 48 data bytes
   567      56 bytes from 10.180.0.1: icmp_seq=0 ttl=254 time=7.600 ms
   568      56 bytes from 10.180.0.1: icmp_seq=1 ttl=254 time=30.705 ms
   569      ^C--- docker ping statistics ---
   570      2 packets transmitted, 2 packets received, 0% packet loss
   571      round-trip min/avg/max/stddev = 7.600/19.152/30.705/11.553 ms
   572  
   573  Sometimes you need to connect to the Docker host from within your
   574  container. To enable this, pass the Docker host's IP address to
   575  the container using the `--add-host` flag. To find the host's address,
   576  use the `ip addr show` command.
   577  
   578  The flags you pass to `ip addr show` depend on whether you are
   579  using IPv4 or IPv6 networking in your containers. Use the following
   580  flags for IPv4 address retrieval for a network device named `eth0`:
   581  
   582      $ HOSTIP=`ip -4 addr show scope global dev eth0 | grep inet | awk '{print \$2}' | cut -d / -f 1`
   583      $ docker run  --add-host=docker:${HOSTIP} --rm -it debian
   584  
   585  For IPv6 use the `-6` flag instead of the `-4` flag. For other network
   586  devices, replace `eth0` with the correct device name (for example `docker0`
   587  for the bridge device).
   588  
   589  ### Set ulimits in container (--ulimit)
   590  
   591  Since setting `ulimit` settings in a container requires extra privileges not
   592  available in the default container, you can set these using the `--ulimit` flag.
   593  `--ulimit` is specified with a soft and hard limit as such:
   594  `<type>=<soft limit>[:<hard limit>]`, for example:
   595  
   596      $ docker run --ulimit nofile=1024:1024 --rm debian sh -c "ulimit -n"
   597      1024
   598  
   599  > **Note:**
   600  > If you do not provide a `hard limit`, the `soft limit` will be used
   601  > for both values. If no `ulimits` are set, they will be inherited from
   602  > the default `ulimits` set on the daemon.  `as` option is disabled now.
   603  > In other words, the following script is not supported:
   604  > `$ docker run -it --ulimit as=1024 fedora /bin/bash`
   605  
   606  The values are sent to the appropriate `syscall` as they are set.
   607  Docker doesn't perform any byte conversion. Take this into account when setting the values.
   608  
   609  #### For `nproc` usage
   610  
   611  Be careful setting `nproc` with the `ulimit` flag as `nproc` is designed by Linux to set the
   612  maximum number of processes available to a user, not to a container.  For example, start four
   613  containers with `daemon` user:
   614  
   615      docker run -d -u daemon --ulimit nproc=3 busybox top
   616      docker run -d -u daemon --ulimit nproc=3 busybox top
   617      docker run -d -u daemon --ulimit nproc=3 busybox top
   618      docker run -d -u daemon --ulimit nproc=3 busybox top
   619  
   620  The 4th container fails and reports "[8] System error: resource temporarily unavailable" error.
   621  This fails because the caller set `nproc=3` resulting in the first three containers using up
   622  the three processes quota set for the `daemon` user.
   623  
   624  ### Stop container with signal (--stop-signal)
   625  
   626  The `--stop-signal` flag sets the system call signal that will be sent to the container to exit.
   627  This signal can be a valid unsigned number that matches a position in the kernel's syscall table, for instance 9,
   628  or a signal name in the format SIGNAME, for instance SIGKILL.
   629  
   630  ### Optional security options (--security-opt)
   631  
   632  On Windows, this flag can be used to specify the `credentialspec` option.
   633  The `credentialspec` must be in the format `file://spec.txt` or `registry://keyname`.
   634  
   635  ### Stop container with timeout (--stop-timeout)
   636  
   637  The `--stop-timeout` flag sets the the timeout (in seconds) that a pre-defined (see `--stop-signal`) system call
   638  signal that will be sent to the container to exit. After timeout elapses the container will be killed with SIGKILL.
   639  
   640  ### Specify isolation technology for container (--isolation)
   641  
   642  This option is useful in situations where you are running Docker containers on
   643  Microsoft Windows. The `--isolation <value>` option sets a container's isolation
   644  technology. On Linux, the only supported is the `default` option which uses
   645  Linux namespaces. These two commands are equivalent on Linux:
   646  
   647  ```
   648  $ docker run -d busybox top
   649  $ docker run -d --isolation default busybox top
   650  ```
   651  
   652  On Microsoft Windows, can take any of these values:
   653  
   654  
   655  | Value     | Description                                                                                                                                                   |
   656  |-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
   657  | `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.  |
   658  | `process` | Namespace isolation only.                                                                                                                                     |
   659  | `hyperv`   | Hyper-V hypervisor partition-based isolation.                                                                                                                  |
   660  
   661  On Windows, the default isolation for client is `hyperv`, and for server is
   662  `process`. Therefore when running on Windows server without a `daemon` option
   663  set, these two commands are equivalent:
   664  ```
   665  $ docker run -d --isolation default busybox top
   666  $ docker run -d --isolation process busybox top
   667  ```
   668  
   669  If you have set the `--exec-opt isolation=hyperv` option on the Docker `daemon`,
   670  if running on Windows server, any of these commands also result in `hyperv` isolation:
   671  
   672  ```
   673  $ docker run -d --isolation default busybox top
   674  $ docker run -d --isolation hyperv busybox top
   675  ```
   676  
   677  ### Configure namespaced kernel parameters (sysctls) at runtime
   678  
   679  The `--sysctl` sets namespaced kernel parameters (sysctls) in the
   680  container. For example, to turn on IP forwarding in the containers
   681  network namespace, run this command:
   682  
   683      $ docker run --sysctl net.ipv4.ip_forward=1 someimage
   684  
   685  
   686  > **Note**: Not all sysctls are namespaced. Docker does not support changing sysctls
   687  > inside of a container that also modify the host system. As the kernel
   688  > evolves we expect to see more sysctls become namespaced.
   689  
   690  #### Currently supported sysctls
   691  
   692    `IPC Namespace`:
   693  
   694    kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced
   695    Sysctls beginning with fs.mqueue.*
   696  
   697    If you use the `--ipc=host` option these sysctls will not be allowed.
   698  
   699    `Network Namespace`:
   700        Sysctls beginning with net.*
   701  
   702    If you use the `--network=host` option using these sysctls will not be allowed.