github.com/yogeshlonkar/moby@v1.13.2-0.20201203103638-c0b64beaea94/docs/api/v1.24.md (about) 1 --- 2 title: "Engine API v1.24" 3 description: "API Documentation for Docker" 4 keywords: "API, Docker, rcli, REST, documentation" 5 redirect_from: 6 - /engine/reference/api/docker_remote_api_v1.24/ 7 - /reference/api/docker_remote_api_v1.24/ 8 --- 9 10 <!-- This file is maintained within the docker/docker Github 11 repository at https://github.com/docker/docker/. 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](../reference/commandline/dockerd.md#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 27 ## 2. Errors 28 29 The Engine API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format: 30 31 { 32 "message": "page not found" 33 } 34 35 The status codes that are returned for each endpoint are specified in the endpoint documentation below. 36 37 ## 3. Endpoints 38 39 ### 3.1 Containers 40 41 #### List containers 42 43 `GET /containers/json` 44 45 List containers 46 47 **Example request**: 48 49 GET /v1.24/containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 50 51 **Example response**: 52 53 HTTP/1.1 200 OK 54 Content-Type: application/json 55 56 [ 57 { 58 "Id": "8dfafdbc3a40", 59 "Names":["/boring_feynman"], 60 "Image": "ubuntu:latest", 61 "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", 62 "Command": "echo 1", 63 "Created": 1367854155, 64 "State": "Exited", 65 "Status": "Exit 0", 66 "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], 67 "Labels": { 68 "com.example.vendor": "Acme", 69 "com.example.license": "GPL", 70 "com.example.version": "1.0" 71 }, 72 "SizeRw": 12288, 73 "SizeRootFs": 0, 74 "HostConfig": { 75 "NetworkMode": "default" 76 }, 77 "NetworkSettings": { 78 "Networks": { 79 "bridge": { 80 "IPAMConfig": null, 81 "Links": null, 82 "Aliases": null, 83 "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812", 84 "EndpointID": "2cdc4edb1ded3631c81f57966563e5c8525b81121bb3706a9a9a3ae102711f3f", 85 "Gateway": "172.17.0.1", 86 "IPAddress": "172.17.0.2", 87 "IPPrefixLen": 16, 88 "IPv6Gateway": "", 89 "GlobalIPv6Address": "", 90 "GlobalIPv6PrefixLen": 0, 91 "MacAddress": "02:42:ac:11:00:02" 92 } 93 } 94 }, 95 "Mounts": [ 96 { 97 "Name": "fac362...80535", 98 "Source": "/data", 99 "Destination": "/data", 100 "Driver": "local", 101 "Mode": "ro,Z", 102 "RW": false, 103 "Propagation": "" 104 } 105 ] 106 }, 107 { 108 "Id": "9cd87474be90", 109 "Names":["/coolName"], 110 "Image": "ubuntu:latest", 111 "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", 112 "Command": "echo 222222", 113 "Created": 1367854155, 114 "State": "Exited", 115 "Status": "Exit 0", 116 "Ports": [], 117 "Labels": {}, 118 "SizeRw": 12288, 119 "SizeRootFs": 0, 120 "HostConfig": { 121 "NetworkMode": "default" 122 }, 123 "NetworkSettings": { 124 "Networks": { 125 "bridge": { 126 "IPAMConfig": null, 127 "Links": null, 128 "Aliases": null, 129 "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812", 130 "EndpointID": "88eaed7b37b38c2a3f0c4bc796494fdf51b270c2d22656412a2ca5d559a64d7a", 131 "Gateway": "172.17.0.1", 132 "IPAddress": "172.17.0.8", 133 "IPPrefixLen": 16, 134 "IPv6Gateway": "", 135 "GlobalIPv6Address": "", 136 "GlobalIPv6PrefixLen": 0, 137 "MacAddress": "02:42:ac:11:00:08" 138 } 139 } 140 }, 141 "Mounts": [] 142 }, 143 { 144 "Id": "3176a2479c92", 145 "Names":["/sleepy_dog"], 146 "Image": "ubuntu:latest", 147 "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", 148 "Command": "echo 3333333333333333", 149 "Created": 1367854154, 150 "State": "Exited", 151 "Status": "Exit 0", 152 "Ports":[], 153 "Labels": {}, 154 "SizeRw":12288, 155 "SizeRootFs":0, 156 "HostConfig": { 157 "NetworkMode": "default" 158 }, 159 "NetworkSettings": { 160 "Networks": { 161 "bridge": { 162 "IPAMConfig": null, 163 "Links": null, 164 "Aliases": null, 165 "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812", 166 "EndpointID": "8b27c041c30326d59cd6e6f510d4f8d1d570a228466f956edf7815508f78e30d", 167 "Gateway": "172.17.0.1", 168 "IPAddress": "172.17.0.6", 169 "IPPrefixLen": 16, 170 "IPv6Gateway": "", 171 "GlobalIPv6Address": "", 172 "GlobalIPv6PrefixLen": 0, 173 "MacAddress": "02:42:ac:11:00:06" 174 } 175 } 176 }, 177 "Mounts": [] 178 }, 179 { 180 "Id": "4cb07b47f9fb", 181 "Names":["/running_cat"], 182 "Image": "ubuntu:latest", 183 "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", 184 "Command": "echo 444444444444444444444444444444444", 185 "Created": 1367854152, 186 "State": "Exited", 187 "Status": "Exit 0", 188 "Ports": [], 189 "Labels": {}, 190 "SizeRw": 12288, 191 "SizeRootFs": 0, 192 "HostConfig": { 193 "NetworkMode": "default" 194 }, 195 "NetworkSettings": { 196 "Networks": { 197 "bridge": { 198 "IPAMConfig": null, 199 "Links": null, 200 "Aliases": null, 201 "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812", 202 "EndpointID": "d91c7b2f0644403d7ef3095985ea0e2370325cd2332ff3a3225c4247328e66e9", 203 "Gateway": "172.17.0.1", 204 "IPAddress": "172.17.0.5", 205 "IPPrefixLen": 16, 206 "IPv6Gateway": "", 207 "GlobalIPv6Address": "", 208 "GlobalIPv6PrefixLen": 0, 209 "MacAddress": "02:42:ac:11:00:05" 210 } 211 } 212 }, 213 "Mounts": [] 214 } 215 ] 216 217 **Query parameters**: 218 219 - **all** – 1/True/true or 0/False/false, Show all containers. 220 Only running containers are shown by default (i.e., this defaults to false) 221 - **limit** – Show `limit` last created 222 containers, include non-running ones. 223 - **since** – Show only containers created since Id, include 224 non-running ones. 225 - **before** – Show only containers created before Id, include 226 non-running ones. 227 - **size** – 1/True/true or 0/False/false, Show the containers 228 sizes 229 - **filters** - a JSON encoded value of the filters (a `map[string][]string`) to process on the containers list. Available filters: 230 - `exited=<int>`; -- containers with exit code of `<int>` ; 231 - `status=`(`created`|`restarting`|`running`|`paused`|`exited`|`dead`) 232 - `label=key` or `label="key=value"` of a container label 233 - `isolation=`(`default`|`process`|`hyperv`) (Windows daemon only) 234 - `ancestor`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) 235 - `before`=(`<container id>` or `<container name>`) 236 - `since`=(`<container id>` or `<container name>`) 237 - `volume`=(`<volume name>` or `<mount point destination>`) 238 - `network`=(`<network id>` or `<network name>`) 239 240 **Status codes**: 241 242 - **200** – no error 243 - **400** – bad parameter 244 - **500** – server error 245 246 #### Create a container 247 248 `POST /containers/create` 249 250 Create a container 251 252 **Example request**: 253 254 POST /v1.24/containers/create HTTP/1.1 255 Content-Type: application/json 256 257 { 258 "Hostname": "", 259 "Domainname": "", 260 "User": "", 261 "AttachStdin": false, 262 "AttachStdout": true, 263 "AttachStderr": true, 264 "Tty": false, 265 "OpenStdin": false, 266 "StdinOnce": false, 267 "Env": [ 268 "FOO=bar", 269 "BAZ=quux" 270 ], 271 "Cmd": [ 272 "date" 273 ], 274 "Entrypoint": "", 275 "Image": "ubuntu", 276 "Labels": { 277 "com.example.vendor": "Acme", 278 "com.example.license": "GPL", 279 "com.example.version": "1.0" 280 }, 281 "Volumes": { 282 "/volumes/data": {} 283 }, 284 "WorkingDir": "", 285 "NetworkDisabled": false, 286 "MacAddress": "12:34:56:78:9a:bc", 287 "ExposedPorts": { 288 "22/tcp": {} 289 }, 290 "StopSignal": "SIGTERM", 291 "HostConfig": { 292 "Binds": ["/tmp:/tmp"], 293 "Tmpfs": { "/run": "rw,noexec,nosuid,size=65536k" }, 294 "Links": ["redis3:redis"], 295 "Memory": 0, 296 "MemorySwap": 0, 297 "MemoryReservation": 0, 298 "KernelMemory": 0, 299 "CpuPercent": 80, 300 "CpuShares": 512, 301 "CpuPeriod": 100000, 302 "CpuQuota": 50000, 303 "CpusetCpus": "0,1", 304 "CpusetMems": "0,1", 305 "IOMaximumBandwidth": 0, 306 "IOMaximumIOps": 0, 307 "BlkioWeight": 300, 308 "BlkioWeightDevice": [{}], 309 "BlkioDeviceReadBps": [{}], 310 "BlkioDeviceReadIOps": [{}], 311 "BlkioDeviceWriteBps": [{}], 312 "BlkioDeviceWriteIOps": [{}], 313 "MemorySwappiness": 60, 314 "OomKillDisable": false, 315 "OomScoreAdj": 500, 316 "PidMode": "", 317 "PidsLimit": -1, 318 "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] }, 319 "PublishAllPorts": false, 320 "Privileged": false, 321 "ReadonlyRootfs": false, 322 "Dns": ["8.8.8.8"], 323 "DnsOptions": [""], 324 "DnsSearch": [""], 325 "ExtraHosts": null, 326 "VolumesFrom": ["parent", "other:ro"], 327 "CapAdd": ["NET_ADMIN"], 328 "CapDrop": ["MKNOD"], 329 "GroupAdd": ["newgroup"], 330 "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 }, 331 "NetworkMode": "bridge", 332 "Devices": [], 333 "Sysctls": { "net.ipv4.ip_forward": "1" }, 334 "Ulimits": [{}], 335 "LogConfig": { "Type": "json-file", "Config": {} }, 336 "SecurityOpt": [], 337 "StorageOpt": {}, 338 "CgroupParent": "", 339 "VolumeDriver": "", 340 "ShmSize": 67108864 341 }, 342 "NetworkingConfig": { 343 "EndpointsConfig": { 344 "isolated_nw" : { 345 "IPAMConfig": { 346 "IPv4Address":"172.20.30.33", 347 "IPv6Address":"2001:db8:abcd::3033", 348 "LinkLocalIPs":["169.254.34.68", "fe80::3468"] 349 }, 350 "Links":["container_1", "container_2"], 351 "Aliases":["server_x", "server_y"] 352 } 353 } 354 } 355 } 356 357 **Example response**: 358 359 HTTP/1.1 201 Created 360 Content-Type: application/json 361 362 { 363 "Id":"e90e34656806", 364 "Warnings":[] 365 } 366 367 **JSON parameters**: 368 369 - **Hostname** - A string value containing the hostname to use for the 370 container. This must be a valid RFC 1123 hostname. 371 - **Domainname** - A string value containing the domain name to use 372 for the container. 373 - **User** - A string value specifying the user inside the container. 374 - **AttachStdin** - Boolean value, attaches to `stdin`. 375 - **AttachStdout** - Boolean value, attaches to `stdout`. 376 - **AttachStderr** - Boolean value, attaches to `stderr`. 377 - **Tty** - Boolean value, Attach standard streams to a `tty`, including `stdin` if it is not closed. 378 - **OpenStdin** - Boolean value, opens `stdin`, 379 - **StdinOnce** - Boolean value, close `stdin` after the 1 attached client disconnects. 380 - **Env** - A list of environment variables in the form of `["VAR=value", ...]` 381 - **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value", ... }` 382 - **Cmd** - Command to run specified as a string or an array of strings. 383 - **Entrypoint** - Set the entry point for the container as a string or an array 384 of strings. 385 - **Image** - A string specifying the image name to use for the container. 386 - **Volumes** - An object mapping mount point paths (strings) inside the 387 container to empty objects. 388 - **WorkingDir** - A string specifying the working directory for commands to 389 run in. 390 - **NetworkDisabled** - Boolean value, when true disables networking for the 391 container 392 - **ExposedPorts** - An object mapping ports to an empty object in the form of: 393 `"ExposedPorts": { "<port>/<tcp|udp>: {}" }` 394 - **StopSignal** - Signal to stop a container as a string or unsigned integer. `SIGTERM` by default. 395 - **HostConfig** 396 - **Binds** – A list of volume bindings for this container. Each volume binding is a string in one of these forms: 397 + `host-src:container-dest` to bind-mount a host path into the 398 container. Both `host-src`, and `container-dest` must be an 399 _absolute_ path. 400 + `host-src:container-dest:ro` to make the bind-mount read-only 401 inside the container. Both `host-src`, and `container-dest` must be 402 an _absolute_ path. 403 + `volume-name:container-dest` to bind-mount a volume managed by a 404 volume driver into the container. `container-dest` must be an 405 _absolute_ path. 406 + `volume-name:container-dest:ro` to mount the volume read-only 407 inside the container. `container-dest` must be an _absolute_ path. 408 - **Tmpfs** – A map of container directories which should be replaced by tmpfs mounts, and their corresponding 409 mount options. A JSON object in the form `{ "/run": "rw,noexec,nosuid,size=65536k" }`. 410 - **Links** - A list of links for the container. Each link entry should be 411 in the form of `container_name:alias`. 412 - **Memory** - Memory limit in bytes. 413 - **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap. 414 You must use this with `memory` and make the swap value larger than `memory`. 415 - **MemoryReservation** - Memory soft limit in bytes. 416 - **KernelMemory** - Kernel memory limit in bytes. 417 - **CpuPercent** - An integer value containing the usable percentage of the available CPUs. (Windows daemon only) 418 - **CpuShares** - An integer value containing the container's CPU Shares 419 (ie. the relative weight vs other containers). 420 - **CpuPeriod** - The length of a CPU period in microseconds. 421 - **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period. 422 - **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use. 423 - **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. 424 - **IOMaximumBandwidth** - Maximum IO absolute rate in terms of IOps. 425 - **IOMaximumIOps** - Maximum IO absolute rate in terms of bytes per second. 426 - **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000. 427 - **BlkioWeightDevice** - Block IO weight (relative device weight) in the form of: `"BlkioWeightDevice": [{"Path": "device_path", "Weight": weight}]` 428 - **BlkioDeviceReadBps** - Limit read rate (bytes per second) from a device in the form of: `"BlkioDeviceReadBps": [{"Path": "device_path", "Rate": rate}]`, for example: 429 `"BlkioDeviceReadBps": [{"Path": "/dev/sda", "Rate": "1024"}]"` 430 - **BlkioDeviceWriteBps** - Limit write rate (bytes per second) to a device in the form of: `"BlkioDeviceWriteBps": [{"Path": "device_path", "Rate": rate}]`, for example: 431 `"BlkioDeviceWriteBps": [{"Path": "/dev/sda", "Rate": "1024"}]"` 432 - **BlkioDeviceReadIOps** - Limit read rate (IO per second) from a device in the form of: `"BlkioDeviceReadIOps": [{"Path": "device_path", "Rate": rate}]`, for example: 433 `"BlkioDeviceReadIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` 434 - **BlkioDeviceWriteIOps** - Limit write rate (IO per second) to a device in the form of: `"BlkioDeviceWriteIOps": [{"Path": "device_path", "Rate": rate}]`, for example: 435 `"BlkioDeviceWriteIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` 436 - **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. 437 - **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. 438 - **OomScoreAdj** - An integer value containing the score given to the container in order to tune OOM killer preferences. 439 - **PidMode** - Set the PID (Process) Namespace mode for the container; 440 `"container:<name|id>"`: joins another container's PID namespace 441 `"host"`: use the host's PID namespace inside the container 442 - **PidsLimit** - Tune a container's pids limit. Set -1 for unlimited. 443 - **PortBindings** - A map of exposed container ports and the host port they 444 should map to. A JSON object in the form 445 `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }` 446 Take note that `port` is specified as a string and not an integer value. 447 - **PublishAllPorts** - Allocates a random host port for all of a container's 448 exposed ports. Specified as a boolean value. 449 - **Privileged** - Gives the container full access to the host. Specified as 450 a boolean value. 451 - **ReadonlyRootfs** - Mount the container's root filesystem as read only. 452 Specified as a boolean value. 453 - **Dns** - A list of DNS servers for the container to use. 454 - **DnsOptions** - A list of DNS options 455 - **DnsSearch** - A list of DNS search domains 456 - **ExtraHosts** - A list of hostnames/IP mappings to add to the 457 container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`. 458 - **VolumesFrom** - A list of volumes to inherit from another container. 459 Specified in the form `<container name>[:<ro|rw>]` 460 - **CapAdd** - A list of kernel capabilities to add to the container. 461 - **Capdrop** - A list of kernel capabilities to drop from the container. 462 - **GroupAdd** - A list of additional groups that the container process will run as 463 - **RestartPolicy** – The behavior to apply when the container exits. The 464 value is an object with a `Name` property of either `"always"` to 465 always restart, `"unless-stopped"` to restart always except when 466 user has manually stopped the container or `"on-failure"` to restart only when the container 467 exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` 468 controls the number of times to retry before giving up. 469 The default is not to restart. (optional) 470 An ever increasing delay (double the previous delay, starting at 100mS) 471 is added before each restart to prevent flooding the server. 472 - **UsernsMode** - Sets the usernamespace mode for the container when usernamespace remapping option is enabled. 473 supported values are: `host`. 474 - **NetworkMode** - Sets the networking mode for the container. Supported 475 standard values are: `bridge`, `host`, `none`, and `container:<name|id>`. Any other value is taken 476 as a custom network's name to which this container should connect to. 477 - **Devices** - A list of devices to add to the container specified as a JSON object in the 478 form 479 `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}` 480 - **Ulimits** - A list of ulimits to set in the container, specified as 481 `{ "Name": <name>, "Soft": <soft limit>, "Hard": <hard limit> }`, for example: 482 `Ulimits: { "Name": "nofile", "Soft": 1024, "Hard": 2048 }` 483 - **Sysctls** - A list of kernel parameters (sysctls) to set in the container, specified as 484 `{ <name>: <Value> }`, for example: 485 `{ "net.ipv4.ip_forward": "1" }` 486 - **SecurityOpt**: A list of string values to customize labels for MLS 487 systems, such as SELinux. 488 - **StorageOpt**: Storage driver options per container. Options can be passed in the form 489 `{"size":"120G"}` 490 - **LogConfig** - Log configuration for the container, specified as a JSON object in the form 491 `{ "Type": "<driver_name>", "Config": {"key1": "val1"}}`. 492 Available types: `json-file`, `syslog`, `journald`, `gelf`, `fluentd`, `awslogs`, `splunk`, `etwlogs`, `none`. 493 `json-file` logging driver. 494 - **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. 495 - **VolumeDriver** - Driver that this container users to mount volumes. 496 - **ShmSize** - Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB. 497 498 **Query parameters**: 499 500 - **name** – Assign the specified name to the container. Must 501 match `/?[a-zA-Z0-9_-]+`. 502 503 **Status codes**: 504 505 - **201** – no error 506 - **400** – bad parameter 507 - **404** – no such container 508 - **406** – impossible to attach (container not running) 509 - **409** – conflict 510 - **500** – server error 511 512 #### Inspect a container 513 514 `GET /containers/(id or name)/json` 515 516 Return low-level information on the container `id` 517 518 **Example request**: 519 520 GET /v1.24/containers/4fa6e0f0c678/json HTTP/1.1 521 522 **Example response**: 523 524 HTTP/1.1 200 OK 525 Content-Type: application/json 526 527 { 528 "AppArmorProfile": "", 529 "Args": [ 530 "-c", 531 "exit 9" 532 ], 533 "Config": { 534 "AttachStderr": true, 535 "AttachStdin": false, 536 "AttachStdout": true, 537 "Cmd": [ 538 "/bin/sh", 539 "-c", 540 "exit 9" 541 ], 542 "Domainname": "", 543 "Entrypoint": null, 544 "Env": [ 545 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 546 ], 547 "ExposedPorts": null, 548 "Hostname": "ba033ac44011", 549 "Image": "ubuntu", 550 "Labels": { 551 "com.example.vendor": "Acme", 552 "com.example.license": "GPL", 553 "com.example.version": "1.0" 554 }, 555 "MacAddress": "", 556 "NetworkDisabled": false, 557 "OnBuild": null, 558 "OpenStdin": false, 559 "StdinOnce": false, 560 "Tty": false, 561 "User": "", 562 "Volumes": { 563 "/volumes/data": {} 564 }, 565 "WorkingDir": "", 566 "StopSignal": "SIGTERM" 567 }, 568 "Created": "2015-01-06T15:47:31.485331387Z", 569 "Driver": "devicemapper", 570 "ExecIDs": null, 571 "HostConfig": { 572 "Binds": null, 573 "IOMaximumBandwidth": 0, 574 "IOMaximumIOps": 0, 575 "BlkioWeight": 0, 576 "BlkioWeightDevice": [{}], 577 "BlkioDeviceReadBps": [{}], 578 "BlkioDeviceWriteBps": [{}], 579 "BlkioDeviceReadIOps": [{}], 580 "BlkioDeviceWriteIOps": [{}], 581 "CapAdd": null, 582 "CapDrop": null, 583 "ContainerIDFile": "", 584 "CpusetCpus": "", 585 "CpusetMems": "", 586 "CpuPercent": 80, 587 "CpuShares": 0, 588 "CpuPeriod": 100000, 589 "Devices": [], 590 "Dns": null, 591 "DnsOptions": null, 592 "DnsSearch": null, 593 "ExtraHosts": null, 594 "IpcMode": "", 595 "Links": null, 596 "LxcConf": [], 597 "Memory": 0, 598 "MemorySwap": 0, 599 "MemoryReservation": 0, 600 "KernelMemory": 0, 601 "OomKillDisable": false, 602 "OomScoreAdj": 500, 603 "NetworkMode": "bridge", 604 "PidMode": "", 605 "PortBindings": {}, 606 "Privileged": false, 607 "ReadonlyRootfs": false, 608 "PublishAllPorts": false, 609 "RestartPolicy": { 610 "MaximumRetryCount": 2, 611 "Name": "on-failure" 612 }, 613 "LogConfig": { 614 "Config": null, 615 "Type": "json-file" 616 }, 617 "SecurityOpt": null, 618 "Sysctls": { 619 "net.ipv4.ip_forward": "1" 620 }, 621 "StorageOpt": null, 622 "VolumesFrom": null, 623 "Ulimits": [{}], 624 "VolumeDriver": "", 625 "ShmSize": 67108864 626 }, 627 "HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname", 628 "HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts", 629 "LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log", 630 "Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39", 631 "Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2", 632 "MountLabel": "", 633 "Name": "/boring_euclid", 634 "NetworkSettings": { 635 "Bridge": "", 636 "SandboxID": "", 637 "HairpinMode": false, 638 "LinkLocalIPv6Address": "", 639 "LinkLocalIPv6PrefixLen": 0, 640 "Ports": null, 641 "SandboxKey": "", 642 "SecondaryIPAddresses": null, 643 "SecondaryIPv6Addresses": null, 644 "EndpointID": "", 645 "Gateway": "", 646 "GlobalIPv6Address": "", 647 "GlobalIPv6PrefixLen": 0, 648 "IPAddress": "", 649 "IPPrefixLen": 0, 650 "IPv6Gateway": "", 651 "MacAddress": "", 652 "Networks": { 653 "bridge": { 654 "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812", 655 "EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d", 656 "Gateway": "172.17.0.1", 657 "IPAddress": "172.17.0.2", 658 "IPPrefixLen": 16, 659 "IPv6Gateway": "", 660 "GlobalIPv6Address": "", 661 "GlobalIPv6PrefixLen": 0, 662 "MacAddress": "02:42:ac:12:00:02" 663 } 664 } 665 }, 666 "Path": "/bin/sh", 667 "ProcessLabel": "", 668 "ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf", 669 "RestartCount": 1, 670 "State": { 671 "Error": "", 672 "ExitCode": 9, 673 "FinishedAt": "2015-01-06T15:47:32.080254511Z", 674 "OOMKilled": false, 675 "Dead": false, 676 "Paused": false, 677 "Pid": 0, 678 "Restarting": false, 679 "Running": true, 680 "StartedAt": "2015-01-06T15:47:32.072697474Z", 681 "Status": "running" 682 }, 683 "Mounts": [ 684 { 685 "Name": "fac362...80535", 686 "Source": "/data", 687 "Destination": "/data", 688 "Driver": "local", 689 "Mode": "ro,Z", 690 "RW": false, 691 "Propagation": "" 692 } 693 ] 694 } 695 696 **Example request, with size information**: 697 698 GET /v1.24/containers/4fa6e0f0c678/json?size=1 HTTP/1.1 699 700 **Example response, with size information**: 701 702 HTTP/1.1 200 OK 703 Content-Type: application/json 704 705 { 706 .... 707 "SizeRw": 0, 708 "SizeRootFs": 972, 709 .... 710 } 711 712 **Query parameters**: 713 714 - **size** – 1/True/true or 0/False/false, return container size information. Default is `false`. 715 716 **Status codes**: 717 718 - **200** – no error 719 - **404** – no such container 720 - **500** – server error 721 722 #### List processes running inside a container 723 724 `GET /containers/(id or name)/top` 725 726 List processes running inside the container `id`. On Unix systems this 727 is done by running the `ps` command. This endpoint is not 728 supported on Windows. 729 730 **Example request**: 731 732 GET /v1.24/containers/4fa6e0f0c678/top HTTP/1.1 733 734 **Example response**: 735 736 HTTP/1.1 200 OK 737 Content-Type: application/json 738 739 { 740 "Titles" : [ 741 "UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD" 742 ], 743 "Processes" : [ 744 [ 745 "root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash" 746 ], 747 [ 748 "root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10" 749 ] 750 ] 751 } 752 753 **Example request**: 754 755 GET /v1.24/containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1 756 757 **Example response**: 758 759 HTTP/1.1 200 OK 760 Content-Type: application/json 761 762 { 763 "Titles" : [ 764 "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND" 765 ] 766 "Processes" : [ 767 [ 768 "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash" 769 ], 770 [ 771 "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10" 772 ] 773 ], 774 } 775 776 **Query parameters**: 777 778 - **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef` 779 780 **Status codes**: 781 782 - **200** – no error 783 - **404** – no such container 784 - **500** – server error 785 786 #### Get container logs 787 788 `GET /containers/(id or name)/logs` 789 790 Get `stdout` and `stderr` logs from the container ``id`` 791 792 > **Note**: 793 > This endpoint works only for containers with the `json-file` or `journald` logging drivers. 794 795 **Example request**: 796 797 GET /v1.24/containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10&since=1428990821 HTTP/1.1 798 799 **Example response**: 800 801 HTTP/1.1 101 UPGRADED 802 Content-Type: application/vnd.docker.raw-stream 803 Connection: Upgrade 804 Upgrade: tcp 805 806 {% raw %} 807 {{ STREAM }} 808 {% endraw %} 809 810 **Query parameters**: 811 812 - **details** - 1/True/true or 0/False/flase, Show extra details provided to logs. Default `false`. 813 - **follow** – 1/True/true or 0/False/false, return stream. Default `false`. 814 - **stdout** – 1/True/true or 0/False/false, show `stdout` log. Default `false`. 815 - **stderr** – 1/True/true or 0/False/false, show `stderr` log. Default `false`. 816 - **since** – UNIX timestamp (integer) to filter logs. Specifying a timestamp 817 will only output log-entries since that timestamp. Default: 0 (unfiltered) 818 - **timestamps** – 1/True/true or 0/False/false, print timestamps for 819 every log line. Default `false`. 820 - **tail** – Output specified number of lines at the end of logs: `all` or `<number>`. Default all. 821 822 **Status codes**: 823 824 - **101** – no error, hints proxy about hijacking 825 - **200** – no error, no upgrade header found 826 - **404** – no such container 827 - **500** – server error 828 829 #### Inspect changes on a container's filesystem 830 831 `GET /containers/(id or name)/changes` 832 833 Inspect changes on container `id`'s filesystem 834 835 **Example request**: 836 837 GET /v1.24/containers/4fa6e0f0c678/changes HTTP/1.1 838 839 **Example response**: 840 841 HTTP/1.1 200 OK 842 Content-Type: application/json 843 844 [ 845 { 846 "Path": "/dev", 847 "Kind": 0 848 }, 849 { 850 "Path": "/dev/kmsg", 851 "Kind": 1 852 }, 853 { 854 "Path": "/test", 855 "Kind": 1 856 } 857 ] 858 859 Values for `Kind`: 860 861 - `0`: Modify 862 - `1`: Add 863 - `2`: Delete 864 865 **Status codes**: 866 867 - **200** – no error 868 - **404** – no such container 869 - **500** – server error 870 871 #### Export a container 872 873 `GET /containers/(id or name)/export` 874 875 Export the contents of container `id` 876 877 **Example request**: 878 879 GET /v1.24/containers/4fa6e0f0c678/export HTTP/1.1 880 881 **Example response**: 882 883 HTTP/1.1 200 OK 884 Content-Type: application/octet-stream 885 886 {% raw %} 887 {{ TAR STREAM }} 888 {% endraw %} 889 890 **Status codes**: 891 892 - **200** – no error 893 - **404** – no such container 894 - **500** – server error 895 896 #### Get container stats based on resource usage 897 898 `GET /containers/(id or name)/stats` 899 900 This endpoint returns a live stream of a container's resource usage statistics. 901 902 **Example request**: 903 904 GET /v1.24/containers/redis1/stats HTTP/1.1 905 906 **Example response**: 907 908 HTTP/1.1 200 OK 909 Content-Type: application/json 910 911 { 912 "read" : "2015-01-08T22:57:31.547920715Z", 913 "pids_stats": { 914 "current": 3 915 }, 916 "networks": { 917 "eth0": { 918 "rx_bytes": 5338, 919 "rx_dropped": 0, 920 "rx_errors": 0, 921 "rx_packets": 36, 922 "tx_bytes": 648, 923 "tx_dropped": 0, 924 "tx_errors": 0, 925 "tx_packets": 8 926 }, 927 "eth5": { 928 "rx_bytes": 4641, 929 "rx_dropped": 0, 930 "rx_errors": 0, 931 "rx_packets": 26, 932 "tx_bytes": 690, 933 "tx_dropped": 0, 934 "tx_errors": 0, 935 "tx_packets": 9 936 } 937 }, 938 "memory_stats" : { 939 "stats" : { 940 "total_pgmajfault" : 0, 941 "cache" : 0, 942 "mapped_file" : 0, 943 "total_inactive_file" : 0, 944 "pgpgout" : 414, 945 "rss" : 6537216, 946 "total_mapped_file" : 0, 947 "writeback" : 0, 948 "unevictable" : 0, 949 "pgpgin" : 477, 950 "total_unevictable" : 0, 951 "pgmajfault" : 0, 952 "total_rss" : 6537216, 953 "total_rss_huge" : 6291456, 954 "total_writeback" : 0, 955 "total_inactive_anon" : 0, 956 "rss_huge" : 6291456, 957 "hierarchical_memory_limit" : 67108864, 958 "total_pgfault" : 964, 959 "total_active_file" : 0, 960 "active_anon" : 6537216, 961 "total_active_anon" : 6537216, 962 "total_pgpgout" : 414, 963 "total_cache" : 0, 964 "inactive_anon" : 0, 965 "active_file" : 0, 966 "pgfault" : 964, 967 "inactive_file" : 0, 968 "total_pgpgin" : 477 969 }, 970 "max_usage" : 6651904, 971 "usage" : 6537216, 972 "failcnt" : 0, 973 "limit" : 67108864 974 }, 975 "blkio_stats" : {}, 976 "cpu_stats" : { 977 "cpu_usage" : { 978 "percpu_usage" : [ 979 8646879, 980 24472255, 981 36438778, 982 30657443 983 ], 984 "usage_in_usermode" : 50000000, 985 "total_usage" : 100215355, 986 "usage_in_kernelmode" : 30000000 987 }, 988 "system_cpu_usage" : 739306590000000, 989 "throttling_data" : {"periods":0,"throttled_periods":0,"throttled_time":0} 990 }, 991 "precpu_stats" : { 992 "cpu_usage" : { 993 "percpu_usage" : [ 994 8646879, 995 24350896, 996 36438778, 997 30657443 998 ], 999 "usage_in_usermode" : 50000000, 1000 "total_usage" : 100093996, 1001 "usage_in_kernelmode" : 30000000 1002 }, 1003 "system_cpu_usage" : 9492140000000, 1004 "throttling_data" : {"periods":0,"throttled_periods":0,"throttled_time":0} 1005 } 1006 } 1007 1008 The precpu_stats is the cpu statistic of last read, which is used for calculating the cpu usage percent. It is not the exact copy of the “cpu_stats” field. 1009 1010 **Query parameters**: 1011 1012 - **stream** – 1/True/true or 0/False/false, pull stats once then disconnect. Default `true`. 1013 1014 **Status codes**: 1015 1016 - **200** – no error 1017 - **404** – no such container 1018 - **500** – server error 1019 1020 #### Resize a container TTY 1021 1022 `POST /containers/(id or name)/resize` 1023 1024 Resize the TTY for container with `id`. The unit is number of characters. You must restart the container for the resize to take effect. 1025 1026 **Example request**: 1027 1028 POST /v1.24/containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1 1029 1030 **Example response**: 1031 1032 HTTP/1.1 200 OK 1033 Content-Length: 0 1034 Content-Type: text/plain; charset=utf-8 1035 1036 **Query parameters**: 1037 1038 - **h** – height of `tty` session 1039 - **w** – width 1040 1041 **Status codes**: 1042 1043 - **200** – no error 1044 - **404** – No such container 1045 - **500** – Cannot resize container 1046 1047 #### Start a container 1048 1049 `POST /containers/(id or name)/start` 1050 1051 Start the container `id` 1052 1053 **Example request**: 1054 1055 POST /v1.24/containers/e90e34656806/start HTTP/1.1 1056 1057 **Example response**: 1058 1059 HTTP/1.1 204 No Content 1060 1061 **Query parameters**: 1062 1063 - **detachKeys** – Override the key sequence for detaching a 1064 container. Format is a single character `[a-Z]` or `ctrl-<value>` 1065 where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. 1066 1067 **Status codes**: 1068 1069 - **204** – no error 1070 - **304** – container already started 1071 - **404** – no such container 1072 - **500** – server error 1073 1074 #### Stop a container 1075 1076 `POST /containers/(id or name)/stop` 1077 1078 Stop the container `id` 1079 1080 **Example request**: 1081 1082 POST /v1.24/containers/e90e34656806/stop?t=5 HTTP/1.1 1083 1084 **Example response**: 1085 1086 HTTP/1.1 204 No Content 1087 1088 **Query parameters**: 1089 1090 - **t** – number of seconds to wait before killing the container 1091 1092 **Status codes**: 1093 1094 - **204** – no error 1095 - **304** – container already stopped 1096 - **404** – no such container 1097 - **500** – server error 1098 1099 #### Restart a container 1100 1101 `POST /containers/(id or name)/restart` 1102 1103 Restart the container `id` 1104 1105 **Example request**: 1106 1107 POST /v1.24/containers/e90e34656806/restart?t=5 HTTP/1.1 1108 1109 **Example response**: 1110 1111 HTTP/1.1 204 No Content 1112 1113 **Query parameters**: 1114 1115 - **t** – number of seconds to wait before killing the container 1116 1117 **Status codes**: 1118 1119 - **204** – no error 1120 - **404** – no such container 1121 - **500** – server error 1122 1123 #### Kill a container 1124 1125 `POST /containers/(id or name)/kill` 1126 1127 Kill the container `id` 1128 1129 **Example request**: 1130 1131 POST /v1.24/containers/e90e34656806/kill HTTP/1.1 1132 1133 **Example response**: 1134 1135 HTTP/1.1 204 No Content 1136 1137 **Query parameters**: 1138 1139 - **signal** - Signal to send to the container: integer or string like `SIGINT`. 1140 When not set, `SIGKILL` is assumed and the call waits for the container to exit. 1141 1142 **Status codes**: 1143 1144 - **204** – no error 1145 - **404** – no such container 1146 - **500** – server error 1147 1148 #### Update a container 1149 1150 `POST /containers/(id or name)/update` 1151 1152 Update configuration of one or more containers. 1153 1154 **Example request**: 1155 1156 POST /v1.24/containers/e90e34656806/update HTTP/1.1 1157 Content-Type: application/json 1158 1159 { 1160 "BlkioWeight": 300, 1161 "CpuShares": 512, 1162 "CpuPeriod": 100000, 1163 "CpuQuota": 50000, 1164 "CpusetCpus": "0,1", 1165 "CpusetMems": "0", 1166 "Memory": 314572800, 1167 "MemorySwap": 514288000, 1168 "MemoryReservation": 209715200, 1169 "KernelMemory": 52428800, 1170 "RestartPolicy": { 1171 "MaximumRetryCount": 4, 1172 "Name": "on-failure" 1173 } 1174 } 1175 1176 **Example response**: 1177 1178 HTTP/1.1 200 OK 1179 Content-Type: application/json 1180 1181 { 1182 "Warnings": [] 1183 } 1184 1185 **Status codes**: 1186 1187 - **200** – no error 1188 - **400** – bad parameter 1189 - **404** – no such container 1190 - **500** – server error 1191 1192 #### Rename a container 1193 1194 `POST /containers/(id or name)/rename` 1195 1196 Rename the container `id` to a `new_name` 1197 1198 **Example request**: 1199 1200 POST /v1.24/containers/e90e34656806/rename?name=new_name HTTP/1.1 1201 1202 **Example response**: 1203 1204 HTTP/1.1 204 No Content 1205 1206 **Query parameters**: 1207 1208 - **name** – new name for the container 1209 1210 **Status codes**: 1211 1212 - **204** – no error 1213 - **404** – no such container 1214 - **409** - conflict name already assigned 1215 - **500** – server error 1216 1217 #### Pause a container 1218 1219 `POST /containers/(id or name)/pause` 1220 1221 Pause the container `id` 1222 1223 **Example request**: 1224 1225 POST /v1.24/containers/e90e34656806/pause HTTP/1.1 1226 1227 **Example response**: 1228 1229 HTTP/1.1 204 No Content 1230 1231 **Status codes**: 1232 1233 - **204** – no error 1234 - **404** – no such container 1235 - **500** – server error 1236 1237 #### Unpause a container 1238 1239 `POST /containers/(id or name)/unpause` 1240 1241 Unpause the container `id` 1242 1243 **Example request**: 1244 1245 POST /v1.24/containers/e90e34656806/unpause HTTP/1.1 1246 1247 **Example response**: 1248 1249 HTTP/1.1 204 No Content 1250 1251 **Status codes**: 1252 1253 - **204** – no error 1254 - **404** – no such container 1255 - **500** – server error 1256 1257 #### Attach to a container 1258 1259 `POST /containers/(id or name)/attach` 1260 1261 Attach to the container `id` 1262 1263 **Example request**: 1264 1265 POST /v1.24/containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 1266 1267 **Example response**: 1268 1269 HTTP/1.1 101 UPGRADED 1270 Content-Type: application/vnd.docker.raw-stream 1271 Connection: Upgrade 1272 Upgrade: tcp 1273 1274 {% raw %} 1275 {{ STREAM }} 1276 {% endraw %} 1277 1278 **Query parameters**: 1279 1280 - **detachKeys** – Override the key sequence for detaching a 1281 container. Format is a single character `[a-Z]` or `ctrl-<value>` 1282 where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. 1283 - **logs** – 1/True/true or 0/False/false, return logs. Default `false`. 1284 - **stream** – 1/True/true or 0/False/false, return stream. 1285 Default `false`. 1286 - **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach 1287 to `stdin`. Default `false`. 1288 - **stdout** – 1/True/true or 0/False/false, if `logs=true`, return 1289 `stdout` log, if `stream=true`, attach to `stdout`. Default `false`. 1290 - **stderr** – 1/True/true or 0/False/false, if `logs=true`, return 1291 `stderr` log, if `stream=true`, attach to `stderr`. Default `false`. 1292 1293 **Status codes**: 1294 1295 - **101** – no error, hints proxy about hijacking 1296 - **200** – no error, no upgrade header found 1297 - **400** – bad parameter 1298 - **404** – no such container 1299 - **409** - container is paused 1300 - **500** – server error 1301 1302 **Stream details**: 1303 1304 When using the TTY setting is enabled in 1305 [`POST /containers/create` 1306 ](#create-a-container), 1307 the stream is the raw data from the process PTY and client's `stdin`. 1308 When the TTY is disabled, then the stream is multiplexed to separate 1309 `stdout` and `stderr`. 1310 1311 The format is a **Header** and a **Payload** (frame). 1312 1313 **HEADER** 1314 1315 The header contains the information which the stream writes (`stdout` or 1316 `stderr`). It also contains the size of the associated frame encoded in the 1317 last four bytes (`uint32`). 1318 1319 It is encoded on the first eight bytes like this: 1320 1321 header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} 1322 1323 `STREAM_TYPE` can be: 1324 1325 - 0: `stdin` (is written on `stdout`) 1326 - 1: `stdout` 1327 - 2: `stderr` 1328 1329 `SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of 1330 the `uint32` size encoded as big endian. 1331 1332 **PAYLOAD** 1333 1334 The payload is the raw stream. 1335 1336 **IMPLEMENTATION** 1337 1338 The simplest way to implement the Attach protocol is the following: 1339 1340 1. Read eight bytes. 1341 2. Choose `stdout` or `stderr` depending on the first byte. 1342 3. Extract the frame size from the last four bytes. 1343 4. Read the extracted size and output it on the correct output. 1344 5. Goto 1. 1345 1346 #### Attach to a container (websocket) 1347 1348 `GET /containers/(id or name)/attach/ws` 1349 1350 Attach to the container `id` via websocket 1351 1352 Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) 1353 1354 **Example request** 1355 1356 GET /v1.24/containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 1357 1358 **Example response** 1359 1360 {% raw %} 1361 {{ STREAM }} 1362 {% endraw %} 1363 1364 **Query parameters**: 1365 1366 - **detachKeys** – Override the key sequence for detaching a 1367 container. Format is a single character `[a-Z]` or `ctrl-<value>` 1368 where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. 1369 - **logs** – 1/True/true or 0/False/false, return logs. Default `false`. 1370 - **stream** – 1/True/true or 0/False/false, return stream. 1371 Default `false`. 1372 - **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach 1373 to `stdin`. Default `false`. 1374 - **stdout** – 1/True/true or 0/False/false, if `logs=true`, return 1375 `stdout` log, if `stream=true`, attach to `stdout`. Default `false`. 1376 - **stderr** – 1/True/true or 0/False/false, if `logs=true`, return 1377 `stderr` log, if `stream=true`, attach to `stderr`. Default `false`. 1378 1379 **Status codes**: 1380 1381 - **200** – no error 1382 - **400** – bad parameter 1383 - **404** – no such container 1384 - **500** – server error 1385 1386 #### Wait a container 1387 1388 `POST /containers/(id or name)/wait` 1389 1390 Block until container `id` stops, then returns the exit code 1391 1392 **Example request**: 1393 1394 POST /v1.24/containers/16253994b7c4/wait HTTP/1.1 1395 1396 **Example response**: 1397 1398 HTTP/1.1 200 OK 1399 Content-Type: application/json 1400 1401 {"StatusCode": 0} 1402 1403 **Status codes**: 1404 1405 - **200** – no error 1406 - **404** – no such container 1407 - **500** – server error 1408 1409 #### Remove a container 1410 1411 `DELETE /containers/(id or name)` 1412 1413 Remove the container `id` from the filesystem 1414 1415 **Example request**: 1416 1417 DELETE /v1.24/containers/16253994b7c4?v=1 HTTP/1.1 1418 1419 **Example response**: 1420 1421 HTTP/1.1 204 No Content 1422 1423 **Query parameters**: 1424 1425 - **v** – 1/True/true or 0/False/false, Remove the volumes 1426 associated to the container. Default `false`. 1427 - **force** - 1/True/true or 0/False/false, Kill then remove the container. 1428 Default `false`. 1429 - **link** - 1/True/true or 0/False/false, Remove the specified 1430 link associated to the container. Default `false`. 1431 1432 **Status codes**: 1433 1434 - **204** – no error 1435 - **400** – bad parameter 1436 - **404** – no such container 1437 - **409** – conflict 1438 - **500** – server error 1439 1440 #### Retrieving information about files and folders in a container 1441 1442 `HEAD /containers/(id or name)/archive` 1443 1444 See the description of the `X-Docker-Container-Path-Stat` header in the 1445 following section. 1446 1447 #### Get an archive of a filesystem resource in a container 1448 1449 `GET /containers/(id or name)/archive` 1450 1451 Get a tar archive of a resource in the filesystem of container `id`. 1452 1453 **Query parameters**: 1454 1455 - **path** - resource in the container's filesystem to archive. Required. 1456 1457 If not an absolute path, it is relative to the container's root directory. 1458 The resource specified by **path** must exist. To assert that the resource 1459 is expected to be a directory, **path** should end in `/` or `/.` 1460 (assuming a path separator of `/`). If **path** ends in `/.` then this 1461 indicates that only the contents of the **path** directory should be 1462 copied. A symlink is always resolved to its target. 1463 1464 > **Note**: It is not possible to copy certain system files such as resources 1465 > under `/proc`, `/sys`, `/dev`, and mounts created by the user in the 1466 > container. 1467 1468 **Example request**: 1469 1470 GET /v1.24/containers/8cce319429b2/archive?path=/root HTTP/1.1 1471 1472 **Example response**: 1473 1474 HTTP/1.1 200 OK 1475 Content-Type: application/x-tar 1476 X-Docker-Container-Path-Stat: eyJuYW1lIjoicm9vdCIsInNpemUiOjQwOTYsIm1vZGUiOjIxNDc0ODQwOTYsIm10aW1lIjoiMjAxNC0wMi0yN1QyMDo1MToyM1oiLCJsaW5rVGFyZ2V0IjoiIn0= 1477 1478 {% raw %} 1479 {{ TAR STREAM }} 1480 {% endraw %} 1481 1482 On success, a response header `X-Docker-Container-Path-Stat` will be set to a 1483 base64-encoded JSON object containing some filesystem header information about 1484 the archived resource. The above example value would decode to the following 1485 JSON object (whitespace added for readability): 1486 1487 ```json 1488 { 1489 "name": "root", 1490 "size": 4096, 1491 "mode": 2147484096, 1492 "mtime": "2014-02-27T20:51:23Z", 1493 "linkTarget": "" 1494 } 1495 ``` 1496 1497 A `HEAD` request can also be made to this endpoint if only this information is 1498 desired. 1499 1500 **Status codes**: 1501 1502 - **200** - success, returns archive of copied resource 1503 - **400** - client error, bad parameter, details in JSON response body, one of: 1504 - must specify path parameter (**path** cannot be empty) 1505 - not a directory (**path** was asserted to be a directory but exists as a 1506 file) 1507 - **404** - client error, resource not found, one of: 1508 – no such container (container `id` does not exist) 1509 - no such file or directory (**path** does not exist) 1510 - **500** - server error 1511 1512 #### Extract an archive of files or folders to a directory in a container 1513 1514 `PUT /containers/(id or name)/archive` 1515 1516 Upload a tar archive to be extracted to a path in the filesystem of container 1517 `id`. 1518 1519 **Query parameters**: 1520 1521 - **path** - path to a directory in the container 1522 to extract the archive's contents into. Required. 1523 1524 If not an absolute path, it is relative to the container's root directory. 1525 The **path** resource must exist. 1526 - **noOverwriteDirNonDir** - If "1", "true", or "True" then it will be an error 1527 if unpacking the given content would cause an existing directory to be 1528 replaced with a non-directory and vice versa. 1529 1530 **Example request**: 1531 1532 PUT /v1.24/containers/8cce319429b2/archive?path=/vol1 HTTP/1.1 1533 Content-Type: application/x-tar 1534 1535 {% raw %} 1536 {{ TAR STREAM }} 1537 {% endraw %} 1538 1539 **Example response**: 1540 1541 HTTP/1.1 200 OK 1542 1543 **Status codes**: 1544 1545 - **200** – the content was extracted successfully 1546 - **400** - client error, bad parameter, details in JSON response body, one of: 1547 - must specify path parameter (**path** cannot be empty) 1548 - not a directory (**path** should be a directory but exists as a file) 1549 - unable to overwrite existing directory with non-directory 1550 (if **noOverwriteDirNonDir**) 1551 - unable to overwrite existing non-directory with directory 1552 (if **noOverwriteDirNonDir**) 1553 - **403** - client error, permission denied, the volume 1554 or container rootfs is marked as read-only. 1555 - **404** - client error, resource not found, one of: 1556 – no such container (container `id` does not exist) 1557 - no such file or directory (**path** resource does not exist) 1558 - **500** – server error 1559 1560 ### 3.2 Images 1561 1562 #### List Images 1563 1564 `GET /images/json` 1565 1566 **Example request**: 1567 1568 GET /v1.24/images/json?all=0 HTTP/1.1 1569 1570 **Example response**: 1571 1572 HTTP/1.1 200 OK 1573 Content-Type: application/json 1574 1575 [ 1576 { 1577 "RepoTags": [ 1578 "ubuntu:12.04", 1579 "ubuntu:precise", 1580 "ubuntu:latest" 1581 ], 1582 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 1583 "Created": 1365714795, 1584 "Size": 131506275, 1585 "VirtualSize": 131506275, 1586 "Labels": {} 1587 }, 1588 { 1589 "RepoTags": [ 1590 "ubuntu:12.10", 1591 "ubuntu:quantal" 1592 ], 1593 "ParentId": "27cf784147099545", 1594 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 1595 "Created": 1364102658, 1596 "Size": 24653, 1597 "VirtualSize": 180116135, 1598 "Labels": { 1599 "com.example.version": "v1" 1600 } 1601 } 1602 ] 1603 1604 **Example request, with digest information**: 1605 1606 GET /v1.24/images/json?digests=1 HTTP/1.1 1607 1608 **Example response, with digest information**: 1609 1610 HTTP/1.1 200 OK 1611 Content-Type: application/json 1612 1613 [ 1614 { 1615 "Created": 1420064636, 1616 "Id": "4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125", 1617 "ParentId": "ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2", 1618 "RepoDigests": [ 1619 "localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf" 1620 ], 1621 "RepoTags": [ 1622 "localhost:5000/test/busybox:latest", 1623 "playdate:latest" 1624 ], 1625 "Size": 0, 1626 "VirtualSize": 2429728, 1627 "Labels": {} 1628 } 1629 ] 1630 1631 The response shows a single image `Id` associated with two repositories 1632 (`RepoTags`): `localhost:5000/test/busybox`: and `playdate`. A caller can use 1633 either of the `RepoTags` values `localhost:5000/test/busybox:latest` or 1634 `playdate:latest` to reference the image. 1635 1636 You can also use `RepoDigests` values to reference an image. In this response, 1637 the array has only one reference and that is to the 1638 `localhost:5000/test/busybox` repository; the `playdate` repository has no 1639 digest. You can reference this digest using the value: 1640 `localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d...` 1641 1642 See the `docker run` and `docker build` commands for examples of digest and tag 1643 references on the command line. 1644 1645 **Query parameters**: 1646 1647 - **all** – 1/True/true or 0/False/false, default false 1648 - **filters** – a JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters: 1649 - `dangling=true` 1650 - `label=key` or `label="key=value"` of an image label 1651 - `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) 1652 - `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`) 1653 - **filter** - only return images with the specified name 1654 1655 #### Build image from a Dockerfile 1656 1657 `POST /build` 1658 1659 Build an image from a Dockerfile 1660 1661 **Example request**: 1662 1663 POST /v1.24/build HTTP/1.1 1664 1665 {% raw %} 1666 {{ TAR STREAM }} 1667 {% endraw %} 1668 1669 **Example response**: 1670 1671 HTTP/1.1 200 OK 1672 Content-Type: application/json 1673 1674 {"stream": "Step 1/5..."} 1675 {"stream": "..."} 1676 {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} 1677 1678 The input stream must be a `tar` archive compressed with one of the 1679 following algorithms: `identity` (no compression), `gzip`, `bzip2`, `xz`. 1680 1681 The archive must include a build instructions file, typically called 1682 `Dockerfile` at the archive's root. The `dockerfile` parameter may be 1683 used to specify a different build instructions file. To do this, its value must be 1684 the path to the alternate build instructions file to use. 1685 1686 The archive may include any number of other files, 1687 which are accessible in the build context (See the [*ADD build 1688 command*](../reference/builder.md#add)). 1689 1690 The Docker daemon performs a preliminary validation of the `Dockerfile` before 1691 starting the build, and returns an error if the syntax is incorrect. After that, 1692 each instruction is run one-by-one until the ID of the new image is output. 1693 1694 The build is canceled if the client drops the connection by quitting 1695 or being killed. 1696 1697 **Query parameters**: 1698 1699 - **dockerfile** - Path within the build context to the `Dockerfile`. This is 1700 ignored if `remote` is specified and points to an external `Dockerfile`. 1701 - **t** – A name and optional tag to apply to the image in the `name:tag` format. 1702 If you omit the `tag` the default `latest` value is assumed. 1703 You can provide one or more `t` parameters. 1704 - **remote** – A Git repository URI or HTTP/HTTPS context URI. If the 1705 URI points to a single text file, the file's contents are placed into 1706 a file called `Dockerfile` and the image is built from that file. If 1707 the URI points to a tarball, the file is downloaded by the daemon and 1708 the contents therein used as the context for the build. If the URI 1709 points to a tarball and the `dockerfile` parameter is also specified, 1710 there must be a file with the corresponding path inside the tarball. 1711 - **q** – Suppress verbose build output. 1712 - **nocache** – Do not use the cache when building the image. 1713 - **pull** - Attempt to pull the image even if an older image exists locally. 1714 - **rm** - Remove intermediate containers after a successful build (default behavior). 1715 - **forcerm** - Always remove intermediate containers (includes `rm`). 1716 - **memory** - Set memory limit for build. 1717 - **memswap** - Total memory (memory + swap), `-1` to enable unlimited swap. 1718 - **cpushares** - CPU shares (relative weight). 1719 - **cpusetcpus** - CPUs in which to allow execution (e.g., `0-3`, `0,1`). 1720 - **cpuperiod** - The length of a CPU period in microseconds. 1721 - **cpuquota** - Microseconds of CPU time that the container can get in a CPU period. 1722 - **buildargs** – JSON map of string pairs for build-time variables. Users pass 1723 these values at build-time. Docker uses the `buildargs` as the environment 1724 context for command(s) run via the Dockerfile's `RUN` instruction or for 1725 variable expansion in other Dockerfile instructions. This is not meant for 1726 passing secret values. [Read more about the buildargs instruction](../reference/builder.md#arg) 1727 - **shmsize** - Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB. 1728 - **labels** – JSON map of string pairs for labels to set on the image. 1729 1730 **Request Headers**: 1731 1732 - **Content-type** – Set to `"application/tar"`. 1733 - **X-Registry-Config** – A base64-url-safe-encoded Registry Auth Config JSON 1734 object with the following structure: 1735 1736 { 1737 "docker.example.com": { 1738 "username": "janedoe", 1739 "password": "hunter2" 1740 }, 1741 "https://index.docker.io/v1/": { 1742 "username": "mobydock", 1743 "password": "conta1n3rize14" 1744 } 1745 } 1746 1747 This object maps the hostname of a registry to an object containing the 1748 "username" and "password" for that registry. Multiple registries may 1749 be specified as the build may be based on an image requiring 1750 authentication to pull from any arbitrary registry. Only the registry 1751 domain name (and port if not the default "443") are required. However 1752 (for legacy reasons) the "official" Docker, Inc. hosted registry must 1753 be specified with both a "https://" prefix and a "/v1/" suffix even 1754 though Docker will prefer to use the v2 registry API. 1755 1756 **Status codes**: 1757 1758 - **200** – no error 1759 - **500** – server error 1760 1761 #### Create an image 1762 1763 `POST /images/create` 1764 1765 Create an image either by pulling it from the registry or by importing it 1766 1767 **Example request**: 1768 1769 POST /v1.24/images/create?fromImage=busybox&tag=latest HTTP/1.1 1770 1771 **Example response**: 1772 1773 HTTP/1.1 200 OK 1774 Content-Type: application/json 1775 1776 {"status": "Pulling..."} 1777 {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} 1778 {"error": "Invalid..."} 1779 ... 1780 1781 When using this endpoint to pull an image from the registry, the 1782 `X-Registry-Auth` header can be used to include 1783 a base64-encoded AuthConfig object. 1784 1785 **Query parameters**: 1786 1787 - **fromImage** – Name of the image to pull. The name may include a tag or 1788 digest. This parameter may only be used when pulling an image. 1789 The pull is cancelled if the HTTP connection is closed. 1790 - **fromSrc** – Source to import. The value may be a URL from which the image 1791 can be retrieved or `-` to read the image from the request body. 1792 This parameter may only be used when importing an image. 1793 - **repo** – Repository name given to an image when it is imported. 1794 The repo may include a tag. This parameter may only be used when importing 1795 an image. 1796 - **tag** – Tag or digest. If empty when pulling an image, this causes all tags 1797 for the given image to be pulled. 1798 1799 **Request Headers**: 1800 1801 - **X-Registry-Auth** – base64-encoded AuthConfig object, containing either login information, or a token 1802 - Credential based login: 1803 1804 ``` 1805 { 1806 "username": "jdoe", 1807 "password": "secret", 1808 "email": "jdoe@acme.com" 1809 } 1810 ``` 1811 1812 - Token based login: 1813 1814 ``` 1815 { 1816 "identitytoken": "9cbaf023786cd7..." 1817 } 1818 ``` 1819 1820 **Status codes**: 1821 1822 - **200** – no error 1823 - **404** - repository does not exist or no read access 1824 - **500** – server error 1825 1826 1827 1828 #### Inspect an image 1829 1830 `GET /images/(name)/json` 1831 1832 Return low-level information on the image `name` 1833 1834 **Example request**: 1835 1836 GET /v1.24/images/example/json HTTP/1.1 1837 1838 **Example response**: 1839 1840 HTTP/1.1 200 OK 1841 Content-Type: application/json 1842 1843 { 1844 "Id" : "sha256:85f05633ddc1c50679be2b16a0479ab6f7637f8884e0cfe0f4d20e1ebb3d6e7c", 1845 "Container" : "cb91e48a60d01f1e27028b4fc6819f4f290b3cf12496c8176ec714d0d390984a", 1846 "Comment" : "", 1847 "Os" : "linux", 1848 "Architecture" : "amd64", 1849 "Parent" : "sha256:91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1850 "ContainerConfig" : { 1851 "Tty" : false, 1852 "Hostname" : "e611e15f9c9d", 1853 "Volumes" : null, 1854 "Domainname" : "", 1855 "AttachStdout" : false, 1856 "PublishService" : "", 1857 "AttachStdin" : false, 1858 "OpenStdin" : false, 1859 "StdinOnce" : false, 1860 "NetworkDisabled" : false, 1861 "OnBuild" : [], 1862 "Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1863 "User" : "", 1864 "WorkingDir" : "", 1865 "Entrypoint" : null, 1866 "MacAddress" : "", 1867 "AttachStderr" : false, 1868 "Labels" : { 1869 "com.example.license" : "GPL", 1870 "com.example.version" : "1.0", 1871 "com.example.vendor" : "Acme" 1872 }, 1873 "Env" : [ 1874 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 1875 ], 1876 "ExposedPorts" : null, 1877 "Cmd" : [ 1878 "/bin/sh", 1879 "-c", 1880 "#(nop) LABEL com.example.vendor=Acme com.example.license=GPL com.example.version=1.0" 1881 ] 1882 }, 1883 "DockerVersion" : "1.9.0-dev", 1884 "VirtualSize" : 188359297, 1885 "Size" : 0, 1886 "Author" : "", 1887 "Created" : "2015-09-10T08:30:53.26995814Z", 1888 "GraphDriver" : { 1889 "Name" : "aufs", 1890 "Data" : null 1891 }, 1892 "RepoDigests" : [ 1893 "localhost:5000/test/busybox/example@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf" 1894 ], 1895 "RepoTags" : [ 1896 "example:1.0", 1897 "example:latest", 1898 "example:stable" 1899 ], 1900 "Config" : { 1901 "Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1902 "NetworkDisabled" : false, 1903 "OnBuild" : [], 1904 "StdinOnce" : false, 1905 "PublishService" : "", 1906 "AttachStdin" : false, 1907 "OpenStdin" : false, 1908 "Domainname" : "", 1909 "AttachStdout" : false, 1910 "Tty" : false, 1911 "Hostname" : "e611e15f9c9d", 1912 "Volumes" : null, 1913 "Cmd" : [ 1914 "/bin/bash" 1915 ], 1916 "ExposedPorts" : null, 1917 "Env" : [ 1918 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 1919 ], 1920 "Labels" : { 1921 "com.example.vendor" : "Acme", 1922 "com.example.version" : "1.0", 1923 "com.example.license" : "GPL" 1924 }, 1925 "Entrypoint" : null, 1926 "MacAddress" : "", 1927 "AttachStderr" : false, 1928 "WorkingDir" : "", 1929 "User" : "" 1930 }, 1931 "RootFS": { 1932 "Type": "layers", 1933 "Layers": [ 1934 "sha256:1834950e52ce4d5a88a1bbd131c537f4d0e56d10ff0dd69e66be3b7dfa9df7e6", 1935 "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef" 1936 ] 1937 } 1938 } 1939 1940 **Status codes**: 1941 1942 - **200** – no error 1943 - **404** – no such image 1944 - **500** – server error 1945 1946 #### Get the history of an image 1947 1948 `GET /images/(name)/history` 1949 1950 Return the history of the image `name` 1951 1952 **Example request**: 1953 1954 GET /v1.24/images/ubuntu/history HTTP/1.1 1955 1956 **Example response**: 1957 1958 HTTP/1.1 200 OK 1959 Content-Type: application/json 1960 1961 [ 1962 { 1963 "Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710", 1964 "Created": 1398108230, 1965 "CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /", 1966 "Tags": [ 1967 "ubuntu:lucid", 1968 "ubuntu:10.04" 1969 ], 1970 "Size": 182964289, 1971 "Comment": "" 1972 }, 1973 { 1974 "Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8", 1975 "Created": 1398108222, 1976 "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/", 1977 "Tags": null, 1978 "Size": 0, 1979 "Comment": "" 1980 }, 1981 { 1982 "Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158", 1983 "Created": 1371157430, 1984 "CreatedBy": "", 1985 "Tags": [ 1986 "scratch12:latest", 1987 "scratch:latest" 1988 ], 1989 "Size": 0, 1990 "Comment": "Imported from -" 1991 } 1992 ] 1993 1994 **Status codes**: 1995 1996 - **200** – no error 1997 - **404** – no such image 1998 - **500** – server error 1999 2000 #### Push an image on the registry 2001 2002 `POST /images/(name)/push` 2003 2004 Push the image `name` on the registry 2005 2006 **Example request**: 2007 2008 POST /v1.24/images/test/push HTTP/1.1 2009 2010 **Example response**: 2011 2012 HTTP/1.1 200 OK 2013 Content-Type: application/json 2014 2015 {"status": "Pushing..."} 2016 {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} 2017 {"error": "Invalid..."} 2018 ... 2019 2020 If you wish to push an image on to a private registry, that image must already have a tag 2021 into a repository which references that registry `hostname` and `port`. This repository name should 2022 then be used in the URL. This duplicates the command line's flow. 2023 2024 The push is cancelled if the HTTP connection is closed. 2025 2026 **Example request**: 2027 2028 POST /v1.24/images/registry.acme.com:5000/test/push HTTP/1.1 2029 2030 2031 **Query parameters**: 2032 2033 - **tag** – The tag to associate with the image on the registry. This is optional. 2034 2035 **Request Headers**: 2036 2037 - **X-Registry-Auth** – base64-encoded AuthConfig object, containing either login information, or a token 2038 - Credential based login: 2039 2040 ``` 2041 { 2042 "username": "jdoe", 2043 "password": "secret", 2044 "email": "jdoe@acme.com", 2045 } 2046 ``` 2047 2048 - Identity token based login: 2049 2050 ``` 2051 { 2052 "identitytoken": "9cbaf023786cd7..." 2053 } 2054 ``` 2055 2056 **Status codes**: 2057 2058 - **200** – no error 2059 - **404** – no such image 2060 - **500** – server error 2061 2062 #### Tag an image into a repository 2063 2064 `POST /images/(name)/tag` 2065 2066 Tag the image `name` into a repository 2067 2068 **Example request**: 2069 2070 POST /v1.24/images/test/tag?repo=myrepo&tag=v42 HTTP/1.1 2071 2072 **Example response**: 2073 2074 HTTP/1.1 201 Created 2075 2076 **Query parameters**: 2077 2078 - **repo** – The repository to tag in 2079 - **tag** - The new tag name 2080 2081 **Status codes**: 2082 2083 - **201** – no error 2084 - **400** – bad parameter 2085 - **404** – no such image 2086 - **409** – conflict 2087 - **500** – server error 2088 2089 #### Remove an image 2090 2091 `DELETE /images/(name)` 2092 2093 Remove the image `name` from the filesystem 2094 2095 **Example request**: 2096 2097 DELETE /v1.24/images/test HTTP/1.1 2098 2099 **Example response**: 2100 2101 HTTP/1.1 200 OK 2102 Content-type: application/json 2103 2104 [ 2105 {"Untagged": "3e2f21a89f"}, 2106 {"Deleted": "3e2f21a89f"}, 2107 {"Deleted": "53b4f83ac9"} 2108 ] 2109 2110 **Query parameters**: 2111 2112 - **force** – 1/True/true or 0/False/false, default false 2113 - **noprune** – 1/True/true or 0/False/false, default false 2114 2115 **Status codes**: 2116 2117 - **200** – no error 2118 - **404** – no such image 2119 - **409** – conflict 2120 - **500** – server error 2121 2122 #### Search images 2123 2124 `GET /images/search` 2125 2126 Search for an image on [Docker Hub](https://hub.docker.com). 2127 2128 > **Note**: 2129 > The response keys have changed from API v1.6 to reflect the JSON 2130 > sent by the registry server to the docker daemon's request. 2131 2132 **Example request**: 2133 2134 GET /v1.24/images/search?term=sshd HTTP/1.1 2135 2136 **Example response**: 2137 2138 HTTP/1.1 200 OK 2139 Content-Type: application/json 2140 2141 [ 2142 { 2143 "description": "", 2144 "is_official": false, 2145 "is_automated": false, 2146 "name": "wma55/u1210sshd", 2147 "star_count": 0 2148 }, 2149 { 2150 "description": "", 2151 "is_official": false, 2152 "is_automated": false, 2153 "name": "jdswinbank/sshd", 2154 "star_count": 0 2155 }, 2156 { 2157 "description": "", 2158 "is_official": false, 2159 "is_automated": false, 2160 "name": "vgauthier/sshd", 2161 "star_count": 0 2162 } 2163 ... 2164 ] 2165 2166 **Query parameters**: 2167 2168 - **term** – term to search 2169 - **limit** – maximum returned search results 2170 - **filters** – a JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters: 2171 - `stars=<number>` 2172 - `is-automated=(true|false)` 2173 - `is-official=(true|false)` 2174 2175 **Status codes**: 2176 2177 - **200** – no error 2178 - **500** – server error 2179 2180 ### 3.3 Misc 2181 2182 #### Check auth configuration 2183 2184 `POST /auth` 2185 2186 Validate credentials for a registry and get identity token, 2187 if available, for accessing the registry without password. 2188 2189 **Example request**: 2190 2191 POST /v1.24/auth HTTP/1.1 2192 Content-Type: application/json 2193 2194 { 2195 "username": "hannibal", 2196 "password": "xxxx", 2197 "serveraddress": "https://index.docker.io/v1/" 2198 } 2199 2200 **Example response**: 2201 2202 HTTP/1.1 200 OK 2203 2204 { 2205 "Status": "Login Succeeded", 2206 "IdentityToken": "9cbaf023786cd7..." 2207 } 2208 2209 **Status codes**: 2210 2211 - **200** – no error 2212 - **204** – no error 2213 - **500** – server error 2214 2215 #### Display system-wide information 2216 2217 `GET /info` 2218 2219 Display system-wide information 2220 2221 **Example request**: 2222 2223 GET /v1.24/info HTTP/1.1 2224 2225 **Example response**: 2226 2227 HTTP/1.1 200 OK 2228 Content-Type: application/json 2229 2230 { 2231 "Architecture": "x86_64", 2232 "ClusterStore": "etcd://localhost:2379", 2233 "CgroupDriver": "cgroupfs", 2234 "Containers": 11, 2235 "ContainersRunning": 7, 2236 "ContainersStopped": 3, 2237 "ContainersPaused": 1, 2238 "CpuCfsPeriod": true, 2239 "CpuCfsQuota": true, 2240 "Debug": false, 2241 "DockerRootDir": "/var/lib/docker", 2242 "Driver": "btrfs", 2243 "DriverStatus": [[""]], 2244 "ExperimentalBuild": false, 2245 "HttpProxy": "http://test:test@localhost:8080", 2246 "HttpsProxy": "https://test:test@localhost:8080", 2247 "ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS", 2248 "IPv4Forwarding": true, 2249 "Images": 16, 2250 "IndexServerAddress": "https://index.docker.io/v1/", 2251 "InitPath": "/usr/bin/docker", 2252 "InitSha1": "", 2253 "KernelMemory": true, 2254 "KernelVersion": "3.12.0-1-amd64", 2255 "Labels": [ 2256 "storage=ssd" 2257 ], 2258 "MemTotal": 2099236864, 2259 "MemoryLimit": true, 2260 "NCPU": 1, 2261 "NEventsListener": 0, 2262 "NFd": 11, 2263 "NGoroutines": 21, 2264 "Name": "prod-server-42", 2265 "NoProxy": "9.81.1.160", 2266 "OomKillDisable": true, 2267 "OSType": "linux", 2268 "OperatingSystem": "Boot2Docker", 2269 "Plugins": { 2270 "Volume": [ 2271 "local" 2272 ], 2273 "Network": [ 2274 "null", 2275 "host", 2276 "bridge" 2277 ] 2278 }, 2279 "RegistryConfig": { 2280 "IndexConfigs": { 2281 "docker.io": { 2282 "Mirrors": null, 2283 "Name": "docker.io", 2284 "Official": true, 2285 "Secure": true 2286 } 2287 }, 2288 "InsecureRegistryCIDRs": [ 2289 "127.0.0.0/8" 2290 ] 2291 }, 2292 "SecurityOptions": [ 2293 "apparmor", 2294 "seccomp", 2295 "selinux" 2296 ], 2297 "ServerVersion": "1.9.0", 2298 "SwapLimit": false, 2299 "SystemStatus": [["State", "Healthy"]], 2300 "SystemTime": "2015-03-10T11:11:23.730591467-07:00" 2301 } 2302 2303 **Status codes**: 2304 2305 - **200** – no error 2306 - **500** – server error 2307 2308 #### Show the docker version information 2309 2310 `GET /version` 2311 2312 Show the docker version information 2313 2314 **Example request**: 2315 2316 GET /v1.24/version HTTP/1.1 2317 2318 **Example response**: 2319 2320 HTTP/1.1 200 OK 2321 Content-Type: application/json 2322 2323 { 2324 "Version": "1.12.0", 2325 "Os": "linux", 2326 "KernelVersion": "3.19.0-23-generic", 2327 "GoVersion": "go1.6.3", 2328 "GitCommit": "deadbee", 2329 "Arch": "amd64", 2330 "ApiVersion": "1.24", 2331 "BuildTime": "2016-06-14T07:09:13.444803460+00:00", 2332 "Experimental": true 2333 } 2334 2335 **Status codes**: 2336 2337 - **200** – no error 2338 - **500** – server error 2339 2340 #### Ping the docker server 2341 2342 `GET /_ping` 2343 2344 Ping the docker server 2345 2346 **Example request**: 2347 2348 GET /v1.24/_ping HTTP/1.1 2349 2350 **Example response**: 2351 2352 HTTP/1.1 200 OK 2353 Content-Type: text/plain 2354 2355 OK 2356 2357 **Status codes**: 2358 2359 - **200** - no error 2360 - **500** - server error 2361 2362 #### Create a new image from a container's changes 2363 2364 `POST /commit` 2365 2366 Create a new image from a container's changes 2367 2368 **Example request**: 2369 2370 POST /v1.24/commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 2371 Content-Type: application/json 2372 2373 { 2374 "Hostname": "", 2375 "Domainname": "", 2376 "User": "", 2377 "AttachStdin": false, 2378 "AttachStdout": true, 2379 "AttachStderr": true, 2380 "Tty": false, 2381 "OpenStdin": false, 2382 "StdinOnce": false, 2383 "Env": null, 2384 "Cmd": [ 2385 "date" 2386 ], 2387 "Mounts": [ 2388 { 2389 "Source": "/data", 2390 "Destination": "/data", 2391 "Mode": "ro,Z", 2392 "RW": false 2393 } 2394 ], 2395 "Labels": { 2396 "key1": "value1", 2397 "key2": "value2" 2398 }, 2399 "WorkingDir": "", 2400 "NetworkDisabled": false, 2401 "ExposedPorts": { 2402 "22/tcp": {} 2403 } 2404 } 2405 2406 **Example response**: 2407 2408 HTTP/1.1 201 Created 2409 Content-Type: application/json 2410 2411 {"Id": "596069db4bf5"} 2412 2413 **JSON parameters**: 2414 2415 - **config** - the container's configuration 2416 2417 **Query parameters**: 2418 2419 - **container** – source container 2420 - **repo** – repository 2421 - **tag** – tag 2422 - **comment** – commit message 2423 - **author** – author (e.g., "John Hannibal Smith 2424 <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") 2425 - **pause** – 1/True/true or 0/False/false, whether to pause the container before committing 2426 - **changes** – Dockerfile instructions to apply while committing 2427 2428 **Status codes**: 2429 2430 - **201** – no error 2431 - **404** – no such container 2432 - **500** – server error 2433 2434 #### Monitor Docker's events 2435 2436 `GET /events` 2437 2438 Get container events from docker, in real time via streaming. 2439 2440 Docker containers report the following events: 2441 2442 attach, commit, copy, create, destroy, detach, die, exec_create, exec_detach, exec_start, export, health_status, kill, oom, pause, rename, resize, restart, start, stop, top, unpause, update 2443 2444 Docker images report the following events: 2445 2446 delete, import, load, pull, push, save, tag, untag 2447 2448 Docker volumes report the following events: 2449 2450 create, mount, unmount, destroy 2451 2452 Docker networks report the following events: 2453 2454 create, connect, disconnect, destroy 2455 2456 Docker daemon report the following event: 2457 2458 reload 2459 2460 **Example request**: 2461 2462 GET /v1.24/events?since=1374067924 2463 2464 **Example response**: 2465 2466 HTTP/1.1 200 OK 2467 Content-Type: application/json 2468 Server: Docker/1.12.0 (linux) 2469 Date: Fri, 29 Apr 2016 15:18:06 GMT 2470 Transfer-Encoding: chunked 2471 2472 { 2473 "status": "pull", 2474 "id": "alpine:latest", 2475 "Type": "image", 2476 "Action": "pull", 2477 "Actor": { 2478 "ID": "alpine:latest", 2479 "Attributes": { 2480 "name": "alpine" 2481 } 2482 }, 2483 "time": 1461943101, 2484 "timeNano": 1461943101301854122 2485 } 2486 { 2487 "status": "create", 2488 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2489 "from": "alpine", 2490 "Type": "container", 2491 "Action": "create", 2492 "Actor": { 2493 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2494 "Attributes": { 2495 "com.example.some-label": "some-label-value", 2496 "image": "alpine", 2497 "name": "my-container" 2498 } 2499 }, 2500 "time": 1461943101, 2501 "timeNano": 1461943101381709551 2502 } 2503 { 2504 "status": "attach", 2505 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2506 "from": "alpine", 2507 "Type": "container", 2508 "Action": "attach", 2509 "Actor": { 2510 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2511 "Attributes": { 2512 "com.example.some-label": "some-label-value", 2513 "image": "alpine", 2514 "name": "my-container" 2515 } 2516 }, 2517 "time": 1461943101, 2518 "timeNano": 1461943101383858412 2519 } 2520 { 2521 "Type": "network", 2522 "Action": "connect", 2523 "Actor": { 2524 "ID": "7dc8ac97d5d29ef6c31b6052f3938c1e8f2749abbd17d1bd1febf2608db1b474", 2525 "Attributes": { 2526 "container": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2527 "name": "bridge", 2528 "type": "bridge" 2529 } 2530 }, 2531 "time": 1461943101, 2532 "timeNano": 1461943101394865557 2533 } 2534 { 2535 "status": "start", 2536 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2537 "from": "alpine", 2538 "Type": "container", 2539 "Action": "start", 2540 "Actor": { 2541 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2542 "Attributes": { 2543 "com.example.some-label": "some-label-value", 2544 "image": "alpine", 2545 "name": "my-container" 2546 } 2547 }, 2548 "time": 1461943101, 2549 "timeNano": 1461943101607533796 2550 } 2551 { 2552 "status": "resize", 2553 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2554 "from": "alpine", 2555 "Type": "container", 2556 "Action": "resize", 2557 "Actor": { 2558 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2559 "Attributes": { 2560 "com.example.some-label": "some-label-value", 2561 "height": "46", 2562 "image": "alpine", 2563 "name": "my-container", 2564 "width": "204" 2565 } 2566 }, 2567 "time": 1461943101, 2568 "timeNano": 1461943101610269268 2569 } 2570 { 2571 "status": "die", 2572 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2573 "from": "alpine", 2574 "Type": "container", 2575 "Action": "die", 2576 "Actor": { 2577 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2578 "Attributes": { 2579 "com.example.some-label": "some-label-value", 2580 "exitCode": "0", 2581 "image": "alpine", 2582 "name": "my-container" 2583 } 2584 }, 2585 "time": 1461943105, 2586 "timeNano": 1461943105079144137 2587 } 2588 { 2589 "Type": "network", 2590 "Action": "disconnect", 2591 "Actor": { 2592 "ID": "7dc8ac97d5d29ef6c31b6052f3938c1e8f2749abbd17d1bd1febf2608db1b474", 2593 "Attributes": { 2594 "container": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2595 "name": "bridge", 2596 "type": "bridge" 2597 } 2598 }, 2599 "time": 1461943105, 2600 "timeNano": 1461943105230860245 2601 } 2602 { 2603 "status": "destroy", 2604 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2605 "from": "alpine", 2606 "Type": "container", 2607 "Action": "destroy", 2608 "Actor": { 2609 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2610 "Attributes": { 2611 "com.example.some-label": "some-label-value", 2612 "image": "alpine", 2613 "name": "my-container" 2614 } 2615 }, 2616 "time": 1461943105, 2617 "timeNano": 1461943105338056026 2618 } 2619 2620 **Query parameters**: 2621 2622 - **since** – Timestamp. Show all events created since timestamp and then stream 2623 - **until** – Timestamp. Show events created until given timestamp and stop streaming 2624 - **filters** – A json encoded value of the filters (a map[string][]string) to process on the event list. Available filters: 2625 - `container=<string>`; -- container to filter 2626 - `event=<string>`; -- event to filter 2627 - `image=<string>`; -- image to filter 2628 - `label=<string>`; -- image and container label to filter 2629 - `type=<string>`; -- either `container` or `image` or `volume` or `network` or `daemon` 2630 - `volume=<string>`; -- volume to filter 2631 - `network=<string>`; -- network to filter 2632 - `daemon=<string>`; -- daemon name or id to filter 2633 2634 **Status codes**: 2635 2636 - **200** – no error 2637 - **400** - bad parameter 2638 - **500** – server error 2639 2640 #### Get a tarball containing all images in a repository 2641 2642 `GET /images/(name)/get` 2643 2644 Get a tarball containing all images and metadata for the repository specified 2645 by `name`. 2646 2647 If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image 2648 (and its parents) are returned. If `name` is an image ID, similarly only that 2649 image (and its parents) are returned, but with the exclusion of the 2650 'repositories' file in the tarball, as there were no image names referenced. 2651 2652 See the [image tarball format](#image-tarball-format) for more details. 2653 2654 **Example request** 2655 2656 GET /v1.24/images/ubuntu/get 2657 2658 **Example response**: 2659 2660 HTTP/1.1 200 OK 2661 Content-Type: application/x-tar 2662 2663 Binary data stream 2664 2665 **Status codes**: 2666 2667 - **200** – no error 2668 - **500** – server error 2669 2670 #### Get a tarball containing all images 2671 2672 `GET /images/get` 2673 2674 Get a tarball containing all images and metadata for one or more repositories. 2675 2676 For each value of the `names` parameter: if it is a specific name and tag (e.g. 2677 `ubuntu:latest`), then only that image (and its parents) are returned; if it is 2678 an image ID, similarly only that image (and its parents) are returned and there 2679 would be no names referenced in the 'repositories' file for this image ID. 2680 2681 See the [image tarball format](#image-tarball-format) for more details. 2682 2683 **Example request** 2684 2685 GET /v1.24/images/get?names=myname%2Fmyapp%3Alatest&names=busybox 2686 2687 **Example response**: 2688 2689 HTTP/1.1 200 OK 2690 Content-Type: application/x-tar 2691 2692 Binary data stream 2693 2694 **Status codes**: 2695 2696 - **200** – no error 2697 - **500** – server error 2698 2699 #### Load a tarball with a set of images and tags into docker 2700 2701 `POST /images/load` 2702 2703 Load a set of images and tags into a Docker repository. 2704 See the [image tarball format](#image-tarball-format) for more details. 2705 2706 **Example request** 2707 2708 POST /v1.24/images/load 2709 Content-Type: application/x-tar 2710 2711 Tarball in body 2712 2713 **Example response**: 2714 2715 HTTP/1.1 200 OK 2716 Content-Type: application/json 2717 Transfer-Encoding: chunked 2718 2719 {"status":"Loading layer","progressDetail":{"current":32768,"total":1292800},"progress":"[= ] 32.77 kB/1.293 MB","id":"8ac8bfaff55a"} 2720 {"status":"Loading layer","progressDetail":{"current":65536,"total":1292800},"progress":"[== ] 65.54 kB/1.293 MB","id":"8ac8bfaff55a"} 2721 {"status":"Loading layer","progressDetail":{"current":98304,"total":1292800},"progress":"[=== ] 98.3 kB/1.293 MB","id":"8ac8bfaff55a"} 2722 {"status":"Loading layer","progressDetail":{"current":131072,"total":1292800},"progress":"[===== ] 131.1 kB/1.293 MB","id":"8ac8bfaff55a"} 2723 ... 2724 {"stream":"Loaded image: busybox:latest\n"} 2725 2726 **Example response**: 2727 2728 If the "quiet" query parameter is set to `true` / `1` (`?quiet=1`), progress 2729 details are suppressed, and only a confirmation message is returned once the 2730 action completes. 2731 2732 HTTP/1.1 200 OK 2733 Content-Type: application/json 2734 Transfer-Encoding: chunked 2735 2736 {"stream":"Loaded image: busybox:latest\n"} 2737 2738 **Query parameters**: 2739 2740 - **quiet** – Boolean value, suppress progress details during load. Defaults 2741 to `0` / `false` if omitted. 2742 2743 **Status codes**: 2744 2745 - **200** – no error 2746 - **500** – server error 2747 2748 #### Image tarball format 2749 2750 An image tarball contains one directory per image layer (named using its long ID), 2751 each containing these files: 2752 2753 - `VERSION`: currently `1.0` - the file format version 2754 - `json`: detailed layer information, similar to `docker inspect layer_id` 2755 - `layer.tar`: A tarfile containing the filesystem changes in this layer 2756 2757 The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories 2758 for storing attribute changes and deletions. 2759 2760 If the tarball defines a repository, the tarball should also include a `repositories` file at 2761 the root that contains a list of repository and tag names mapped to layer IDs. 2762 2763 ``` 2764 {"hello-world": 2765 {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} 2766 } 2767 ``` 2768 2769 #### Exec Create 2770 2771 `POST /containers/(id or name)/exec` 2772 2773 Sets up an exec instance in a running container `id` 2774 2775 **Example request**: 2776 2777 POST /v1.24/containers/e90e34656806/exec HTTP/1.1 2778 Content-Type: application/json 2779 2780 { 2781 "AttachStdin": true, 2782 "AttachStdout": true, 2783 "AttachStderr": true, 2784 "Cmd": ["sh"], 2785 "DetachKeys": "ctrl-p,ctrl-q", 2786 "Privileged": true, 2787 "Tty": true, 2788 "User": "123:456" 2789 } 2790 2791 **Example response**: 2792 2793 HTTP/1.1 201 Created 2794 Content-Type: application/json 2795 2796 { 2797 "Id": "f90e34656806", 2798 "Warnings":[] 2799 } 2800 2801 **JSON parameters**: 2802 2803 - **AttachStdin** - Boolean value, attaches to `stdin` of the `exec` command. 2804 - **AttachStdout** - Boolean value, attaches to `stdout` of the `exec` command. 2805 - **AttachStderr** - Boolean value, attaches to `stderr` of the `exec` command. 2806 - **DetachKeys** – Override the key sequence for detaching a 2807 container. Format is a single character `[a-Z]` or `ctrl-<value>` 2808 where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. 2809 - **Tty** - Boolean value to allocate a pseudo-TTY. 2810 - **Cmd** - Command to run specified as a string or an array of strings. 2811 - **Privileged** - Boolean value, runs the exec process with extended privileges. 2812 - **User** - A string value specifying the user, and optionally, group to run 2813 the exec process inside the container. Format is one of: `"user"`, 2814 `"user:group"`, `"uid"`, or `"uid:gid"`. 2815 2816 **Status codes**: 2817 2818 - **201** – no error 2819 - **404** – no such container 2820 - **409** - container is paused 2821 - **500** - server error 2822 2823 #### Exec Start 2824 2825 `POST /exec/(id)/start` 2826 2827 Starts a previously set up `exec` instance `id`. If `detach` is true, this API 2828 returns after starting the `exec` command. Otherwise, this API sets up an 2829 interactive session with the `exec` command. 2830 2831 **Example request**: 2832 2833 POST /v1.24/exec/e90e34656806/start HTTP/1.1 2834 Content-Type: application/json 2835 2836 { 2837 "Detach": false, 2838 "Tty": false 2839 } 2840 2841 **Example response**: 2842 2843 HTTP/1.1 200 OK 2844 Content-Type: application/vnd.docker.raw-stream 2845 2846 {% raw %} 2847 {{ STREAM }} 2848 {% endraw %} 2849 2850 **JSON parameters**: 2851 2852 - **Detach** - Detach from the `exec` command. 2853 - **Tty** - Boolean value to allocate a pseudo-TTY. 2854 2855 **Status codes**: 2856 2857 - **200** – no error 2858 - **404** – no such exec instance 2859 - **409** - container is paused 2860 2861 **Stream details**: 2862 2863 Similar to the stream behavior of `POST /containers/(id or name)/attach` API 2864 2865 #### Exec Resize 2866 2867 `POST /exec/(id)/resize` 2868 2869 Resizes the `tty` session used by the `exec` command `id`. The unit is number of characters. 2870 This API is valid only if `tty` was specified as part of creating and starting the `exec` command. 2871 2872 **Example request**: 2873 2874 POST /v1.24/exec/e90e34656806/resize?h=40&w=80 HTTP/1.1 2875 Content-Type: text/plain 2876 2877 **Example response**: 2878 2879 HTTP/1.1 201 Created 2880 Content-Type: text/plain 2881 2882 **Query parameters**: 2883 2884 - **h** – height of `tty` session 2885 - **w** – width 2886 2887 **Status codes**: 2888 2889 - **201** – no error 2890 - **404** – no such exec instance 2891 2892 #### Exec Inspect 2893 2894 `GET /exec/(id)/json` 2895 2896 Return low-level information about the `exec` command `id`. 2897 2898 **Example request**: 2899 2900 GET /v1.24/exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1 2901 2902 **Example response**: 2903 2904 HTTP/1.1 200 OK 2905 Content-Type: application/json 2906 2907 { 2908 "CanRemove": false, 2909 "ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126", 2910 "DetachKeys": "", 2911 "ExitCode": 2, 2912 "ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b", 2913 "OpenStderr": true, 2914 "OpenStdin": true, 2915 "OpenStdout": true, 2916 "ProcessConfig": { 2917 "arguments": [ 2918 "-c", 2919 "exit 2" 2920 ], 2921 "entrypoint": "sh", 2922 "privileged": false, 2923 "tty": true, 2924 "user": "1000" 2925 }, 2926 "Running": false 2927 } 2928 2929 **Status codes**: 2930 2931 - **200** – no error 2932 - **404** – no such exec instance 2933 - **500** - server error 2934 2935 ### 3.4 Volumes 2936 2937 #### List volumes 2938 2939 `GET /volumes` 2940 2941 **Example request**: 2942 2943 GET /v1.24/volumes HTTP/1.1 2944 2945 **Example response**: 2946 2947 HTTP/1.1 200 OK 2948 Content-Type: application/json 2949 2950 { 2951 "Volumes": [ 2952 { 2953 "Name": "tardis", 2954 "Driver": "local", 2955 "Mountpoint": "/var/lib/docker/volumes/tardis", 2956 "Labels": null, 2957 "Scope": "local" 2958 } 2959 ], 2960 "Warnings": [] 2961 } 2962 2963 **Query parameters**: 2964 2965 - **filters** - JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters: 2966 - `name=<volume-name>` Matches all or part of a volume name. 2967 - `dangling=<boolean>` When set to `true` (or `1`), returns all volumes that are "dangling" (not in use by a container). When set to `false` (or `0`), only volumes that are in use by one or more containers are returned. 2968 - `driver=<volume-driver-name>` Matches all or part of a volume driver name. 2969 2970 **Status codes**: 2971 2972 - **200** - no error 2973 - **500** - server error 2974 2975 #### Create a volume 2976 2977 `POST /volumes/create` 2978 2979 Create a volume 2980 2981 **Example request**: 2982 2983 POST /v1.24/volumes/create HTTP/1.1 2984 Content-Type: application/json 2985 2986 { 2987 "Name": "tardis", 2988 "Labels": { 2989 "com.example.some-label": "some-value", 2990 "com.example.some-other-label": "some-other-value" 2991 }, 2992 "Driver": "custom" 2993 } 2994 2995 **Example response**: 2996 2997 HTTP/1.1 201 Created 2998 Content-Type: application/json 2999 3000 { 3001 "Name": "tardis", 3002 "Driver": "custom", 3003 "Mountpoint": "/var/lib/docker/volumes/tardis", 3004 "Status": { 3005 "hello": "world" 3006 }, 3007 "Labels": { 3008 "com.example.some-label": "some-value", 3009 "com.example.some-other-label": "some-other-value" 3010 }, 3011 "Scope": "local" 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 **JSON fields in response**: 3028 3029 Refer to the [inspect a volume](#inspect-a-volume) section or details about the 3030 JSON fields returned in the response. 3031 3032 #### Inspect a volume 3033 3034 `GET /volumes/(name)` 3035 3036 Return low-level information on the volume `name` 3037 3038 **Example request**: 3039 3040 GET /v1.24/volumes/tardis 3041 3042 **Example response**: 3043 3044 HTTP/1.1 200 OK 3045 Content-Type: application/json 3046 3047 { 3048 "Name": "tardis", 3049 "Driver": "custom", 3050 "Mountpoint": "/var/lib/docker/volumes/tardis/_data", 3051 "Status": { 3052 "hello": "world" 3053 }, 3054 "Labels": { 3055 "com.example.some-label": "some-value", 3056 "com.example.some-other-label": "some-other-value" 3057 }, 3058 "Scope": "local" 3059 } 3060 3061 **Status codes**: 3062 3063 - **200** - no error 3064 - **404** - no such volume 3065 - **500** - server error 3066 3067 **JSON fields in response**: 3068 3069 The following fields can be returned in the API response. Empty fields, or 3070 fields that are not supported by the volume's driver may be omitted in the 3071 response. 3072 3073 - **Name** - Name of the volume. 3074 - **Driver** - Name of the volume driver used by the volume. 3075 - **Mountpoint** - Mount path of the volume on the host. 3076 - **Status** - Low-level details about the volume, provided by the volume driver. 3077 Details are returned as a map with key/value pairs: `{"key":"value","key2":"value2"}`. 3078 The `Status` field is optional, and is omitted if the volume driver does not 3079 support this feature. 3080 - **Labels** - Labels set on the volume, specified as a map: `{"key":"value","key2":"value2"}`. 3081 - **Scope** - Scope describes the level at which the volume exists, can be one of 3082 `global` for cluster-wide or `local` for machine level. The default is `local`. 3083 3084 #### Remove a volume 3085 3086 `DELETE /volumes/(name)` 3087 3088 Instruct the driver to remove the volume (`name`). 3089 3090 **Example request**: 3091 3092 DELETE /v1.24/volumes/tardis HTTP/1.1 3093 3094 **Example response**: 3095 3096 HTTP/1.1 204 No Content 3097 3098 **Status codes**: 3099 3100 - **204** - no error 3101 - **404** - no such volume or volume driver 3102 - **409** - volume is in use and cannot be removed 3103 - **500** - server error 3104 3105 ### 3.5 Networks 3106 3107 #### List networks 3108 3109 `GET /networks` 3110 3111 **Example request**: 3112 3113 GET /v1.24/networks?filters={"type":{"custom":true}} HTTP/1.1 3114 3115 **Example response**: 3116 3117 ``` 3118 HTTP/1.1 200 OK 3119 Content-Type: application/json 3120 3121 [ 3122 { 3123 "Name": "bridge", 3124 "Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566", 3125 "Scope": "local", 3126 "Driver": "bridge", 3127 "EnableIPv6": false, 3128 "Internal": false, 3129 "IPAM": { 3130 "Driver": "default", 3131 "Config": [ 3132 { 3133 "Subnet": "172.17.0.0/16" 3134 } 3135 ] 3136 }, 3137 "Containers": { 3138 "39b69226f9d79f5634485fb236a23b2fe4e96a0a94128390a7fbbcc167065867": { 3139 "EndpointID": "ed2419a97c1d9954d05b46e462e7002ea552f216e9b136b80a7db8d98b442eda", 3140 "MacAddress": "02:42:ac:11:00:02", 3141 "IPv4Address": "172.17.0.2/16", 3142 "IPv6Address": "" 3143 } 3144 }, 3145 "Options": { 3146 "com.docker.network.bridge.default_bridge": "true", 3147 "com.docker.network.bridge.enable_icc": "true", 3148 "com.docker.network.bridge.enable_ip_masquerade": "true", 3149 "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", 3150 "com.docker.network.bridge.name": "docker0", 3151 "com.docker.network.driver.mtu": "1500" 3152 } 3153 }, 3154 { 3155 "Name": "none", 3156 "Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794", 3157 "Scope": "local", 3158 "Driver": "null", 3159 "EnableIPv6": false, 3160 "Internal": false, 3161 "IPAM": { 3162 "Driver": "default", 3163 "Config": [] 3164 }, 3165 "Containers": {}, 3166 "Options": {} 3167 }, 3168 { 3169 "Name": "host", 3170 "Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e", 3171 "Scope": "local", 3172 "Driver": "host", 3173 "EnableIPv6": false, 3174 "Internal": false, 3175 "IPAM": { 3176 "Driver": "default", 3177 "Config": [] 3178 }, 3179 "Containers": {}, 3180 "Options": {} 3181 } 3182 ] 3183 ``` 3184 3185 **Query parameters**: 3186 3187 - **filters** - JSON encoded network list filter. The filter value is one of: 3188 - `driver=<driver-name>` Matches a network's driver. 3189 - `id=<network-id>` Matches all or part of a network id. 3190 - `label=<key>` or `label=<key>=<value>` of a network label. 3191 - `name=<network-name>` Matches all or part of a network name. 3192 - `type=["custom"|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. 3193 3194 **Status codes**: 3195 3196 - **200** - no error 3197 - **500** - server error 3198 3199 #### Inspect network 3200 3201 `GET /networks/<network-id>` 3202 3203 **Example request**: 3204 3205 GET /v1.24/networks/7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99 HTTP/1.1 3206 3207 **Example response**: 3208 3209 ``` 3210 HTTP/1.1 200 OK 3211 Content-Type: application/json 3212 3213 { 3214 "Name": "net01", 3215 "Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99", 3216 "Scope": "local", 3217 "Driver": "bridge", 3218 "EnableIPv6": false, 3219 "IPAM": { 3220 "Driver": "default", 3221 "Config": [ 3222 { 3223 "Subnet": "172.19.0.0/16", 3224 "Gateway": "172.19.0.1" 3225 } 3226 ], 3227 "Options": { 3228 "foo": "bar" 3229 } 3230 }, 3231 "Internal": false, 3232 "Containers": { 3233 "19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": { 3234 "Name": "test", 3235 "EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a", 3236 "MacAddress": "02:42:ac:13:00:02", 3237 "IPv4Address": "172.19.0.2/16", 3238 "IPv6Address": "" 3239 } 3240 }, 3241 "Options": { 3242 "com.docker.network.bridge.default_bridge": "true", 3243 "com.docker.network.bridge.enable_icc": "true", 3244 "com.docker.network.bridge.enable_ip_masquerade": "true", 3245 "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", 3246 "com.docker.network.bridge.name": "docker0", 3247 "com.docker.network.driver.mtu": "1500" 3248 }, 3249 "Labels": { 3250 "com.example.some-label": "some-value", 3251 "com.example.some-other-label": "some-other-value" 3252 } 3253 } 3254 ``` 3255 3256 **Status codes**: 3257 3258 - **200** - no error 3259 - **404** - network not found 3260 3261 #### Create a network 3262 3263 `POST /networks/create` 3264 3265 Create a network 3266 3267 **Example request**: 3268 3269 ``` 3270 POST /v1.24/networks/create HTTP/1.1 3271 Content-Type: application/json 3272 3273 { 3274 "Name":"isolated_nw", 3275 "CheckDuplicate":true, 3276 "Driver":"bridge", 3277 "EnableIPv6": true, 3278 "IPAM":{ 3279 "Driver": "default", 3280 "Config":[ 3281 { 3282 "Subnet":"172.20.0.0/16", 3283 "IPRange":"172.20.10.0/24", 3284 "Gateway":"172.20.10.11" 3285 }, 3286 { 3287 "Subnet":"2001:db8:abcd::/64", 3288 "Gateway":"2001:db8:abcd::1011" 3289 } 3290 ], 3291 "Options": { 3292 "foo": "bar" 3293 } 3294 }, 3295 "Internal":true, 3296 "Options": { 3297 "com.docker.network.bridge.default_bridge": "true", 3298 "com.docker.network.bridge.enable_icc": "true", 3299 "com.docker.network.bridge.enable_ip_masquerade": "true", 3300 "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", 3301 "com.docker.network.bridge.name": "docker0", 3302 "com.docker.network.driver.mtu": "1500" 3303 }, 3304 "Labels": { 3305 "com.example.some-label": "some-value", 3306 "com.example.some-other-label": "some-other-value" 3307 } 3308 } 3309 ``` 3310 3311 **Example response**: 3312 3313 ``` 3314 HTTP/1.1 201 Created 3315 Content-Type: application/json 3316 3317 { 3318 "Id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30", 3319 "Warning": "" 3320 } 3321 ``` 3322 3323 **Status codes**: 3324 3325 - **201** - no error 3326 - **403** - operation not supported for pre-defined networks 3327 - **404** - plugin not found 3328 - **500** - server error 3329 3330 **JSON parameters**: 3331 3332 - **Name** - The new network's name. this is a mandatory field 3333 - **CheckDuplicate** - Requests daemon to check for networks with same name. Defaults to `false` 3334 - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver 3335 - **Internal** - Restrict external access to the network 3336 - **IPAM** - Optional custom IP scheme for the network 3337 - **Driver** - Name of the IPAM driver to use. Defaults to `default` driver 3338 - **Config** - List of IPAM configuration options, specified as a map: 3339 `{"Subnet": <CIDR>, "IPRange": <CIDR>, "Gateway": <IP address>, "AuxAddress": <device_name:IP address>}` 3340 - **Options** - Driver-specific options, specified as a map: `{"option":"value" [,"option2":"value2"]}` 3341 - **EnableIPv6** - Enable IPv6 on the network 3342 - **Options** - Network specific options to be used by the drivers 3343 - **Labels** - Labels to set on the network, specified as a map: `{"key":"value" [,"key2":"value2"]}` 3344 3345 #### Connect a container to a network 3346 3347 `POST /networks/(id)/connect` 3348 3349 Connect a container to a network 3350 3351 **Example request**: 3352 3353 ``` 3354 POST /v1.24/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1 3355 Content-Type: application/json 3356 3357 { 3358 "Container":"3613f73ba0e4", 3359 "EndpointConfig": { 3360 "IPAMConfig": { 3361 "IPv4Address":"172.24.56.89", 3362 "IPv6Address":"2001:db8::5689" 3363 } 3364 } 3365 } 3366 ``` 3367 3368 **Example response**: 3369 3370 HTTP/1.1 200 OK 3371 3372 **Status codes**: 3373 3374 - **200** - no error 3375 - **403** - operation not supported for swarm scoped networks 3376 - **404** - network or container is not found 3377 - **500** - Internal Server Error 3378 3379 **JSON parameters**: 3380 3381 - **container** - container-id/name to be connected to the network 3382 3383 #### Disconnect a container from a network 3384 3385 `POST /networks/(id)/disconnect` 3386 3387 Disconnect a container from a network 3388 3389 **Example request**: 3390 3391 ``` 3392 POST /v1.24/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1 3393 Content-Type: application/json 3394 3395 { 3396 "Container":"3613f73ba0e4", 3397 "Force":false 3398 } 3399 ``` 3400 3401 **Example response**: 3402 3403 HTTP/1.1 200 OK 3404 3405 **Status codes**: 3406 3407 - **200** - no error 3408 - **403** - operation not supported for swarm scoped networks 3409 - **404** - network or container not found 3410 - **500** - Internal Server Error 3411 3412 **JSON parameters**: 3413 3414 - **Container** - container-id/name to be disconnected from a network 3415 - **Force** - Force the container to disconnect from a network 3416 3417 #### Remove a network 3418 3419 `DELETE /networks/(id)` 3420 3421 Instruct the driver to remove the network (`id`). 3422 3423 **Example request**: 3424 3425 DELETE /v1.24/networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30 HTTP/1.1 3426 3427 **Example response**: 3428 3429 HTTP/1.1 204 No Content 3430 3431 **Status codes**: 3432 3433 - **204** - no error 3434 - **404** - no such network 3435 - **500** - server error 3436 3437 ### 3.6 Plugins (experimental) 3438 3439 #### List plugins 3440 3441 `GET /plugins` 3442 3443 Returns information about installed plugins. 3444 3445 **Example request**: 3446 3447 GET /v1.24/plugins HTTP/1.1 3448 3449 **Example response**: 3450 3451 ``` 3452 HTTP/1.1 200 OK 3453 Content-Type: application/json 3454 3455 [ 3456 { 3457 "Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078", 3458 "Name": "tiborvass/no-remove", 3459 "Tag": "latest", 3460 "Active": true, 3461 "Config": { 3462 "Mounts": [ 3463 { 3464 "Name": "", 3465 "Description": "", 3466 "Settable": null, 3467 "Source": "/data", 3468 "Destination": "/data", 3469 "Type": "bind", 3470 "Options": [ 3471 "shared", 3472 "rbind" 3473 ] 3474 }, 3475 { 3476 "Name": "", 3477 "Description": "", 3478 "Settable": null, 3479 "Source": null, 3480 "Destination": "/foobar", 3481 "Type": "tmpfs", 3482 "Options": null 3483 } 3484 ], 3485 "Env": [ 3486 "DEBUG=1" 3487 ], 3488 "Args": null, 3489 "Devices": null 3490 }, 3491 "Manifest": { 3492 "ManifestVersion": "v0", 3493 "Description": "A test plugin for Docker", 3494 "Documentation": "https://docs.docker.com/engine/extend/plugins/", 3495 "Interface": { 3496 "Types": [ 3497 "docker.volumedriver/1.0" 3498 ], 3499 "Socket": "plugins.sock" 3500 }, 3501 "Entrypoint": [ 3502 "plugin-no-remove", 3503 "/data" 3504 ], 3505 "Workdir": "", 3506 "User": { 3507 }, 3508 "Network": { 3509 "Type": "host" 3510 }, 3511 "Capabilities": null, 3512 "Mounts": [ 3513 { 3514 "Name": "", 3515 "Description": "", 3516 "Settable": null, 3517 "Source": "/data", 3518 "Destination": "/data", 3519 "Type": "bind", 3520 "Options": [ 3521 "shared", 3522 "rbind" 3523 ] 3524 }, 3525 { 3526 "Name": "", 3527 "Description": "", 3528 "Settable": null, 3529 "Source": null, 3530 "Destination": "/foobar", 3531 "Type": "tmpfs", 3532 "Options": null 3533 } 3534 ], 3535 "Devices": [ 3536 { 3537 "Name": "device", 3538 "Description": "a host device to mount", 3539 "Settable": null, 3540 "Path": "/dev/cpu_dma_latency" 3541 } 3542 ], 3543 "Env": [ 3544 { 3545 "Name": "DEBUG", 3546 "Description": "If set, prints debug messages", 3547 "Settable": null, 3548 "Value": "1" 3549 } 3550 ], 3551 "Args": { 3552 "Name": "args", 3553 "Description": "command line arguments", 3554 "Settable": null, 3555 "Value": [ 3556 3557 ] 3558 } 3559 } 3560 } 3561 ] 3562 ``` 3563 3564 **Status codes**: 3565 3566 - **200** - no error 3567 - **500** - server error 3568 3569 #### Install a plugin 3570 3571 `POST /plugins/pull?name=<plugin name>` 3572 3573 Pulls and installs a plugin. After the plugin is installed, it can be enabled 3574 using the [`POST /plugins/(plugin name)/enable` endpoint](#enable-a-plugin). 3575 3576 **Example request**: 3577 3578 ``` 3579 POST /v1.24/plugins/pull?name=tiborvass/no-remove:latest HTTP/1.1 3580 ``` 3581 3582 The `:latest` tag is optional, and is used as default if omitted. When using 3583 this endpoint to pull a plugin from the registry, the `X-Registry-Auth` header 3584 can be used to include a base64-encoded AuthConfig object. Refer to the [create 3585 an image](#create-an-image) section for more details. 3586 3587 **Example response**: 3588 3589 ``` 3590 HTTP/1.1 200 OK 3591 Content-Type: application/json 3592 Content-Length: 175 3593 3594 [ 3595 { 3596 "Name": "network", 3597 "Description": "", 3598 "Value": [ 3599 "host" 3600 ] 3601 }, 3602 { 3603 "Name": "mount", 3604 "Description": "", 3605 "Value": [ 3606 "/data" 3607 ] 3608 }, 3609 { 3610 "Name": "device", 3611 "Description": "", 3612 "Value": [ 3613 "/dev/cpu_dma_latency" 3614 ] 3615 } 3616 ] 3617 ``` 3618 3619 **Query parameters**: 3620 3621 - **name** - Name of the plugin to pull. The name may include a tag or digest. 3622 This parameter is required. 3623 3624 **Status codes**: 3625 3626 - **200** - no error 3627 - **500** - error parsing reference / not a valid repository/tag: repository 3628 name must have at least one component 3629 - **500** - plugin already exists 3630 3631 #### Inspect a plugin 3632 3633 `GET /plugins/(plugin name)` 3634 3635 Returns detailed information about an installed plugin. 3636 3637 **Example request**: 3638 3639 ``` 3640 GET /v1.24/plugins/tiborvass/no-remove:latest HTTP/1.1 3641 ``` 3642 3643 The `:latest` tag is optional, and is used as default if omitted. 3644 3645 3646 **Example response**: 3647 3648 ``` 3649 HTTP/1.1 200 OK 3650 Content-Type: application/json 3651 3652 { 3653 "Id": "5724e2c8652da337ab2eedd19fc6fc0ec908e4bd907c7421bf6a8dfc70c4c078", 3654 "Name": "tiborvass/no-remove", 3655 "Tag": "latest", 3656 "Active": false, 3657 "Config": { 3658 "Mounts": [ 3659 { 3660 "Name": "", 3661 "Description": "", 3662 "Settable": null, 3663 "Source": "/data", 3664 "Destination": "/data", 3665 "Type": "bind", 3666 "Options": [ 3667 "shared", 3668 "rbind" 3669 ] 3670 }, 3671 { 3672 "Name": "", 3673 "Description": "", 3674 "Settable": null, 3675 "Source": null, 3676 "Destination": "/foobar", 3677 "Type": "tmpfs", 3678 "Options": null 3679 } 3680 ], 3681 "Env": [ 3682 "DEBUG=1" 3683 ], 3684 "Args": null, 3685 "Devices": null 3686 }, 3687 "Manifest": { 3688 "ManifestVersion": "v0", 3689 "Description": "A test plugin for Docker", 3690 "Documentation": "https://docs.docker.com/engine/extend/plugins/", 3691 "Interface": { 3692 "Types": [ 3693 "docker.volumedriver/1.0" 3694 ], 3695 "Socket": "plugins.sock" 3696 }, 3697 "Entrypoint": [ 3698 "plugin-no-remove", 3699 "/data" 3700 ], 3701 "Workdir": "", 3702 "User": { 3703 }, 3704 "Network": { 3705 "Type": "host" 3706 }, 3707 "Capabilities": null, 3708 "Mounts": [ 3709 { 3710 "Name": "", 3711 "Description": "", 3712 "Settable": null, 3713 "Source": "/data", 3714 "Destination": "/data", 3715 "Type": "bind", 3716 "Options": [ 3717 "shared", 3718 "rbind" 3719 ] 3720 }, 3721 { 3722 "Name": "", 3723 "Description": "", 3724 "Settable": null, 3725 "Source": null, 3726 "Destination": "/foobar", 3727 "Type": "tmpfs", 3728 "Options": null 3729 } 3730 ], 3731 "Devices": [ 3732 { 3733 "Name": "device", 3734 "Description": "a host device to mount", 3735 "Settable": null, 3736 "Path": "/dev/cpu_dma_latency" 3737 } 3738 ], 3739 "Env": [ 3740 { 3741 "Name": "DEBUG", 3742 "Description": "If set, prints debug messages", 3743 "Settable": null, 3744 "Value": "1" 3745 } 3746 ], 3747 "Args": { 3748 "Name": "args", 3749 "Description": "command line arguments", 3750 "Settable": null, 3751 "Value": [ 3752 3753 ] 3754 } 3755 } 3756 } 3757 ``` 3758 3759 **Status codes**: 3760 3761 - **200** - no error 3762 - **404** - plugin not installed 3763 3764 #### Enable a plugin 3765 3766 `POST /plugins/(plugin name)/enable` 3767 3768 Enables a plugin 3769 3770 **Example request**: 3771 3772 ``` 3773 POST /v1.24/plugins/tiborvass/no-remove:latest/enable HTTP/1.1 3774 ``` 3775 3776 The `:latest` tag is optional, and is used as default if omitted. 3777 3778 3779 **Example response**: 3780 3781 ``` 3782 HTTP/1.1 200 OK 3783 Content-Length: 0 3784 Content-Type: text/plain; charset=utf-8 3785 ``` 3786 3787 **Status codes**: 3788 3789 - **200** - no error 3790 - **404** - plugin not installed 3791 - **500** - plugin is already enabled 3792 3793 #### Disable a plugin 3794 3795 `POST /plugins/(plugin name)/disable` 3796 3797 Disables a plugin 3798 3799 **Example request**: 3800 3801 ``` 3802 POST /v1.24/plugins/tiborvass/no-remove:latest/disable HTTP/1.1 3803 ``` 3804 3805 The `:latest` tag is optional, and is used as default if omitted. 3806 3807 3808 **Example response**: 3809 3810 ``` 3811 HTTP/1.1 200 OK 3812 Content-Length: 0 3813 Content-Type: text/plain; charset=utf-8 3814 ``` 3815 3816 **Status codes**: 3817 3818 - **200** - no error 3819 - **404** - plugin not installed 3820 - **500** - plugin is already disabled 3821 3822 #### Remove a plugin 3823 3824 `DELETE /plugins/(plugin name)` 3825 3826 Removes a plugin 3827 3828 **Example request**: 3829 3830 ``` 3831 DELETE /v1.24/plugins/tiborvass/no-remove:latest HTTP/1.1 3832 ``` 3833 3834 The `:latest` tag is optional, and is used as default if omitted. 3835 3836 **Example response**: 3837 3838 ``` 3839 HTTP/1.1 200 OK 3840 Content-Length: 0 3841 Content-Type: text/plain; charset=utf-8 3842 ``` 3843 3844 **Status codes**: 3845 3846 - **200** - no error 3847 - **404** - plugin not installed 3848 - **500** - plugin is active 3849 3850 <!-- TODO Document "docker plugin push" endpoint once we have "plugin build" 3851 3852 #### Push a plugin 3853 3854 `POST /v1.24/plugins/tiborvass/(plugin name)/push HTTP/1.1` 3855 3856 Pushes a plugin to the registry. 3857 3858 **Example request**: 3859 3860 ``` 3861 POST /v1.24/plugins/tiborvass/no-remove:latest HTTP/1.1 3862 ``` 3863 3864 The `:latest` tag is optional, and is used as default if omitted. When using 3865 this endpoint to push a plugin to the registry, the `X-Registry-Auth` header 3866 can be used to include a base64-encoded AuthConfig object. Refer to the [create 3867 an image](#create-an-image) section for more details. 3868 3869 **Example response**: 3870 3871 **Status codes**: 3872 3873 - **200** - no error 3874 - **404** - plugin not installed 3875 3876 --> 3877 3878 ### 3.7 Nodes 3879 3880 **Note**: Node operations require the engine to be part of a swarm. 3881 3882 #### List nodes 3883 3884 3885 `GET /nodes` 3886 3887 List nodes 3888 3889 **Example request**: 3890 3891 GET /v1.24/nodes HTTP/1.1 3892 3893 **Example response**: 3894 3895 HTTP/1.1 200 OK 3896 Content-Type: application/json 3897 3898 [ 3899 { 3900 "ID": "24ifsmvkjbyhk", 3901 "Version": { 3902 "Index": 8 3903 }, 3904 "CreatedAt": "2016-06-07T20:31:11.853781916Z", 3905 "UpdatedAt": "2016-06-07T20:31:11.999868824Z", 3906 "Spec": { 3907 "Name": "my-node", 3908 "Role": "manager", 3909 "Availability": "active" 3910 "Labels": { 3911 "foo": "bar" 3912 } 3913 }, 3914 "Description": { 3915 "Hostname": "bf3067039e47", 3916 "Platform": { 3917 "Architecture": "x86_64", 3918 "OS": "linux" 3919 }, 3920 "Resources": { 3921 "NanoCPUs": 4000000000, 3922 "MemoryBytes": 8272408576 3923 }, 3924 "Engine": { 3925 "EngineVersion": "1.12.0", 3926 "Labels": { 3927 "foo": "bar", 3928 } 3929 "Plugins": [ 3930 { 3931 "Type": "Volume", 3932 "Name": "local" 3933 }, 3934 { 3935 "Type": "Network", 3936 "Name": "bridge" 3937 } 3938 { 3939 "Type": "Network", 3940 "Name": "null" 3941 } 3942 { 3943 "Type": "Network", 3944 "Name": "overlay" 3945 } 3946 ] 3947 } 3948 }, 3949 "Status": { 3950 "State": "ready" 3951 }, 3952 "ManagerStatus": { 3953 "Leader": true, 3954 "Reachability": "reachable", 3955 "Addr": "172.17.0.2:2377"" 3956 } 3957 } 3958 ] 3959 3960 **Query parameters**: 3961 3962 - **filters** – a JSON encoded value of the filters (a `map[string][]string`) to process on the 3963 nodes list. Available filters: 3964 - `id=<node id>` 3965 - `label=<engine label>` 3966 - `membership=`(`accepted`|`pending`)` 3967 - `name=<node name>` 3968 - `role=`(`manager`|`worker`)` 3969 3970 **Status codes**: 3971 3972 - **200** – no error 3973 - **406** - node is not part of a swarm 3974 - **500** – server error 3975 3976 #### Inspect a node 3977 3978 3979 `GET /nodes/(id or name)` 3980 3981 Return low-level information on the node `id` 3982 3983 **Example request**: 3984 3985 GET /v1.24/nodes/24ifsmvkjbyhk HTTP/1.1 3986 3987 **Example response**: 3988 3989 HTTP/1.1 200 OK 3990 Content-Type: application/json 3991 3992 { 3993 "ID": "24ifsmvkjbyhk", 3994 "Version": { 3995 "Index": 8 3996 }, 3997 "CreatedAt": "2016-06-07T20:31:11.853781916Z", 3998 "UpdatedAt": "2016-06-07T20:31:11.999868824Z", 3999 "Spec": { 4000 "Name": "my-node", 4001 "Role": "manager", 4002 "Availability": "active" 4003 "Labels": { 4004 "foo": "bar" 4005 } 4006 }, 4007 "Description": { 4008 "Hostname": "bf3067039e47", 4009 "Platform": { 4010 "Architecture": "x86_64", 4011 "OS": "linux" 4012 }, 4013 "Resources": { 4014 "NanoCPUs": 4000000000, 4015 "MemoryBytes": 8272408576 4016 }, 4017 "Engine": { 4018 "EngineVersion": "1.12.0", 4019 "Labels": { 4020 "foo": "bar", 4021 } 4022 "Plugins": [ 4023 { 4024 "Type": "Volume", 4025 "Name": "local" 4026 }, 4027 { 4028 "Type": "Network", 4029 "Name": "bridge" 4030 } 4031 { 4032 "Type": "Network", 4033 "Name": "null" 4034 } 4035 { 4036 "Type": "Network", 4037 "Name": "overlay" 4038 } 4039 ] 4040 } 4041 }, 4042 "Status": { 4043 "State": "ready" 4044 }, 4045 "ManagerStatus": { 4046 "Leader": true, 4047 "Reachability": "reachable", 4048 "Addr": "172.17.0.2:2377"" 4049 } 4050 } 4051 4052 **Status codes**: 4053 4054 - **200** – no error 4055 - **404** – no such node 4056 - **406** – node is not part of a swarm 4057 - **500** – server error 4058 4059 #### Remove a node 4060 4061 4062 `DELETE /nodes/(id or name)` 4063 4064 Remove a node from the swarm. 4065 4066 **Example request**: 4067 4068 DELETE /v1.24/nodes/24ifsmvkjbyhk HTTP/1.1 4069 4070 **Example response**: 4071 4072 HTTP/1.1 200 OK 4073 Content-Length: 0 4074 Content-Type: text/plain; charset=utf-8 4075 4076 **Query parameters**: 4077 4078 - **force** - 1/True/true or 0/False/false, Force remove a node from the swarm. 4079 Default `false`. 4080 4081 **Status codes**: 4082 4083 - **200** – no error 4084 - **404** – no such node 4085 - **406** – node is not part of a swarm 4086 - **500** – server error 4087 4088 #### Update a node 4089 4090 4091 `POST /nodes/(id)/update` 4092 4093 Update a node. 4094 4095 The payload of the `POST` request is the new `NodeSpec` and 4096 overrides the current `NodeSpec` for the specified node. 4097 4098 If `Availability` or `Role` are omitted, this returns an 4099 error. Any other field omitted resets the current value to either 4100 an empty value or the default cluster-wide value. 4101 4102 **Example Request** 4103 4104 POST /v1.24/nodes/24ifsmvkjbyhk/update?version=8 HTTP/1.1 4105 Content-Type: application/json 4106 4107 { 4108 "Availability": "active", 4109 "Name": "node-name", 4110 "Role": "manager", 4111 "Labels": { 4112 "foo": "bar" 4113 } 4114 } 4115 4116 **Example response**: 4117 4118 HTTP/1.1 200 OK 4119 Content-Length: 0 4120 Content-Type: text/plain; charset=utf-8 4121 4122 **Query parameters**: 4123 4124 - **version** – The version number of the node object being updated. This is 4125 required to avoid conflicting writes. 4126 4127 JSON Parameters: 4128 4129 - **Annotations** – Optional medata to associate with the node. 4130 - **Name** – User-defined name for the node. 4131 - **Labels** – A map of labels to associate with the node (e.g., 4132 `{"key":"value", "key2":"value2"}`). 4133 - **Role** - Role of the node (worker/manager). 4134 - **Availability** - Availability of the node (active/pause/drain). 4135 4136 4137 **Status codes**: 4138 4139 - **200** – no error 4140 - **404** – no such node 4141 - **406** – node is not part of a swarm 4142 - **500** – server error 4143 4144 ### 3.8 Swarm 4145 4146 #### Inspect swarm 4147 4148 4149 `GET /swarm` 4150 4151 Inspect swarm 4152 4153 **Example response**: 4154 4155 HTTP/1.1 200 OK 4156 Content-Type: application/json 4157 4158 { 4159 "CreatedAt" : "2016-08-15T16:00:20.349727406Z", 4160 "Spec" : { 4161 "Dispatcher" : { 4162 "HeartbeatPeriod" : 5000000000 4163 }, 4164 "Orchestration" : { 4165 "TaskHistoryRetentionLimit" : 10 4166 }, 4167 "CAConfig" : { 4168 "NodeCertExpiry" : 7776000000000000 4169 }, 4170 "Raft" : { 4171 "LogEntriesForSlowFollowers" : 500, 4172 "HeartbeatTick" : 1, 4173 "SnapshotInterval" : 10000, 4174 "ElectionTick" : 3 4175 }, 4176 "TaskDefaults" : {}, 4177 "Name" : "default" 4178 }, 4179 "JoinTokens" : { 4180 "Worker" : "SWMTKN-1-1h8aps2yszaiqmz2l3oc5392pgk8e49qhx2aj3nyv0ui0hez2a-6qmn92w6bu3jdvnglku58u11a", 4181 "Manager" : "SWMTKN-1-1h8aps2yszaiqmz2l3oc5392pgk8e49qhx2aj3nyv0ui0hez2a-8llk83c4wm9lwioey2s316r9l" 4182 }, 4183 "ID" : "70ilmkj2f6sp2137c753w2nmt", 4184 "UpdatedAt" : "2016-08-15T16:32:09.623207604Z", 4185 "Version" : { 4186 "Index" : 51 4187 } 4188 } 4189 4190 **Status codes**: 4191 4192 - **200** - no error 4193 - **406** – node is not part of a swarm 4194 - **500** - sever error 4195 4196 #### Initialize a new swarm 4197 4198 4199 `POST /swarm/init` 4200 4201 Initialize a new swarm. The body of the HTTP response includes the node ID. 4202 4203 **Example request**: 4204 4205 POST /v1.24/swarm/init HTTP/1.1 4206 Content-Type: application/json 4207 4208 { 4209 "ListenAddr": "0.0.0.0:2377", 4210 "AdvertiseAddr": "192.168.1.1:2377", 4211 "ForceNewCluster": false, 4212 "Spec": { 4213 "Orchestration": {}, 4214 "Raft": {}, 4215 "Dispatcher": {}, 4216 "CAConfig": {} 4217 } 4218 } 4219 4220 **Example response**: 4221 4222 HTTP/1.1 200 OK 4223 Content-Length: 28 4224 Content-Type: application/json 4225 Date: Thu, 01 Sep 2016 21:49:13 GMT 4226 Server: Docker/1.12.0 (linux) 4227 4228 "7v2t30z9blmxuhnyo6s4cpenp" 4229 4230 **Status codes**: 4231 4232 - **200** – no error 4233 - **400** – bad parameter 4234 - **406** – node is already part of a swarm 4235 - **500** - server error 4236 4237 JSON Parameters: 4238 4239 - **ListenAddr** – Listen address used for inter-manager communication, as well as determining 4240 the networking interface used for the VXLAN Tunnel Endpoint (VTEP). This can either be an 4241 address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port 4242 number, like `eth0:4567`. If the port number is omitted, the default swarm listening port is 4243 used. 4244 - **AdvertiseAddr** – Externally reachable address advertised to other nodes. This can either be 4245 an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port 4246 number, like `eth0:4567`. If the port number is omitted, the port number from the listen 4247 address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when 4248 possible. 4249 - **ForceNewCluster** – Force creation of a new swarm. 4250 - **Spec** – Configuration settings for the new swarm. 4251 - **Orchestration** – Configuration settings for the orchestration aspects of the swarm. 4252 - **TaskHistoryRetentionLimit** – Maximum number of tasks history stored. 4253 - **Raft** – Raft related configuration. 4254 - **SnapshotInterval** – Number of logs entries between snapshot. 4255 - **KeepOldSnapshots** – Number of snapshots to keep beyond the current snapshot. 4256 - **LogEntriesForSlowFollowers** – Number of log entries to keep around to sync up slow 4257 followers after a snapshot is created. 4258 - **HeartbeatTick** – Amount of ticks (in seconds) between each heartbeat. 4259 - **ElectionTick** – Amount of ticks (in seconds) needed without a leader to trigger a new 4260 election. 4261 - **Dispatcher** – Configuration settings for the task dispatcher. 4262 - **HeartbeatPeriod** – The delay for an agent to send a heartbeat to the dispatcher. 4263 - **CAConfig** – Certificate authority configuration. 4264 - **NodeCertExpiry** – Automatic expiry for nodes certificates. 4265 - **ExternalCA** - Configuration for forwarding signing requests to an external 4266 certificate authority. 4267 - **Protocol** - Protocol for communication with the external CA 4268 (currently only "cfssl" is supported). 4269 - **URL** - URL where certificate signing requests should be sent. 4270 - **Options** - An object with key/value pairs that are interpreted 4271 as protocol-specific options for the external CA driver. 4272 4273 #### Join an existing swarm 4274 4275 `POST /swarm/join` 4276 4277 Join an existing swarm 4278 4279 **Example request**: 4280 4281 POST /v1.24/swarm/join HTTP/1.1 4282 Content-Type: application/json 4283 4284 { 4285 "ListenAddr": "0.0.0.0:2377", 4286 "AdvertiseAddr": "192.168.1.1:2377", 4287 "RemoteAddrs": ["node1:2377"], 4288 "JoinToken": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2" 4289 } 4290 4291 **Example response**: 4292 4293 HTTP/1.1 200 OK 4294 Content-Length: 0 4295 Content-Type: text/plain; charset=utf-8 4296 4297 **Status codes**: 4298 4299 - **200** – no error 4300 - **400** – bad parameter 4301 - **406** – node is already part of a swarm 4302 - **500** - server error 4303 4304 JSON Parameters: 4305 4306 - **ListenAddr** – Listen address used for inter-manager communication if the node gets promoted to 4307 manager, as well as determining the networking interface used for the VXLAN Tunnel Endpoint (VTEP). 4308 - **AdvertiseAddr** – Externally reachable address advertised to other nodes. This can either be 4309 an address/port combination in the form `192.168.1.1:4567`, or an interface followed by a port 4310 number, like `eth0:4567`. If the port number is omitted, the port number from the listen 4311 address is used. If `AdvertiseAddr` is not specified, it will be automatically detected when 4312 possible. 4313 - **RemoteAddr** – Address of any manager node already participating in the swarm. 4314 - **JoinToken** – Secret token for joining this swarm. 4315 4316 #### Leave a swarm 4317 4318 4319 `POST /swarm/leave` 4320 4321 Leave a swarm 4322 4323 **Example request**: 4324 4325 POST /v1.24/swarm/leave HTTP/1.1 4326 4327 **Example response**: 4328 4329 HTTP/1.1 200 OK 4330 Content-Length: 0 4331 Content-Type: text/plain; charset=utf-8 4332 4333 **Query parameters**: 4334 4335 - **force** - Boolean (0/1, false/true). Force leave swarm, even if this is the last manager or that it will break the cluster. 4336 4337 **Status codes**: 4338 4339 - **200** – no error 4340 - **406** – node is not part of a swarm 4341 - **500** - server error 4342 4343 #### Update a swarm 4344 4345 4346 `POST /swarm/update` 4347 4348 Update a swarm 4349 4350 **Example request**: 4351 4352 POST /v1.24/swarm/update HTTP/1.1 4353 4354 { 4355 "Name": "default", 4356 "Orchestration": { 4357 "TaskHistoryRetentionLimit": 10 4358 }, 4359 "Raft": { 4360 "SnapshotInterval": 10000, 4361 "LogEntriesForSlowFollowers": 500, 4362 "HeartbeatTick": 1, 4363 "ElectionTick": 3 4364 }, 4365 "Dispatcher": { 4366 "HeartbeatPeriod": 5000000000 4367 }, 4368 "CAConfig": { 4369 "NodeCertExpiry": 7776000000000000 4370 }, 4371 "JoinTokens": { 4372 "Worker": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-1awxwuwd3z9j1z3puu7rcgdbx", 4373 "Manager": "SWMTKN-1-3pu6hszjas19xyp7ghgosyx9k8atbfcr8p2is99znpy26u2lkl-7p73s1dx5in4tatdymyhg9hu2" 4374 } 4375 } 4376 4377 4378 **Example response**: 4379 4380 HTTP/1.1 200 OK 4381 Content-Length: 0 4382 Content-Type: text/plain; charset=utf-8 4383 4384 **Query parameters**: 4385 4386 - **version** – The version number of the swarm object being updated. This is 4387 required to avoid conflicting writes. 4388 - **rotateWorkerToken** - Set to `true` (or `1`) to rotate the worker join token. 4389 - **rotateManagerToken** - Set to `true` (or `1`) to rotate the manager join token. 4390 4391 **Status codes**: 4392 4393 - **200** – no error 4394 - **400** – bad parameter 4395 - **406** – node is not part of a swarm 4396 - **500** - server error 4397 4398 JSON Parameters: 4399 4400 - **Orchestration** – Configuration settings for the orchestration aspects of the swarm. 4401 - **TaskHistoryRetentionLimit** – Maximum number of tasks history stored. 4402 - **Raft** – Raft related configuration. 4403 - **SnapshotInterval** – Number of logs entries between snapshot. 4404 - **KeepOldSnapshots** – Number of snapshots to keep beyond the current snapshot. 4405 - **LogEntriesForSlowFollowers** – Number of log entries to keep around to sync up slow 4406 followers after a snapshot is created. 4407 - **HeartbeatTick** – Amount of ticks (in seconds) between each heartbeat. 4408 - **ElectionTick** – Amount of ticks (in seconds) needed without a leader to trigger a new 4409 election. 4410 - **Dispatcher** – Configuration settings for the task dispatcher. 4411 - **HeartbeatPeriod** – The delay for an agent to send a heartbeat to the dispatcher. 4412 - **CAConfig** – CA configuration. 4413 - **NodeCertExpiry** – Automatic expiry for nodes certificates. 4414 - **ExternalCA** - Configuration for forwarding signing requests to an external 4415 certificate authority. 4416 - **Protocol** - Protocol for communication with the external CA 4417 (currently only "cfssl" is supported). 4418 - **URL** - URL where certificate signing requests should be sent. 4419 - **Options** - An object with key/value pairs that are interpreted 4420 as protocol-specific options for the external CA driver. 4421 - **JoinTokens** - Tokens that can be used by other nodes to join the swarm. 4422 - **Worker** - Token to use for joining as a worker. 4423 - **Manager** - Token to use for joining as a manager. 4424 4425 ### 3.9 Services 4426 4427 **Note**: Service operations require to first be part of a swarm. 4428 4429 #### List services 4430 4431 4432 `GET /services` 4433 4434 List services 4435 4436 **Example request**: 4437 4438 GET /v1.24/services HTTP/1.1 4439 4440 **Example response**: 4441 4442 HTTP/1.1 200 OK 4443 Content-Type: application/json 4444 4445 [ 4446 { 4447 "ID": "9mnpnzenvg8p8tdbtq4wvbkcz", 4448 "Version": { 4449 "Index": 19 4450 }, 4451 "CreatedAt": "2016-06-07T21:05:51.880065305Z", 4452 "UpdatedAt": "2016-06-07T21:07:29.962229872Z", 4453 "Spec": { 4454 "Name": "hopeful_cori", 4455 "TaskTemplate": { 4456 "ContainerSpec": { 4457 "Image": "redis" 4458 }, 4459 "Resources": { 4460 "Limits": {}, 4461 "Reservations": {} 4462 }, 4463 "RestartPolicy": { 4464 "Condition": "any", 4465 "MaxAttempts": 0 4466 }, 4467 "Placement": { 4468 "Constraints": [ 4469 "node.role == worker" 4470 ] 4471 } 4472 }, 4473 "Mode": { 4474 "Replicated": { 4475 "Replicas": 1 4476 } 4477 }, 4478 "UpdateConfig": { 4479 "Parallelism": 1, 4480 "FailureAction": "pause" 4481 }, 4482 "EndpointSpec": { 4483 "Mode": "vip", 4484 "Ports": [ 4485 { 4486 "Protocol": "tcp", 4487 "TargetPort": 6379, 4488 "PublishedPort": 30001 4489 } 4490 ] 4491 } 4492 }, 4493 "Endpoint": { 4494 "Spec": { 4495 "Mode": "vip", 4496 "Ports": [ 4497 { 4498 "Protocol": "tcp", 4499 "TargetPort": 6379, 4500 "PublishedPort": 30001 4501 } 4502 ] 4503 }, 4504 "Ports": [ 4505 { 4506 "Protocol": "tcp", 4507 "TargetPort": 6379, 4508 "PublishedPort": 30001 4509 } 4510 ], 4511 "VirtualIPs": [ 4512 { 4513 "NetworkID": "4qvuz4ko70xaltuqbt8956gd1", 4514 "Addr": "10.255.0.2/16" 4515 }, 4516 { 4517 "NetworkID": "4qvuz4ko70xaltuqbt8956gd1", 4518 "Addr": "10.255.0.3/16" 4519 } 4520 ] 4521 } 4522 } 4523 ] 4524 4525 **Query parameters**: 4526 4527 - **filters** – a JSON encoded value of the filters (a `map[string][]string`) to process on the 4528 services list. Available filters: 4529 - `id=<service id>` 4530 - `label=<service label>` 4531 - `name=<service name>` 4532 4533 **Status codes**: 4534 4535 - **200** – no error 4536 - **406** – node is not part of a swarm 4537 - **500** – server error 4538 4539 #### Create a service 4540 4541 `POST /services/create` 4542 4543 Create a service. When using this endpoint to create a service using a private 4544 repository from the registry, the `X-Registry-Auth` header must be used to 4545 include a base64-encoded AuthConfig object. Refer to the [create an 4546 image](#create-an-image) section for more details. 4547 4548 **Example request**: 4549 4550 POST /v1.24/services/create HTTP/1.1 4551 Content-Type: application/json 4552 4553 { 4554 "Name": "web", 4555 "TaskTemplate": { 4556 "ContainerSpec": { 4557 "Image": "nginx:alpine", 4558 "Mounts": [ 4559 { 4560 "ReadOnly": true, 4561 "Source": "web-data", 4562 "Target": "/usr/share/nginx/html", 4563 "Type": "volume", 4564 "VolumeOptions": { 4565 "DriverConfig": { 4566 }, 4567 "Labels": { 4568 "com.example.something": "something-value" 4569 } 4570 } 4571 } 4572 ], 4573 "User": "33" 4574 }, 4575 "Networks": [ 4576 { 4577 "Target": "overlay1" 4578 } 4579 ], 4580 "LogDriver": { 4581 "Name": "json-file", 4582 "Options": { 4583 "max-file": "3", 4584 "max-size": "10M" 4585 } 4586 }, 4587 "Placement": { 4588 "Constraints": [ 4589 "node.role == worker" 4590 ] 4591 }, 4592 "Resources": { 4593 "Limits": { 4594 "MemoryBytes": 104857600 4595 }, 4596 "Reservations": { 4597 } 4598 }, 4599 "RestartPolicy": { 4600 "Condition": "on-failure", 4601 "Delay": 10000000000, 4602 "MaxAttempts": 10 4603 } 4604 }, 4605 "Mode": { 4606 "Replicated": { 4607 "Replicas": 4 4608 } 4609 }, 4610 "UpdateConfig": { 4611 "Delay": 30000000000, 4612 "Parallelism": 2, 4613 "FailureAction": "pause" 4614 }, 4615 "EndpointSpec": { 4616 "Ports": [ 4617 { 4618 "Protocol": "tcp", 4619 "PublishedPort": 8080, 4620 "TargetPort": 80 4621 } 4622 ] 4623 }, 4624 "Labels": { 4625 "foo": "bar" 4626 } 4627 } 4628 4629 **Example response**: 4630 4631 HTTP/1.1 201 Created 4632 Content-Type: application/json 4633 4634 { 4635 "ID":"ak7w3gjqoa3kuz8xcpnyy0pvl" 4636 } 4637 4638 **Status codes**: 4639 4640 - **201** – no error 4641 - **403** - network is not eligible for services 4642 - **406** – node is not part of a swarm 4643 - **409** – name conflicts with an existing object 4644 - **500** - server error 4645 4646 **JSON Parameters**: 4647 4648 - **Name** – User-defined name for the service. 4649 - **Labels** – A map of labels to associate with the service (e.g., `{"key":"value", "key2":"value2"}`). 4650 - **TaskTemplate** – Specification of the tasks to start as part of the new service. 4651 - **ContainerSpec** - Container settings for containers started as part of this task. 4652 - **Image** – A string specifying the image name to use for the container. 4653 - **Command** – The command to be run in the image. 4654 - **Args** – Arguments to the command. 4655 - **Env** – A list of environment variables in the form of `["VAR=value"[,"VAR2=value2"]]`. 4656 - **Dir** – A string specifying the working directory for commands to run in. 4657 - **User** – A string value specifying the user inside the container. 4658 - **Labels** – A map of labels to associate with the service (e.g., 4659 `{"key":"value", "key2":"value2"}`). 4660 - **Mounts** – Specification for mounts to be added to containers 4661 created as part of the service. 4662 - **Target** – Container path. 4663 - **Source** – Mount source (e.g. a volume name, a host path). 4664 - **Type** – The mount type (`bind`, or `volume`). 4665 - **ReadOnly** – A boolean indicating whether the mount should be read-only. 4666 - **BindOptions** - Optional configuration for the `bind` type. 4667 - **Propagation** – A propagation mode with the value `[r]private`, `[r]shared`, or `[r]slave`. 4668 - **VolumeOptions** – Optional configuration for the `volume` type. 4669 - **NoCopy** – A boolean indicating if volume should be 4670 populated with the data from the target. (Default false) 4671 - **Labels** – User-defined name and labels for the volume. 4672 - **DriverConfig** – Map of driver-specific options. 4673 - **Name** - Name of the driver to use to create the volume. 4674 - **Options** - key/value map of driver specific options. 4675 - **StopGracePeriod** – Amount of time to wait for the container to terminate before 4676 forcefully killing it. 4677 - **LogDriver** - Log configuration for containers created as part of the 4678 service. 4679 - **Name** - Name of the logging driver to use (`json-file`, `syslog`, 4680 `journald`, `gelf`, `fluentd`, `awslogs`, `splunk`, `etwlogs`, `none`). 4681 - **Options** - Driver-specific options. 4682 - **Resources** – Resource requirements which apply to each individual container created as part 4683 of the service. 4684 - **Limits** – Define resources limits. 4685 - **NanoCPUs** – CPU limit in units of 10<sup>-9</sup> CPU shares. 4686 - **MemoryBytes** – Memory limit in Bytes. 4687 - **Reservation** – Define resources reservation. 4688 - **NanoCPUs** – CPU reservation in units of 10<sup>-9</sup> CPU shares. 4689 - **MemoryBytes** – Memory reservation in Bytes. 4690 - **RestartPolicy** – Specification for the restart policy which applies to containers created 4691 as part of this service. 4692 - **Condition** – Condition for restart (`none`, `on-failure`, or `any`). 4693 - **Delay** – Delay between restart attempts. 4694 - **MaxAttempts** – Maximum attempts to restart a given container before giving up (default value 4695 is 0, which is ignored). 4696 - **Window** – Windows is the time window used to evaluate the restart policy (default value is 4697 0, which is unbounded). 4698 - **Placement** – Restrictions on where a service can run. 4699 - **Constraints** – An array of constraints, e.g. `[ "node.role == manager" ]`. 4700 - **Mode** – Scheduling mode for the service (`replicated` or `global`, defaults to `replicated`). 4701 - **UpdateConfig** – Specification for the update strategy of the service. 4702 - **Parallelism** – Maximum number of tasks to be updated in one iteration (0 means unlimited 4703 parallelism). 4704 - **Delay** – Amount of time between updates. 4705 - **FailureAction** - Action to take if an updated task fails to run, or stops running during the 4706 update. Values are `continue` and `pause`. 4707 - **Networks** – Array of network names or IDs to attach the service to. 4708 - **EndpointSpec** – Properties that can be configured to access and load balance a service. 4709 - **Mode** – The mode of resolution to use for internal load balancing 4710 between tasks (`vip` or `dnsrr`). Defaults to `vip` if not provided. 4711 - **Ports** – List of exposed ports that this service is accessible on from 4712 the outside, in the form of: 4713 `{"Protocol": <"tcp"|"udp">, "PublishedPort": <port>, "TargetPort": <port>}`. 4714 Ports can only be provided if `vip` resolution mode is used. 4715 4716 **Request Headers**: 4717 4718 - **Content-type** – Set to `"application/json"`. 4719 - **X-Registry-Auth** – base64-encoded AuthConfig object, containing either 4720 login information, or a token. Refer to the [create an image](#create-an-image) 4721 section for more details. 4722 4723 4724 #### Remove a service 4725 4726 4727 `DELETE /services/(id or name)` 4728 4729 Stop and remove the service `id` 4730 4731 **Example request**: 4732 4733 DELETE /v1.24/services/16253994b7c4 HTTP/1.1 4734 4735 **Example response**: 4736 4737 HTTP/1.1 200 OK 4738 Content-Length: 0 4739 Content-Type: text/plain; charset=utf-8 4740 4741 **Status codes**: 4742 4743 - **200** – no error 4744 - **404** – no such service 4745 - **406** - node is not part of a swarm 4746 - **500** – server error 4747 4748 #### Inspect one or more services 4749 4750 4751 `GET /services/(id or name)` 4752 4753 Return information on the service `id`. 4754 4755 **Example request**: 4756 4757 GET /v1.24/services/1cb4dnqcyx6m66g2t538x3rxha HTTP/1.1 4758 4759 **Example response**: 4760 4761 { 4762 "ID": "ak7w3gjqoa3kuz8xcpnyy0pvl", 4763 "Version": { 4764 "Index": 95 4765 }, 4766 "CreatedAt": "2016-06-07T21:10:20.269723157Z", 4767 "UpdatedAt": "2016-06-07T21:10:20.276301259Z", 4768 "Spec": { 4769 "Name": "redis", 4770 "TaskTemplate": { 4771 "ContainerSpec": { 4772 "Image": "redis" 4773 }, 4774 "Resources": { 4775 "Limits": {}, 4776 "Reservations": {} 4777 }, 4778 "RestartPolicy": { 4779 "Condition": "any", 4780 "MaxAttempts": 0 4781 }, 4782 "Placement": {} 4783 }, 4784 "Mode": { 4785 "Replicated": { 4786 "Replicas": 1 4787 } 4788 }, 4789 "UpdateConfig": { 4790 "Parallelism": 1, 4791 "FailureAction": "pause" 4792 }, 4793 "EndpointSpec": { 4794 "Mode": "vip", 4795 "Ports": [ 4796 { 4797 "Protocol": "tcp", 4798 "TargetPort": 6379, 4799 "PublishedPort": 30001 4800 } 4801 ] 4802 } 4803 }, 4804 "Endpoint": { 4805 "Spec": { 4806 "Mode": "vip", 4807 "Ports": [ 4808 { 4809 "Protocol": "tcp", 4810 "TargetPort": 6379, 4811 "PublishedPort": 30001 4812 } 4813 ] 4814 }, 4815 "Ports": [ 4816 { 4817 "Protocol": "tcp", 4818 "TargetPort": 6379, 4819 "PublishedPort": 30001 4820 } 4821 ], 4822 "VirtualIPs": [ 4823 { 4824 "NetworkID": "4qvuz4ko70xaltuqbt8956gd1", 4825 "Addr": "10.255.0.4/16" 4826 } 4827 ] 4828 } 4829 } 4830 4831 **Status codes**: 4832 4833 - **200** – no error 4834 - **404** – no such service 4835 - **406** - node is not part of a swarm 4836 - **500** – server error 4837 4838 #### Update a service 4839 4840 `POST /services/(id)/update` 4841 4842 Update a service. When using this endpoint to create a service using a 4843 private repository from the registry, the `X-Registry-Auth` header can be used 4844 to update the authentication information for that is stored for the service. 4845 The header contains a base64-encoded AuthConfig object. Refer to the [create an 4846 image](#create-an-image) section for more details. 4847 4848 **Example request**: 4849 4850 POST /v1.24/services/1cb4dnqcyx6m66g2t538x3rxha/update?version=23 HTTP/1.1 4851 Content-Type: application/json 4852 4853 { 4854 "Name": "top", 4855 "TaskTemplate": { 4856 "ContainerSpec": { 4857 "Image": "busybox", 4858 "Args": [ 4859 "top" 4860 ] 4861 }, 4862 "Resources": { 4863 "Limits": {}, 4864 "Reservations": {} 4865 }, 4866 "RestartPolicy": { 4867 "Condition": "any", 4868 "MaxAttempts": 0 4869 }, 4870 "Placement": {} 4871 }, 4872 "Mode": { 4873 "Replicated": { 4874 "Replicas": 1 4875 } 4876 }, 4877 "UpdateConfig": { 4878 "Parallelism": 1 4879 }, 4880 "EndpointSpec": { 4881 "Mode": "vip" 4882 } 4883 } 4884 4885 **Example response**: 4886 4887 HTTP/1.1 200 OK 4888 Content-Length: 0 4889 Content-Type: text/plain; charset=utf-8 4890 4891 **JSON Parameters**: 4892 4893 - **Name** – User-defined name for the service. Note that renaming services is not supported. 4894 - **Labels** – A map of labels to associate with the service (e.g., `{"key":"value", "key2":"value2"}`). 4895 - **TaskTemplate** – Specification of the tasks to start as part of the new service. 4896 - **ContainerSpec** - Container settings for containers started as part of this task. 4897 - **Image** – A string specifying the image name to use for the container. 4898 - **Command** – The command to be run in the image. 4899 - **Args** – Arguments to the command. 4900 - **Env** – A list of environment variables in the form of `["VAR=value"[,"VAR2=value2"]]`. 4901 - **Dir** – A string specifying the working directory for commands to run in. 4902 - **User** – A string value specifying the user inside the container. 4903 - **Labels** – A map of labels to associate with the service (e.g., 4904 `{"key":"value", "key2":"value2"}`). 4905 - **Mounts** – Specification for mounts to be added to containers created as part of the new 4906 service. 4907 - **Target** – Container path. 4908 - **Source** – Mount source (e.g. a volume name, a host path). 4909 - **Type** – The mount type (`bind`, or `volume`). 4910 - **ReadOnly** – A boolean indicating whether the mount should be read-only. 4911 - **BindOptions** - Optional configuration for the `bind` type 4912 - **Propagation** – A propagation mode with the value `[r]private`, `[r]shared`, or `[r]slave`. 4913 - **VolumeOptions** – Optional configuration for the `volume` type. 4914 - **NoCopy** – A boolean indicating if volume should be 4915 populated with the data from the target. (Default false) 4916 - **Labels** – User-defined name and labels for the volume. 4917 - **DriverConfig** – Map of driver-specific options. 4918 - **Name** - Name of the driver to use to create the volume 4919 - **Options** - key/value map of driver specific options 4920 - **StopGracePeriod** – Amount of time to wait for the container to terminate before 4921 forcefully killing it. 4922 - **Resources** – Resource requirements which apply to each individual container created as part 4923 of the service. 4924 - **Limits** – Define resources limits. 4925 - **CPU** – CPU limit 4926 - **Memory** – Memory limit 4927 - **Reservation** – Define resources reservation. 4928 - **CPU** – CPU reservation 4929 - **Memory** – Memory reservation 4930 - **RestartPolicy** – Specification for the restart policy which applies to containers created 4931 as part of this service. 4932 - **Condition** – Condition for restart (`none`, `on-failure`, or `any`). 4933 - **Delay** – Delay between restart attempts. 4934 - **MaxAttempts** – Maximum attempts to restart a given container before giving up (default value 4935 is 0, which is ignored). 4936 - **Window** – Windows is the time window used to evaluate the restart policy (default value is 4937 0, which is unbounded). 4938 - **Placement** – Restrictions on where a service can run. 4939 - **Constraints** – An array of constraints, e.g. `[ "node.role == manager" ]`. 4940 - **Mode** – Scheduling mode for the service (`replicated` or `global`, defaults to `replicated`). 4941 - **UpdateConfig** – Specification for the update strategy of the service. 4942 - **Parallelism** – Maximum number of tasks to be updated in one iteration (0 means unlimited 4943 parallelism). 4944 - **Delay** – Amount of time between updates. 4945 - **Networks** – Array of network names or IDs to attach the service to. 4946 - **EndpointSpec** – Properties that can be configured to access and load balance a service. 4947 - **Mode** – The mode of resolution to use for internal load balancing 4948 between tasks (`vip` or `dnsrr`). Defaults to `vip` if not provided. 4949 - **Ports** – List of exposed ports that this service is accessible on from 4950 the outside, in the form of: 4951 `{"Protocol": <"tcp"|"udp">, "PublishedPort": <port>, "TargetPort": <port>}`. 4952 Ports can only be provided if `vip` resolution mode is used. 4953 4954 **Query parameters**: 4955 4956 - **version** – The version number of the service object being updated. This is 4957 required to avoid conflicting writes. 4958 4959 **Request Headers**: 4960 4961 - **Content-type** – Set to `"application/json"`. 4962 - **X-Registry-Auth** – base64-encoded AuthConfig object, containing either 4963 login information, or a token. Refer to the [create an image](#create-an-image) 4964 section for more details. 4965 4966 **Status codes**: 4967 4968 - **200** – no error 4969 - **404** – no such service 4970 - **406** - node is not part of a swarm 4971 - **500** – server error 4972 4973 ### 3.10 Tasks 4974 4975 **Note**: Task operations require the engine to be part of a swarm. 4976 4977 #### List tasks 4978 4979 4980 `GET /tasks` 4981 4982 List tasks 4983 4984 **Example request**: 4985 4986 GET /v1.24/tasks HTTP/1.1 4987 4988 **Example response**: 4989 4990 [ 4991 { 4992 "ID": "0kzzo1i0y4jz6027t0k7aezc7", 4993 "Version": { 4994 "Index": 71 4995 }, 4996 "CreatedAt": "2016-06-07T21:07:31.171892745Z", 4997 "UpdatedAt": "2016-06-07T21:07:31.376370513Z", 4998 "Spec": { 4999 "ContainerSpec": { 5000 "Image": "redis" 5001 }, 5002 "Resources": { 5003 "Limits": {}, 5004 "Reservations": {} 5005 }, 5006 "RestartPolicy": { 5007 "Condition": "any", 5008 "MaxAttempts": 0 5009 }, 5010 "Placement": {} 5011 }, 5012 "ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz", 5013 "Slot": 1, 5014 "NodeID": "60gvrl6tm78dmak4yl7srz94v", 5015 "Status": { 5016 "Timestamp": "2016-06-07T21:07:31.290032978Z", 5017 "State": "running", 5018 "Message": "started", 5019 "ContainerStatus": { 5020 "ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035", 5021 "PID": 677 5022 } 5023 }, 5024 "DesiredState": "running", 5025 "NetworksAttachments": [ 5026 { 5027 "Network": { 5028 "ID": "4qvuz4ko70xaltuqbt8956gd1", 5029 "Version": { 5030 "Index": 18 5031 }, 5032 "CreatedAt": "2016-06-07T20:31:11.912919752Z", 5033 "UpdatedAt": "2016-06-07T21:07:29.955277358Z", 5034 "Spec": { 5035 "Name": "ingress", 5036 "Labels": { 5037 "com.docker.swarm.internal": "true" 5038 }, 5039 "DriverConfiguration": {}, 5040 "IPAMOptions": { 5041 "Driver": {}, 5042 "Configs": [ 5043 { 5044 "Subnet": "10.255.0.0/16", 5045 "Gateway": "10.255.0.1" 5046 } 5047 ] 5048 } 5049 }, 5050 "DriverState": { 5051 "Name": "overlay", 5052 "Options": { 5053 "com.docker.network.driver.overlay.vxlanid_list": "256" 5054 } 5055 }, 5056 "IPAMOptions": { 5057 "Driver": { 5058 "Name": "default" 5059 }, 5060 "Configs": [ 5061 { 5062 "Subnet": "10.255.0.0/16", 5063 "Gateway": "10.255.0.1" 5064 } 5065 ] 5066 } 5067 }, 5068 "Addresses": [ 5069 "10.255.0.10/16" 5070 ] 5071 } 5072 ], 5073 }, 5074 { 5075 "ID": "1yljwbmlr8er2waf8orvqpwms", 5076 "Version": { 5077 "Index": 30 5078 }, 5079 "CreatedAt": "2016-06-07T21:07:30.019104782Z", 5080 "UpdatedAt": "2016-06-07T21:07:30.231958098Z", 5081 "Name": "hopeful_cori", 5082 "Spec": { 5083 "ContainerSpec": { 5084 "Image": "redis" 5085 }, 5086 "Resources": { 5087 "Limits": {}, 5088 "Reservations": {} 5089 }, 5090 "RestartPolicy": { 5091 "Condition": "any", 5092 "MaxAttempts": 0 5093 }, 5094 "Placement": {} 5095 }, 5096 "ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz", 5097 "Slot": 1, 5098 "NodeID": "60gvrl6tm78dmak4yl7srz94v", 5099 "Status": { 5100 "Timestamp": "2016-06-07T21:07:30.202183143Z", 5101 "State": "shutdown", 5102 "Message": "shutdown", 5103 "ContainerStatus": { 5104 "ContainerID": "1cf8d63d18e79668b0004a4be4c6ee58cddfad2dae29506d8781581d0688a213" 5105 } 5106 }, 5107 "DesiredState": "shutdown", 5108 "NetworksAttachments": [ 5109 { 5110 "Network": { 5111 "ID": "4qvuz4ko70xaltuqbt8956gd1", 5112 "Version": { 5113 "Index": 18 5114 }, 5115 "CreatedAt": "2016-06-07T20:31:11.912919752Z", 5116 "UpdatedAt": "2016-06-07T21:07:29.955277358Z", 5117 "Spec": { 5118 "Name": "ingress", 5119 "Labels": { 5120 "com.docker.swarm.internal": "true" 5121 }, 5122 "DriverConfiguration": {}, 5123 "IPAMOptions": { 5124 "Driver": {}, 5125 "Configs": [ 5126 { 5127 "Subnet": "10.255.0.0/16", 5128 "Gateway": "10.255.0.1" 5129 } 5130 ] 5131 } 5132 }, 5133 "DriverState": { 5134 "Name": "overlay", 5135 "Options": { 5136 "com.docker.network.driver.overlay.vxlanid_list": "256" 5137 } 5138 }, 5139 "IPAMOptions": { 5140 "Driver": { 5141 "Name": "default" 5142 }, 5143 "Configs": [ 5144 { 5145 "Subnet": "10.255.0.0/16", 5146 "Gateway": "10.255.0.1" 5147 } 5148 ] 5149 } 5150 }, 5151 "Addresses": [ 5152 "10.255.0.5/16" 5153 ] 5154 } 5155 ] 5156 } 5157 ] 5158 5159 **Query parameters**: 5160 5161 - **filters** – a JSON encoded value of the filters (a `map[string][]string`) to process on the 5162 services list. Available filters: 5163 - `id=<task id>` 5164 - `name=<task name>` 5165 - `service=<service name>` 5166 - `node=<node id or name>` 5167 - `label=key` or `label="key=value"` 5168 - `desired-state=(running | shutdown | accepted)` 5169 5170 **Status codes**: 5171 5172 - **200** – no error 5173 - **406** - node is not part of a swarm 5174 - **500** – server error 5175 5176 #### Inspect a task 5177 5178 5179 `GET /tasks/(id)` 5180 5181 Get details on the task `id` 5182 5183 **Example request**: 5184 5185 GET /v1.24/tasks/0kzzo1i0y4jz6027t0k7aezc7 HTTP/1.1 5186 5187 **Example response**: 5188 5189 { 5190 "ID": "0kzzo1i0y4jz6027t0k7aezc7", 5191 "Version": { 5192 "Index": 71 5193 }, 5194 "CreatedAt": "2016-06-07T21:07:31.171892745Z", 5195 "UpdatedAt": "2016-06-07T21:07:31.376370513Z", 5196 "Spec": { 5197 "ContainerSpec": { 5198 "Image": "redis" 5199 }, 5200 "Resources": { 5201 "Limits": {}, 5202 "Reservations": {} 5203 }, 5204 "RestartPolicy": { 5205 "Condition": "any", 5206 "MaxAttempts": 0 5207 }, 5208 "Placement": {} 5209 }, 5210 "ServiceID": "9mnpnzenvg8p8tdbtq4wvbkcz", 5211 "Slot": 1, 5212 "NodeID": "60gvrl6tm78dmak4yl7srz94v", 5213 "Status": { 5214 "Timestamp": "2016-06-07T21:07:31.290032978Z", 5215 "State": "running", 5216 "Message": "started", 5217 "ContainerStatus": { 5218 "ContainerID": "e5d62702a1b48d01c3e02ca1e0212a250801fa8d67caca0b6f35919ebc12f035", 5219 "PID": 677 5220 } 5221 }, 5222 "DesiredState": "running", 5223 "NetworksAttachments": [ 5224 { 5225 "Network": { 5226 "ID": "4qvuz4ko70xaltuqbt8956gd1", 5227 "Version": { 5228 "Index": 18 5229 }, 5230 "CreatedAt": "2016-06-07T20:31:11.912919752Z", 5231 "UpdatedAt": "2016-06-07T21:07:29.955277358Z", 5232 "Spec": { 5233 "Name": "ingress", 5234 "Labels": { 5235 "com.docker.swarm.internal": "true" 5236 }, 5237 "DriverConfiguration": {}, 5238 "IPAMOptions": { 5239 "Driver": {}, 5240 "Configs": [ 5241 { 5242 "Subnet": "10.255.0.0/16", 5243 "Gateway": "10.255.0.1" 5244 } 5245 ] 5246 } 5247 }, 5248 "DriverState": { 5249 "Name": "overlay", 5250 "Options": { 5251 "com.docker.network.driver.overlay.vxlanid_list": "256" 5252 } 5253 }, 5254 "IPAMOptions": { 5255 "Driver": { 5256 "Name": "default" 5257 }, 5258 "Configs": [ 5259 { 5260 "Subnet": "10.255.0.0/16", 5261 "Gateway": "10.255.0.1" 5262 } 5263 ] 5264 } 5265 }, 5266 "Addresses": [ 5267 "10.255.0.10/16" 5268 ] 5269 } 5270 ] 5271 } 5272 5273 **Status codes**: 5274 5275 - **200** – no error 5276 - **404** – unknown task 5277 - **406** - node is not part of a swarm 5278 - **500** – server error 5279 5280 ## 4. Going further 5281 5282 ### 4.1 Inside `docker run` 5283 5284 As an example, the `docker run` command line makes the following API calls: 5285 5286 - Create the container 5287 5288 - If the status code is 404, it means the image doesn't exist: 5289 - Try to pull it. 5290 - Then, retry to create the container. 5291 5292 - Start the container. 5293 5294 - If you are not in detached mode: 5295 - Attach to the container, using `logs=1` (to have `stdout` and 5296 `stderr` from the container's start) and `stream=1` 5297 5298 - If in detached mode or only `stdin` is attached, display the container's id. 5299 5300 ### 4.2 Hijacking 5301 5302 In this version of the API, `/attach`, uses hijacking to transport `stdin`, 5303 `stdout`, and `stderr` on the same socket. 5304 5305 To hint potential proxies about connection hijacking, Docker client sends 5306 connection upgrade headers similarly to websocket. 5307 5308 Upgrade: tcp 5309 Connection: Upgrade 5310 5311 When Docker daemon detects the `Upgrade` header, it switches its status code 5312 from **200 OK** to **101 UPGRADED** and resends the same headers. 5313 5314 5315 ### 4.3 CORS Requests 5316 5317 To set cross origin requests to the Engine API please give values to 5318 `--api-cors-header` when running Docker in daemon mode. Set * (asterisk) allows all, 5319 default or blank means CORS disabled 5320 5321 $ dockerd -H="192.168.1.9:2375" --api-cors-header="http://foo.bar"