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