From c48ec056d574e706651dd6f1d7351d258150545f Mon Sep 17 00:00:00 2001 From: Sally O'Malley Date: Wed, 29 Jul 2015 08:21:16 -0400 Subject: [PATCH] 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 --- docs/reference/run.md | 32 ++++++++++++++++++++++++++++++++ man/docker-run.1.md | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) diff --git a/docs/reference/run.md b/docs/reference/run.md index 1693e52cc7..a6e5fe124d 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -518,6 +518,38 @@ non-zero exit status more than 10 times in a row Docker will abort trying to restart the container. Providing a maximum restart limit is only valid for the **on-failure** policy. +## Exit Status + +The exit code from `docker run` gives information about why the container +failed to run or why it exited. When `docker run` exits with a non-zero code, +the exit codes follow the `chroot` standard, see below: + +**_125_** if the error is with Docker daemon **_itself_** + + $ docker run --foo busybox; echo $? + # flag provided but not defined: --foo + See 'docker run --help'. + 125 + +**_126_** if the **_contained command_** cannot be invoked + + $ docker run busybox /etc; echo $? + # exec: "/etc": permission denied + docker: Error response from daemon: Contained command could not be invoked + 126 + +**_127_** if the **_contained command_** cannot be found + + $ docker run busybox foo; echo $? + # exec: "foo": executable file not found in $PATH + docker: Error response from daemon: Contained command not found or does not exist + 127 + +**_Exit code_** of **_contained command_** otherwise + + $ docker run busybox /bin/sh -c 'exit 3' + # 3 + ## Clean up (--rm) By default a container's file system persists even after the container diff --git a/man/docker-run.1.md b/man/docker-run.1.md index e556ecfbd6..1fdb1bc7d8 100644 --- a/man/docker-run.1.md +++ b/man/docker-run.1.md @@ -508,6 +508,38 @@ running binaries within a container is the root directory (/). The developer can set a different default with the Dockerfile WORKDIR instruction. The operator can override the working directory by using the **-w** option. +# Exit Status + +The exit code from `docker run` gives information about why the container +failed to run or why it exited. When `docker run` exits with a non-zero code, +the exit codes follow the `chroot` standard, see below: + +**_125_** if the error is with Docker daemon **_itself_** + + $ docker run --foo busybox; echo $? + # flag provided but not defined: --foo + See 'docker run --help'. + 125 + +**_126_** if the **_contained command_** cannot be invoked + + $ docker run busybox /etc; echo $? + # exec: "/etc": permission denied + docker: Error response from daemon: Contained command could not be invoked + 126 + +**_127_** if the **_contained command_** cannot be found + + $ docker run busybox foo; echo $? + # exec: "foo": executable file not found in $PATH + docker: Error response from daemon: Contained command not found or does not exist + 127 + +**_Exit code_** of **_contained command_** otherwise + + $ docker run busybox /bin/sh -c 'exit 3' + # 3 + # EXAMPLES ## Exposing log messages from the container to the host's log @@ -732,3 +764,4 @@ April 2014, Originally compiled by William Henry (whenry at redhat dot com) based on docker.com source material and internal work. June 2014, updated by Sven Dowideit July 2014, updated by Sven Dowideit +November 2015, updated by Sally O'Malley