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