Fix #1330 and #1149. Improve CMD, ENTRYPOINT, and attach docs.

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
+

docs/sources/use/builder.rst

@@ -102,11 +102,50 @@ control.
 3.4 CMD
 -------
 
-    ``CMD <command>``
+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": <command>}'`` 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":
+<command>}'`` outside the builder.
+
+If you use the *shell* form of the CMD, then the ``<command>`` will
+execute in ``/bin/sh -c``:
+
+.. code-block:: bash
+
+    FROM ubuntu
+    CMD echo "This is a test." | wc -
+
+If you want to **run your** ``<command>`` **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 <image> -d`` will pass the "-d" argument
-to the entrypoint.
+entrypoint.  i.e. ``docker run <image> -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
 ----------