github.com/yogeshlonkar/moby@v1.13.2-0.20201203103638-c0b64beaea94/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 - **link** - 1/True/true or 0/False/false, Remove the specified 1189 link associated to the container. Default `false`. 1190 1191 **Status codes**: 1192 1193 - **204** – no error 1194 - **400** – bad parameter 1195 - **404** – no such container 1196 - **409** – conflict 1197 - **500** – server error 1198 1199 #### Copy files or folders from a container 1200 1201 `POST /containers/(id or name)/copy` 1202 1203 Copy files or folders of container `id` 1204 1205 **Deprecated** in favor of the `archive` endpoint below. 1206 1207 **Example request**: 1208 1209 POST /v1.21/containers/4fa6e0f0c678/copy HTTP/1.1 1210 Content-Type: application/json 1211 1212 { 1213 "Resource": "test.txt" 1214 } 1215 1216 **Example response**: 1217 1218 HTTP/1.1 200 OK 1219 Content-Type: application/x-tar 1220 1221 {% raw %} 1222 {{ TAR STREAM }} 1223 {% endraw %} 1224 1225 **Status codes**: 1226 1227 - **200** – no error 1228 - **404** – no such container 1229 - **500** – server error 1230 1231 #### Retrieving information about files and folders in a container 1232 1233 `HEAD /containers/(id or name)/archive` 1234 1235 See the description of the `X-Docker-Container-Path-Stat` header in the 1236 following section. 1237 1238 #### Get an archive of a filesystem resource in a container 1239 1240 `GET /containers/(id or name)/archive` 1241 1242 Get a tar archive of a resource in the filesystem of container `id`. 1243 1244 **Query parameters**: 1245 1246 - **path** - resource in the container's filesystem to archive. Required. 1247 1248 If not an absolute path, it is relative to the container's root directory. 1249 The resource specified by **path** must exist. To assert that the resource 1250 is expected to be a directory, **path** should end in `/` or `/.` 1251 (assuming a path separator of `/`). If **path** ends in `/.` then this 1252 indicates that only the contents of the **path** directory should be 1253 copied. A symlink is always resolved to its target. 1254 1255 > **Note**: It is not possible to copy certain system files such as resources 1256 > under `/proc`, `/sys`, `/dev`, and mounts created by the user in the 1257 > container. 1258 1259 **Example request**: 1260 1261 GET /v1.21/containers/8cce319429b2/archive?path=/root HTTP/1.1 1262 1263 **Example response**: 1264 1265 HTTP/1.1 200 OK 1266 Content-Type: application/x-tar 1267 X-Docker-Container-Path-Stat: eyJuYW1lIjoicm9vdCIsInNpemUiOjQwOTYsIm1vZGUiOjIxNDc0ODQwOTYsIm10aW1lIjoiMjAxNC0wMi0yN1QyMDo1MToyM1oiLCJsaW5rVGFyZ2V0IjoiIn0= 1268 1269 {% raw %} 1270 {{ TAR STREAM }} 1271 {% endraw %} 1272 1273 On success, a response header `X-Docker-Container-Path-Stat` will be set to a 1274 base64-encoded JSON object containing some filesystem header information about 1275 the archived resource. The above example value would decode to the following 1276 JSON object (whitespace added for readability): 1277 1278 ```json 1279 { 1280 "name": "root", 1281 "size": 4096, 1282 "mode": 2147484096, 1283 "mtime": "2014-02-27T20:51:23Z", 1284 "linkTarget": "" 1285 } 1286 ``` 1287 1288 A `HEAD` request can also be made to this endpoint if only this information is 1289 desired. 1290 1291 **Status codes**: 1292 1293 - **200** - success, returns archive of copied resource 1294 - **400** - client error, bad parameter, details in JSON response body, one of: 1295 - must specify path parameter (**path** cannot be empty) 1296 - not a directory (**path** was asserted to be a directory but exists as a 1297 file) 1298 - **404** - client error, resource not found, one of: 1299 – no such container (container `id` does not exist) 1300 - no such file or directory (**path** does not exist) 1301 - **500** - server error 1302 1303 #### Extract an archive of files or folders to a directory in a container 1304 1305 `PUT /containers/(id or name)/archive` 1306 1307 Upload a tar archive to be extracted to a path in the filesystem of container 1308 `id`. 1309 1310 **Query parameters**: 1311 1312 - **path** - path to a directory in the container 1313 to extract the archive's contents into. Required. 1314 1315 If not an absolute path, it is relative to the container's root directory. 1316 The **path** resource must exist. 1317 - **noOverwriteDirNonDir** - If "1", "true", or "True" then it will be an error 1318 if unpacking the given content would cause an existing directory to be 1319 replaced with a non-directory and vice versa. 1320 1321 **Example request**: 1322 1323 PUT /v1.21/containers/8cce319429b2/archive?path=/vol1 HTTP/1.1 1324 Content-Type: application/x-tar 1325 1326 {% raw %} 1327 {{ TAR STREAM }} 1328 {% endraw %} 1329 1330 **Example response**: 1331 1332 HTTP/1.1 200 OK 1333 1334 **Status codes**: 1335 1336 - **200** – the content was extracted successfully 1337 - **400** - client error, bad parameter, details in JSON response body, one of: 1338 - must specify path parameter (**path** cannot be empty) 1339 - not a directory (**path** should be a directory but exists as a file) 1340 - unable to overwrite existing directory with non-directory 1341 (if **noOverwriteDirNonDir**) 1342 - unable to overwrite existing non-directory with directory 1343 (if **noOverwriteDirNonDir**) 1344 - **403** - client error, permission denied, the volume 1345 or container rootfs is marked as read-only. 1346 - **404** - client error, resource not found, one of: 1347 – no such container (container `id` does not exist) 1348 - no such file or directory (**path** resource does not exist) 1349 - **500** – server error 1350 1351 ### 2.2 Images 1352 1353 #### List Images 1354 1355 `GET /images/json` 1356 1357 **Example request**: 1358 1359 GET /v1.21/images/json?all=0 HTTP/1.1 1360 1361 **Example response**: 1362 1363 HTTP/1.1 200 OK 1364 Content-Type: application/json 1365 1366 [ 1367 { 1368 "RepoTags": [ 1369 "ubuntu:12.04", 1370 "ubuntu:precise", 1371 "ubuntu:latest" 1372 ], 1373 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 1374 "Created": 1365714795, 1375 "Size": 131506275, 1376 "VirtualSize": 131506275, 1377 "Labels": {} 1378 }, 1379 { 1380 "RepoTags": [ 1381 "ubuntu:12.10", 1382 "ubuntu:quantal" 1383 ], 1384 "ParentId": "27cf784147099545", 1385 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 1386 "Created": 1364102658, 1387 "Size": 24653, 1388 "VirtualSize": 180116135, 1389 "Labels": { 1390 "com.example.version": "v1" 1391 } 1392 } 1393 ] 1394 1395 **Example request, with digest information**: 1396 1397 GET /v1.21/images/json?digests=1 HTTP/1.1 1398 1399 **Example response, with digest information**: 1400 1401 HTTP/1.1 200 OK 1402 Content-Type: application/json 1403 1404 [ 1405 { 1406 "Created": 1420064636, 1407 "Id": "4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125", 1408 "ParentId": "ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2", 1409 "RepoDigests": [ 1410 "localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf" 1411 ], 1412 "RepoTags": [ 1413 "localhost:5000/test/busybox:latest", 1414 "playdate:latest" 1415 ], 1416 "Size": 0, 1417 "VirtualSize": 2429728, 1418 "Labels": {} 1419 } 1420 ] 1421 1422 The response shows a single image `Id` associated with two repositories 1423 (`RepoTags`): `localhost:5000/test/busybox`: and `playdate`. A caller can use 1424 either of the `RepoTags` values `localhost:5000/test/busybox:latest` or 1425 `playdate:latest` to reference the image. 1426 1427 You can also use `RepoDigests` values to reference an image. In this response, 1428 the array has only one reference and that is to the 1429 `localhost:5000/test/busybox` repository; the `playdate` repository has no 1430 digest. You can reference this digest using the value: 1431 `localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d...` 1432 1433 See the `docker run` and `docker build` commands for examples of digest and tag 1434 references on the command line. 1435 1436 **Query parameters**: 1437 1438 - **all** – 1/True/true or 0/False/false, default false 1439 - **filters** – a JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters: 1440 - `dangling=true` 1441 - `label=key` or `label="key=value"` of an image label 1442 - **filter** - only return images with the specified name 1443 1444 #### Build image from a Dockerfile 1445 1446 `POST /build` 1447 1448 Build an image from a Dockerfile 1449 1450 **Example request**: 1451 1452 POST /v1.21/build HTTP/1.1 1453 1454 {% raw %} 1455 {{ TAR STREAM }} 1456 {% endraw %} 1457 1458 **Example response**: 1459 1460 HTTP/1.1 200 OK 1461 Content-Type: application/json 1462 1463 {"stream": "Step 1/5..."} 1464 {"stream": "..."} 1465 {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} 1466 1467 The input stream must be a `tar` archive compressed with one of the 1468 following algorithms: `identity` (no compression), `gzip`, `bzip2`, `xz`. 1469 1470 The archive must include a build instructions file, typically called 1471 `Dockerfile` at the archive's root. The `dockerfile` parameter may be 1472 used to specify a different build instructions file. To do this, its value must be 1473 the path to the alternate build instructions file to use. 1474 1475 The archive may include any number of other files, 1476 which are accessible in the build context (See the [*ADD build 1477 command*](../reference/builder.md#add)). 1478 1479 The Docker daemon performs a preliminary validation of the `Dockerfile` before 1480 starting the build, and returns an error if the syntax is incorrect. After that, 1481 each instruction is run one-by-one until the ID of the new image is output. 1482 1483 The build is canceled if the client drops the connection by quitting 1484 or being killed. 1485 1486 **Query parameters**: 1487 1488 - **dockerfile** - Path within the build context to the `Dockerfile`. This is 1489 ignored if `remote` is specified and points to an external `Dockerfile`. 1490 - **t** – A name and optional tag to apply to the image in the `name:tag` format. 1491 If you omit the `tag` the default `latest` value is assumed. 1492 You can provide one or more `t` parameters. 1493 - **remote** – A Git repository URI or HTTP/HTTPS context URI. If the 1494 URI points to a single text file, the file's contents are placed into 1495 a file called `Dockerfile` and the image is built from that file. If 1496 the URI points to a tarball, the file is downloaded by the daemon and 1497 the contents therein used as the context for the build. If the URI 1498 points to a tarball and the `dockerfile` parameter is also specified, 1499 there must be a file with the corresponding path inside the tarball. 1500 - **q** – Suppress verbose build output. 1501 - **nocache** – Do not use the cache when building the image. 1502 - **pull** - Attempt to pull the image even if an older image exists locally. 1503 - **rm** - Remove intermediate containers after a successful build (default behavior). 1504 - **forcerm** - Always remove intermediate containers (includes `rm`). 1505 - **memory** - Set memory limit for build. 1506 - **memswap** - Total memory (memory + swap), `-1` to enable unlimited swap. 1507 - **cpushares** - CPU shares (relative weight). 1508 - **cpusetcpus** - CPUs in which to allow execution (e.g., `0-3`, `0,1`). 1509 - **cpuperiod** - The length of a CPU period in microseconds. 1510 - **cpuquota** - Microseconds of CPU time that the container can get in a CPU period. 1511 - **buildargs** – JSON map of string pairs for build-time variables. Users pass 1512 these values at build-time. Docker uses the `buildargs` as the environment 1513 context for command(s) run via the Dockerfile's `RUN` instruction or for 1514 variable expansion in other Dockerfile instructions. This is not meant for 1515 passing secret values. [Read more about the buildargs instruction](../reference/builder.md#arg) 1516 1517 **Request Headers**: 1518 1519 - **Content-type** – Set to `"application/tar"`. 1520 - **X-Registry-Config** – A base64-url-safe-encoded Registry Auth Config JSON 1521 object with the following structure: 1522 1523 { 1524 "docker.example.com": { 1525 "username": "janedoe", 1526 "password": "hunter2" 1527 }, 1528 "https://index.docker.io/v1/": { 1529 "username": "mobydock", 1530 "password": "conta1n3rize14" 1531 } 1532 } 1533 1534 This object maps the hostname of a registry to an object containing the 1535 "username" and "password" for that registry. Multiple registries may 1536 be specified as the build may be based on an image requiring 1537 authentication to pull from any arbitrary registry. Only the registry 1538 domain name (and port if not the default "443") are required. However 1539 (for legacy reasons) the "official" Docker, Inc. hosted registry must 1540 be specified with both a "https://" prefix and a "/v1/" suffix even 1541 though Docker will prefer to use the v2 registry API. 1542 1543 **Status codes**: 1544 1545 - **200** – no error 1546 - **500** – server error 1547 1548 #### Create an image 1549 1550 `POST /images/create` 1551 1552 Create an image either by pulling it from the registry or by importing it 1553 1554 **Example request**: 1555 1556 POST /v1.21/images/create?fromImage=busybox&tag=latest HTTP/1.1 1557 1558 **Example response**: 1559 1560 HTTP/1.1 200 OK 1561 Content-Type: application/json 1562 1563 {"status": "Pulling..."} 1564 {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} 1565 {"error": "Invalid..."} 1566 ... 1567 1568 When using this endpoint to pull an image from the registry, the 1569 `X-Registry-Auth` header can be used to include 1570 a base64-encoded AuthConfig object. 1571 1572 **Query parameters**: 1573 1574 - **fromImage** – Name of the image to pull. The name may include a tag or 1575 digest. This parameter may only be used when pulling an image. 1576 - **fromSrc** – Source to import. The value may be a URL from which the image 1577 can be retrieved or `-` to read the image from the request body. 1578 This parameter may only be used when importing an image. 1579 - **repo** – Repository name given to an image when it is imported. 1580 The repo may include a tag. This parameter may only be used when importing 1581 an image. 1582 - **tag** – Tag or digest. If empty when pulling an image, this causes all tags 1583 for the given image to be pulled. 1584 1585 **Request Headers**: 1586 1587 - **X-Registry-Auth** – base64-encoded AuthConfig object 1588 1589 **Status codes**: 1590 1591 - **200** – no error 1592 - **404** - repository does not exist or no read access 1593 - **500** – server error 1594 1595 1596 1597 #### Inspect an image 1598 1599 `GET /images/(name)/json` 1600 1601 Return low-level information on the image `name` 1602 1603 **Example request**: 1604 1605 GET /v1.21/images/example/json HTTP/1.1 1606 1607 **Example response**: 1608 1609 HTTP/1.1 200 OK 1610 Content-Type: application/json 1611 1612 { 1613 "Id" : "85f05633ddc1c50679be2b16a0479ab6f7637f8884e0cfe0f4d20e1ebb3d6e7c", 1614 "Container" : "cb91e48a60d01f1e27028b4fc6819f4f290b3cf12496c8176ec714d0d390984a", 1615 "Comment" : "", 1616 "Os" : "linux", 1617 "Architecture" : "amd64", 1618 "Parent" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1619 "ContainerConfig" : { 1620 "Tty" : false, 1621 "Hostname" : "e611e15f9c9d", 1622 "Volumes" : null, 1623 "Domainname" : "", 1624 "AttachStdout" : false, 1625 "PublishService" : "", 1626 "AttachStdin" : false, 1627 "OpenStdin" : false, 1628 "StdinOnce" : false, 1629 "NetworkDisabled" : false, 1630 "OnBuild" : [], 1631 "Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1632 "User" : "", 1633 "WorkingDir" : "", 1634 "Entrypoint" : null, 1635 "MacAddress" : "", 1636 "AttachStderr" : false, 1637 "Labels" : { 1638 "com.example.license" : "GPL", 1639 "com.example.version" : "1.0", 1640 "com.example.vendor" : "Acme" 1641 }, 1642 "Env" : [ 1643 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 1644 ], 1645 "ExposedPorts" : null, 1646 "Cmd" : [ 1647 "/bin/sh", 1648 "-c", 1649 "#(nop) LABEL com.example.vendor=Acme com.example.license=GPL com.example.version=1.0" 1650 ] 1651 }, 1652 "DockerVersion" : "1.9.0-dev", 1653 "VirtualSize" : 188359297, 1654 "Size" : 0, 1655 "Author" : "", 1656 "Created" : "2015-09-10T08:30:53.26995814Z", 1657 "GraphDriver" : { 1658 "Name" : "aufs", 1659 "Data" : null 1660 }, 1661 "RepoDigests" : [ 1662 "localhost:5000/test/busybox/example@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf" 1663 ], 1664 "RepoTags" : [ 1665 "example:1.0", 1666 "example:latest", 1667 "example:stable" 1668 ], 1669 "Config" : { 1670 "Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1671 "NetworkDisabled" : false, 1672 "OnBuild" : [], 1673 "StdinOnce" : false, 1674 "PublishService" : "", 1675 "AttachStdin" : false, 1676 "OpenStdin" : false, 1677 "Domainname" : "", 1678 "AttachStdout" : false, 1679 "Tty" : false, 1680 "Hostname" : "e611e15f9c9d", 1681 "Volumes" : null, 1682 "Cmd" : [ 1683 "/bin/bash" 1684 ], 1685 "ExposedPorts" : null, 1686 "Env" : [ 1687 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 1688 ], 1689 "Labels" : { 1690 "com.example.vendor" : "Acme", 1691 "com.example.version" : "1.0", 1692 "com.example.license" : "GPL" 1693 }, 1694 "Entrypoint" : null, 1695 "MacAddress" : "", 1696 "AttachStderr" : false, 1697 "WorkingDir" : "", 1698 "User" : "" 1699 } 1700 } 1701 1702 **Status codes**: 1703 1704 - **200** – no error 1705 - **404** – no such image 1706 - **500** – server error 1707 1708 #### Get the history of an image 1709 1710 `GET /images/(name)/history` 1711 1712 Return the history of the image `name` 1713 1714 **Example request**: 1715 1716 GET /v1.21/images/ubuntu/history HTTP/1.1 1717 1718 **Example response**: 1719 1720 HTTP/1.1 200 OK 1721 Content-Type: application/json 1722 1723 [ 1724 { 1725 "Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710", 1726 "Created": 1398108230, 1727 "CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /", 1728 "Tags": [ 1729 "ubuntu:lucid", 1730 "ubuntu:10.04" 1731 ], 1732 "Size": 182964289, 1733 "Comment": "" 1734 }, 1735 { 1736 "Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8", 1737 "Created": 1398108222, 1738 "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/", 1739 "Tags": null, 1740 "Size": 0, 1741 "Comment": "" 1742 }, 1743 { 1744 "Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158", 1745 "Created": 1371157430, 1746 "CreatedBy": "", 1747 "Tags": [ 1748 "scratch12:latest", 1749 "scratch:latest" 1750 ], 1751 "Size": 0, 1752 "Comment": "Imported from -" 1753 } 1754 ] 1755 1756 **Status codes**: 1757 1758 - **200** – no error 1759 - **404** – no such image 1760 - **500** – server error 1761 1762 #### Push an image on the registry 1763 1764 `POST /images/(name)/push` 1765 1766 Push the image `name` on the registry 1767 1768 **Example request**: 1769 1770 POST /v1.21/images/test/push HTTP/1.1 1771 1772 **Example response**: 1773 1774 HTTP/1.1 200 OK 1775 Content-Type: application/json 1776 1777 {"status": "Pushing..."} 1778 {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} 1779 {"error": "Invalid..."} 1780 ... 1781 1782 If you wish to push an image on to a private registry, that image must already have a tag 1783 into a repository which references that registry `hostname` and `port`. This repository name should 1784 then be used in the URL. This duplicates the command line's flow. 1785 1786 **Example request**: 1787 1788 POST /v1.21/images/registry.acme.com:5000/test/push HTTP/1.1 1789 1790 1791 **Query parameters**: 1792 1793 - **tag** – The tag to associate with the image on the registry. This is optional. 1794 1795 **Request Headers**: 1796 1797 - **X-Registry-Auth** – base64-encoded AuthConfig object. 1798 1799 **Status codes**: 1800 1801 - **200** – no error 1802 - **404** – no such image 1803 - **500** – server error 1804 1805 #### Tag an image into a repository 1806 1807 `POST /images/(name)/tag` 1808 1809 Tag the image `name` into a repository 1810 1811 **Example request**: 1812 1813 POST /v1.21/images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 1814 1815 **Example response**: 1816 1817 HTTP/1.1 201 Created 1818 1819 **Query parameters**: 1820 1821 - **repo** – The repository to tag in 1822 - **force** – 1/True/true or 0/False/false, default false 1823 - **tag** - The new tag name 1824 1825 **Status codes**: 1826 1827 - **201** – no error 1828 - **400** – bad parameter 1829 - **404** – no such image 1830 - **409** – conflict 1831 - **500** – server error 1832 1833 #### Remove an image 1834 1835 `DELETE /images/(name)` 1836 1837 Remove the image `name` from the filesystem 1838 1839 **Example request**: 1840 1841 DELETE /v1.21/images/test HTTP/1.1 1842 1843 **Example response**: 1844 1845 HTTP/1.1 200 OK 1846 Content-type: application/json 1847 1848 [ 1849 {"Untagged": "3e2f21a89f"}, 1850 {"Deleted": "3e2f21a89f"}, 1851 {"Deleted": "53b4f83ac9"} 1852 ] 1853 1854 **Query parameters**: 1855 1856 - **force** – 1/True/true or 0/False/false, default false 1857 - **noprune** – 1/True/true or 0/False/false, default false 1858 1859 **Status codes**: 1860 1861 - **200** – no error 1862 - **404** – no such image 1863 - **409** – conflict 1864 - **500** – server error 1865 1866 #### Search images 1867 1868 `GET /images/search` 1869 1870 Search for an image on [Docker Hub](https://hub.docker.com). 1871 1872 > **Note**: 1873 > The response keys have changed from API v1.6 to reflect the JSON 1874 > sent by the registry server to the docker daemon's request. 1875 1876 **Example request**: 1877 1878 GET /v1.21/images/search?term=sshd HTTP/1.1 1879 1880 **Example response**: 1881 1882 HTTP/1.1 200 OK 1883 Content-Type: application/json 1884 1885 [ 1886 { 1887 "description": "", 1888 "is_official": false, 1889 "is_automated": false, 1890 "name": "wma55/u1210sshd", 1891 "star_count": 0 1892 }, 1893 { 1894 "description": "", 1895 "is_official": false, 1896 "is_automated": false, 1897 "name": "jdswinbank/sshd", 1898 "star_count": 0 1899 }, 1900 { 1901 "description": "", 1902 "is_official": false, 1903 "is_automated": false, 1904 "name": "vgauthier/sshd", 1905 "star_count": 0 1906 } 1907 ... 1908 ] 1909 1910 **Query parameters**: 1911 1912 - **term** – term to search 1913 1914 **Status codes**: 1915 1916 - **200** – no error 1917 - **500** – server error 1918 1919 ### 2.3 Misc 1920 1921 #### Check auth configuration 1922 1923 `POST /auth` 1924 1925 Get the default username and email 1926 1927 **Example request**: 1928 1929 POST /v1.21/auth HTTP/1.1 1930 Content-Type: application/json 1931 1932 { 1933 "username": "hannibal", 1934 "password": "xxxx", 1935 "email": "hannibal@a-team.com", 1936 "serveraddress": "https://index.docker.io/v1/" 1937 } 1938 1939 **Example response**: 1940 1941 HTTP/1.1 200 OK 1942 1943 **Status codes**: 1944 1945 - **200** – no error 1946 - **204** – no error 1947 - **500** – server error 1948 1949 #### Display system-wide information 1950 1951 `GET /info` 1952 1953 Display system-wide information 1954 1955 **Example request**: 1956 1957 GET /v1.21/info HTTP/1.1 1958 1959 **Example response**: 1960 1961 HTTP/1.1 200 OK 1962 Content-Type: application/json 1963 1964 { 1965 "ClusterStore": "etcd://localhost:2379", 1966 "Containers": 11, 1967 "CpuCfsPeriod": true, 1968 "CpuCfsQuota": true, 1969 "Debug": false, 1970 "DockerRootDir": "/var/lib/docker", 1971 "Driver": "btrfs", 1972 "DriverStatus": [[""]], 1973 "ExecutionDriver": "native-0.1", 1974 "ExperimentalBuild": false, 1975 "HttpProxy": "http://test:test@localhost:8080", 1976 "HttpsProxy": "https://test:test@localhost:8080", 1977 "ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS", 1978 "IPv4Forwarding": true, 1979 "Images": 16, 1980 "IndexServerAddress": "https://index.docker.io/v1/", 1981 "InitPath": "/usr/bin/docker", 1982 "InitSha1": "", 1983 "KernelVersion": "3.12.0-1-amd64", 1984 "Labels": [ 1985 "storage=ssd" 1986 ], 1987 "MemTotal": 2099236864, 1988 "MemoryLimit": true, 1989 "NCPU": 1, 1990 "NEventsListener": 0, 1991 "NFd": 11, 1992 "NGoroutines": 21, 1993 "Name": "prod-server-42", 1994 "NoProxy": "9.81.1.160", 1995 "OomKillDisable": true, 1996 "OperatingSystem": "Boot2Docker", 1997 "RegistryConfig": { 1998 "IndexConfigs": { 1999 "docker.io": { 2000 "Mirrors": null, 2001 "Name": "docker.io", 2002 "Official": true, 2003 "Secure": true 2004 } 2005 }, 2006 "InsecureRegistryCIDRs": [ 2007 "127.0.0.0/8" 2008 ] 2009 }, 2010 "ServerVersion": "1.9.0", 2011 "SwapLimit": false, 2012 "SystemTime": "2015-03-10T11:11:23.730591467-07:00" 2013 } 2014 2015 **Status codes**: 2016 2017 - **200** – no error 2018 - **500** – server error 2019 2020 #### Show the docker version information 2021 2022 `GET /version` 2023 2024 Show the docker version information 2025 2026 **Example request**: 2027 2028 GET /v1.21/version HTTP/1.1 2029 2030 **Example response**: 2031 2032 HTTP/1.1 200 OK 2033 Content-Type: application/json 2034 2035 { 2036 "Version": "1.5.0", 2037 "Os": "linux", 2038 "KernelVersion": "3.18.5-tinycore64", 2039 "GoVersion": "go1.4.1", 2040 "GitCommit": "a8a31ef", 2041 "Arch": "amd64", 2042 "ApiVersion": "1.20", 2043 "Experimental": false 2044 } 2045 2046 **Status codes**: 2047 2048 - **200** – no error 2049 - **500** – server error 2050 2051 #### Ping the docker server 2052 2053 `GET /_ping` 2054 2055 Ping the docker server 2056 2057 **Example request**: 2058 2059 GET /v1.21/_ping HTTP/1.1 2060 2061 **Example response**: 2062 2063 HTTP/1.1 200 OK 2064 Content-Type: text/plain 2065 2066 OK 2067 2068 **Status codes**: 2069 2070 - **200** - no error 2071 - **500** - server error 2072 2073 #### Create a new image from a container's changes 2074 2075 `POST /commit` 2076 2077 Create a new image from a container's changes 2078 2079 **Example request**: 2080 2081 POST /v1.21/commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 2082 Content-Type: application/json 2083 2084 { 2085 "Hostname": "", 2086 "Domainname": "", 2087 "User": "", 2088 "AttachStdin": false, 2089 "AttachStdout": true, 2090 "AttachStderr": true, 2091 "Tty": false, 2092 "OpenStdin": false, 2093 "StdinOnce": false, 2094 "Env": null, 2095 "Cmd": [ 2096 "date" 2097 ], 2098 "Mounts": [ 2099 { 2100 "Source": "/data", 2101 "Destination": "/data", 2102 "Mode": "ro,Z", 2103 "RW": false 2104 } 2105 ], 2106 "Labels": { 2107 "key1": "value1", 2108 "key2": "value2" 2109 }, 2110 "WorkingDir": "", 2111 "NetworkDisabled": false, 2112 "ExposedPorts": { 2113 "22/tcp": {} 2114 } 2115 } 2116 2117 **Example response**: 2118 2119 HTTP/1.1 201 Created 2120 Content-Type: application/json 2121 2122 {"Id": "596069db4bf5"} 2123 2124 **JSON parameters**: 2125 2126 - **config** - the container's configuration 2127 2128 **Query parameters**: 2129 2130 - **container** – source container 2131 - **repo** – repository 2132 - **tag** – tag 2133 - **comment** – commit message 2134 - **author** – author (e.g., "John Hannibal Smith 2135 <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") 2136 - **pause** – 1/True/true or 0/False/false, whether to pause the container before committing 2137 - **changes** – Dockerfile instructions to apply while committing 2138 2139 **Status codes**: 2140 2141 - **201** – no error 2142 - **404** – no such container 2143 - **500** – server error 2144 2145 #### Monitor Docker's events 2146 2147 `GET /events` 2148 2149 Get container events from docker, in real time via streaming. 2150 2151 Docker containers report the following events: 2152 2153 attach, commit, copy, create, destroy, die, exec_create, exec_start, export, kill, oom, pause, rename, resize, restart, start, stop, top, unpause 2154 2155 Docker images report the following events: 2156 2157 delete, import, pull, push, tag, untag 2158 2159 **Example request**: 2160 2161 GET /v1.21/events?since=1374067924 2162 2163 **Example response**: 2164 2165 HTTP/1.1 200 OK 2166 Content-Type: application/json 2167 2168 {"status":"pull","id":"busybox:latest","time":1442421700,"timeNano":1442421700598988358} 2169 {"status":"create","id":"5745704abe9caa5","from":"busybox","time":1442421716,"timeNano":1442421716853979870} 2170 {"status":"attach","id":"5745704abe9caa5","from":"busybox","time":1442421716,"timeNano":1442421716894759198} 2171 {"status":"start","id":"5745704abe9caa5","from":"busybox","time":1442421716,"timeNano":1442421716983607193} 2172 2173 **Query parameters**: 2174 2175 - **since** – Timestamp. Show all events created since timestamp and then stream 2176 - **until** – Timestamp. Show events created until given timestamp and stop streaming 2177 - **filters** – A json encoded value of the filters (a map[string][]string) to process on the event list. Available filters: 2178 - `container=<string>`; -- container to filter 2179 - `event=<string>`; -- event to filter 2180 - `image=<string>`; -- image to filter 2181 - `label=<string>`; -- image and container label to filter 2182 2183 **Status codes**: 2184 2185 - **200** – no error 2186 - **500** – server error 2187 2188 #### Get a tarball containing all images in a repository 2189 2190 `GET /images/(name)/get` 2191 2192 Get a tarball containing all images and metadata for the repository specified 2193 by `name`. 2194 2195 If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image 2196 (and its parents) are returned. If `name` is an image ID, similarly only that 2197 image (and its parents) are returned, but with the exclusion of the 2198 'repositories' file in the tarball, as there were no image names referenced. 2199 2200 See the [image tarball format](#image-tarball-format) for more details. 2201 2202 **Example request** 2203 2204 GET /v1.21/images/ubuntu/get 2205 2206 **Example response**: 2207 2208 HTTP/1.1 200 OK 2209 Content-Type: application/x-tar 2210 2211 Binary data stream 2212 2213 **Status codes**: 2214 2215 - **200** – no error 2216 - **500** – server error 2217 2218 #### Get a tarball containing all images 2219 2220 `GET /images/get` 2221 2222 Get a tarball containing all images and metadata for one or more repositories. 2223 2224 For each value of the `names` parameter: if it is a specific name and tag (e.g. 2225 `ubuntu:latest`), then only that image (and its parents) are returned; if it is 2226 an image ID, similarly only that image (and its parents) are returned and there 2227 would be no names referenced in the 'repositories' file for this image ID. 2228 2229 See the [image tarball format](#image-tarball-format) for more details. 2230 2231 **Example request** 2232 2233 GET /v1.21/images/get?names=myname%2Fmyapp%3Alatest&names=busybox 2234 2235 **Example response**: 2236 2237 HTTP/1.1 200 OK 2238 Content-Type: application/x-tar 2239 2240 Binary data stream 2241 2242 **Status codes**: 2243 2244 - **200** – no error 2245 - **500** – server error 2246 2247 #### Load a tarball with a set of images and tags into docker 2248 2249 `POST /images/load` 2250 2251 Load a set of images and tags into a Docker repository. 2252 See the [image tarball format](#image-tarball-format) for more details. 2253 2254 **Example request** 2255 2256 POST /v1.21/images/load 2257 Content-Type: application/x-tar 2258 2259 Tarball in body 2260 2261 **Example response**: 2262 2263 HTTP/1.1 200 OK 2264 2265 **Status codes**: 2266 2267 - **200** – no error 2268 - **500** – server error 2269 2270 #### Image tarball format 2271 2272 An image tarball contains one directory per image layer (named using its long ID), 2273 each containing these files: 2274 2275 - `VERSION`: currently `1.0` - the file format version 2276 - `json`: detailed layer information, similar to `docker inspect layer_id` 2277 - `layer.tar`: A tarfile containing the filesystem changes in this layer 2278 2279 The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories 2280 for storing attribute changes and deletions. 2281 2282 If the tarball defines a repository, the tarball should also include a `repositories` file at 2283 the root that contains a list of repository and tag names mapped to layer IDs. 2284 2285 ``` 2286 {"hello-world": 2287 {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} 2288 } 2289 ``` 2290 2291 #### Exec Create 2292 2293 `POST /containers/(id or name)/exec` 2294 2295 Sets up an exec instance in a running container `id` 2296 2297 **Example request**: 2298 2299 POST /v1.21/containers/e90e34656806/exec HTTP/1.1 2300 Content-Type: application/json 2301 2302 { 2303 "AttachStdin": true, 2304 "AttachStdout": true, 2305 "AttachStderr": true, 2306 "Cmd": ["sh"], 2307 "Privileged": true, 2308 "Tty": true, 2309 "User": "123:456" 2310 } 2311 2312 **Example response**: 2313 2314 HTTP/1.1 201 Created 2315 Content-Type: application/json 2316 2317 { 2318 "Id": "f90e34656806", 2319 "Warnings":[] 2320 } 2321 2322 **JSON parameters**: 2323 2324 - **AttachStdin** - Boolean value, attaches to `stdin` of the `exec` command. 2325 - **AttachStdout** - Boolean value, attaches to `stdout` of the `exec` command. 2326 - **AttachStderr** - Boolean value, attaches to `stderr` of the `exec` command. 2327 - **Tty** - Boolean value to allocate a pseudo-TTY. 2328 - **Cmd** - Command to run specified as a string or an array of strings. 2329 - **Privileged** - Boolean value, runs the exec process with extended privileges. 2330 - **User** - A string value specifying the user, and optionally, group to run 2331 the exec process inside the container. Format is one of: `"user"`, 2332 `"user:group"`, `"uid"`, or `"uid:gid"`. 2333 2334 **Status codes**: 2335 2336 - **201** – no error 2337 - **404** – no such container 2338 - **409** - container is paused 2339 - **500** - server error 2340 2341 #### Exec Start 2342 2343 `POST /exec/(id)/start` 2344 2345 Starts a previously set up `exec` instance `id`. If `detach` is true, this API 2346 returns after starting the `exec` command. Otherwise, this API sets up an 2347 interactive session with the `exec` command. 2348 2349 **Example request**: 2350 2351 POST /v1.21/exec/e90e34656806/start HTTP/1.1 2352 Content-Type: application/json 2353 2354 { 2355 "Detach": false, 2356 "Tty": false 2357 } 2358 2359 **Example response**: 2360 2361 HTTP/1.1 200 OK 2362 Content-Type: application/vnd.docker.raw-stream 2363 2364 {% raw %} 2365 {{ STREAM }} 2366 {% endraw %} 2367 2368 **JSON parameters**: 2369 2370 - **Detach** - Detach from the `exec` command. 2371 - **Tty** - Boolean value to allocate a pseudo-TTY. 2372 2373 **Status codes**: 2374 2375 - **200** – no error 2376 - **404** – no such exec instance 2377 - **409** - container is paused 2378 2379 **Stream details**: 2380 2381 Similar to the stream behavior of `POST /containers/(id or name)/attach` API 2382 2383 #### Exec Resize 2384 2385 `POST /exec/(id)/resize` 2386 2387 Resizes the `tty` session used by the `exec` command `id`. The unit is number of characters. 2388 This API is valid only if `tty` was specified as part of creating and starting the `exec` command. 2389 2390 **Example request**: 2391 2392 POST /v1.21/exec/e90e34656806/resize?h=40&w=80 HTTP/1.1 2393 Content-Type: text/plain 2394 2395 **Example response**: 2396 2397 HTTP/1.1 201 Created 2398 Content-Type: text/plain 2399 2400 **Query parameters**: 2401 2402 - **h** – height of `tty` session 2403 - **w** – width 2404 2405 **Status codes**: 2406 2407 - **201** – no error 2408 - **404** – no such exec instance 2409 2410 #### Exec Inspect 2411 2412 `GET /exec/(id)/json` 2413 2414 Return low-level information about the `exec` command `id`. 2415 2416 **Example request**: 2417 2418 GET /v1.21/exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1 2419 2420 **Example response**: 2421 2422 HTTP/1.1 200 OK 2423 Content-Type: plain/text 2424 2425 { 2426 "ID" : "11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39", 2427 "Running" : false, 2428 "ExitCode" : 2, 2429 "ProcessConfig" : { 2430 "privileged" : false, 2431 "user" : "", 2432 "tty" : false, 2433 "entrypoint" : "sh", 2434 "arguments" : [ 2435 "-c", 2436 "exit 2" 2437 ] 2438 }, 2439 "OpenStdin" : false, 2440 "OpenStderr" : false, 2441 "OpenStdout" : false, 2442 "Container" : { 2443 "State" : { 2444 "Status" : "running", 2445 "Running" : true, 2446 "Paused" : false, 2447 "Restarting" : false, 2448 "OOMKilled" : false, 2449 "Pid" : 3650, 2450 "ExitCode" : 0, 2451 "Error" : "", 2452 "StartedAt" : "2014-11-17T22:26:03.717657531Z", 2453 "FinishedAt" : "0001-01-01T00:00:00Z" 2454 }, 2455 "ID" : "8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c", 2456 "Created" : "2014-11-17T22:26:03.626304998Z", 2457 "Path" : "date", 2458 "Args" : [], 2459 "Config" : { 2460 "Hostname" : "8f177a186b97", 2461 "Domainname" : "", 2462 "User" : "", 2463 "AttachStdin" : false, 2464 "AttachStdout" : false, 2465 "AttachStderr" : false, 2466 "ExposedPorts" : null, 2467 "Tty" : false, 2468 "OpenStdin" : false, 2469 "StdinOnce" : false, 2470 "Env" : [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ], 2471 "Cmd" : [ 2472 "date" 2473 ], 2474 "Image" : "ubuntu", 2475 "Volumes" : null, 2476 "WorkingDir" : "", 2477 "Entrypoint" : null, 2478 "NetworkDisabled" : false, 2479 "MacAddress" : "", 2480 "OnBuild" : null, 2481 "SecurityOpt" : null 2482 }, 2483 "Image" : "5506de2b643be1e6febbf3b8a240760c6843244c41e12aa2f60ccbb7153d17f5", 2484 "NetworkSettings" : { 2485 "Bridge": "", 2486 "SandboxID": "", 2487 "HairpinMode": false, 2488 "LinkLocalIPv6Address": "", 2489 "LinkLocalIPv6PrefixLen": 0, 2490 "Ports": null, 2491 "SandboxKey": "", 2492 "SecondaryIPAddresses": null, 2493 "SecondaryIPv6Addresses": null, 2494 "EndpointID": "", 2495 "Gateway": "", 2496 "GlobalIPv6Address": "", 2497 "GlobalIPv6PrefixLen": 0, 2498 "IPAddress": "", 2499 "IPPrefixLen": 0, 2500 "IPv6Gateway": "", 2501 "MacAddress": "", 2502 "Networks": { 2503 "bridge": { 2504 "EndpointID": "", 2505 "Gateway": "", 2506 "IPAddress": "", 2507 "IPPrefixLen": 0, 2508 "IPv6Gateway": "", 2509 "GlobalIPv6Address": "", 2510 "GlobalIPv6PrefixLen": 0, 2511 "MacAddress": "" 2512 } 2513 } 2514 }, 2515 "ResolvConfPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/resolv.conf", 2516 "HostnamePath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hostname", 2517 "HostsPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hosts", 2518 "LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log", 2519 "Name" : "/test", 2520 "Driver" : "aufs", 2521 "ExecDriver" : "native-0.2", 2522 "MountLabel" : "", 2523 "ProcessLabel" : "", 2524 "AppArmorProfile" : "", 2525 "RestartCount" : 0, 2526 "Mounts" : [] 2527 } 2528 } 2529 2530 **Status codes**: 2531 2532 - **200** – no error 2533 - **404** – no such exec instance 2534 - **500** - server error 2535 2536 ### 2.4 Volumes 2537 2538 #### List volumes 2539 2540 `GET /volumes` 2541 2542 **Example request**: 2543 2544 GET /v1.21/volumes HTTP/1.1 2545 2546 **Example response**: 2547 2548 HTTP/1.1 200 OK 2549 Content-Type: application/json 2550 2551 { 2552 "Volumes": [ 2553 { 2554 "Name": "tardis", 2555 "Driver": "local", 2556 "Mountpoint": "/var/lib/docker/volumes/tardis" 2557 } 2558 ] 2559 } 2560 2561 **Query parameters**: 2562 2563 - **filters** - JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. There is one available filter: `dangling=true` 2564 2565 **Status codes**: 2566 2567 - **200** - no error 2568 - **500** - server error 2569 2570 #### Create a volume 2571 2572 `POST /volumes/create` 2573 2574 Create a volume 2575 2576 **Example request**: 2577 2578 POST /v1.21/volumes/create HTTP/1.1 2579 Content-Type: application/json 2580 2581 { 2582 "Name": "tardis" 2583 } 2584 2585 **Example response**: 2586 2587 HTTP/1.1 201 Created 2588 Content-Type: application/json 2589 2590 { 2591 "Name": "tardis", 2592 "Driver": "local", 2593 "Mountpoint": "/var/lib/docker/volumes/tardis" 2594 } 2595 2596 **Status codes**: 2597 2598 - **201** - no error 2599 - **500** - server error 2600 2601 **JSON parameters**: 2602 2603 - **Name** - The new volume's name. If not specified, Docker generates a name. 2604 - **Driver** - Name of the volume driver to use. Defaults to `local` for the name. 2605 - **DriverOpts** - A mapping of driver options and values. These options are 2606 passed directly to the driver and are driver specific. 2607 2608 #### Inspect a volume 2609 2610 `GET /volumes/(name)` 2611 2612 Return low-level information on the volume `name` 2613 2614 **Example request**: 2615 2616 GET /volumes/tardis 2617 2618 **Example response**: 2619 2620 HTTP/1.1 200 OK 2621 Content-Type: application/json 2622 2623 { 2624 "Name": "tardis", 2625 "Driver": "local", 2626 "Mountpoint": "/var/lib/docker/volumes/tardis" 2627 } 2628 2629 **Status codes**: 2630 2631 - **200** - no error 2632 - **404** - no such volume 2633 - **500** - server error 2634 2635 #### Remove a volume 2636 2637 `DELETE /volumes/(name)` 2638 2639 Instruct the driver to remove the volume (`name`). 2640 2641 **Example request**: 2642 2643 DELETE /v1.21/volumes/tardis HTTP/1.1 2644 2645 **Example response**: 2646 2647 HTTP/1.1 204 No Content 2648 2649 **Status codes**: 2650 2651 - **204** - no error 2652 - **404** - no such volume or volume driver 2653 - **409** - volume is in use and cannot be removed 2654 - **500** - server error 2655 2656 ### 2.5 Networks 2657 2658 #### List networks 2659 2660 `GET /networks` 2661 2662 **Example request**: 2663 2664 GET /v1.21/networks HTTP/1.1 2665 2666 **Example response**: 2667 2668 ``` 2669 HTTP/1.1 200 OK 2670 Content-Type: application/json 2671 2672 [ 2673 { 2674 "Name": "bridge", 2675 "Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566", 2676 "Scope": "local", 2677 "Driver": "bridge", 2678 "IPAM": { 2679 "Driver": "default", 2680 "Config": [ 2681 { 2682 "Subnet": "172.17.0.0/16" 2683 } 2684 ] 2685 }, 2686 "Containers": { 2687 "39b69226f9d79f5634485fb236a23b2fe4e96a0a94128390a7fbbcc167065867": { 2688 "EndpointID": "ed2419a97c1d9954d05b46e462e7002ea552f216e9b136b80a7db8d98b442eda", 2689 "MacAddress": "02:42:ac:11:00:02", 2690 "IPv4Address": "172.17.0.2/16", 2691 "IPv6Address": "" 2692 } 2693 }, 2694 "Options": { 2695 "com.docker.network.bridge.default_bridge": "true", 2696 "com.docker.network.bridge.enable_icc": "true", 2697 "com.docker.network.bridge.enable_ip_masquerade": "true", 2698 "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", 2699 "com.docker.network.bridge.name": "docker0", 2700 "com.docker.network.driver.mtu": "1500" 2701 } 2702 }, 2703 { 2704 "Name": "none", 2705 "Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794", 2706 "Scope": "local", 2707 "Driver": "null", 2708 "IPAM": { 2709 "Driver": "default", 2710 "Config": [] 2711 }, 2712 "Containers": {}, 2713 "Options": {} 2714 }, 2715 { 2716 "Name": "host", 2717 "Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e", 2718 "Scope": "local", 2719 "Driver": "host", 2720 "IPAM": { 2721 "Driver": "default", 2722 "Config": [] 2723 }, 2724 "Containers": {}, 2725 "Options": {} 2726 } 2727 ] 2728 ``` 2729 2730 **Query parameters**: 2731 2732 - **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]` 2733 2734 **Status codes**: 2735 2736 - **200** - no error 2737 - **500** - server error 2738 2739 #### Inspect network 2740 2741 `GET /networks/<network-id>` 2742 2743 **Example request**: 2744 2745 GET /v1.21/networks/f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566 HTTP/1.1 2746 2747 **Example response**: 2748 2749 ``` 2750 HTTP/1.1 200 OK 2751 Content-Type: application/json 2752 2753 { 2754 "Name": "bridge", 2755 "Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566", 2756 "Scope": "local", 2757 "Driver": "bridge", 2758 "IPAM": { 2759 "Driver": "default", 2760 "Config": [ 2761 { 2762 "Subnet": "172.17.0.0/16" 2763 } 2764 ] 2765 }, 2766 "Containers": { 2767 "39b69226f9d79f5634485fb236a23b2fe4e96a0a94128390a7fbbcc167065867": { 2768 "EndpointID": "ed2419a97c1d9954d05b46e462e7002ea552f216e9b136b80a7db8d98b442eda", 2769 "MacAddress": "02:42:ac:11:00:02", 2770 "IPv4Address": "172.17.0.2/16", 2771 "IPv6Address": "" 2772 } 2773 }, 2774 "Options": { 2775 "com.docker.network.bridge.default_bridge": "true", 2776 "com.docker.network.bridge.enable_icc": "true", 2777 "com.docker.network.bridge.enable_ip_masquerade": "true", 2778 "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", 2779 "com.docker.network.bridge.name": "docker0", 2780 "com.docker.network.driver.mtu": "1500" 2781 } 2782 } 2783 ``` 2784 2785 **Status codes**: 2786 2787 - **200** - no error 2788 - **404** - network not found 2789 2790 #### Create a network 2791 2792 `POST /networks/create` 2793 2794 Create a network 2795 2796 **Example request**: 2797 2798 ``` 2799 POST /v1.21/networks/create HTTP/1.1 2800 Content-Type: application/json 2801 2802 { 2803 "Name":"isolated_nw", 2804 "CheckDuplicate":true, 2805 "Driver":"bridge", 2806 "IPAM":{ 2807 "Driver": "default", 2808 "Config":[ 2809 { 2810 "Subnet":"172.20.0.0/16", 2811 "IPRange":"172.20.10.0/24", 2812 "Gateway":"172.20.10.11" 2813 } 2814 ] 2815 } 2816 } 2817 ``` 2818 2819 **Example response**: 2820 2821 ``` 2822 HTTP/1.1 201 Created 2823 Content-Type: application/json 2824 2825 { 2826 "Id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30", 2827 "Warning": "" 2828 } 2829 ``` 2830 2831 **Status codes**: 2832 2833 - **201** - no error 2834 - **404** - plugin not found 2835 - **500** - server error 2836 2837 **JSON parameters**: 2838 2839 - **Name** - The new network's name. this is a mandatory field 2840 - **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false` 2841 - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver 2842 - **IPAM** - Optional custom IP scheme for the network 2843 - **Driver** - Name of the IPAM driver to use. Defaults to `default` driver 2844 - **Config** - List of IPAM configuration options, specified as a map: 2845 `{"Subnet": <CIDR>, "IPRange": <CIDR>, "Gateway": <IP address>, "AuxAddress": <device_name:IP address>}` 2846 - **Options** - Network specific options to be used by the drivers 2847 2848 #### Connect a container to a network 2849 2850 `POST /networks/(id)/connect` 2851 2852 Connect a container to a network 2853 2854 **Example request**: 2855 2856 ``` 2857 POST /v1.21/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1 2858 Content-Type: application/json 2859 2860 { 2861 "Container":"3613f73ba0e4" 2862 } 2863 ``` 2864 2865 **Example response**: 2866 2867 HTTP/1.1 200 OK 2868 2869 **Status codes**: 2870 2871 - **200** - no error 2872 - **404** - network or container is not found 2873 - **500** - Internal Server Error 2874 2875 **JSON parameters**: 2876 2877 - **container** - container-id/name to be connected to the network 2878 2879 #### Disconnect a container from a network 2880 2881 `POST /networks/(id)/disconnect` 2882 2883 Disconnect a container from a network 2884 2885 **Example request**: 2886 2887 ``` 2888 POST /v1.21/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1 2889 Content-Type: application/json 2890 2891 { 2892 "Container":"3613f73ba0e4" 2893 } 2894 ``` 2895 2896 **Example response**: 2897 2898 HTTP/1.1 200 OK 2899 2900 **Status codes**: 2901 2902 - **200** - no error 2903 - **404** - network or container not found 2904 - **500** - Internal Server Error 2905 2906 **JSON parameters**: 2907 2908 - **Container** - container-id/name to be disconnected from a network 2909 2910 #### Remove a network 2911 2912 `DELETE /networks/(id)` 2913 2914 Instruct the driver to remove the network (`id`). 2915 2916 **Example request**: 2917 2918 DELETE /v1.21/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30 HTTP/1.1 2919 2920 **Example response**: 2921 2922 HTTP/1.1 200 OK 2923 2924 **Status codes**: 2925 2926 - **200** - no error 2927 - **404** - no such network 2928 - **500** - server error 2929 2930 ## 3. Going further 2931 2932 ### 3.1 Inside `docker run` 2933 2934 As an example, the `docker run` command line makes the following API calls: 2935 2936 - Create the container 2937 2938 - If the status code is 404, it means the image doesn't exist: 2939 - Try to pull it. 2940 - Then, retry to create the container. 2941 2942 - Start the container. 2943 2944 - If you are not in detached mode: 2945 - Attach to the container, using `logs=1` (to have `stdout` and 2946 `stderr` from the container's start) and `stream=1` 2947 2948 - If in detached mode or only `stdin` is attached, display the container's id. 2949 2950 ### 3.2 Hijacking 2951 2952 In this version of the API, `/attach`, uses hijacking to transport `stdin`, 2953 `stdout`, and `stderr` on the same socket. 2954 2955 To hint potential proxies about connection hijacking, Docker client sends 2956 connection upgrade headers similarly to websocket. 2957 2958 Upgrade: tcp 2959 Connection: Upgrade 2960 2961 When Docker daemon detects the `Upgrade` header, it switches its status code 2962 from **200 OK** to **101 UPGRADED** and resends the same headers. 2963 2964 2965 ### 3.3 CORS Requests 2966 2967 To set cross origin requests to the Engine API please give values to 2968 `--api-cors-header` when running Docker in daemon mode. Set * (asterisk) allows all, 2969 default or blank means CORS disabled 2970 2971 $ dockerd -H="192.168.1.9:2375" --api-cors-header="http://foo.bar"