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