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