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