github.com/caseyhadden/docker@v1.6.2/docs/sources/reference/api/docker_remote_api_v1.17.md (about) 1 page_title: Remote API v1.17 2 page_description: API Documentation for Docker 3 page_keywords: API, Docker, rcli, REST, documentation 4 5 # Docker Remote API v1.17 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 11 [Bind Docker to another host/port or a Unix socket]( 12 /articles/basics/#bind-docker-to-another-hostport-or-a-unix-socket). 13 - The API tends to be REST, but for some complex commands, like `attach` 14 or `pull`, the HTTP connection is hijacked to transport `STDOUT`, 15 `STDIN` and `STDERR`. 16 17 # 2. Endpoints 18 19 ## 2.1 Containers 20 21 ### List containers 22 23 `GET /containers/json` 24 25 List containers 26 27 **Example request**: 28 29 GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 30 31 **Example response**: 32 33 HTTP/1.1 200 OK 34 Content-Type: application/json 35 36 [ 37 { 38 "Id": "8dfafdbc3a40", 39 "Image": "ubuntu:latest", 40 "Command": "echo 1", 41 "Created": 1367854155, 42 "Status": "Exit 0", 43 "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], 44 "SizeRw": 12288, 45 "SizeRootFs": 0 46 }, 47 { 48 "Id": "9cd87474be90", 49 "Image": "ubuntu:latest", 50 "Command": "echo 222222", 51 "Created": 1367854155, 52 "Status": "Exit 0", 53 "Ports": [], 54 "SizeRw": 12288, 55 "SizeRootFs": 0 56 }, 57 { 58 "Id": "3176a2479c92", 59 "Image": "ubuntu:latest", 60 "Command": "echo 3333333333333333", 61 "Created": 1367854154, 62 "Status": "Exit 0", 63 "Ports":[], 64 "SizeRw":12288, 65 "SizeRootFs":0 66 }, 67 { 68 "Id": "4cb07b47f9fb", 69 "Image": "ubuntu:latest", 70 "Command": "echo 444444444444444444444444444444444", 71 "Created": 1367854152, 72 "Status": "Exit 0", 73 "Ports": [], 74 "SizeRw": 12288, 75 "SizeRootFs": 0 76 } 77 ] 78 79 Query Parameters: 80 81 - **all** – 1/True/true or 0/False/false, Show all containers. 82 Only running containers are shown by default (i.e., this defaults to false) 83 - **limit** – Show `limit` last created 84 containers, include non-running ones. 85 - **since** – Show only containers created since Id, include 86 non-running ones. 87 - **before** – Show only containers created before Id, include 88 non-running ones. 89 - **size** – 1/True/true or 0/False/false, Show the containers 90 sizes 91 - **filters** - a json encoded value of the filters (a map[string][]string) to process on the containers list. Available filters: 92 - exited=<int> -- containers with exit code of <int> 93 - status=(restarting|running|paused|exited) 94 95 Status Codes: 96 97 - **200** – no error 98 - **400** – bad parameter 99 - **500** – server error 100 101 ### Create a container 102 103 `POST /containers/create` 104 105 Create a container 106 107 **Example request**: 108 109 POST /containers/create HTTP/1.1 110 Content-Type: application/json 111 112 { 113 "Hostname": "", 114 "Domainname": "", 115 "User": "", 116 "Memory": 0, 117 "MemorySwap": 0, 118 "CpuShares": 512, 119 "Cpuset": "0,1", 120 "AttachStdin": false, 121 "AttachStdout": true, 122 "AttachStderr": true, 123 "Tty": false, 124 "OpenStdin": false, 125 "StdinOnce": false, 126 "Env": null, 127 "Cmd": [ 128 "date" 129 ], 130 "Entrypoint": "", 131 "Image": "ubuntu", 132 "Volumes": { 133 "/tmp": {} 134 }, 135 "WorkingDir": "", 136 "NetworkDisabled": false, 137 "MacAddress": "12:34:56:78:9a:bc", 138 "ExposedPorts": { 139 "22/tcp": {} 140 }, 141 "SecurityOpts": [""], 142 "HostConfig": { 143 "Binds": ["/tmp:/tmp"], 144 "Links": ["redis3:redis"], 145 "LxcConf": {"lxc.utsname":"docker"}, 146 "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] }, 147 "PublishAllPorts": false, 148 "Privileged": false, 149 "ReadonlyRootfs": false, 150 "Dns": ["8.8.8.8"], 151 "DnsSearch": [""], 152 "ExtraHosts": null, 153 "VolumesFrom": ["parent", "other:ro"], 154 "CapAdd": ["NET_ADMIN"], 155 "CapDrop": ["MKNOD"], 156 "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 }, 157 "NetworkMode": "bridge", 158 "Devices": [] 159 } 160 } 161 162 **Example response**: 163 164 HTTP/1.1 201 Created 165 Content-Type: application/json 166 167 { 168 "Id":"e90e34656806" 169 "Warnings":[] 170 } 171 172 Json Parameters: 173 174 - **Hostname** - A string value containing the desired hostname to use for the 175 container. 176 - **Domainname** - A string value containing the desired domain name to use 177 for the container. 178 - **User** - A string value containg the user to use inside the container. 179 - **Memory** - Memory limit in bytes. 180 - **MemorySwap**- Total memory limit (memory + swap); set `-1` to disable swap, 181 always use this with `memory`, and make the value larger than `memory`. 182 - **CpuShares** - An integer value containing the CPU Shares for container 183 (ie. the relative weight vs othercontainers). 184 **CpuSet** - String value containg the cgroups Cpuset to use. 185 - **AttachStdin** - Boolean value, attaches to stdin. 186 - **AttachStdout** - Boolean value, attaches to stdout. 187 - **AttachStderr** - Boolean value, attaches to stderr. 188 - **Tty** - Boolean value, Attach standard streams to a tty, including stdin if it is not closed. 189 - **OpenStdin** - Boolean value, opens stdin, 190 - **StdinOnce** - Boolean value, close stdin after the 1 attached client disconnects. 191 - **Env** - A list of environment variables in the form of `VAR=value` 192 - **Cmd** - Command to run specified as a string or an array of strings. 193 - **Entrypoint** - Set the entrypoint for the container a a string or an array 194 of strings 195 - **Image** - String value containing the image name to use for the container 196 - **Volumes** – An object mapping mountpoint paths (strings) inside the 197 container to empty objects. 198 - **WorkingDir** - A string value containing the working dir for commands to 199 run in. 200 - **NetworkDisabled** - Boolean value, when true disables neworking for the 201 container 202 - **ExposedPorts** - An object mapping ports to an empty object in the form of: 203 `"ExposedPorts": { "<port>/<tcp|udp>: {}" }` 204 - **SecurityOpts**: A list of string values to customize labels for MLS 205 systems, such as SELinux. 206 - **HostConfig** 207 - **Binds** – A list of volume bindings for this container. Each volume 208 binding is a string of the form `container_path` (to create a new 209 volume for the container), `host_path:container_path` (to bind-mount 210 a host path into the container), or `host_path:container_path:ro` 211 (to make the bind-mount read-only inside the container). 212 - **Links** - A list of links for the container. Each link entry should be of 213 of the form "container_name:alias". 214 - **LxcConf** - LXC specific configurations. These configurations will only 215 work when using the `lxc` execution driver. 216 - **PortBindings** - A map of exposed container ports and the host port they 217 should map to. It should be specified in the form 218 `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }` 219 Take note that `port` is specified as a string and not an integer value. 220 - **PublishAllPorts** - Allocates a random host port for all of a container's 221 exposed ports. Specified as a boolean value. 222 - **Privileged** - Gives the container full access to the host. Specified as 223 a boolean value. 224 - **ReadonlyRootfs** - Mount the container's root filesystem as read only. 225 Specified as a boolean value. 226 - **Dns** - A list of dns servers for the container to use. 227 - **DnsSearch** - A list of DNS search domains 228 - **ExtraHosts** - A list of hostnames/IP mappings to be added to the 229 container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`. 230 - **VolumesFrom** - A list of volumes to inherit from another container. 231 Specified in the form `<container name>[:<ro|rw>]` 232 - **CapAdd** - A list of kernel capabilties to add to the container. 233 - **Capdrop** - A list of kernel capabilties to drop from the container. 234 - **RestartPolicy** – The behavior to apply when the container exits. The 235 value is an object with a `Name` property of either `"always"` to 236 always restart or `"on-failure"` to restart only when the container 237 exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` 238 controls the number of times to retry before giving up. 239 The default is not to restart. (optional) 240 An ever increasing delay (double the previous delay, starting at 100mS) 241 is added before each restart to prevent flooding the server. 242 - **NetworkMode** - Sets the networking mode for the container. Supported 243 values are: `bridge`, `host`, and `container:<name|id>` 244 - **Devices** - A list of devices to add to the container specified in the 245 form 246 `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}` 247 248 Query Parameters: 249 250 - **name** – Assign the specified name to the container. Must 251 match `/?[a-zA-Z0-9_-]+`. 252 253 Status Codes: 254 255 - **201** – no error 256 - **404** – no such container 257 - **406** – impossible to attach (container not running) 258 - **500** – server error 259 260 ### Inspect a container 261 262 `GET /containers/(id)/json` 263 264 Return low-level information on the container `id` 265 266 267 **Example request**: 268 269 GET /containers/4fa6e0f0c678/json HTTP/1.1 270 271 **Example response**: 272 273 HTTP/1.1 200 OK 274 Content-Type: application/json 275 276 { 277 "AppArmorProfile": "", 278 "Args": [ 279 "-c", 280 "exit 9" 281 ], 282 "Config": { 283 "AttachStderr": true, 284 "AttachStdin": false, 285 "AttachStdout": true, 286 "Cmd": [ 287 "/bin/sh", 288 "-c", 289 "exit 9" 290 ], 291 "CpuShares": 0, 292 "Cpuset": "", 293 "Domainname": "", 294 "Entrypoint": null, 295 "Env": [ 296 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 297 ], 298 "ExposedPorts": null, 299 "Hostname": "ba033ac44011", 300 "Image": "ubuntu", 301 "MacAddress": "", 302 "Memory": 0, 303 "MemorySwap": 0, 304 "NetworkDisabled": false, 305 "OnBuild": null, 306 "OpenStdin": false, 307 "PortSpecs": null, 308 "StdinOnce": false, 309 "Tty": false, 310 "User": "", 311 "Volumes": null, 312 "WorkingDir": "" 313 }, 314 "Created": "2015-01-06T15:47:31.485331387Z", 315 "Driver": "devicemapper", 316 "ExecDriver": "native-0.2", 317 "ExecIDs": null, 318 "HostConfig": { 319 "Binds": null, 320 "CapAdd": null, 321 "CapDrop": null, 322 "ContainerIDFile": "", 323 "Devices": [], 324 "Dns": null, 325 "DnsSearch": null, 326 "ExtraHosts": null, 327 "IpcMode": "", 328 "Links": null, 329 "LxcConf": [], 330 "NetworkMode": "bridge", 331 "PortBindings": {}, 332 "Privileged": false, 333 "ReadonlyRootfs": false, 334 "PublishAllPorts": false, 335 "RestartPolicy": { 336 "MaximumRetryCount": 2, 337 "Name": "on-failure" 338 }, 339 "SecurityOpt": null, 340 "VolumesFrom": null 341 }, 342 "HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname", 343 "HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts", 344 "Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39", 345 "Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2", 346 "MountLabel": "", 347 "Name": "/boring_euclid", 348 "NetworkSettings": { 349 "Bridge": "", 350 "Gateway": "", 351 "IPAddress": "", 352 "IPPrefixLen": 0, 353 "MacAddress": "", 354 "PortMapping": null, 355 "Ports": null 356 }, 357 "Path": "/bin/sh", 358 "ProcessLabel": "", 359 "ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf", 360 "RestartCount": 1, 361 "State": { 362 "Error": "", 363 "ExitCode": 9, 364 "FinishedAt": "2015-01-06T15:47:32.080254511Z", 365 "OOMKilled": false, 366 "Paused": false, 367 "Pid": 0, 368 "Restarting": false, 369 "Running": false, 370 "StartedAt": "2015-01-06T15:47:32.072697474Z" 371 }, 372 "Volumes": {}, 373 "VolumesRW": {} 374 } 375 376 Status Codes: 377 378 - **200** – no error 379 - **404** – no such container 380 - **500** – server error 381 382 ### List processes running inside a container 383 384 `GET /containers/(id)/top` 385 386 List processes running inside the container `id` 387 388 **Example request**: 389 390 GET /containers/4fa6e0f0c678/top HTTP/1.1 391 392 **Example response**: 393 394 HTTP/1.1 200 OK 395 Content-Type: application/json 396 397 { 398 "Titles": [ 399 "USER", 400 "PID", 401 "%CPU", 402 "%MEM", 403 "VSZ", 404 "RSS", 405 "TTY", 406 "STAT", 407 "START", 408 "TIME", 409 "COMMAND" 410 ], 411 "Processes": [ 412 ["root","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"], 413 ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"] 414 ] 415 } 416 417 Query Parameters: 418 419 - **ps_args** – ps arguments to use (e.g., aux) 420 421 Status Codes: 422 423 - **200** – no error 424 - **404** – no such container 425 - **500** – server error 426 427 ### Get container logs 428 429 `GET /containers/(id)/logs` 430 431 Get stdout and stderr logs from the container ``id`` 432 433 **Example request**: 434 435 GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10 HTTP/1.1 436 437 **Example response**: 438 439 HTTP/1.1 101 UPGRADED 440 Content-Type: application/vnd.docker.raw-stream 441 Connection: Upgrade 442 Upgrade: tcp 443 444 {{ STREAM }} 445 446 Query Parameters: 447 448 - **follow** – 1/True/true or 0/False/false, return stream. Default false 449 - **stdout** – 1/True/true or 0/False/false, show stdout log. Default false 450 - **stderr** – 1/True/true or 0/False/false, show stderr log. Default false 451 - **timestamps** – 1/True/true or 0/False/false, print timestamps for 452 every log line. Default false 453 - **tail** – Output specified number of lines at the end of logs: `all` or `<number>`. Default all 454 455 Status Codes: 456 457 - **101** – no error, hints proxy about hijacking 458 - **200** – no error, no upgrade header found 459 - **404** – no such container 460 - **500** – server error 461 462 ### Inspect changes on a container's filesystem 463 464 `GET /containers/(id)/changes` 465 466 Inspect changes on container `id`'s filesystem 467 468 **Example request**: 469 470 GET /containers/4fa6e0f0c678/changes HTTP/1.1 471 472 **Example response**: 473 474 HTTP/1.1 200 OK 475 Content-Type: application/json 476 477 [ 478 { 479 "Path": "/dev", 480 "Kind": 0 481 }, 482 { 483 "Path": "/dev/kmsg", 484 "Kind": 1 485 }, 486 { 487 "Path": "/test", 488 "Kind": 1 489 } 490 ] 491 492 Status Codes: 493 494 - **200** – no error 495 - **404** – no such container 496 - **500** – server error 497 498 ### Export a container 499 500 `GET /containers/(id)/export` 501 502 Export the contents of container `id` 503 504 **Example request**: 505 506 GET /containers/4fa6e0f0c678/export HTTP/1.1 507 508 **Example response**: 509 510 HTTP/1.1 200 OK 511 Content-Type: application/octet-stream 512 513 {{ TAR STREAM }} 514 515 Status Codes: 516 517 - **200** – no error 518 - **404** – no such container 519 - **500** – server error 520 521 ### Get container stats based on resource usage 522 523 `GET /containers/(id)/stats` 524 525 This endpoint returns a live stream of a container's resource usage statistics. 526 527 **Example request**: 528 529 GET /containers/redis1/stats HTTP/1.1 530 531 **Example response**: 532 533 HTTP/1.1 200 OK 534 Content-Type: application/json 535 536 { 537 "read" : "2015-01-08T22:57:31.547920715Z", 538 "network" : { 539 "rx_dropped" : 0, 540 "rx_bytes" : 648, 541 "rx_errors" : 0, 542 "tx_packets" : 8, 543 "tx_dropped" : 0, 544 "rx_packets" : 8, 545 "tx_errors" : 0, 546 "tx_bytes" : 648 547 }, 548 "memory_stats" : { 549 "stats" : { 550 "total_pgmajfault" : 0, 551 "cache" : 0, 552 "mapped_file" : 0, 553 "total_inactive_file" : 0, 554 "pgpgout" : 414, 555 "rss" : 6537216, 556 "total_mapped_file" : 0, 557 "writeback" : 0, 558 "unevictable" : 0, 559 "pgpgin" : 477, 560 "total_unevictable" : 0, 561 "pgmajfault" : 0, 562 "total_rss" : 6537216, 563 "total_rss_huge" : 6291456, 564 "total_writeback" : 0, 565 "total_inactive_anon" : 0, 566 "rss_huge" : 6291456, 567 "hierarchical_memory_limit" : 67108864, 568 "total_pgfault" : 964, 569 "total_active_file" : 0, 570 "active_anon" : 6537216, 571 "total_active_anon" : 6537216, 572 "total_pgpgout" : 414, 573 "total_cache" : 0, 574 "inactive_anon" : 0, 575 "active_file" : 0, 576 "pgfault" : 964, 577 "inactive_file" : 0, 578 "total_pgpgin" : 477 579 }, 580 "max_usage" : 6651904, 581 "usage" : 6537216, 582 "failcnt" : 0, 583 "limit" : 67108864 584 }, 585 "blkio_stats" : {}, 586 "cpu_stats" : { 587 "cpu_usage" : { 588 "percpu_usage" : [ 589 16970827, 590 1839451, 591 7107380, 592 10571290 593 ], 594 "usage_in_usermode" : 10000000, 595 "total_usage" : 36488948, 596 "usage_in_kernelmode" : 20000000 597 }, 598 "system_cpu_usage" : 20091722000000000, 599 "throttling_data" : {} 600 } 601 } 602 603 Status Codes: 604 605 - **200** – no error 606 - **404** – no such container 607 - **500** – server error 608 609 ### Resize a container TTY 610 611 `POST /containers/(id)/resize?h=<height>&w=<width>` 612 613 Resize the TTY for container with `id`. The container must be restarted for the resize to take effect. 614 615 **Example request**: 616 617 POST /containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1 618 619 **Example response**: 620 621 HTTP/1.1 200 OK 622 Content-Length: 0 623 Content-Type: text/plain; charset=utf-8 624 625 Status Codes: 626 627 - **200** – no error 628 - **404** – No such container 629 - **500** – Cannot resize container 630 631 ### Start a container 632 633 `POST /containers/(id)/start` 634 635 Start the container `id` 636 637 **Example request**: 638 639 POST /containers/(id)/start HTTP/1.1 640 Content-Type: application/json 641 642 **Example response**: 643 644 HTTP/1.1 204 No Content 645 646 Json Parameters: 647 648 Status Codes: 649 650 - **204** – no error 651 - **304** – container already started 652 - **404** – no such container 653 - **500** – server error 654 655 ### Stop a container 656 657 `POST /containers/(id)/stop` 658 659 Stop the container `id` 660 661 **Example request**: 662 663 POST /containers/e90e34656806/stop?t=5 HTTP/1.1 664 665 **Example response**: 666 667 HTTP/1.1 204 No Content 668 669 Query Parameters: 670 671 - **t** – number of seconds to wait before killing the container 672 673 Status Codes: 674 675 - **204** – no error 676 - **304** – container already stopped 677 - **404** – no such container 678 - **500** – server error 679 680 ### Restart a container 681 682 `POST /containers/(id)/restart` 683 684 Restart the container `id` 685 686 **Example request**: 687 688 POST /containers/e90e34656806/restart?t=5 HTTP/1.1 689 690 **Example response**: 691 692 HTTP/1.1 204 No Content 693 694 Query Parameters: 695 696 - **t** – number of seconds to wait before killing the container 697 698 Status Codes: 699 700 - **204** – no error 701 - **404** – no such container 702 - **500** – server error 703 704 ### Kill a container 705 706 `POST /containers/(id)/kill` 707 708 Kill the container `id` 709 710 **Example request**: 711 712 POST /containers/e90e34656806/kill HTTP/1.1 713 714 **Example response**: 715 716 HTTP/1.1 204 No Content 717 718 Query Parameters 719 720 - **signal** - Signal to send to the container: integer or string like "SIGINT". 721 When not set, SIGKILL is assumed and the call will waits for the container to exit. 722 723 Status Codes: 724 725 - **204** – no error 726 - **404** – no such container 727 - **500** – server error 728 729 ### Rename a container 730 731 `POST /containers/(id)/rename` 732 733 Rename the container `id` to a `new_name` 734 735 **Example request**: 736 737 POST /containers/e90e34656806/rename?name=new_name HTTP/1.1 738 739 **Example response**: 740 741 HTTP/1.1 204 No Content 742 743 Query Parameters: 744 745 - **name** – new name for the container 746 747 Status Codes: 748 749 - **204** – no error 750 - **404** – no such container 751 - **409** - conflict name already assigned 752 - **500** – server error 753 754 ### Pause a container 755 756 `POST /containers/(id)/pause` 757 758 Pause the container `id` 759 760 **Example request**: 761 762 POST /containers/e90e34656806/pause HTTP/1.1 763 764 **Example response**: 765 766 HTTP/1.1 204 No Content 767 768 Status Codes: 769 770 - **204** – no error 771 - **404** – no such container 772 - **500** – server error 773 774 ### Unpause a container 775 776 `POST /containers/(id)/unpause` 777 778 Unpause the container `id` 779 780 **Example request**: 781 782 POST /containers/e90e34656806/unpause HTTP/1.1 783 784 **Example response**: 785 786 HTTP/1.1 204 No Content 787 788 Status Codes: 789 790 - **204** – no error 791 - **404** – no such container 792 - **500** – server error 793 794 ### Attach to a container 795 796 `POST /containers/(id)/attach` 797 798 Attach to the container `id` 799 800 **Example request**: 801 802 POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 803 804 **Example response**: 805 806 HTTP/1.1 101 UPGRADED 807 Content-Type: application/vnd.docker.raw-stream 808 Connection: Upgrade 809 Upgrade: tcp 810 811 {{ STREAM }} 812 813 Query Parameters: 814 815 - **logs** – 1/True/true or 0/False/false, return logs. Default false 816 - **stream** – 1/True/true or 0/False/false, return stream. 817 Default false 818 - **stdin** – 1/True/true or 0/False/false, if stream=true, attach 819 to stdin. Default false 820 - **stdout** – 1/True/true or 0/False/false, if logs=true, return 821 stdout log, if stream=true, attach to stdout. Default false 822 - **stderr** – 1/True/true or 0/False/false, if logs=true, return 823 stderr log, if stream=true, attach to stderr. Default false 824 825 Status Codes: 826 827 - **101** – no error, hints proxy about hijacking 828 - **200** – no error, no upgrade header found 829 - **400** – bad parameter 830 - **404** – no such container 831 - **500** – server error 832 833 **Stream details**: 834 835 When using the TTY setting is enabled in 836 [`POST /containers/create` 837 ](/reference/api/docker_remote_api_v1.9/#create-a-container "POST /containers/create"), 838 the stream is the raw data from the process PTY and client's stdin. 839 When the TTY is disabled, then the stream is multiplexed to separate 840 stdout and stderr. 841 842 The format is a **Header** and a **Payload** (frame). 843 844 **HEADER** 845 846 The header will contain the information on which stream write the 847 stream (stdout or stderr). It also contain the size of the 848 associated frame encoded on the last 4 bytes (uint32). 849 850 It is encoded on the first 8 bytes like this: 851 852 header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} 853 854 `STREAM_TYPE` can be: 855 856 - 0: stdin (will be written on stdout) 857 - 1: stdout 858 - 2: stderr 859 860 `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of 861 the uint32 size encoded as big endian. 862 863 **PAYLOAD** 864 865 The payload is the raw stream. 866 867 **IMPLEMENTATION** 868 869 The simplest way to implement the Attach protocol is the following: 870 871 1. Read 8 bytes 872 2. chose stdout or stderr depending on the first byte 873 3. Extract the frame size from the last 4 byets 874 4. Read the extracted size and output it on the correct output 875 5. Goto 1 876 877 ### Attach to a container (websocket) 878 879 `GET /containers/(id)/attach/ws` 880 881 Attach to the container `id` via websocket 882 883 Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) 884 885 **Example request** 886 887 GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 888 889 **Example response** 890 891 {{ STREAM }} 892 893 Query Parameters: 894 895 - **logs** – 1/True/true or 0/False/false, return logs. Default false 896 - **stream** – 1/True/true or 0/False/false, return stream. 897 Default false 898 - **stdin** – 1/True/true or 0/False/false, if stream=true, attach 899 to stdin. Default false 900 - **stdout** – 1/True/true or 0/False/false, if logs=true, return 901 stdout log, if stream=true, attach to stdout. Default false 902 - **stderr** – 1/True/true or 0/False/false, if logs=true, return 903 stderr log, if stream=true, attach to stderr. Default false 904 905 Status Codes: 906 907 - **200** – no error 908 - **400** – bad parameter 909 - **404** – no such container 910 - **500** – server error 911 912 ### Wait a container 913 914 `POST /containers/(id)/wait` 915 916 Block until container `id` stops, then returns the exit code 917 918 **Example request**: 919 920 POST /containers/16253994b7c4/wait HTTP/1.1 921 922 **Example response**: 923 924 HTTP/1.1 200 OK 925 Content-Type: application/json 926 927 {"StatusCode": 0} 928 929 Status Codes: 930 931 - **200** – no error 932 - **404** – no such container 933 - **500** – server error 934 935 ### Remove a container 936 937 `DELETE /containers/(id)` 938 939 Remove the container `id` from the filesystem 940 941 **Example request**: 942 943 DELETE /containers/16253994b7c4?v=1 HTTP/1.1 944 945 **Example response**: 946 947 HTTP/1.1 204 No Content 948 949 Query Parameters: 950 951 - **v** – 1/True/true or 0/False/false, Remove the volumes 952 associated to the container. Default false 953 - **force** - 1/True/true or 0/False/false, Kill then remove the container. 954 Default false 955 956 Status Codes: 957 958 - **204** – no error 959 - **400** – bad parameter 960 - **404** – no such container 961 - **500** – server error 962 963 ### Copy files or folders from a container 964 965 `POST /containers/(id)/copy` 966 967 Copy files or folders of container `id` 968 969 **Example request**: 970 971 POST /containers/4fa6e0f0c678/copy HTTP/1.1 972 Content-Type: application/json 973 974 { 975 "Resource": "test.txt" 976 } 977 978 **Example response**: 979 980 HTTP/1.1 200 OK 981 Content-Type: application/x-tar 982 983 {{ TAR STREAM }} 984 985 Status Codes: 986 987 - **200** – no error 988 - **404** – no such container 989 - **500** – server error 990 991 ## 2.2 Images 992 993 ### List Images 994 995 `GET /images/json` 996 997 **Example request**: 998 999 GET /images/json?all=0 HTTP/1.1 1000 1001 **Example response**: 1002 1003 HTTP/1.1 200 OK 1004 Content-Type: application/json 1005 1006 [ 1007 { 1008 "RepoTags": [ 1009 "ubuntu:12.04", 1010 "ubuntu:precise", 1011 "ubuntu:latest" 1012 ], 1013 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 1014 "Created": 1365714795, 1015 "Size": 131506275, 1016 "VirtualSize": 131506275 1017 }, 1018 { 1019 "RepoTags": [ 1020 "ubuntu:12.10", 1021 "ubuntu:quantal" 1022 ], 1023 "ParentId": "27cf784147099545", 1024 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 1025 "Created": 1364102658, 1026 "Size": 24653, 1027 "VirtualSize": 180116135 1028 } 1029 ] 1030 1031 1032 Query Parameters: 1033 1034 - **all** – 1/True/true or 0/False/false, default false 1035 - **filters** – a json encoded value of the filters (a map[string][]string) to process on the images list. Available filters: 1036 - dangling=true 1037 1038 ### Build image from a Dockerfile 1039 1040 `POST /build` 1041 1042 Build an image from a Dockerfile 1043 1044 **Example request**: 1045 1046 POST /build HTTP/1.1 1047 1048 {{ TAR STREAM }} 1049 1050 **Example response**: 1051 1052 HTTP/1.1 200 OK 1053 Content-Type: application/json 1054 1055 {"stream": "Step 1..."} 1056 {"stream": "..."} 1057 {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} 1058 1059 The input stream must be a tar archive compressed with one of the 1060 following algorithms: identity (no compression), gzip, bzip2, xz. 1061 1062 The archive must include a build instructions file, typically called 1063 `Dockerfile` at the root of the archive. The `dockerfile` parameter may be 1064 used to specify a different build instructions file by having its value be 1065 the path to the alternate build instructions file to use. 1066 1067 The archive may include any number of other files, 1068 which will be accessible in the build context (See the [*ADD build 1069 command*](/reference/builder/#dockerbuilder)). 1070 1071 Query Parameters: 1072 1073 - **dockerfile** - path within the build context to the Dockerfile 1074 - **t** – repository name (and optionally a tag) to be applied to 1075 the resulting image in case of success 1076 - **remote** – git or HTTP/HTTPS URI build source 1077 - **q** – suppress verbose build output 1078 - **nocache** – do not use the cache when building the image 1079 - **pull** - attempt to pull the image even if an older image exists locally 1080 - **rm** - remove intermediate containers after a successful build (default behavior) 1081 - **forcerm** - always remove intermediate containers (includes rm) 1082 1083 Request Headers: 1084 1085 - **Content-type** – should be set to `"application/tar"`. 1086 - **X-Registry-Config** – base64-encoded ConfigFile objec 1087 1088 Status Codes: 1089 1090 - **200** – no error 1091 - **500** – server error 1092 1093 ### Create an image 1094 1095 `POST /images/create` 1096 1097 Create an image, either by pulling it from the registry or by importing it 1098 1099 **Example request**: 1100 1101 POST /images/create?fromImage=ubuntu HTTP/1.1 1102 1103 **Example response**: 1104 1105 HTTP/1.1 200 OK 1106 Content-Type: application/json 1107 1108 {"status": "Pulling..."} 1109 {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} 1110 {"error": "Invalid..."} 1111 ... 1112 1113 When using this endpoint to pull an image from the registry, the 1114 `X-Registry-Auth` header can be used to include 1115 a base64-encoded AuthConfig object. 1116 1117 Query Parameters: 1118 1119 - **fromImage** – name of the image to pull 1120 - **fromSrc** – source to import. The value may be a URL from which the image 1121 can be retrieved or `-` to read the image from the request body. 1122 - **repo** – repository 1123 - **tag** – tag 1124 - **registry** – the registry to pull from 1125 1126 Request Headers: 1127 1128 - **X-Registry-Auth** – base64-encoded AuthConfig object 1129 1130 Status Codes: 1131 1132 - **200** – no error 1133 - **500** – server error 1134 1135 1136 1137 ### Inspect an image 1138 1139 `GET /images/(name)/json` 1140 1141 Return low-level information on the image `name` 1142 1143 **Example request**: 1144 1145 GET /images/ubuntu/json HTTP/1.1 1146 1147 **Example response**: 1148 1149 HTTP/1.1 200 OK 1150 Content-Type: application/json 1151 1152 { 1153 "Created": "2013-03-23T22:24:18.818426-07:00", 1154 "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", 1155 "ContainerConfig": 1156 { 1157 "Hostname": "", 1158 "User": "", 1159 "Memory": 0, 1160 "MemorySwap": 0, 1161 "AttachStdin": false, 1162 "AttachStdout": false, 1163 "AttachStderr": false, 1164 "PortSpecs": null, 1165 "Tty": true, 1166 "OpenStdin": true, 1167 "StdinOnce": false, 1168 "Env": null, 1169 "Cmd": ["/bin/bash"], 1170 "Dns": null, 1171 "Image": "ubuntu", 1172 "Volumes": null, 1173 "VolumesFrom": "", 1174 "WorkingDir": "" 1175 }, 1176 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 1177 "Parent": "27cf784147099545", 1178 "Size": 6824592 1179 } 1180 1181 Status Codes: 1182 1183 - **200** – no error 1184 - **404** – no such image 1185 - **500** – server error 1186 1187 ### Get the history of an image 1188 1189 `GET /images/(name)/history` 1190 1191 Return the history of the image `name` 1192 1193 **Example request**: 1194 1195 GET /images/ubuntu/history HTTP/1.1 1196 1197 **Example response**: 1198 1199 HTTP/1.1 200 OK 1200 Content-Type: application/json 1201 1202 [ 1203 { 1204 "Id": "b750fe79269d", 1205 "Created": 1364102658, 1206 "CreatedBy": "/bin/bash" 1207 }, 1208 { 1209 "Id": "27cf78414709", 1210 "Created": 1364068391, 1211 "CreatedBy": "" 1212 } 1213 ] 1214 1215 Status Codes: 1216 1217 - **200** – no error 1218 - **404** – no such image 1219 - **500** – server error 1220 1221 ### Push an image on the registry 1222 1223 `POST /images/(name)/push` 1224 1225 Push the image `name` on the registry 1226 1227 **Example request**: 1228 1229 POST /images/test/push HTTP/1.1 1230 1231 **Example response**: 1232 1233 HTTP/1.1 200 OK 1234 Content-Type: application/json 1235 1236 {"status": "Pushing..."} 1237 {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} 1238 {"error": "Invalid..."} 1239 ... 1240 1241 If you wish to push an image on to a private registry, that image must already have been tagged 1242 into a repository which references that registry host name and port. This repository name should 1243 then be used in the URL. This mirrors the flow of the CLI. 1244 1245 **Example request**: 1246 1247 POST /images/registry.acme.com:5000/test/push HTTP/1.1 1248 1249 1250 Query Parameters: 1251 1252 - **tag** – the tag to associate with the image on the registry, optional 1253 1254 Request Headers: 1255 1256 - **X-Registry-Auth** – include a base64-encoded AuthConfig 1257 object. 1258 1259 Status Codes: 1260 1261 - **200** – no error 1262 - **404** – no such image 1263 - **500** – server error 1264 1265 ### Tag an image into a repository 1266 1267 `POST /images/(name)/tag` 1268 1269 Tag the image `name` into a repository 1270 1271 **Example request**: 1272 1273 POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 1274 1275 **Example response**: 1276 1277 HTTP/1.1 201 OK 1278 1279 Query Parameters: 1280 1281 - **repo** – The repository to tag in 1282 - **force** – 1/True/true or 0/False/false, default false 1283 - **tag** - The new tag name 1284 1285 Status Codes: 1286 1287 - **201** – no error 1288 - **400** – bad parameter 1289 - **404** – no such image 1290 - **409** – conflict 1291 - **500** – server error 1292 1293 ### Remove an image 1294 1295 `DELETE /images/(name)` 1296 1297 Remove the image `name` from the filesystem 1298 1299 **Example request**: 1300 1301 DELETE /images/test HTTP/1.1 1302 1303 **Example response**: 1304 1305 HTTP/1.1 200 OK 1306 Content-type: application/json 1307 1308 [ 1309 {"Untagged": "3e2f21a89f"}, 1310 {"Deleted": "3e2f21a89f"}, 1311 {"Deleted": "53b4f83ac9"} 1312 ] 1313 1314 Query Parameters: 1315 1316 - **force** – 1/True/true or 0/False/false, default false 1317 - **noprune** – 1/True/true or 0/False/false, default false 1318 1319 Status Codes: 1320 1321 - **200** – no error 1322 - **404** – no such image 1323 - **409** – conflict 1324 - **500** – server error 1325 1326 ### Search images 1327 1328 `GET /images/search` 1329 1330 Search for an image on [Docker Hub](https://hub.docker.com). 1331 1332 > **Note**: 1333 > The response keys have changed from API v1.6 to reflect the JSON 1334 > sent by the registry server to the docker daemon's request. 1335 1336 **Example request**: 1337 1338 GET /images/search?term=sshd HTTP/1.1 1339 1340 **Example response**: 1341 1342 HTTP/1.1 200 OK 1343 Content-Type: application/json 1344 1345 [ 1346 { 1347 "description": "", 1348 "is_official": false, 1349 "is_automated": false, 1350 "name": "wma55/u1210sshd", 1351 "star_count": 0 1352 }, 1353 { 1354 "description": "", 1355 "is_official": false, 1356 "is_automated": false, 1357 "name": "jdswinbank/sshd", 1358 "star_count": 0 1359 }, 1360 { 1361 "description": "", 1362 "is_official": false, 1363 "is_automated": false, 1364 "name": "vgauthier/sshd", 1365 "star_count": 0 1366 } 1367 ... 1368 ] 1369 1370 Query Parameters: 1371 1372 - **term** – term to search 1373 1374 Status Codes: 1375 1376 - **200** – no error 1377 - **500** – server error 1378 1379 ## 2.3 Misc 1380 1381 ### Check auth configuration 1382 1383 `POST /auth` 1384 1385 Get the default username and email 1386 1387 **Example request**: 1388 1389 POST /auth HTTP/1.1 1390 Content-Type: application/json 1391 1392 { 1393 "username":" hannibal", 1394 "password: "xxxx", 1395 "email": "hannibal@a-team.com", 1396 "serveraddress": "https://index.docker.io/v1/" 1397 } 1398 1399 **Example response**: 1400 1401 HTTP/1.1 200 OK 1402 1403 Status Codes: 1404 1405 - **200** – no error 1406 - **204** – no error 1407 - **500** – server error 1408 1409 ### Display system-wide information 1410 1411 `GET /info` 1412 1413 Display system-wide information 1414 1415 **Example request**: 1416 1417 GET /info HTTP/1.1 1418 1419 **Example response**: 1420 1421 HTTP/1.1 200 OK 1422 Content-Type: application/json 1423 1424 { 1425 "Containers":11, 1426 "Images":16, 1427 "Driver":"btrfs", 1428 "DriverStatus": [[""]], 1429 "ExecutionDriver":"native-0.1", 1430 "KernelVersion":"3.12.0-1-amd64" 1431 "NCPU":1, 1432 "MemTotal":2099236864, 1433 "Name":"prod-server-42", 1434 "ID":"7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS", 1435 "Debug":false, 1436 "NFd": 11, 1437 "NGoroutines":21, 1438 "NEventsListener":0, 1439 "InitPath":"/usr/bin/docker", 1440 "InitSha1":"", 1441 "IndexServerAddress":["https://index.docker.io/v1/"], 1442 "MemoryLimit":true, 1443 "SwapLimit":false, 1444 "IPv4Forwarding":true, 1445 "Labels":["storage=ssd"], 1446 "DockerRootDir": "/var/lib/docker", 1447 "OperatingSystem": "Boot2Docker", 1448 } 1449 1450 Status Codes: 1451 1452 - **200** – no error 1453 - **500** – server error 1454 1455 ### Show the docker version information 1456 1457 `GET /version` 1458 1459 Show the docker version information 1460 1461 **Example request**: 1462 1463 GET /version HTTP/1.1 1464 1465 **Example response**: 1466 1467 HTTP/1.1 200 OK 1468 Content-Type: application/json 1469 1470 { 1471 "ApiVersion": "1.12", 1472 "Version": "0.2.2", 1473 "GitCommit": "5a2a5cc+CHANGES", 1474 "GoVersion": "go1.0.3" 1475 } 1476 1477 Status Codes: 1478 1479 - **200** – no error 1480 - **500** – server error 1481 1482 ### Ping the docker server 1483 1484 `GET /_ping` 1485 1486 Ping the docker server 1487 1488 **Example request**: 1489 1490 GET /_ping HTTP/1.1 1491 1492 **Example response**: 1493 1494 HTTP/1.1 200 OK 1495 Content-Type: text/plain 1496 1497 OK 1498 1499 Status Codes: 1500 1501 - **200** - no error 1502 - **500** - server error 1503 1504 ### Create a new image from a container's changes 1505 1506 `POST /commit` 1507 1508 Create a new image from a container's changes 1509 1510 **Example request**: 1511 1512 POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 1513 Content-Type: application/json 1514 1515 { 1516 "Hostname": "", 1517 "Domainname": "", 1518 "User": "", 1519 "Memory": 0, 1520 "MemorySwap": 0, 1521 "CpuShares": 512, 1522 "Cpuset": "0,1", 1523 "AttachStdin": false, 1524 "AttachStdout": true, 1525 "AttachStderr": true, 1526 "PortSpecs": null, 1527 "Tty": false, 1528 "OpenStdin": false, 1529 "StdinOnce": false, 1530 "Env": null, 1531 "Cmd": [ 1532 "date" 1533 ], 1534 "Volumes": { 1535 "/tmp": {} 1536 }, 1537 "WorkingDir": "", 1538 "NetworkDisabled": false, 1539 "ExposedPorts": { 1540 "22/tcp": {} 1541 } 1542 } 1543 1544 **Example response**: 1545 1546 HTTP/1.1 201 Created 1547 Content-Type: application/vnd.docker.raw-stream 1548 1549 {"Id": "596069db4bf5"} 1550 1551 Json Parameters: 1552 1553 - **config** - the container's configuration 1554 1555 Query Parameters: 1556 1557 - **container** – source container 1558 - **repo** – repository 1559 - **tag** – tag 1560 - **comment** – commit message 1561 - **author** – author (e.g., "John Hannibal Smith 1562 <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") 1563 1564 Status Codes: 1565 1566 - **201** – no error 1567 - **404** – no such container 1568 - **500** – server error 1569 1570 ### Monitor Docker's events 1571 1572 `GET /events` 1573 1574 Get container events from docker, either in real time via streaming, or via 1575 polling (using since). 1576 1577 Docker containers will report the following events: 1578 1579 create, destroy, die, exec_create, exec_start, export, kill, oom, pause, restart, start, stop, unpause 1580 1581 and Docker images will report: 1582 1583 untag, delete 1584 1585 **Example request**: 1586 1587 GET /events?since=1374067924 1588 1589 **Example response**: 1590 1591 HTTP/1.1 200 OK 1592 Content-Type: application/json 1593 1594 {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} 1595 {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} 1596 {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} 1597 {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} 1598 1599 Query Parameters: 1600 1601 - **since** – timestamp used for polling 1602 - **until** – timestamp used for polling 1603 - **filters** – a json encoded value of the filters (a map[string][]string) to process on the event list. Available filters: 1604 - event=<string> -- event to filter 1605 - image=<string> -- image to filter 1606 - container=<string> -- container to filter 1607 1608 Status Codes: 1609 1610 - **200** – no error 1611 - **500** – server error 1612 1613 ### Get a tarball containing all images in a repository 1614 1615 `GET /images/(name)/get` 1616 1617 Get a tarball containing all images and metadata for the repository specified 1618 by `name`. 1619 1620 If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image 1621 (and its parents) are returned. If `name` is an image ID, similarly only tha 1622 image (and its parents) are returned, but with the exclusion of the 1623 'repositories' file in the tarball, as there were no image names referenced. 1624 1625 See the [image tarball format](#image-tarball-format) for more details. 1626 1627 **Example request** 1628 1629 GET /images/ubuntu/get 1630 1631 **Example response**: 1632 1633 HTTP/1.1 200 OK 1634 Content-Type: application/x-tar 1635 1636 Binary data stream 1637 1638 Status Codes: 1639 1640 - **200** – no error 1641 - **500** – server error 1642 1643 ### Get a tarball containing all images. 1644 1645 `GET /images/get` 1646 1647 Get a tarball containing all images and metadata for one or more repositories. 1648 1649 For each value of the `names` parameter: if it is a specific name and tag (e.g. 1650 ubuntu:latest), then only that image (and its parents) are returned; if it is 1651 an image ID, similarly only that image (and its parents) are returned and there 1652 would be no names referenced in the 'repositories' file for this image ID. 1653 1654 See the [image tarball format](#image-tarball-format) for more details. 1655 1656 **Example request** 1657 1658 GET /images/get?names=myname%2Fmyapp%3Alatest&names=busybox 1659 1660 **Example response**: 1661 1662 HTTP/1.1 200 OK 1663 Content-Type: application/x-tar 1664 1665 Binary data stream 1666 1667 Status Codes: 1668 1669 - **200** – no error 1670 - **500** – server error 1671 1672 ### Load a tarball with a set of images and tags into docker 1673 1674 `POST /images/load` 1675 1676 Load a set of images and tags into the docker repository. 1677 See the [image tarball format](#image-tarball-format) for more details. 1678 1679 **Example request** 1680 1681 POST /images/load 1682 1683 Tarball in body 1684 1685 **Example response**: 1686 1687 HTTP/1.1 200 OK 1688 1689 Status Codes: 1690 1691 - **200** – no error 1692 - **500** – server error 1693 1694 ### Image tarball format 1695 1696 An image tarball contains one directory per image layer (named using its long ID), 1697 each containing three files: 1698 1699 1. `VERSION`: currently `1.0` - the file format version 1700 2. `json`: detailed layer information, similar to `docker inspect layer_id` 1701 3. `layer.tar`: A tarfile containing the filesystem changes in this layer 1702 1703 The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories 1704 for storing attribute changes and deletions. 1705 1706 If the tarball defines a repository, there will also be a `repositories` file at 1707 the root that contains a list of repository and tag names mapped to layer IDs. 1708 1709 ``` 1710 {"hello-world": 1711 {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} 1712 } 1713 ``` 1714 1715 ### Exec Create 1716 1717 `POST /containers/(id)/exec` 1718 1719 Sets up an exec instance in a running container `id` 1720 1721 **Example request**: 1722 1723 POST /containers/e90e34656806/exec HTTP/1.1 1724 Content-Type: application/json 1725 1726 { 1727 "AttachStdin": false, 1728 "AttachStdout": true, 1729 "AttachStderr": true, 1730 "Tty": false, 1731 "Cmd": [ 1732 "date" 1733 ], 1734 } 1735 1736 **Example response**: 1737 1738 HTTP/1.1 201 OK 1739 Content-Type: application/json 1740 1741 { 1742 "Id": "f90e34656806" 1743 } 1744 1745 Json Parameters: 1746 1747 - **AttachStdin** - Boolean value, attaches to stdin of the exec command. 1748 - **AttachStdout** - Boolean value, attaches to stdout of the exec command. 1749 - **AttachStderr** - Boolean value, attaches to stderr of the exec command. 1750 - **Tty** - Boolean value to allocate a pseudo-TTY 1751 - **Cmd** - Command to run specified as a string or an array of strings. 1752 1753 1754 Status Codes: 1755 1756 - **201** – no error 1757 - **404** – no such container 1758 1759 ### Exec Start 1760 1761 `POST /exec/(id)/start` 1762 1763 Starts a previously set up exec instance `id`. If `detach` is true, this API 1764 returns after starting the `exec` command. Otherwise, this API sets up an 1765 interactive session with the `exec` command. 1766 1767 **Example request**: 1768 1769 POST /exec/e90e34656806/start HTTP/1.1 1770 Content-Type: application/json 1771 1772 { 1773 "Detach": false, 1774 "Tty": false, 1775 } 1776 1777 **Example response**: 1778 1779 HTTP/1.1 201 OK 1780 Content-Type: application/json 1781 1782 {{ STREAM }} 1783 1784 Json Parameters: 1785 1786 - **Detach** - Detach from the exec command 1787 - **Tty** - Boolean value to allocate a pseudo-TTY 1788 1789 Status Codes: 1790 1791 - **201** – no error 1792 - **404** – no such exec instance 1793 1794 **Stream details**: 1795 Similar to the stream behavior of `POST /container/(id)/attach` API 1796 1797 ### Exec Resize 1798 1799 `POST /exec/(id)/resize` 1800 1801 Resizes the tty session used by the exec command `id`. 1802 This API is valid only if `tty` was specified as part of creating and starting the exec command. 1803 1804 **Example request**: 1805 1806 POST /exec/e90e34656806/resize HTTP/1.1 1807 Content-Type: text/plain 1808 1809 **Example response**: 1810 1811 HTTP/1.1 201 OK 1812 Content-Type: text/plain 1813 1814 Query Parameters: 1815 1816 - **h** – height of tty session 1817 - **w** – width 1818 1819 Status Codes: 1820 1821 - **201** – no error 1822 - **404** – no such exec instance 1823 1824 ### Exec Inspect 1825 1826 `GET /exec/(id)/json` 1827 1828 Return low-level information about the exec command `id`. 1829 1830 **Example request**: 1831 1832 GET /exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1 1833 1834 **Example response**: 1835 1836 HTTP/1.1 200 OK 1837 Content-Type: plain/text 1838 1839 { 1840 "ID" : "11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39", 1841 "Running" : false, 1842 "ExitCode" : 2, 1843 "ProcessConfig" : { 1844 "privileged" : false, 1845 "user" : "", 1846 "tty" : false, 1847 "entrypoint" : "sh", 1848 "arguments" : [ 1849 "-c", 1850 "exit 2" 1851 ] 1852 }, 1853 "OpenStdin" : false, 1854 "OpenStderr" : false, 1855 "OpenStdout" : false, 1856 "Container" : { 1857 "State" : { 1858 "Running" : true, 1859 "Paused" : false, 1860 "Restarting" : false, 1861 "OOMKilled" : false, 1862 "Pid" : 3650, 1863 "ExitCode" : 0, 1864 "Error" : "", 1865 "StartedAt" : "2014-11-17T22:26:03.717657531Z", 1866 "FinishedAt" : "0001-01-01T00:00:00Z" 1867 }, 1868 "ID" : "8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c", 1869 "Created" : "2014-11-17T22:26:03.626304998Z", 1870 "Path" : "date", 1871 "Args" : [], 1872 "Config" : { 1873 "Hostname" : "8f177a186b97", 1874 "Domainname" : "", 1875 "User" : "", 1876 "Memory" : 0, 1877 "MemorySwap" : 0, 1878 "CpuShares" : 0, 1879 "Cpuset" : "", 1880 "AttachStdin" : false, 1881 "AttachStdout" : false, 1882 "AttachStderr" : false, 1883 "PortSpecs" : null, 1884 "ExposedPorts" : null, 1885 "Tty" : false, 1886 "OpenStdin" : false, 1887 "StdinOnce" : false, 1888 "Env" : [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ], 1889 "Cmd" : [ 1890 "date" 1891 ], 1892 "Image" : "ubuntu", 1893 "Volumes" : null, 1894 "WorkingDir" : "", 1895 "Entrypoint" : null, 1896 "NetworkDisabled" : false, 1897 "MacAddress" : "", 1898 "OnBuild" : null, 1899 "SecurityOpt" : null 1900 }, 1901 "Image" : "5506de2b643be1e6febbf3b8a240760c6843244c41e12aa2f60ccbb7153d17f5", 1902 "NetworkSettings" : { 1903 "IPAddress" : "172.17.0.2", 1904 "IPPrefixLen" : 16, 1905 "MacAddress" : "02:42:ac:11:00:02", 1906 "Gateway" : "172.17.42.1", 1907 "Bridge" : "docker0", 1908 "PortMapping" : null, 1909 "Ports" : {} 1910 }, 1911 "ResolvConfPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/resolv.conf", 1912 "HostnamePath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hostname", 1913 "HostsPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hosts", 1914 "Name" : "/test", 1915 "Driver" : "aufs", 1916 "ExecDriver" : "native-0.2", 1917 "MountLabel" : "", 1918 "ProcessLabel" : "", 1919 "AppArmorProfile" : "", 1920 "RestartCount" : 0, 1921 "Volumes" : {}, 1922 "VolumesRW" : {} 1923 } 1924 } 1925 1926 Status Codes: 1927 1928 - **200** – no error 1929 - **404** – no such exec instance 1930 - **500** - server error 1931 1932 # 3. Going further 1933 1934 ## 3.1 Inside `docker run` 1935 1936 As an example, the `docker run` command line makes the following API calls: 1937 1938 - Create the container 1939 1940 - If the status code is 404, it means the image doesn't exist: 1941 - Try to pull it 1942 - Then retry to create the container 1943 1944 - Start the container 1945 1946 - If you are not in detached mode: 1947 - Attach to the container, using logs=1 (to have stdout and 1948 stderr from the container's start) and stream=1 1949 1950 - If in detached mode or only stdin is attached: 1951 - Display the container's id 1952 1953 ## 3.2 Hijacking 1954 1955 In this version of the API, /attach, uses hijacking to transport stdin, 1956 stdout and stderr on the same socket. 1957 1958 To hint potential proxies about connection hijacking, Docker client sends 1959 connection upgrade headers similarly to websocket. 1960 1961 Upgrade: tcp 1962 Connection: Upgrade 1963 1964 When Docker daemon detects the `Upgrade` header, it will switch its status code 1965 from **200 OK** to **101 UPGRADED** and resend the same headers. 1966 1967 This might change in the future. 1968 1969 ## 3.3 CORS Requests 1970 1971 To set cross origin requests to the remote api, please add flag "--api-enable-cors" 1972 when running docker in daemon mode. 1973 1974 $ docker -d -H="192.168.1.9:2375" --api-enable-cors