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