1. docker
  2. Commit 75f4fd978d234efbc3a5c5c55ea162a9a68246d9
Browse code

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

Andy Rothfusz authored on 2013/08/20 11:13:26
Showing 2 changed files
docs/sources/commandline/command/attach.rst
History View file @ 75f4fd9
... ... 
@@ -10,4 +10,50 @@
10 10
11 11 
     Usage: docker attach CONTAINER
12 12
13 
-    Attach to a running container
13 
+    Attach to a running container.
14 
+
15 
+You can detach from the container again (and leave it running) with
16 
+``CTRL-c`` (for a quiet exit) or ``CTRL-\`` to get a stacktrace of
17 
+the Docker client when it quits.
18 
+
19 
+To stop a container, use ``docker stop``
20 
+
21 
+To kill the container, use ``docker kill``
22 
+
23 
+Examples:
24 
+---------
25 
+
26 
+.. code-block:: bash
27 
+
28 
+     $ ID=$(sudo docker run -d ubuntu /usr/bin/top -b)
29 
+     $ sudo docker attach $ID
30 
+     top - 02:05:52 up  3:05,  0 users,  load average: 0.01, 0.02, 0.05
31 
+     Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
32 
+     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
33 
+     Mem:    373572k total,   355560k used,    18012k free,    27872k buffers
34 
+     Swap:   786428k total,        0k used,   786428k free,   221740k cached
35 
+
36 
+     PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
37 
+      1 root      20   0 17200 1116  912 R    0  0.3   0:00.03 top
38 
+
39 
+      top - 02:05:55 up  3:05,  0 users,  load average: 0.01, 0.02, 0.05
40 
+      Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
41 
+      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
42 
+      Mem:    373572k total,   355244k used,    18328k free,    27872k buffers
43 
+      Swap:   786428k total,        0k used,   786428k free,   221776k cached
44 
+
45 
+        PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
46 
+	    1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
47 
+
48 
+
49 
+      top - 02:05:58 up  3:06,  0 users,  load average: 0.01, 0.02, 0.05
50 
+      Tasks:   1 total,   1 running,   0 sleeping,   0 stopped,   0 zombie
51 
+      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
52 
+      Mem:    373572k total,   355780k used,    17792k free,    27880k buffers
53 
+      Swap:   786428k total,        0k used,   786428k free,   221776k cached
54 
+
55 
+      PID USER      PR  NI  VIRT  RES  SHR S %CPU %MEM    TIME+  COMMAND
56 
+           1 root      20   0 17208 1144  932 R    0  0.3   0:00.03 top
57 
+     ^C$
58 
+     $ sudo docker stop $ID
59 
+
docs/sources/use/builder.rst
History View file @ 75f4fd9
... ... 
@@ -102,11 +102,50 @@ control.
102 102 
 3.4 CMD
103 103 
 -------
104 104
105 
-    ``CMD <command>``
105 
+CMD has three forms:
106 106
107 
-The ``CMD`` instruction sets the command to be executed when running
108 
-the image.  This is functionally equivalent to running ``docker commit
109 
--run '{"Cmd": <command>}'`` outside the builder.
107 
+* ``CMD ["executable","param1","param2"]`` (like an *exec*, preferred form)
108 
+* ``CMD ["param1","param2"]`` (as *default parameters to ENTRYPOINT*)
109 
+* ``CMD command param1 param2`` (as a *shell*)
110 
+
111 
+There can only be one CMD in a Dockerfile. If you list more than one
112 
+CMD then only the last CMD will take effect.
113 
+
114 
+**The main purpose of a CMD is to provide defaults for an executing
115 
+container.** These defaults can include an executable, or they can
116 
+omit the executable, in which case you must specify an ENTRYPOINT as
117 
+well.
118 
+
119 
+When used in the shell or exec formats, the ``CMD`` instruction sets
120 
+the command to be executed when running the image.  This is
121 
+functionally equivalent to running ``docker commit -run '{"Cmd":
122 
+<command>}'`` outside the builder.
123 
+
124 
+If you use the *shell* form of the CMD, then the ``<command>`` will
125 
+execute in ``/bin/sh -c``:
126 
+
127 
+.. code-block:: bash
128 
+
129 
+    FROM ubuntu
130 
+    CMD echo "This is a test." | wc -
131 
+
132 
+If you want to **run your** ``<command>`` **without a shell** then you
133 
+must express the command as a JSON array and give the full path to the
134 
+executable. **This array form is the preferred format of CMD.** Any
135 
+additional parameters must be individually expressed as strings in the
136 
+array:
137 
+
138 
+.. code-block:: bash
139 
+
140 
+    FROM ubuntu
141 
+    CMD ["/usr/bin/wc","--help"]
142 
+
143 
+If you would like your container to run the same executable every
144 
+time, then you should consider using ``ENTRYPOINT`` in combination
145 
+with ``CMD``. See :ref:`entrypoint_def`.
146 
+
147 
+If the user specifies arguments to ``docker run`` then they will
148 
+override the default specified in CMD.
110 149
111 150 
 .. note::
112 151 
     Don't confuse ``RUN`` with ``CMD``. ``RUN`` actually runs a
... ... 
@@ -186,16 +225,55 @@ The copy obeys the following rules:
186 186 
   directories in its path. All new files and directories are created
187 187 
   with mode 0755, uid and gid 0.
188 188
189 
+.. _entrypoint_def:
190 
+
189 191 
 3.8 ENTRYPOINT
190 192 
 --------------
191 193
192 
-    ``ENTRYPOINT ["/bin/echo"]``
194 
+ENTRYPOINT has two forms:
193 195
194 
-The ``ENTRYPOINT`` instruction adds an entry command that will not be
195 
-overwritten when arguments are passed to docker run, unlike the
196 
+* ``ENTRYPOINT ["executable", "param1", "param2"]`` (like an *exec*,
197 
+  preferred form)
198 
+* ``ENTRYPOINT command param1 param2`` (as a *shell*)
199 
+
200 
+There can only be one ``ENTRYPOINT`` in a Dockerfile. If you have more
201 
+than one ``ENTRYPOINT``, then only the last one in the Dockerfile will
202 
+have an effect.
203 
+
204 
+An ``ENTRYPOINT`` helps you to configure a container that you can run
205 
+as an executable. That is, when you specify an ``ENTRYPOINT``, then
206 
+the whole container runs as if it was just that executable.
207 
+
208 
+The ``ENTRYPOINT`` instruction adds an entry command that will **not**
209 
+be overwritten when arguments are passed to ``docker run``, unlike the
196 210 
 behavior of ``CMD``.  This allows arguments to be passed to the
197 
-entrypoint.  i.e. ``docker run <image> -d`` will pass the "-d" argument
198 
-to the entrypoint.
211 
+entrypoint.  i.e. ``docker run <image> -d`` will pass the "-d"
212 
+argument to the ENTRYPOINT.
213 
+
214 
+You can specify parameters either in the ENTRYPOINT JSON array (as in
215 
+"like an exec" above), or by using a CMD statement. Parameters in the
216 
+ENTRYPOINT will not be overridden by the ``docker run`` arguments, but
217 
+parameters specified via CMD will be overridden by ``docker run``
218 
+arguments.
219 
+
220 
+Like a ``CMD``, you can specify a plain string for the ENTRYPOINT and
221 
+it will execute in ``/bin/sh -c``:
222 
+
223 
+.. code-block:: bash
224 
+
225 
+    FROM ubuntu
226 
+    ENTRYPOINT wc -l -
227 
+
228 
+For example, that Dockerfile's image will *always* take stdin as input
229 
+("-") and print the number of lines ("-l"). If you wanted to make
230 
+this optional but default, you could use a CMD:
231 
+
232 
+.. code-block:: bash
233 
+
234 
+    FROM ubuntu
235 
+    CMD ["-l", "-"]
236 
+    ENTRYPOINT ["/usr/bin/wc"]
237 
+
199 238
200 239 
 3.9 VOLUME
201 240 
 ----------