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