github.com/kim0/docker@v0.6.2-0.20161130212042-4addda3f07e7/docs/reference/api/docker_remote_api_v1.21.md (about) 1 --- 2 title: "Remote API v1.21" 3 description: "API Documentation for Docker" 4 keywords: ["API, Docker, rcli, REST, documentation"] 5 --- 6 7 <!-- This file is maintained within the docker/docker Github 8 repository at https://github.com/docker/docker/. Make all 9 pull requests against that repo. If you see this file in 10 another repository, consider it read-only there, as it will 11 periodically be overwritten by the definitive file. Pull 12 requests which include edits to this file in other repositories 13 will be rejected. 14 --> 15 16 # Docker Remote API v1.21 17 18 ## 1. Brief introduction 19 20 - The Remote API has replaced `rcli`. 21 - The daemon listens on `unix:///var/run/docker.sock` but you can 22 [Bind Docker to another host/port or a Unix socket](../commandline/dockerd.md#bind-docker-to-another-host-port-or-a-unix-socket). 23 - The API tends to be REST. However, for some complex commands, like `attach` 24 or `pull`, the HTTP connection is hijacked to transport `stdout`, 25 `stdin` and `stderr`. 26 - When the client API version is newer than the daemon's, these calls return an HTTP 27 `400 Bad Request` error message. 28 29 # 2. Endpoints 30 31 ## 2.1 Containers 32 33 ### List containers 34 35 `GET /containers/json` 36 37 List containers 38 39 **Example request**: 40 41 GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 42 43 **Example response**: 44 45 HTTP/1.1 200 OK 46 Content-Type: application/json 47 48 [ 49 { 50 "Id": "8dfafdbc3a40", 51 "Names":["/boring_feynman"], 52 "Image": "ubuntu:latest", 53 "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", 54 "Command": "echo 1", 55 "Created": 1367854155, 56 "Status": "Exit 0", 57 "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], 58 "Labels": { 59 "com.example.vendor": "Acme", 60 "com.example.license": "GPL", 61 "com.example.version": "1.0" 62 }, 63 "SizeRw": 12288, 64 "SizeRootFs": 0 65 }, 66 { 67 "Id": "9cd87474be90", 68 "Names":["/coolName"], 69 "Image": "ubuntu:latest", 70 "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", 71 "Command": "echo 222222", 72 "Created": 1367854155, 73 "Status": "Exit 0", 74 "Ports": [], 75 "Labels": {}, 76 "SizeRw": 12288, 77 "SizeRootFs": 0 78 }, 79 { 80 "Id": "3176a2479c92", 81 "Names":["/sleepy_dog"], 82 "Image": "ubuntu:latest", 83 "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", 84 "Command": "echo 3333333333333333", 85 "Created": 1367854154, 86 "Status": "Exit 0", 87 "Ports":[], 88 "Labels": {}, 89 "SizeRw":12288, 90 "SizeRootFs":0 91 }, 92 { 93 "Id": "4cb07b47f9fb", 94 "Names":["/running_cat"], 95 "Image": "ubuntu:latest", 96 "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", 97 "Command": "echo 444444444444444444444444444444444", 98 "Created": 1367854152, 99 "Status": "Exit 0", 100 "Ports": [], 101 "Labels": {}, 102 "SizeRw": 12288, 103 "SizeRootFs": 0 104 } 105 ] 106 107 **Query parameters**: 108 109 - **all** – 1/True/true or 0/False/false, Show all containers. 110 Only running containers are shown by default (i.e., this defaults to false) 111 - **limit** – Show `limit` last created 112 containers, include non-running ones. 113 - **since** – Show only containers created since Id, include 114 non-running ones. 115 - **before** – Show only containers created before Id, include 116 non-running ones. 117 - **size** – 1/True/true or 0/False/false, Show the containers 118 sizes 119 - **filters** - a JSON encoded value of the filters (a `map[string][]string`) to process on the containers list. Available filters: 120 - `exited=<int>`; -- containers with exit code of `<int>` ; 121 - `status=`(`created`|`restarting`|`running`|`paused`|`exited`) 122 - `label=key` or `label="key=value"` of a container label 123 124 **Status codes**: 125 126 - **200** – no error 127 - **400** – bad parameter 128 - **500** – server error 129 130 ### Create a container 131 132 `POST /containers/create` 133 134 Create a container 135 136 **Example request**: 137 138 POST /containers/create HTTP/1.1 139 Content-Type: application/json 140 141 { 142 "Hostname": "", 143 "Domainname": "", 144 "User": "", 145 "AttachStdin": false, 146 "AttachStdout": true, 147 "AttachStderr": true, 148 "Tty": false, 149 "OpenStdin": false, 150 "StdinOnce": false, 151 "Env": [ 152 "FOO=bar", 153 "BAZ=quux" 154 ], 155 "Cmd": [ 156 "date" 157 ], 158 "Entrypoint": null, 159 "Image": "ubuntu", 160 "Labels": { 161 "com.example.vendor": "Acme", 162 "com.example.license": "GPL", 163 "com.example.version": "1.0" 164 }, 165 "Volumes": { 166 "/volumes/data": {} 167 }, 168 "WorkingDir": "", 169 "NetworkDisabled": false, 170 "MacAddress": "12:34:56:78:9a:bc", 171 "ExposedPorts": { 172 "22/tcp": {} 173 }, 174 "StopSignal": "SIGTERM", 175 "HostConfig": { 176 "Binds": ["/tmp:/tmp"], 177 "Links": ["redis3:redis"], 178 "LxcConf": {"lxc.utsname":"docker"}, 179 "Memory": 0, 180 "MemorySwap": 0, 181 "MemoryReservation": 0, 182 "KernelMemory": 0, 183 "CpuShares": 512, 184 "CpuPeriod": 100000, 185 "CpuQuota": 50000, 186 "CpusetCpus": "0,1", 187 "CpusetMems": "0,1", 188 "BlkioWeight": 300, 189 "MemorySwappiness": 60, 190 "OomKillDisable": false, 191 "PidMode": "", 192 "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] }, 193 "PublishAllPorts": false, 194 "Privileged": false, 195 "ReadonlyRootfs": false, 196 "Dns": ["8.8.8.8"], 197 "DnsOptions": [""], 198 "DnsSearch": [""], 199 "ExtraHosts": null, 200 "VolumesFrom": ["parent", "other:ro"], 201 "CapAdd": ["NET_ADMIN"], 202 "CapDrop": ["MKNOD"], 203 "GroupAdd": ["newgroup"], 204 "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 }, 205 "NetworkMode": "bridge", 206 "Devices": [], 207 "Ulimits": [{}], 208 "LogConfig": { "Type": "json-file", "Config": {} }, 209 "SecurityOpt": [], 210 "CgroupParent": "", 211 "VolumeDriver": "" 212 } 213 } 214 215 **Example response**: 216 217 HTTP/1.1 201 Created 218 Content-Type: application/json 219 220 { 221 "Id":"e90e34656806", 222 "Warnings":[] 223 } 224 225 **JSON parameters**: 226 227 - **Hostname** - A string value containing the hostname to use for the 228 container. 229 - **Domainname** - A string value containing the domain name to use 230 for the container. 231 - **User** - A string value specifying the user inside the container. 232 - **AttachStdin** - Boolean value, attaches to `stdin`. 233 - **AttachStdout** - Boolean value, attaches to `stdout`. 234 - **AttachStderr** - Boolean value, attaches to `stderr`. 235 - **Tty** - Boolean value, Attach standard streams to a `tty`, including `stdin` if it is not closed. 236 - **OpenStdin** - Boolean value, opens `stdin`, 237 - **StdinOnce** - Boolean value, close `stdin` after the 1 attached client disconnects. 238 - **Env** - A list of environment variables in the form of `["VAR=value", ...]` 239 - **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value", ... }` 240 - **Cmd** - Command to run specified as a string or an array of strings. 241 - **Entrypoint** - Set the entry point for the container as a string or an array 242 of strings. 243 - **Image** - A string specifying the image name to use for the container. 244 - **Volumes** - An object mapping mount point paths (strings) inside the 245 container to empty objects. 246 - **WorkingDir** - A string specifying the working directory for commands to 247 run in. 248 - **NetworkDisabled** - Boolean value, when true disables networking for the 249 container 250 - **ExposedPorts** - An object mapping ports to an empty object in the form of: 251 `"ExposedPorts": { "<port>/<tcp|udp>: {}" }` 252 - **StopSignal** - Signal to stop a container as a string or unsigned integer. `SIGTERM` by default. 253 - **HostConfig** 254 - **Binds** – A list of volume bindings for this container. Each volume binding is a string in one of these forms: 255 + `host-src:container-dest` to bind-mount a host path into the 256 container. Both `host-src`, and `container-dest` must be an 257 _absolute_ path. 258 + `host-src:container-dest:ro` to make the bind-mount read-only 259 inside the container. Both `host-src`, and `container-dest` must be 260 an _absolute_ path. 261 + `volume-name:container-dest` to bind-mount a volume managed by a 262 volume driver into the container. `container-dest` must be an 263 _absolute_ path. 264 + `volume-name:container-dest:ro` to mount the volume read-only 265 inside the container. `container-dest` must be an _absolute_ path. 266 - **Links** - A list of links for the container. Each link entry should be 267 in the form of `container_name:alias`. 268 - **LxcConf** - LXC specific configurations. These configurations only 269 work when using the `lxc` execution driver. 270 - **Memory** - Memory limit in bytes. 271 - **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap. 272 You must use this with `memory` and make the swap value larger than `memory`. 273 - **MemoryReservation** - Memory soft limit in bytes. 274 - **KernelMemory** - Kernel memory limit in bytes. 275 - **CpuShares** - An integer value containing the container's CPU Shares 276 (ie. the relative weight vs other containers). 277 - **CpuPeriod** - The length of a CPU period in microseconds. 278 - **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period. 279 - **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use. 280 - **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. 281 - **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000. 282 - **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. 283 - **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. 284 - **PidMode** - Set the PID (Process) Namespace mode for the container; 285 `"container:<name|id>"`: joins another container's PID namespace 286 `"host"`: use the host's PID namespace inside the container 287 - **PortBindings** - A map of exposed container ports and the host port they 288 should map to. A JSON object in the form 289 `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }` 290 Take note that `port` is specified as a string and not an integer value. 291 - **PublishAllPorts** - Allocates a random host port for all of a container's 292 exposed ports. Specified as a boolean value. 293 - **Privileged** - Gives the container full access to the host. Specified as 294 a boolean value. 295 - **ReadonlyRootfs** - Mount the container's root filesystem as read only. 296 Specified as a boolean value. 297 - **Dns** - A list of DNS servers for the container to use. 298 - **DnsOptions** - A list of DNS options 299 - **DnsSearch** - A list of DNS search domains 300 - **ExtraHosts** - A list of hostnames/IP mappings to add to the 301 container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`. 302 - **VolumesFrom** - A list of volumes to inherit from another container. 303 Specified in the form `<container name>[:<ro|rw>]` 304 - **CapAdd** - A list of kernel capabilities to add to the container. 305 - **Capdrop** - A list of kernel capabilities to drop from the container. 306 - **GroupAdd** - A list of additional groups that the container process will run as 307 - **RestartPolicy** – The behavior to apply when the container exits. The 308 value is an object with a `Name` property of either `"always"` to 309 always restart, `"unless-stopped"` to restart always except when 310 user has manually stopped the container or `"on-failure"` to restart only when the container 311 exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` 312 controls the number of times to retry before giving up. 313 The default is not to restart. (optional) 314 An ever increasing delay (double the previous delay, starting at 100mS) 315 is added before each restart to prevent flooding the server. 316 - **NetworkMode** - Sets the networking mode for the container. Supported 317 standard values are: `bridge`, `host`, `none`, and `container:<name|id>`. Any other value is taken 318 as a custom network's name to which this container should connect to. 319 - **Devices** - A list of devices to add to the container specified as a JSON object in the 320 form 321 `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}` 322 - **Ulimits** - A list of ulimits to set in the container, specified as 323 `{ "Name": <name>, "Soft": <soft limit>, "Hard": <hard limit> }`, for example: 324 `Ulimits: { "Name": "nofile", "Soft": 1024, "Hard": 2048 }` 325 - **SecurityOpt**: A list of string values to customize labels for MLS 326 systems, such as SELinux. 327 - **LogConfig** - Log configuration for the container, specified as a JSON object in the form 328 `{ "Type": "<driver_name>", "Config": {"key1": "val1"}}`. 329 Available types: `json-file`, `syslog`, `journald`, `gelf`, `awslogs`, `none`. 330 `json-file` logging driver. 331 - **CgroupParent** - Path to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist. 332 - **VolumeDriver** - Driver that this container users to mount volumes. 333 334 **Query parameters**: 335 336 - **name** – Assign the specified name to the container. Must 337 match `/?[a-zA-Z0-9_-]+`. 338 339 **Status codes**: 340 341 - **201** – no error 342 - **400** – bad parameter 343 - **404** – no such container 344 - **406** – impossible to attach (container not running) 345 - **409** – conflict 346 - **500** – server error 347 348 ### Inspect a container 349 350 `GET /containers/(id or name)/json` 351 352 Return low-level information on the container `id` 353 354 **Example request**: 355 356 GET /containers/4fa6e0f0c678/json HTTP/1.1 357 358 **Example response**: 359 360 HTTP/1.1 200 OK 361 Content-Type: application/json 362 363 { 364 "AppArmorProfile": "", 365 "Args": [ 366 "-c", 367 "exit 9" 368 ], 369 "Config": { 370 "AttachStderr": true, 371 "AttachStdin": false, 372 "AttachStdout": true, 373 "Cmd": [ 374 "/bin/sh", 375 "-c", 376 "exit 9" 377 ], 378 "Domainname": "", 379 "Entrypoint": null, 380 "Env": [ 381 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 382 ], 383 "ExposedPorts": null, 384 "Hostname": "ba033ac44011", 385 "Image": "ubuntu", 386 "Labels": { 387 "com.example.vendor": "Acme", 388 "com.example.license": "GPL", 389 "com.example.version": "1.0" 390 }, 391 "MacAddress": "", 392 "NetworkDisabled": false, 393 "OnBuild": null, 394 "OpenStdin": false, 395 "StdinOnce": false, 396 "Tty": false, 397 "User": "", 398 "Volumes": null, 399 "WorkingDir": "", 400 "StopSignal": "SIGTERM" 401 }, 402 "Created": "2015-01-06T15:47:31.485331387Z", 403 "Driver": "devicemapper", 404 "ExecDriver": "native-0.2", 405 "ExecIDs": null, 406 "HostConfig": { 407 "Binds": null, 408 "BlkioWeight": 0, 409 "CapAdd": null, 410 "CapDrop": null, 411 "ContainerIDFile": "", 412 "CpusetCpus": "", 413 "CpusetMems": "", 414 "CpuShares": 0, 415 "CpuPeriod": 100000, 416 "Devices": [], 417 "Dns": null, 418 "DnsOptions": null, 419 "DnsSearch": null, 420 "ExtraHosts": null, 421 "IpcMode": "", 422 "Links": null, 423 "LxcConf": [], 424 "Memory": 0, 425 "MemorySwap": 0, 426 "MemoryReservation": 0, 427 "KernelMemory": 0, 428 "OomKillDisable": false, 429 "NetworkMode": "bridge", 430 "PidMode": "", 431 "PortBindings": {}, 432 "Privileged": false, 433 "ReadonlyRootfs": false, 434 "PublishAllPorts": false, 435 "RestartPolicy": { 436 "MaximumRetryCount": 2, 437 "Name": "on-failure" 438 }, 439 "LogConfig": { 440 "Config": null, 441 "Type": "json-file" 442 }, 443 "SecurityOpt": null, 444 "VolumesFrom": null, 445 "Ulimits": [{}], 446 "VolumeDriver": "" 447 }, 448 "HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname", 449 "HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts", 450 "LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log", 451 "Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39", 452 "Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2", 453 "MountLabel": "", 454 "Name": "/boring_euclid", 455 "NetworkSettings": { 456 "Bridge": "", 457 "SandboxID": "", 458 "HairpinMode": false, 459 "LinkLocalIPv6Address": "", 460 "LinkLocalIPv6PrefixLen": 0, 461 "Ports": null, 462 "SandboxKey": "", 463 "SecondaryIPAddresses": null, 464 "SecondaryIPv6Addresses": null, 465 "EndpointID": "", 466 "Gateway": "", 467 "GlobalIPv6Address": "", 468 "GlobalIPv6PrefixLen": 0, 469 "IPAddress": "", 470 "IPPrefixLen": 0, 471 "IPv6Gateway": "", 472 "MacAddress": "", 473 "Networks": { 474 "bridge": { 475 "EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d", 476 "Gateway": "172.17.0.1", 477 "IPAddress": "172.17.0.2", 478 "IPPrefixLen": 16, 479 "IPv6Gateway": "", 480 "GlobalIPv6Address": "", 481 "GlobalIPv6PrefixLen": 0, 482 "MacAddress": "02:42:ac:12:00:02" 483 } 484 } 485 }, 486 "Path": "/bin/sh", 487 "ProcessLabel": "", 488 "ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf", 489 "RestartCount": 1, 490 "State": { 491 "Error": "", 492 "ExitCode": 9, 493 "FinishedAt": "2015-01-06T15:47:32.080254511Z", 494 "OOMKilled": false, 495 "Paused": false, 496 "Pid": 0, 497 "Restarting": false, 498 "Running": true, 499 "StartedAt": "2015-01-06T15:47:32.072697474Z", 500 "Status": "running" 501 }, 502 "Mounts": [ 503 { 504 "Source": "/data", 505 "Destination": "/data", 506 "Mode": "ro,Z", 507 "RW": false 508 } 509 ] 510 } 511 512 **Example request, with size information**: 513 514 GET /containers/4fa6e0f0c678/json?size=1 HTTP/1.1 515 516 **Example response, with size information**: 517 518 HTTP/1.1 200 OK 519 Content-Type: application/json 520 521 { 522 .... 523 "SizeRw": 0, 524 "SizeRootFs": 972, 525 .... 526 } 527 528 **Query parameters**: 529 530 - **size** – 1/True/true or 0/False/false, return container size information. Default is `false`. 531 532 **Status codes**: 533 534 - **200** – no error 535 - **404** – no such container 536 - **500** – server error 537 538 ### List processes running inside a container 539 540 `GET /containers/(id or name)/top` 541 542 List processes running inside the container `id`. On Unix systems this 543 is done by running the `ps` command. This endpoint is not 544 supported on Windows. 545 546 **Example request**: 547 548 GET /containers/4fa6e0f0c678/top HTTP/1.1 549 550 **Example response**: 551 552 HTTP/1.1 200 OK 553 Content-Type: application/json 554 555 { 556 "Titles" : [ 557 "UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD" 558 ], 559 "Processes" : [ 560 [ 561 "root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash" 562 ], 563 [ 564 "root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10" 565 ] 566 ] 567 } 568 569 **Example request**: 570 571 GET /containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1 572 573 **Example response**: 574 575 HTTP/1.1 200 OK 576 Content-Type: application/json 577 578 { 579 "Titles" : [ 580 "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND" 581 ] 582 "Processes" : [ 583 [ 584 "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash" 585 ], 586 [ 587 "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10" 588 ] 589 ], 590 } 591 592 **Query parameters**: 593 594 - **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef` 595 596 **Status codes**: 597 598 - **200** – no error 599 - **404** – no such container 600 - **500** – server error 601 602 ### Get container logs 603 604 `GET /containers/(id or name)/logs` 605 606 Get `stdout` and `stderr` logs from the container ``id`` 607 608 > **Note**: 609 > This endpoint works only for containers with the `json-file` or `journald` logging drivers. 610 611 **Example request**: 612 613 GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10&since=1428990821 HTTP/1.1 614 615 **Example response**: 616 617 HTTP/1.1 101 UPGRADED 618 Content-Type: application/vnd.docker.raw-stream 619 Connection: Upgrade 620 Upgrade: tcp 621 622 {% raw %} 623 {{ STREAM }} 624 {% endraw %} 625 626 **Query parameters**: 627 628 - **follow** – 1/True/true or 0/False/false, return stream. Default `false`. 629 - **stdout** – 1/True/true or 0/False/false, show `stdout` log. Default `false`. 630 - **stderr** – 1/True/true or 0/False/false, show `stderr` log. Default `false`. 631 - **since** – UNIX timestamp (integer) to filter logs. Specifying a timestamp 632 will only output log-entries since that timestamp. Default: 0 (unfiltered) 633 - **timestamps** – 1/True/true or 0/False/false, print timestamps for 634 every log line. Default `false`. 635 - **tail** – Output specified number of lines at the end of logs: `all` or `<number>`. Default all. 636 637 **Status codes**: 638 639 - **101** – no error, hints proxy about hijacking 640 - **200** – no error, no upgrade header found 641 - **404** – no such container 642 - **500** – server error 643 644 ### Inspect changes on a container's filesystem 645 646 `GET /containers/(id or name)/changes` 647 648 Inspect changes on container `id`'s filesystem 649 650 **Example request**: 651 652 GET /containers/4fa6e0f0c678/changes HTTP/1.1 653 654 **Example response**: 655 656 HTTP/1.1 200 OK 657 Content-Type: application/json 658 659 [ 660 { 661 "Path": "/dev", 662 "Kind": 0 663 }, 664 { 665 "Path": "/dev/kmsg", 666 "Kind": 1 667 }, 668 { 669 "Path": "/test", 670 "Kind": 1 671 } 672 ] 673 674 Values for `Kind`: 675 676 - `0`: Modify 677 - `1`: Add 678 - `2`: Delete 679 680 **Status codes**: 681 682 - **200** – no error 683 - **404** – no such container 684 - **500** – server error 685 686 ### Export a container 687 688 `GET /containers/(id or name)/export` 689 690 Export the contents of container `id` 691 692 **Example request**: 693 694 GET /containers/4fa6e0f0c678/export HTTP/1.1 695 696 **Example response**: 697 698 HTTP/1.1 200 OK 699 Content-Type: application/octet-stream 700 701 {% raw %} 702 {{ TAR STREAM }} 703 {% endraw %} 704 705 **Status codes**: 706 707 - **200** – no error 708 - **404** – no such container 709 - **500** – server error 710 711 ### Get container stats based on resource usage 712 713 `GET /containers/(id or name)/stats` 714 715 This endpoint returns a live stream of a container's resource usage statistics. 716 717 **Example request**: 718 719 GET /containers/redis1/stats HTTP/1.1 720 721 **Example response**: 722 723 HTTP/1.1 200 OK 724 Content-Type: application/json 725 726 { 727 "read" : "2015-01-08T22:57:31.547920715Z", 728 "networks": { 729 "eth0": { 730 "rx_bytes": 5338, 731 "rx_dropped": 0, 732 "rx_errors": 0, 733 "rx_packets": 36, 734 "tx_bytes": 648, 735 "tx_dropped": 0, 736 "tx_errors": 0, 737 "tx_packets": 8 738 }, 739 "eth5": { 740 "rx_bytes": 4641, 741 "rx_dropped": 0, 742 "rx_errors": 0, 743 "rx_packets": 26, 744 "tx_bytes": 690, 745 "tx_dropped": 0, 746 "tx_errors": 0, 747 "tx_packets": 9 748 } 749 }, 750 "memory_stats" : { 751 "stats" : { 752 "total_pgmajfault" : 0, 753 "cache" : 0, 754 "mapped_file" : 0, 755 "total_inactive_file" : 0, 756 "pgpgout" : 414, 757 "rss" : 6537216, 758 "total_mapped_file" : 0, 759 "writeback" : 0, 760 "unevictable" : 0, 761 "pgpgin" : 477, 762 "total_unevictable" : 0, 763 "pgmajfault" : 0, 764 "total_rss" : 6537216, 765 "total_rss_huge" : 6291456, 766 "total_writeback" : 0, 767 "total_inactive_anon" : 0, 768 "rss_huge" : 6291456, 769 "hierarchical_memory_limit" : 67108864, 770 "total_pgfault" : 964, 771 "total_active_file" : 0, 772 "active_anon" : 6537216, 773 "total_active_anon" : 6537216, 774 "total_pgpgout" : 414, 775 "total_cache" : 0, 776 "inactive_anon" : 0, 777 "active_file" : 0, 778 "pgfault" : 964, 779 "inactive_file" : 0, 780 "total_pgpgin" : 477 781 }, 782 "max_usage" : 6651904, 783 "usage" : 6537216, 784 "failcnt" : 0, 785 "limit" : 67108864 786 }, 787 "blkio_stats" : {}, 788 "cpu_stats" : { 789 "cpu_usage" : { 790 "percpu_usage" : [ 791 8646879, 792 24472255, 793 36438778, 794 30657443 795 ], 796 "usage_in_usermode" : 50000000, 797 "total_usage" : 100215355, 798 "usage_in_kernelmode" : 30000000 799 }, 800 "system_cpu_usage" : 739306590000000, 801 "throttling_data" : {"periods":0,"throttled_periods":0,"throttled_time":0} 802 }, 803 "precpu_stats" : { 804 "cpu_usage" : { 805 "percpu_usage" : [ 806 8646879, 807 24350896, 808 36438778, 809 30657443 810 ], 811 "usage_in_usermode" : 50000000, 812 "total_usage" : 100093996, 813 "usage_in_kernelmode" : 30000000 814 }, 815 "system_cpu_usage" : 9492140000000, 816 "throttling_data" : {"periods":0,"throttled_periods":0,"throttled_time":0} 817 } 818 } 819 820 The precpu_stats is the cpu statistic of last read, which is used for calculating the cpu usage percent. It is not the exact copy of the “cpu_stats” field. 821 822 **Query parameters**: 823 824 - **stream** – 1/True/true or 0/False/false, pull stats once then disconnect. Default `true`. 825 826 **Status codes**: 827 828 - **200** – no error 829 - **404** – no such container 830 - **500** – server error 831 832 ### Resize a container TTY 833 834 `POST /containers/(id or name)/resize` 835 836 Resize the TTY for container with `id`. The unit is number of characters. You must restart the container for the resize to take effect. 837 838 **Example request**: 839 840 POST /containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1 841 842 **Example response**: 843 844 HTTP/1.1 200 OK 845 Content-Length: 0 846 Content-Type: text/plain; charset=utf-8 847 848 **Query parameters**: 849 850 - **h** – height of `tty` session 851 - **w** – width 852 853 **Status codes**: 854 855 - **200** – no error 856 - **404** – No such container 857 - **500** – Cannot resize container 858 859 ### Start a container 860 861 `POST /containers/(id or name)/start` 862 863 Start the container `id` 864 865 > **Note**: 866 > For backwards compatibility, this endpoint accepts a `HostConfig` as JSON-encoded request body. 867 > See [create a container](#create-a-container) for details. 868 869 **Example request**: 870 871 POST /containers/e90e34656806/start HTTP/1.1 872 873 **Example response**: 874 875 HTTP/1.1 204 No Content 876 877 **Status codes**: 878 879 - **204** – no error 880 - **304** – container already started 881 - **404** – no such container 882 - **500** – server error 883 884 ### Stop a container 885 886 `POST /containers/(id or name)/stop` 887 888 Stop the container `id` 889 890 **Example request**: 891 892 POST /containers/e90e34656806/stop?t=5 HTTP/1.1 893 894 **Example response**: 895 896 HTTP/1.1 204 No Content 897 898 **Query parameters**: 899 900 - **t** – number of seconds to wait before killing the container 901 902 **Status codes**: 903 904 - **204** – no error 905 - **304** – container already stopped 906 - **404** – no such container 907 - **500** – server error 908 909 ### Restart a container 910 911 `POST /containers/(id or name)/restart` 912 913 Restart the container `id` 914 915 **Example request**: 916 917 POST /containers/e90e34656806/restart?t=5 HTTP/1.1 918 919 **Example response**: 920 921 HTTP/1.1 204 No Content 922 923 **Query parameters**: 924 925 - **t** – number of seconds to wait before killing the container 926 927 **Status codes**: 928 929 - **204** – no error 930 - **404** – no such container 931 - **500** – server error 932 933 ### Kill a container 934 935 `POST /containers/(id or name)/kill` 936 937 Kill the container `id` 938 939 **Example request**: 940 941 POST /containers/e90e34656806/kill HTTP/1.1 942 943 **Example response**: 944 945 HTTP/1.1 204 No Content 946 947 **Query parameters**: 948 949 - **signal** - Signal to send to the container: integer or string like `SIGINT`. 950 When not set, `SIGKILL` is assumed and the call waits for the container to exit. 951 952 **Status codes**: 953 954 - **204** – no error 955 - **404** – no such container 956 - **500** – server error 957 958 ### Rename a container 959 960 `POST /containers/(id or name)/rename` 961 962 Rename the container `id` to a `new_name` 963 964 **Example request**: 965 966 POST /containers/e90e34656806/rename?name=new_name HTTP/1.1 967 968 **Example response**: 969 970 HTTP/1.1 204 No Content 971 972 **Query parameters**: 973 974 - **name** – new name for the container 975 976 **Status codes**: 977 978 - **204** – no error 979 - **404** – no such container 980 - **409** - conflict name already assigned 981 - **500** – server error 982 983 ### Pause a container 984 985 `POST /containers/(id or name)/pause` 986 987 Pause the container `id` 988 989 **Example request**: 990 991 POST /containers/e90e34656806/pause HTTP/1.1 992 993 **Example response**: 994 995 HTTP/1.1 204 No Content 996 997 **Status codes**: 998 999 - **204** – no error 1000 - **404** – no such container 1001 - **500** – server error 1002 1003 ### Unpause a container 1004 1005 `POST /containers/(id or name)/unpause` 1006 1007 Unpause the container `id` 1008 1009 **Example request**: 1010 1011 POST /containers/e90e34656806/unpause HTTP/1.1 1012 1013 **Example response**: 1014 1015 HTTP/1.1 204 No Content 1016 1017 **Status codes**: 1018 1019 - **204** – no error 1020 - **404** – no such container 1021 - **500** – server error 1022 1023 ### Attach to a container 1024 1025 `POST /containers/(id or name)/attach` 1026 1027 Attach to the container `id` 1028 1029 **Example request**: 1030 1031 POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 1032 1033 **Example response**: 1034 1035 HTTP/1.1 101 UPGRADED 1036 Content-Type: application/vnd.docker.raw-stream 1037 Connection: Upgrade 1038 Upgrade: tcp 1039 1040 {% raw %} 1041 {{ STREAM }} 1042 {% endraw %} 1043 1044 **Query parameters**: 1045 1046 - **logs** – 1/True/true or 0/False/false, return logs. Default `false`. 1047 - **stream** – 1/True/true or 0/False/false, return stream. 1048 Default `false`. 1049 - **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach 1050 to `stdin`. Default `false`. 1051 - **stdout** – 1/True/true or 0/False/false, if `logs=true`, return 1052 `stdout` log, if `stream=true`, attach to `stdout`. Default `false`. 1053 - **stderr** – 1/True/true or 0/False/false, if `logs=true`, return 1054 `stderr` log, if `stream=true`, attach to `stderr`. Default `false`. 1055 1056 **Status codes**: 1057 1058 - **101** – no error, hints proxy about hijacking 1059 - **200** – no error, no upgrade header found 1060 - **400** – bad parameter 1061 - **404** – no such container 1062 - **500** – server error 1063 1064 **Stream details**: 1065 1066 When using the TTY setting is enabled in 1067 [`POST /containers/create` 1068 ](#create-a-container), 1069 the stream is the raw data from the process PTY and client's `stdin`. 1070 When the TTY is disabled, then the stream is multiplexed to separate 1071 `stdout` and `stderr`. 1072 1073 The format is a **Header** and a **Payload** (frame). 1074 1075 **HEADER** 1076 1077 The header contains the information which the stream writes (`stdout` or 1078 `stderr`). It also contains the size of the associated frame encoded in the 1079 last four bytes (`uint32`). 1080 1081 It is encoded on the first eight bytes like this: 1082 1083 header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} 1084 1085 `STREAM_TYPE` can be: 1086 1087 - 0: `stdin` (is written on `stdout`) 1088 - 1: `stdout` 1089 - 2: `stderr` 1090 1091 `SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of 1092 the `uint32` size encoded as big endian. 1093 1094 **PAYLOAD** 1095 1096 The payload is the raw stream. 1097 1098 **IMPLEMENTATION** 1099 1100 The simplest way to implement the Attach protocol is the following: 1101 1102 1. Read eight bytes. 1103 2. Choose `stdout` or `stderr` depending on the first byte. 1104 3. Extract the frame size from the last four bytes. 1105 4. Read the extracted size and output it on the correct output. 1106 5. Goto 1. 1107 1108 ### Attach to a container (websocket) 1109 1110 `GET /containers/(id or name)/attach/ws` 1111 1112 Attach to the container `id` via websocket 1113 1114 Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) 1115 1116 **Example request** 1117 1118 GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 1119 1120 **Example response** 1121 1122 {% raw %} 1123 {{ STREAM }} 1124 {% endraw %} 1125 1126 **Query parameters**: 1127 1128 - **logs** – 1/True/true or 0/False/false, return logs. Default `false`. 1129 - **stream** – 1/True/true or 0/False/false, return stream. 1130 Default `false`. 1131 - **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach 1132 to `stdin`. Default `false`. 1133 - **stdout** – 1/True/true or 0/False/false, if `logs=true`, return 1134 `stdout` log, if `stream=true`, attach to `stdout`. Default `false`. 1135 - **stderr** – 1/True/true or 0/False/false, if `logs=true`, return 1136 `stderr` log, if `stream=true`, attach to `stderr`. Default `false`. 1137 1138 **Status codes**: 1139 1140 - **200** – no error 1141 - **400** – bad parameter 1142 - **404** – no such container 1143 - **500** – server error 1144 1145 ### Wait a container 1146 1147 `POST /containers/(id or name)/wait` 1148 1149 Block until container `id` stops, then returns the exit code 1150 1151 **Example request**: 1152 1153 POST /containers/16253994b7c4/wait HTTP/1.1 1154 1155 **Example response**: 1156 1157 HTTP/1.1 200 OK 1158 Content-Type: application/json 1159 1160 {"StatusCode": 0} 1161 1162 **Status codes**: 1163 1164 - **200** – no error 1165 - **404** – no such container 1166 - **500** – server error 1167 1168 ### Remove a container 1169 1170 `DELETE /containers/(id or name)` 1171 1172 Remove the container `id` from the filesystem 1173 1174 **Example request**: 1175 1176 DELETE /containers/16253994b7c4?v=1 HTTP/1.1 1177 1178 **Example response**: 1179 1180 HTTP/1.1 204 No Content 1181 1182 **Query parameters**: 1183 1184 - **v** – 1/True/true or 0/False/false, Remove the volumes 1185 associated to the container. Default `false`. 1186 - **force** - 1/True/true or 0/False/false, Kill then remove the container. 1187 Default `false`. 1188 1189 **Status codes**: 1190 1191 - **204** – no error 1192 - **400** – bad parameter 1193 - **404** – no such container 1194 - **409** – conflict 1195 - **500** – server error 1196 1197 ### Copy files or folders from a container 1198 1199 `POST /containers/(id or name)/copy` 1200 1201 Copy files or folders of container `id` 1202 1203 **Deprecated** in favor of the `archive` endpoint below. 1204 1205 **Example request**: 1206 1207 POST /containers/4fa6e0f0c678/copy HTTP/1.1 1208 Content-Type: application/json 1209 1210 { 1211 "Resource": "test.txt" 1212 } 1213 1214 **Example response**: 1215 1216 HTTP/1.1 200 OK 1217 Content-Type: application/x-tar 1218 1219 {% raw %} 1220 {{ TAR STREAM }} 1221 {% endraw %} 1222 1223 **Status codes**: 1224 1225 - **200** – no error 1226 - **404** – no such container 1227 - **500** – server error 1228 1229 ### Retrieving information about files and folders in a container 1230 1231 `HEAD /containers/(id or name)/archive` 1232 1233 See the description of the `X-Docker-Container-Path-Stat` header in the 1234 following section. 1235 1236 ### Get an archive of a filesystem resource in a container 1237 1238 `GET /containers/(id or name)/archive` 1239 1240 Get a tar archive of a resource in the filesystem of container `id`. 1241 1242 **Query parameters**: 1243 1244 - **path** - resource in the container's filesystem to archive. Required. 1245 1246 If not an absolute path, it is relative to the container's root directory. 1247 The resource specified by **path** must exist. To assert that the resource 1248 is expected to be a directory, **path** should end in `/` or `/.` 1249 (assuming a path separator of `/`). If **path** ends in `/.` then this 1250 indicates that only the contents of the **path** directory should be 1251 copied. A symlink is always resolved to its target. 1252 1253 > **Note**: It is not possible to copy certain system files such as resources 1254 > under `/proc`, `/sys`, `/dev`, and mounts created by the user in the 1255 > container. 1256 1257 **Example request**: 1258 1259 GET /containers/8cce319429b2/archive?path=/root HTTP/1.1 1260 1261 **Example response**: 1262 1263 HTTP/1.1 200 OK 1264 Content-Type: application/x-tar 1265 X-Docker-Container-Path-Stat: eyJuYW1lIjoicm9vdCIsInNpemUiOjQwOTYsIm1vZGUiOjIxNDc0ODQwOTYsIm10aW1lIjoiMjAxNC0wMi0yN1QyMDo1MToyM1oiLCJsaW5rVGFyZ2V0IjoiIn0= 1266 1267 {% raw %} 1268 {{ TAR STREAM }} 1269 {% endraw %} 1270 1271 On success, a response header `X-Docker-Container-Path-Stat` will be set to a 1272 base64-encoded JSON object containing some filesystem header information about 1273 the archived resource. The above example value would decode to the following 1274 JSON object (whitespace added for readability): 1275 1276 ```json 1277 { 1278 "name": "root", 1279 "size": 4096, 1280 "mode": 2147484096, 1281 "mtime": "2014-02-27T20:51:23Z", 1282 "linkTarget": "" 1283 } 1284 ``` 1285 1286 A `HEAD` request can also be made to this endpoint if only this information is 1287 desired. 1288 1289 **Status codes**: 1290 1291 - **200** - success, returns archive of copied resource 1292 - **400** - client error, bad parameter, details in JSON response body, one of: 1293 - must specify path parameter (**path** cannot be empty) 1294 - not a directory (**path** was asserted to be a directory but exists as a 1295 file) 1296 - **404** - client error, resource not found, one of: 1297 – no such container (container `id` does not exist) 1298 - no such file or directory (**path** does not exist) 1299 - **500** - server error 1300 1301 ### Extract an archive of files or folders to a directory in a container 1302 1303 `PUT /containers/(id or name)/archive` 1304 1305 Upload a tar archive to be extracted to a path in the filesystem of container 1306 `id`. 1307 1308 **Query parameters**: 1309 1310 - **path** - path to a directory in the container 1311 to extract the archive's contents into. Required. 1312 1313 If not an absolute path, it is relative to the container's root directory. 1314 The **path** resource must exist. 1315 - **noOverwriteDirNonDir** - If "1", "true", or "True" then it will be an error 1316 if unpacking the given content would cause an existing directory to be 1317 replaced with a non-directory and vice versa. 1318 1319 **Example request**: 1320 1321 PUT /containers/8cce319429b2/archive?path=/vol1 HTTP/1.1 1322 Content-Type: application/x-tar 1323 1324 {% raw %} 1325 {{ TAR STREAM }} 1326 {% endraw %} 1327 1328 **Example response**: 1329 1330 HTTP/1.1 200 OK 1331 1332 **Status codes**: 1333 1334 - **200** – the content was extracted successfully 1335 - **400** - client error, bad parameter, details in JSON response body, one of: 1336 - must specify path parameter (**path** cannot be empty) 1337 - not a directory (**path** should be a directory but exists as a file) 1338 - unable to overwrite existing directory with non-directory 1339 (if **noOverwriteDirNonDir**) 1340 - unable to overwrite existing non-directory with directory 1341 (if **noOverwriteDirNonDir**) 1342 - **403** - client error, permission denied, the volume 1343 or container rootfs is marked as read-only. 1344 - **404** - client error, resource not found, one of: 1345 – no such container (container `id` does not exist) 1346 - no such file or directory (**path** resource does not exist) 1347 - **500** – server error 1348 1349 ## 2.2 Images 1350 1351 ### List Images 1352 1353 `GET /images/json` 1354 1355 **Example request**: 1356 1357 GET /images/json?all=0 HTTP/1.1 1358 1359 **Example response**: 1360 1361 HTTP/1.1 200 OK 1362 Content-Type: application/json 1363 1364 [ 1365 { 1366 "RepoTags": [ 1367 "ubuntu:12.04", 1368 "ubuntu:precise", 1369 "ubuntu:latest" 1370 ], 1371 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 1372 "Created": 1365714795, 1373 "Size": 131506275, 1374 "VirtualSize": 131506275, 1375 "Labels": {} 1376 }, 1377 { 1378 "RepoTags": [ 1379 "ubuntu:12.10", 1380 "ubuntu:quantal" 1381 ], 1382 "ParentId": "27cf784147099545", 1383 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 1384 "Created": 1364102658, 1385 "Size": 24653, 1386 "VirtualSize": 180116135, 1387 "Labels": { 1388 "com.example.version": "v1" 1389 } 1390 } 1391 ] 1392 1393 **Example request, with digest information**: 1394 1395 GET /images/json?digests=1 HTTP/1.1 1396 1397 **Example response, with digest information**: 1398 1399 HTTP/1.1 200 OK 1400 Content-Type: application/json 1401 1402 [ 1403 { 1404 "Created": 1420064636, 1405 "Id": "4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125", 1406 "ParentId": "ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2", 1407 "RepoDigests": [ 1408 "localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf" 1409 ], 1410 "RepoTags": [ 1411 "localhost:5000/test/busybox:latest", 1412 "playdate:latest" 1413 ], 1414 "Size": 0, 1415 "VirtualSize": 2429728, 1416 "Labels": {} 1417 } 1418 ] 1419 1420 The response shows a single image `Id` associated with two repositories 1421 (`RepoTags`): `localhost:5000/test/busybox`: and `playdate`. A caller can use 1422 either of the `RepoTags` values `localhost:5000/test/busybox:latest` or 1423 `playdate:latest` to reference the image. 1424 1425 You can also use `RepoDigests` values to reference an image. In this response, 1426 the array has only one reference and that is to the 1427 `localhost:5000/test/busybox` repository; the `playdate` repository has no 1428 digest. You can reference this digest using the value: 1429 `localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d...` 1430 1431 See the `docker run` and `docker build` commands for examples of digest and tag 1432 references on the command line. 1433 1434 **Query parameters**: 1435 1436 - **all** – 1/True/true or 0/False/false, default false 1437 - **filters** – a JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters: 1438 - `dangling=true` 1439 - `label=key` or `label="key=value"` of an image label 1440 - **filter** - only return images with the specified name 1441 1442 ### Build image from a Dockerfile 1443 1444 `POST /build` 1445 1446 Build an image from a Dockerfile 1447 1448 **Example request**: 1449 1450 POST /build HTTP/1.1 1451 1452 {% raw %} 1453 {{ TAR STREAM }} 1454 {% endraw %} 1455 1456 **Example response**: 1457 1458 HTTP/1.1 200 OK 1459 Content-Type: application/json 1460 1461 {"stream": "Step 1..."} 1462 {"stream": "..."} 1463 {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} 1464 1465 The input stream must be a `tar` archive compressed with one of the 1466 following algorithms: `identity` (no compression), `gzip`, `bzip2`, `xz`. 1467 1468 The archive must include a build instructions file, typically called 1469 `Dockerfile` at the archive's root. The `dockerfile` parameter may be 1470 used to specify a different build instructions file. To do this, its value must be 1471 the path to the alternate build instructions file to use. 1472 1473 The archive may include any number of other files, 1474 which are accessible in the build context (See the [*ADD build 1475 command*](../../reference/builder.md#add)). 1476 1477 The Docker daemon performs a preliminary validation of the `Dockerfile` before 1478 starting the build, and returns an error if the syntax is incorrect. After that, 1479 each instruction is run one-by-one until the ID of the new image is output. 1480 1481 The build is canceled if the client drops the connection by quitting 1482 or being killed. 1483 1484 **Query parameters**: 1485 1486 - **dockerfile** - Path within the build context to the `Dockerfile`. This is 1487 ignored if `remote` is specified and points to an external `Dockerfile`. 1488 - **t** – A name and optional tag to apply to the image in the `name:tag` format. 1489 If you omit the `tag` the default `latest` value is assumed. 1490 You can provide one or more `t` parameters. 1491 - **remote** – A Git repository URI or HTTP/HTTPS context URI. If the 1492 URI points to a single text file, the file's contents are placed into 1493 a file called `Dockerfile` and the image is built from that file. If 1494 the URI points to a tarball, the file is downloaded by the daemon and 1495 the contents therein used as the context for the build. If the URI 1496 points to a tarball and the `dockerfile` parameter is also specified, 1497 there must be a file with the corresponding path inside the tarball. 1498 - **q** – Suppress verbose build output. 1499 - **nocache** – Do not use the cache when building the image. 1500 - **pull** - Attempt to pull the image even if an older image exists locally. 1501 - **rm** - Remove intermediate containers after a successful build (default behavior). 1502 - **forcerm** - Always remove intermediate containers (includes `rm`). 1503 - **memory** - Set memory limit for build. 1504 - **memswap** - Total memory (memory + swap), `-1` to enable unlimited swap. 1505 - **cpushares** - CPU shares (relative weight). 1506 - **cpusetcpus** - CPUs in which to allow execution (e.g., `0-3`, `0,1`). 1507 - **cpuperiod** - The length of a CPU period in microseconds. 1508 - **cpuquota** - Microseconds of CPU time that the container can get in a CPU period. 1509 - **buildargs** – JSON map of string pairs for build-time variables. Users pass 1510 these values at build-time. Docker uses the `buildargs` as the environment 1511 context for command(s) run via the Dockerfile's `RUN` instruction or for 1512 variable expansion in other Dockerfile instructions. This is not meant for 1513 passing secret values. [Read more about the buildargs instruction](../../reference/builder.md#arg) 1514 1515 **Request Headers**: 1516 1517 - **Content-type** – Set to `"application/tar"`. 1518 - **X-Registry-Config** – A base64-url-safe-encoded Registry Auth Config JSON 1519 object with the following structure: 1520 1521 { 1522 "docker.example.com": { 1523 "username": "janedoe", 1524 "password": "hunter2" 1525 }, 1526 "https://index.docker.io/v1/": { 1527 "username": "mobydock", 1528 "password": "conta1n3rize14" 1529 } 1530 } 1531 1532 This object maps the hostname of a registry to an object containing the 1533 "username" and "password" for that registry. Multiple registries may 1534 be specified as the build may be based on an image requiring 1535 authentication to pull from any arbitrary registry. Only the registry 1536 domain name (and port if not the default "443") are required. However 1537 (for legacy reasons) the "official" Docker, Inc. hosted registry must 1538 be specified with both a "https://" prefix and a "/v1/" suffix even 1539 though Docker will prefer to use the v2 registry API. 1540 1541 **Status codes**: 1542 1543 - **200** – no error 1544 - **500** – server error 1545 1546 ### Create an image 1547 1548 `POST /images/create` 1549 1550 Create an image either by pulling it from the registry or by importing it 1551 1552 **Example request**: 1553 1554 POST /images/create?fromImage=busybox&tag=latest HTTP/1.1 1555 1556 **Example response**: 1557 1558 HTTP/1.1 200 OK 1559 Content-Type: application/json 1560 1561 {"status": "Pulling..."} 1562 {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} 1563 {"error": "Invalid..."} 1564 ... 1565 1566 When using this endpoint to pull an image from the registry, the 1567 `X-Registry-Auth` header can be used to include 1568 a base64-encoded AuthConfig object. 1569 1570 **Query parameters**: 1571 1572 - **fromImage** – Name of the image to pull. The name may include a tag or 1573 digest. This parameter may only be used when pulling an image. 1574 - **fromSrc** – Source to import. The value may be a URL from which the image 1575 can be retrieved or `-` to read the image from the request body. 1576 This parameter may only be used when importing an image. 1577 - **repo** – Repository name given to an image when it is imported. 1578 The repo may include a tag. This parameter may only be used when importing 1579 an image. 1580 - **tag** – Tag or digest. If empty when pulling an image, this causes all tags 1581 for the given image to be pulled. 1582 1583 **Request Headers**: 1584 1585 - **X-Registry-Auth** – base64-encoded AuthConfig object 1586 1587 **Status codes**: 1588 1589 - **200** – no error 1590 - **500** – server error 1591 1592 1593 1594 ### Inspect an image 1595 1596 `GET /images/(name)/json` 1597 1598 Return low-level information on the image `name` 1599 1600 **Example request**: 1601 1602 GET /images/example/json HTTP/1.1 1603 1604 **Example response**: 1605 1606 HTTP/1.1 200 OK 1607 Content-Type: application/json 1608 1609 { 1610 "Id" : "85f05633ddc1c50679be2b16a0479ab6f7637f8884e0cfe0f4d20e1ebb3d6e7c", 1611 "Container" : "cb91e48a60d01f1e27028b4fc6819f4f290b3cf12496c8176ec714d0d390984a", 1612 "Comment" : "", 1613 "Os" : "linux", 1614 "Architecture" : "amd64", 1615 "Parent" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1616 "ContainerConfig" : { 1617 "Tty" : false, 1618 "Hostname" : "e611e15f9c9d", 1619 "Volumes" : null, 1620 "Domainname" : "", 1621 "AttachStdout" : false, 1622 "PublishService" : "", 1623 "AttachStdin" : false, 1624 "OpenStdin" : false, 1625 "StdinOnce" : false, 1626 "NetworkDisabled" : false, 1627 "OnBuild" : [], 1628 "Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1629 "User" : "", 1630 "WorkingDir" : "", 1631 "Entrypoint" : null, 1632 "MacAddress" : "", 1633 "AttachStderr" : false, 1634 "Labels" : { 1635 "com.example.license" : "GPL", 1636 "com.example.version" : "1.0", 1637 "com.example.vendor" : "Acme" 1638 }, 1639 "Env" : [ 1640 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 1641 ], 1642 "ExposedPorts" : null, 1643 "Cmd" : [ 1644 "/bin/sh", 1645 "-c", 1646 "#(nop) LABEL com.example.vendor=Acme com.example.license=GPL com.example.version=1.0" 1647 ] 1648 }, 1649 "DockerVersion" : "1.9.0-dev", 1650 "VirtualSize" : 188359297, 1651 "Size" : 0, 1652 "Author" : "", 1653 "Created" : "2015-09-10T08:30:53.26995814Z", 1654 "GraphDriver" : { 1655 "Name" : "aufs", 1656 "Data" : null 1657 }, 1658 "RepoDigests" : [ 1659 "localhost:5000/test/busybox/example@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf" 1660 ], 1661 "RepoTags" : [ 1662 "example:1.0", 1663 "example:latest", 1664 "example:stable" 1665 ], 1666 "Config" : { 1667 "Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1668 "NetworkDisabled" : false, 1669 "OnBuild" : [], 1670 "StdinOnce" : false, 1671 "PublishService" : "", 1672 "AttachStdin" : false, 1673 "OpenStdin" : false, 1674 "Domainname" : "", 1675 "AttachStdout" : false, 1676 "Tty" : false, 1677 "Hostname" : "e611e15f9c9d", 1678 "Volumes" : null, 1679 "Cmd" : [ 1680 "/bin/bash" 1681 ], 1682 "ExposedPorts" : null, 1683 "Env" : [ 1684 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 1685 ], 1686 "Labels" : { 1687 "com.example.vendor" : "Acme", 1688 "com.example.version" : "1.0", 1689 "com.example.license" : "GPL" 1690 }, 1691 "Entrypoint" : null, 1692 "MacAddress" : "", 1693 "AttachStderr" : false, 1694 "WorkingDir" : "", 1695 "User" : "" 1696 } 1697 } 1698 1699 **Status codes**: 1700 1701 - **200** – no error 1702 - **404** – no such image 1703 - **500** – server error 1704 1705 ### Get the history of an image 1706 1707 `GET /images/(name)/history` 1708 1709 Return the history of the image `name` 1710 1711 **Example request**: 1712 1713 GET /images/ubuntu/history HTTP/1.1 1714 1715 **Example response**: 1716 1717 HTTP/1.1 200 OK 1718 Content-Type: application/json 1719 1720 [ 1721 { 1722 "Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710", 1723 "Created": 1398108230, 1724 "CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /", 1725 "Tags": [ 1726 "ubuntu:lucid", 1727 "ubuntu:10.04" 1728 ], 1729 "Size": 182964289, 1730 "Comment": "" 1731 }, 1732 { 1733 "Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8", 1734 "Created": 1398108222, 1735 "CreatedBy": "/bin/sh -c #(nop) MAINTAINER Tianon Gravi <admwiggin@gmail.com> - mkimage-debootstrap.sh -i iproute,iputils-ping,ubuntu-minimal -t lucid.tar.xz lucid http://archive.ubuntu.com/ubuntu/", 1736 "Tags": null, 1737 "Size": 0, 1738 "Comment": "" 1739 }, 1740 { 1741 "Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158", 1742 "Created": 1371157430, 1743 "CreatedBy": "", 1744 "Tags": [ 1745 "scratch12:latest", 1746 "scratch:latest" 1747 ], 1748 "Size": 0, 1749 "Comment": "Imported from -" 1750 } 1751 ] 1752 1753 **Status codes**: 1754 1755 - **200** – no error 1756 - **404** – no such image 1757 - **500** – server error 1758 1759 ### Push an image on the registry 1760 1761 `POST /images/(name)/push` 1762 1763 Push the image `name` on the registry 1764 1765 **Example request**: 1766 1767 POST /images/test/push HTTP/1.1 1768 1769 **Example response**: 1770 1771 HTTP/1.1 200 OK 1772 Content-Type: application/json 1773 1774 {"status": "Pushing..."} 1775 {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} 1776 {"error": "Invalid..."} 1777 ... 1778 1779 If you wish to push an image on to a private registry, that image must already have a tag 1780 into a repository which references that registry `hostname` and `port`. This repository name should 1781 then be used in the URL. This duplicates the command line's flow. 1782 1783 **Example request**: 1784 1785 POST /images/registry.acme.com:5000/test/push HTTP/1.1 1786 1787 1788 **Query parameters**: 1789 1790 - **tag** – The tag to associate with the image on the registry. This is optional. 1791 1792 **Request Headers**: 1793 1794 - **X-Registry-Auth** – base64-encoded AuthConfig object. 1795 1796 **Status codes**: 1797 1798 - **200** – no error 1799 - **404** – no such image 1800 - **500** – server error 1801 1802 ### Tag an image into a repository 1803 1804 `POST /images/(name)/tag` 1805 1806 Tag the image `name` into a repository 1807 1808 **Example request**: 1809 1810 POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 1811 1812 **Example response**: 1813 1814 HTTP/1.1 201 Created 1815 1816 **Query parameters**: 1817 1818 - **repo** – The repository to tag in 1819 - **force** – 1/True/true or 0/False/false, default false 1820 - **tag** - The new tag name 1821 1822 **Status codes**: 1823 1824 - **201** – no error 1825 - **400** – bad parameter 1826 - **404** – no such image 1827 - **409** – conflict 1828 - **500** – server error 1829 1830 ### Remove an image 1831 1832 `DELETE /images/(name)` 1833 1834 Remove the image `name` from the filesystem 1835 1836 **Example request**: 1837 1838 DELETE /images/test HTTP/1.1 1839 1840 **Example response**: 1841 1842 HTTP/1.1 200 OK 1843 Content-type: application/json 1844 1845 [ 1846 {"Untagged": "3e2f21a89f"}, 1847 {"Deleted": "3e2f21a89f"}, 1848 {"Deleted": "53b4f83ac9"} 1849 ] 1850 1851 **Query parameters**: 1852 1853 - **force** – 1/True/true or 0/False/false, default false 1854 - **noprune** – 1/True/true or 0/False/false, default false 1855 1856 **Status codes**: 1857 1858 - **200** – no error 1859 - **404** – no such image 1860 - **409** – conflict 1861 - **500** – server error 1862 1863 ### Search images 1864 1865 `GET /images/search` 1866 1867 Search for an image on [Docker Hub](https://hub.docker.com). 1868 1869 > **Note**: 1870 > The response keys have changed from API v1.6 to reflect the JSON 1871 > sent by the registry server to the docker daemon's request. 1872 1873 **Example request**: 1874 1875 GET /images/search?term=sshd HTTP/1.1 1876 1877 **Example response**: 1878 1879 HTTP/1.1 200 OK 1880 Content-Type: application/json 1881 1882 [ 1883 { 1884 "description": "", 1885 "is_official": false, 1886 "is_automated": false, 1887 "name": "wma55/u1210sshd", 1888 "star_count": 0 1889 }, 1890 { 1891 "description": "", 1892 "is_official": false, 1893 "is_automated": false, 1894 "name": "jdswinbank/sshd", 1895 "star_count": 0 1896 }, 1897 { 1898 "description": "", 1899 "is_official": false, 1900 "is_automated": false, 1901 "name": "vgauthier/sshd", 1902 "star_count": 0 1903 } 1904 ... 1905 ] 1906 1907 **Query parameters**: 1908 1909 - **term** – term to search 1910 1911 **Status codes**: 1912 1913 - **200** – no error 1914 - **500** – server error 1915 1916 ## 2.3 Misc 1917 1918 ### Check auth configuration 1919 1920 `POST /auth` 1921 1922 Get the default username and email 1923 1924 **Example request**: 1925 1926 POST /auth HTTP/1.1 1927 Content-Type: application/json 1928 1929 { 1930 "username": "hannibal", 1931 "password": "xxxx", 1932 "email": "hannibal@a-team.com", 1933 "serveraddress": "https://index.docker.io/v1/" 1934 } 1935 1936 **Example response**: 1937 1938 HTTP/1.1 200 OK 1939 1940 **Status codes**: 1941 1942 - **200** – no error 1943 - **204** – no error 1944 - **500** – server error 1945 1946 ### Display system-wide information 1947 1948 `GET /info` 1949 1950 Display system-wide information 1951 1952 **Example request**: 1953 1954 GET /info HTTP/1.1 1955 1956 **Example response**: 1957 1958 HTTP/1.1 200 OK 1959 Content-Type: application/json 1960 1961 { 1962 "ClusterStore": "etcd://localhost:2379", 1963 "Containers": 11, 1964 "CpuCfsPeriod": true, 1965 "CpuCfsQuota": true, 1966 "Debug": false, 1967 "DockerRootDir": "/var/lib/docker", 1968 "Driver": "btrfs", 1969 "DriverStatus": [[""]], 1970 "ExecutionDriver": "native-0.1", 1971 "ExperimentalBuild": false, 1972 "HttpProxy": "http://test:test@localhost:8080", 1973 "HttpsProxy": "https://test:test@localhost:8080", 1974 "ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS", 1975 "IPv4Forwarding": true, 1976 "Images": 16, 1977 "IndexServerAddress": "https://index.docker.io/v1/", 1978 "InitPath": "/usr/bin/docker", 1979 "InitSha1": "", 1980 "KernelVersion": "3.12.0-1-amd64", 1981 "Labels": [ 1982 "storage=ssd" 1983 ], 1984 "MemTotal": 2099236864, 1985 "MemoryLimit": true, 1986 "NCPU": 1, 1987 "NEventsListener": 0, 1988 "NFd": 11, 1989 "NGoroutines": 21, 1990 "Name": "prod-server-42", 1991 "NoProxy": "9.81.1.160", 1992 "OomKillDisable": true, 1993 "OperatingSystem": "Boot2Docker", 1994 "RegistryConfig": { 1995 "IndexConfigs": { 1996 "docker.io": { 1997 "Mirrors": null, 1998 "Name": "docker.io", 1999 "Official": true, 2000 "Secure": true 2001 } 2002 }, 2003 "InsecureRegistryCIDRs": [ 2004 "127.0.0.0/8" 2005 ] 2006 }, 2007 "ServerVersion": "1.9.0", 2008 "SwapLimit": false, 2009 "SystemTime": "2015-03-10T11:11:23.730591467-07:00" 2010 } 2011 2012 **Status codes**: 2013 2014 - **200** – no error 2015 - **500** – server error 2016 2017 ### Show the docker version information 2018 2019 `GET /version` 2020 2021 Show the docker version information 2022 2023 **Example request**: 2024 2025 GET /version HTTP/1.1 2026 2027 **Example response**: 2028 2029 HTTP/1.1 200 OK 2030 Content-Type: application/json 2031 2032 { 2033 "Version": "1.5.0", 2034 "Os": "linux", 2035 "KernelVersion": "3.18.5-tinycore64", 2036 "GoVersion": "go1.4.1", 2037 "GitCommit": "a8a31ef", 2038 "Arch": "amd64", 2039 "ApiVersion": "1.20", 2040 "Experimental": false 2041 } 2042 2043 **Status codes**: 2044 2045 - **200** – no error 2046 - **500** – server error 2047 2048 ### Ping the docker server 2049 2050 `GET /_ping` 2051 2052 Ping the docker server 2053 2054 **Example request**: 2055 2056 GET /_ping HTTP/1.1 2057 2058 **Example response**: 2059 2060 HTTP/1.1 200 OK 2061 Content-Type: text/plain 2062 2063 OK 2064 2065 **Status codes**: 2066 2067 - **200** - no error 2068 - **500** - server error 2069 2070 ### Create a new image from a container's changes 2071 2072 `POST /commit` 2073 2074 Create a new image from a container's changes 2075 2076 **Example request**: 2077 2078 POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 2079 Content-Type: application/json 2080 2081 { 2082 "Hostname": "", 2083 "Domainname": "", 2084 "User": "", 2085 "AttachStdin": false, 2086 "AttachStdout": true, 2087 "AttachStderr": true, 2088 "Tty": false, 2089 "OpenStdin": false, 2090 "StdinOnce": false, 2091 "Env": null, 2092 "Cmd": [ 2093 "date" 2094 ], 2095 "Mounts": [ 2096 { 2097 "Source": "/data", 2098 "Destination": "/data", 2099 "Mode": "ro,Z", 2100 "RW": false 2101 } 2102 ], 2103 "Labels": { 2104 "key1": "value1", 2105 "key2": "value2" 2106 }, 2107 "WorkingDir": "", 2108 "NetworkDisabled": false, 2109 "ExposedPorts": { 2110 "22/tcp": {} 2111 } 2112 } 2113 2114 **Example response**: 2115 2116 HTTP/1.1 201 Created 2117 Content-Type: application/json 2118 2119 {"Id": "596069db4bf5"} 2120 2121 **JSON parameters**: 2122 2123 - **config** - the container's configuration 2124 2125 **Query parameters**: 2126 2127 - **container** – source container 2128 - **repo** – repository 2129 - **tag** – tag 2130 - **comment** – commit message 2131 - **author** – author (e.g., "John Hannibal Smith 2132 <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") 2133 - **pause** – 1/True/true or 0/False/false, whether to pause the container before committing 2134 - **changes** – Dockerfile instructions to apply while committing 2135 2136 **Status codes**: 2137 2138 - **201** – no error 2139 - **404** – no such container 2140 - **500** – server error 2141 2142 ### Monitor Docker's events 2143 2144 `GET /events` 2145 2146 Get container events from docker, in real time via streaming. 2147 2148 Docker containers report the following events: 2149 2150 attach, commit, copy, create, destroy, die, exec_create, exec_start, export, kill, oom, pause, rename, resize, restart, start, stop, top, unpause 2151 2152 Docker images report the following events: 2153 2154 delete, import, pull, push, tag, untag 2155 2156 **Example request**: 2157 2158 GET /events?since=1374067924 2159 2160 **Example response**: 2161 2162 HTTP/1.1 200 OK 2163 Content-Type: application/json 2164 2165 {"status":"pull","id":"busybox:latest","time":1442421700,"timeNano":1442421700598988358} 2166 {"status":"create","id":"5745704abe9caa5","from":"busybox","time":1442421716,"timeNano":1442421716853979870} 2167 {"status":"attach","id":"5745704abe9caa5","from":"busybox","time":1442421716,"timeNano":1442421716894759198} 2168 {"status":"start","id":"5745704abe9caa5","from":"busybox","time":1442421716,"timeNano":1442421716983607193} 2169 2170 **Query parameters**: 2171 2172 - **since** – Timestamp. Show all events created since timestamp and then stream 2173 - **until** – Timestamp. Show events created until given timestamp and stop streaming 2174 - **filters** – A json encoded value of the filters (a map[string][]string) to process on the event list. Available filters: 2175 - `container=<string>`; -- container to filter 2176 - `event=<string>`; -- event to filter 2177 - `image=<string>`; -- image to filter 2178 - `label=<string>`; -- image and container label to filter 2179 2180 **Status codes**: 2181 2182 - **200** – no error 2183 - **500** – server error 2184 2185 ### Get a tarball containing all images in a repository 2186 2187 `GET /images/(name)/get` 2188 2189 Get a tarball containing all images and metadata for the repository specified 2190 by `name`. 2191 2192 If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image 2193 (and its parents) are returned. If `name` is an image ID, similarly only that 2194 image (and its parents) are returned, but with the exclusion of the 2195 'repositories' file in the tarball, as there were no image names referenced. 2196 2197 See the [image tarball format](#image-tarball-format) for more details. 2198 2199 **Example request** 2200 2201 GET /images/ubuntu/get 2202 2203 **Example response**: 2204 2205 HTTP/1.1 200 OK 2206 Content-Type: application/x-tar 2207 2208 Binary data stream 2209 2210 **Status codes**: 2211 2212 - **200** – no error 2213 - **500** – server error 2214 2215 ### Get a tarball containing all images 2216 2217 `GET /images/get` 2218 2219 Get a tarball containing all images and metadata for one or more repositories. 2220 2221 For each value of the `names` parameter: if it is a specific name and tag (e.g. 2222 `ubuntu:latest`), then only that image (and its parents) are returned; if it is 2223 an image ID, similarly only that image (and its parents) are returned and there 2224 would be no names referenced in the 'repositories' file for this image ID. 2225 2226 See the [image tarball format](#image-tarball-format) for more details. 2227 2228 **Example request** 2229 2230 GET /images/get?names=myname%2Fmyapp%3Alatest&names=busybox 2231 2232 **Example response**: 2233 2234 HTTP/1.1 200 OK 2235 Content-Type: application/x-tar 2236 2237 Binary data stream 2238 2239 **Status codes**: 2240 2241 - **200** – no error 2242 - **500** – server error 2243 2244 ### Load a tarball with a set of images and tags into docker 2245 2246 `POST /images/load` 2247 2248 Load a set of images and tags into a Docker repository. 2249 See the [image tarball format](#image-tarball-format) for more details. 2250 2251 **Example request** 2252 2253 POST /images/load 2254 Content-Type: application/x-tar 2255 2256 Tarball in body 2257 2258 **Example response**: 2259 2260 HTTP/1.1 200 OK 2261 2262 **Status codes**: 2263 2264 - **200** – no error 2265 - **500** – server error 2266 2267 ### Image tarball format 2268 2269 An image tarball contains one directory per image layer (named using its long ID), 2270 each containing these files: 2271 2272 - `VERSION`: currently `1.0` - the file format version 2273 - `json`: detailed layer information, similar to `docker inspect layer_id` 2274 - `layer.tar`: A tarfile containing the filesystem changes in this layer 2275 2276 The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories 2277 for storing attribute changes and deletions. 2278 2279 If the tarball defines a repository, the tarball should also include a `repositories` file at 2280 the root that contains a list of repository and tag names mapped to layer IDs. 2281 2282 ``` 2283 {"hello-world": 2284 {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} 2285 } 2286 ``` 2287 2288 ### Exec Create 2289 2290 `POST /containers/(id or name)/exec` 2291 2292 Sets up an exec instance in a running container `id` 2293 2294 **Example request**: 2295 2296 POST /containers/e90e34656806/exec HTTP/1.1 2297 Content-Type: application/json 2298 2299 { 2300 "AttachStdin": true, 2301 "AttachStdout": true, 2302 "AttachStderr": true, 2303 "Cmd": ["sh"], 2304 "Privileged": true, 2305 "Tty": true, 2306 "User": "123:456" 2307 } 2308 2309 **Example response**: 2310 2311 HTTP/1.1 201 Created 2312 Content-Type: application/json 2313 2314 { 2315 "Id": "f90e34656806", 2316 "Warnings":[] 2317 } 2318 2319 **JSON parameters**: 2320 2321 - **AttachStdin** - Boolean value, attaches to `stdin` of the `exec` command. 2322 - **AttachStdout** - Boolean value, attaches to `stdout` of the `exec` command. 2323 - **AttachStderr** - Boolean value, attaches to `stderr` of the `exec` command. 2324 - **Tty** - Boolean value to allocate a pseudo-TTY. 2325 - **Cmd** - Command to run specified as a string or an array of strings. 2326 - **Privileged** - Boolean value, runs the exec process with extended privileges. 2327 - **User** - A string value specifying the user, and optionally, group to run 2328 the exec process inside the container. Format is one of: `"user"`, 2329 `"user:group"`, `"uid"`, or `"uid:gid"`. 2330 2331 **Status codes**: 2332 2333 - **201** – no error 2334 - **404** – no such container 2335 - **409** - container is paused 2336 - **500** - server error 2337 2338 ### Exec Start 2339 2340 `POST /exec/(id)/start` 2341 2342 Starts a previously set up `exec` instance `id`. If `detach` is true, this API 2343 returns after starting the `exec` command. Otherwise, this API sets up an 2344 interactive session with the `exec` command. 2345 2346 **Example request**: 2347 2348 POST /exec/e90e34656806/start HTTP/1.1 2349 Content-Type: application/json 2350 2351 { 2352 "Detach": false, 2353 "Tty": false 2354 } 2355 2356 **Example response**: 2357 2358 HTTP/1.1 200 OK 2359 Content-Type: application/vnd.docker.raw-stream 2360 2361 {% raw %} 2362 {{ STREAM }} 2363 {% endraw %} 2364 2365 **JSON parameters**: 2366 2367 - **Detach** - Detach from the `exec` command. 2368 - **Tty** - Boolean value to allocate a pseudo-TTY. 2369 2370 **Status codes**: 2371 2372 - **200** – no error 2373 - **404** – no such exec instance 2374 - **409** - container is paused 2375 2376 **Stream details**: 2377 2378 Similar to the stream behavior of `POST /containers/(id or name)/attach` API 2379 2380 ### Exec Resize 2381 2382 `POST /exec/(id)/resize` 2383 2384 Resizes the `tty` session used by the `exec` command `id`. The unit is number of characters. 2385 This API is valid only if `tty` was specified as part of creating and starting the `exec` command. 2386 2387 **Example request**: 2388 2389 POST /exec/e90e34656806/resize?h=40&w=80 HTTP/1.1 2390 Content-Type: text/plain 2391 2392 **Example response**: 2393 2394 HTTP/1.1 201 Created 2395 Content-Type: text/plain 2396 2397 **Query parameters**: 2398 2399 - **h** – height of `tty` session 2400 - **w** – width 2401 2402 **Status codes**: 2403 2404 - **201** – no error 2405 - **404** – no such exec instance 2406 2407 ### Exec Inspect 2408 2409 `GET /exec/(id)/json` 2410 2411 Return low-level information about the `exec` command `id`. 2412 2413 **Example request**: 2414 2415 GET /exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1 2416 2417 **Example response**: 2418 2419 HTTP/1.1 200 OK 2420 Content-Type: plain/text 2421 2422 { 2423 "ID" : "11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39", 2424 "Running" : false, 2425 "ExitCode" : 2, 2426 "ProcessConfig" : { 2427 "privileged" : false, 2428 "user" : "", 2429 "tty" : false, 2430 "entrypoint" : "sh", 2431 "arguments" : [ 2432 "-c", 2433 "exit 2" 2434 ] 2435 }, 2436 "OpenStdin" : false, 2437 "OpenStderr" : false, 2438 "OpenStdout" : false, 2439 "Container" : { 2440 "State" : { 2441 "Status" : "running", 2442 "Running" : true, 2443 "Paused" : false, 2444 "Restarting" : false, 2445 "OOMKilled" : false, 2446 "Pid" : 3650, 2447 "ExitCode" : 0, 2448 "Error" : "", 2449 "StartedAt" : "2014-11-17T22:26:03.717657531Z", 2450 "FinishedAt" : "0001-01-01T00:00:00Z" 2451 }, 2452 "ID" : "8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c", 2453 "Created" : "2014-11-17T22:26:03.626304998Z", 2454 "Path" : "date", 2455 "Args" : [], 2456 "Config" : { 2457 "Hostname" : "8f177a186b97", 2458 "Domainname" : "", 2459 "User" : "", 2460 "AttachStdin" : false, 2461 "AttachStdout" : false, 2462 "AttachStderr" : false, 2463 "ExposedPorts" : null, 2464 "Tty" : false, 2465 "OpenStdin" : false, 2466 "StdinOnce" : false, 2467 "Env" : [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ], 2468 "Cmd" : [ 2469 "date" 2470 ], 2471 "Image" : "ubuntu", 2472 "Volumes" : null, 2473 "WorkingDir" : "", 2474 "Entrypoint" : null, 2475 "NetworkDisabled" : false, 2476 "MacAddress" : "", 2477 "OnBuild" : null, 2478 "SecurityOpt" : null 2479 }, 2480 "Image" : "5506de2b643be1e6febbf3b8a240760c6843244c41e12aa2f60ccbb7153d17f5", 2481 "NetworkSettings" : { 2482 "Bridge": "", 2483 "SandboxID": "", 2484 "HairpinMode": false, 2485 "LinkLocalIPv6Address": "", 2486 "LinkLocalIPv6PrefixLen": 0, 2487 "Ports": null, 2488 "SandboxKey": "", 2489 "SecondaryIPAddresses": null, 2490 "SecondaryIPv6Addresses": null, 2491 "EndpointID": "", 2492 "Gateway": "", 2493 "GlobalIPv6Address": "", 2494 "GlobalIPv6PrefixLen": 0, 2495 "IPAddress": "", 2496 "IPPrefixLen": 0, 2497 "IPv6Gateway": "", 2498 "MacAddress": "", 2499 "Networks": { 2500 "bridge": { 2501 "EndpointID": "", 2502 "Gateway": "", 2503 "IPAddress": "", 2504 "IPPrefixLen": 0, 2505 "IPv6Gateway": "", 2506 "GlobalIPv6Address": "", 2507 "GlobalIPv6PrefixLen": 0, 2508 "MacAddress": "" 2509 } 2510 } 2511 }, 2512 "ResolvConfPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/resolv.conf", 2513 "HostnamePath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hostname", 2514 "HostsPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hosts", 2515 "LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log", 2516 "Name" : "/test", 2517 "Driver" : "aufs", 2518 "ExecDriver" : "native-0.2", 2519 "MountLabel" : "", 2520 "ProcessLabel" : "", 2521 "AppArmorProfile" : "", 2522 "RestartCount" : 0, 2523 "Mounts" : [] 2524 } 2525 } 2526 2527 **Status codes**: 2528 2529 - **200** – no error 2530 - **404** – no such exec instance 2531 - **500** - server error 2532 2533 ## 2.4 Volumes 2534 2535 ### List volumes 2536 2537 `GET /volumes` 2538 2539 **Example request**: 2540 2541 GET /volumes HTTP/1.1 2542 2543 **Example response**: 2544 2545 HTTP/1.1 200 OK 2546 Content-Type: application/json 2547 2548 { 2549 "Volumes": [ 2550 { 2551 "Name": "tardis", 2552 "Driver": "local", 2553 "Mountpoint": "/var/lib/docker/volumes/tardis" 2554 } 2555 ] 2556 } 2557 2558 **Query parameters**: 2559 2560 - **filters** - JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. There is one available filter: `dangling=true` 2561 2562 **Status codes**: 2563 2564 - **200** - no error 2565 - **500** - server error 2566 2567 ### Create a volume 2568 2569 `POST /volumes/create` 2570 2571 Create a volume 2572 2573 **Example request**: 2574 2575 POST /volumes/create HTTP/1.1 2576 Content-Type: application/json 2577 2578 { 2579 "Name": "tardis" 2580 } 2581 2582 **Example response**: 2583 2584 HTTP/1.1 201 Created 2585 Content-Type: application/json 2586 2587 { 2588 "Name": "tardis", 2589 "Driver": "local", 2590 "Mountpoint": "/var/lib/docker/volumes/tardis" 2591 } 2592 2593 **Status codes**: 2594 2595 - **201** - no error 2596 - **500** - server error 2597 2598 **JSON parameters**: 2599 2600 - **Name** - The new volume's name. If not specified, Docker generates a name. 2601 - **Driver** - Name of the volume driver to use. Defaults to `local` for the name. 2602 - **DriverOpts** - A mapping of driver options and values. These options are 2603 passed directly to the driver and are driver specific. 2604 2605 ### Inspect a volume 2606 2607 `GET /volumes/(name)` 2608 2609 Return low-level information on the volume `name` 2610 2611 **Example request**: 2612 2613 GET /volumes/tardis 2614 2615 **Example response**: 2616 2617 HTTP/1.1 200 OK 2618 Content-Type: application/json 2619 2620 { 2621 "Name": "tardis", 2622 "Driver": "local", 2623 "Mountpoint": "/var/lib/docker/volumes/tardis" 2624 } 2625 2626 **Status codes**: 2627 2628 - **200** - no error 2629 - **404** - no such volume 2630 - **500** - server error 2631 2632 ### Remove a volume 2633 2634 `DELETE /volumes/(name)` 2635 2636 Instruct the driver to remove the volume (`name`). 2637 2638 **Example request**: 2639 2640 DELETE /volumes/tardis HTTP/1.1 2641 2642 **Example response**: 2643 2644 HTTP/1.1 204 No Content 2645 2646 **Status codes**: 2647 2648 - **204** - no error 2649 - **404** - no such volume or volume driver 2650 - **409** - volume is in use and cannot be removed 2651 - **500** - server error 2652 2653 ## 2.5 Networks 2654 2655 ### List networks 2656 2657 `GET /networks` 2658 2659 **Example request**: 2660 2661 GET /networks HTTP/1.1 2662 2663 **Example response**: 2664 2665 ``` 2666 HTTP/1.1 200 OK 2667 Content-Type: application/json 2668 2669 [ 2670 { 2671 "Name": "bridge", 2672 "Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566", 2673 "Scope": "local", 2674 "Driver": "bridge", 2675 "IPAM": { 2676 "Driver": "default", 2677 "Config": [ 2678 { 2679 "Subnet": "172.17.0.0/16" 2680 } 2681 ] 2682 }, 2683 "Containers": { 2684 "39b69226f9d79f5634485fb236a23b2fe4e96a0a94128390a7fbbcc167065867": { 2685 "EndpointID": "ed2419a97c1d9954d05b46e462e7002ea552f216e9b136b80a7db8d98b442eda", 2686 "MacAddress": "02:42:ac:11:00:02", 2687 "IPv4Address": "172.17.0.2/16", 2688 "IPv6Address": "" 2689 } 2690 }, 2691 "Options": { 2692 "com.docker.network.bridge.default_bridge": "true", 2693 "com.docker.network.bridge.enable_icc": "true", 2694 "com.docker.network.bridge.enable_ip_masquerade": "true", 2695 "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", 2696 "com.docker.network.bridge.name": "docker0", 2697 "com.docker.network.driver.mtu": "1500" 2698 } 2699 }, 2700 { 2701 "Name": "none", 2702 "Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794", 2703 "Scope": "local", 2704 "Driver": "null", 2705 "IPAM": { 2706 "Driver": "default", 2707 "Config": [] 2708 }, 2709 "Containers": {}, 2710 "Options": {} 2711 }, 2712 { 2713 "Name": "host", 2714 "Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e", 2715 "Scope": "local", 2716 "Driver": "host", 2717 "IPAM": { 2718 "Driver": "default", 2719 "Config": [] 2720 }, 2721 "Containers": {}, 2722 "Options": {} 2723 } 2724 ] 2725 ``` 2726 2727 **Query parameters**: 2728 2729 - **filters** - JSON encoded value of the filters (a `map[string][]string`) to process on the networks list. Available filters: `name=[network-names]` , `id=[network-ids]` 2730 2731 **Status codes**: 2732 2733 - **200** - no error 2734 - **500** - server error 2735 2736 ### Inspect network 2737 2738 `GET /networks/<network-id>` 2739 2740 **Example request**: 2741 2742 GET /networks/f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566 HTTP/1.1 2743 2744 **Example response**: 2745 2746 ``` 2747 HTTP/1.1 200 OK 2748 Content-Type: application/json 2749 2750 { 2751 "Name": "bridge", 2752 "Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566", 2753 "Scope": "local", 2754 "Driver": "bridge", 2755 "IPAM": { 2756 "Driver": "default", 2757 "Config": [ 2758 { 2759 "Subnet": "172.17.0.0/16" 2760 } 2761 ] 2762 }, 2763 "Containers": { 2764 "39b69226f9d79f5634485fb236a23b2fe4e96a0a94128390a7fbbcc167065867": { 2765 "EndpointID": "ed2419a97c1d9954d05b46e462e7002ea552f216e9b136b80a7db8d98b442eda", 2766 "MacAddress": "02:42:ac:11:00:02", 2767 "IPv4Address": "172.17.0.2/16", 2768 "IPv6Address": "" 2769 } 2770 }, 2771 "Options": { 2772 "com.docker.network.bridge.default_bridge": "true", 2773 "com.docker.network.bridge.enable_icc": "true", 2774 "com.docker.network.bridge.enable_ip_masquerade": "true", 2775 "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", 2776 "com.docker.network.bridge.name": "docker0", 2777 "com.docker.network.driver.mtu": "1500" 2778 } 2779 } 2780 ``` 2781 2782 **Status codes**: 2783 2784 - **200** - no error 2785 - **404** - network not found 2786 2787 ### Create a network 2788 2789 `POST /networks/create` 2790 2791 Create a network 2792 2793 **Example request**: 2794 2795 ``` 2796 POST /networks/create HTTP/1.1 2797 Content-Type: application/json 2798 2799 { 2800 "Name":"isolated_nw", 2801 "CheckDuplicate":true, 2802 "Driver":"bridge", 2803 "IPAM":{ 2804 "Driver": "default", 2805 "Config":[ 2806 { 2807 "Subnet":"172.20.0.0/16", 2808 "IPRange":"172.20.10.0/24", 2809 "Gateway":"172.20.10.11" 2810 } 2811 ] 2812 } 2813 } 2814 ``` 2815 2816 **Example response**: 2817 2818 ``` 2819 HTTP/1.1 201 Created 2820 Content-Type: application/json 2821 2822 { 2823 "Id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30", 2824 "Warning": "" 2825 } 2826 ``` 2827 2828 **Status codes**: 2829 2830 - **201** - no error 2831 - **404** - plugin not found 2832 - **500** - server error 2833 2834 **JSON parameters**: 2835 2836 - **Name** - The new network's name. this is a mandatory field 2837 - **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false` 2838 - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver 2839 - **IPAM** - Optional custom IP scheme for the network 2840 - **Driver** - Name of the IPAM driver to use. Defaults to `default` driver 2841 - **Config** - List of IPAM configuration options, specified as a map: 2842 `{"Subnet": <CIDR>, "IPRange": <CIDR>, "Gateway": <IP address>, "AuxAddress": <device_name:IP address>}` 2843 - **Options** - Network specific options to be used by the drivers 2844 2845 ### Connect a container to a network 2846 2847 `POST /networks/(id)/connect` 2848 2849 Connect a container to a network 2850 2851 **Example request**: 2852 2853 ``` 2854 POST /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1 2855 Content-Type: application/json 2856 2857 { 2858 "Container":"3613f73ba0e4" 2859 } 2860 ``` 2861 2862 **Example response**: 2863 2864 HTTP/1.1 200 OK 2865 2866 **Status codes**: 2867 2868 - **200** - no error 2869 - **404** - network or container is not found 2870 - **500** - Internal Server Error 2871 2872 **JSON parameters**: 2873 2874 - **container** - container-id/name to be connected to the network 2875 2876 ### Disconnect a container from a network 2877 2878 `POST /networks/(id)/disconnect` 2879 2880 Disconnect a container from a network 2881 2882 **Example request**: 2883 2884 ``` 2885 POST /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1 2886 Content-Type: application/json 2887 2888 { 2889 "Container":"3613f73ba0e4" 2890 } 2891 ``` 2892 2893 **Example response**: 2894 2895 HTTP/1.1 200 OK 2896 2897 **Status codes**: 2898 2899 - **200** - no error 2900 - **404** - network or container not found 2901 - **500** - Internal Server Error 2902 2903 **JSON parameters**: 2904 2905 - **Container** - container-id/name to be disconnected from a network 2906 2907 ### Remove a network 2908 2909 `DELETE /networks/(id)` 2910 2911 Instruct the driver to remove the network (`id`). 2912 2913 **Example request**: 2914 2915 DELETE /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30 HTTP/1.1 2916 2917 **Example response**: 2918 2919 HTTP/1.1 200 OK 2920 2921 **Status codes**: 2922 2923 - **200** - no error 2924 - **404** - no such network 2925 - **500** - server error 2926 2927 # 3. Going further 2928 2929 ## 3.1 Inside `docker run` 2930 2931 As an example, the `docker run` command line makes the following API calls: 2932 2933 - Create the container 2934 2935 - If the status code is 404, it means the image doesn't exist: 2936 - Try to pull it. 2937 - Then, retry to create the container. 2938 2939 - Start the container. 2940 2941 - If you are not in detached mode: 2942 - Attach to the container, using `logs=1` (to have `stdout` and 2943 `stderr` from the container's start) and `stream=1` 2944 2945 - If in detached mode or only `stdin` is attached, display the container's id. 2946 2947 ## 3.2 Hijacking 2948 2949 In this version of the API, `/attach`, uses hijacking to transport `stdin`, 2950 `stdout`, and `stderr` on the same socket. 2951 2952 To hint potential proxies about connection hijacking, Docker client sends 2953 connection upgrade headers similarly to websocket. 2954 2955 Upgrade: tcp 2956 Connection: Upgrade 2957 2958 When Docker daemon detects the `Upgrade` header, it switches its status code 2959 from **200 OK** to **101 UPGRADED** and resends the same headers. 2960 2961 2962 ## 3.3 CORS Requests 2963 2964 To set cross origin requests to the remote api please give values to 2965 `--api-cors-header` when running Docker in daemon mode. Set * (asterisk) allows all, 2966 default or blank means CORS disabled 2967 2968 $ dockerd -H="192.168.1.9:2375" --api-cors-header="http://foo.bar"