github.com/guilhermebr/docker@v1.4.2-0.20150428121140-67da055cebca/docs/sources/reference/api/docker_remote_api_v1.9.md (about) 1 page_title: Remote API v1.9 2 page_description: API Documentation for Docker 3 page_keywords: API, Docker, rcli, REST, documentation 4 5 # Docker Remote API v1.9 6 7 # 1. Brief introduction 8 9 - The Remote API has replaced rcli 10 - The daemon listens on `unix:///var/run/docker.sock` but you can bind 11 Docker to another host/port or a Unix socket. 12 - The API tends to be REST, but for some complex commands, like `attach` 13 or `pull`, the HTTP connection is hijacked to transport `stdout, stdin` 14 and `stderr` 15 16 # 2. Endpoints 17 18 ## 2.1 Containers 19 20 ### List containers 21 22 `GET /containers/json` 23 24 List containers. 25 26 **Example request**: 27 28 GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 29 30 **Example response**: 31 32 HTTP/1.1 200 OK 33 Content-Type: application/json 34 35 [ 36 { 37 "Id": "8dfafdbc3a40", 38 "Image": "base:latest", 39 "Command": "echo 1", 40 "Created": 1367854155, 41 "Status": "Exit 0", 42 "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], 43 "SizeRw": 12288, 44 "SizeRootFs": 0 45 }, 46 { 47 "Id": "9cd87474be90", 48 "Image": "base:latest", 49 "Command": "echo 222222", 50 "Created": 1367854155, 51 "Status": "Exit 0", 52 "Ports": [], 53 "SizeRw": 12288, 54 "SizeRootFs": 0 55 }, 56 { 57 "Id": "3176a2479c92", 58 "Image": "base:latest", 59 "Command": "echo 3333333333333333", 60 "Created": 1367854154, 61 "Status": "Exit 0", 62 "Ports":[], 63 "SizeRw":12288, 64 "SizeRootFs":0 65 }, 66 { 67 "Id": "4cb07b47f9fb", 68 "Image": "base:latest", 69 "Command": "echo 444444444444444444444444444444444", 70 "Created": 1367854152, 71 "Status": "Exit 0", 72 "Ports": [], 73 "SizeRw": 12288, 74 "SizeRootFs": 0 75 } 76 ] 77 78 Query Parameters: 79 80 81 82 - **all** – 1/True/true or 0/False/false, Show all containers. 83 Only running containers are shown by default (i.e., this defaults to false) 84 - **limit** – Show `limit` last created containers, include non-running ones. 85 - **since** – Show only containers created since Id, include non-running ones. 86 - **before** – Show only containers created before Id, include non-running ones. 87 - **size** – 1/True/true or 0/False/false, Show the containers sizes 88 89 Status Codes: 90 91 - **200** – no error 92 - **400** – bad parameter 93 - **500** – server error 94 95 ### Create a container 96 97 `POST /containers/create` 98 99 Create a container 100 101 **Example request**: 102 103 POST /containers/create HTTP/1.1 104 Content-Type: application/json 105 106 { 107 "Hostname":"", 108 "User":"", 109 "Memory":0, 110 "MemorySwap":0, 111 "CpuShares":0, 112 "AttachStdin":false, 113 "AttachStdout":true, 114 "AttachStderr":true, 115 "PortSpecs":null, 116 "Tty":false, 117 "OpenStdin":false, 118 "StdinOnce":false, 119 "Env":null, 120 "Cmd":[ 121 "date" 122 ], 123 "Dns":null, 124 "Image":"base", 125 "Volumes":{ 126 "/tmp": {} 127 }, 128 "VolumesFrom":"", 129 "WorkingDir":"", 130 "ExposedPorts":{ 131 "22/tcp": {} 132 } 133 } 134 135 **Example response**: 136 137 HTTP/1.1 201 Created 138 Content-Type: application/json 139 140 { 141 "Id":"e90e34656806" 142 "Warnings":[] 143 } 144 145 Json Parameters: 146 147 148 149 - **Hostname** – Container host name 150 - **User** – Username or UID 151 - **Memory** – Memory Limit in bytes 152 - **CpuShares** – CPU shares (relative weight) 153 - **AttachStdin** – 1/True/true or 0/False/false, attach to 154 standard input. Default false 155 - **AttachStdout** – 1/True/true or 0/False/false, attach to 156 standard output. Default false 157 - **AttachStderr** – 1/True/true or 0/False/false, attach to 158 standard error. Default false 159 - **Tty** – 1/True/true or 0/False/false, allocate a pseudo-tty. 160 Default false 161 - **OpenStdin** – 1/True/true or 0/False/false, keep stdin open 162 even if not attached. Default false 163 164 Query Parameters: 165 166 167 168 - **name** – Assign the specified name to the container. Mus 169 match `/?[a-zA-Z0-9_-]+`. 170 171 Status Codes: 172 173 - **201** – no error 174 - **404** – no such container 175 - **406** – impossible to attach (container not running) 176 - **500** – server error 177 178 ### Inspect a container 179 180 `GET /containers/(id)/json` 181 182 Return low-level information on the container `id` 183 184 **Example request**: 185 186 GET /containers/4fa6e0f0c678/json HTTP/1.1 187 188 **Example response**: 189 190 HTTP/1.1 200 OK 191 Content-Type: application/json 192 193 { 194 "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", 195 "Created": "2013-05-07T14:51:42.041847+02:00", 196 "Path": "date", 197 "Args": [], 198 "Config": { 199 "Hostname": "4fa6e0f0c678", 200 "User": "", 201 "Memory": 0, 202 "MemorySwap": 0, 203 "AttachStdin": false, 204 "AttachStdout": true, 205 "AttachStderr": true, 206 "PortSpecs": null, 207 "Tty": false, 208 "OpenStdin": false, 209 "StdinOnce": false, 210 "Env": null, 211 "Cmd": [ 212 "date" 213 ], 214 "Dns": null, 215 "Image": "base", 216 "Volumes": {}, 217 "VolumesFrom": "", 218 "WorkingDir": "" 219 }, 220 "State": { 221 "Running": false, 222 "Pid": 0, 223 "ExitCode": 0, 224 "StartedAt": "2013-05-07T14:51:42.087658+02:01360", 225 "Ghost": false 226 }, 227 "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 228 "NetworkSettings": { 229 "IpAddress": "", 230 "IpPrefixLen": 0, 231 "Gateway": "", 232 "Bridge": "", 233 "PortMapping": null 234 }, 235 "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", 236 "ResolvConfPath": "/etc/resolv.conf", 237 "Volumes": {}, 238 "HostConfig": { 239 "Binds": null, 240 "ContainerIDFile": "", 241 "LxcConf": [], 242 "Privileged": false, 243 "PortBindings": { 244 "80/tcp": [ 245 { 246 "HostIp": "0.0.0.0", 247 "HostPort": "49153" 248 } 249 ] 250 }, 251 "Links": null, 252 "PublishAllPorts": false 253 } 254 } 255 256 Status Codes: 257 258 - **200** – no error 259 - **404** – no such container 260 - **500** – server error 261 262 ### List processes running inside a container 263 264 `GET /containers/(id)/top` 265 266 List processes running inside the container `id` 267 268 **Example request**: 269 270 GET /containers/4fa6e0f0c678/top HTTP/1.1 271 272 **Example response**: 273 274 HTTP/1.1 200 OK 275 Content-Type: application/json 276 277 { 278 "Titles": [ 279 "USER", 280 "PID", 281 "%CPU", 282 "%MEM", 283 "VSZ", 284 "RSS", 285 "TTY", 286 "STAT", 287 "START", 288 "TIME", 289 "COMMAND" 290 ], 291 "Processes": [ 292 ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], 293 ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] 294 ] 295 } 296 297 Query Parameters: 298 299 - **ps_args** – ps arguments to use (e.g., aux) 300 301 Status Codes: 302 303 - **200** – no error 304 - **404** – no such container 305 - **500** – server error 306 307 ### Inspect changes on a container's filesystem 308 309 `GET /containers/(id)/changes` 310 311 Inspect changes on container `id`'s filesystem 312 313 **Example request**: 314 315 GET /containers/4fa6e0f0c678/changes HTTP/1.1 316 317 **Example response**: 318 319 HTTP/1.1 200 OK 320 Content-Type: application/json 321 322 [ 323 { 324 "Path": "/dev", 325 "Kind": 0 326 }, 327 { 328 "Path": "/dev/kmsg", 329 "Kind": 1 330 }, 331 { 332 "Path": "/test", 333 "Kind": 1 334 } 335 ] 336 337 Status Codes: 338 339 - **200** – no error 340 - **404** – no such container 341 - **500** – server error 342 343 ### Export a container 344 345 `GET /containers/(id)/export` 346 347 Export the contents of container `id` 348 349 **Example request**: 350 351 GET /containers/4fa6e0f0c678/export HTTP/1.1 352 353 **Example response**: 354 355 HTTP/1.1 200 OK 356 Content-Type: application/octet-stream 357 358 {{ TAR STREAM }} 359 360 Status Codes: 361 362 - **200** – no error 363 - **404** – no such container 364 - **500** – server error 365 366 ### Start a container 367 368 `POST /containers/(id)/start` 369 370 Start the container `id` 371 372 **Example request**: 373 374 POST /containers/(id)/start HTTP/1.1 375 Content-Type: application/json 376 377 { 378 "Binds":["/tmp:/tmp"], 379 "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], 380 "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, 381 "PublishAllPorts":false, 382 "Privileged":false 383 } 384 385 **Example response**: 386 387 HTTP/1.1 204 No Content 388 Content-Type: text/plain 389 390 Json Parameters: 391 392 393 394 - **Binds** – Create a bind mount to a directory or file with 395 [host-path]:[container-path]:[rw|ro]. If a directory 396 "container-path" is missing, then docker creates a new volume. 397 - **LxcConf** – Map of custom lxc options 398 - **PortBindings** – Expose ports from the container, optionally 399 publishing them via the HostPort flag 400 - **PublishAllPorts** – 1/True/true or 0/False/false, publish all 401 exposed ports to the host interfaces. Default false 402 - **Privileged** – 1/True/true or 0/False/false, give extended 403 privileges to this container. Default false 404 405 Status Codes: 406 407 - **204** – no error 408 - **404** – no such container 409 - **500** – server error 410 411 ### Stop a container 412 413 `POST /containers/(id)/stop` 414 415 Stop the container `id` 416 417 **Example request**: 418 419 POST /containers/e90e34656806/stop?t=5 HTTP/1.1 420 421 **Example response**: 422 423 HTTP/1.1 204 OK 424 425 Query Parameters: 426 427 - **t** – number of seconds to wait before killing the container 428 429 Status Codes: 430 431 - **204** – no error 432 - **404** – no such container 433 - **500** – server error 434 435 ### Restart a container 436 437 `POST /containers/(id)/restart` 438 439 Restart the container `id` 440 441 **Example request**: 442 443 POST /containers/e90e34656806/restart?t=5 HTTP/1.1 444 445 **Example response**: 446 447 HTTP/1.1 204 No Content 448 449 Query Parameters: 450 451 - **t** – number of seconds to wait before killing the container 452 453 Status Codes: 454 455 - **204** – no error 456 - **404** – no such container 457 - **500** – server error 458 459 ### Kill a container 460 461 `POST /containers/(id)/kill` 462 463 Kill the container `id` 464 465 **Example request**: 466 467 POST /containers/e90e34656806/kill HTTP/1.1 468 469 **Example response**: 470 471 HTTP/1.1 204 No Content 472 473 Query Parameters 474 475 - **signal** - Signal to send to the container: integer or string like "SIGINT". 476 When not set, SIGKILL is assumed and the call will wait for the container to exit. 477 478 Status Codes: 479 480 - **204** – no error 481 - **404** – no such container 482 - **500** – server error 483 484 ### Attach to a container 485 486 `POST /containers/(id)/attach` 487 488 Attach to the container `id` 489 490 **Example request**: 491 492 POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 493 494 **Example response**: 495 496 HTTP/1.1 200 OK 497 Content-Type: application/vnd.docker.raw-stream 498 499 {{ STREAM }} 500 501 Query Parameters: 502 503 - **logs** – 1/True/true or 0/False/false, return logs. Defaul 504 false 505 - **stream** – 1/True/true or 0/False/false, return stream. 506 Default false 507 - **stdin** – 1/True/true or 0/False/false, if stream=true, attach 508 to stdin. Default false 509 - **stdout** – 1/True/true or 0/False/false, if logs=true, return 510 stdout log, if stream=true, attach to stdout. Default false 511 - **stderr** – 1/True/true or 0/False/false, if logs=true, return 512 stderr log, if stream=true, attach to stderr. Default false 513 514 Status Codes: 515 516 - **200** – no error 517 - **400** – bad parameter 518 - **404** – no such container 519 - **500** – server error 520 521 **Stream details**: 522 523 When using the TTY setting is enabled in 524 [`POST /containers/create`](#create-a-container), the 525 stream is the raw data from the process PTY and client's stdin. When 526 the TTY is disabled, then the stream is multiplexed to separate 527 stdout and stderr. 528 529 The format is a **Header** and a **Payload** (frame). 530 531 **HEADER** 532 533 The header will contain the information on which stream write the 534 stream (stdout or stderr). It also contain the size of the 535 associated frame encoded on the last 4 bytes (uint32). 536 537 It is encoded on the first 8 bytes like this: 538 539 header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} 540 541 `STREAM_TYPE` can be: 542 543 - 0: stdin (will be written on stdout) 544 - 1: stdout 545 - 2: stderr 546 547 `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of 548 the uint32 size encoded as big endian. 549 550 **PAYLOAD** 551 552 The payload is the raw stream. 553 554 **IMPLEMENTATION** 555 556 The simplest way to implement the Attach protocol is the following: 557 558 1. Read 8 bytes 559 2. chose stdout or stderr depending on the first byte 560 3. Extract the frame size from the last 4 bytes 561 4. Read the extracted size and output it on the correct output 562 5. Goto 1) 563 564 ### Attach to a container (websocket) 565 566 `GET /containers/(id)/attach/ws` 567 568 Attach to the container `id` via websocket 569 570 Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) 571 572 **Example request** 573 574 GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 575 576 **Example response** 577 578 {{ STREAM }} 579 580 Query Parameters: 581 582 - **logs** – 1/True/true or 0/False/false, return logs. Default false 583 - **stream** – 1/True/true or 0/False/false, return stream. 584 Default false 585 - **stdin** – 1/True/true or 0/False/false, if stream=true, attach 586 to stdin. Default false 587 - **stdout** – 1/True/true or 0/False/false, if logs=true, return 588 stdout log, if stream=true, attach to stdout. Default false 589 - **stderr** – 1/True/true or 0/False/false, if logs=true, return 590 stderr log, if stream=true, attach to stderr. Default false 591 592 Status Codes: 593 594 - **200** – no error 595 - **400** – bad parameter 596 - **404** – no such container 597 - **500** – server error 598 599 ### Wait a container 600 601 `POST /containers/(id)/wait` 602 603 Block until container `id` stops, then returns the exit code 604 605 **Example request**: 606 607 POST /containers/16253994b7c4/wait HTTP/1.1 608 609 **Example response**: 610 611 HTTP/1.1 200 OK 612 Content-Type: application/json 613 614 {"StatusCode": 0} 615 616 Status Codes: 617 618 - **200** – no error 619 - **404** – no such container 620 - **500** – server error 621 622 ### Remove a container 623 624 `DELETE /containers/(id)` 625 626 Remove the container `id` from the filesystem 627 628 **Example request**: 629 630 DELETE /containers/16253994b7c4?v=1 HTTP/1.1 631 632 **Example response**: 633 634 HTTP/1.1 204 No Content 635 636 Query Parameters: 637 638 - **v** – 1/True/true or 0/False/false, Remove the volumes 639 associated to the container. Default false 640 641 Status Codes: 642 643 - **204** – no error 644 - **400** – bad parameter 645 - **404** – no such container 646 - **500** – server error 647 648 ### Copy files or folders from a container 649 650 `POST /containers/(id)/copy` 651 652 Copy files or folders of container `id` 653 654 **Example request**: 655 656 POST /containers/4fa6e0f0c678/copy HTTP/1.1 657 Content-Type: application/json 658 659 { 660 "Resource": "test.txt" 661 } 662 663 **Example response**: 664 665 HTTP/1.1 200 OK 666 Content-Type: application/octet-stream 667 668 {{ TAR STREAM }} 669 670 Status Codes: 671 672 - **200** – no error 673 - **404** – no such container 674 - **500** – server error 675 676 ## 2.2 Images 677 678 ### List images 679 680 `GET /images/json` 681 682 **Example request**: 683 684 GET /images/json?all=0 HTTP/1.1 685 686 **Example response**: 687 688 HTTP/1.1 200 OK 689 Content-Type: application/json 690 691 [ 692 { 693 "RepoTags": [ 694 "ubuntu:12.04", 695 "ubuntu:precise", 696 "ubuntu:latest" 697 ], 698 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 699 "Created": 1365714795, 700 "Size": 131506275, 701 "VirtualSize": 131506275 702 }, 703 { 704 "RepoTags": [ 705 "ubuntu:12.10", 706 "ubuntu:quantal" 707 ], 708 "ParentId": "27cf784147099545", 709 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 710 "Created": 1364102658, 711 "Size": 24653, 712 "VirtualSize": 180116135 713 } 714 ] 715 716 ### Create an image 717 718 `POST /images/create` 719 720 Create an image, either by pull it from the registry or by importing i 721 722 **Example request**: 723 724 POST /images/create?fromImage=base HTTP/1.1 725 726 **Example response**: 727 728 HTTP/1.1 200 OK 729 Content-Type: application/json 730 731 {"status": "Pulling..."} 732 {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} 733 {"error": "Invalid..."} 734 ... 735 736 When using this endpoint to pull an image from the registry, the 737 `X-Registry-Auth` header can be used to include 738 a base64-encoded AuthConfig object. 739 740 Query Parameters: 741 742 - **fromImage** – name of the image to pull 743 - **fromSrc** – source to import, - means stdin 744 - **repo** – repository 745 - **tag** – tag 746 - **registry** – the registry to pull from 747 748 Request Headers: 749 750 - **X-Registry-Auth** – base64-encoded AuthConfig object 751 752 Status Codes: 753 754 - **200** – no error 755 - **500** – server error 756 757 ### Insert a file in an image 758 759 `POST /images/(name)/insert` 760 761 Insert a file from `url` in the image `name` at `path` 762 763 **Example request**: 764 765 POST /images/test/insert?path=/usr&url=myurl HTTP/1.1 766 767 **Example response**: 768 769 HTTP/1.1 200 OK 770 Content-Type: application/json 771 772 {"status":"Inserting..."} 773 {"status":"Inserting", "progress":"1/? (n/a)", "progressDetail":{"current":1}} 774 {"error":"Invalid..."} 775 ... 776 777 Query Parameters: 778 779 - **url** – The url from where the file is taken 780 - **path** – The path where the file is stored 781 782 Status Codes: 783 784 - **200** – no error 785 - **500** – server error 786 787 ### Inspect an image 788 789 `GET /images/(name)/json` 790 791 Return low-level information on the image `name` 792 793 **Example request**: 794 795 GET /images/base/json HTTP/1.1 796 797 **Example response**: 798 799 HTTP/1.1 200 OK 800 Content-Type: application/json 801 802 { 803 "id":"b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 804 "parent":"27cf784147099545", 805 "created":"2013-03-23T22:24:18.818426-07:00", 806 "container":"3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", 807 "container_config": 808 { 809 "Hostname":"", 810 "User":"", 811 "Memory":0, 812 "MemorySwap":0, 813 "AttachStdin":false, 814 "AttachStdout":false, 815 "AttachStderr":false, 816 "PortSpecs":null, 817 "Tty":true, 818 "OpenStdin":true, 819 "StdinOnce":false, 820 "Env":null, 821 "Cmd": ["/bin/bash"], 822 "Dns":null, 823 "Image":"base", 824 "Volumes":null, 825 "VolumesFrom":"", 826 "WorkingDir":"" 827 }, 828 "Size": 6824592 829 } 830 831 Status Codes: 832 833 - **200** – no error 834 - **404** – no such image 835 - **500** – server error 836 837 ### Get the history of an image 838 839 `GET /images/(name)/history` 840 841 Return the history of the image `name` 842 843 **Example request**: 844 845 GET /images/base/history HTTP/1.1 846 847 **Example response**: 848 849 HTTP/1.1 200 OK 850 Content-Type: application/json 851 852 [ 853 { 854 "Id": "b750fe79269d", 855 "Created": 1364102658, 856 "CreatedBy": "/bin/bash" 857 }, 858 { 859 "Id": "27cf78414709", 860 "Created": 1364068391, 861 "CreatedBy": "" 862 } 863 ] 864 865 Status Codes: 866 867 - **200** – no error 868 - **404** – no such image 869 - **500** – server error 870 871 ### Push an image on the registry 872 873 `POST /images/(name)/push` 874 875 Push the image `name` on the registry 876 877 **Example request**: 878 879 POST /images/test/push HTTP/1.1 880 881 **Example response**: 882 883 HTTP/1.1 200 OK 884 Content-Type: application/json 885 886 {"status": "Pushing..."} 887 {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} 888 {"error": "Invalid..."} 889 ... 890 891 Request Headers: 892 893 894 895 - **X-Registry-Auth** – include a base64-encoded AuthConfig 896 object. 897 898 Status Codes: 899 900 - **200** – no error 901 - **404** – no such image 902 - **500** – server error 903 904 ### Tag an image into a repository 905 906 `POST /images/(name)/tag` 907 908 Tag the image `name` into a repository 909 910 **Example request**: 911 912 POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 913 914 **Example response**: 915 916 HTTP/1.1 201 OK 917 918 Query Parameters: 919 920 - **repo** – The repository to tag in 921 - **force** – 1/True/true or 0/False/false, default false 922 - **tag** - The new tag name 923 924 Status Codes: 925 926 - **201** – no error 927 - **400** – bad parameter 928 - **404** – no such image 929 - **409** – conflict 930 - **500** – server error 931 932 ### Remove an image 933 934 `DELETE /images/(name*) 935 : Remove the image `name` from the filesystem 936 937 **Example request**: 938 939 DELETE /images/test HTTP/1.1 940 941 **Example response**: 942 943 HTTP/1.1 200 OK 944 Content-type: application/json 945 946 [ 947 {"Untagged": "3e2f21a89f"}, 948 {"Deleted": "3e2f21a89f"}, 949 {"Deleted": "53b4f83ac9"} 950 ] 951 952 Status Codes: 953 954 - **200** – no error 955 - **404** – no such image 956 - **409** – conflict 957 - **500** – server error 958 959 ### Search images 960 961 `GET /images/search` 962 963 Search for an image on [Docker Hub](https://hub.docker.com). 964 965 > **Note**: 966 > The response keys have changed from API v1.6 to reflect the JSON 967 > sent by the registry server to the docker daemon's request. 968 969 **Example request**: 970 971 GET /images/search?term=sshd HTTP/1.1 972 973 **Example response**: 974 975 HTTP/1.1 200 OK 976 Content-Type: application/json 977 978 [ 979 { 980 "description": "", 981 "is_official": false, 982 "is_trusted": false, 983 "name": "wma55/u1210sshd", 984 "star_count": 0 985 }, 986 { 987 "description": "", 988 "is_official": false, 989 "is_trusted": false, 990 "name": "jdswinbank/sshd", 991 "star_count": 0 992 }, 993 { 994 "description": "", 995 "is_official": false, 996 "is_trusted": false, 997 "name": "vgauthier/sshd", 998 "star_count": 0 999 } 1000 ... 1001 ] 1002 1003 Query Parameters: 1004 1005 - **term** – term to search 1006 1007 Status Codes: 1008 1009 - **200** – no error 1010 - **500** – server error 1011 1012 ## 2.3 Misc 1013 1014 ### Build an image from Dockerfile 1015 1016 `POST /build` 1017 1018 Build an image from Dockerfile using a POST body. 1019 1020 **Example request**: 1021 1022 POST /build HTTP/1.1 1023 1024 {{ TAR STREAM }} 1025 1026 **Example response**: 1027 1028 HTTP/1.1 200 OK 1029 Content-Type: application/json 1030 1031 {"stream": "Step 1..."} 1032 {"stream": "..."} 1033 {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} 1034 1035 The stream must be a tar archive compressed with one of the 1036 following algorithms: identity (no compression), gzip, bzip2, xz. 1037 1038 The archive must include a file called `Dockerfile` 1039 at its root. It may include any number of other files, 1040 which will be accessible in the build context (See the [*ADD build 1041 command*](/reference/builder/#add)). 1042 1043 Query Parameters: 1044 1045 - **t** – repository name (and optionally a tag) to be applied to 1046 the resulting image in case of success 1047 - **remote** – build source URI (git or HTTPS/HTTP) 1048 - **q** – suppress verbose build output 1049 - **nocache** – do not use the cache when building the image 1050 - **rm** – Remove intermediate containers after a successful build 1051 1052 Request Headers: 1053 1054 - **Content-type** – should be set to `"application/tar"`. 1055 - **X-Registry-Config** – base64-encoded ConfigFile object 1056 1057 Status Codes: 1058 1059 - **200** – no error 1060 - **500** – server error 1061 1062 ### Check auth configuration 1063 1064 `POST /auth` 1065 1066 Get the default username and email 1067 1068 **Example request**: 1069 1070 POST /auth HTTP/1.1 1071 Content-Type: application/json 1072 1073 { 1074 "username":" hannibal", 1075 "password: "xxxx", 1076 "email": "hannibal@a-team.com", 1077 "serveraddress": "https://index.docker.io/v1/" 1078 } 1079 1080 **Example response**: 1081 1082 HTTP/1.1 200 OK 1083 Content-Type: text/plain 1084 1085 Status Codes: 1086 1087 - **200** – no error 1088 - **204** – no error 1089 - **500** – server error 1090 1091 ### Display system-wide information 1092 1093 `GET /info` 1094 1095 Display system-wide information 1096 1097 **Example request**: 1098 1099 GET /info HTTP/1.1 1100 1101 **Example response**: 1102 1103 HTTP/1.1 200 OK 1104 Content-Type: application/json 1105 1106 { 1107 "Containers":11, 1108 "Images":16, 1109 "Debug":false, 1110 "NFd": 11, 1111 "NGoroutines":21, 1112 "MemoryLimit":true, 1113 "SwapLimit":false, 1114 "IPv4Forwarding":true 1115 } 1116 1117 Status Codes: 1118 1119 - **200** – no error 1120 - **500** – server error 1121 1122 ### Show the Docker version information 1123 1124 `GET /version` 1125 1126 Show the docker version information 1127 1128 **Example request**: 1129 1130 GET /version HTTP/1.1 1131 1132 **Example response**: 1133 1134 HTTP/1.1 200 OK 1135 Content-Type: application/json 1136 1137 { 1138 "Version":"0.2.2", 1139 "GitCommit":"5a2a5cc+CHANGES", 1140 "GoVersion":"go1.0.3" 1141 } 1142 1143 Status Codes: 1144 1145 - **200** – no error 1146 - **500** – server error 1147 1148 ### Create a new image from a container's changes 1149 1150 `POST /commit` 1151 1152 Create a new image from a container's changes 1153 1154 **Example request**: 1155 1156 POST /commit?container=44c004db4b17&m=message&repo=myrepo HTTP/1.1 1157 Content-Type: application/json 1158 1159 { 1160 "Hostname":"", 1161 "User":"", 1162 "Memory":0, 1163 "MemorySwap":0, 1164 "AttachStdin":false, 1165 "AttachStdout":true, 1166 "AttachStderr":true, 1167 "PortSpecs":null, 1168 "Tty":false, 1169 "OpenStdin":false, 1170 "StdinOnce":false, 1171 "Env":null, 1172 "Cmd":[ 1173 "date" 1174 ], 1175 "Volumes":{ 1176 "/tmp": {} 1177 }, 1178 "WorkingDir":"", 1179 "DisableNetwork": false, 1180 "ExposedPorts":{ 1181 "22/tcp": {} 1182 } 1183 } 1184 1185 **Example response**: 1186 1187 HTTP/1.1 201 Created 1188 Content-Type: application/vnd.docker.raw-stream 1189 1190 {"Id": "596069db4bf5"} 1191 1192 Json Parameters: 1193 1194 - **config** - the container's configuration 1195 1196 Query Parameters: 1197 1198 - **container** – source container 1199 - **repo** – repository 1200 - **tag** – tag 1201 - **m** – commit message 1202 - **author** – author (e.g., "John Hannibal Smith 1203 <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") 1204 1205 Status Codes: 1206 1207 - **201** – no error 1208 - **404** – no such container 1209 - **500** – server error 1210 1211 ### Monitor Docker's events 1212 1213 `GET /events` 1214 1215 Get events from docker, either in real time via streaming, or via 1216 polling (using since). 1217 1218 Docker containers will report the following events: 1219 1220 create, destroy, die, export, kill, pause, restart, start, stop, unpause 1221 1222 and Docker images will report: 1223 1224 untag, delete 1225 1226 **Example request**: 1227 1228 GET /events?since=1374067924 1229 1230 **Example response**: 1231 1232 HTTP/1.1 200 OK 1233 Content-Type: application/json 1234 1235 {"status": "create", "id": "dfdf82bd3881","from": "base:latest", "time":1374067924} 1236 {"status": "start", "id": "dfdf82bd3881","from": "base:latest", "time":1374067924} 1237 {"status": "stop", "id": "dfdf82bd3881","from": "base:latest", "time":1374067966} 1238 {"status": "destroy", "id": "dfdf82bd3881","from": "base:latest", "time":1374067970} 1239 1240 Query Parameters: 1241 1242 - **since** – timestamp used for polling 1243 1244 Status Codes: 1245 1246 - **200** – no error 1247 - **500** – server error 1248 1249 ### Get a tarball containing all images and tags in a repository 1250 1251 `GET /images/(name)/get` 1252 1253 Get a tarball containing all images and metadata for the repository specified by `name`. 1254 1255 See the [image tarball format](#image-tarball-format) for more details. 1256 1257 **Example request** 1258 1259 GET /images/ubuntu/get 1260 1261 **Example response**: 1262 1263 HTTP/1.1 200 OK 1264 Content-Type: application/x-tar 1265 1266 Binary data stream 1267 1268 Status Codes: 1269 1270 - **200** – no error 1271 - **500** – server error 1272 1273 ### Load a tarball with a set of images and tags into docker 1274 1275 `POST /images/load` 1276 1277 Load a set of images and tags into the docker repository. 1278 1279 See the [image tarball format](#image-tarball-format) for more details. 1280 1281 **Example request** 1282 1283 POST /images/load 1284 1285 Tarball in body 1286 1287 **Example response**: 1288 1289 HTTP/1.1 200 OK 1290 1291 Status Codes: 1292 1293 - **200** – no error 1294 - **500** – server error 1295 1296 ### Image tarball format 1297 1298 An image tarball contains one directory per image layer (named using its long ID), 1299 each containing three files: 1300 1301 1. `VERSION`: currently `1.0` - the file format version 1302 2. `json`: detailed layer information, similar to `docker inspect layer_id` 1303 3. `layer.tar`: A tarfile containing the filesystem changes in this layer 1304 1305 The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories 1306 for storing attribute changes and deletions. 1307 1308 If the tarball defines a repository, there will also be a `repositories` file at 1309 the root that contains a list of repository and tag names mapped to layer IDs. 1310 1311 ``` 1312 {"hello-world": 1313 {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} 1314 } 1315 ``` 1316 1317 # 3. Going further 1318 1319 ## 3.1 Inside `docker run` 1320 1321 Here are the steps of `docker run` : 1322 1323 - Create the container 1324 1325 - If the status code is 404, it means the image doesn't exist: 1326 1327 - Try to pull it 1328 - Then retry to create the container 1329 1330 - Start the container 1331 1332 - If you are not in detached mode: 1333 1334 - Attach to the container, using logs=1 (to have stdout and 1335 - stderr from the container's start) and stream=1 1336 1337 - If in detached mode or only stdin is attached: 1338 1339 - Display the container's id 1340 1341 ## 3.2 Hijacking 1342 1343 In this version of the API, /attach, uses hijacking to transport stdin, 1344 stdout and stderr on the same socket. This might change in the future. 1345 1346 ## 3.3 CORS requests 1347 1348 To enable cross origin requests to the remote api add the flag 1349 "--api-enable-cors" when running docker in daemon mode. 1350 1351 $ docker -d -H="192.168.1.9:2375" --api-enable-cors