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