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