Commit Graph

96 Commits

Author SHA1 Message Date
Thomas Leonard 51ddea93a2 Add support for user-defined healthchecks
This PR adds support for user-defined health-check probes for Docker
containers. It adds a `HEALTHCHECK` instruction to the Dockerfile syntax plus
some corresponding "docker run" options. It can be used with a restart policy
to automatically restart a container if the check fails.

The `HEALTHCHECK` instruction has two forms:

* `HEALTHCHECK [OPTIONS] CMD command` (check container health by running a command inside the container)
* `HEALTHCHECK NONE` (disable any healthcheck inherited from the base image)

The `HEALTHCHECK` instruction tells Docker how to test a container to check that
it is still working. This can detect cases such as a web server that is stuck in
an infinite loop and unable to handle new connections, even though the server
process is still running.

When a container has a healthcheck specified, it has a _health status_ in
addition to its normal status. This status is initially `starting`. Whenever a
health check passes, it becomes `healthy` (whatever state it was previously in).
After a certain number of consecutive failures, it becomes `unhealthy`.

The options that can appear before `CMD` are:

* `--interval=DURATION` (default: `30s`)
* `--timeout=DURATION` (default: `30s`)
* `--retries=N` (default: `1`)

The health check will first run **interval** seconds after the container is
started, and then again **interval** seconds after each previous check completes.

If a single run of the check takes longer than **timeout** seconds then the check
is considered to have failed.

It takes **retries** consecutive failures of the health check for the container
to be considered `unhealthy`.

There can only be one `HEALTHCHECK` instruction in a Dockerfile. If you list
more than one then only the last `HEALTHCHECK` will take effect.

The command after the `CMD` keyword can be either a shell command (e.g. `HEALTHCHECK
CMD /bin/check-running`) or an _exec_ array (as with other Dockerfile commands;
see e.g. `ENTRYPOINT` for details).

The command's exit status indicates the health status of the container.
The possible values are:

- 0: success - the container is healthy and ready for use
- 1: unhealthy - the container is not working correctly
- 2: starting - the container is not ready for use yet, but is working correctly

If the probe returns 2 ("starting") when the container has already moved out of the
"starting" state then it is treated as "unhealthy" instead.

For example, to check every five minutes or so that a web-server is able to
serve the site's main page within three seconds:

    HEALTHCHECK --interval=5m --timeout=3s \
      CMD curl -f http://localhost/ || exit 1

To help debug failing probes, any output text (UTF-8 encoded) that the command writes
on stdout or stderr will be stored in the health status and can be queried with
`docker inspect`. Such output should be kept short (only the first 4096 bytes
are stored currently).

When the health status of a container changes, a `health_status` event is
generated with the new status. The health status is also displayed in the
`docker ps` output.

Signed-off-by: Thomas Leonard <thomas.leonard@docker.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2017-06-02 00:07:41 +00:00
Yong Tang d1aaf129f2 The option --add-host and --net=host should not be mutually exclusive.
This fix tries to address the issue raised in #21976 and allows
the options of `--add-host` and `--net=host` to work at the same time.

The documentation has been updated and additional tests have been
added to cover this change.

This fix fixes #21976.

Signed-off-by: Yong Tang <yong.tang.github@outlook.com>
2017-06-02 00:07:40 +00:00
Yong Tang f17fb53f53 The option --dns, --dns-search, --dns-opt and --net=host should not be mutually exclusive.
This fix tries to address the issue raised in #21976 and allows
the options of `--dns`, `--dns-search`, `--dns-opt` and `--net=host`
to work at the same time.

The documentation has been updated and additional tests have been
added to cover this change.

This fix fixes #21976.

Signed-off-by: Yong Tang <yong.tang.github@outlook.com>
2017-06-02 00:07:40 +00:00
Michael Friis 3cc96bb891 remove duplicated text
Signed-off-by: Michael Friis <friism@gmail.com>
2017-06-02 00:07:39 +00:00
Sebastiaan van Stijn 563b5dab54 Remove MLS example from SELinux example in run reference
Automatic translation of MLS labels is currently not
supported, so should not be documented as an example.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2017-06-02 00:07:39 +00:00
Justin Cormack ba8f5cfbb8 Align default seccomp profile with selected capabilities
Currently the default seccomp profile is fixed. This changes it
so that it varies depending on the Linux capabilities selected with
the --cap-add and --cap-drop options. Without this, if a user adds
privileges, eg to allow ptrace with --cap-add sys_ptrace then still
cannot actually use ptrace as it is still blocked by seccomp, so
they will probably disable seccomp or use --privileged. With this
change the syscalls that are needed for the capability are also
allowed by the seccomp profile based on the selected capabilities.

While this patch makes it easier to do things with for example
cap_sys_admin enabled, as it will now allow creating new namespaces
and use of mount, it still allows less than --cap-add cap_sys_admin
--security-opt seccomp:unconfined would have previously. It is not
recommended that users run containers with cap_sys_admin as this does
give full access to the host machine.

It also cleans up some architecture specific system calls to be
only selected when needed.

Signed-off-by: Justin Cormack <justin.cormack@docker.com>
2017-06-02 00:07:39 +00:00
Mrunal Patel 637048e176 Add support for --pid=container:<id>
Signed-off-by: Mrunal Patel <mrunalp@gmail.com>
2017-06-02 00:07:39 +00:00
Yuan Sun d16947629c from inheritted to inherited
Signed-off-by: Yuan Sun <sunyuan3@huawei.com>
2017-06-02 00:07:37 +00:00
Doug Davis fe09131526 Remove unnecessary double-double quotes
Signed-off-by: Doug Davis <dug@us.ibm.com>
2017-06-02 00:07:37 +00:00
Yuan Sun 7d3bb7a6d0 remove "the" in docs.
Signed-off-by: Yuan Sun <sunyuan3@huawei.com>
2017-06-02 00:07:37 +00:00
Hao Zhang 64ba15e3a3 update cgroup link in doc of run
Signed-off-by: Hao Zhang <21521210@zju.edu.cn>
2017-06-02 00:07:37 +00:00
Sebastiaan van Stijn d192f97acc docs: add note about MAC addresses not being unique
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2017-06-02 00:07:36 +00:00
Kai Qiang Wu(Kennan) 6a5870dcfa Fix the old exit status example
Signed-off-by: Kai Qiang Wu(Kennan) <wkqwu@cn.ibm.com>
2017-06-02 00:07:36 +00:00
Kai Qiang Wu(Kennan) a8a29fe7f5 Fix deprecated format for security-opt
Signed-off-by: Kai Qiang Wu(Kennan) <wkqwu@cn.ibm.com>
2017-06-02 00:07:35 +00:00
Lei Jitang 42dfcc1d2a Correct the description of --group-add in run.md
Signed-off-by: Lei Jitang <leijitang@huawei.com>
2017-06-02 00:07:35 +00:00
Sebastiaan van Stijn 0a13b2a1ce Un-deprecate auto-creation of host directories for mounts
Auto-creation of host-directories was marked deprecated in
Docker 1.9, but was decided to be too much of an backward-incompatible
change, so it was decided to keep the feature.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2017-06-02 00:07:35 +00:00
Brian Goff eba678647b Add explicit flags for volume cp/no-cp
This allows a user to specify explicitly to enable
automatic copying of data from the container path to the volume path.
This does not change the default behavior of automatically copying, but
does allow a user to disable it at runtime.

Signed-off-by: Brian Goff <cpuguy83@gmail.com>
2017-06-02 00:07:32 +00:00
David Calavera a7364b3743 Consolidate security options to use `=` as separator.
All other options we have use `=` as separator, labels,
log configurations, graph configurations and so on.
We should be consistent and use `=` for the security
options too.

Signed-off-by: David Calavera <david.calavera@gmail.com>
2017-06-02 00:07:32 +00:00
Dan Walsh 2d0316cb43 Fix documentation on --security-opt seccomp
Missing documentation and man pages on seccomp options.
Signed-off-by: Dan Walsh <dwalsh@redhat.com>
2017-06-02 00:07:32 +00:00
Zhang Wei d219111855 Fix typo
Signed-off-by: Zhang Wei <zhangwei555@huawei.com>
2017-06-02 00:07:32 +00:00
Jason Heiss 6bcb137d2f Allow --hostname with --net=host
Docker creates a UTS namespace by default, even with --net=host, so it
is reasonable to let the user set the hostname. Note that --hostname is
forbidden if the user specifies --uts=host.

Closes #12076
Signed-off-by: Jason Heiss <jheiss@aput.net>
2017-06-02 00:07:32 +00:00
Mrunal Patel d3f632156e Add support for NoNewPrivileges in docker
Signed-off-by: Mrunal Patel <mrunalp@gmail.com>

Add tests for no-new-privileges

Signed-off-by: Mrunal Patel <mrunalp@gmail.com>

Update documentation for no-new-privileges

Signed-off-by: Mrunal Patel <mrunalp@gmail.com>
2017-06-02 00:07:31 +00:00
Jessica Frazelle 91d0d25ee4 update cap-add docs for seccomp
Signed-off-by: Jessica Frazelle <acidburn@docker.com>
2017-06-02 00:07:28 +00:00
Sian Lerk Lau 7c85fb1665 Improve usage details on overriding USER command in Docker run reference page
Signed-off-by: Sian Lerk Lau <kiawin@gmail.com>
2017-06-02 00:07:28 +00:00
Tianon Gravi a015293ff7 Remove "--group-add dbus" from busybox example (no dbus group in busybox anymore)
Signed-off-by: Andrew "Tianon" Page <admwiggin@gmail.com>
2017-06-02 00:07:28 +00:00
Sebastiaan van Stijn d4fd7fd13b Fix docs for tmpfs (pr 19688)
Underlying files are no longer copied to the tmpfs.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2017-06-02 00:07:27 +00:00
Mary Anthony 7910f01804 Creating Engine specific menu
Fixing the links
Updating with Seb's comments
Adding weight
Fixing the engine aliases
Updating after Arun pushed
Removing empty file

Signed-off-by: Mary Anthony <mary@docker.com>
2017-06-02 00:07:26 +00:00
Brian Goff 88fa05ccb4 Add note about mount propagation on systemd
Signed-off-by: Brian Goff <cpuguy83@gmail.com>
2017-06-02 00:07:26 +00:00
Brian Goff 8de6a3fc71 On container rm, don't remove named mountpoints
This makes it so when calling `docker run --rm`, or `docker rm -v`, only
volumes specified without a name, e.g. `docker run -v /foo` instead of
`docker run -v awesome:/foo` are removed.

Note that all volumes are named, some are named by the user, some get a
generated name. This is specifically about how the volume was specified
on `run`, assuming that if the user specified it with a name they expect
it to persist after the container is cleaned up.

Signed-off-by: Brian Goff <cpuguy83@gmail.com>
2017-06-02 00:07:26 +00:00
Jasmine Hegman 6495ac0c5f Correcting `overlay` -> `bridge` driver in run.md
Correcting `overlay` -> `bridge` driver in run.md to match the preceding paragraph.

Signed-off-by: Jasmine Hegman <jasmine@jhegman.com>
2017-06-02 00:07:25 +00:00
Madhu Venugopal 46db31de0a Network scoped alias support
Signed-off-by: Madhu Venugopal <madhu@docker.com>
2017-06-02 00:07:24 +00:00
Alessandro Boch d3aa590eec Add missing documentation for static IP options
Signed-off-by: Alessandro Boch <aboch@docker.com>
2017-06-02 00:07:23 +00:00
Madhu Venugopal bf03439e68 Docs update for link functionality in user-defined networks
Signed-off-by: Madhu Venugopal <madhu@docker.com>
2017-06-02 00:07:23 +00:00
Alessandro Boch 0a3c040a07 Allow user to choose the IP address for the container
Signed-off-by: Alessandro Boch <aboch@docker.com>
2017-06-02 00:07:22 +00:00
Sebastiaan van Stijn 31ad32c879 Fix pid=host example in documentation
The existing example didn't illustrate how to
install strace in the container. In addition,
the rhel7 image used is no longer public (and maintained)
so not a good image to use in the example.

This updates the example to use htop (strace is
not working without disabling apparmor for the container)

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2017-06-02 00:07:22 +00:00
Doug Davis 421578fbd4 remove =false from options that default to false in the docs
This re-aligns the docs with what the cmd line now does.

Signed-off-by: Doug Davis <dug@us.ibm.com>
2017-06-02 00:07:21 +00:00
Ma Shimiao 499d634f32 Add support for blkio read/write iops device
Signed-off-by: Ma Shimiao <mashimiao.fnst@cn.fujitsu.com>
2017-06-02 00:07:21 +00:00
Aidan Feldman 4620840d57 Update restart description
add a note around restart policies only working in detached mode

Signed-off-by: Aidan Feldman <aidan.feldman@gmail.com>

Update restart description with Mary's comments.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2017-06-02 00:07:21 +00:00
Vivek Goyal b2cbaa03af Add capability to specify mount propagation per volume
Allow passing mount propagation option shared, slave, or private as volume
property.

For example.
docker run -ti -v /root/mnt-source:/root/mnt-dest:slave fedora bash

Signed-off-by: Vivek Goyal <vgoyal@redhat.com>
2017-06-02 00:07:20 +00:00
Qiang Huang d9278dd4a8 Check minimum kernel memory limit to be 4M
Fixes: #18405

Signed-off-by: Qiang Huang <h.huangqiang@huawei.com>
2017-06-02 00:07:19 +00:00
Sebastiaan van Stijn 7071c15b5f docs: markdown and textual fixups in reference/run.md
This fixes markdown formatting, and formatting of tables;

 - Our markdown engine doesn't support spanning rows, so
   re-wrapped table contents.
 - Added a CSS-styles to prevent "code" blocks in tables
   from wrapping
 - The "logging drivers" table didn't have a header
 - Aligned table borders in source code for better readability.
 - Standardize on using `-it` in stead of -i -t or -ti
 - Some markup issues
 - Some minor textual fixups

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2017-06-02 00:07:19 +00:00
Ma Shimiao 9480c4763d Add support for blkio read/write bps device
Signed-off-by: Ma Shimiao <mashimiao.fnst@cn.fujitsu.com>
2017-06-02 00:07:19 +00:00
Wen Cheng Ma deae0706ea Add NETWORK_NAME_or_ID value for --net= option
Signed-off-by: Wen Cheng Ma <wenchma@cn.ibm.com>
2017-06-02 00:07:19 +00:00
Dan Walsh 65120e8851 This patch adds --tmpfs as a option for mounting tmpfs on directories
It will Tar up contents of child directory onto tmpfs if mounted over

This patch will use the new PreMount and PostMount hooks to "tar"
up the contents of the base image on top of tmpfs mount points.

Signed-off-by: Dan Walsh <dwalsh@redhat.com>
2017-06-02 00:07:18 +00:00
Kai Qiang Wu(Kennan) 4fbaeb5f25 Fixing the volume options doc
Fixes #15896
Signed-off-by: Kai Qiang Wu(Kennan) <wkqwu@cn.ibm.com>
2017-06-02 00:07:18 +00:00
NIWA Hideyuki fa2f024bc6 Addition of "--shm-size" to which size of /dev/shm is changed.
- Optional "--shm-size=" was added to the sub-command(run, create,and build).
- The size of /dev/shm in the container can be changed
  when container is made.
- Being able to specify is a numerical value that applies number,
  b, k, m, and g.
- The default value is 64MB, when this option is not set.
- It deals with both native and lxc drivers.

Signed-off-by: NIWA Hideyuki <niwa.hiedyuki@jp.fujitsu.com>
2017-06-02 00:07:18 +00:00
Ma Shimiao e303d6cc9f Add support for blkio.weight_device
Signed-off-by: Ma Shimiao <mashimiao.fnst@cn.fujitsu.com>
2017-06-02 00:07:17 +00:00
John Howard f5f5b31358 Removing made up word
Signed-off-by: John Howard <jhoward@microsoft.com>
2017-06-02 00:07:16 +00:00
David Calavera c5ed875bd9 Remove LXC support.
The LXC driver was deprecated in Docker 1.8.
Following the deprecation rules, we can remove a deprecated feature
after two major releases. LXC won't be supported anymore starting on Docker 1.10.

Signed-off-by: David Calavera <david.calavera@gmail.com>
2017-06-02 00:07:15 +00:00
Sally O'Malley c48ec056d5 Change 'docker run' exit codes to distinguish docker/contained errors
The purpose of this PR is for users to distinguish Docker errors from
contained command errors.
This PR modifies 'docker run' exit codes to follow the chroot standard
for exit codes.
Exit status:
125 if 'docker run' itself fails
126 if contained command cannot be invoked
127 if contained command cannot be found
the exit status otherwise

Signed-off-by: Sally O'Malley <somalley@redhat.com>
2017-06-02 00:07:15 +00:00