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