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