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