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