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