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