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