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