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