github.com/olljanat/moby@v1.13.1/docs/api/v1.21.md (about) 1 --- 2 title: "Engine API v1.21" 3 description: "API Documentation for Docker" 4 keywords: "API, Docker, rcli, REST, documentation" 5 redirect_from: 6 - /engine/reference/api/docker_remote_api_v1.21/ 7 - /reference/api/docker_remote_api_v1.21/ 8 --- 9 10 <!-- This file is maintained within the docker/docker Github 11 repository at https://github.com/docker/docker/. Make all 12 pull requests against that repo. If you see this file in 13 another repository, consider it read-only there, as it will 14 periodically be overwritten by the definitive file. Pull 15 requests which include edits to this file in other repositories 16 will be rejected. 17 --> 18 19 ## 1. Brief introduction 20 21 - The daemon listens on `unix:///var/run/docker.sock` but you can 22 [Bind Docker to another host/port or a Unix socket](../reference/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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 /v1.21/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/5..."} 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 /v1.21/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 - **404** - repository does not exist or no read access 1591 - **500** – server error 1592 1593 1594 1595 #### Inspect an image 1596 1597 `GET /images/(name)/json` 1598 1599 Return low-level information on the image `name` 1600 1601 **Example request**: 1602 1603 GET /v1.21/images/example/json HTTP/1.1 1604 1605 **Example response**: 1606 1607 HTTP/1.1 200 OK 1608 Content-Type: application/json 1609 1610 { 1611 "Id" : "85f05633ddc1c50679be2b16a0479ab6f7637f8884e0cfe0f4d20e1ebb3d6e7c", 1612 "Container" : "cb91e48a60d01f1e27028b4fc6819f4f290b3cf12496c8176ec714d0d390984a", 1613 "Comment" : "", 1614 "Os" : "linux", 1615 "Architecture" : "amd64", 1616 "Parent" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1617 "ContainerConfig" : { 1618 "Tty" : false, 1619 "Hostname" : "e611e15f9c9d", 1620 "Volumes" : null, 1621 "Domainname" : "", 1622 "AttachStdout" : false, 1623 "PublishService" : "", 1624 "AttachStdin" : false, 1625 "OpenStdin" : false, 1626 "StdinOnce" : false, 1627 "NetworkDisabled" : false, 1628 "OnBuild" : [], 1629 "Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1630 "User" : "", 1631 "WorkingDir" : "", 1632 "Entrypoint" : null, 1633 "MacAddress" : "", 1634 "AttachStderr" : false, 1635 "Labels" : { 1636 "com.example.license" : "GPL", 1637 "com.example.version" : "1.0", 1638 "com.example.vendor" : "Acme" 1639 }, 1640 "Env" : [ 1641 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 1642 ], 1643 "ExposedPorts" : null, 1644 "Cmd" : [ 1645 "/bin/sh", 1646 "-c", 1647 "#(nop) LABEL com.example.vendor=Acme com.example.license=GPL com.example.version=1.0" 1648 ] 1649 }, 1650 "DockerVersion" : "1.9.0-dev", 1651 "VirtualSize" : 188359297, 1652 "Size" : 0, 1653 "Author" : "", 1654 "Created" : "2015-09-10T08:30:53.26995814Z", 1655 "GraphDriver" : { 1656 "Name" : "aufs", 1657 "Data" : null 1658 }, 1659 "RepoDigests" : [ 1660 "localhost:5000/test/busybox/example@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf" 1661 ], 1662 "RepoTags" : [ 1663 "example:1.0", 1664 "example:latest", 1665 "example:stable" 1666 ], 1667 "Config" : { 1668 "Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1669 "NetworkDisabled" : false, 1670 "OnBuild" : [], 1671 "StdinOnce" : false, 1672 "PublishService" : "", 1673 "AttachStdin" : false, 1674 "OpenStdin" : false, 1675 "Domainname" : "", 1676 "AttachStdout" : false, 1677 "Tty" : false, 1678 "Hostname" : "e611e15f9c9d", 1679 "Volumes" : null, 1680 "Cmd" : [ 1681 "/bin/bash" 1682 ], 1683 "ExposedPorts" : null, 1684 "Env" : [ 1685 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 1686 ], 1687 "Labels" : { 1688 "com.example.vendor" : "Acme", 1689 "com.example.version" : "1.0", 1690 "com.example.license" : "GPL" 1691 }, 1692 "Entrypoint" : null, 1693 "MacAddress" : "", 1694 "AttachStderr" : false, 1695 "WorkingDir" : "", 1696 "User" : "" 1697 } 1698 } 1699 1700 **Status codes**: 1701 1702 - **200** – no error 1703 - **404** – no such image 1704 - **500** – server error 1705 1706 #### Get the history of an image 1707 1708 `GET /images/(name)/history` 1709 1710 Return the history of the image `name` 1711 1712 **Example request**: 1713 1714 GET /v1.21/images/ubuntu/history HTTP/1.1 1715 1716 **Example response**: 1717 1718 HTTP/1.1 200 OK 1719 Content-Type: application/json 1720 1721 [ 1722 { 1723 "Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710", 1724 "Created": 1398108230, 1725 "CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /", 1726 "Tags": [ 1727 "ubuntu:lucid", 1728 "ubuntu:10.04" 1729 ], 1730 "Size": 182964289, 1731 "Comment": "" 1732 }, 1733 { 1734 "Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8", 1735 "Created": 1398108222, 1736 "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/", 1737 "Tags": null, 1738 "Size": 0, 1739 "Comment": "" 1740 }, 1741 { 1742 "Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158", 1743 "Created": 1371157430, 1744 "CreatedBy": "", 1745 "Tags": [ 1746 "scratch12:latest", 1747 "scratch:latest" 1748 ], 1749 "Size": 0, 1750 "Comment": "Imported from -" 1751 } 1752 ] 1753 1754 **Status codes**: 1755 1756 - **200** – no error 1757 - **404** – no such image 1758 - **500** – server error 1759 1760 #### Push an image on the registry 1761 1762 `POST /images/(name)/push` 1763 1764 Push the image `name` on the registry 1765 1766 **Example request**: 1767 1768 POST /v1.21/images/test/push HTTP/1.1 1769 1770 **Example response**: 1771 1772 HTTP/1.1 200 OK 1773 Content-Type: application/json 1774 1775 {"status": "Pushing..."} 1776 {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} 1777 {"error": "Invalid..."} 1778 ... 1779 1780 If you wish to push an image on to a private registry, that image must already have a tag 1781 into a repository which references that registry `hostname` and `port`. This repository name should 1782 then be used in the URL. This duplicates the command line's flow. 1783 1784 **Example request**: 1785 1786 POST /v1.21/images/registry.acme.com:5000/test/push HTTP/1.1 1787 1788 1789 **Query parameters**: 1790 1791 - **tag** – The tag to associate with the image on the registry. This is optional. 1792 1793 **Request Headers**: 1794 1795 - **X-Registry-Auth** – base64-encoded AuthConfig object. 1796 1797 **Status codes**: 1798 1799 - **200** – no error 1800 - **404** – no such image 1801 - **500** – server error 1802 1803 #### Tag an image into a repository 1804 1805 `POST /images/(name)/tag` 1806 1807 Tag the image `name` into a repository 1808 1809 **Example request**: 1810 1811 POST /v1.21/images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 1812 1813 **Example response**: 1814 1815 HTTP/1.1 201 Created 1816 1817 **Query parameters**: 1818 1819 - **repo** – The repository to tag in 1820 - **force** – 1/True/true or 0/False/false, default false 1821 - **tag** - The new tag name 1822 1823 **Status codes**: 1824 1825 - **201** – no error 1826 - **400** – bad parameter 1827 - **404** – no such image 1828 - **409** – conflict 1829 - **500** – server error 1830 1831 #### Remove an image 1832 1833 `DELETE /images/(name)` 1834 1835 Remove the image `name` from the filesystem 1836 1837 **Example request**: 1838 1839 DELETE /v1.21/images/test HTTP/1.1 1840 1841 **Example response**: 1842 1843 HTTP/1.1 200 OK 1844 Content-type: application/json 1845 1846 [ 1847 {"Untagged": "3e2f21a89f"}, 1848 {"Deleted": "3e2f21a89f"}, 1849 {"Deleted": "53b4f83ac9"} 1850 ] 1851 1852 **Query parameters**: 1853 1854 - **force** – 1/True/true or 0/False/false, default false 1855 - **noprune** – 1/True/true or 0/False/false, default false 1856 1857 **Status codes**: 1858 1859 - **200** – no error 1860 - **404** – no such image 1861 - **409** – conflict 1862 - **500** – server error 1863 1864 #### Search images 1865 1866 `GET /images/search` 1867 1868 Search for an image on [Docker Hub](https://hub.docker.com). 1869 1870 > **Note**: 1871 > The response keys have changed from API v1.6 to reflect the JSON 1872 > sent by the registry server to the docker daemon's request. 1873 1874 **Example request**: 1875 1876 GET /v1.21/images/search?term=sshd HTTP/1.1 1877 1878 **Example response**: 1879 1880 HTTP/1.1 200 OK 1881 Content-Type: application/json 1882 1883 [ 1884 { 1885 "description": "", 1886 "is_official": false, 1887 "is_automated": false, 1888 "name": "wma55/u1210sshd", 1889 "star_count": 0 1890 }, 1891 { 1892 "description": "", 1893 "is_official": false, 1894 "is_automated": false, 1895 "name": "jdswinbank/sshd", 1896 "star_count": 0 1897 }, 1898 { 1899 "description": "", 1900 "is_official": false, 1901 "is_automated": false, 1902 "name": "vgauthier/sshd", 1903 "star_count": 0 1904 } 1905 ... 1906 ] 1907 1908 **Query parameters**: 1909 1910 - **term** – term to search 1911 1912 **Status codes**: 1913 1914 - **200** – no error 1915 - **500** – server error 1916 1917 ### 2.3 Misc 1918 1919 #### Check auth configuration 1920 1921 `POST /auth` 1922 1923 Get the default username and email 1924 1925 **Example request**: 1926 1927 POST /v1.21/auth HTTP/1.1 1928 Content-Type: application/json 1929 1930 { 1931 "username": "hannibal", 1932 "password": "xxxx", 1933 "email": "hannibal@a-team.com", 1934 "serveraddress": "https://index.docker.io/v1/" 1935 } 1936 1937 **Example response**: 1938 1939 HTTP/1.1 200 OK 1940 1941 **Status codes**: 1942 1943 - **200** – no error 1944 - **204** – no error 1945 - **500** – server error 1946 1947 #### Display system-wide information 1948 1949 `GET /info` 1950 1951 Display system-wide information 1952 1953 **Example request**: 1954 1955 GET /v1.21/info HTTP/1.1 1956 1957 **Example response**: 1958 1959 HTTP/1.1 200 OK 1960 Content-Type: application/json 1961 1962 { 1963 "ClusterStore": "etcd://localhost:2379", 1964 "Containers": 11, 1965 "CpuCfsPeriod": true, 1966 "CpuCfsQuota": true, 1967 "Debug": false, 1968 "DockerRootDir": "/var/lib/docker", 1969 "Driver": "btrfs", 1970 "DriverStatus": [[""]], 1971 "ExecutionDriver": "native-0.1", 1972 "ExperimentalBuild": false, 1973 "HttpProxy": "http://test:test@localhost:8080", 1974 "HttpsProxy": "https://test:test@localhost:8080", 1975 "ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS", 1976 "IPv4Forwarding": true, 1977 "Images": 16, 1978 "IndexServerAddress": "https://index.docker.io/v1/", 1979 "InitPath": "/usr/bin/docker", 1980 "InitSha1": "", 1981 "KernelVersion": "3.12.0-1-amd64", 1982 "Labels": [ 1983 "storage=ssd" 1984 ], 1985 "MemTotal": 2099236864, 1986 "MemoryLimit": true, 1987 "NCPU": 1, 1988 "NEventsListener": 0, 1989 "NFd": 11, 1990 "NGoroutines": 21, 1991 "Name": "prod-server-42", 1992 "NoProxy": "9.81.1.160", 1993 "OomKillDisable": true, 1994 "OperatingSystem": "Boot2Docker", 1995 "RegistryConfig": { 1996 "IndexConfigs": { 1997 "docker.io": { 1998 "Mirrors": null, 1999 "Name": "docker.io", 2000 "Official": true, 2001 "Secure": true 2002 } 2003 }, 2004 "InsecureRegistryCIDRs": [ 2005 "127.0.0.0/8" 2006 ] 2007 }, 2008 "ServerVersion": "1.9.0", 2009 "SwapLimit": false, 2010 "SystemTime": "2015-03-10T11:11:23.730591467-07:00" 2011 } 2012 2013 **Status codes**: 2014 2015 - **200** – no error 2016 - **500** – server error 2017 2018 #### Show the docker version information 2019 2020 `GET /version` 2021 2022 Show the docker version information 2023 2024 **Example request**: 2025 2026 GET /v1.21/version HTTP/1.1 2027 2028 **Example response**: 2029 2030 HTTP/1.1 200 OK 2031 Content-Type: application/json 2032 2033 { 2034 "Version": "1.5.0", 2035 "Os": "linux", 2036 "KernelVersion": "3.18.5-tinycore64", 2037 "GoVersion": "go1.4.1", 2038 "GitCommit": "a8a31ef", 2039 "Arch": "amd64", 2040 "ApiVersion": "1.20", 2041 "Experimental": false 2042 } 2043 2044 **Status codes**: 2045 2046 - **200** – no error 2047 - **500** – server error 2048 2049 #### Ping the docker server 2050 2051 `GET /_ping` 2052 2053 Ping the docker server 2054 2055 **Example request**: 2056 2057 GET /v1.21/_ping HTTP/1.1 2058 2059 **Example response**: 2060 2061 HTTP/1.1 200 OK 2062 Content-Type: text/plain 2063 2064 OK 2065 2066 **Status codes**: 2067 2068 - **200** - no error 2069 - **500** - server error 2070 2071 #### Create a new image from a container's changes 2072 2073 `POST /commit` 2074 2075 Create a new image from a container's changes 2076 2077 **Example request**: 2078 2079 POST /v1.21/commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 2080 Content-Type: application/json 2081 2082 { 2083 "Hostname": "", 2084 "Domainname": "", 2085 "User": "", 2086 "AttachStdin": false, 2087 "AttachStdout": true, 2088 "AttachStderr": true, 2089 "Tty": false, 2090 "OpenStdin": false, 2091 "StdinOnce": false, 2092 "Env": null, 2093 "Cmd": [ 2094 "date" 2095 ], 2096 "Mounts": [ 2097 { 2098 "Source": "/data", 2099 "Destination": "/data", 2100 "Mode": "ro,Z", 2101 "RW": false 2102 } 2103 ], 2104 "Labels": { 2105 "key1": "value1", 2106 "key2": "value2" 2107 }, 2108 "WorkingDir": "", 2109 "NetworkDisabled": false, 2110 "ExposedPorts": { 2111 "22/tcp": {} 2112 } 2113 } 2114 2115 **Example response**: 2116 2117 HTTP/1.1 201 Created 2118 Content-Type: application/json 2119 2120 {"Id": "596069db4bf5"} 2121 2122 **JSON parameters**: 2123 2124 - **config** - the container's configuration 2125 2126 **Query parameters**: 2127 2128 - **container** – source container 2129 - **repo** – repository 2130 - **tag** – tag 2131 - **comment** – commit message 2132 - **author** – author (e.g., "John Hannibal Smith 2133 <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") 2134 - **pause** – 1/True/true or 0/False/false, whether to pause the container before committing 2135 - **changes** – Dockerfile instructions to apply while committing 2136 2137 **Status codes**: 2138 2139 - **201** – no error 2140 - **404** – no such container 2141 - **500** – server error 2142 2143 #### Monitor Docker's events 2144 2145 `GET /events` 2146 2147 Get container events from docker, in real time via streaming. 2148 2149 Docker containers report the following events: 2150 2151 attach, commit, copy, create, destroy, die, exec_create, exec_start, export, kill, oom, pause, rename, resize, restart, start, stop, top, unpause 2152 2153 Docker images report the following events: 2154 2155 delete, import, pull, push, tag, untag 2156 2157 **Example request**: 2158 2159 GET /v1.21/events?since=1374067924 2160 2161 **Example response**: 2162 2163 HTTP/1.1 200 OK 2164 Content-Type: application/json 2165 2166 {"status":"pull","id":"busybox:latest","time":1442421700,"timeNano":1442421700598988358} 2167 {"status":"create","id":"5745704abe9caa5","from":"busybox","time":1442421716,"timeNano":1442421716853979870} 2168 {"status":"attach","id":"5745704abe9caa5","from":"busybox","time":1442421716,"timeNano":1442421716894759198} 2169 {"status":"start","id":"5745704abe9caa5","from":"busybox","time":1442421716,"timeNano":1442421716983607193} 2170 2171 **Query parameters**: 2172 2173 - **since** – Timestamp. Show all events created since timestamp and then stream 2174 - **until** – Timestamp. Show events created until given timestamp and stop streaming 2175 - **filters** – A json encoded value of the filters (a map[string][]string) to process on the event list. Available filters: 2176 - `container=<string>`; -- container to filter 2177 - `event=<string>`; -- event to filter 2178 - `image=<string>`; -- image to filter 2179 - `label=<string>`; -- image and container label to filter 2180 2181 **Status codes**: 2182 2183 - **200** – no error 2184 - **500** – server error 2185 2186 #### Get a tarball containing all images in a repository 2187 2188 `GET /images/(name)/get` 2189 2190 Get a tarball containing all images and metadata for the repository specified 2191 by `name`. 2192 2193 If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image 2194 (and its parents) are returned. If `name` is an image ID, similarly only that 2195 image (and its parents) are returned, but with the exclusion of the 2196 'repositories' file in the tarball, as there were no image names referenced. 2197 2198 See the [image tarball format](#image-tarball-format) for more details. 2199 2200 **Example request** 2201 2202 GET /v1.21/images/ubuntu/get 2203 2204 **Example response**: 2205 2206 HTTP/1.1 200 OK 2207 Content-Type: application/x-tar 2208 2209 Binary data stream 2210 2211 **Status codes**: 2212 2213 - **200** – no error 2214 - **500** – server error 2215 2216 #### Get a tarball containing all images 2217 2218 `GET /images/get` 2219 2220 Get a tarball containing all images and metadata for one or more repositories. 2221 2222 For each value of the `names` parameter: if it is a specific name and tag (e.g. 2223 `ubuntu:latest`), then only that image (and its parents) are returned; if it is 2224 an image ID, similarly only that image (and its parents) are returned and there 2225 would be no names referenced in the 'repositories' file for this image ID. 2226 2227 See the [image tarball format](#image-tarball-format) for more details. 2228 2229 **Example request** 2230 2231 GET /v1.21/images/get?names=myname%2Fmyapp%3Alatest&names=busybox 2232 2233 **Example response**: 2234 2235 HTTP/1.1 200 OK 2236 Content-Type: application/x-tar 2237 2238 Binary data stream 2239 2240 **Status codes**: 2241 2242 - **200** – no error 2243 - **500** – server error 2244 2245 #### Load a tarball with a set of images and tags into docker 2246 2247 `POST /images/load` 2248 2249 Load a set of images and tags into a Docker repository. 2250 See the [image tarball format](#image-tarball-format) for more details. 2251 2252 **Example request** 2253 2254 POST /v1.21/images/load 2255 Content-Type: application/x-tar 2256 2257 Tarball in body 2258 2259 **Example response**: 2260 2261 HTTP/1.1 200 OK 2262 2263 **Status codes**: 2264 2265 - **200** – no error 2266 - **500** – server error 2267 2268 #### Image tarball format 2269 2270 An image tarball contains one directory per image layer (named using its long ID), 2271 each containing these files: 2272 2273 - `VERSION`: currently `1.0` - the file format version 2274 - `json`: detailed layer information, similar to `docker inspect layer_id` 2275 - `layer.tar`: A tarfile containing the filesystem changes in this layer 2276 2277 The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories 2278 for storing attribute changes and deletions. 2279 2280 If the tarball defines a repository, the tarball should also include a `repositories` file at 2281 the root that contains a list of repository and tag names mapped to layer IDs. 2282 2283 ``` 2284 {"hello-world": 2285 {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} 2286 } 2287 ``` 2288 2289 #### Exec Create 2290 2291 `POST /containers/(id or name)/exec` 2292 2293 Sets up an exec instance in a running container `id` 2294 2295 **Example request**: 2296 2297 POST /v1.21/containers/e90e34656806/exec HTTP/1.1 2298 Content-Type: application/json 2299 2300 { 2301 "AttachStdin": true, 2302 "AttachStdout": true, 2303 "AttachStderr": true, 2304 "Cmd": ["sh"], 2305 "Privileged": true, 2306 "Tty": true, 2307 "User": "123:456" 2308 } 2309 2310 **Example response**: 2311 2312 HTTP/1.1 201 Created 2313 Content-Type: application/json 2314 2315 { 2316 "Id": "f90e34656806", 2317 "Warnings":[] 2318 } 2319 2320 **JSON parameters**: 2321 2322 - **AttachStdin** - Boolean value, attaches to `stdin` of the `exec` command. 2323 - **AttachStdout** - Boolean value, attaches to `stdout` of the `exec` command. 2324 - **AttachStderr** - Boolean value, attaches to `stderr` of the `exec` command. 2325 - **Tty** - Boolean value to allocate a pseudo-TTY. 2326 - **Cmd** - Command to run specified as a string or an array of strings. 2327 - **Privileged** - Boolean value, runs the exec process with extended privileges. 2328 - **User** - A string value specifying the user, and optionally, group to run 2329 the exec process inside the container. Format is one of: `"user"`, 2330 `"user:group"`, `"uid"`, or `"uid:gid"`. 2331 2332 **Status codes**: 2333 2334 - **201** – no error 2335 - **404** – no such container 2336 - **409** - container is paused 2337 - **500** - server error 2338 2339 #### Exec Start 2340 2341 `POST /exec/(id)/start` 2342 2343 Starts a previously set up `exec` instance `id`. If `detach` is true, this API 2344 returns after starting the `exec` command. Otherwise, this API sets up an 2345 interactive session with the `exec` command. 2346 2347 **Example request**: 2348 2349 POST /v1.21/exec/e90e34656806/start HTTP/1.1 2350 Content-Type: application/json 2351 2352 { 2353 "Detach": false, 2354 "Tty": false 2355 } 2356 2357 **Example response**: 2358 2359 HTTP/1.1 200 OK 2360 Content-Type: application/vnd.docker.raw-stream 2361 2362 {% raw %} 2363 {{ STREAM }} 2364 {% endraw %} 2365 2366 **JSON parameters**: 2367 2368 - **Detach** - Detach from the `exec` command. 2369 - **Tty** - Boolean value to allocate a pseudo-TTY. 2370 2371 **Status codes**: 2372 2373 - **200** – no error 2374 - **404** – no such exec instance 2375 - **409** - container is paused 2376 2377 **Stream details**: 2378 2379 Similar to the stream behavior of `POST /containers/(id or name)/attach` API 2380 2381 #### Exec Resize 2382 2383 `POST /exec/(id)/resize` 2384 2385 Resizes the `tty` session used by the `exec` command `id`. The unit is number of characters. 2386 This API is valid only if `tty` was specified as part of creating and starting the `exec` command. 2387 2388 **Example request**: 2389 2390 POST /v1.21/exec/e90e34656806/resize?h=40&w=80 HTTP/1.1 2391 Content-Type: text/plain 2392 2393 **Example response**: 2394 2395 HTTP/1.1 201 Created 2396 Content-Type: text/plain 2397 2398 **Query parameters**: 2399 2400 - **h** – height of `tty` session 2401 - **w** – width 2402 2403 **Status codes**: 2404 2405 - **201** – no error 2406 - **404** – no such exec instance 2407 2408 #### Exec Inspect 2409 2410 `GET /exec/(id)/json` 2411 2412 Return low-level information about the `exec` command `id`. 2413 2414 **Example request**: 2415 2416 GET /v1.21/exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1 2417 2418 **Example response**: 2419 2420 HTTP/1.1 200 OK 2421 Content-Type: plain/text 2422 2423 { 2424 "ID" : "11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39", 2425 "Running" : false, 2426 "ExitCode" : 2, 2427 "ProcessConfig" : { 2428 "privileged" : false, 2429 "user" : "", 2430 "tty" : false, 2431 "entrypoint" : "sh", 2432 "arguments" : [ 2433 "-c", 2434 "exit 2" 2435 ] 2436 }, 2437 "OpenStdin" : false, 2438 "OpenStderr" : false, 2439 "OpenStdout" : false, 2440 "Container" : { 2441 "State" : { 2442 "Status" : "running", 2443 "Running" : true, 2444 "Paused" : false, 2445 "Restarting" : false, 2446 "OOMKilled" : false, 2447 "Pid" : 3650, 2448 "ExitCode" : 0, 2449 "Error" : "", 2450 "StartedAt" : "2014-11-17T22:26:03.717657531Z", 2451 "FinishedAt" : "0001-01-01T00:00:00Z" 2452 }, 2453 "ID" : "8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c", 2454 "Created" : "2014-11-17T22:26:03.626304998Z", 2455 "Path" : "date", 2456 "Args" : [], 2457 "Config" : { 2458 "Hostname" : "8f177a186b97", 2459 "Domainname" : "", 2460 "User" : "", 2461 "AttachStdin" : false, 2462 "AttachStdout" : false, 2463 "AttachStderr" : false, 2464 "ExposedPorts" : null, 2465 "Tty" : false, 2466 "OpenStdin" : false, 2467 "StdinOnce" : false, 2468 "Env" : [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ], 2469 "Cmd" : [ 2470 "date" 2471 ], 2472 "Image" : "ubuntu", 2473 "Volumes" : null, 2474 "WorkingDir" : "", 2475 "Entrypoint" : null, 2476 "NetworkDisabled" : false, 2477 "MacAddress" : "", 2478 "OnBuild" : null, 2479 "SecurityOpt" : null 2480 }, 2481 "Image" : "5506de2b643be1e6febbf3b8a240760c6843244c41e12aa2f60ccbb7153d17f5", 2482 "NetworkSettings" : { 2483 "Bridge": "", 2484 "SandboxID": "", 2485 "HairpinMode": false, 2486 "LinkLocalIPv6Address": "", 2487 "LinkLocalIPv6PrefixLen": 0, 2488 "Ports": null, 2489 "SandboxKey": "", 2490 "SecondaryIPAddresses": null, 2491 "SecondaryIPv6Addresses": null, 2492 "EndpointID": "", 2493 "Gateway": "", 2494 "GlobalIPv6Address": "", 2495 "GlobalIPv6PrefixLen": 0, 2496 "IPAddress": "", 2497 "IPPrefixLen": 0, 2498 "IPv6Gateway": "", 2499 "MacAddress": "", 2500 "Networks": { 2501 "bridge": { 2502 "EndpointID": "", 2503 "Gateway": "", 2504 "IPAddress": "", 2505 "IPPrefixLen": 0, 2506 "IPv6Gateway": "", 2507 "GlobalIPv6Address": "", 2508 "GlobalIPv6PrefixLen": 0, 2509 "MacAddress": "" 2510 } 2511 } 2512 }, 2513 "ResolvConfPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/resolv.conf", 2514 "HostnamePath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hostname", 2515 "HostsPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hosts", 2516 "LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log", 2517 "Name" : "/test", 2518 "Driver" : "aufs", 2519 "ExecDriver" : "native-0.2", 2520 "MountLabel" : "", 2521 "ProcessLabel" : "", 2522 "AppArmorProfile" : "", 2523 "RestartCount" : 0, 2524 "Mounts" : [] 2525 } 2526 } 2527 2528 **Status codes**: 2529 2530 - **200** – no error 2531 - **404** – no such exec instance 2532 - **500** - server error 2533 2534 ### 2.4 Volumes 2535 2536 #### List volumes 2537 2538 `GET /volumes` 2539 2540 **Example request**: 2541 2542 GET /v1.21/volumes HTTP/1.1 2543 2544 **Example response**: 2545 2546 HTTP/1.1 200 OK 2547 Content-Type: application/json 2548 2549 { 2550 "Volumes": [ 2551 { 2552 "Name": "tardis", 2553 "Driver": "local", 2554 "Mountpoint": "/var/lib/docker/volumes/tardis" 2555 } 2556 ] 2557 } 2558 2559 **Query parameters**: 2560 2561 - **filters** - JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. There is one available filter: `dangling=true` 2562 2563 **Status codes**: 2564 2565 - **200** - no error 2566 - **500** - server error 2567 2568 #### Create a volume 2569 2570 `POST /volumes/create` 2571 2572 Create a volume 2573 2574 **Example request**: 2575 2576 POST /v1.21/volumes/create HTTP/1.1 2577 Content-Type: application/json 2578 2579 { 2580 "Name": "tardis" 2581 } 2582 2583 **Example response**: 2584 2585 HTTP/1.1 201 Created 2586 Content-Type: application/json 2587 2588 { 2589 "Name": "tardis", 2590 "Driver": "local", 2591 "Mountpoint": "/var/lib/docker/volumes/tardis" 2592 } 2593 2594 **Status codes**: 2595 2596 - **201** - no error 2597 - **500** - server error 2598 2599 **JSON parameters**: 2600 2601 - **Name** - The new volume's name. If not specified, Docker generates a name. 2602 - **Driver** - Name of the volume driver to use. Defaults to `local` for the name. 2603 - **DriverOpts** - A mapping of driver options and values. These options are 2604 passed directly to the driver and are driver specific. 2605 2606 #### Inspect a volume 2607 2608 `GET /volumes/(name)` 2609 2610 Return low-level information on the volume `name` 2611 2612 **Example request**: 2613 2614 GET /volumes/tardis 2615 2616 **Example response**: 2617 2618 HTTP/1.1 200 OK 2619 Content-Type: application/json 2620 2621 { 2622 "Name": "tardis", 2623 "Driver": "local", 2624 "Mountpoint": "/var/lib/docker/volumes/tardis" 2625 } 2626 2627 **Status codes**: 2628 2629 - **200** - no error 2630 - **404** - no such volume 2631 - **500** - server error 2632 2633 #### Remove a volume 2634 2635 `DELETE /volumes/(name)` 2636 2637 Instruct the driver to remove the volume (`name`). 2638 2639 **Example request**: 2640 2641 DELETE /v1.21/volumes/tardis HTTP/1.1 2642 2643 **Example response**: 2644 2645 HTTP/1.1 204 No Content 2646 2647 **Status codes**: 2648 2649 - **204** - no error 2650 - **404** - no such volume or volume driver 2651 - **409** - volume is in use and cannot be removed 2652 - **500** - server error 2653 2654 ### 2.5 Networks 2655 2656 #### List networks 2657 2658 `GET /networks` 2659 2660 **Example request**: 2661 2662 GET /v1.21/networks HTTP/1.1 2663 2664 **Example response**: 2665 2666 ``` 2667 HTTP/1.1 200 OK 2668 Content-Type: application/json 2669 2670 [ 2671 { 2672 "Name": "bridge", 2673 "Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566", 2674 "Scope": "local", 2675 "Driver": "bridge", 2676 "IPAM": { 2677 "Driver": "default", 2678 "Config": [ 2679 { 2680 "Subnet": "172.17.0.0/16" 2681 } 2682 ] 2683 }, 2684 "Containers": { 2685 "39b69226f9d79f5634485fb236a23b2fe4e96a0a94128390a7fbbcc167065867": { 2686 "EndpointID": "ed2419a97c1d9954d05b46e462e7002ea552f216e9b136b80a7db8d98b442eda", 2687 "MacAddress": "02:42:ac:11:00:02", 2688 "IPv4Address": "172.17.0.2/16", 2689 "IPv6Address": "" 2690 } 2691 }, 2692 "Options": { 2693 "com.docker.network.bridge.default_bridge": "true", 2694 "com.docker.network.bridge.enable_icc": "true", 2695 "com.docker.network.bridge.enable_ip_masquerade": "true", 2696 "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", 2697 "com.docker.network.bridge.name": "docker0", 2698 "com.docker.network.driver.mtu": "1500" 2699 } 2700 }, 2701 { 2702 "Name": "none", 2703 "Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794", 2704 "Scope": "local", 2705 "Driver": "null", 2706 "IPAM": { 2707 "Driver": "default", 2708 "Config": [] 2709 }, 2710 "Containers": {}, 2711 "Options": {} 2712 }, 2713 { 2714 "Name": "host", 2715 "Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e", 2716 "Scope": "local", 2717 "Driver": "host", 2718 "IPAM": { 2719 "Driver": "default", 2720 "Config": [] 2721 }, 2722 "Containers": {}, 2723 "Options": {} 2724 } 2725 ] 2726 ``` 2727 2728 **Query parameters**: 2729 2730 - **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]` 2731 2732 **Status codes**: 2733 2734 - **200** - no error 2735 - **500** - server error 2736 2737 #### Inspect network 2738 2739 `GET /networks/<network-id>` 2740 2741 **Example request**: 2742 2743 GET /v1.21/networks/f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566 HTTP/1.1 2744 2745 **Example response**: 2746 2747 ``` 2748 HTTP/1.1 200 OK 2749 Content-Type: application/json 2750 2751 { 2752 "Name": "bridge", 2753 "Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566", 2754 "Scope": "local", 2755 "Driver": "bridge", 2756 "IPAM": { 2757 "Driver": "default", 2758 "Config": [ 2759 { 2760 "Subnet": "172.17.0.0/16" 2761 } 2762 ] 2763 }, 2764 "Containers": { 2765 "39b69226f9d79f5634485fb236a23b2fe4e96a0a94128390a7fbbcc167065867": { 2766 "EndpointID": "ed2419a97c1d9954d05b46e462e7002ea552f216e9b136b80a7db8d98b442eda", 2767 "MacAddress": "02:42:ac:11:00:02", 2768 "IPv4Address": "172.17.0.2/16", 2769 "IPv6Address": "" 2770 } 2771 }, 2772 "Options": { 2773 "com.docker.network.bridge.default_bridge": "true", 2774 "com.docker.network.bridge.enable_icc": "true", 2775 "com.docker.network.bridge.enable_ip_masquerade": "true", 2776 "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", 2777 "com.docker.network.bridge.name": "docker0", 2778 "com.docker.network.driver.mtu": "1500" 2779 } 2780 } 2781 ``` 2782 2783 **Status codes**: 2784 2785 - **200** - no error 2786 - **404** - network not found 2787 2788 #### Create a network 2789 2790 `POST /networks/create` 2791 2792 Create a network 2793 2794 **Example request**: 2795 2796 ``` 2797 POST /v1.21/networks/create HTTP/1.1 2798 Content-Type: application/json 2799 2800 { 2801 "Name":"isolated_nw", 2802 "CheckDuplicate":true, 2803 "Driver":"bridge", 2804 "IPAM":{ 2805 "Driver": "default", 2806 "Config":[ 2807 { 2808 "Subnet":"172.20.0.0/16", 2809 "IPRange":"172.20.10.0/24", 2810 "Gateway":"172.20.10.11" 2811 } 2812 ] 2813 } 2814 } 2815 ``` 2816 2817 **Example response**: 2818 2819 ``` 2820 HTTP/1.1 201 Created 2821 Content-Type: application/json 2822 2823 { 2824 "Id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30", 2825 "Warning": "" 2826 } 2827 ``` 2828 2829 **Status codes**: 2830 2831 - **201** - no error 2832 - **404** - plugin not found 2833 - **500** - server error 2834 2835 **JSON parameters**: 2836 2837 - **Name** - The new network's name. this is a mandatory field 2838 - **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false` 2839 - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver 2840 - **IPAM** - Optional custom IP scheme for the network 2841 - **Driver** - Name of the IPAM driver to use. Defaults to `default` driver 2842 - **Config** - List of IPAM configuration options, specified as a map: 2843 `{"Subnet": <CIDR>, "IPRange": <CIDR>, "Gateway": <IP address>, "AuxAddress": <device_name:IP address>}` 2844 - **Options** - Network specific options to be used by the drivers 2845 2846 #### Connect a container to a network 2847 2848 `POST /networks/(id)/connect` 2849 2850 Connect a container to a network 2851 2852 **Example request**: 2853 2854 ``` 2855 POST /v1.21/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1 2856 Content-Type: application/json 2857 2858 { 2859 "Container":"3613f73ba0e4" 2860 } 2861 ``` 2862 2863 **Example response**: 2864 2865 HTTP/1.1 200 OK 2866 2867 **Status codes**: 2868 2869 - **200** - no error 2870 - **404** - network or container is not found 2871 - **500** - Internal Server Error 2872 2873 **JSON parameters**: 2874 2875 - **container** - container-id/name to be connected to the network 2876 2877 #### Disconnect a container from a network 2878 2879 `POST /networks/(id)/disconnect` 2880 2881 Disconnect a container from a network 2882 2883 **Example request**: 2884 2885 ``` 2886 POST /v1.21/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1 2887 Content-Type: application/json 2888 2889 { 2890 "Container":"3613f73ba0e4" 2891 } 2892 ``` 2893 2894 **Example response**: 2895 2896 HTTP/1.1 200 OK 2897 2898 **Status codes**: 2899 2900 - **200** - no error 2901 - **404** - network or container not found 2902 - **500** - Internal Server Error 2903 2904 **JSON parameters**: 2905 2906 - **Container** - container-id/name to be disconnected from a network 2907 2908 #### Remove a network 2909 2910 `DELETE /networks/(id)` 2911 2912 Instruct the driver to remove the network (`id`). 2913 2914 **Example request**: 2915 2916 DELETE /v1.21/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30 HTTP/1.1 2917 2918 **Example response**: 2919 2920 HTTP/1.1 200 OK 2921 2922 **Status codes**: 2923 2924 - **200** - no error 2925 - **404** - no such network 2926 - **500** - server error 2927 2928 ## 3. Going further 2929 2930 ### 3.1 Inside `docker run` 2931 2932 As an example, the `docker run` command line makes the following API calls: 2933 2934 - Create the container 2935 2936 - If the status code is 404, it means the image doesn't exist: 2937 - Try to pull it. 2938 - Then, retry to create the container. 2939 2940 - Start the container. 2941 2942 - If you are not in detached mode: 2943 - Attach to the container, using `logs=1` (to have `stdout` and 2944 `stderr` from the container's start) and `stream=1` 2945 2946 - If in detached mode or only `stdin` is attached, display the container's id. 2947 2948 ### 3.2 Hijacking 2949 2950 In this version of the API, `/attach`, uses hijacking to transport `stdin`, 2951 `stdout`, and `stderr` on the same socket. 2952 2953 To hint potential proxies about connection hijacking, Docker client sends 2954 connection upgrade headers similarly to websocket. 2955 2956 Upgrade: tcp 2957 Connection: Upgrade 2958 2959 When Docker daemon detects the `Upgrade` header, it switches its status code 2960 from **200 OK** to **101 UPGRADED** and resends the same headers. 2961 2962 2963 ### 3.3 CORS Requests 2964 2965 To set cross origin requests to the Engine API please give values to 2966 `--api-cors-header` when running Docker in daemon mode. Set * (asterisk) allows all, 2967 default or blank means CORS disabled 2968 2969 $ dockerd -H="192.168.1.9:2375" --api-cors-header="http://foo.bar"