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