1. docker
  2. Commit 6d5b73c2a6d668b11d6b5c643a45170265bf73c0
Browse code

update "images" documentation

Nate Jones authored on 2013/10/28 13:02:24
Showing 3 changed files
docs/sources/api/docker_remote_api.rst
History View file @ 6d5b73c
... ... 
@@ -26,14 +26,118 @@ Docker Remote API
26 26 
 2. Versions
27 27 
 ===========
28 28
29 
-The current version of the API is 1.6
29 
+The current version of the API is 1.7
30 30
31 31 
 Calling /images/<name>/insert is the same as calling
32 
-/v1.6/images/<name>/insert
32 
+/v1.7/images/<name>/insert
33 33
34 34 
 You can still call an old version of the api using
35 35 
 /v1.0/images/<name>/insert
36 36
37 
+v1.7
38 
+****
39 
+
40 
+Full Documentation
41 
+------------------
42 
+
43 
+:doc:`docker_remote_api_v1.7`
44 
+
45 
+What's new
46 
+----------
47 
+
48 
+.. http:get:: /images/json
49 
+
50 
+   The format of the json returned from this uri changed.  Instead of an entry
51 
+   for each repo/tag on an image, each image is only represented once, with a
52 
+   nested attribute indicating the repo/tags that apply to that image.
53 
+
54 
+   Instead of:
55 
+
56 
+   .. sourcecode:: http
57 
+
58 
+      HTTP/1.1 200 OK
59 
+      Content-Type: application/json
60 
+
61 
+      [
62 
+        {
63 
+          "VirtualSize": 131506275,
64 
+          "Size": 131506275,
65 
+          "Created": 1365714795,
66 
+          "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
67 
+          "Tag": "12.04",
68 
+          "Repository": "ubuntu"
69 
+        },
70 
+        {
71 
+          "VirtualSize": 131506275,
72 
+          "Size": 131506275,
73 
+          "Created": 1365714795,
74 
+          "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
75 
+          "Tag": "latest",
76 
+          "Repository": "ubuntu"
77 
+        },
78 
+        {
79 
+          "VirtualSize": 131506275,
80 
+          "Size": 131506275,
81 
+          "Created": 1365714795,
82 
+          "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
83 
+          "Tag": "precise",
84 
+          "Repository": "ubuntu"
85 
+        },
86 
+        {
87 
+          "VirtualSize": 180116135,
88 
+          "Size": 24653,
89 
+          "Created": 1364102658,
90 
+          "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
91 
+          "Tag": "12.10",
92 
+          "Repository": "ubuntu"
93 
+        },
94 
+        {
95 
+          "VirtualSize": 180116135,
96 
+          "Size": 24653,
97 
+          "Created": 1364102658,
98 
+          "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
99 
+          "Tag": "quantal",
100 
+          "Repository": "ubuntu"
101 
+        }
102 
+      ]
103 
+
104 
+   The returned json looks like this:
105 
+
106 
+   .. sourcecode:: http
107 
+
108 
+      HTTP/1.1 200 OK
109 
+      Content-Type: application/json
110 
+
111 
+      [
112 
+        {
113 
+           "RepoTag": [
114 
+             "ubuntu:12.04",
115 
+             "ubuntu:precise",
116 
+             "ubuntu:latest"
117 
+           ],
118 
+           "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
119 
+           "Created": 1365714795,
120 
+           "Size": 131506275,
121 
+           "VirtualSize": 131506275
122 
+        },
123 
+        {
124 
+           "RepoTag": [
125 
+             "ubuntu:12.10",
126 
+             "ubuntu:quantal"
127 
+           ],
128 
+           "ParentId": "27cf784147099545",
129 
+           "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
130 
+           "Created": 1364102658,
131 
+           "Size": 24653,
132 
+           "VirtualSize": 180116135
133 
+        }
134 
+      ]
135 
+
136 
+.. http:get:: /images/viz
137 
+
138 
+   This URI no longer exists.  The ``images -viz`` output is now generated in
139 
+   the client, using the ``/images/json`` data.
140 
+
37 141 
 v1.6
38 142 
 ****
39 143
docs/sources/api/docker_remote_api_v1.7.rst
History View file @ 6d5b73c
40 144 
new file mode 100644
... ... 
@@ -0,0 +1,1187 @@
0 
+:title: Remote API v1.7
1 
+:description: API Documentation for Docker
2 
+:keywords: API, Docker, rcli, REST, documentation
3 
+
4 
+:orphan:
5 
+
6 
+======================
7 
+Docker Remote API v1.7
8 
+======================
9 
+
10 
+.. contents:: Table of Contents
11 
+
12 
+1. Brief introduction
13 
+=====================
14 
+
15 
+- The Remote API is replacing rcli
16 
+- Default port in the docker daemon is 4243
17 
+- The API tends to be REST, but for some complex commands, like attach or pull, the HTTP connection is hijacked to transport stdout stdin and stderr
18 
+
19 
+2. Endpoints
20 
+============
21 
+
22 
+2.1 Containers
23 
+--------------
24 
+
25 
+List containers
26 
+***************
27 
+
28 
+.. http:get:: /containers/json
29 
+
30 
+	List containers
31 
+
32 
+	**Example request**:
33 
+
34 
+	.. sourcecode:: http
35 
+
36 
+	   GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1
37 
+
38 
+	**Example response**:
39 
+
40 
+	.. sourcecode:: http
41 
+
42 
+	   HTTP/1.1 200 OK
43 
+	   Content-Type: application/json
44 
+
45 
+	   [
46 
+		{
47 
+			"Id": "8dfafdbc3a40",
48 
+			"Image": "base:latest",
49 
+			"Command": "echo 1",
50 
+			"Created": 1367854155,
51 
+			"Status": "Exit 0",
52 
+			"Ports":[{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}],
53 
+			"SizeRw":12288,
54 
+			"SizeRootFs":0
55 
+		},
56 
+		{
57 
+			"Id": "9cd87474be90",
58 
+			"Image": "base:latest",
59 
+			"Command": "echo 222222",
60 
+			"Created": 1367854155,
61 
+			"Status": "Exit 0",
62 
+			"Ports":[],
63 
+			"SizeRw":12288,
64 
+			"SizeRootFs":0
65 
+		},
66 
+		{
67 
+			"Id": "3176a2479c92",
68 
+			"Image": "base:latest",
69 
+			"Command": "echo 3333333333333333",
70 
+			"Created": 1367854154,
71 
+			"Status": "Exit 0",
72 
+			"Ports":[],
73 
+			"SizeRw":12288,
74 
+			"SizeRootFs":0
75 
+		},
76 
+		{
77 
+			"Id": "4cb07b47f9fb",
78 
+			"Image": "base:latest",
79 
+			"Command": "echo 444444444444444444444444444444444",
80 
+			"Created": 1367854152,
81 
+			"Status": "Exit 0",
82 
+			"Ports":[],
83 
+			"SizeRw":12288,
84 
+			"SizeRootFs":0
85 
+		}
86 
+	   ]
87 
+
88 
+	:query all: 1/True/true or 0/False/false, Show all containers. Only running containers are shown by default
89 
+	:query limit: Show ``limit`` last created containers, include non-running ones.
90 
+	:query since: Show only containers created since Id, include non-running ones.
91 
+	:query before: Show only containers created before Id, include non-running ones.
92 
+	:query size: 1/True/true or 0/False/false, Show the containers sizes
93 
+	:statuscode 200: no error
94 
+	:statuscode 400: bad parameter
95 
+	:statuscode 500: server error
96 
+
97 
+
98 
+Create a container
99 
+******************
100 
+
101 
+.. http:post:: /containers/create
102 
+
103 
+	Create a container
104 
+
105 
+	**Example request**:
106 
+
107 
+	.. sourcecode:: http
108 
+
109 
+	   POST /containers/create HTTP/1.1
110 
+	   Content-Type: application/json
111 
+
112 
+	   {
113 
+		"Hostname":"",
114 
+		"User":"",
115 
+		"Memory":0,
116 
+		"MemorySwap":0,
117 
+		"AttachStdin":false,
118 
+		"AttachStdout":true,
119 
+		"AttachStderr":true,
120 
+		"PortSpecs":null,
121 
+		"Privileged": false,
122 
+		"Tty":false,
123 
+		"OpenStdin":false,
124 
+		"StdinOnce":false,
125 
+		"Env":null,
126 
+		"Cmd":[
127 
+			"date"
128 
+		],
129 
+		"Dns":null,
130 
+		"Image":"base",
131 
+		"Volumes":{},
132 
+		"VolumesFrom":"",
133 
+		"WorkingDir":""
134 
+
135 
+	   }
136 
+
137 
+	**Example response**:
138 
+
139 
+	.. sourcecode:: http
140 
+
141 
+	   HTTP/1.1 201 OK
142 
+	   Content-Type: application/json
143 
+
144 
+	   {
145 
+		"Id":"e90e34656806"
146 
+		"Warnings":[]
147 
+	   }
148 
+
149 
+	:jsonparam config: the container's configuration
150 
+	:statuscode 201: no error
151 
+	:statuscode 404: no such container
152 
+	:statuscode 406: impossible to attach (container not running)
153 
+	:statuscode 500: server error
154 
+
155 
+
156 
+Inspect a container
157 
+*******************
158 
+
159 
+.. http:get:: /containers/(id)/json
160 
+
161 
+	Return low-level information on the container ``id``
162 
+
163 
+	**Example request**:
164 
+
165 
+	.. sourcecode:: http
166 
+
167 
+	   GET /containers/4fa6e0f0c678/json HTTP/1.1
168 
+
169 
+	**Example response**:
170 
+
171 
+	.. sourcecode:: http
172 
+
173 
+	   HTTP/1.1 200 OK
174 
+	   Content-Type: application/json
175 
+
176 
+	   {
177 
+			"Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2",
178 
+			"Created": "2013-05-07T14:51:42.041847+02:00",
179 
+			"Path": "date",
180 
+			"Args": [],
181 
+			"Config": {
182 
+				"Hostname": "4fa6e0f0c678",
183 
+				"User": "",
184 
+				"Memory": 0,
185 
+				"MemorySwap": 0,
186 
+				"AttachStdin": false,
187 
+				"AttachStdout": true,
188 
+				"AttachStderr": true,
189 
+				"PortSpecs": null,
190 
+				"Tty": false,
191 
+				"OpenStdin": false,
192 
+				"StdinOnce": false,
193 
+				"Env": null,
194 
+				"Cmd": [
195 
+					"date"
196 
+				],
197 
+				"Dns": null,
198 
+				"Image": "base",
199 
+				"Volumes": {},
200 
+				"VolumesFrom": "",
201 
+				"WorkingDir":""
202 
+
203 
+			},
204 
+			"State": {
205 
+				"Running": false,
206 
+				"Pid": 0,
207 
+				"ExitCode": 0,
208 
+				"StartedAt": "2013-05-07T14:51:42.087658+02:01360",
209 
+				"Ghost": false
210 
+			},
211 
+			"Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
212 
+			"NetworkSettings": {
213 
+				"IpAddress": "",
214 
+				"IpPrefixLen": 0,
215 
+				"Gateway": "",
216 
+				"Bridge": "",
217 
+				"PortMapping": null
218 
+			},
219 
+			"SysInitPath": "/home/kitty/go/src/github.com/dotcloud/docker/bin/docker",
220 
+			"ResolvConfPath": "/etc/resolv.conf",
221 
+			"Volumes": {}
222 
+	   }
223 
+
224 
+	:statuscode 200: no error
225 
+	:statuscode 404: no such container
226 
+	:statuscode 500: server error
227 
+
228 
+
229 
+List processes running inside a container
230 
+*****************************************
231 
+
232 
+.. http:get:: /containers/(id)/top
233 
+
234 
+	List processes running inside the container ``id``
235 
+
236 
+	**Example request**:
237 
+
238 
+	.. sourcecode:: http
239 
+
240 
+	   GET /containers/4fa6e0f0c678/top HTTP/1.1
241 
+
242 
+	**Example response**:
243 
+
244 
+	.. sourcecode:: http
245 
+
246 
+	   HTTP/1.1 200 OK
247 
+	   Content-Type: application/json
248 
+
249 
+	   {
250 
+		"Titles":[
251 
+			"USER",
252 
+			"PID",
253 
+			"%CPU",
254 
+			"%MEM",
255 
+			"VSZ",
256 
+			"RSS",
257 
+			"TTY",
258 
+			"STAT",
259 
+			"START",
260 
+			"TIME",
261 
+			"COMMAND"
262 
+			],
263 
+		"Processes":[
264 
+			["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"],
265 
+			["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"]
266 
+		]
267 
+	   }
268 
+
269 
+	:query ps_args: ps arguments to use (eg. aux)
270 
+	:statuscode 200: no error
271 
+	:statuscode 404: no such container
272 
+	:statuscode 500: server error
273 
+
274 
+
275 
+Inspect changes on a container's filesystem
276 
+*******************************************
277 
+
278 
+.. http:get:: /containers/(id)/changes
279 
+
280 
+	Inspect changes on container ``id`` 's filesystem
281 
+
282 
+	**Example request**:
283 
+
284 
+	.. sourcecode:: http
285 
+
286 
+	   GET /containers/4fa6e0f0c678/changes HTTP/1.1
287 
+
288 
+
289 
+	**Example response**:
290 
+
291 
+	.. sourcecode:: http
292 
+
293 
+	   HTTP/1.1 200 OK
294 
+	   Content-Type: application/json
295 
+
296 
+	   [
297 
+		{
298 
+			"Path":"/dev",
299 
+			"Kind":0
300 
+		},
301 
+		{
302 
+			"Path":"/dev/kmsg",
303 
+			"Kind":1
304 
+		},
305 
+		{
306 
+			"Path":"/test",
307 
+			"Kind":1
308 
+		}
309 
+	   ]
310 
+
311 
+	:statuscode 200: no error
312 
+	:statuscode 404: no such container
313 
+	:statuscode 500: server error
314 
+
315 
+
316 
+Export a container
317 
+******************
318 
+
319 
+.. http:get:: /containers/(id)/export
320 
+
321 
+	Export the contents of container ``id``
322 
+
323 
+	**Example request**:
324 
+
325 
+	.. sourcecode:: http
326 
+
327 
+	   GET /containers/4fa6e0f0c678/export HTTP/1.1
328 
+
329 
+
330 
+	**Example response**:
331 
+
332 
+	.. sourcecode:: http
333 
+
334 
+	   HTTP/1.1 200 OK
335 
+	   Content-Type: application/octet-stream
336 
+
337 
+	   {{ STREAM }}
338 
+
339 
+	:statuscode 200: no error
340 
+	:statuscode 404: no such container
341 
+	:statuscode 500: server error
342 
+
343 
+
344 
+Start a container
345 
+*****************
346 
+
347 
+.. http:post:: /containers/(id)/start
348 
+
349 
+        Start the container ``id``
350 
+
351 
+        **Example request**:
352 
+
353 
+        .. sourcecode:: http
354 
+
355 
+           POST /containers/(id)/start HTTP/1.1
356 
+           Content-Type: application/json
357 
+
358 
+           {
359 
+                "Binds":["/tmp:/tmp"],
360 
+                "LxcConf":{"lxc.utsname":"docker"}
361 
+           }
362 
+
363 
+        **Example response**:
364 
+
365 
+        .. sourcecode:: http
366 
+
367 
+           HTTP/1.1 204 No Content
368 
+           Content-Type: text/plain
369 
+
370 
+        :jsonparam hostConfig: the container's host configuration (optional)
371 
+        :statuscode 204: no error
372 
+        :statuscode 404: no such container
373 
+        :statuscode 500: server error
374 
+
375 
+
376 
+Stop a container
377 
+****************
378 
+
379 
+.. http:post:: /containers/(id)/stop
380 
+
381 
+	Stop the container ``id``
382 
+
383 
+	**Example request**:
384 
+
385 
+	.. sourcecode:: http
386 
+
387 
+	   POST /containers/e90e34656806/stop?t=5 HTTP/1.1
388 
+
389 
+	**Example response**:
390 
+
391 
+	.. sourcecode:: http
392 
+
393 
+	   HTTP/1.1 204 OK
394 
+
395 
+	:query t: number of seconds to wait before killing the container
396 
+	:statuscode 204: no error
397 
+	:statuscode 404: no such container
398 
+	:statuscode 500: server error
399 
+
400 
+
401 
+Restart a container
402 
+*******************
403 
+
404 
+.. http:post:: /containers/(id)/restart
405 
+
406 
+	Restart the container ``id``
407 
+
408 
+	**Example request**:
409 
+
410 
+	.. sourcecode:: http
411 
+
412 
+	   POST /containers/e90e34656806/restart?t=5 HTTP/1.1
413 
+
414 
+	**Example response**:
415 
+
416 
+	.. sourcecode:: http
417 
+
418 
+	   HTTP/1.1 204 OK
419 
+
420 
+	:query t: number of seconds to wait before killing the container
421 
+	:statuscode 204: no error
422 
+	:statuscode 404: no such container
423 
+	:statuscode 500: server error
424 
+
425 
+
426 
+Kill a container
427 
+****************
428 
+
429 
+.. http:post:: /containers/(id)/kill
430 
+
431 
+	Kill the container ``id``
432 
+
433 
+	**Example request**:
434 
+
435 
+	.. sourcecode:: http
436 
+
437 
+	   POST /containers/e90e34656806/kill HTTP/1.1
438 
+
439 
+	**Example response**:
440 
+
441 
+	.. sourcecode:: http
442 
+
443 
+	   HTTP/1.1 204 OK
444 
+
445 
+	:statuscode 204: no error
446 
+	:statuscode 404: no such container
447 
+	:statuscode 500: server error
448 
+
449 
+
450 
+Attach to a container
451 
+*********************
452 
+
453 
+.. http:post:: /containers/(id)/attach
454 
+
455 
+	Attach to the container ``id``
456 
+
457 
+	**Example request**:
458 
+
459 
+	.. sourcecode:: http
460 
+
461 
+	   POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1
462 
+
463 
+	**Example response**:
464 
+
465 
+	.. sourcecode:: http
466 
+
467 
+	   HTTP/1.1 200 OK
468 
+	   Content-Type: application/vnd.docker.raw-stream
469 
+
470 
+	   {{ STREAM }}
471 
+
472 
+	:query logs: 1/True/true or 0/False/false, return logs. Default false
473 
+	:query stream: 1/True/true or 0/False/false, return stream. Default false
474 
+	:query stdin: 1/True/true or 0/False/false, if stream=true, attach to stdin. Default false
475 
+	:query stdout: 1/True/true or 0/False/false, if logs=true, return stdout log, if stream=true, attach to stdout. Default false
476 
+	:query stderr: 1/True/true or 0/False/false, if logs=true, return stderr log, if stream=true, attach to stderr. Default false
477 
+	:statuscode 200: no error
478 
+	:statuscode 400: bad parameter
479 
+	:statuscode 404: no such container
480 
+	:statuscode 500: server error
481 
+
482 
+	**Stream details**:
483 
+
484 
+	When using the TTY setting is enabled in
485 
+	:http:post:`/containers/create`, the stream is the raw data
486 
+	from the process PTY and client's stdin.  When the TTY is
487 
+	disabled, then the stream is multiplexed to separate stdout
488 
+	and stderr.
489 
+
490 
+	The format is a **Header** and a **Payload** (frame).
491 
+
492 
+	**HEADER**
493 
+
494 
+	The header will contain the information on which stream write
495 
+	the stream (stdout or stderr). It also contain the size of
496 
+	the associated frame encoded on the last 4 bytes (uint32).
497 
+
498 
+	It is encoded on the first 8 bytes like this::
499 
+
500 
+	    header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
501 
+
502 
+	``STREAM_TYPE`` can be:
503 
+
504 
+	- 0: stdin (will be writen on stdout)
505 
+	- 1: stdout
506 
+	- 2: stderr
507 
+
508 
+	``SIZE1, SIZE2, SIZE3, SIZE4`` are the 4 bytes of the uint32 size encoded as big endian.
509 
+
510 
+	**PAYLOAD**
511 
+
512 
+	The payload is the raw stream.
513 
+
514 
+	**IMPLEMENTATION**
515 
+
516 
+	The simplest way to implement the Attach protocol is the following:
517 
+
518 
+	1) Read 8 bytes
519 
+	2) chose stdout or stderr depending on the first byte
520 
+	3) Extract the frame size from the last 4 byets
521 
+	4) Read the extracted size and output it on the correct output
522 
+	5) Goto 1)
523 
+
524 
+
525 
+
526 
+Wait a container
527 
+****************
528 
+
529 
+.. http:post:: /containers/(id)/wait
530 
+
531 
+	Block until container ``id`` stops, then returns the exit code
532 
+
533 
+	**Example request**:
534 
+
535 
+	.. sourcecode:: http
536 
+
537 
+	   POST /containers/16253994b7c4/wait HTTP/1.1
538 
+
539 
+	**Example response**:
540 
+
541 
+	.. sourcecode:: http
542 
+
543 
+	   HTTP/1.1 200 OK
544 
+	   Content-Type: application/json
545 
+
546 
+	   {"StatusCode":0}
547 
+
548 
+	:statuscode 200: no error
549 
+	:statuscode 404: no such container
550 
+	:statuscode 500: server error
551 
+
552 
+
553 
+Remove a container
554 
+*******************
555 
+
556 
+.. http:delete:: /containers/(id)
557 
+
558 
+	Remove the container ``id`` from the filesystem
559 
+
560 
+	**Example request**:
561 
+
562 
+        .. sourcecode:: http
563 
+
564 
+           DELETE /containers/16253994b7c4?v=1 HTTP/1.1
565 
+
566 
+        **Example response**:
567 
+
568 
+        .. sourcecode:: http
569 
+
570 
+	   HTTP/1.1 204 OK
571 
+
572 
+	:query v: 1/True/true or 0/False/false, Remove the volumes associated to the container. Default false
573 
+        :statuscode 204: no error
574 
+	:statuscode 400: bad parameter
575 
+        :statuscode 404: no such container
576 
+        :statuscode 500: server error
577 
+
578 
+
579 
+Copy files or folders from a container
580 
+**************************************
581 
+
582 
+.. http:post:: /containers/(id)/copy
583 
+
584 
+	Copy files or folders of container ``id``
585 
+
586 
+	**Example request**:
587 
+
588 
+	.. sourcecode:: http
589 
+
590 
+	   POST /containers/4fa6e0f0c678/copy HTTP/1.1
591 
+	   Content-Type: application/json
592 
+
593 
+	   {
594 
+		"Resource":"test.txt"
595 
+	   }
596 
+
597 
+	**Example response**:
598 
+
599 
+	.. sourcecode:: http
600 
+
601 
+	   HTTP/1.1 200 OK
602 
+	   Content-Type: application/octet-stream
603 
+
604 
+	   {{ STREAM }}
605 
+
606 
+	:statuscode 200: no error
607 
+	:statuscode 404: no such container
608 
+	:statuscode 500: server error
609 
+
610 
+
611 
+2.2 Images
612 
+----------
613 
+
614 
+List Images
615 
+***********
616 
+
617 
+.. http:get:: /images/(format)
618 
+
619 
+	List images ``format`` could be json or viz (json default)
620 
+
621 
+	**Example request**:
622 
+
623 
+	.. sourcecode:: http
624 
+
625 
+	   GET /images/json?all=0 HTTP/1.1
626 
+
627 
+	**Example response**:
628 
+
629 
+	.. sourcecode:: http
630 
+
631 
+	   HTTP/1.1 200 OK
632 
+	   Content-Type: application/json
633 
+
634 
+	   [
635 
+	     {
636 
+	   	"RepoTag": [
637 
+	   	  "ubuntu:12.04",
638 
+	   	  "ubuntu:precise",
639 
+	   	  "ubuntu:latest"
640 
+	   	],
641 
+	   	"Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
642 
+	   	"Created": 1365714795,
643 
+	   	"Size": 131506275,
644 
+	   	"VirtualSize": 131506275
645 
+	     },
646 
+	     {
647 
+	   	"RepoTag": [
648 
+	   	  "ubuntu:12.10",
649 
+	   	  "ubuntu:quantal"
650 
+	   	],
651 
+	   	"ParentId": "27cf784147099545",
652 
+	   	"Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
653 
+	   	"Created": 1364102658,
654 
+	   	"Size": 24653,
655 
+	   	"VirtualSize": 180116135
656 
+	     }
657 
+	   ]
658 
+
659 
+
660 
+Create an image
661 
+***************
662 
+
663 
+.. http:post:: /images/create
664 
+
665 
+	Create an image, either by pull it from the registry or by importing it
666 
+
667 
+	**Example request**:
668 
+
669 
+        .. sourcecode:: http
670 
+
671 
+           POST /images/create?fromImage=base HTTP/1.1
672 
+
673 
+        **Example response**:
674 
+
675 
+        .. sourcecode:: http
676 
+
677 
+           HTTP/1.1 200 OK
678 
+	   Content-Type: application/json
679 
+
680 
+	   {"status":"Pulling..."}
681 
+	   {"status":"Pulling", "progress":"1/? (n/a)"}
682 
+	   {"error":"Invalid..."}
683 
+	   ...
684 
+
685 
+	When using this endpoint to pull an image from the registry,
686 
+	the ``X-Registry-Auth`` header can be used to include a
687 
+	base64-encoded AuthConfig object.
688 
+
689 
+        :query fromImage: name of the image to pull
690 
+	:query fromSrc: source to import, - means stdin
691 
+        :query repo: repository
692 
+	:query tag: tag
693 
+	:query registry: the registry to pull from
694 
+        :statuscode 200: no error
695 
+        :statuscode 500: server error
696 
+
697 
+
698 
+Insert a file in an image
699 
+*************************
700 
+
701 
+.. http:post:: /images/(name)/insert
702 
+
703 
+	Insert a file from ``url`` in the image ``name`` at ``path``
704 
+
705 
+	**Example request**:
706 
+
707 
+        .. sourcecode:: http
708 
+
709 
+           POST /images/test/insert?path=/usr&url=myurl HTTP/1.1
710 
+
711 
+	**Example response**:
712 
+
713 
+        .. sourcecode:: http
714 
+
715 
+           HTTP/1.1 200 OK
716 
+	   Content-Type: application/json
717 
+
718 
+	   {"status":"Inserting..."}
719 
+	   {"status":"Inserting", "progress":"1/? (n/a)"}
720 
+	   {"error":"Invalid..."}
721 
+	   ...
722 
+
723 
+	:statuscode 200: no error
724 
+        :statuscode 500: server error
725 
+
726 
+
727 
+Inspect an image
728 
+****************
729 
+
730 
+.. http:get:: /images/(name)/json
731 
+
732 
+	Return low-level information on the image ``name``
733 
+
734 
+	**Example request**:
735 
+
736 
+	.. sourcecode:: http
737 
+
738 
+	   GET /images/base/json HTTP/1.1
739 
+
740 
+	**Example response**:
741 
+
742 
+        .. sourcecode:: http
743 
+
744 
+           HTTP/1.1 200 OK
745 
+	   Content-Type: application/json
746 
+
747 
+	   {
748 
+		"id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
749 
+		"parent":"27cf784147099545",
750 
+		"created":"2013-03-23T22:24:18.818426-07:00",
751 
+		"container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0",
752 
+		"container_config":
753 
+			{
754 
+				"Hostname":"",
755 
+				"User":"",
756 
+				"Memory":0,
757 
+				"MemorySwap":0,
758 
+				"AttachStdin":false,
759 
+				"AttachStdout":false,
760 
+				"AttachStderr":false,
761 
+				"PortSpecs":null,
762 
+				"Tty":true,
763 
+				"OpenStdin":true,
764 
+				"StdinOnce":false,
765 
+				"Env":null,
766 
+				"Cmd": ["/bin/bash"]
767 
+				,"Dns":null,
768 
+				"Image":"base",
769 
+				"Volumes":null,
770 
+				"VolumesFrom":"",
771 
+				"WorkingDir":""
772 
+			},
773 
+		"Size": 6824592
774 
+	   }
775 
+
776 
+	:statuscode 200: no error
777 
+	:statuscode 404: no such image
778 
+        :statuscode 500: server error
779 
+
780 
+
781 
+Get the history of an image
782 
+***************************
783 
+
784 
+.. http:get:: /images/(name)/history
785 
+
786 
+        Return the history of the image ``name``
787 
+
788 
+        **Example request**:
789 
+
790 
+        .. sourcecode:: http
791 
+
792 
+           GET /images/base/history HTTP/1.1
793 
+
794 
+        **Example response**:
795 
+
796 
+        .. sourcecode:: http
797 
+
798 
+           HTTP/1.1 200 OK
799 
+	   Content-Type: application/json
800 
+
801 
+	   [
802 
+		{
803 
+			"Id":"b750fe79269d",
804 
+			"Created":1364102658,
805 
+			"CreatedBy":"/bin/bash"
806 
+		},
807 
+		{
808 
+			"Id":"27cf78414709",
809 
+			"Created":1364068391,
810 
+			"CreatedBy":""
811 
+		}
812 
+	   ]
813 
+
814 
+        :statuscode 200: no error
815 
+        :statuscode 404: no such image
816 
+        :statuscode 500: server error
817 
+
818 
+
819 
+Push an image on the registry
820 
+*****************************
821 
+
822 
+.. http:post:: /images/(name)/push
823 
+
824 
+   Push the image ``name`` on the registry
825 
+
826 
+   **Example request**:
827 
+
828 
+   .. sourcecode:: http
829 
+
830 
+      POST /images/test/push HTTP/1.1
831 
+
832 
+   **Example response**:
833 
+
834 
+   .. sourcecode:: http
835 
+
836 
+    HTTP/1.1 200 OK
837 
+    Content-Type: application/json
838 
+
839 
+   {"status":"Pushing..."}
840 
+   {"status":"Pushing", "progress":"1/? (n/a)"}
841 
+   {"error":"Invalid..."}
842 
+   ...
843 
+
844 
+	The ``X-Registry-Auth`` header can be used to include a
845 
+	base64-encoded AuthConfig object.
846 
+
847 
+   :query registry: the registry you wan to push, optional
848 
+   :statuscode 200: no error
849 
+        :statuscode 404: no such image
850 
+        :statuscode 500: server error
851 
+
852 
+
853 
+Tag an image into a repository
854 
+******************************
855 
+
856 
+.. http:post:: /images/(name)/tag
857 
+
858 
+	Tag the image ``name`` into a repository
859 
+
860 
+        **Example request**:
861 
+
862 
+        .. sourcecode:: http
863 
+
864 
+	   POST /images/test/tag?repo=myrepo&force=0 HTTP/1.1
865 
+
866 
+	**Example response**:
867 
+
868 
+        .. sourcecode:: http
869 
+
870 
+           HTTP/1.1 200 OK
871 
+
872 
+	:query repo: The repository to tag in
873 
+	:query force: 1/True/true or 0/False/false, default false
874 
+	:statuscode 200: no error
875 
+	:statuscode 400: bad parameter
876 
+	:statuscode 404: no such image
877 
+	:statuscode 409: conflict
878 
+        :statuscode 500: server error
879 
+
880 
+
881 
+Remove an image
882 
+***************
883 
+
884 
+.. http:delete:: /images/(name)
885 
+
886 
+	Remove the image ``name`` from the filesystem
887 
+
888 
+	**Example request**:
889 
+
890 
+	.. sourcecode:: http
891 
+
892 
+	   DELETE /images/test HTTP/1.1
893 
+
894 
+	**Example response**:
895 
+
896 
+        .. sourcecode:: http
897 
+
898 
+	   HTTP/1.1 200 OK
899 
+	   Content-type: application/json
900 
+
901 
+	   [
902 
+	    {"Untagged":"3e2f21a89f"},
903 
+	    {"Deleted":"3e2f21a89f"},
904 
+	    {"Deleted":"53b4f83ac9"}
905 
+	   ]
906 
+
907 
+	:statuscode 200: no error
908 
+        :statuscode 404: no such image
909 
+	:statuscode 409: conflict
910 
+        :statuscode 500: server error
911 
+
912 
+
913 
+Search images
914 
+*************
915 
+
916 
+.. http:get:: /images/search
917 
+
918 
+	Search for an image in the docker index
919 
+
920 
+	**Example request**:
921 
+
922 
+        .. sourcecode:: http
923 
+
924 
+           GET /images/search?term=sshd HTTP/1.1
925 
+
926 
+	**Example response**:
927 
+
928 
+	.. sourcecode:: http
929 
+
930 
+	   HTTP/1.1 200 OK
931 
+	   Content-Type: application/json
932 
+
933 
+	   [
934 
+		{
935 
+			"Name":"cespare/sshd",
936 
+			"Description":""
937 
+		},
938 
+		{
939 
+			"Name":"johnfuller/sshd",
940 
+			"Description":""
941 
+		},
942 
+		{
943 
+			"Name":"dhrp/mongodb-sshd",
944 
+			"Description":""
945 
+		}
946 
+	   ]
947 
+
948 
+	   :query term: term to search
949 
+	   :statuscode 200: no error
950 
+	   :statuscode 500: server error
951 
+
952 
+
953 
+2.3 Misc
954 
+--------
955 
+
956 
+Build an image from Dockerfile via stdin
957 
+****************************************
958 
+
959 
+.. http:post:: /build
960 
+
961 
+   Build an image from Dockerfile via stdin
962 
+
963 
+   **Example request**:
964 
+
965 
+   .. sourcecode:: http
966 
+
967 
+      POST /build HTTP/1.1
968 
+
969 
+      {{ STREAM }}
970 
+
971 
+   **Example response**:
972 
+
973 
+   .. sourcecode:: http
974 
+
975 
+      HTTP/1.1 200 OK
976 
+
977 
+      {{ STREAM }}
978 
+
979 
+
980 
+       The stream must be a tar archive compressed with one of the following algorithms:
981 
+       identity (no compression), gzip, bzip2, xz. The archive must include a file called
982 
+       `Dockerfile` at its root. It may include any number of other files, which will be
983 
+       accessible in the build context (See the ADD build command).
984 
+
985 
+       The Content-type header should be set to "application/tar".
986 
+
987 
+	:query t: repository name (and optionally a tag) to be applied to the resulting image in case of success
988 
+	:query q: suppress verbose build output
989 
+    :query nocache: do not use the cache when building the image
990 
+	:statuscode 200: no error
991 
+    :statuscode 500: server error
992 
+
993 
+
994 
+Check auth configuration
995 
+************************
996 
+
997 
+.. http:post:: /auth
998 
+
999 
+        Get the default username and email
1000 
+
1001 
+        **Example request**:
1002 
+
1003 
+        .. sourcecode:: http
1004 
+
1005 
+           POST /auth HTTP/1.1
1006 
+	   Content-Type: application/json
1007 
+
1008 
+	   {
1009 
+		"username":"hannibal",
1010 
+		"password:"xxxx",
1011 
+		"email":"hannibal@a-team.com",
1012 
+		"serveraddress":"https://index.docker.io/v1/"
1013 
+	   }
1014 
+
1015 
+        **Example response**:
1016 
+
1017 
+        .. sourcecode:: http
1018 
+
1019 
+           HTTP/1.1 200 OK
1020 
+
1021 
+        :statuscode 200: no error
1022 
+        :statuscode 204: no error
1023 
+        :statuscode 500: server error
1024 
+
1025 
+
1026 
+Display system-wide information
1027 
+*******************************
1028 
+
1029 
+.. http:get:: /info
1030 
+
1031 
+	Display system-wide information
1032 
+
1033 
+	**Example request**:
1034 
+
1035 
+        .. sourcecode:: http
1036 
+
1037 
+           GET /info HTTP/1.1
1038 
+
1039 
+        **Example response**:
1040 
+
1041 
+        .. sourcecode:: http
1042 
+
1043 
+           HTTP/1.1 200 OK
1044 
+	   Content-Type: application/json
1045 
+
1046 
+	   {
1047 
+		"Containers":11,
1048 
+		"Images":16,
1049 
+		"Debug":false,
1050 
+		"NFd": 11,
1051 
+		"NGoroutines":21,
1052 
+		"MemoryLimit":true,
1053 
+		"SwapLimit":false,
1054 
+		"IPv4Forwarding":true
1055 
+	   }
1056 
+
1057 
+        :statuscode 200: no error
1058 
+        :statuscode 500: server error
1059 
+
1060 
+
1061 
+Show the docker version information
1062 
+***********************************
1063 
+
1064 
+.. http:get:: /version
1065 
+
1066 
+	Show the docker version information
1067 
+
1068 
+	**Example request**:
1069 
+
1070 
+        .. sourcecode:: http
1071 
+
1072 
+           GET /version HTTP/1.1
1073 
+
1074 
+        **Example response**:
1075 
+
1076 
+        .. sourcecode:: http
1077 
+
1078 
+           HTTP/1.1 200 OK
1079 
+	   Content-Type: application/json
1080 
+
1081 
+	   {
1082 
+		"Version":"0.2.2",
1083 
+		"GitCommit":"5a2a5cc+CHANGES",
1084 
+		"GoVersion":"go1.0.3"
1085 
+	   }
1086 
+
1087 
+        :statuscode 200: no error
1088 
+	:statuscode 500: server error
1089 
+
1090 
+
1091 
+Create a new image from a container's changes
1092 
+*********************************************
1093 
+
1094 
+.. http:post:: /commit
1095 
+
1096 
+    Create a new image from a container's changes
1097 
+
1098 
+    **Example request**:
1099 
+
1100 
+    .. sourcecode:: http
1101 
+
1102 
+        POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1
1103 
+
1104 
+    **Example response**:
1105 
+
1106 
+    .. sourcecode:: http
1107 
+
1108 
+        HTTP/1.1 201 OK
1109 
+	    Content-Type: application/vnd.docker.raw-stream
1110 
+
1111 
+        {"Id":"596069db4bf5"}
1112 
+
1113 
+    :query container: source container
1114 
+    :query repo: repository
1115 
+    :query tag: tag
1116 
+    :query m: commit message
1117 
+    :query author: author (eg. "John Hannibal Smith <hannibal@a-team.com>")
1118 
+    :query run: config automatically applied when the image is run. (ex: {"Cmd": ["cat", "/world"], "PortSpecs":["22"]})
1119 
+    :statuscode 201: no error
1120 
+    :statuscode 404: no such container
1121 
+    :statuscode 500: server error
1122 
+
1123 
+
1124 
+Monitor Docker's events
1125 
+***********************
1126 
+
1127 
+.. http:get:: /events
1128 
+
1129 
+	Get events from docker, either in real time via streaming, or via polling (using `since`)
1130 
+
1131 
+	**Example request**:
1132 
+
1133 
+	.. sourcecode:: http
1134 
+
1135 
+           POST /events?since=1374067924
1136 
+
1137 
+        **Example response**:
1138 
+
1139 
+        .. sourcecode:: http
1140 
+
1141 
+           HTTP/1.1 200 OK
1142 
+	   Content-Type: application/json
1143 
+
1144 
+	   {"status":"create","id":"dfdf82bd3881","from":"base:latest","time":1374067924}
1145 
+	   {"status":"start","id":"dfdf82bd3881","from":"base:latest","time":1374067924}
1146 
+	   {"status":"stop","id":"dfdf82bd3881","from":"base:latest","time":1374067966}
1147 
+	   {"status":"destroy","id":"dfdf82bd3881","from":"base:latest","time":1374067970}
1148 
+
1149 
+	:query since: timestamp used for polling
1150 
+        :statuscode 200: no error
1151 
+        :statuscode 500: server error
1152 
+
1153 
+
1154 
+3. Going further
1155 
+================
1156 
+
1157 
+3.1 Inside 'docker run'
1158 
+-----------------------
1159 
+
1160 
+Here are the steps of 'docker run' :
1161 
+
1162 
+* Create the container
1163 
+* If the status code is 404, it means the image doesn't exists:
1164 
+        * Try to pull it
1165 
+        * Then retry to create the container
1166 
+* Start the container
1167 
+* If you are not in detached mode:
1168 
+        * Attach to the container, using logs=1 (to have stdout and stderr from the container's start) and stream=1
1169 
+* If in detached mode or only stdin is attached:
1170 
+	* Display the container's id
1171 
+
1172 
+
1173 
+3.2 Hijacking
1174 
+-------------
1175 
+
1176 
+In this version of the API, /attach, uses hijacking to transport stdin, stdout and stderr on the same socket. This might change in the future.
1177 
+
1178 
+3.3 CORS Requests
1179 
+-----------------
1180 
+
1181 
+To enable cross origin requests to the remote api add the flag "-api-enable-cors" when running docker in daemon mode.
1182 
+
1183 
+.. code-block:: bash
1184 
+
1185 
+   docker -d -H="192.168.1.9:4243" -api-enable-cors
1186 
+
docs/sources/commandline/cli.rst
History View file @ 6d5b73c
... ... 
@@ -328,6 +328,36 @@ Displaying images visually
328 328 
 .. image:: docker_images.gif
329 329 
    :alt: Example inheritance graph of Docker images.
330 330
331 
+
332 
+Displaying image hierarchy
333 
+~~~~~~~~~~~~~~~~~~~~~~~~~~
334 
+
335 
+::
336 
+
337 
+    sudo docker images -tree
338 
+
339 
+    |─8dbd9e392a96 Size: 131.5 MB (virtual 131.5 MB) Tags: ubuntu:12.04,ubuntu:latest,ubuntu:precise
340 
+    └─27cf78414709 Size: 180.1 MB (virtual 180.1 MB)
341 
+      └─b750fe79269d Size: 24.65 kB (virtual 180.1 MB) Tags: ubuntu:12.10,ubuntu:quantal
342 
+        |─f98de3b610d5 Size: 12.29 kB (virtual 180.1 MB)
343 
+        | └─7da80deb7dbf Size: 16.38 kB (virtual 180.1 MB)
344 
+        |   └─65ed2fee0a34 Size: 20.66 kB (virtual 180.2 MB)
345 
+        |     └─a2b9ea53dddc Size: 819.7 MB (virtual 999.8 MB)
346 
+        |       └─a29b932eaba8 Size: 28.67 kB (virtual 999.9 MB)
347 
+        |         └─e270a44f124d Size: 12.29 kB (virtual 999.9 MB) Tags: progrium/buildstep:latest
348 
+        └─17e74ac162d8 Size: 53.93 kB (virtual 180.2 MB)
349 
+          └─339a3f56b760 Size: 24.65 kB (virtual 180.2 MB)
350 
+            └─904fcc40e34d Size: 96.7 MB (virtual 276.9 MB)
351 
+              └─b1b0235328dd Size: 363.3 MB (virtual 640.2 MB)
352 
+                └─7cb05d1acb3b Size: 20.48 kB (virtual 640.2 MB)
353 
+                  └─47bf6f34832d Size: 20.48 kB (virtual 640.2 MB)
354 
+                    └─f165104e82ed Size: 12.29 kB (virtual 640.2 MB)
355 
+                      └─d9cf85a47b7e Size: 1.911 MB (virtual 642.2 MB)
356 
+                        └─3ee562df86ca Size: 17.07 kB (virtual 642.2 MB)
357 
+                          └─b05fc2d00e4a Size: 24.96 kB (virtual 642.2 MB)
358 
+                            └─c96a99614930 Size: 12.29 kB (virtual 642.2 MB)
359 
+                              └─a6a357a48c49 Size: 12.29 kB (virtual 642.2 MB) Tags: ndj/mongodb:latest
360 
+
331 361 
 .. _cli_import:
332 362
333 363 
 ``import``