github.com/vieux/docker@v0.6.3-0.20161004191708-e097c2a938c7/docs/reference/api/docker_remote_api_v1.22.md (about) 1 <!--[metadata]> 2 +++ 3 title = "Remote API v1.22" 4 description = "API Documentation for Docker" 5 keywords = ["API, Docker, rcli, REST, documentation"] 6 [menu.main] 7 parent="engine_remoteapi" 8 weight=-3 9 +++ 10 <![end-metadata]--> 11 12 # Docker Remote API v1.22 13 14 ## 1. Brief introduction 15 16 - The Remote API has replaced `rcli`. 17 - The daemon listens on `unix:///var/run/docker.sock` but you can 18 [Bind Docker to another host/port or a Unix socket](../commandline/dockerd.md#bind-docker-to-another-host-port-or-a-unix-socket). 19 - The API tends to be REST. However, for some complex commands, like `attach` 20 or `pull`, the HTTP connection is hijacked to transport `stdout`, 21 `stdin` and `stderr`. 22 - When the client API version is newer than the daemon's, these calls return an HTTP 23 `400 Bad Request` error message. 24 25 # 2. Endpoints 26 27 ## 2.1 Containers 28 29 ### List containers 30 31 `GET /containers/json` 32 33 List containers 34 35 **Example request**: 36 37 GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 38 39 **Example response**: 40 41 HTTP/1.1 200 OK 42 Content-Type: application/json 43 44 [ 45 { 46 "Id": "8dfafdbc3a40", 47 "Names":["/boring_feynman"], 48 "Image": "ubuntu:latest", 49 "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", 50 "Command": "echo 1", 51 "Created": 1367854155, 52 "Status": "Exit 0", 53 "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], 54 "Labels": { 55 "com.example.vendor": "Acme", 56 "com.example.license": "GPL", 57 "com.example.version": "1.0" 58 }, 59 "SizeRw": 12288, 60 "SizeRootFs": 0, 61 "HostConfig": { 62 "NetworkMode": "default" 63 }, 64 "NetworkSettings": { 65 "Networks": { 66 "bridge": { 67 "IPAMConfig": null, 68 "Links": null, 69 "Aliases": null, 70 "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812", 71 "EndpointID": "2cdc4edb1ded3631c81f57966563e5c8525b81121bb3706a9a9a3ae102711f3f", 72 "Gateway": "172.17.0.1", 73 "IPAddress": "172.17.0.2", 74 "IPPrefixLen": 16, 75 "IPv6Gateway": "", 76 "GlobalIPv6Address": "", 77 "GlobalIPv6PrefixLen": 0, 78 "MacAddress": "02:42:ac:11:00:02" 79 } 80 } 81 } 82 }, 83 { 84 "Id": "9cd87474be90", 85 "Names":["/coolName"], 86 "Image": "ubuntu:latest", 87 "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", 88 "Command": "echo 222222", 89 "Created": 1367854155, 90 "Status": "Exit 0", 91 "Ports": [], 92 "Labels": {}, 93 "SizeRw": 12288, 94 "SizeRootFs": 0, 95 "HostConfig": { 96 "NetworkMode": "default" 97 }, 98 "NetworkSettings": { 99 "Networks": { 100 "bridge": { 101 "IPAMConfig": null, 102 "Links": null, 103 "Aliases": null, 104 "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812", 105 "EndpointID": "88eaed7b37b38c2a3f0c4bc796494fdf51b270c2d22656412a2ca5d559a64d7a", 106 "Gateway": "172.17.0.1", 107 "IPAddress": "172.17.0.8", 108 "IPPrefixLen": 16, 109 "IPv6Gateway": "", 110 "GlobalIPv6Address": "", 111 "GlobalIPv6PrefixLen": 0, 112 "MacAddress": "02:42:ac:11:00:08" 113 } 114 } 115 } 116 }, 117 { 118 "Id": "3176a2479c92", 119 "Names":["/sleepy_dog"], 120 "Image": "ubuntu:latest", 121 "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", 122 "Command": "echo 3333333333333333", 123 "Created": 1367854154, 124 "Status": "Exit 0", 125 "Ports":[], 126 "Labels": {}, 127 "SizeRw":12288, 128 "SizeRootFs":0, 129 "HostConfig": { 130 "NetworkMode": "default" 131 }, 132 "NetworkSettings": { 133 "Networks": { 134 "bridge": { 135 "IPAMConfig": null, 136 "Links": null, 137 "Aliases": null, 138 "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812", 139 "EndpointID": "8b27c041c30326d59cd6e6f510d4f8d1d570a228466f956edf7815508f78e30d", 140 "Gateway": "172.17.0.1", 141 "IPAddress": "172.17.0.6", 142 "IPPrefixLen": 16, 143 "IPv6Gateway": "", 144 "GlobalIPv6Address": "", 145 "GlobalIPv6PrefixLen": 0, 146 "MacAddress": "02:42:ac:11:00:06" 147 } 148 } 149 } 150 }, 151 { 152 "Id": "4cb07b47f9fb", 153 "Names":["/running_cat"], 154 "Image": "ubuntu:latest", 155 "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82", 156 "Command": "echo 444444444444444444444444444444444", 157 "Created": 1367854152, 158 "Status": "Exit 0", 159 "Ports": [], 160 "Labels": {}, 161 "SizeRw": 12288, 162 "SizeRootFs": 0, 163 "HostConfig": { 164 "NetworkMode": "default" 165 }, 166 "NetworkSettings": { 167 "Networks": { 168 "bridge": { 169 "IPAMConfig": null, 170 "Links": null, 171 "Aliases": null, 172 "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812", 173 "EndpointID": "d91c7b2f0644403d7ef3095985ea0e2370325cd2332ff3a3225c4247328e66e9", 174 "Gateway": "172.17.0.1", 175 "IPAddress": "172.17.0.5", 176 "IPPrefixLen": 16, 177 "IPv6Gateway": "", 178 "GlobalIPv6Address": "", 179 "GlobalIPv6PrefixLen": 0, 180 "MacAddress": "02:42:ac:11:00:05" 181 } 182 } 183 } 184 } 185 ] 186 187 **Query parameters**: 188 189 - **all** – 1/True/true or 0/False/false, Show all containers. 190 Only running containers are shown by default (i.e., this defaults to false) 191 - **limit** – Show `limit` last created 192 containers, include non-running ones. 193 - **since** – Show only containers created since Id, include 194 non-running ones. 195 - **before** – Show only containers created before Id, include 196 non-running ones. 197 - **size** – 1/True/true or 0/False/false, Show the containers 198 sizes 199 - **filters** - a JSON encoded value of the filters (a `map[string][]string`) to process on the containers list. Available filters: 200 - `exited=<int>`; -- containers with exit code of `<int>` ; 201 - `status=`(`created`|`restarting`|`running`|`paused`|`exited`|`dead`) 202 - `label=key` or `label="key=value"` of a container label 203 - `isolation=`(`default`|`process`|`hyperv`) (Windows daemon only) 204 205 **Status codes**: 206 207 - **200** – no error 208 - **400** – bad parameter 209 - **500** – server error 210 211 ### Create a container 212 213 `POST /containers/create` 214 215 Create a container 216 217 **Example request**: 218 219 POST /containers/create HTTP/1.1 220 Content-Type: application/json 221 222 { 223 "Hostname": "", 224 "Domainname": "", 225 "User": "", 226 "AttachStdin": false, 227 "AttachStdout": true, 228 "AttachStderr": true, 229 "Tty": false, 230 "OpenStdin": false, 231 "StdinOnce": false, 232 "Env": [ 233 "FOO=bar", 234 "BAZ=quux" 235 ], 236 "Cmd": [ 237 "date" 238 ], 239 "Entrypoint": null, 240 "Image": "ubuntu", 241 "Labels": { 242 "com.example.vendor": "Acme", 243 "com.example.license": "GPL", 244 "com.example.version": "1.0" 245 }, 246 "Volumes": { 247 "/volumes/data": {} 248 }, 249 "WorkingDir": "", 250 "NetworkDisabled": false, 251 "MacAddress": "12:34:56:78:9a:bc", 252 "ExposedPorts": { 253 "22/tcp": {} 254 }, 255 "StopSignal": "SIGTERM", 256 "HostConfig": { 257 "Binds": ["/tmp:/tmp"], 258 "Links": ["redis3:redis"], 259 "Memory": 0, 260 "MemorySwap": 0, 261 "MemoryReservation": 0, 262 "KernelMemory": 0, 263 "CpuShares": 512, 264 "CpuPeriod": 100000, 265 "CpuQuota": 50000, 266 "CpusetCpus": "0,1", 267 "CpusetMems": "0,1", 268 "BlkioWeight": 300, 269 "BlkioWeightDevice": [{}], 270 "BlkioDeviceReadBps": [{}], 271 "BlkioDeviceReadIOps": [{}], 272 "BlkioDeviceWriteBps": [{}], 273 "BlkioDeviceWriteIOps": [{}], 274 "MemorySwappiness": 60, 275 "OomKillDisable": false, 276 "OomScoreAdj": 500, 277 "PidMode": "", 278 "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] }, 279 "PublishAllPorts": false, 280 "Privileged": false, 281 "ReadonlyRootfs": false, 282 "Dns": ["8.8.8.8"], 283 "DnsOptions": [""], 284 "DnsSearch": [""], 285 "ExtraHosts": null, 286 "VolumesFrom": ["parent", "other:ro"], 287 "CapAdd": ["NET_ADMIN"], 288 "CapDrop": ["MKNOD"], 289 "GroupAdd": ["newgroup"], 290 "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 }, 291 "NetworkMode": "bridge", 292 "Devices": [], 293 "Ulimits": [{}], 294 "LogConfig": { "Type": "json-file", "Config": {} }, 295 "SecurityOpt": [], 296 "CgroupParent": "", 297 "VolumeDriver": "", 298 "ShmSize": 67108864 299 }, 300 "NetworkingConfig": { 301 "EndpointsConfig": { 302 "isolated_nw" : { 303 "IPAMConfig": { 304 "IPv4Address":"172.20.30.33", 305 "IPv6Address":"2001:db8:abcd::3033" 306 }, 307 "Links":["container_1", "container_2"], 308 "Aliases":["server_x", "server_y"] 309 } 310 } 311 } 312 } 313 314 **Example response**: 315 316 HTTP/1.1 201 Created 317 Content-Type: application/json 318 319 { 320 "Id":"e90e34656806", 321 "Warnings":[] 322 } 323 324 **JSON parameters**: 325 326 - **Hostname** - A string value containing the hostname to use for the 327 container. 328 - **Domainname** - A string value containing the domain name to use 329 for the container. 330 - **User** - A string value specifying the user inside the container. 331 - **AttachStdin** - Boolean value, attaches to `stdin`. 332 - **AttachStdout** - Boolean value, attaches to `stdout`. 333 - **AttachStderr** - Boolean value, attaches to `stderr`. 334 - **Tty** - Boolean value, Attach standard streams to a `tty`, including `stdin` if it is not closed. 335 - **OpenStdin** - Boolean value, opens `stdin`, 336 - **StdinOnce** - Boolean value, close `stdin` after the 1 attached client disconnects. 337 - **Env** - A list of environment variables in the form of `["VAR=value"[,"VAR2=value2"]]` 338 - **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value"[,"key2":"value2"]}` 339 - **Cmd** - Command to run specified as a string or an array of strings. 340 - **Entrypoint** - Set the entry point for the container as a string or an array 341 of strings. 342 - **Image** - A string specifying the image name to use for the container. 343 - **Volumes** - An object mapping mount point paths (strings) inside the 344 container to empty objects. 345 - **WorkingDir** - A string specifying the working directory for commands to 346 run in. 347 - **NetworkDisabled** - Boolean value, when true disables networking for the 348 container 349 - **ExposedPorts** - An object mapping ports to an empty object in the form of: 350 `"ExposedPorts": { "<port>/<tcp|udp>: {}" }` 351 - **StopSignal** - Signal to stop a container as a string or unsigned integer. `SIGTERM` by default. 352 - **HostConfig** 353 - **Binds** – A list of volume bindings for this container. Each volume binding is a string in one of these forms: 354 + `host-src:container-dest` to bind-mount a host path into the 355 container. Both `host-src`, and `container-dest` must be an 356 _absolute_ path. 357 + `host-src:container-dest:ro` to make the bind-mount read-only 358 inside the container. Both `host-src`, and `container-dest` must be 359 an _absolute_ path. 360 + `volume-name:container-dest` to bind-mount a volume managed by a 361 volume driver into the container. `container-dest` must be an 362 _absolute_ path. 363 + `volume-name:container-dest:ro` to mount the volume read-only 364 inside the container. `container-dest` must be an _absolute_ path. 365 - **Links** - A list of links for the container. Each link entry should be 366 in the form of `container_name:alias`. 367 - **Memory** - Memory limit in bytes. 368 - **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap. 369 You must use this with `memory` and make the swap value larger than `memory`. 370 - **MemoryReservation** - Memory soft limit in bytes. 371 - **KernelMemory** - Kernel memory limit in bytes. 372 - **CpuShares** - An integer value containing the container's CPU Shares 373 (ie. the relative weight vs other containers). 374 - **CpuPeriod** - The length of a CPU period in microseconds. 375 - **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period. 376 - **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use. 377 - **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. 378 - **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000. 379 - **BlkioWeightDevice** - Block IO weight (relative device weight) in the form of: `"BlkioWeightDevice": [{"Path": "device_path", "Weight": weight}]` 380 - **BlkioDeviceReadBps** - Limit read rate (bytes per second) from a device in the form of: `"BlkioDeviceReadBps": [{"Path": "device_path", "Rate": rate}]`, for example: 381 `"BlkioDeviceReadBps": [{"Path": "/dev/sda", "Rate": "1024"}]"` 382 - **BlkioDeviceWriteBps** - Limit write rate (bytes per second) to a device in the form of: `"BlkioDeviceWriteBps": [{"Path": "device_path", "Rate": rate}]`, for example: 383 `"BlkioDeviceWriteBps": [{"Path": "/dev/sda", "Rate": "1024"}]"` 384 - **BlkioDeviceReadIOps** - Limit read rate (IO per second) from a device in the form of: `"BlkioDeviceReadIOps": [{"Path": "device_path", "Rate": rate}]`, for example: 385 `"BlkioDeviceReadIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` 386 - **BlkioDeviceWiiteIOps** - Limit write rate (IO per second) to a device in the form of: `"BlkioDeviceWriteIOps": [{"Path": "device_path", "Rate": rate}]`, for example: 387 `"BlkioDeviceWriteIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` 388 - **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. 389 - **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. 390 - **OomScoreAdj** - An integer value containing the score given to the container in order to tune OOM killer preferences. 391 - **PidMode** - Set the PID (Process) Namespace mode for the container; 392 `"container:<name|id>"`: joins another container's PID namespace 393 `"host"`: use the host's PID namespace inside the container 394 - **PortBindings** - A map of exposed container ports and the host port they 395 should map to. A JSON object in the form 396 `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }` 397 Take note that `port` is specified as a string and not an integer value. 398 - **PublishAllPorts** - Allocates a random host port for all of a container's 399 exposed ports. Specified as a boolean value. 400 - **Privileged** - Gives the container full access to the host. Specified as 401 a boolean value. 402 - **ReadonlyRootfs** - Mount the container's root filesystem as read only. 403 Specified as a boolean value. 404 - **Dns** - A list of DNS servers for the container to use. 405 - **DnsOptions** - A list of DNS options 406 - **DnsSearch** - A list of DNS search domains 407 - **ExtraHosts** - A list of hostnames/IP mappings to add to the 408 container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`. 409 - **VolumesFrom** - A list of volumes to inherit from another container. 410 Specified in the form `<container name>[:<ro|rw>]` 411 - **CapAdd** - A list of kernel capabilities to add to the container. 412 - **Capdrop** - A list of kernel capabilities to drop from the container. 413 - **GroupAdd** - A list of additional groups that the container process will run as 414 - **RestartPolicy** – The behavior to apply when the container exits. The 415 value is an object with a `Name` property of either `"always"` to 416 always restart, `"unless-stopped"` to restart always except when 417 user has manually stopped the container or `"on-failure"` to restart only when the container 418 exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` 419 controls the number of times to retry before giving up. 420 The default is not to restart. (optional) 421 An ever increasing delay (double the previous delay, starting at 100mS) 422 is added before each restart to prevent flooding the server. 423 - **NetworkMode** - Sets the networking mode for the container. Supported 424 standard values are: `bridge`, `host`, `none`, and `container:<name|id>`. Any other value is taken 425 as a custom network's name to which this container should connect to. 426 - **Devices** - A list of devices to add to the container specified as a JSON object in the 427 form 428 `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}` 429 - **Ulimits** - A list of ulimits to set in the container, specified as 430 `{ "Name": <name>, "Soft": <soft limit>, "Hard": <hard limit> }`, for example: 431 `Ulimits: { "Name": "nofile", "Soft": 1024, "Hard": 2048 }` 432 - **SecurityOpt**: A list of string values to customize labels for MLS 433 systems, such as SELinux. 434 - **LogConfig** - Log configuration for the container, specified as a JSON object in the form 435 `{ "Type": "<driver_name>", "Config": {"key1": "val1"}}`. 436 Available types: `json-file`, `syslog`, `journald`, `gelf`, `awslogs`, `splunk`, `none`. 437 `json-file` logging driver. 438 - **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. 439 - **VolumeDriver** - Driver that this container users to mount volumes. 440 - **ShmSize** - Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB. 441 442 **Query parameters**: 443 444 - **name** – Assign the specified name to the container. Must 445 match `/?[a-zA-Z0-9_-]+`. 446 447 **Status codes**: 448 449 - **201** – no error 450 - **400** – bad parameter 451 - **404** – no such container 452 - **406** – impossible to attach (container not running) 453 - **409** – conflict 454 - **500** – server error 455 456 ### Inspect a container 457 458 `GET /containers/(id or name)/json` 459 460 Return low-level information on the container `id` 461 462 **Example request**: 463 464 GET /containers/4fa6e0f0c678/json HTTP/1.1 465 466 **Example response**: 467 468 HTTP/1.1 200 OK 469 Content-Type: application/json 470 471 { 472 "AppArmorProfile": "", 473 "Args": [ 474 "-c", 475 "exit 9" 476 ], 477 "Config": { 478 "AttachStderr": true, 479 "AttachStdin": false, 480 "AttachStdout": true, 481 "Cmd": [ 482 "/bin/sh", 483 "-c", 484 "exit 9" 485 ], 486 "Domainname": "", 487 "Entrypoint": null, 488 "Env": [ 489 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 490 ], 491 "ExposedPorts": null, 492 "Hostname": "ba033ac44011", 493 "Image": "ubuntu", 494 "Labels": { 495 "com.example.vendor": "Acme", 496 "com.example.license": "GPL", 497 "com.example.version": "1.0" 498 }, 499 "MacAddress": "", 500 "NetworkDisabled": false, 501 "OnBuild": null, 502 "OpenStdin": false, 503 "StdinOnce": false, 504 "Tty": false, 505 "User": "", 506 "Volumes": { 507 "/volumes/data": {} 508 }, 509 "WorkingDir": "", 510 "StopSignal": "SIGTERM" 511 }, 512 "Created": "2015-01-06T15:47:31.485331387Z", 513 "Driver": "devicemapper", 514 "ExecIDs": null, 515 "HostConfig": { 516 "Binds": null, 517 "BlkioWeight": 0, 518 "BlkioWeightDevice": [{}], 519 "BlkioDeviceReadBps": [{}], 520 "BlkioDeviceWriteBps": [{}], 521 "BlkioDeviceReadIOps": [{}], 522 "BlkioDeviceWriteIOps": [{}], 523 "CapAdd": null, 524 "CapDrop": null, 525 "ContainerIDFile": "", 526 "CpusetCpus": "", 527 "CpusetMems": "", 528 "CpuShares": 0, 529 "CpuPeriod": 100000, 530 "Devices": [], 531 "Dns": null, 532 "DnsOptions": null, 533 "DnsSearch": null, 534 "ExtraHosts": null, 535 "IpcMode": "", 536 "Links": null, 537 "LxcConf": [], 538 "Memory": 0, 539 "MemorySwap": 0, 540 "MemoryReservation": 0, 541 "KernelMemory": 0, 542 "OomKillDisable": false, 543 "OomScoreAdj": 500, 544 "NetworkMode": "bridge", 545 "PidMode": "", 546 "PortBindings": {}, 547 "Privileged": false, 548 "ReadonlyRootfs": false, 549 "PublishAllPorts": false, 550 "RestartPolicy": { 551 "MaximumRetryCount": 2, 552 "Name": "on-failure" 553 }, 554 "LogConfig": { 555 "Config": null, 556 "Type": "json-file" 557 }, 558 "SecurityOpt": null, 559 "VolumesFrom": null, 560 "Ulimits": [{}], 561 "VolumeDriver": "", 562 "ShmSize": 67108864 563 }, 564 "HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname", 565 "HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts", 566 "LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log", 567 "Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39", 568 "Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2", 569 "MountLabel": "", 570 "Name": "/boring_euclid", 571 "NetworkSettings": { 572 "Bridge": "", 573 "SandboxID": "", 574 "HairpinMode": false, 575 "LinkLocalIPv6Address": "", 576 "LinkLocalIPv6PrefixLen": 0, 577 "Ports": null, 578 "SandboxKey": "", 579 "SecondaryIPAddresses": null, 580 "SecondaryIPv6Addresses": null, 581 "EndpointID": "", 582 "Gateway": "", 583 "GlobalIPv6Address": "", 584 "GlobalIPv6PrefixLen": 0, 585 "IPAddress": "", 586 "IPPrefixLen": 0, 587 "IPv6Gateway": "", 588 "MacAddress": "", 589 "Networks": { 590 "bridge": { 591 "NetworkID": "7ea29fc1412292a2d7bba362f9253545fecdfa8ce9a6e37dd10ba8bee7129812", 592 "EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d", 593 "Gateway": "172.17.0.1", 594 "IPAddress": "172.17.0.2", 595 "IPPrefixLen": 16, 596 "IPv6Gateway": "", 597 "GlobalIPv6Address": "", 598 "GlobalIPv6PrefixLen": 0, 599 "MacAddress": "02:42:ac:12:00:02" 600 } 601 } 602 }, 603 "Path": "/bin/sh", 604 "ProcessLabel": "", 605 "ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf", 606 "RestartCount": 1, 607 "State": { 608 "Error": "", 609 "ExitCode": 9, 610 "FinishedAt": "2015-01-06T15:47:32.080254511Z", 611 "OOMKilled": false, 612 "Dead": false, 613 "Paused": false, 614 "Pid": 0, 615 "Restarting": false, 616 "Running": true, 617 "StartedAt": "2015-01-06T15:47:32.072697474Z", 618 "Status": "running" 619 }, 620 "Mounts": [ 621 { 622 "Name": "fac362...80535", 623 "Source": "/data", 624 "Destination": "/data", 625 "Driver": "local", 626 "Mode": "ro,Z", 627 "RW": false, 628 "Propagation": "" 629 } 630 ] 631 } 632 633 **Example request, with size information**: 634 635 GET /containers/4fa6e0f0c678/json?size=1 HTTP/1.1 636 637 **Example response, with size information**: 638 639 HTTP/1.1 200 OK 640 Content-Type: application/json 641 642 { 643 .... 644 "SizeRw": 0, 645 "SizeRootFs": 972, 646 .... 647 } 648 649 **Query parameters**: 650 651 - **size** – 1/True/true or 0/False/false, return container size information. Default is `false`. 652 653 **Status codes**: 654 655 - **200** – no error 656 - **404** – no such container 657 - **500** – server error 658 659 ### List processes running inside a container 660 661 `GET /containers/(id or name)/top` 662 663 List processes running inside the container `id`. On Unix systems this 664 is done by running the `ps` command. This endpoint is not 665 supported on Windows. 666 667 **Example request**: 668 669 GET /containers/4fa6e0f0c678/top HTTP/1.1 670 671 **Example response**: 672 673 HTTP/1.1 200 OK 674 Content-Type: application/json 675 676 { 677 "Titles" : [ 678 "UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD" 679 ], 680 "Processes" : [ 681 [ 682 "root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash" 683 ], 684 [ 685 "root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10" 686 ] 687 ] 688 } 689 690 **Example request**: 691 692 GET /containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1 693 694 **Example response**: 695 696 HTTP/1.1 200 OK 697 Content-Type: application/json 698 699 { 700 "Titles" : [ 701 "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND" 702 ] 703 "Processes" : [ 704 [ 705 "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash" 706 ], 707 [ 708 "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10" 709 ] 710 ], 711 } 712 713 **Query parameters**: 714 715 - **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef` 716 717 **Status codes**: 718 719 - **200** – no error 720 - **404** – no such container 721 - **500** – server error 722 723 ### Get container logs 724 725 `GET /containers/(id or name)/logs` 726 727 Get `stdout` and `stderr` logs from the container ``id`` 728 729 > **Note**: 730 > This endpoint works only for containers with the `json-file` or `journald` logging drivers. 731 732 **Example request**: 733 734 GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10&since=1428990821 HTTP/1.1 735 736 **Example response**: 737 738 HTTP/1.1 101 UPGRADED 739 Content-Type: application/vnd.docker.raw-stream 740 Connection: Upgrade 741 Upgrade: tcp 742 743 {{ STREAM }} 744 745 **Query parameters**: 746 747 - **follow** – 1/True/true or 0/False/false, return stream. Default `false`. 748 - **stdout** – 1/True/true or 0/False/false, show `stdout` log. Default `false`. 749 - **stderr** – 1/True/true or 0/False/false, show `stderr` log. Default `false`. 750 - **since** – UNIX timestamp (integer) to filter logs. Specifying a timestamp 751 will only output log-entries since that timestamp. Default: 0 (unfiltered) 752 - **timestamps** – 1/True/true or 0/False/false, print timestamps for 753 every log line. Default `false`. 754 - **tail** – Output specified number of lines at the end of logs: `all` or `<number>`. Default all. 755 756 **Status codes**: 757 758 - **101** – no error, hints proxy about hijacking 759 - **200** – no error, no upgrade header found 760 - **404** – no such container 761 - **500** – server error 762 763 ### Inspect changes on a container's filesystem 764 765 `GET /containers/(id or name)/changes` 766 767 Inspect changes on container `id`'s filesystem 768 769 **Example request**: 770 771 GET /containers/4fa6e0f0c678/changes HTTP/1.1 772 773 **Example response**: 774 775 HTTP/1.1 200 OK 776 Content-Type: application/json 777 778 [ 779 { 780 "Path": "/dev", 781 "Kind": 0 782 }, 783 { 784 "Path": "/dev/kmsg", 785 "Kind": 1 786 }, 787 { 788 "Path": "/test", 789 "Kind": 1 790 } 791 ] 792 793 Values for `Kind`: 794 795 - `0`: Modify 796 - `1`: Add 797 - `2`: Delete 798 799 **Status codes**: 800 801 - **200** – no error 802 - **404** – no such container 803 - **500** – server error 804 805 ### Export a container 806 807 `GET /containers/(id or name)/export` 808 809 Export the contents of container `id` 810 811 **Example request**: 812 813 GET /containers/4fa6e0f0c678/export HTTP/1.1 814 815 **Example response**: 816 817 HTTP/1.1 200 OK 818 Content-Type: application/octet-stream 819 820 {{ TAR STREAM }} 821 822 **Status codes**: 823 824 - **200** – no error 825 - **404** – no such container 826 - **500** – server error 827 828 ### Get container stats based on resource usage 829 830 `GET /containers/(id or name)/stats` 831 832 This endpoint returns a live stream of a container's resource usage statistics. 833 834 **Example request**: 835 836 GET /containers/redis1/stats HTTP/1.1 837 838 **Example response**: 839 840 HTTP/1.1 200 OK 841 Content-Type: application/json 842 843 { 844 "read" : "2015-01-08T22:57:31.547920715Z", 845 "networks": { 846 "eth0": { 847 "rx_bytes": 5338, 848 "rx_dropped": 0, 849 "rx_errors": 0, 850 "rx_packets": 36, 851 "tx_bytes": 648, 852 "tx_dropped": 0, 853 "tx_errors": 0, 854 "tx_packets": 8 855 }, 856 "eth5": { 857 "rx_bytes": 4641, 858 "rx_dropped": 0, 859 "rx_errors": 0, 860 "rx_packets": 26, 861 "tx_bytes": 690, 862 "tx_dropped": 0, 863 "tx_errors": 0, 864 "tx_packets": 9 865 } 866 }, 867 "memory_stats" : { 868 "stats" : { 869 "total_pgmajfault" : 0, 870 "cache" : 0, 871 "mapped_file" : 0, 872 "total_inactive_file" : 0, 873 "pgpgout" : 414, 874 "rss" : 6537216, 875 "total_mapped_file" : 0, 876 "writeback" : 0, 877 "unevictable" : 0, 878 "pgpgin" : 477, 879 "total_unevictable" : 0, 880 "pgmajfault" : 0, 881 "total_rss" : 6537216, 882 "total_rss_huge" : 6291456, 883 "total_writeback" : 0, 884 "total_inactive_anon" : 0, 885 "rss_huge" : 6291456, 886 "hierarchical_memory_limit" : 67108864, 887 "total_pgfault" : 964, 888 "total_active_file" : 0, 889 "active_anon" : 6537216, 890 "total_active_anon" : 6537216, 891 "total_pgpgout" : 414, 892 "total_cache" : 0, 893 "inactive_anon" : 0, 894 "active_file" : 0, 895 "pgfault" : 964, 896 "inactive_file" : 0, 897 "total_pgpgin" : 477 898 }, 899 "max_usage" : 6651904, 900 "usage" : 6537216, 901 "failcnt" : 0, 902 "limit" : 67108864 903 }, 904 "blkio_stats" : {}, 905 "cpu_stats" : { 906 "cpu_usage" : { 907 "percpu_usage" : [ 908 8646879, 909 24472255, 910 36438778, 911 30657443 912 ], 913 "usage_in_usermode" : 50000000, 914 "total_usage" : 100215355, 915 "usage_in_kernelmode" : 30000000 916 }, 917 "system_cpu_usage" : 739306590000000, 918 "throttling_data" : {"periods":0,"throttled_periods":0,"throttled_time":0} 919 }, 920 "precpu_stats" : { 921 "cpu_usage" : { 922 "percpu_usage" : [ 923 8646879, 924 24350896, 925 36438778, 926 30657443 927 ], 928 "usage_in_usermode" : 50000000, 929 "total_usage" : 100093996, 930 "usage_in_kernelmode" : 30000000 931 }, 932 "system_cpu_usage" : 9492140000000, 933 "throttling_data" : {"periods":0,"throttled_periods":0,"throttled_time":0} 934 } 935 } 936 937 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. 938 939 **Query parameters**: 940 941 - **stream** – 1/True/true or 0/False/false, pull stats once then disconnect. Default `true`. 942 943 **Status codes**: 944 945 - **200** – no error 946 - **404** – no such container 947 - **500** – server error 948 949 ### Resize a container TTY 950 951 `POST /containers/(id or name)/resize` 952 953 Resize the TTY for container with `id`. The unit is number of characters. You must restart the container for the resize to take effect. 954 955 **Example request**: 956 957 POST /containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1 958 959 **Example response**: 960 961 HTTP/1.1 200 OK 962 Content-Length: 0 963 Content-Type: text/plain; charset=utf-8 964 965 **Query parameters**: 966 967 - **h** – height of `tty` session 968 - **w** – width 969 970 **Status codes**: 971 972 - **200** – no error 973 - **404** – No such container 974 - **500** – Cannot resize container 975 976 ### Start a container 977 978 `POST /containers/(id or name)/start` 979 980 Start the container `id` 981 982 > **Note**: 983 > For backwards compatibility, this endpoint accepts a `HostConfig` as JSON-encoded request body. 984 > See [create a container](#create-a-container) for details. 985 986 **Example request**: 987 988 POST /containers/e90e34656806/start HTTP/1.1 989 990 **Example response**: 991 992 HTTP/1.1 204 No Content 993 994 **Query parameters**: 995 996 - **detachKeys** – Override the key sequence for detaching a 997 container. Format is a single character `[a-Z]` or `ctrl-<value>` 998 where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. 999 1000 **Status codes**: 1001 1002 - **204** – no error 1003 - **304** – container already started 1004 - **404** – no such container 1005 - **500** – server error 1006 1007 ### Stop a container 1008 1009 `POST /containers/(id or name)/stop` 1010 1011 Stop the container `id` 1012 1013 **Example request**: 1014 1015 POST /containers/e90e34656806/stop?t=5 HTTP/1.1 1016 1017 **Example response**: 1018 1019 HTTP/1.1 204 No Content 1020 1021 **Query parameters**: 1022 1023 - **t** – number of seconds to wait before killing the container 1024 1025 **Status codes**: 1026 1027 - **204** – no error 1028 - **304** – container already stopped 1029 - **404** – no such container 1030 - **500** – server error 1031 1032 ### Restart a container 1033 1034 `POST /containers/(id or name)/restart` 1035 1036 Restart the container `id` 1037 1038 **Example request**: 1039 1040 POST /containers/e90e34656806/restart?t=5 HTTP/1.1 1041 1042 **Example response**: 1043 1044 HTTP/1.1 204 No Content 1045 1046 **Query parameters**: 1047 1048 - **t** – number of seconds to wait before killing the container 1049 1050 **Status codes**: 1051 1052 - **204** – no error 1053 - **404** – no such container 1054 - **500** – server error 1055 1056 ### Kill a container 1057 1058 `POST /containers/(id or name)/kill` 1059 1060 Kill the container `id` 1061 1062 **Example request**: 1063 1064 POST /containers/e90e34656806/kill HTTP/1.1 1065 1066 **Example response**: 1067 1068 HTTP/1.1 204 No Content 1069 1070 **Query parameters**: 1071 1072 - **signal** - Signal to send to the container: integer or string like `SIGINT`. 1073 When not set, `SIGKILL` is assumed and the call waits for the container to exit. 1074 1075 **Status codes**: 1076 1077 - **204** – no error 1078 - **404** – no such container 1079 - **500** – server error 1080 1081 ### Update a container 1082 1083 `POST /containers/(id or name)/update` 1084 1085 Update resource configs of one or more containers. 1086 1087 **Example request**: 1088 1089 POST /containers/e90e34656806/update HTTP/1.1 1090 Content-Type: application/json 1091 1092 { 1093 "BlkioWeight": 300, 1094 "CpuShares": 512, 1095 "CpuPeriod": 100000, 1096 "CpuQuota": 50000, 1097 "CpusetCpus": "0,1", 1098 "CpusetMems": "0", 1099 "Memory": 314572800, 1100 "MemorySwap": 514288000, 1101 "MemoryReservation": 209715200, 1102 "KernelMemory": 52428800, 1103 } 1104 1105 **Example response**: 1106 1107 HTTP/1.1 200 OK 1108 Content-Type: application/json 1109 1110 { 1111 "Warnings": [] 1112 } 1113 1114 **Status codes**: 1115 1116 - **200** – no error 1117 - **400** – bad parameter 1118 - **404** – no such container 1119 - **500** – server error 1120 1121 ### Rename a container 1122 1123 `POST /containers/(id or name)/rename` 1124 1125 Rename the container `id` to a `new_name` 1126 1127 **Example request**: 1128 1129 POST /containers/e90e34656806/rename?name=new_name HTTP/1.1 1130 1131 **Example response**: 1132 1133 HTTP/1.1 204 No Content 1134 1135 **Query parameters**: 1136 1137 - **name** – new name for the container 1138 1139 **Status codes**: 1140 1141 - **204** – no error 1142 - **404** – no such container 1143 - **409** - conflict name already assigned 1144 - **500** – server error 1145 1146 ### Pause a container 1147 1148 `POST /containers/(id or name)/pause` 1149 1150 Pause the container `id` 1151 1152 **Example request**: 1153 1154 POST /containers/e90e34656806/pause HTTP/1.1 1155 1156 **Example response**: 1157 1158 HTTP/1.1 204 No Content 1159 1160 **Status codes**: 1161 1162 - **204** – no error 1163 - **404** – no such container 1164 - **500** – server error 1165 1166 ### Unpause a container 1167 1168 `POST /containers/(id or name)/unpause` 1169 1170 Unpause the container `id` 1171 1172 **Example request**: 1173 1174 POST /containers/e90e34656806/unpause HTTP/1.1 1175 1176 **Example response**: 1177 1178 HTTP/1.1 204 No Content 1179 1180 **Status codes**: 1181 1182 - **204** – no error 1183 - **404** – no such container 1184 - **500** – server error 1185 1186 ### Attach to a container 1187 1188 `POST /containers/(id or name)/attach` 1189 1190 Attach to the container `id` 1191 1192 **Example request**: 1193 1194 POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 1195 1196 **Example response**: 1197 1198 HTTP/1.1 101 UPGRADED 1199 Content-Type: application/vnd.docker.raw-stream 1200 Connection: Upgrade 1201 Upgrade: tcp 1202 1203 {{ STREAM }} 1204 1205 **Query parameters**: 1206 1207 - **detachKeys** – Override the key sequence for detaching a 1208 container. Format is a single character `[a-Z]` or `ctrl-<value>` 1209 where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. 1210 - **logs** – 1/True/true or 0/False/false, return logs. Default `false`. 1211 - **stream** – 1/True/true or 0/False/false, return stream. 1212 Default `false`. 1213 - **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach 1214 to `stdin`. Default `false`. 1215 - **stdout** – 1/True/true or 0/False/false, if `logs=true`, return 1216 `stdout` log, if `stream=true`, attach to `stdout`. Default `false`. 1217 - **stderr** – 1/True/true or 0/False/false, if `logs=true`, return 1218 `stderr` log, if `stream=true`, attach to `stderr`. Default `false`. 1219 1220 **Status codes**: 1221 1222 - **101** – no error, hints proxy about hijacking 1223 - **200** – no error, no upgrade header found 1224 - **400** – bad parameter 1225 - **404** – no such container 1226 - **409** - container is paused 1227 - **500** – server error 1228 1229 **Stream details**: 1230 1231 When using the TTY setting is enabled in 1232 [`POST /containers/create` 1233 ](#create-a-container), 1234 the stream is the raw data from the process PTY and client's `stdin`. 1235 When the TTY is disabled, then the stream is multiplexed to separate 1236 `stdout` and `stderr`. 1237 1238 The format is a **Header** and a **Payload** (frame). 1239 1240 **HEADER** 1241 1242 The header contains the information which the stream writes (`stdout` or 1243 `stderr`). It also contains the size of the associated frame encoded in the 1244 last four bytes (`uint32`). 1245 1246 It is encoded on the first eight bytes like this: 1247 1248 header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} 1249 1250 `STREAM_TYPE` can be: 1251 1252 - 0: `stdin` (is written on `stdout`) 1253 - 1: `stdout` 1254 - 2: `stderr` 1255 1256 `SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of 1257 the `uint32` size encoded as big endian. 1258 1259 **PAYLOAD** 1260 1261 The payload is the raw stream. 1262 1263 **IMPLEMENTATION** 1264 1265 The simplest way to implement the Attach protocol is the following: 1266 1267 1. Read eight bytes. 1268 2. Choose `stdout` or `stderr` depending on the first byte. 1269 3. Extract the frame size from the last four bytes. 1270 4. Read the extracted size and output it on the correct output. 1271 5. Goto 1. 1272 1273 ### Attach to a container (websocket) 1274 1275 `GET /containers/(id or name)/attach/ws` 1276 1277 Attach to the container `id` via websocket 1278 1279 Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) 1280 1281 **Example request** 1282 1283 GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 1284 1285 **Example response** 1286 1287 {{ STREAM }} 1288 1289 **Query parameters**: 1290 1291 - **detachKeys** – Override the key sequence for detaching a 1292 container. Format is a single character `[a-Z]` or `ctrl-<value>` 1293 where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. 1294 - **logs** – 1/True/true or 0/False/false, return logs. Default `false`. 1295 - **stream** – 1/True/true or 0/False/false, return stream. 1296 Default `false`. 1297 - **stdin** – 1/True/true or 0/False/false, if `stream=true`, attach 1298 to `stdin`. Default `false`. 1299 - **stdout** – 1/True/true or 0/False/false, if `logs=true`, return 1300 `stdout` log, if `stream=true`, attach to `stdout`. Default `false`. 1301 - **stderr** – 1/True/true or 0/False/false, if `logs=true`, return 1302 `stderr` log, if `stream=true`, attach to `stderr`. Default `false`. 1303 1304 **Status codes**: 1305 1306 - **200** – no error 1307 - **400** – bad parameter 1308 - **404** – no such container 1309 - **500** – server error 1310 1311 ### Wait a container 1312 1313 `POST /containers/(id or name)/wait` 1314 1315 Block until container `id` stops, then returns the exit code 1316 1317 **Example request**: 1318 1319 POST /containers/16253994b7c4/wait HTTP/1.1 1320 1321 **Example response**: 1322 1323 HTTP/1.1 200 OK 1324 Content-Type: application/json 1325 1326 {"StatusCode": 0} 1327 1328 **Status codes**: 1329 1330 - **200** – no error 1331 - **404** – no such container 1332 - **500** – server error 1333 1334 ### Remove a container 1335 1336 `DELETE /containers/(id or name)` 1337 1338 Remove the container `id` from the filesystem 1339 1340 **Example request**: 1341 1342 DELETE /containers/16253994b7c4?v=1 HTTP/1.1 1343 1344 **Example response**: 1345 1346 HTTP/1.1 204 No Content 1347 1348 **Query parameters**: 1349 1350 - **v** – 1/True/true or 0/False/false, Remove the volumes 1351 associated to the container. Default `false`. 1352 - **force** - 1/True/true or 0/False/false, Kill then remove the container. 1353 Default `false`. 1354 1355 **Status codes**: 1356 1357 - **204** – no error 1358 - **400** – bad parameter 1359 - **404** – no such container 1360 - **409** – conflict 1361 - **500** – server error 1362 1363 ### Copy files or folders from a container 1364 1365 `POST /containers/(id or name)/copy` 1366 1367 Copy files or folders of container `id` 1368 1369 **Deprecated** in favor of the `archive` endpoint below. 1370 1371 **Example request**: 1372 1373 POST /containers/4fa6e0f0c678/copy HTTP/1.1 1374 Content-Type: application/json 1375 1376 { 1377 "Resource": "test.txt" 1378 } 1379 1380 **Example response**: 1381 1382 HTTP/1.1 200 OK 1383 Content-Type: application/x-tar 1384 1385 {{ TAR STREAM }} 1386 1387 **Status codes**: 1388 1389 - **200** – no error 1390 - **404** – no such container 1391 - **500** – server error 1392 1393 ### Retrieving information about files and folders in a container 1394 1395 `HEAD /containers/(id or name)/archive` 1396 1397 See the description of the `X-Docker-Container-Path-Stat` header in the 1398 following section. 1399 1400 ### Get an archive of a filesystem resource in a container 1401 1402 `GET /containers/(id or name)/archive` 1403 1404 Get a tar archive of a resource in the filesystem of container `id`. 1405 1406 **Query parameters**: 1407 1408 - **path** - resource in the container's filesystem to archive. Required. 1409 1410 If not an absolute path, it is relative to the container's root directory. 1411 The resource specified by **path** must exist. To assert that the resource 1412 is expected to be a directory, **path** should end in `/` or `/.` 1413 (assuming a path separator of `/`). If **path** ends in `/.` then this 1414 indicates that only the contents of the **path** directory should be 1415 copied. A symlink is always resolved to its target. 1416 1417 > **Note**: It is not possible to copy certain system files such as resources 1418 > under `/proc`, `/sys`, `/dev`, and mounts created by the user in the 1419 > container. 1420 1421 **Example request**: 1422 1423 GET /containers/8cce319429b2/archive?path=/root HTTP/1.1 1424 1425 **Example response**: 1426 1427 HTTP/1.1 200 OK 1428 Content-Type: application/x-tar 1429 X-Docker-Container-Path-Stat: eyJuYW1lIjoicm9vdCIsInNpemUiOjQwOTYsIm1vZGUiOjIxNDc0ODQwOTYsIm10aW1lIjoiMjAxNC0wMi0yN1QyMDo1MToyM1oiLCJsaW5rVGFyZ2V0IjoiIn0= 1430 1431 {{ TAR STREAM }} 1432 1433 On success, a response header `X-Docker-Container-Path-Stat` will be set to a 1434 base64-encoded JSON object containing some filesystem header information about 1435 the archived resource. The above example value would decode to the following 1436 JSON object (whitespace added for readability): 1437 1438 ```json 1439 { 1440 "name": "root", 1441 "size": 4096, 1442 "mode": 2147484096, 1443 "mtime": "2014-02-27T20:51:23Z", 1444 "linkTarget": "" 1445 } 1446 ``` 1447 1448 A `HEAD` request can also be made to this endpoint if only this information is 1449 desired. 1450 1451 **Status codes**: 1452 1453 - **200** - success, returns archive of copied resource 1454 - **400** - client error, bad parameter, details in JSON response body, one of: 1455 - must specify path parameter (**path** cannot be empty) 1456 - not a directory (**path** was asserted to be a directory but exists as a 1457 file) 1458 - **404** - client error, resource not found, one of: 1459 – no such container (container `id` does not exist) 1460 - no such file or directory (**path** does not exist) 1461 - **500** - server error 1462 1463 ### Extract an archive of files or folders to a directory in a container 1464 1465 `PUT /containers/(id or name)/archive` 1466 1467 Upload a tar archive to be extracted to a path in the filesystem of container 1468 `id`. 1469 1470 **Query parameters**: 1471 1472 - **path** - path to a directory in the container 1473 to extract the archive's contents into. Required. 1474 1475 If not an absolute path, it is relative to the container's root directory. 1476 The **path** resource must exist. 1477 - **noOverwriteDirNonDir** - If "1", "true", or "True" then it will be an error 1478 if unpacking the given content would cause an existing directory to be 1479 replaced with a non-directory and vice versa. 1480 1481 **Example request**: 1482 1483 PUT /containers/8cce319429b2/archive?path=/vol1 HTTP/1.1 1484 Content-Type: application/x-tar 1485 1486 {{ TAR STREAM }} 1487 1488 **Example response**: 1489 1490 HTTP/1.1 200 OK 1491 1492 **Status codes**: 1493 1494 - **200** – the content was extracted successfully 1495 - **400** - client error, bad parameter, details in JSON response body, one of: 1496 - must specify path parameter (**path** cannot be empty) 1497 - not a directory (**path** should be a directory but exists as a file) 1498 - unable to overwrite existing directory with non-directory 1499 (if **noOverwriteDirNonDir**) 1500 - unable to overwrite existing non-directory with directory 1501 (if **noOverwriteDirNonDir**) 1502 - **403** - client error, permission denied, the volume 1503 or container rootfs is marked as read-only. 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** resource does not exist) 1507 - **500** – server error 1508 1509 ## 2.2 Images 1510 1511 ### List Images 1512 1513 `GET /images/json` 1514 1515 **Example request**: 1516 1517 GET /images/json?all=0 HTTP/1.1 1518 1519 **Example response**: 1520 1521 HTTP/1.1 200 OK 1522 Content-Type: application/json 1523 1524 [ 1525 { 1526 "RepoTags": [ 1527 "ubuntu:12.04", 1528 "ubuntu:precise", 1529 "ubuntu:latest" 1530 ], 1531 "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", 1532 "Created": 1365714795, 1533 "Size": 131506275, 1534 "VirtualSize": 131506275, 1535 "Labels": {} 1536 }, 1537 { 1538 "RepoTags": [ 1539 "ubuntu:12.10", 1540 "ubuntu:quantal" 1541 ], 1542 "ParentId": "27cf784147099545", 1543 "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", 1544 "Created": 1364102658, 1545 "Size": 24653, 1546 "VirtualSize": 180116135, 1547 "Labels": { 1548 "com.example.version": "v1" 1549 } 1550 } 1551 ] 1552 1553 **Example request, with digest information**: 1554 1555 GET /images/json?digests=1 HTTP/1.1 1556 1557 **Example response, with digest information**: 1558 1559 HTTP/1.1 200 OK 1560 Content-Type: application/json 1561 1562 [ 1563 { 1564 "Created": 1420064636, 1565 "Id": "4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125", 1566 "ParentId": "ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2", 1567 "RepoDigests": [ 1568 "localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf" 1569 ], 1570 "RepoTags": [ 1571 "localhost:5000/test/busybox:latest", 1572 "playdate:latest" 1573 ], 1574 "Size": 0, 1575 "VirtualSize": 2429728, 1576 "Labels": {} 1577 } 1578 ] 1579 1580 The response shows a single image `Id` associated with two repositories 1581 (`RepoTags`): `localhost:5000/test/busybox`: and `playdate`. A caller can use 1582 either of the `RepoTags` values `localhost:5000/test/busybox:latest` or 1583 `playdate:latest` to reference the image. 1584 1585 You can also use `RepoDigests` values to reference an image. In this response, 1586 the array has only one reference and that is to the 1587 `localhost:5000/test/busybox` repository; the `playdate` repository has no 1588 digest. You can reference this digest using the value: 1589 `localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d...` 1590 1591 See the `docker run` and `docker build` commands for examples of digest and tag 1592 references on the command line. 1593 1594 **Query parameters**: 1595 1596 - **all** – 1/True/true or 0/False/false, default false 1597 - **filters** – a JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters: 1598 - `dangling=true` 1599 - `label=key` or `label="key=value"` of an image label 1600 - **filter** - only return images with the specified name 1601 1602 ### Build image from a Dockerfile 1603 1604 `POST /build` 1605 1606 Build an image from a Dockerfile 1607 1608 **Example request**: 1609 1610 POST /build HTTP/1.1 1611 1612 {{ TAR STREAM }} 1613 1614 **Example response**: 1615 1616 HTTP/1.1 200 OK 1617 Content-Type: application/json 1618 1619 {"stream": "Step 1..."} 1620 {"stream": "..."} 1621 {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} 1622 1623 The input stream must be a `tar` archive compressed with one of the 1624 following algorithms: `identity` (no compression), `gzip`, `bzip2`, `xz`. 1625 1626 The archive must include a build instructions file, typically called 1627 `Dockerfile` at the archive's root. The `dockerfile` parameter may be 1628 used to specify a different build instructions file. To do this, its value must be 1629 the path to the alternate build instructions file to use. 1630 1631 The archive may include any number of other files, 1632 which are accessible in the build context (See the [*ADD build 1633 command*](../../reference/builder.md#add)). 1634 1635 The Docker daemon performs a preliminary validation of the `Dockerfile` before 1636 starting the build, and returns an error if the syntax is incorrect. After that, 1637 each instruction is run one-by-one until the ID of the new image is output. 1638 1639 The build is canceled if the client drops the connection by quitting 1640 or being killed. 1641 1642 **Query parameters**: 1643 1644 - **dockerfile** - Path within the build context to the `Dockerfile`. This is 1645 ignored if `remote` is specified and points to an external `Dockerfile`. 1646 - **t** – A name and optional tag to apply to the image in the `name:tag` format. 1647 If you omit the `tag` the default `latest` value is assumed. 1648 You can provide one or more `t` parameters. 1649 - **remote** – A Git repository URI or HTTP/HTTPS context URI. If the 1650 URI points to a single text file, the file's contents are placed into 1651 a file called `Dockerfile` and the image is built from that file. If 1652 the URI points to a tarball, the file is downloaded by the daemon and 1653 the contents therein used as the context for the build. If the URI 1654 points to a tarball and the `dockerfile` parameter is also specified, 1655 there must be a file with the corresponding path inside the tarball. 1656 - **q** – Suppress verbose build output. 1657 - **nocache** – Do not use the cache when building the image. 1658 - **pull** - Attempt to pull the image even if an older image exists locally. 1659 - **rm** - Remove intermediate containers after a successful build (default behavior). 1660 - **forcerm** - Always remove intermediate containers (includes `rm`). 1661 - **memory** - Set memory limit for build. 1662 - **memswap** - Total memory (memory + swap), `-1` to enable unlimited swap. 1663 - **cpushares** - CPU shares (relative weight). 1664 - **cpusetcpus** - CPUs in which to allow execution (e.g., `0-3`, `0,1`). 1665 - **cpuperiod** - The length of a CPU period in microseconds. 1666 - **cpuquota** - Microseconds of CPU time that the container can get in a CPU period. 1667 - **buildargs** – JSON map of string pairs for build-time variables. Users pass 1668 these values at build-time. Docker uses the `buildargs` as the environment 1669 context for command(s) run via the Dockerfile's `RUN` instruction or for 1670 variable expansion in other Dockerfile instructions. This is not meant for 1671 passing secret values. [Read more about the buildargs instruction](../../reference/builder.md#arg) 1672 - **shmsize** - Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB. 1673 1674 **Request Headers**: 1675 1676 - **Content-type** – Set to `"application/tar"`. 1677 - **X-Registry-Config** – A base64-url-safe-encoded Registry Auth Config JSON 1678 object with the following structure: 1679 1680 { 1681 "docker.example.com": { 1682 "username": "janedoe", 1683 "password": "hunter2" 1684 }, 1685 "https://index.docker.io/v1/": { 1686 "username": "mobydock", 1687 "password": "conta1n3rize14" 1688 } 1689 } 1690 1691 This object maps the hostname of a registry to an object containing the 1692 "username" and "password" for that registry. Multiple registries may 1693 be specified as the build may be based on an image requiring 1694 authentication to pull from any arbitrary registry. Only the registry 1695 domain name (and port if not the default "443") are required. However 1696 (for legacy reasons) the "official" Docker, Inc. hosted registry must 1697 be specified with both a "https://" prefix and a "/v1/" suffix even 1698 though Docker will prefer to use the v2 registry API. 1699 1700 **Status codes**: 1701 1702 - **200** – no error 1703 - **500** – server error 1704 1705 ### Create an image 1706 1707 `POST /images/create` 1708 1709 Create an image either by pulling it from the registry or by importing it 1710 1711 **Example request**: 1712 1713 POST /images/create?fromImage=busybox&tag=latest HTTP/1.1 1714 1715 **Example response**: 1716 1717 HTTP/1.1 200 OK 1718 Content-Type: application/json 1719 1720 {"status": "Pulling..."} 1721 {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} 1722 {"error": "Invalid..."} 1723 ... 1724 1725 When using this endpoint to pull an image from the registry, the 1726 `X-Registry-Auth` header can be used to include 1727 a base64-encoded AuthConfig object. 1728 1729 **Query parameters**: 1730 1731 - **fromImage** – Name of the image to pull. The name may include a tag or 1732 digest. This parameter may only be used when pulling an image. 1733 The pull is cancelled if the HTTP connection is closed. 1734 - **fromSrc** – Source to import. The value may be a URL from which the image 1735 can be retrieved or `-` to read the image from the request body. 1736 This parameter may only be used when importing an image. 1737 - **repo** – Repository name given to an image when it is imported. 1738 The repo may include a tag. This parameter may only be used when importing 1739 an image. 1740 - **tag** – Tag or digest. If empty when pulling an image, this causes all tags 1741 for the given image to be pulled. 1742 1743 **Request Headers**: 1744 1745 - **X-Registry-Auth** – base64-encoded AuthConfig object, containing either login information, or a token 1746 - Credential based login: 1747 1748 ``` 1749 { 1750 "username": "jdoe", 1751 "password": "secret", 1752 "email": "jdoe@acme.com" 1753 } 1754 ``` 1755 1756 - Token based login: 1757 1758 ``` 1759 { 1760 "registrytoken": "9cbaf023786cd7..." 1761 } 1762 ``` 1763 1764 **Status codes**: 1765 1766 - **200** – no error 1767 - **500** – server error 1768 1769 1770 1771 ### Inspect an image 1772 1773 `GET /images/(name)/json` 1774 1775 Return low-level information on the image `name` 1776 1777 **Example request**: 1778 1779 GET /images/example/json HTTP/1.1 1780 1781 **Example response**: 1782 1783 HTTP/1.1 200 OK 1784 Content-Type: application/json 1785 1786 { 1787 "Id" : "85f05633ddc1c50679be2b16a0479ab6f7637f8884e0cfe0f4d20e1ebb3d6e7c", 1788 "Container" : "cb91e48a60d01f1e27028b4fc6819f4f290b3cf12496c8176ec714d0d390984a", 1789 "Comment" : "", 1790 "Os" : "linux", 1791 "Architecture" : "amd64", 1792 "Parent" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1793 "ContainerConfig" : { 1794 "Tty" : false, 1795 "Hostname" : "e611e15f9c9d", 1796 "Volumes" : null, 1797 "Domainname" : "", 1798 "AttachStdout" : false, 1799 "PublishService" : "", 1800 "AttachStdin" : false, 1801 "OpenStdin" : false, 1802 "StdinOnce" : false, 1803 "NetworkDisabled" : false, 1804 "OnBuild" : [], 1805 "Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1806 "User" : "", 1807 "WorkingDir" : "", 1808 "Entrypoint" : null, 1809 "MacAddress" : "", 1810 "AttachStderr" : false, 1811 "Labels" : { 1812 "com.example.license" : "GPL", 1813 "com.example.version" : "1.0", 1814 "com.example.vendor" : "Acme" 1815 }, 1816 "Env" : [ 1817 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 1818 ], 1819 "ExposedPorts" : null, 1820 "Cmd" : [ 1821 "/bin/sh", 1822 "-c", 1823 "#(nop) LABEL com.example.vendor=Acme com.example.license=GPL com.example.version=1.0" 1824 ] 1825 }, 1826 "DockerVersion" : "1.9.0-dev", 1827 "VirtualSize" : 188359297, 1828 "Size" : 0, 1829 "Author" : "", 1830 "Created" : "2015-09-10T08:30:53.26995814Z", 1831 "GraphDriver" : { 1832 "Name" : "aufs", 1833 "Data" : null 1834 }, 1835 "RepoDigests" : [ 1836 "localhost:5000/test/busybox/example@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf" 1837 ], 1838 "RepoTags" : [ 1839 "example:1.0", 1840 "example:latest", 1841 "example:stable" 1842 ], 1843 "Config" : { 1844 "Image" : "91e54dfb11794fad694460162bf0cb0a4fa710cfa3f60979c177d920813e267c", 1845 "NetworkDisabled" : false, 1846 "OnBuild" : [], 1847 "StdinOnce" : false, 1848 "PublishService" : "", 1849 "AttachStdin" : false, 1850 "OpenStdin" : false, 1851 "Domainname" : "", 1852 "AttachStdout" : false, 1853 "Tty" : false, 1854 "Hostname" : "e611e15f9c9d", 1855 "Volumes" : null, 1856 "Cmd" : [ 1857 "/bin/bash" 1858 ], 1859 "ExposedPorts" : null, 1860 "Env" : [ 1861 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 1862 ], 1863 "Labels" : { 1864 "com.example.vendor" : "Acme", 1865 "com.example.version" : "1.0", 1866 "com.example.license" : "GPL" 1867 }, 1868 "Entrypoint" : null, 1869 "MacAddress" : "", 1870 "AttachStderr" : false, 1871 "WorkingDir" : "", 1872 "User" : "" 1873 } 1874 } 1875 1876 **Status codes**: 1877 1878 - **200** – no error 1879 - **404** – no such image 1880 - **500** – server error 1881 1882 ### Get the history of an image 1883 1884 `GET /images/(name)/history` 1885 1886 Return the history of the image `name` 1887 1888 **Example request**: 1889 1890 GET /images/ubuntu/history HTTP/1.1 1891 1892 **Example response**: 1893 1894 HTTP/1.1 200 OK 1895 Content-Type: application/json 1896 1897 [ 1898 { 1899 "Id": "3db9c44f45209632d6050b35958829c3a2aa256d81b9a7be45b362ff85c54710", 1900 "Created": 1398108230, 1901 "CreatedBy": "/bin/sh -c #(nop) ADD file:eb15dbd63394e063b805a3c32ca7bf0266ef64676d5a6fab4801f2e81e2a5148 in /", 1902 "Tags": [ 1903 "ubuntu:lucid", 1904 "ubuntu:10.04" 1905 ], 1906 "Size": 182964289, 1907 "Comment": "" 1908 }, 1909 { 1910 "Id": "6cfa4d1f33fb861d4d114f43b25abd0ac737509268065cdfd69d544a59c85ab8", 1911 "Created": 1398108222, 1912 "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/", 1913 "Tags": null, 1914 "Size": 0, 1915 "Comment": "" 1916 }, 1917 { 1918 "Id": "511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158", 1919 "Created": 1371157430, 1920 "CreatedBy": "", 1921 "Tags": [ 1922 "scratch12:latest", 1923 "scratch:latest" 1924 ], 1925 "Size": 0, 1926 "Comment": "Imported from -" 1927 } 1928 ] 1929 1930 **Status codes**: 1931 1932 - **200** – no error 1933 - **404** – no such image 1934 - **500** – server error 1935 1936 ### Push an image on the registry 1937 1938 `POST /images/(name)/push` 1939 1940 Push the image `name` on the registry 1941 1942 **Example request**: 1943 1944 POST /images/test/push HTTP/1.1 1945 1946 **Example response**: 1947 1948 HTTP/1.1 200 OK 1949 Content-Type: application/json 1950 1951 {"status": "Pushing..."} 1952 {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} 1953 {"error": "Invalid..."} 1954 ... 1955 1956 If you wish to push an image on to a private registry, that image must already have a tag 1957 into a repository which references that registry `hostname` and `port`. This repository name should 1958 then be used in the URL. This duplicates the command line's flow. 1959 1960 The push is cancelled if the HTTP connection is closed. 1961 1962 **Example request**: 1963 1964 POST /images/registry.acme.com:5000/test/push HTTP/1.1 1965 1966 1967 **Query parameters**: 1968 1969 - **tag** – The tag to associate with the image on the registry. This is optional. 1970 1971 **Request Headers**: 1972 1973 - **X-Registry-Auth** – base64-encoded AuthConfig object, containing either login information, or a token 1974 - Credential based login: 1975 1976 ``` 1977 { 1978 "username": "jdoe", 1979 "password": "secret", 1980 "email": "jdoe@acme.com", 1981 } 1982 ``` 1983 1984 - Token based login: 1985 1986 ``` 1987 { 1988 "registrytoken": "9cbaf023786cd7..." 1989 } 1990 ``` 1991 1992 **Status codes**: 1993 1994 - **200** – no error 1995 - **404** – no such image 1996 - **500** – server error 1997 1998 ### Tag an image into a repository 1999 2000 `POST /images/(name)/tag` 2001 2002 Tag the image `name` into a repository 2003 2004 **Example request**: 2005 2006 POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 2007 2008 **Example response**: 2009 2010 HTTP/1.1 201 Created 2011 2012 **Query parameters**: 2013 2014 - **repo** – The repository to tag in 2015 - **force** – 1/True/true or 0/False/false, default false 2016 - **tag** - The new tag name 2017 2018 **Status codes**: 2019 2020 - **201** – no error 2021 - **400** – bad parameter 2022 - **404** – no such image 2023 - **409** – conflict 2024 - **500** – server error 2025 2026 ### Remove an image 2027 2028 `DELETE /images/(name)` 2029 2030 Remove the image `name` from the filesystem 2031 2032 **Example request**: 2033 2034 DELETE /images/test HTTP/1.1 2035 2036 **Example response**: 2037 2038 HTTP/1.1 200 OK 2039 Content-type: application/json 2040 2041 [ 2042 {"Untagged": "3e2f21a89f"}, 2043 {"Deleted": "3e2f21a89f"}, 2044 {"Deleted": "53b4f83ac9"} 2045 ] 2046 2047 **Query parameters**: 2048 2049 - **force** – 1/True/true or 0/False/false, default false 2050 - **noprune** – 1/True/true or 0/False/false, default false 2051 2052 **Status codes**: 2053 2054 - **200** – no error 2055 - **404** – no such image 2056 - **409** – conflict 2057 - **500** – server error 2058 2059 ### Search images 2060 2061 `GET /images/search` 2062 2063 Search for an image on [Docker Hub](https://hub.docker.com). 2064 2065 > **Note**: 2066 > The response keys have changed from API v1.6 to reflect the JSON 2067 > sent by the registry server to the docker daemon's request. 2068 2069 **Example request**: 2070 2071 GET /images/search?term=sshd HTTP/1.1 2072 2073 **Example response**: 2074 2075 HTTP/1.1 200 OK 2076 Content-Type: application/json 2077 2078 [ 2079 { 2080 "description": "", 2081 "is_official": false, 2082 "is_automated": false, 2083 "name": "wma55/u1210sshd", 2084 "star_count": 0 2085 }, 2086 { 2087 "description": "", 2088 "is_official": false, 2089 "is_automated": false, 2090 "name": "jdswinbank/sshd", 2091 "star_count": 0 2092 }, 2093 { 2094 "description": "", 2095 "is_official": false, 2096 "is_automated": false, 2097 "name": "vgauthier/sshd", 2098 "star_count": 0 2099 } 2100 ... 2101 ] 2102 2103 **Query parameters**: 2104 2105 - **term** – term to search 2106 2107 **Status codes**: 2108 2109 - **200** – no error 2110 - **500** – server error 2111 2112 ## 2.3 Misc 2113 2114 ### Check auth configuration 2115 2116 `POST /auth` 2117 2118 Get the default username and email 2119 2120 **Example request**: 2121 2122 POST /auth HTTP/1.1 2123 Content-Type: application/json 2124 2125 { 2126 "username": "hannibal", 2127 "password": "xxxx", 2128 "email": "hannibal@a-team.com", 2129 "serveraddress": "https://index.docker.io/v1/" 2130 } 2131 2132 **Example response**: 2133 2134 HTTP/1.1 200 OK 2135 2136 **Status codes**: 2137 2138 - **200** – no error 2139 - **204** – no error 2140 - **500** – server error 2141 2142 ### Display system-wide information 2143 2144 `GET /info` 2145 2146 Display system-wide information 2147 2148 **Example request**: 2149 2150 GET /info HTTP/1.1 2151 2152 **Example response**: 2153 2154 HTTP/1.1 200 OK 2155 Content-Type: application/json 2156 2157 { 2158 "Architecture": "x86_64", 2159 "ClusterStore": "etcd://localhost:2379", 2160 "Containers": 11, 2161 "ContainersRunning": 7, 2162 "ContainersStopped": 3, 2163 "ContainersPaused": 1, 2164 "CpuCfsPeriod": true, 2165 "CpuCfsQuota": true, 2166 "Debug": false, 2167 "DockerRootDir": "/var/lib/docker", 2168 "Driver": "btrfs", 2169 "DriverStatus": [[""]], 2170 "ExecutionDriver": "native-0.1", 2171 "ExperimentalBuild": false, 2172 "HttpProxy": "http://test:test@localhost:8080", 2173 "HttpsProxy": "https://test:test@localhost:8080", 2174 "ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS", 2175 "IPv4Forwarding": true, 2176 "Images": 16, 2177 "IndexServerAddress": "https://index.docker.io/v1/", 2178 "InitPath": "/usr/bin/docker", 2179 "InitSha1": "", 2180 "KernelVersion": "3.12.0-1-amd64", 2181 "Labels": [ 2182 "storage=ssd" 2183 ], 2184 "MemTotal": 2099236864, 2185 "MemoryLimit": true, 2186 "NCPU": 1, 2187 "NEventsListener": 0, 2188 "NFd": 11, 2189 "NGoroutines": 21, 2190 "Name": "prod-server-42", 2191 "NoProxy": "9.81.1.160", 2192 "OomKillDisable": true, 2193 "OSType": "linux", 2194 "OperatingSystem": "Boot2Docker", 2195 "Plugins": { 2196 "Volume": [ 2197 "local" 2198 ], 2199 "Network": [ 2200 "null", 2201 "host", 2202 "bridge" 2203 ] 2204 }, 2205 "RegistryConfig": { 2206 "IndexConfigs": { 2207 "docker.io": { 2208 "Mirrors": null, 2209 "Name": "docker.io", 2210 "Official": true, 2211 "Secure": true 2212 } 2213 }, 2214 "InsecureRegistryCIDRs": [ 2215 "127.0.0.0/8" 2216 ] 2217 }, 2218 "ServerVersion": "1.9.0", 2219 "SwapLimit": false, 2220 "SystemStatus": [["State", "Healthy"]], 2221 "SystemTime": "2015-03-10T11:11:23.730591467-07:00" 2222 } 2223 2224 **Status codes**: 2225 2226 - **200** – no error 2227 - **500** – server error 2228 2229 ### Show the docker version information 2230 2231 `GET /version` 2232 2233 Show the docker version information 2234 2235 **Example request**: 2236 2237 GET /version HTTP/1.1 2238 2239 **Example response**: 2240 2241 HTTP/1.1 200 OK 2242 Content-Type: application/json 2243 2244 { 2245 "Version": "1.10.0", 2246 "Os": "linux", 2247 "KernelVersion": "3.19.0-23-generic", 2248 "GoVersion": "go1.4.2", 2249 "GitCommit": "e75da4b", 2250 "Arch": "amd64", 2251 "ApiVersion": "1.22", 2252 "BuildTime": "2015-12-01T07:09:13.444803460+00:00", 2253 "Experimental": true 2254 } 2255 2256 **Status codes**: 2257 2258 - **200** – no error 2259 - **500** – server error 2260 2261 ### Ping the docker server 2262 2263 `GET /_ping` 2264 2265 Ping the docker server 2266 2267 **Example request**: 2268 2269 GET /_ping HTTP/1.1 2270 2271 **Example response**: 2272 2273 HTTP/1.1 200 OK 2274 Content-Type: text/plain 2275 2276 OK 2277 2278 **Status codes**: 2279 2280 - **200** - no error 2281 - **500** - server error 2282 2283 ### Create a new image from a container's changes 2284 2285 `POST /commit` 2286 2287 Create a new image from a container's changes 2288 2289 **Example request**: 2290 2291 POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 2292 Content-Type: application/json 2293 2294 { 2295 "Hostname": "", 2296 "Domainname": "", 2297 "User": "", 2298 "AttachStdin": false, 2299 "AttachStdout": true, 2300 "AttachStderr": true, 2301 "Tty": false, 2302 "OpenStdin": false, 2303 "StdinOnce": false, 2304 "Env": null, 2305 "Cmd": [ 2306 "date" 2307 ], 2308 "Mounts": [ 2309 { 2310 "Source": "/data", 2311 "Destination": "/data", 2312 "Mode": "ro,Z", 2313 "RW": false 2314 } 2315 ], 2316 "Labels": { 2317 "key1": "value1", 2318 "key2": "value2" 2319 }, 2320 "WorkingDir": "", 2321 "NetworkDisabled": false, 2322 "ExposedPorts": { 2323 "22/tcp": {} 2324 } 2325 } 2326 2327 **Example response**: 2328 2329 HTTP/1.1 201 Created 2330 Content-Type: application/json 2331 2332 {"Id": "596069db4bf5"} 2333 2334 **JSON parameters**: 2335 2336 - **config** - the container's configuration 2337 2338 **Query parameters**: 2339 2340 - **container** – source container 2341 - **repo** – repository 2342 - **tag** – tag 2343 - **comment** – commit message 2344 - **author** – author (e.g., "John Hannibal Smith 2345 <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") 2346 - **pause** – 1/True/true or 0/False/false, whether to pause the container before committing 2347 - **changes** – Dockerfile instructions to apply while committing 2348 2349 **Status codes**: 2350 2351 - **201** – no error 2352 - **404** – no such container 2353 - **500** – server error 2354 2355 ### Monitor Docker's events 2356 2357 `GET /events` 2358 2359 Get container events from docker, in real time via streaming. 2360 2361 Docker containers report the following events: 2362 2363 attach, commit, copy, create, destroy, die, exec_create, exec_start, export, kill, oom, pause, rename, resize, restart, start, stop, top, unpause, update 2364 2365 Docker images report the following events: 2366 2367 delete, import, pull, push, tag, untag 2368 2369 Docker volumes report the following events: 2370 2371 create, mount, unmount, destroy 2372 2373 Docker networks report the following events: 2374 2375 create, connect, disconnect, destroy 2376 2377 **Example request**: 2378 2379 GET /events?since=1374067924 2380 2381 **Example response**: 2382 2383 HTTP/1.1 200 OK 2384 Content-Type: application/json 2385 Server: Docker/1.10.0 (linux) 2386 Date: Fri, 29 Apr 2016 15:18:06 GMT 2387 Transfer-Encoding: chunked 2388 2389 { 2390 "status": "pull", 2391 "id": "alpine:latest", 2392 "Type": "image", 2393 "Action": "pull", 2394 "Actor": { 2395 "ID": "alpine:latest", 2396 "Attributes": { 2397 "name": "alpine" 2398 } 2399 }, 2400 "time": 1461943101, 2401 "timeNano": 1461943101301854122 2402 } 2403 { 2404 "status": "create", 2405 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2406 "from": "alpine", 2407 "Type": "container", 2408 "Action": "create", 2409 "Actor": { 2410 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2411 "Attributes": { 2412 "com.example.some-label": "some-label-value", 2413 "image": "alpine", 2414 "name": "my-container" 2415 } 2416 }, 2417 "time": 1461943101, 2418 "timeNano": 1461943101381709551 2419 } 2420 { 2421 "status": "attach", 2422 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2423 "from": "alpine", 2424 "Type": "container", 2425 "Action": "attach", 2426 "Actor": { 2427 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2428 "Attributes": { 2429 "com.example.some-label": "some-label-value", 2430 "image": "alpine", 2431 "name": "my-container" 2432 } 2433 }, 2434 "time": 1461943101, 2435 "timeNano": 1461943101383858412 2436 } 2437 { 2438 "Type": "network", 2439 "Action": "connect", 2440 "Actor": { 2441 "ID": "7dc8ac97d5d29ef6c31b6052f3938c1e8f2749abbd17d1bd1febf2608db1b474", 2442 "Attributes": { 2443 "container": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2444 "name": "bridge", 2445 "type": "bridge" 2446 } 2447 }, 2448 "time": 1461943101, 2449 "timeNano": 1461943101394865557 2450 } 2451 { 2452 "status": "start", 2453 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2454 "from": "alpine", 2455 "Type": "container", 2456 "Action": "start", 2457 "Actor": { 2458 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2459 "Attributes": { 2460 "com.example.some-label": "some-label-value", 2461 "image": "alpine", 2462 "name": "my-container" 2463 } 2464 }, 2465 "time": 1461943101, 2466 "timeNano": 1461943101607533796 2467 } 2468 { 2469 "status": "resize", 2470 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2471 "from": "alpine", 2472 "Type": "container", 2473 "Action": "resize", 2474 "Actor": { 2475 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2476 "Attributes": { 2477 "com.example.some-label": "some-label-value", 2478 "height": "46", 2479 "image": "alpine", 2480 "name": "my-container", 2481 "width": "204" 2482 } 2483 }, 2484 "time": 1461943101, 2485 "timeNano": 1461943101610269268 2486 } 2487 { 2488 "status": "die", 2489 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2490 "from": "alpine", 2491 "Type": "container", 2492 "Action": "die", 2493 "Actor": { 2494 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2495 "Attributes": { 2496 "com.example.some-label": "some-label-value", 2497 "exitCode": "0", 2498 "image": "alpine", 2499 "name": "my-container" 2500 } 2501 }, 2502 "time": 1461943105, 2503 "timeNano": 1461943105079144137 2504 } 2505 { 2506 "Type": "network", 2507 "Action": "disconnect", 2508 "Actor": { 2509 "ID": "7dc8ac97d5d29ef6c31b6052f3938c1e8f2749abbd17d1bd1febf2608db1b474", 2510 "Attributes": { 2511 "container": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2512 "name": "bridge", 2513 "type": "bridge" 2514 } 2515 }, 2516 "time": 1461943105, 2517 "timeNano": 1461943105230860245 2518 } 2519 { 2520 "status": "destroy", 2521 "id": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2522 "from": "alpine", 2523 "Type": "container", 2524 "Action": "destroy", 2525 "Actor": { 2526 "ID": "ede54ee1afda366ab42f824e8a5ffd195155d853ceaec74a927f249ea270c743", 2527 "Attributes": { 2528 "com.example.some-label": "some-label-value", 2529 "image": "alpine", 2530 "name": "my-container" 2531 } 2532 }, 2533 "time": 1461943105, 2534 "timeNano": 1461943105338056026 2535 } 2536 2537 **Query parameters**: 2538 2539 - **since** – Timestamp. Show all events created since timestamp and then stream 2540 - **until** – Timestamp. Show events created until given timestamp and stop streaming 2541 - **filters** – A json encoded value of the filters (a map[string][]string) to process on the event list. Available filters: 2542 - `container=<string>`; -- container to filter 2543 - `event=<string>`; -- event to filter 2544 - `image=<string>`; -- image to filter 2545 - `label=<string>`; -- image and container label to filter 2546 - `type=<string>`; -- either `container` or `image` or `volume` or `network` 2547 - `volume=<string>`; -- volume to filter 2548 - `network=<string>`; -- network to filter 2549 2550 **Status codes**: 2551 2552 - **200** – no error 2553 - **500** – server error 2554 2555 ### Get a tarball containing all images in a repository 2556 2557 `GET /images/(name)/get` 2558 2559 Get a tarball containing all images and metadata for the repository specified 2560 by `name`. 2561 2562 If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image 2563 (and its parents) are returned. If `name` is an image ID, similarly only that 2564 image (and its parents) are returned, but with the exclusion of the 2565 'repositories' file in the tarball, as there were no image names referenced. 2566 2567 See the [image tarball format](#image-tarball-format) for more details. 2568 2569 **Example request** 2570 2571 GET /images/ubuntu/get 2572 2573 **Example response**: 2574 2575 HTTP/1.1 200 OK 2576 Content-Type: application/x-tar 2577 2578 Binary data stream 2579 2580 **Status codes**: 2581 2582 - **200** – no error 2583 - **500** – server error 2584 2585 ### Get a tarball containing all images 2586 2587 `GET /images/get` 2588 2589 Get a tarball containing all images and metadata for one or more repositories. 2590 2591 For each value of the `names` parameter: if it is a specific name and tag (e.g. 2592 `ubuntu:latest`), then only that image (and its parents) are returned; if it is 2593 an image ID, similarly only that image (and its parents) are returned and there 2594 would be no names referenced in the 'repositories' file for this image ID. 2595 2596 See the [image tarball format](#image-tarball-format) for more details. 2597 2598 **Example request** 2599 2600 GET /images/get?names=myname%2Fmyapp%3Alatest&names=busybox 2601 2602 **Example response**: 2603 2604 HTTP/1.1 200 OK 2605 Content-Type: application/x-tar 2606 2607 Binary data stream 2608 2609 **Status codes**: 2610 2611 - **200** – no error 2612 - **500** – server error 2613 2614 ### Load a tarball with a set of images and tags into docker 2615 2616 `POST /images/load` 2617 2618 Load a set of images and tags into a Docker repository. 2619 See the [image tarball format](#image-tarball-format) for more details. 2620 2621 **Example request** 2622 2623 POST /images/load 2624 Content-Type: application/x-tar 2625 2626 Tarball in body 2627 2628 **Example response**: 2629 2630 HTTP/1.1 200 OK 2631 2632 **Status codes**: 2633 2634 - **200** – no error 2635 - **500** – server error 2636 2637 ### Image tarball format 2638 2639 An image tarball contains one directory per image layer (named using its long ID), 2640 each containing these files: 2641 2642 - `VERSION`: currently `1.0` - the file format version 2643 - `json`: detailed layer information, similar to `docker inspect layer_id` 2644 - `layer.tar`: A tarfile containing the filesystem changes in this layer 2645 2646 The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories 2647 for storing attribute changes and deletions. 2648 2649 If the tarball defines a repository, the tarball should also include a `repositories` file at 2650 the root that contains a list of repository and tag names mapped to layer IDs. 2651 2652 ``` 2653 {"hello-world": 2654 {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} 2655 } 2656 ``` 2657 2658 ### Exec Create 2659 2660 `POST /containers/(id or name)/exec` 2661 2662 Sets up an exec instance in a running container `id` 2663 2664 **Example request**: 2665 2666 POST /containers/e90e34656806/exec HTTP/1.1 2667 Content-Type: application/json 2668 2669 { 2670 "AttachStdin": true, 2671 "AttachStdout": true, 2672 "AttachStderr": true, 2673 "Cmd": ["sh"], 2674 "DetachKeys": "ctrl-p,ctrl-q", 2675 "Privileged": true, 2676 "Tty": true, 2677 "User": "123:456" 2678 } 2679 2680 **Example response**: 2681 2682 HTTP/1.1 201 Created 2683 Content-Type: application/json 2684 2685 { 2686 "Id": "f90e34656806", 2687 "Warnings":[] 2688 } 2689 2690 **JSON parameters**: 2691 2692 - **AttachStdin** - Boolean value, attaches to `stdin` of the `exec` command. 2693 - **AttachStdout** - Boolean value, attaches to `stdout` of the `exec` command. 2694 - **AttachStderr** - Boolean value, attaches to `stderr` of the `exec` command. 2695 - **DetachKeys** – Override the key sequence for detaching a 2696 container. Format is a single character `[a-Z]` or `ctrl-<value>` 2697 where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. 2698 - **Tty** - Boolean value to allocate a pseudo-TTY. 2699 - **Cmd** - Command to run specified as a string or an array of strings. 2700 - **Privileged** - Boolean value, runs the exec process with extended privileges. 2701 - **User** - A string value specifying the user, and optionally, group to run 2702 the exec process inside the container. Format is one of: `"user"`, 2703 `"user:group"`, `"uid"`, or `"uid:gid"`. 2704 2705 **Status codes**: 2706 2707 - **201** – no error 2708 - **404** – no such container 2709 - **409** - container is paused 2710 - **500** - server error 2711 2712 ### Exec Start 2713 2714 `POST /exec/(id)/start` 2715 2716 Starts a previously set up `exec` instance `id`. If `detach` is true, this API 2717 returns after starting the `exec` command. Otherwise, this API sets up an 2718 interactive session with the `exec` command. 2719 2720 **Example request**: 2721 2722 POST /exec/e90e34656806/start HTTP/1.1 2723 Content-Type: application/json 2724 2725 { 2726 "Detach": false, 2727 "Tty": false 2728 } 2729 2730 **Example response**: 2731 2732 HTTP/1.1 200 OK 2733 Content-Type: application/vnd.docker.raw-stream 2734 2735 {{ STREAM }} 2736 2737 **JSON parameters**: 2738 2739 - **Detach** - Detach from the `exec` command. 2740 - **Tty** - Boolean value to allocate a pseudo-TTY. 2741 2742 **Status codes**: 2743 2744 - **200** – no error 2745 - **404** – no such exec instance 2746 - **409** - container is paused 2747 2748 **Stream details**: 2749 2750 Similar to the stream behavior of `POST /containers/(id or name)/attach` API 2751 2752 ### Exec Resize 2753 2754 `POST /exec/(id)/resize` 2755 2756 Resizes the `tty` session used by the `exec` command `id`. The unit is number of characters. 2757 This API is valid only if `tty` was specified as part of creating and starting the `exec` command. 2758 2759 **Example request**: 2760 2761 POST /exec/e90e34656806/resize?h=40&w=80 HTTP/1.1 2762 Content-Type: text/plain 2763 2764 **Example response**: 2765 2766 HTTP/1.1 201 Created 2767 Content-Type: text/plain 2768 2769 **Query parameters**: 2770 2771 - **h** – height of `tty` session 2772 - **w** – width 2773 2774 **Status codes**: 2775 2776 - **201** – no error 2777 - **404** – no such exec instance 2778 2779 ### Exec Inspect 2780 2781 `GET /exec/(id)/json` 2782 2783 Return low-level information about the `exec` command `id`. 2784 2785 **Example request**: 2786 2787 GET /exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1 2788 2789 **Example response**: 2790 2791 HTTP/1.1 200 OK 2792 Content-Type: application/json 2793 2794 { 2795 "CanRemove": false, 2796 "ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126", 2797 "DetachKeys": "", 2798 "ExitCode": 2, 2799 "ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b", 2800 "OpenStderr": true, 2801 "OpenStdin": true, 2802 "OpenStdout": true, 2803 "ProcessConfig": { 2804 "arguments": [ 2805 "-c", 2806 "exit 2" 2807 ], 2808 "entrypoint": "sh", 2809 "privileged": false, 2810 "tty": true, 2811 "user": "1000" 2812 }, 2813 "Running": false 2814 } 2815 2816 **Status codes**: 2817 2818 - **200** – no error 2819 - **404** – no such exec instance 2820 - **500** - server error 2821 2822 ## 2.4 Volumes 2823 2824 ### List volumes 2825 2826 `GET /volumes` 2827 2828 **Example request**: 2829 2830 GET /volumes HTTP/1.1 2831 2832 **Example response**: 2833 2834 HTTP/1.1 200 OK 2835 Content-Type: application/json 2836 2837 { 2838 "Volumes": [ 2839 { 2840 "Name": "tardis", 2841 "Driver": "local", 2842 "Mountpoint": "/var/lib/docker/volumes/tardis" 2843 } 2844 ], 2845 "Warnings": [] 2846 } 2847 2848 **Query parameters**: 2849 2850 - **filters** - JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. There is one available filter: `dangling=true` 2851 2852 **Status codes**: 2853 2854 - **200** - no error 2855 - **500** - server error 2856 2857 ### Create a volume 2858 2859 `POST /volumes/create` 2860 2861 Create a volume 2862 2863 **Example request**: 2864 2865 POST /volumes/create HTTP/1.1 2866 Content-Type: application/json 2867 2868 { 2869 "Name": "tardis" 2870 } 2871 2872 **Example response**: 2873 2874 HTTP/1.1 201 Created 2875 Content-Type: application/json 2876 2877 { 2878 "Name": "tardis", 2879 "Driver": "local", 2880 "Mountpoint": "/var/lib/docker/volumes/tardis" 2881 } 2882 2883 **Status codes**: 2884 2885 - **201** - no error 2886 - **500** - server error 2887 2888 **JSON parameters**: 2889 2890 - **Name** - The new volume's name. If not specified, Docker generates a name. 2891 - **Driver** - Name of the volume driver to use. Defaults to `local` for the name. 2892 - **DriverOpts** - A mapping of driver options and values. These options are 2893 passed directly to the driver and are driver specific. 2894 2895 ### Inspect a volume 2896 2897 `GET /volumes/(name)` 2898 2899 Return low-level information on the volume `name` 2900 2901 **Example request**: 2902 2903 GET /volumes/tardis 2904 2905 **Example response**: 2906 2907 HTTP/1.1 200 OK 2908 Content-Type: application/json 2909 2910 { 2911 "Name": "tardis", 2912 "Driver": "local", 2913 "Mountpoint": "/var/lib/docker/volumes/tardis" 2914 } 2915 2916 **Status codes**: 2917 2918 - **200** - no error 2919 - **404** - no such volume 2920 - **500** - server error 2921 2922 ### Remove a volume 2923 2924 `DELETE /volumes/(name)` 2925 2926 Instruct the driver to remove the volume (`name`). 2927 2928 **Example request**: 2929 2930 DELETE /volumes/tardis HTTP/1.1 2931 2932 **Example response**: 2933 2934 HTTP/1.1 204 No Content 2935 2936 **Status codes**: 2937 2938 - **204** - no error 2939 - **404** - no such volume or volume driver 2940 - **409** - volume is in use and cannot be removed 2941 - **500** - server error 2942 2943 ## 2.5 Networks 2944 2945 ### List networks 2946 2947 `GET /networks` 2948 2949 **Example request**: 2950 2951 GET /networks?filters={"type":{"custom":true}} HTTP/1.1 2952 2953 **Example response**: 2954 2955 ``` 2956 HTTP/1.1 200 OK 2957 Content-Type: application/json 2958 2959 [ 2960 { 2961 "Name": "bridge", 2962 "Id": "f2de39df4171b0dc801e8002d1d999b77256983dfc63041c0f34030aa3977566", 2963 "Scope": "local", 2964 "Driver": "bridge", 2965 "IPAM": { 2966 "Driver": "default", 2967 "Config": [ 2968 { 2969 "Subnet": "172.17.0.0/16" 2970 } 2971 ] 2972 }, 2973 "Containers": { 2974 "39b69226f9d79f5634485fb236a23b2fe4e96a0a94128390a7fbbcc167065867": { 2975 "EndpointID": "ed2419a97c1d9954d05b46e462e7002ea552f216e9b136b80a7db8d98b442eda", 2976 "MacAddress": "02:42:ac:11:00:02", 2977 "IPv4Address": "172.17.0.2/16", 2978 "IPv6Address": "" 2979 } 2980 }, 2981 "Options": { 2982 "com.docker.network.bridge.default_bridge": "true", 2983 "com.docker.network.bridge.enable_icc": "true", 2984 "com.docker.network.bridge.enable_ip_masquerade": "true", 2985 "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", 2986 "com.docker.network.bridge.name": "docker0", 2987 "com.docker.network.driver.mtu": "1500" 2988 } 2989 }, 2990 { 2991 "Name": "none", 2992 "Id": "e086a3893b05ab69242d3c44e49483a3bbbd3a26b46baa8f61ab797c1088d794", 2993 "Scope": "local", 2994 "Driver": "null", 2995 "IPAM": { 2996 "Driver": "default", 2997 "Config": [] 2998 }, 2999 "Containers": {}, 3000 "Options": {} 3001 }, 3002 { 3003 "Name": "host", 3004 "Id": "13e871235c677f196c4e1ecebb9dc733b9b2d2ab589e30c539efeda84a24215e", 3005 "Scope": "local", 3006 "Driver": "host", 3007 "IPAM": { 3008 "Driver": "default", 3009 "Config": [] 3010 }, 3011 "Containers": {}, 3012 "Options": {} 3013 } 3014 ] 3015 ``` 3016 3017 **Query parameters**: 3018 3019 - **filters** - JSON encoded network list filter. The filter value is one of: 3020 - `id=<network-id>` Matches all or part of a network id. 3021 - `name=<network-name>` Matches all or part of a network name. 3022 - `type=["custom"|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. 3023 3024 **Status codes**: 3025 3026 - **200** - no error 3027 - **500** - server error 3028 3029 ### Inspect network 3030 3031 `GET /networks/<network-id>` 3032 3033 **Example request**: 3034 3035 GET /networks/7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99 HTTP/1.1 3036 3037 **Example response**: 3038 3039 ``` 3040 HTTP/1.1 200 OK 3041 Content-Type: application/json 3042 3043 { 3044 "Name": "net01", 3045 "Id": "7d86d31b1478e7cca9ebed7e73aa0fdeec46c5ca29497431d3007d2d9e15ed99", 3046 "Scope": "local", 3047 "Driver": "bridge", 3048 "IPAM": { 3049 "Driver": "default", 3050 "Config": [ 3051 { 3052 "Subnet": "172.19.0.0/16", 3053 "Gateway": "172.19.0.1/16" 3054 } 3055 ], 3056 "Options": { 3057 "foo": "bar" 3058 } 3059 }, 3060 "Containers": { 3061 "19a4d5d687db25203351ed79d478946f861258f018fe384f229f2efa4b23513c": { 3062 "Name": "test", 3063 "EndpointID": "628cadb8bcb92de107b2a1e516cbffe463e321f548feb37697cce00ad694f21a", 3064 "MacAddress": "02:42:ac:13:00:02", 3065 "IPv4Address": "172.19.0.2/16", 3066 "IPv6Address": "" 3067 } 3068 }, 3069 "Options": { 3070 "com.docker.network.bridge.default_bridge": "true", 3071 "com.docker.network.bridge.enable_icc": "true", 3072 "com.docker.network.bridge.enable_ip_masquerade": "true", 3073 "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", 3074 "com.docker.network.bridge.name": "docker0", 3075 "com.docker.network.driver.mtu": "1500" 3076 } 3077 } 3078 ``` 3079 3080 **Status codes**: 3081 3082 - **200** - no error 3083 - **404** - network not found 3084 3085 ### Create a network 3086 3087 `POST /networks/create` 3088 3089 Create a network 3090 3091 **Example request**: 3092 3093 ``` 3094 POST /networks/create HTTP/1.1 3095 Content-Type: application/json 3096 3097 { 3098 "Name":"isolated_nw", 3099 "Driver":"bridge", 3100 "IPAM":{ 3101 "Config":[ 3102 { 3103 "Subnet":"172.20.0.0/16", 3104 "IPRange":"172.20.10.0/24", 3105 "Gateway":"172.20.10.11" 3106 }, 3107 { 3108 "Subnet":"2001:db8:abcd::/64", 3109 "Gateway":"2001:db8:abcd::1011" 3110 } 3111 ], 3112 "Options": { 3113 "foo": "bar" 3114 } 3115 }, 3116 "Internal":true 3117 } 3118 ``` 3119 3120 **Example response**: 3121 3122 ``` 3123 HTTP/1.1 201 Created 3124 Content-Type: application/json 3125 3126 { 3127 "Id": "22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30", 3128 "Warning": "" 3129 } 3130 ``` 3131 3132 **Status codes**: 3133 3134 - **201** - no error 3135 - **404** - plugin not found 3136 - **500** - server error 3137 3138 **JSON parameters**: 3139 3140 - **Name** - The new network's name. this is a mandatory field 3141 - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver 3142 - **IPAM** - Optional custom IP scheme for the network 3143 - **Options** - Network specific options to be used by the drivers 3144 - **CheckDuplicate** - Requests daemon to check for networks with same name 3145 3146 ### Connect a container to a network 3147 3148 `POST /networks/(id)/connect` 3149 3150 Connect a container to a network 3151 3152 **Example request**: 3153 3154 ``` 3155 POST /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/connect HTTP/1.1 3156 Content-Type: application/json 3157 3158 { 3159 "Container":"3613f73ba0e4", 3160 "EndpointConfig": { 3161 "IPAMConfig": { 3162 "IPv4Address":"172.24.56.89", 3163 "IPv6Address":"2001:db8::5689" 3164 } 3165 } 3166 } 3167 ``` 3168 3169 **Example response**: 3170 3171 HTTP/1.1 200 OK 3172 3173 **Status codes**: 3174 3175 - **200** - no error 3176 - **404** - network or container is not found 3177 - **500** - Internal Server Error 3178 3179 **JSON parameters**: 3180 3181 - **container** - container-id/name to be connected to the network 3182 3183 ### Disconnect a container from a network 3184 3185 `POST /networks/(id)/disconnect` 3186 3187 Disconnect a container from a network 3188 3189 **Example request**: 3190 3191 ``` 3192 POST /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30/disconnect HTTP/1.1 3193 Content-Type: application/json 3194 3195 { 3196 "Container":"3613f73ba0e4", 3197 "Force":false 3198 } 3199 ``` 3200 3201 **Example response**: 3202 3203 HTTP/1.1 200 OK 3204 3205 **Status codes**: 3206 3207 - **200** - no error 3208 - **404** - network or container not found 3209 - **500** - Internal Server Error 3210 3211 **JSON parameters**: 3212 3213 - **Container** - container-id/name to be disconnected from a network 3214 - **Force** - Force the container to disconnect from a network 3215 3216 ### Remove a network 3217 3218 `DELETE /networks/(id)` 3219 3220 Instruct the driver to remove the network (`id`). 3221 3222 **Example request**: 3223 3224 DELETE /networks/22be93d5babb089c5aab8dbc369042fad48ff791584ca2da2100db837a1c7c30 HTTP/1.1 3225 3226 **Example response**: 3227 3228 HTTP/1.1 200 OK 3229 3230 **Status codes**: 3231 3232 - **200** - no error 3233 - **404** - no such network 3234 - **500** - server error 3235 3236 # 3. Going further 3237 3238 ## 3.1 Inside `docker run` 3239 3240 As an example, the `docker run` command line makes the following API calls: 3241 3242 - Create the container 3243 3244 - If the status code is 404, it means the image doesn't exist: 3245 - Try to pull it. 3246 - Then, retry to create the container. 3247 3248 - Start the container. 3249 3250 - If you are not in detached mode: 3251 - Attach to the container, using `logs=1` (to have `stdout` and 3252 `stderr` from the container's start) and `stream=1` 3253 3254 - If in detached mode or only `stdin` is attached, display the container's id. 3255 3256 ## 3.2 Hijacking 3257 3258 In this version of the API, `/attach`, uses hijacking to transport `stdin`, 3259 `stdout`, and `stderr` on the same socket. 3260 3261 To hint potential proxies about connection hijacking, Docker client sends 3262 connection upgrade headers similarly to websocket. 3263 3264 Upgrade: tcp 3265 Connection: Upgrade 3266 3267 When Docker daemon detects the `Upgrade` header, it switches its status code 3268 from **200 OK** to **101 UPGRADED** and resends the same headers. 3269 3270 3271 ## 3.3 CORS Requests 3272 3273 To set cross origin requests to the remote api please give values to 3274 `--api-cors-header` when running Docker in daemon mode. Set * (asterisk) allows all, 3275 default or blank means CORS disabled 3276 3277 $ dockerd -H="192.168.1.9:2375" --api-cors-header="http://foo.bar"