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