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