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