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