github.com/flavio/docker@v0.1.3-0.20170117145210-f63d1a6eec47/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 1368 **Status codes**: 1369 1370 - **204** – no error 1371 - **400** – bad parameter 1372 - **404** – no such container 1373 - **409** – conflict 1374 - **500** – server error 1375 1376 #### Copy files or folders from a container 1377 1378 `POST /containers/(id or name)/copy` 1379 1380 Copy files or folders of container `id` 1381 1382 **Deprecated** in favor of the `archive` endpoint below. 1383 1384 **Example request**: 1385 1386 POST /v1.22/containers/4fa6e0f0c678/copy HTTP/1.1 1387 Content-Type: application/json 1388 1389 { 1390 "Resource": "test.txt" 1391 } 1392 1393 **Example response**: 1394 1395 HTTP/1.1 200 OK 1396 Content-Type: application/x-tar 1397 1398 {% raw %} 1399 {{ TAR STREAM }} 1400 {% endraw %} 1401 1402 **Status codes**: 1403 1404 - **200** – no error 1405 - **404** – no such container 1406 - **500** – server error 1407 1408 #### Retrieving information about files and folders in a container 1409 1410 `HEAD /containers/(id or name)/archive` 1411 1412 See the description of the `X-Docker-Container-Path-Stat` header in the 1413 following section. 1414 1415 #### Get an archive of a filesystem resource in a container 1416 1417 `GET /containers/(id or name)/archive` 1418 1419 Get a tar archive of a resource in the filesystem of container `id`. 1420 1421 **Query parameters**: 1422 1423 - **path** - resource in the container's filesystem to archive. Required. 1424 1425 If not an absolute path, it is relative to the container's root directory. 1426 The resource specified by **path** must exist. To assert that the resource 1427 is expected to be a directory, **path** should end in `/` or `/.` 1428 (assuming a path separator of `/`). If **path** ends in `/.` then this 1429 indicates that only the contents of the **path** directory should be 1430 copied. A symlink is always resolved to its target. 1431 1432 > **Note**: It is not possible to copy certain system files such as resources 1433 > under `/proc`, `/sys`, `/dev`, and mounts created by the user in the 1434 > container. 1435 1436 **Example request**: 1437 1438 GET /v1.22/containers/8cce319429b2/archive?path=/root HTTP/1.1 1439 1440 **Example response**: 1441 1442 HTTP/1.1 200 OK 1443 Content-Type: application/x-tar 1444 X-Docker-Container-Path-Stat: eyJuYW1lIjoicm9vdCIsInNpemUiOjQwOTYsIm1vZGUiOjIxNDc0ODQwOTYsIm10aW1lIjoiMjAxNC0wMi0yN1QyMDo1MToyM1oiLCJsaW5rVGFyZ2V0IjoiIn0= 1445 1446 {% raw %} 1447 {{ TAR STREAM }} 1448 {% endraw %} 1449 1450 On success, a response header `X-Docker-Container-Path-Stat` will be set to a 1451 base64-encoded JSON object containing some filesystem header information about 1452 the archived resource. The above example value would decode to the following 1453 JSON object (whitespace added for readability): 1454 1455 ```json 1456 { 1457 "name": "root", 1458 "size": 4096, 1459 "mode": 2147484096, 1460 "mtime": "2014-02-27T20:51:23Z", 1461 "linkTarget": "" 1462 } 1463 ``` 1464 1465 A `HEAD` request can also be made to this endpoint if only this information is 1466 desired. 1467 1468 **Status codes**: 1469 1470 - **200** - success, returns archive of copied resource 1471 - **400** - client error, bad parameter, details in JSON response body, one of: 1472 - must specify path parameter (**path** cannot be empty) 1473 - not a directory (**path** was asserted to be a directory but exists as a 1474 file) 1475 - **404** - client error, resource not found, one of: 1476 – no such container (container `id` does not exist) 1477 - no such file or directory (**path** does not exist) 1478 - **500** - server error 1479 1480 #### Extract an archive of files or folders to a directory in a container 1481 1482 `PUT /containers/(id or name)/archive` 1483 1484 Upload a tar archive to be extracted to a path in the filesystem of container 1485 `id`. 1486 1487 **Query parameters**: 1488 1489 - **path** - path to a directory in the container 1490 to extract the archive's contents into. Required. 1491 1492 If not an absolute path, it is relative to the container's root directory. 1493 The **path** resource must exist. 1494 - **noOverwriteDirNonDir** - If "1", "true", or "True" then it will be an error 1495 if unpacking the given content would cause an existing directory to be 1496 replaced with a non-directory and vice versa. 1497 1498 **Example request**: 1499 1500 PUT /v1.22/containers/8cce319429b2/archive?path=/vol1 HTTP/1.1 1501 Content-Type: application/x-tar 1502 1503 {% raw %} 1504 {{ TAR STREAM }} 1505 {% endraw %} 1506 1507 **Example response**: 1508 1509 HTTP/1.1 200 OK 1510 1511 **Status codes**: 1512 1513 - **200** – the content was extracted successfully 1514 - **400** - client error, bad parameter, details in JSON response body, one of: 1515 - must specify path parameter (**path** cannot be empty) 1516 - not a directory (**path** should be a directory but exists as a file) 1517 - unable to overwrite existing directory with non-directory 1518 (if **noOverwriteDirNonDir**) 1519 - unable to overwrite existing non-directory with directory 1520 (if **noOverwriteDirNonDir**) 1521 - **403** - client error, permission denied, the volume 1522 or container rootfs is marked as read-only. 1523 - **404** - client error, resource not found, one of: 1524 – no such container (container `id` does not exist) 1525 - no such file or directory (**path** resource does not exist) 1526 - **500** – server error 1527 1528 ### 2.2 Images 1529 1530 #### List Images 1531 1532 `GET /images/json` 1533 1534 **Example request**: 1535 1536 GET /v1.22/images/json?all=0 HTTP/1.1 1537 1538 **Example response**: 1539 1540 HTTP/1.1 200 OK 1541 Content-Type: application/json 1542 1543 [ 1544 { 1545 "RepoTags": [ 1546 "ubuntu:12.04", 1547 "ubuntu:precise", 1548 "ubuntu:latest" 1549 ], 1550 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 1551 "Created": 1365714795, 1552 "Size": 131506275, 1553 "VirtualSize": 131506275, 1554 "Labels": {} 1555 }, 1556 { 1557 "RepoTags": [ 1558 "ubuntu:12.10", 1559 "ubuntu:quantal" 1560 ], 1561 "ParentId": "27cf784147099545", 1562 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 1563 "Created": 1364102658, 1564 "Size": 24653, 1565 "VirtualSize": 180116135, 1566 "Labels": { 1567 "com.example.version": "v1" 1568 } 1569 } 1570 ] 1571 1572 **Example request, with digest information**: 1573 1574 GET /v1.22/images/json?digests=1 HTTP/1.1 1575 1576 **Example response, with digest information**: 1577 1578 HTTP/1.1 200 OK 1579 Content-Type: application/json 1580 1581 [ 1582 { 1583 "Created": 1420064636, 1584 "Id": "4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125", 1585 "ParentId": "ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2", 1586 "RepoDigests": [ 1587 "localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf" 1588 ], 1589 "RepoTags": [ 1590 "localhost:5000/test/busybox:latest", 1591 "playdate:latest" 1592 ], 1593 "Size": 0, 1594 "VirtualSize": 2429728, 1595 "Labels": {} 1596 } 1597 ] 1598 1599 The response shows a single image `Id` associated with two repositories 1600 (`RepoTags`): `localhost:5000/test/busybox`: and `playdate`. A caller can use 1601 either of the `RepoTags` values `localhost:5000/test/busybox:latest` or 1602 `playdate:latest` to reference the image. 1603 1604 You can also use `RepoDigests` values to reference an image. In this response, 1605 the array has only one reference and that is to the 1606 `localhost:5000/test/busybox` repository; the `playdate` repository has no 1607 digest. You can reference this digest using the value: 1608 `localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d...` 1609 1610 See the `docker run` and `docker build` commands for examples of digest and tag 1611 references on the command line. 1612 1613 **Query parameters**: 1614 1615 - **all** – 1/True/true or 0/False/false, default false 1616 - **filters** – a JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters: 1617 - `dangling=true` 1618 - `label=key` or `label="key=value"` of an image label 1619 - **filter** - only return images with the specified name 1620 1621 #### Build image from a Dockerfile 1622 1623 `POST /build` 1624 1625 Build an image from a Dockerfile 1626 1627 **Example request**: 1628 1629 POST /v1.22/build HTTP/1.1 1630 Content-Type: application/x-tar 1631 1632 {% raw %} 1633 {{ TAR STREAM }} 1634 {% endraw %} 1635 1636 **Example response**: 1637 1638 HTTP/1.1 200 OK 1639 Content-Type: application/json 1640 1641 {"stream": "Step 1/5..."} 1642 {"stream": "..."} 1643 {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} 1644 1645 The input stream must be a `tar` archive compressed with one of the 1646 following algorithms: `identity` (no compression), `gzip`, `bzip2`, `xz`. 1647 1648 The archive must include a build instructions file, typically called 1649 `Dockerfile` at the archive's root. The `dockerfile` parameter may be 1650 used to specify a different build instructions file. To do this, its value must be 1651 the path to the alternate build instructions file to use. 1652 1653 The archive may include any number of other files, 1654 which are accessible in the build context (See the [*ADD build 1655 command*](../../reference/builder.md#add)). 1656 1657 The Docker daemon performs a preliminary validation of the `Dockerfile` before 1658 starting the build, and returns an error if the syntax is incorrect. After that, 1659 each instruction is run one-by-one until the ID of the new image is output. 1660 1661 The build is canceled if the client drops the connection by quitting 1662 or being killed. 1663 1664 **Query parameters**: 1665 1666 - **dockerfile** - Path within the build context to the `Dockerfile`. This is 1667 ignored if `remote` is specified and points to an external `Dockerfile`. 1668 - **t** – A name and optional tag to apply to the image in the `name:tag` format. 1669 If you omit the `tag` the default `latest` value is assumed. 1670 You can provide one or more `t` parameters. 1671 - **remote** – A Git repository URI or HTTP/HTTPS context URI. If the 1672 URI points to a single text file, the file's contents are placed into 1673 a file called `Dockerfile` and the image is built from that file. If 1674 the URI points to a tarball, the file is downloaded by the daemon and 1675 the contents therein used as the context for the build. If the URI 1676 points to a tarball and the `dockerfile` parameter is also specified, 1677 there must be a file with the corresponding path inside the tarball. 1678 - **q** – Suppress verbose build output. 1679 - **nocache** – Do not use the cache when building the image. 1680 - **pull** - Attempt to pull the image even if an older image exists locally. 1681 - **rm** - Remove intermediate containers after a successful build (default behavior). 1682 - **forcerm** - Always remove intermediate containers (includes `rm`). 1683 - **memory** - Set memory limit for build. 1684 - **memswap** - Total memory (memory + swap), `-1` to enable unlimited swap. 1685 - **cpushares** - CPU shares (relative weight). 1686 - **cpusetcpus** - CPUs in which to allow execution (e.g., `0-3`, `0,1`). 1687 - **cpuperiod** - The length of a CPU period in microseconds. 1688 - **cpuquota** - Microseconds of CPU time that the container can get in a CPU period. 1689 - **buildargs** – JSON map of string pairs for build-time variables. Users pass 1690 these values at build-time. Docker uses the `buildargs` as the environment 1691 context for command(s) run via the Dockerfile's `RUN` instruction or for 1692 variable expansion in other Dockerfile instructions. This is not meant for 1693 passing secret values. [Read more about the buildargs instruction](../../reference/builder.md#arg) 1694 - **shmsize** - Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB. 1695 1696 **Request Headers**: 1697 1698 - **Content-type** – Set to `"application/x-tar"`. 1699 - **X-Registry-Config** – A base64-url-safe-encoded Registry Auth Config JSON 1700 object with the following structure: 1701 1702 { 1703 "docker.example.com": { 1704 "username": "janedoe", 1705 "password": "hunter2" 1706 }, 1707 "https://index.docker.io/v1/": { 1708 "username": "mobydock", 1709 "password": "conta1n3rize14" 1710 } 1711 } 1712 1713 This object maps the hostname of a registry to an object containing the 1714 "username" and "password" for that registry. Multiple registries may 1715 be specified as the build may be based on an image requiring 1716 authentication to pull from any arbitrary registry. Only the registry 1717 domain name (and port if not the default "443") are required. However 1718 (for legacy reasons) the "official" Docker, Inc. hosted registry must 1719 be specified with both a "https://" prefix and a "/v1/" suffix even 1720 though Docker will prefer to use the v2 registry API. 1721 1722 **Status codes**: 1723 1724 - **200** – no error 1725 - **500** – server error 1726 1727 #### Create an image 1728 1729 `POST /images/create` 1730 1731 Create an image either by pulling it from the registry or by importing it 1732 1733 **Example request**: 1734 1735 POST /v1.22/images/create?fromImage=busybox&tag=latest HTTP/1.1 1736 1737 **Example response**: 1738 1739 HTTP/1.1 200 OK 1740 Content-Type: application/json 1741 1742 {"status": "Pulling..."} 1743 {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} 1744 {"error": "Invalid..."} 1745 ... 1746 1747 When using this endpoint to pull an image from the registry, the 1748 `X-Registry-Auth` header can be used to include 1749 a base64-encoded AuthConfig object. 1750 1751 **Query parameters**: 1752 1753 - **fromImage** – Name of the image to pull. The name may include a tag or 1754 digest. This parameter may only be used when pulling an image. 1755 The pull is cancelled if the HTTP connection is closed. 1756 - **fromSrc** – Source to import. The value may be a URL from which the image 1757 can be retrieved or `-` to read the image from the request body. 1758 This parameter may only be used when importing an image. 1759 - **repo** – Repository name given to an image when it is imported. 1760 The repo may include a tag. This parameter may only be used when importing 1761 an image. 1762 - **tag** – Tag or digest. If empty when pulling an image, this causes all tags 1763 for the given image to be pulled. 1764 1765 **Request Headers**: 1766 1767 - **X-Registry-Auth** – base64-encoded AuthConfig object, containing either login information, or a token 1768 - Credential based login: 1769 1770 ``` 1771 { 1772 "username": "jdoe", 1773 "password": "secret", 1774 "email": "jdoe@acme.com" 1775 } 1776 ``` 1777 1778 - Token based login: 1779 1780 ``` 1781 { 1782 "registrytoken": "9cbaf023786cd7..." 1783 } 1784 ``` 1785 1786 **Status codes**: 1787 1788 - **200** – no error 1789 - **404** - repository does not exist or no read access 1790 - **500** – server error 1791 1792 1793 1794 #### Inspect an image 1795 1796 `GET /images/(name)/json` 1797 1798 Return low-level information on the image `name` 1799 1800 **Example request**: 1801 1802 GET /v1.22/images/example/json HTTP/1.1 1803 1804 **Example response**: 1805 1806 HTTP/1.1 200 OK 1807 Content-Type: application/json 1808 1809 { 1810 "Id" : "85f05633ddc1c50679be2b16a0479ab6f7637f8884e0cfe0f4d20e1ebb3d6e7c", 1811 "Container" : "cb91e48a60d01f1e27028b4fc6819f4f290b3cf12496c8176ec714d0d390984a", 1812 "Comment" : "", 1813 "Os" : "linux", 1814 "Architecture" : "amd64", 1815 "Parent" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1816 "ContainerConfig" : { 1817 "Tty" : false, 1818 "Hostname" : "e611e15f9c9d", 1819 "Volumes" : null, 1820 "Domainname" : "", 1821 "AttachStdout" : false, 1822 "PublishService" : "", 1823 "AttachStdin" : false, 1824 "OpenStdin" : false, 1825 "StdinOnce" : false, 1826 "NetworkDisabled" : false, 1827 "OnBuild" : [], 1828 "Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1829 "User" : "", 1830 "WorkingDir" : "", 1831 "Entrypoint" : null, 1832 "MacAddress" : "", 1833 "AttachStderr" : false, 1834 "Labels" : { 1835 "com.example.license" : "GPL", 1836 "com.example.version" : "1.0", 1837 "com.example.vendor" : "Acme" 1838 }, 1839 "Env" : [ 1840 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 1841 ], 1842 "ExposedPorts" : null, 1843 "Cmd" : [ 1844 "/bin/sh", 1845 "-c", 1846 "#(nop) LABEL com.example.vendor=Acme com.example.license=GPL com.example.version=1.0" 1847 ] 1848 }, 1849 "DockerVersion" : "1.9.0-dev", 1850 "VirtualSize" : 188359297, 1851 "Size" : 0, 1852 "Author" : "", 1853 "Created" : "2015-09-10T08:30:53.26995814Z", 1854 "GraphDriver" : { 1855 "Name" : "aufs", 1856 "Data" : null 1857 }, 1858 "RepoDigests" : [ 1859 "localhost:5000/test/busybox/example@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf" 1860 ], 1861 "RepoTags" : [ 1862 "example:1.0", 1863 "example:latest", 1864 "example:stable" 1865 ], 1866 "Config" : { 1867 "Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1868 "NetworkDisabled" : false, 1869 "OnBuild" : [], 1870 "StdinOnce" : false, 1871 "PublishService" : "", 1872 "AttachStdin" : false, 1873 "OpenStdin" : false, 1874 "Domainname" : "", 1875 "AttachStdout" : false, 1876 "Tty" : false, 1877 "Hostname" : "e611e15f9c9d", 1878 "Volumes" : null, 1879 "Cmd" : [ 1880 "/bin/bash" 1881 ], 1882 "ExposedPorts" : null, 1883 "Env" : [ 1884 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 1885 ], 1886 "Labels" : { 1887 "com.example.vendor" : "Acme", 1888 "com.example.version" : "1.0", 1889 "com.example.license" : "GPL" 1890 }, 1891 "Entrypoint" : null, 1892 "MacAddress" : "", 1893 "AttachStderr" : false, 1894 "WorkingDir" : "", 1895 "User" : "" 1896 } 1897 } 1898 1899 **Status codes**: 1900 1901 - **200** – no error 1902 - **404** – no such image 1903 - **500** – server error 1904 1905 #### Get the history of an image 1906 1907 `GET /images/(name)/history` 1908 1909 Return the history of the image `name` 1910 1911 **Example request**: 1912 1913 GET /v1.22/images/ubuntu/history HTTP/1.1 1914 1915 **Example response**: 1916 1917 HTTP/1.1 200 OK 1918 Content-Type: application/json 1919 1920 [ 1921 { 1922 "Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710", 1923 "Created": 1398108230, 1924 "CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /", 1925 "Tags": [ 1926 "ubuntu:lucid", 1927 "ubuntu:10.04" 1928 ], 1929 "Size": 182964289, 1930 "Comment": "" 1931 }, 1932 { 1933 "Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8", 1934 "Created": 1398108222, 1935 "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/", 1936 "Tags": null, 1937 "Size": 0, 1938 "Comment": "" 1939 }, 1940 { 1941 "Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158", 1942 "Created": 1371157430, 1943 "CreatedBy": "", 1944 "Tags": [ 1945 "scratch12:latest", 1946 "scratch:latest" 1947 ], 1948 "Size": 0, 1949 "Comment": "Imported from -" 1950 } 1951 ] 1952 1953 **Status codes**: 1954 1955 - **200** – no error 1956 - **404** – no such image 1957 - **500** – server error 1958 1959 #### Push an image on the registry 1960 1961 `POST /images/(name)/push` 1962 1963 Push the image `name` on the registry 1964 1965 **Example request**: 1966 1967 POST /v1.22/images/test/push HTTP/1.1 1968 1969 **Example response**: 1970 1971 HTTP/1.1 200 OK 1972 Content-Type: application/json 1973 1974 {"status": "Pushing..."} 1975 {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} 1976 {"error": "Invalid..."} 1977 ... 1978 1979 If you wish to push an image on to a private registry, that image must already have a tag 1980 into a repository which references that registry `hostname` and `port`. This repository name should 1981 then be used in the URL. This duplicates the command line's flow. 1982 1983 The push is cancelled if the HTTP connection is closed. 1984 1985 **Example request**: 1986 1987 POST /v1.22/images/registry.acme.com:5000/test/push HTTP/1.1 1988 1989 1990 **Query parameters**: 1991 1992 - **tag** – The tag to associate with the image on the registry. This is optional. 1993 1994 **Request Headers**: 1995 1996 - **X-Registry-Auth** – base64-encoded AuthConfig object, containing either login information, or a token 1997 - Credential based login: 1998 1999 ``` 2000 { 2001 "username": "jdoe", 2002 "password": "secret", 2003 "email": "jdoe@acme.com", 2004 } 2005 ``` 2006 2007 - Token based login: 2008 2009 ``` 2010 { 2011 "registrytoken": "9cbaf023786cd7..." 2012 } 2013 ``` 2014 2015 **Status codes**: 2016 2017 - **200** – no error 2018 - **404** – no such image 2019 - **500** – server error 2020 2021 #### Tag an image into a repository 2022 2023 `POST /images/(name)/tag` 2024 2025 Tag the image `name` into a repository 2026 2027 **Example request**: 2028 2029 POST /v1.22/images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 2030 2031 **Example response**: 2032 2033 HTTP/1.1 201 Created 2034 2035 **Query parameters**: 2036 2037 - **repo** – The repository to tag in 2038 - **force** – 1/True/true or 0/False/false, default false 2039 - **tag** - The new tag name 2040 2041 **Status codes**: 2042 2043 - **201** – no error 2044 - **400** – bad parameter 2045 - **404** – no such image 2046 - **409** – conflict 2047 - **500** – server error 2048 2049 #### Remove an image 2050 2051 `DELETE /images/(name)` 2052 2053 Remove the image `name` from the filesystem 2054 2055 **Example request**: 2056 2057 DELETE /v1.22/images/test HTTP/1.1 2058 2059 **Example response**: 2060 2061 HTTP/1.1 200 OK 2062 Content-type: application/json 2063 2064 [ 2065 {"Untagged": "3e2f21a89f"}, 2066 {"Deleted": "3e2f21a89f"}, 2067 {"Deleted": "53b4f83ac9"} 2068 ] 2069 2070 **Query parameters**: 2071 2072 - **force** – 1/True/true or 0/False/false, default false 2073 - **noprune** – 1/True/true or 0/False/false, default false 2074 2075 **Status codes**: 2076 2077 - **200** – no error 2078 - **404** – no such image 2079 - **409** – conflict 2080 - **500** – server error 2081 2082 #### Search images 2083 2084 `GET /images/search` 2085 2086 Search for an image on [Docker Hub](https://hub.docker.com). 2087 2088 > **Note**: 2089 > The response keys have changed from API v1.6 to reflect the JSON 2090 > sent by the registry server to the docker daemon's request. 2091 2092 **Example request**: 2093 2094 GET /v1.22/images/search?term=sshd HTTP/1.1 2095 2096 **Example response**: 2097 2098 HTTP/1.1 200 OK 2099 Content-Type: application/json 2100 2101 [ 2102 { 2103 "description": "", 2104 "is_official": false, 2105 "is_automated": false, 2106 "name": "wma55/u1210sshd", 2107 "star_count": 0 2108 }, 2109 { 2110 "description": "", 2111 "is_official": false, 2112 "is_automated": false, 2113 "name": "jdswinbank/sshd", 2114 "star_count": 0 2115 }, 2116 { 2117 "description": "", 2118 "is_official": false, 2119 "is_automated": false, 2120 "name": "vgauthier/sshd", 2121 "star_count": 0 2122 } 2123 ... 2124 ] 2125 2126 **Query parameters**: 2127 2128 - **term** – term to search 2129 2130 **Status codes**: 2131 2132 - **200** – no error 2133 - **500** – server error 2134 2135 ### 2.3 Misc 2136 2137 #### Check auth configuration 2138 2139 `POST /auth` 2140 2141 Get the default username and email 2142 2143 **Example request**: 2144 2145 POST /v1.22/auth HTTP/1.1 2146 Content-Type: application/json 2147 2148 { 2149 "username": "hannibal", 2150 "password": "xxxx", 2151 "email": "hannibal@a-team.com", 2152 "serveraddress": "https://index.docker.io/v1/" 2153 } 2154 2155 **Example response**: 2156 2157 HTTP/1.1 200 OK 2158 2159 **Status codes**: 2160 2161 - **200** – no error 2162 - **204** – no error 2163 - **500** – server error 2164 2165 #### Display system-wide information 2166 2167 `GET /info` 2168 2169 Display system-wide information 2170 2171 **Example request**: 2172 2173 GET /v1.22/info HTTP/1.1 2174 2175 **Example response**: 2176 2177 HTTP/1.1 200 OK 2178 Content-Type: application/json 2179 2180 { 2181 "Architecture": "x86_64", 2182 "ClusterStore": "etcd://localhost:2379", 2183 "Containers": 11, 2184 "ContainersRunning": 7, 2185 "ContainersStopped": 3, 2186 "ContainersPaused": 1, 2187 "CpuCfsPeriod": true, 2188 "CpuCfsQuota": true, 2189 "Debug": false, 2190 "DockerRootDir": "/var/lib/docker", 2191 "Driver": "btrfs", 2192 "DriverStatus": [[""]], 2193 "ExecutionDriver": "native-0.1", 2194 "ExperimentalBuild": false, 2195 "HttpProxy": "http://test:test@localhost:8080", 2196 "HttpsProxy": "https://test:test@localhost:8080", 2197 "ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS", 2198 "IPv4Forwarding": true, 2199 "Images": 16, 2200 "IndexServerAddress": "https://index.docker.io/v1/", 2201 "InitPath": "/usr/bin/docker", 2202 "InitSha1": "", 2203 "KernelVersion": "3.12.0-1-amd64", 2204 "Labels": [ 2205 "storage=ssd" 2206 ], 2207 "MemTotal": 2099236864, 2208 "MemoryLimit": true, 2209 "NCPU": 1, 2210 "NEventsListener": 0, 2211 "NFd": 11, 2212 "NGoroutines": 21, 2213 "Name": "prod-server-42", 2214 "NoProxy": "9.81.1.160", 2215 "OomKillDisable": true, 2216 "OSType": "linux", 2217 "OperatingSystem": "Boot2Docker", 2218 "Plugins": { 2219 "Volume": [ 2220 "local" 2221 ], 2222 "Network": [ 2223 "null", 2224 "host", 2225 "bridge" 2226 ] 2227 }, 2228 "RegistryConfig": { 2229 "IndexConfigs": { 2230 "docker.io": { 2231 "Mirrors": null, 2232 "Name": "docker.io", 2233 "Official": true, 2234 "Secure": true 2235 } 2236 }, 2237 "InsecureRegistryCIDRs": [ 2238 "127.0.0.0/8" 2239 ] 2240 }, 2241 "ServerVersion": "1.9.0", 2242 "SwapLimit": false, 2243 "SystemStatus": [["State", "Healthy"]], 2244 "SystemTime": "2015-03-10T11:11:23.730591467-07:00" 2245 } 2246 2247 **Status codes**: 2248 2249 - **200** – no error 2250 - **500** – server error 2251 2252 #### Show the docker version information 2253 2254 `GET /version` 2255 2256 Show the docker version information 2257 2258 **Example request**: 2259 2260 GET /v1.22/version HTTP/1.1 2261 2262 **Example response**: 2263 2264 HTTP/1.1 200 OK 2265 Content-Type: application/json 2266 2267 { 2268 "Version": "1.10.0", 2269 "Os": "linux", 2270 "KernelVersion": "3.19.0-23-generic", 2271 "GoVersion": "go1.4.2", 2272 "GitCommit": "e75da4b", 2273 "Arch": "amd64", 2274 "ApiVersion": "1.22", 2275 "BuildTime": "2015-12-01T07:09:13.444803460+00:00", 2276 "Experimental": true 2277 } 2278 2279 **Status codes**: 2280 2281 - **200** – no error 2282 - **500** – server error 2283 2284 #### Ping the docker server 2285 2286 `GET /_ping` 2287 2288 Ping the docker server 2289 2290 **Example request**: 2291 2292 GET /v1.22/_ping HTTP/1.1 2293 2294 **Example response**: 2295 2296 HTTP/1.1 200 OK 2297 Content-Type: text/plain 2298 2299 OK 2300 2301 **Status codes**: 2302 2303 - **200** - no error 2304 - **500** - server error 2305 2306 #### Create a new image from a container's changes 2307 2308 `POST /commit` 2309 2310 Create a new image from a container's changes 2311 2312 **Example request**: 2313 2314 POST /v1.22/commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 2315 Content-Type: application/json 2316 2317 { 2318 "Hostname": "", 2319 "Domainname": "", 2320 "User": "", 2321 "AttachStdin": false, 2322 "AttachStdout": true, 2323 "AttachStderr": true, 2324 "Tty": false, 2325 "OpenStdin": false, 2326 "StdinOnce": false, 2327 "Env": null, 2328 "Cmd": [ 2329 "date" 2330 ], 2331 "Mounts": [ 2332 { 2333 "Source": "/data", 2334 "Destination": "/data", 2335 "Mode": "ro,Z", 2336 "RW": false 2337 } 2338 ], 2339 "Labels": { 2340 "key1": "value1", 2341 "key2": "value2" 2342 }, 2343 "WorkingDir": "", 2344 "NetworkDisabled": false, 2345 "ExposedPorts": { 2346 "22/tcp": {} 2347 } 2348 } 2349 2350 **Example response**: 2351 2352 HTTP/1.1 201 Created 2353 Content-Type: application/json 2354 2355 {"Id": "596069db4bf5"} 2356 2357 **JSON parameters**: 2358 2359 - **config** - the container's configuration 2360 2361 **Query parameters**: 2362 2363 - **container** – source container 2364 - **repo** – repository 2365 - **tag** – tag 2366 - **comment** – commit message 2367 - **author** – author (e.g., "John Hannibal Smith 2368 <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") 2369 - **pause** – 1/True/true or 0/False/false, whether to pause the container before committing 2370 - **changes** – Dockerfile instructions to apply while committing 2371 2372 **Status codes**: 2373 2374 - **201** – no error 2375 - **404** – no such container 2376 - **500** – server error 2377 2378 #### Monitor Docker's events 2379 2380 `GET /events` 2381 2382 Get container events from docker, in real time via streaming. 2383 2384 Docker containers report the following events: 2385 2386 attach, commit, copy, create, destroy, die, exec_create, exec_start, export, kill, oom, pause, rename, resize, restart, start, stop, top, unpause, update 2387 2388 Docker images report the following events: 2389 2390 delete, import, pull, push, tag, untag 2391 2392 Docker volumes report the following events: 2393 2394 create, mount, unmount, destroy 2395 2396 Docker networks report the following events: 2397 2398 create, connect, disconnect, destroy 2399 2400 **Example request**: 2401 2402 GET /v1.22/events?since=1374067924 2403 2404 **Example response**: 2405 2406 HTTP/1.1 200 OK 2407 Content-Type: application/json 2408 Server: Docker/1.10.0 (linux) 2409 Date: Fri, 29 Apr 2016 15:18:06 GMT 2410 Transfer-Encoding: chunked 2411 2412 { 2413 "status": "pull", 2414 "id": "alpine:latest", 2415 "Type": "image", 2416 "Action": "pull", 2417 "Actor": { 2418 "ID": "alpine:latest", 2419 "Attributes": { 2420 "name": "alpine" 2421 } 2422 }, 2423 "time": 1461943101, 2424 "timeNano": 1461943101301854122 2425 } 2426 { 2427 "status": "create", 2428 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2429 "from": "alpine", 2430 "Type": "container", 2431 "Action": "create", 2432 "Actor": { 2433 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2434 "Attributes": { 2435 "com.example.some-label": "some-label-value", 2436 "image": "alpine", 2437 "name": "my-container" 2438 } 2439 }, 2440 "time": 1461943101, 2441 "timeNano": 1461943101381709551 2442 } 2443 { 2444 "status": "attach", 2445 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2446 "from": "alpine", 2447 "Type": "container", 2448 "Action": "attach", 2449 "Actor": { 2450 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2451 "Attributes": { 2452 "com.example.some-label": "some-label-value", 2453 "image": "alpine", 2454 "name": "my-container" 2455 } 2456 }, 2457 "time": 1461943101, 2458 "timeNano": 1461943101383858412 2459 } 2460 { 2461 "Type": "network", 2462 "Action": "connect", 2463 "Actor": { 2464 "ID": "7dc8ac97d5d29ef6c31b6052f3938c1e8f2749abbd17d1bd1febf2608db1b474", 2465 "Attributes": { 2466 "container": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2467 "name": "bridge", 2468 "type": "bridge" 2469 } 2470 }, 2471 "time": 1461943101, 2472 "timeNano": 1461943101394865557 2473 } 2474 { 2475 "status": "start", 2476 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2477 "from": "alpine", 2478 "Type": "container", 2479 "Action": "start", 2480 "Actor": { 2481 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2482 "Attributes": { 2483 "com.example.some-label": "some-label-value", 2484 "image": "alpine", 2485 "name": "my-container" 2486 } 2487 }, 2488 "time": 1461943101, 2489 "timeNano": 1461943101607533796 2490 } 2491 { 2492 "status": "resize", 2493 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2494 "from": "alpine", 2495 "Type": "container", 2496 "Action": "resize", 2497 "Actor": { 2498 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2499 "Attributes": { 2500 "com.example.some-label": "some-label-value", 2501 "height": "46", 2502 "image": "alpine", 2503 "name": "my-container", 2504 "width": "204" 2505 } 2506 }, 2507 "time": 1461943101, 2508 "timeNano": 1461943101610269268 2509 } 2510 { 2511 "status": "die", 2512 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2513 "from": "alpine", 2514 "Type": "container", 2515 "Action": "die", 2516 "Actor": { 2517 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2518 "Attributes": { 2519 "com.example.some-label": "some-label-value", 2520 "exitCode": "0", 2521 "image": "alpine", 2522 "name": "my-container" 2523 } 2524 }, 2525 "time": 1461943105, 2526 "timeNano": 1461943105079144137 2527 } 2528 { 2529 "Type": "network", 2530 "Action": "disconnect", 2531 "Actor": { 2532 "ID": "7dc8ac97d5d29ef6c31b6052f3938c1e8f2749abbd17d1bd1febf2608db1b474", 2533 "Attributes": { 2534 "container": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2535 "name": "bridge", 2536 "type": "bridge" 2537 } 2538 }, 2539 "time": 1461943105, 2540 "timeNano": 1461943105230860245 2541 } 2542 { 2543 "status": "destroy", 2544 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2545 "from": "alpine", 2546 "Type": "container", 2547 "Action": "destroy", 2548 "Actor": { 2549 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2550 "Attributes": { 2551 "com.example.some-label": "some-label-value", 2552 "image": "alpine", 2553 "name": "my-container" 2554 } 2555 }, 2556 "time": 1461943105, 2557 "timeNano": 1461943105338056026 2558 } 2559 2560 **Query parameters**: 2561 2562 - **since** – Timestamp. Show all events created since timestamp and then stream 2563 - **until** – Timestamp. Show events created until given timestamp and stop streaming 2564 - **filters** – A json encoded value of the filters (a map[string][]string) to process on the event list. Available filters: 2565 - `container=<string>`; -- container to filter 2566 - `event=<string>`; -- event to filter 2567 - `image=<string>`; -- image to filter 2568 - `label=<string>`; -- image and container label to filter 2569 - `type=<string>`; -- either `container` or `image` or `volume` or `network` 2570 - `volume=<string>`; -- volume to filter 2571 - `network=<string>`; -- network to filter 2572 2573 **Status codes**: 2574 2575 - **200** – no error 2576 - **500** – server error 2577 2578 #### Get a tarball containing all images in a repository 2579 2580 `GET /images/(name)/get` 2581 2582 Get a tarball containing all images and metadata for the repository specified 2583 by `name`. 2584 2585 If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image 2586 (and its parents) are returned. If `name` is an image ID, similarly only that 2587 image (and its parents) are returned, but with the exclusion of the 2588 'repositories' file in the tarball, as there were no image names referenced. 2589 2590 See the [image tarball format](#image-tarball-format) for more details. 2591 2592 **Example request** 2593 2594 GET /v1.22/images/ubuntu/get 2595 2596 **Example response**: 2597 2598 HTTP/1.1 200 OK 2599 Content-Type: application/x-tar 2600 2601 Binary data stream 2602 2603 **Status codes**: 2604 2605 - **200** – no error 2606 - **500** – server error 2607 2608 #### Get a tarball containing all images 2609 2610 `GET /images/get` 2611 2612 Get a tarball containing all images and metadata for one or more repositories. 2613 2614 For each value of the `names` parameter: if it is a specific name and tag (e.g. 2615 `ubuntu:latest`), then only that image (and its parents) are returned; if it is 2616 an image ID, similarly only that image (and its parents) are returned and there 2617 would be no names referenced in the 'repositories' file for this image ID. 2618 2619 See the [image tarball format](#image-tarball-format) for more details. 2620 2621 **Example request** 2622 2623 GET /v1.22/images/get?names=myname%2Fmyapp%3Alatest&names=busybox 2624 2625 **Example response**: 2626 2627 HTTP/1.1 200 OK 2628 Content-Type: application/x-tar 2629 2630 Binary data stream 2631 2632 **Status codes**: 2633 2634 - **200** – no error 2635 - **500** – server error 2636 2637 #### Load a tarball with a set of images and tags into docker 2638 2639 `POST /images/load` 2640 2641 Load a set of images and tags into a Docker repository. 2642 See the [image tarball format](#image-tarball-format) for more details. 2643 2644 **Example request** 2645 2646 POST /v1.22/images/load 2647 Content-Type: application/x-tar 2648 2649 Tarball in body 2650 2651 **Example response**: 2652 2653 HTTP/1.1 200 OK 2654 2655 **Status codes**: 2656 2657 - **200** – no error 2658 - **500** – server error 2659 2660 #### Image tarball format 2661 2662 An image tarball contains one directory per image layer (named using its long ID), 2663 each containing these files: 2664 2665 - `VERSION`: currently `1.0` - the file format version 2666 - `json`: detailed layer information, similar to `docker inspect layer_id` 2667 - `layer.tar`: A tarfile containing the filesystem changes in this layer 2668 2669 The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories 2670 for storing attribute changes and deletions. 2671 2672 If the tarball defines a repository, the tarball should also include a `repositories` file at 2673 the root that contains a list of repository and tag names mapped to layer IDs. 2674 2675 ``` 2676 {"hello-world": 2677 {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} 2678 } 2679 ``` 2680 2681 #### Exec Create 2682 2683 `POST /containers/(id or name)/exec` 2684 2685 Sets up an exec instance in a running container `id` 2686 2687 **Example request**: 2688 2689 POST /v1.22/containers/e90e34656806/exec HTTP/1.1 2690 Content-Type: application/json 2691 2692 { 2693 "AttachStdin": true, 2694 "AttachStdout": true, 2695 "AttachStderr": true, 2696 "Cmd": ["sh"], 2697 "DetachKeys": "ctrl-p,ctrl-q", 2698 "Privileged": true, 2699 "Tty": true, 2700 "User": "123:456" 2701 } 2702 2703 **Example response**: 2704 2705 HTTP/1.1 201 Created 2706 Content-Type: application/json 2707 2708 { 2709 "Id": "f90e34656806", 2710 "Warnings":[] 2711 } 2712 2713 **JSON parameters**: 2714 2715 - **AttachStdin** - Boolean value, attaches to `stdin` of the `exec` command. 2716 - **AttachStdout** - Boolean value, attaches to `stdout` of the `exec` command. 2717 - **AttachStderr** - Boolean value, attaches to `stderr` of the `exec` command. 2718 - **DetachKeys** – Override the key sequence for detaching a 2719 container. Format is a single character `[a-Z]` or `ctrl-<value>` 2720 where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. 2721 - **Tty** - Boolean value to allocate a pseudo-TTY. 2722 - **Cmd** - Command to run specified as a string or an array of strings. 2723 - **Privileged** - Boolean value, runs the exec process with extended privileges. 2724 - **User** - A string value specifying the user, and optionally, group to run 2725 the exec process inside the container. Format is one of: `"user"`, 2726 `"user:group"`, `"uid"`, or `"uid:gid"`. 2727 2728 **Status codes**: 2729 2730 - **201** – no error 2731 - **404** – no such container 2732 - **409** - container is paused 2733 - **500** - server error 2734 2735 #### Exec Start 2736 2737 `POST /exec/(id)/start` 2738 2739 Starts a previously set up `exec` instance `id`. If `detach` is true, this API 2740 returns after starting the `exec` command. Otherwise, this API sets up an 2741 interactive session with the `exec` command. 2742 2743 **Example request**: 2744 2745 POST /v1.22/exec/e90e34656806/start HTTP/1.1 2746 Content-Type: application/json 2747 2748 { 2749 "Detach": false, 2750 "Tty": false 2751 } 2752 2753 **Example response**: 2754 2755 HTTP/1.1 200 OK 2756 Content-Type: application/vnd.docker.raw-stream 2757 2758 {% raw %} 2759 {{ STREAM }} 2760 {% endraw %} 2761 2762 **JSON parameters**: 2763 2764 - **Detach** - Detach from the `exec` command. 2765 - **Tty** - Boolean value to allocate a pseudo-TTY. 2766 2767 **Status codes**: 2768 2769 - **200** – no error 2770 - **404** – no such exec instance 2771 - **409** - container is paused 2772 2773 **Stream details**: 2774 2775 Similar to the stream behavior of `POST /containers/(id or name)/attach` API 2776 2777 #### Exec Resize 2778 2779 `POST /exec/(id)/resize` 2780 2781 Resizes the `tty` session used by the `exec` command `id`. The unit is number of characters. 2782 This API is valid only if `tty` was specified as part of creating and starting the `exec` command. 2783 2784 **Example request**: 2785 2786 POST /v1.22/exec/e90e34656806/resize?h=40&w=80 HTTP/1.1 2787 Content-Type: text/plain 2788 2789 **Example response**: 2790 2791 HTTP/1.1 201 Created 2792 Content-Type: text/plain 2793 2794 **Query parameters**: 2795 2796 - **h** – height of `tty` session 2797 - **w** – width 2798 2799 **Status codes**: 2800 2801 - **201** – no error 2802 - **404** – no such exec instance 2803 2804 #### Exec Inspect 2805 2806 `GET /exec/(id)/json` 2807 2808 Return low-level information about the `exec` command `id`. 2809 2810 **Example request**: 2811 2812 GET /v1.22/exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1 2813 2814 **Example response**: 2815 2816 HTTP/1.1 200 OK 2817 Content-Type: application/json 2818 2819 { 2820 "CanRemove": false, 2821 "ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126", 2822 "DetachKeys": "", 2823 "ExitCode": 2, 2824 "ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b", 2825 "OpenStderr": true, 2826 "OpenStdin": true, 2827 "OpenStdout": true, 2828 "ProcessConfig": { 2829 "arguments": [ 2830 "-c", 2831 "exit 2" 2832 ], 2833 "entrypoint": "sh", 2834 "privileged": false, 2835 "tty": true, 2836 "user": "1000" 2837 }, 2838 "Running": false 2839 } 2840 2841 **Status codes**: 2842 2843 - **200** – no error 2844 - **404** – no such exec instance 2845 - **500** - server error 2846 2847 ### 2.4 Volumes 2848 2849 #### List volumes 2850 2851 `GET /volumes` 2852 2853 **Example request**: 2854 2855 GET /v1.22/volumes HTTP/1.1 2856 2857 **Example response**: 2858 2859 HTTP/1.1 200 OK 2860 Content-Type: application/json 2861 2862 { 2863 "Volumes": [ 2864 { 2865 "Name": "tardis", 2866 "Driver": "local", 2867 "Mountpoint": "/var/lib/docker/volumes/tardis" 2868 } 2869 ], 2870 "Warnings": [] 2871 } 2872 2873 **Query parameters**: 2874 2875 - **filters** - JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. There is one available filter: `dangling=true` 2876 2877 **Status codes**: 2878 2879 - **200** - no error 2880 - **500** - server error 2881 2882 #### Create a volume 2883 2884 `POST /volumes/create` 2885 2886 Create a volume 2887 2888 **Example request**: 2889 2890 POST /v1.22/volumes/create HTTP/1.1 2891 Content-Type: application/json 2892 2893 { 2894 "Name": "tardis" 2895 } 2896 2897 **Example response**: 2898 2899 HTTP/1.1 201 Created 2900 Content-Type: application/json 2901 2902 { 2903 "Name": "tardis", 2904 "Driver": "local", 2905 "Mountpoint": "/var/lib/docker/volumes/tardis" 2906 } 2907 2908 **Status codes**: 2909 2910 - **201** - no error 2911 - **500** - server error 2912 2913 **JSON parameters**: 2914 2915 - **Name** - The new volume's name. If not specified, Docker generates a name. 2916 - **Driver** - Name of the volume driver to use. Defaults to `local` for the name. 2917 - **DriverOpts** - A mapping of driver options and values. These options are 2918 passed directly to the driver and are driver specific. 2919 2920 #### Inspect a volume 2921 2922 `GET /volumes/(name)` 2923 2924 Return low-level information on the volume `name` 2925 2926 **Example request**: 2927 2928 GET /volumes/tardis 2929 2930 **Example response**: 2931 2932 HTTP/1.1 200 OK 2933 Content-Type: application/json 2934 2935 { 2936 "Name": "tardis", 2937 "Driver": "local", 2938 "Mountpoint": "/var/lib/docker/volumes/tardis" 2939 } 2940 2941 **Status codes**: 2942 2943 - **200** - no error 2944 - **404** - no such volume 2945 - **500** - server error 2946 2947 #### Remove a volume 2948 2949 `DELETE /volumes/(name)` 2950 2951 Instruct the driver to remove the volume (`name`). 2952 2953 **Example request**: 2954 2955 DELETE /v1.22/volumes/tardis HTTP/1.1 2956 2957 **Example response**: 2958 2959 HTTP/1.1 204 No Content 2960 2961 **Status codes**: 2962 2963 - **204** - no error 2964 - **404** - no such volume or volume driver 2965 - **409** - volume is in use and cannot be removed 2966 - **500** - server error 2967 2968 ### 2.5 Networks 2969 2970 #### List networks 2971 2972 `GET /networks` 2973 2974 **Example request**: 2975 2976 GET /v1.22/networks?filters={"type":{"custom":true}} HTTP/1.1 2977 2978 **Example response**: 2979 2980 ``` 2981 HTTP/1.1 200 OK 2982 Content-Type: application/json 2983 2984 [ 2985 { 2986 "Name": "bridge", 2987 "Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566", 2988 "Scope": "local", 2989 "Driver": "bridge", 2990 "IPAM": { 2991 "Driver": "default", 2992 "Config": [ 2993 { 2994 "Subnet": "172.17.0.0/16" 2995 } 2996 ] 2997 }, 2998 "Containers": { 2999 "39b69226f9d79f5634485fb236a23b2fe4e96a0a94128390a7fbbcc167065867": { 3000 "EndpointID": "ed2419a97c1d9954d05b46e462e7002ea552f216e9b136b80a7db8d98b442eda", 3001 "MacAddress": "02:42:ac:11:00:02", 3002 "IPv4Address": "172.17.0.2/16", 3003 "IPv6Address": "" 3004 } 3005 }, 3006 "Options": { 3007 "com.docker.network.bridge.default_bridge": "true", 3008 "com.docker.network.bridge.enable_icc": "true", 3009 "com.docker.network.bridge.enable_ip_masquerade": "true", 3010 "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", 3011 "com.docker.network.bridge.name": "docker0", 3012 "com.docker.network.driver.mtu": "1500" 3013 } 3014 }, 3015 { 3016 "Name": "none", 3017 "Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794", 3018 "Scope": "local", 3019 "Driver": "null", 3020 "IPAM": { 3021 "Driver": "default", 3022 "Config": [] 3023 }, 3024 "Containers": {}, 3025 "Options": {} 3026 }, 3027 { 3028 "Name": "host", 3029 "Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e", 3030 "Scope": "local", 3031 "Driver": "host", 3032 "IPAM": { 3033 "Driver": "default", 3034 "Config": [] 3035 }, 3036 "Containers": {}, 3037 "Options": {} 3038 } 3039 ] 3040 ``` 3041 3042 **Query parameters**: 3043 3044 - **filters** - JSON encoded network list filter. The filter value is one of: 3045 - `id=<network-id>` Matches all or part of a network id. 3046 - `name=<network-name>` Matches all or part of a network name. 3047 - `type=["custom"|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. 3048 3049 **Status codes**: 3050 3051 - **200** - no error 3052 - **500** - server error 3053 3054 #### Inspect network 3055 3056 `GET /networks/<network-id>` 3057 3058 **Example request**: 3059 3060 GET /v1.22/networks/7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99 HTTP/1.1 3061 3062 **Example response**: 3063 3064 ``` 3065 HTTP/1.1 200 OK 3066 Content-Type: application/json 3067 3068 { 3069 "Name": "net01", 3070 "Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99", 3071 "Scope": "local", 3072 "Driver": "bridge", 3073 "IPAM": { 3074 "Driver": "default", 3075 "Config": [ 3076 { 3077 "Subnet": "172.19.0.0/16", 3078 "Gateway": "172.19.0.1/16" 3079 } 3080 ], 3081 "Options": { 3082 "foo": "bar" 3083 } 3084 }, 3085 "Containers": { 3086 "19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": { 3087 "Name": "test", 3088 "EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a", 3089 "MacAddress": "02:42:ac:13:00:02", 3090 "IPv4Address": "172.19.0.2/16", 3091 "IPv6Address": "" 3092 } 3093 }, 3094 "Options": { 3095 "com.docker.network.bridge.default_bridge": "true", 3096 "com.docker.network.bridge.enable_icc": "true", 3097 "com.docker.network.bridge.enable_ip_masquerade": "true", 3098 "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", 3099 "com.docker.network.bridge.name": "docker0", 3100 "com.docker.network.driver.mtu": "1500" 3101 } 3102 } 3103 ``` 3104 3105 **Status codes**: 3106 3107 - **200** - no error 3108 - **404** - network not found 3109 3110 #### Create a network 3111 3112 `POST /networks/create` 3113 3114 Create a network 3115 3116 **Example request**: 3117 3118 ``` 3119 POST /v1.22/networks/create HTTP/1.1 3120 Content-Type: application/json 3121 3122 { 3123 "Name":"isolated_nw", 3124 "CheckDuplicate":true, 3125 "Driver":"bridge", 3126 "IPAM":{ 3127 "Driver": "default", 3128 "Config":[ 3129 { 3130 "Subnet":"172.20.0.0/16", 3131 "IPRange":"172.20.10.0/24", 3132 "Gateway":"172.20.10.11" 3133 }, 3134 { 3135 "Subnet":"2001:db8:abcd::/64", 3136 "Gateway":"2001:db8:abcd::1011" 3137 } 3138 ], 3139 "Options": { 3140 "foo": "bar" 3141 } 3142 }, 3143 "Internal":true 3144 } 3145 ``` 3146 3147 **Example response**: 3148 3149 ``` 3150 HTTP/1.1 201 Created 3151 Content-Type: application/json 3152 3153 { 3154 "Id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30", 3155 "Warning": "" 3156 } 3157 ``` 3158 3159 **Status codes**: 3160 3161 - **201** - no error 3162 - **404** - plugin not found 3163 - **500** - server error 3164 3165 **JSON parameters**: 3166 3167 - **Name** - The new network's name. this is a mandatory field 3168 - **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false` 3169 - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver 3170 - **IPAM** - Optional custom IP scheme for the network 3171 - **Driver** - Name of the IPAM driver to use. Defaults to `default` driver 3172 - **Config** - List of IPAM configuration options, specified as a map: 3173 `{"Subnet": <CIDR>, "IPRange": <CIDR>, "Gateway": <IP address>, "AuxAddress": <device_name:IP address>}` 3174 - **Options** - Driver-specific options, specified as a map: `{"option":"value" [,"option2":"value2"]}` 3175 - **Options** - Network specific options to be used by the drivers 3176 3177 #### Connect a container to a network 3178 3179 `POST /networks/(id)/connect` 3180 3181 Connect a container to a network 3182 3183 **Example request**: 3184 3185 ``` 3186 POST /v1.22/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1 3187 Content-Type: application/json 3188 3189 { 3190 "Container":"3613f73ba0e4", 3191 "EndpointConfig": { 3192 "IPAMConfig": { 3193 "IPv4Address":"172.24.56.89", 3194 "IPv6Address":"2001:db8::5689" 3195 } 3196 } 3197 } 3198 ``` 3199 3200 **Example response**: 3201 3202 HTTP/1.1 200 OK 3203 3204 **Status codes**: 3205 3206 - **200** - no error 3207 - **404** - network or container is not found 3208 - **500** - Internal Server Error 3209 3210 **JSON parameters**: 3211 3212 - **container** - container-id/name to be connected to the network 3213 3214 #### Disconnect a container from a network 3215 3216 `POST /networks/(id)/disconnect` 3217 3218 Disconnect a container from a network 3219 3220 **Example request**: 3221 3222 ``` 3223 POST /v1.22/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1 3224 Content-Type: application/json 3225 3226 { 3227 "Container":"3613f73ba0e4", 3228 "Force":false 3229 } 3230 ``` 3231 3232 **Example response**: 3233 3234 HTTP/1.1 200 OK 3235 3236 **Status codes**: 3237 3238 - **200** - no error 3239 - **404** - network or container not found 3240 - **500** - Internal Server Error 3241 3242 **JSON parameters**: 3243 3244 - **Container** - container-id/name to be disconnected from a network 3245 - **Force** - Force the container to disconnect from a network 3246 3247 #### Remove a network 3248 3249 `DELETE /networks/(id)` 3250 3251 Instruct the driver to remove the network (`id`). 3252 3253 **Example request**: 3254 3255 DELETE /v1.22/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30 HTTP/1.1 3256 3257 **Example response**: 3258 3259 HTTP/1.1 200 OK 3260 3261 **Status codes**: 3262 3263 - **200** - no error 3264 - **404** - no such network 3265 - **500** - server error 3266 3267 ## 3. Going further 3268 3269 ### 3.1 Inside `docker run` 3270 3271 As an example, the `docker run` command line makes the following API calls: 3272 3273 - Create the container 3274 3275 - If the status code is 404, it means the image doesn't exist: 3276 - Try to pull it. 3277 - Then, retry to create the container. 3278 3279 - Start the container. 3280 3281 - If you are not in detached mode: 3282 - Attach to the container, using `logs=1` (to have `stdout` and 3283 `stderr` from the container's start) and `stream=1` 3284 3285 - If in detached mode or only `stdin` is attached, display the container's id. 3286 3287 ### 3.2 Hijacking 3288 3289 In this version of the API, `/attach`, uses hijacking to transport `stdin`, 3290 `stdout`, and `stderr` on the same socket. 3291 3292 To hint potential proxies about connection hijacking, Docker client sends 3293 connection upgrade headers similarly to websocket. 3294 3295 Upgrade: tcp 3296 Connection: Upgrade 3297 3298 When Docker daemon detects the `Upgrade` header, it switches its status code 3299 from **200 OK** to **101 UPGRADED** and resends the same headers. 3300 3301 3302 ### 3.3 CORS Requests 3303 3304 To set cross origin requests to the Engine API please give values to 3305 `--api-cors-header` when running Docker in daemon mode. Set * (asterisk) allows all, 3306 default or blank means CORS disabled 3307 3308 $ dockerd -H="192.168.1.9:2375" --api-cors-header="http://foo.bar"