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