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