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