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