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