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