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