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