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