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