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