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