From 75f4fd978d234efbc3a5c5c55ea162a9a68246d9 Mon Sep 17 00:00:00 2001 From: Andy Rothfusz Date: Mon, 19 Aug 2013 19:13:26 -0700 Subject: [PATCH] Fix #1330 and #1149. Improve CMD, ENTRYPOINT, and attach docs. --- docs/sources/commandline/command/attach.rst | 48 ++++++++++- docs/sources/use/builder.rst | 96 +++++++++++++++++++-- 2 files changed, 134 insertions(+), 10 deletions(-) diff --git a/docs/sources/commandline/command/attach.rst b/docs/sources/commandline/command/attach.rst index 4c4c189d8f..12ed802a02 100644 --- a/docs/sources/commandline/command/attach.rst +++ b/docs/sources/commandline/command/attach.rst @@ -10,4 +10,50 @@ Usage: docker attach CONTAINER - Attach to a running container + Attach to a running container. + +You can detach from the container again (and leave it running) with +``CTRL-c`` (for a quiet exit) or ``CTRL-\`` to get a stacktrace of +the Docker client when it quits. + +To stop a container, use ``docker stop`` + +To kill the container, use ``docker kill`` + +Examples: +--------- + +.. code-block:: bash + + $ ID=$(sudo docker run -d ubuntu /usr/bin/top -b) + $ sudo docker attach $ID + top - 02:05:52 up 3:05, 0 users, load average: 0.01, 0.02, 0.05 + Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie + Cpu(s): 0.1%us, 0.2%sy, 0.0%ni, 99.7%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st + Mem: 373572k total, 355560k used, 18012k free, 27872k buffers + Swap: 786428k total, 0k used, 786428k free, 221740k cached + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 17200 1116 912 R 0 0.3 0:00.03 top + + top - 02:05:55 up 3:05, 0 users, load average: 0.01, 0.02, 0.05 + Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie + Cpu(s): 0.0%us, 0.2%sy, 0.0%ni, 99.8%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st + Mem: 373572k total, 355244k used, 18328k free, 27872k buffers + Swap: 786428k total, 0k used, 786428k free, 221776k cached + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top + + + top - 02:05:58 up 3:06, 0 users, load average: 0.01, 0.02, 0.05 + Tasks: 1 total, 1 running, 0 sleeping, 0 stopped, 0 zombie + Cpu(s): 0.2%us, 0.3%sy, 0.0%ni, 99.5%id, 0.0%wa, 0.0%hi, 0.0%si, 0.0%st + Mem: 373572k total, 355780k used, 17792k free, 27880k buffers + Swap: 786428k total, 0k used, 786428k free, 221776k cached + + PID USER PR NI VIRT RES SHR S %CPU %MEM TIME+ COMMAND + 1 root 20 0 17208 1144 932 R 0 0.3 0:00.03 top + ^C$ + $ sudo docker stop $ID + diff --git a/docs/sources/use/builder.rst b/docs/sources/use/builder.rst index de765a5467..fcb17c6c05 100644 --- a/docs/sources/use/builder.rst +++ b/docs/sources/use/builder.rst @@ -102,11 +102,50 @@ control. 3.4 CMD ------- - ``CMD `` +CMD has three forms: -The ``CMD`` instruction sets the command to be executed when running -the image. This is functionally equivalent to running ``docker commit --run '{"Cmd": }'`` outside the builder. +* ``CMD ["executable","param1","param2"]`` (like an *exec*, preferred form) +* ``CMD ["param1","param2"]`` (as *default parameters to ENTRYPOINT*) +* ``CMD command param1 param2`` (as a *shell*) + +There can only be one CMD in a Dockerfile. If you list more than one +CMD then only the last CMD will take effect. + +**The main purpose of a CMD is to provide defaults for an executing +container.** These defaults can include an executable, or they can +omit the executable, in which case you must specify an ENTRYPOINT as +well. + +When used in the shell or exec formats, the ``CMD`` instruction sets +the command to be executed when running the image. This is +functionally equivalent to running ``docker commit -run '{"Cmd": +}'`` outside the builder. + +If you use the *shell* form of the CMD, then the ```` will +execute in ``/bin/sh -c``: + +.. code-block:: bash + + FROM ubuntu + CMD echo "This is a test." | wc - + +If you want to **run your** ```` **without a shell** then you +must express the command as a JSON array and give the full path to the +executable. **This array form is the preferred format of CMD.** Any +additional parameters must be individually expressed as strings in the +array: + +.. code-block:: bash + + FROM ubuntu + CMD ["/usr/bin/wc","--help"] + +If you would like your container to run the same executable every +time, then you should consider using ``ENTRYPOINT`` in combination +with ``CMD``. See :ref:`entrypoint_def`. + +If the user specifies arguments to ``docker run`` then they will +override the default specified in CMD. .. note:: Don't confuse ``RUN`` with ``CMD``. ``RUN`` actually runs a @@ -186,16 +225,55 @@ The copy obeys the following rules: directories in its path. All new files and directories are created with mode 0755, uid and gid 0. +.. _entrypoint_def: + 3.8 ENTRYPOINT -------------- - ``ENTRYPOINT ["/bin/echo"]`` +ENTRYPOINT has two forms: -The ``ENTRYPOINT`` instruction adds an entry command that will not be -overwritten when arguments are passed to docker run, unlike the +* ``ENTRYPOINT ["executable", "param1", "param2"]`` (like an *exec*, + preferred form) +* ``ENTRYPOINT command param1 param2`` (as a *shell*) + +There can only be one ``ENTRYPOINT`` in a Dockerfile. If you have more +than one ``ENTRYPOINT``, then only the last one in the Dockerfile will +have an effect. + +An ``ENTRYPOINT`` helps you to configure a container that you can run +as an executable. That is, when you specify an ``ENTRYPOINT``, then +the whole container runs as if it was just that executable. + +The ``ENTRYPOINT`` instruction adds an entry command that will **not** +be overwritten when arguments are passed to ``docker run``, unlike the behavior of ``CMD``. This allows arguments to be passed to the -entrypoint. i.e. ``docker run -d`` will pass the "-d" argument -to the entrypoint. +entrypoint. i.e. ``docker run -d`` will pass the "-d" +argument to the ENTRYPOINT. + +You can specify parameters either in the ENTRYPOINT JSON array (as in +"like an exec" above), or by using a CMD statement. Parameters in the +ENTRYPOINT will not be overridden by the ``docker run`` arguments, but +parameters specified via CMD will be overridden by ``docker run`` +arguments. + +Like a ``CMD``, you can specify a plain string for the ENTRYPOINT and +it will execute in ``/bin/sh -c``: + +.. code-block:: bash + + FROM ubuntu + ENTRYPOINT wc -l - + +For example, that Dockerfile's image will *always* take stdin as input +("-") and print the number of lines ("-l"). If you wanted to make +this optional but default, you could use a CMD: + +.. code-block:: bash + + FROM ubuntu + CMD ["-l", "-"] + ENTRYPOINT ["/usr/bin/wc"] + 3.9 VOLUME ----------