diff --git a/docs/reference/api/docker_remote_api.md b/docs/reference/api/docker_remote_api.md index 39bf8a3369..01a1666ff3 100644 --- a/docs/reference/api/docker_remote_api.md +++ b/docs/reference/api/docker_remote_api.md @@ -50,10 +50,6 @@ Docker version | API version | Changes 1.8.x | [1.20](docker_remote_api_v1.20.md) | [API changes](docker_remote_api.md#v1-20-api-changes) 1.7.x | [1.19](docker_remote_api_v1.19.md) | [API changes](docker_remote_api.md#v1-19-api-changes) 1.6.x | [1.18](docker_remote_api_v1.18.md) | [API changes](docker_remote_api.md#v1-18-api-changes) -1.5.x | [1.17](docker_remote_api_v1.17.md) | [API changes](docker_remote_api.md#v1-17-api-changes) -1.4.x | [1.16](docker_remote_api_v1.16.md) | [API changes](docker_remote_api.md#v1-16-api-changes) -1.3.x | [1.15](docker_remote_api_v1.15.md) | [API changes](docker_remote_api.md#v1-15-api-changes) -1.2.x | [1.14](docker_remote_api_v1.14.md) | [API changes](docker_remote_api.md#v1-14-api-changes) Refer to the [GitHub repository]( https://github.com/docker/docker/tree/master/docs/reference/api) for @@ -61,12 +57,12 @@ older releases. ## Authentication -Since API version 1.2, the auth configuration is now handled client side, so the +Authentication configuration is handled client side, so the client has to send the `authConfig` as a `POST` in `/images/(name)/push`. The `authConfig`, set as the `X-Registry-Auth` header, is currently a Base64 encoded (JSON) string with the following structure: -``` +```JSON {"username": "string", "password": "string", "email": "string", "serveraddress" : "string", "auth": ""} ``` @@ -250,53 +246,3 @@ end point now returns the new boolean fields `CpuCfsPeriod`, `CpuCfsQuota`, and * `POST /build` closing the HTTP request cancels the build * `POST /containers/(id)/exec` includes `Warnings` field to response. -### v1.17 API changes - -[Docker Remote API v1.17](docker_remote_api_v1.17.md) documentation - -* The build supports `LABEL` command. Use this to add metadata to an image. For -example you could add data describing the content of an image. `LABEL -"com.example.vendor"="ACME Incorporated"` -* `POST /containers/(id)/attach` and `POST /exec/(id)/start` -* The Docker client now hints potential proxies about connection hijacking using HTTP Upgrade headers. -* `POST /containers/create` sets labels on container create describing the container. -* `GET /containers/json` returns the labels associated with the containers (`Labels`). -* `GET /containers/(id)/json` returns the list current execs associated with the -container (`ExecIDs`). This endpoint now returns the container labels -(`Config.Labels`). -* `POST /containers/(id)/rename` renames a container `id` to a new name.* -* `POST /containers/create` and `POST /containers/(id)/start` callers can pass -`ReadonlyRootfs` in the host config to mount the container's root filesystem as -read only. -* `GET /containers/(id)/stats` returns a live stream of a container's resource usage statistics. -* `GET /images/json` returns the labels associated with each image (`Labels`). - - -### v1.16 API changes - -[Docker Remote API v1.16](docker_remote_api_v1.16.md) - -* `GET /info` returns the number of CPUs available on the machine (`NCPU`), -total memory available (`MemTotal`), a user-friendly name describing the running Docker daemon (`Name`), a unique ID identifying the daemon (`ID`), and -a list of daemon labels (`Labels`). -* `POST /containers/create` callers can set the new container's MAC address explicitly. -* Volumes are now initialized when the container is created. -* `POST /containers/(id)/copy` copies data which is contained in a volume. - -### v1.15 API changes - -[Docker Remote API v1.15](docker_remote_api_v1.15.md) documentation - -`POST /containers/create` you can set a container's `HostConfig` when creating a -container. Previously this was only available when starting a container. - -### v1.14 API changes - -[Docker Remote API v1.14](docker_remote_api_v1.14.md) documentation - -* `DELETE /containers/(id)` when using `force`, the container will be immediately killed with SIGKILL. -* `POST /containers/(id)/start` the `HostConfig` option accepts the field `CapAdd`, which specifies a list of capabilities -to add, and the field `CapDrop`, which specifies a list of capabilities to drop. -* `POST /images/create` th `fromImage` and `repo` parameters support the -`repo:tag` format. Consequently, the `tag` parameter is now obsolete. Using the -new format and the `tag` parameter at the same time will return an error. diff --git a/docs/reference/api/docker_remote_api_v1.14.md b/docs/reference/api/docker_remote_api_v1.14.md deleted file mode 100644 index 673ed84437..0000000000 --- a/docs/reference/api/docker_remote_api_v1.14.md +++ /dev/null @@ -1,1469 +0,0 @@ - - -# Docker Remote API v1.14 - -## 1. Brief introduction - - - The Remote API has replaced `rcli`. - - The daemon listens on `unix:///var/run/docker.sock` but you can - [Bind Docker to another host/port or a Unix socket](../../quickstart.md#bind-docker-to-another-host-port-or-a-unix-socket). - - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `STDOUT`, - `STDIN` and `STDERR`. - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "9cd87474be90", - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "3176a2479c92", - "Image": "ubuntu:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Image": "ubuntu:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - } - ] - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by default (i.e., this defaults to false) -- **limit** – Show `limit` last created containers, include non-running ones. -- **since** – Show only containers created since Id, include non-running ones. -- **before** – Show only containers created before Id, include non-running ones. -- **size** – 1/True/true or 0/False/false, Show the containers sizes -- **filters** - a json encoded value of the filters (a map[string][]string) to process on the containers list. Available filters: - - exited=<int> -- containers with exit code of <int> - - status=(restarting|running|paused|exited) - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "Domainname": "", - "User":"", - "Memory":0, - "MemorySwap":0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env": [ - "FOO=bar", - "BAZ=quux" - ], - "Cmd":[ - "date" - ], - "Image":"ubuntu", - "Volumes":{ - "/tmp": {} - }, - "WorkingDir":"", - "NetworkDisabled": false, - "ExposedPorts":{ - "22/tcp": {} - }, - "RestartPolicy": { "Name": "always" } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -- **RestartPolicy** – The behavior to apply when the container exits. The - value is an object with a `Name` property of either `"always"` to - always restart or `"on-failure"` to restart only when the container - exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` - controls the number of times to retry before giving up. - The default is not to restart. (optional) - An ever increasing delay (double the previous delay, starting at 100mS) - is added before each restart to prevent flooding the server. -- **config** – the container's configuration - -Query Parameters: - -- **name** – Assign the specified name to the container. Must match `/?[a-zA-Z0-9_-]+`. - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id or name)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "ubuntu", - "Volumes": {}, - "VolumesFrom": "", - "WorkingDir": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {}, - "HostConfig": { - "Binds": null, - "ContainerIDFile": "", - "LxcConf": [], - "Privileged": false, - "PortBindings": { - "80/tcp": [ - { - "HostIp": "0.0.0.0", - "HostPort": "49153" - } - ] - }, - "Links": ["/name:alias"], - "PublishAllPorts": false, - "CapAdd": ["NET_ADMIN"], - "CapDrop": ["MKNOD"] - } - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id or name)/top` - -List processes running inside the container `id`. On Unix systems this -is done by running the `ps` command. This endpoint is not -supported on Windows. - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles" : [ - "UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD" - ], - "Processes" : [ - [ - "root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash" - ], - [ - "root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10" - ] - ] - } - -**Example request**: - - GET /containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles" : [ - "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND" - ] - "Processes" : [ - [ - "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash" - ], - [ - "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10" - ] - ], - } - -Query Parameters: - -- **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef` - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Get container logs - -`GET /containers/(id or name)/logs` - -Get stdout and stderr logs from the container ``id`` - -**Example request**: - - GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Query Parameters: - -- **follow** – 1/True/true or 0/False/false, return stream. Default false -- **stdout** – 1/True/true or 0/False/false, show stdout log. Default false -- **stderr** – 1/True/true or 0/False/false, show stderr log. Default false -- **timestamps** – 1/True/true or 0/False/false, print timestamps for every - log line. Default false -- **tail** – Output specified number of lines at the end of logs: `all` or - ``. Default all - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id or name)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id or name)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Start a container - -`POST /containers/(id or name)/start` - -Start the container `id` - -**Example request**: - - POST /containers/e90e34656806/start HTTP/1.1 - Content-Type: application/json - - { - "Binds":["/tmp:/tmp"], - "Links":["redis3:redis"], - "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], - "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, - "PublishAllPorts":false, - "Privileged":false, - "Dns": ["8.8.8.8"], - "VolumesFrom": ["parent", "other:ro"], - "CapAdd": ["NET_ADMIN"], - "CapDrop": ["MKNOD"] - } - -**Example response**: - - HTTP/1.1 204 No Content - -Json Parameters: - -- **hostConfig** – the container's host configuration (optional) - -Status Codes: - -- **204** – no error -- **304** – container already started -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id or name)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **304** – container already stopped -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id or name)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id or name)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters - -- **signal** - Signal to send to the container: integer or string like "SIGINT". - When not set, SIGKILL is assumed and the call will wait for the container to exit. - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Pause a container - -`POST /containers/(id or name)/pause` - -Pause the container `id` - -**Example request**: - - POST /containers/e90e34656806/pause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Unpause a container - -`POST /containers/(id or name)/unpause` - -Unpause the container `id` - -**Example request**: - - POST /containers/e90e34656806/unpause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id or name)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Query Parameters: - -- **logs** – 1/True/true or 0/False/false, return logs. Default false -- **stream** – 1/True/true or 0/False/false, return stream. Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach to stdin. - Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - - **Stream details**: - - When using the TTY setting is enabled in - [`POST /containers/create`](#create-a-container), - the stream is the raw data from the process PTY and client's stdin. - When the TTY is disabled, then the stream is multiplexed to separate - stdout and stderr. - - The format is a **Header** and a **Payload** (frame). - - **HEADER** - - The header will contain the information on which stream write the - stream (stdout or stderr). It also contain the size of the - associated frame encoded on the last 4 bytes (uint32). - - It is encoded on the first 8 bytes like this: - - header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} - - `STREAM_TYPE` can be: - -- 0: stdin (will be written on stdout) -- 1: stdout -- 2: stderr - - `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of - the uint32 size encoded as big endian. - - **PAYLOAD** - - The payload is the raw stream. - - **IMPLEMENTATION** - - The simplest way to implement the Attach protocol is the following: - - 1. Read 8 bytes - 2. chose stdout or stderr depending on the first byte - 3. Extract the frame size from the last 4 bytes - 4. Read the extracted size and output it on the correct output - 5. Goto 1 - -### Attach to a container (websocket) - -`GET /containers/(id or name)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **logs** – 1/True/true or 0/False/false, return logs. Default false -- **stream** – 1/True/true or 0/False/false, return stream. - Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach - to stdin. Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id or name)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id or name)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **v** – 1/True/true or 0/False/false, Remove the volumes - associated to the container. Default false -- **force** - 1/True/true or 0/False/false, Kill then remove the container. - Default false - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id or name)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/json` - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "RepoTags": [ - "ubuntu:12.04", - "ubuntu:precise", - "ubuntu:latest" - ], - "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", - "Created": 1365714795, - "Size": 131506275, - "VirtualSize": 131506275 - }, - { - "RepoTags": [ - "ubuntu:12.10", - "ubuntu:quantal" - ], - "ParentId": "27cf784147099545", - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Created": 1364102658, - "Size": 24653, - "VirtualSize": 180116135 - } - ] - - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, default false -- **filters** – a json encoded value of the filters (a map[string][]string) to process on the images list. Available filters: - - dangling=true -- **filter** - only return images with the specified name - -### Create an image - -`POST /images/create` - -Create an image, either by pulling it from the registry or by importing it - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pulling..."} - {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} - {"error": "Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -Query Parameters: - -- **fromImage** – name of the image to pull -- **fromSrc** – source to import, - means stdin -- **repo** – repository -- **tag** – tag - -Request Headers: - -- **X-Registry-Auth** – base64-encoded AuthConfig object - -Status Codes: - -- **200** – no error -- **500** – server error - - - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/ubuntu/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Created": "2013-03-23T22:24:18.818426-07:00", - "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "ContainerConfig": - { - "Hostname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": false, - "AttachStderr": false, - "PortSpecs": null, - "Tty": true, - "OpenStdin": true, - "StdinOnce": false, - "Env": null, - "Cmd": ["/bin/bash"], - "Dns": null, - "Image": "ubuntu", - "Volumes": null, - "VolumesFrom": "", - "WorkingDir": "" - }, - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Parent": "27cf784147099545", - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/ubuntu/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pushing..."} - {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} - {"error": "Invalid..."} - ... - - If you wish to push an image on to a private registry, that image must already have been tagged - into a repository which references that registry host name and port. This repository name should - then be used in the URL. This mirrors the flow of the CLI. - -**Example request**: - - POST /images/registry.acme.com:5000/test/push HTTP/1.1 - - -Query Parameters: - -- **tag** – the tag to associate with the image on the registry, optional - -Request Headers: - -- **X-Registry-Auth** – include a base64-encoded AuthConfig object. - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 Created - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Query Parameters: - -- **force** – 1/True/true or 0/False/false, default false -- **noprune** – 1/True/true or 0/False/false, default false - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com). - -> **Note**: -> The response keys have changed from API v1.6 to reflect the JSON -> sent by the registry server to the docker daemon's request. - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "wma55/u1210sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "jdswinbank/sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "vgauthier/sshd", - "star_count": 0 - } - ... - ] - -Query Parameters: - -- **term** – term to search - -Status Codes: - -- **200** – no error -- **500** – server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"stream": "Step 1..."} - {"stream": "..."} - {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - - The archive must include a file called `Dockerfile` - at its root. It may include any number of other files, - which will be accessible in the build context (See the [*ADD build - command*](../../reference/builder.md#dockerbuilder)). - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – git or HTTP/HTTPS URI build source -- **q** – suppress verbose build output -- **nocache** – do not use the cache when building the image -- **rm** - remove intermediate containers after a successful build (default behavior) -- **forcerm** - always remove intermediate containers (includes rm) - - Request Headers: - -- **Content-type** – should be set to `"application/tar"`. -- **X-Registry-Config** – base64-encoded ConfigFile object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers": 11, - "Images": 16, - "Driver": "btrfs", - "ExecutionDriver": "native-0.1", - "KernelVersion": "3.12.0-1-amd64" - "Debug": false, - "NFd": 11, - "NGoroutines": 21, - "NEventsListener": 0, - "InitPath": "/usr/bin/docker", - "IndexServerAddress": ["https://index.docker.io/v1/"], - "MemoryLimit": true, - "SwapLimit": false, - "IPv4Forwarding": true - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "ApiVersion": "1.12", - "Version": "0.2.2", - "GitCommit": "5a2a5cc+CHANGES", - "GoVersion": "go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Ping the docker server - -`GET /_ping` - -Ping the docker server - -**Example request**: - - GET /_ping HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - OK - -Status Codes: - -- **200** - no error -- **500** - server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Hostname": "", - "Domainname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Volumes": { - "/tmp": {} - }, - "WorkingDir": "", - "NetworkDisabled": false, - "ExposedPorts": { - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - {"Id": "596069db4bf5"} - -Json Parameters: - -- **config** - the container's configuration - -Query Parameters: - -- **container** – source container -- **repo** – repository -- **tag** – tag -- **comment** – commit message -- **author** – author (e.g., "John Hannibal Smith - <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get container events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} - {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling -- **until** – timestamp used for polling - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images and tags in a repository - -`GET /images/(name)/get` - -Get a tarball containing all images and metadata for the repository -specified by `name`. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/ubuntu/get - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Load a tarball with a set of images and tags into docker - -`POST /images/load` - -Load a set of images and tags into the docker repository. -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - POST /images/load - - Tarball in body - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **500** – server error - -### Image tarball format - -An image tarball contains one directory per image layer (named using its long ID), -each containing three files: - -1. `VERSION`: currently `1.0` - the file format version -2. `json`: detailed layer information, similar to `docker inspect layer_id` -3. `layer.tar`: A tarfile containing the filesystem changes in this layer - -The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories -for storing attribute changes and deletions. - -If the tarball defines a repository, there will also be a `repositories` file at -the root that contains a list of repository and tag names mapped to layer IDs. - -``` -{"hello-world": - {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} -} -``` - -# 3. Going further - -## 3.1 Inside `docker run` - -As an example, the `docker run` command line makes the following API calls: - -- Create the container - -- If the status code is 404, it means the image doesn't exist: - - Try to pull it - - Then retry to create the container - -- Start the container - -- If you are not in detached mode: - - Attach to the container, using logs=1 (to have stdout and - stderr from the container's start) and stream=1 - -- If in detached mode or only stdin is attached: - - Display the container's id - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -stdout and stderr on the same socket. This might change in the future. - -## 3.3 CORS Requests - -To enable cross origin requests to the remote api add the flag -"--api-enable-cors" when running docker in daemon mode. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.15.md b/docs/reference/api/docker_remote_api_v1.15.md deleted file mode 100644 index e5f3ca6348..0000000000 --- a/docs/reference/api/docker_remote_api_v1.15.md +++ /dev/null @@ -1,1763 +0,0 @@ - - -# Docker Remote API v1.15 - -## 1. Brief introduction - - - The Remote API has replaced `rcli`. - - The daemon listens on `unix:///var/run/docker.sock` but you can - [Bind Docker to another host/port or a Unix socket](../../quickstart.md#bind-docker-to-another-host-port-or-a-unix-socket). - - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `STDOUT`, - `STDIN` and `STDERR`. - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Names":["/boring_feynman"], - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "9cd87474be90", - "Names":["/coolName"], - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "3176a2479c92", - "Names":["/sleepy_dog"], - "Image": "ubuntu:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Names":["/running_cat"], - "Image": "ubuntu:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - } - ] - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by default (i.e., this defaults to false) -- **limit** – Show `limit` last created - containers, include non-running ones. -- **since** – Show only containers created since Id, include - non-running ones. -- **before** – Show only containers created before Id, include - non-running ones. -- **size** – 1/True/true or 0/False/false, Show the containers - sizes -- **filters** - a json encoded value of the filters (a map[string][]string) to process on the containers list. Available filters: - - exited=<int> -- containers with exit code of <int> - - status=(restarting|running|paused|exited) - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname": "", - "Domainname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": [ - "FOO=bar", - "BAZ=quux" - ], - "Cmd": [ - "date" - ], - "Entrypoint": "", - "Image": "ubuntu", - "Volumes": { - "/tmp": {} - }, - "WorkingDir": "", - "NetworkDisabled": false, - "MacAddress": "12:34:56:78:9a:bc", - "ExposedPorts": { - "22/tcp": {} - }, - "SecurityOpt": [], - "HostConfig": { - "Binds": ["/tmp:/tmp"], - "Links": ["redis3:redis"], - "LxcConf": {"lxc.utsname":"docker"}, - "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] }, - "PublishAllPorts": false, - "Privileged": false, - "Dns": ["8.8.8.8"], - "DnsSearch": [""], - "ExtraHosts": null, - "VolumesFrom": ["parent", "other:ro"], - "CapAdd": ["NET_ADMIN"], - "CapDrop": ["MKNOD"], - "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 }, - "NetworkMode": "bridge", - "Devices": [] - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id": "f91ddc4b01e079c4481a8340bbbeca4dbd33d6e4a10662e499f8eacbb5bf252b" - "Warnings": [] - } - -Json Parameters: - -- **Hostname** - A string value containing the desired hostname to use for the - container. -- **Domainname** - A string value containing the desired domain name to use - for the container. -- **User** - A string value containing the user to use inside the container. -- **Memory** - Memory limit in bytes. -- **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap. -- **CpuShares** - An integer value containing the CPU Shares for container - (ie. the relative weight vs other containers). - **CpuSet** - String value containing the cgroups Cpuset to use. -- **AttachStdin** - Boolean value, attaches to stdin. -- **AttachStdout** - Boolean value, attaches to stdout. -- **AttachStderr** - Boolean value, attaches to stderr. -- **Tty** - Boolean value, Attach standard streams to a tty, including stdin if it is not closed. -- **OpenStdin** - Boolean value, opens stdin, -- **StdinOnce** - Boolean value, close stdin after the 1 attached client disconnects. -- **Env** - A list of environment variables in the form of `["VAR=value"[,"VAR2=value2"]]` -- **Cmd** - Command to run specified as a string or an array of strings. -- **Entrypoint** - Set the entrypoint for the container a string or an array - of strings -- **Image** - String value containing the image name to use for the container -- **Volumes** – An object mapping mountpoint paths (strings) inside the - container to empty objects. -- **WorkingDir** - A string value containing the working dir for commands to - run in. -- **NetworkDisabled** - Boolean value, when true disables networking for the - container -- **ExposedPorts** - An object mapping ports to an empty object in the form of: - `"ExposedPorts": { "/: {}" }` -- **SecurityOpt**: A list of string values to customize labels for MLS - systems, such as SELinux. -- **HostConfig** - - **Binds** – A list of volume bindings for this container. Each volume - binding is a string of the form `container_path` (to create a new - volume for the container), `host_path:container_path` (to bind-mount - a host path into the container), or `host_path:container_path:ro` - (to make the bind-mount read-only inside the container). - - **Links** - A list of links for the container. Each link entry should be - in the form of "container_name:alias". - - **LxcConf** - LXC specific configurations. These configurations will only - work when using the `lxc` execution driver. - - **PortBindings** - A map of exposed container ports and the host port they - should map to. It should be specified in the form - `{ /: [{ "HostPort": "" }] }` - Take note that `port` is specified as a string and not an integer value. - - **PublishAllPorts** - Allocates a random host port for all of a container's - exposed ports. Specified as a boolean value. - - **Privileged** - Gives the container full access to the host. Specified as - a boolean value. - - **Dns** - A list of dns servers for the container to use. - - **DnsSearch** - A list of DNS search domains - - **ExtraHosts** - A list of hostnames/IP mappings to be added to the - container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`. - - **VolumesFrom** - A list of volumes to inherit from another container. - Specified in the form `[:]` - - **CapAdd** - A list of kernel capabilities to add to the container. - - **Capdrop** - A list of kernel capabilities to drop from the container. - - **RestartPolicy** – The behavior to apply when the container exits. The - value is an object with a `Name` property of either `"always"` to - always restart or `"on-failure"` to restart only when the container - exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` - controls the number of times to retry before giving up. - The default is not to restart. (optional) - An ever increasing delay (double the previous delay, starting at 100mS) - is added before each restart to prevent flooding the server. - - **NetworkMode** - Sets the networking mode for the container. Supported - values are: `bridge`, `host`, `none`, and `container:` - - **Devices** - A list of devices to add to the container specified in the - form - `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}` - -Query Parameters: - -- **name** – Assign the specified name to the container. Must - match `/?[a-zA-Z0-9_-]+`. - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id or name)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "ubuntu", - "Volumes": {}, - "VolumesFrom": "", - "WorkingDir": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {}, - "HostConfig": { - "Binds": null, - "ContainerIDFile": "", - "LxcConf": [], - "Privileged": false, - "PortBindings": { - "80/tcp": [ - { - "HostIp": "0.0.0.0", - "HostPort": "49153" - } - ] - }, - "Links": ["/name:alias"], - "PublishAllPorts": false, - "CapAdd": ["NET_ADMIN"], - "CapDrop": ["MKNOD"] - } - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id or name)/top` - -List processes running inside the container `id`. On Unix systems this -is done by running the `ps` command. This endpoint is not -supported on Windows. - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles" : [ - "UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD" - ], - "Processes" : [ - [ - "root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash" - ], - [ - "root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10" - ] - ] - } - -**Example request**: - - GET /containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles" : [ - "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND" - ] - "Processes" : [ - [ - "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash" - ], - [ - "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10" - ] - ], - } - -Query Parameters: - -- **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef` - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Get container logs - -`GET /containers/(id or name)/logs` - -Get stdout and stderr logs from the container ``id`` - -**Example request**: - - GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Query Parameters: - -- **follow** – 1/True/true or 0/False/false, return stream. Default false -- **stdout** – 1/True/true or 0/False/false, show stdout log. Default false -- **stderr** – 1/True/true or 0/False/false, show stderr log. Default false -- **timestamps** – 1/True/true or 0/False/false, print timestamps for - every log line. Default false -- **tail** – Output specified number of lines at the end of logs: `all` or ``. Default all - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id or name)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id or name)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Resize a container TTY - -`GET /containers/(id or name)/resize?h=&w=` - -Resize the TTY of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Length: 0 - Content-Type: text/plain; charset=utf-8 - -Status Codes: - -- **200** – no error -- **404** – No such container -- **500** – bad file descriptor - -### Start a container - -`POST /containers/(id or name)/start` - -Start the container `id` - -**Example request**: - - POST /containers/e90e34656806/start HTTP/1.1 - Content-Type: application/json - - { - "Binds": ["/tmp:/tmp"], - "Links": ["redis3:redis"], - "LxcConf": {"lxc.utsname":"docker"}, - "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] }, - "PublishAllPorts": false, - "Privileged": false, - "Dns": ["8.8.8.8"], - "DnsSearch": [""], - "VolumesFrom": ["parent", "other:ro"], - "CapAdd": ["NET_ADMIN"], - "CapDrop": ["MKNOD"], - "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 }, - "NetworkMode": "bridge", - "Devices": [] - } - -**Example response**: - - HTTP/1.1 204 No Content - -Json Parameters: - -- **Binds** – A list of volume bindings for this container. Each volume - binding is a string of the form `container_path` (to create a new - volume for the container), `host_path:container_path` (to bind-mount - a host path into the container), or `host_path:container_path:ro` - (to make the bind-mount read-only inside the container). -- **Links** - A list of links for the container. Each link entry should be of - of the form "container_name:alias". -- **LxcConf** - LXC specific configurations. These configurations will only - work when using the `lxc` execution driver. -- **PortBindings** - A map of exposed container ports and the host port they - should map to. It should be specified in the form - `{ /: [{ "HostPort": "" }] }` - Take note that `port` is specified as a string and not an integer value. -- **PublishAllPorts** - Allocates a random host port for all of a container's - exposed ports. Specified as a boolean value. -- **Privileged** - Gives the container full access to the host. Specified as - a boolean value. -- **Dns** - A list of dns servers for the container to use. -- **DnsSearch** - A list of DNS search domains -- **VolumesFrom** - A list of volumes to inherit from another container. - Specified in the form `[:]` -- **CapAdd** - A list of kernel capabilities to add to the container. -- **Capdrop** - A list of kernel capabilities to drop from the container. -- **RestartPolicy** – The behavior to apply when the container exits. The - value is an object with a `Name` property of either `"always"` to - always restart or `"on-failure"` to restart only when the container - exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` - controls the number of times to retry before giving up. - The default is not to restart. (optional) - An ever increasing delay (double the previous delay, starting at 100mS) - is added before each restart to prevent flooding the server. -- **NetworkMode** - Sets the networking mode for the container. Supported - values are: `bridge`, `host`, `none`, and `container:` -- **Devices** - A list of devices to add to the container specified in the - form - `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}` - -Status Codes: - -- **204** – no error -- **304** – container already started -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id or name)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **304** – container already stopped -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id or name)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id or name)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters - -- **signal** - Signal to send to the container: integer or string like "SIGINT". - When not set, SIGKILL is assumed and the call will waits for the container to exit. - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Pause a container - -`POST /containers/(id or name)/pause` - -Pause the container `id` - -**Example request**: - - POST /containers/e90e34656806/pause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Unpause a container - -`POST /containers/(id or name)/unpause` - -Unpause the container `id` - -**Example request**: - - POST /containers/e90e34656806/unpause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id or name)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Query Parameters: - -- **logs** – 1/True/true or 0/False/false, return logs. Default false -- **stream** – 1/True/true or 0/False/false, return stream. - Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach - to stdin. Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - - **Stream details**: - - When using the TTY setting is enabled in - [`POST /containers/create`](#create-a-container), - the stream is the raw data from the process PTY and client's stdin. - When the TTY is disabled, then the stream is multiplexed to separate - stdout and stderr. - - The format is a **Header** and a **Payload** (frame). - - **HEADER** - - The header will contain the information on which stream write the - stream (stdout or stderr). It also contain the size of the - associated frame encoded on the last 4 bytes (uint32). - - It is encoded on the first 8 bytes like this: - - header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} - - `STREAM_TYPE` can be: - -- 0: stdin (will be written on stdout) -- 1: stdout -- 2: stderr - - `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of - the uint32 size encoded as big endian. - - **PAYLOAD** - - The payload is the raw stream. - - **IMPLEMENTATION** - - The simplest way to implement the Attach protocol is the following: - - 1. Read 8 bytes - 2. chose stdout or stderr depending on the first byte - 3. Extract the frame size from the last 4 bytes - 4. Read the extracted size and output it on the correct output - 5. Goto 1 - -### Attach to a container (websocket) - -`GET /containers/(id or name)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **logs** – 1/True/true or 0/False/false, return logs. Default false -- **stream** – 1/True/true or 0/False/false, return stream. - Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach - to stdin. Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id or name)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id or name)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **v** – 1/True/true or 0/False/false, Remove the volumes - associated to the container. Default false -- **force** - 1/True/true or 0/False/false, Kill then remove the container. - Default false - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id or name)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/json` - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "RepoTags": [ - "ubuntu:12.04", - "ubuntu:precise", - "ubuntu:latest" - ], - "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", - "Created": 1365714795, - "Size": 131506275, - "VirtualSize": 131506275 - }, - { - "RepoTags": [ - "ubuntu:12.10", - "ubuntu:quantal" - ], - "ParentId": "27cf784147099545", - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Created": 1364102658, - "Size": 24653, - "VirtualSize": 180116135 - } - ] - - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, default false -- **filters** – a json encoded value of the filters (a map[string][]string) to process on the images list. Available filters: - - dangling=true -- **filter** - only return images with the specified name - -### Create an image - -`POST /images/create` - -Create an image, either by pulling it from the registry or by importing it - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pulling..."} - {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} - {"error": "Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -Query Parameters: - -- **fromImage** – name of the image to pull -- **fromSrc** – source to import. The value may be a URL from which the image - can be retrieved or `-` to read the image from the request body. -- **repo** – repository -- **tag** – tag - - Request Headers: - -- **X-Registry-Auth** – base64-encoded AuthConfig object - -Status Codes: - -- **200** – no error -- **500** – server error - - - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/ubuntu/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Created": "2013-03-23T22:24:18.818426-07:00", - "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "ContainerConfig": - { - "Hostname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": false, - "AttachStderr": false, - "PortSpecs": null, - "Tty": true, - "OpenStdin": true, - "StdinOnce": false, - "Env": null, - "Cmd": ["/bin/bash"], - "Dns": null, - "Image": "ubuntu", - "Volumes": null, - "VolumesFrom": "", - "WorkingDir": "" - }, - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Parent": "27cf784147099545", - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/ubuntu/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pushing..."} - {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} - {"error": "Invalid..."} - ... - - If you wish to push an image on to a private registry, that image must already have been tagged - into a repository which references that registry host name and port. This repository name should - then be used in the URL. This mirrors the flow of the CLI. - -**Example request**: - - POST /images/registry.acme.com:5000/test/push HTTP/1.1 - - -Query Parameters: - -- **tag** – the tag to associate with the image on the registry, optional - -Request Headers: - -- **X-Registry-Auth** – include a base64-encoded AuthConfig - object. - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 Created - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Query Parameters: - -- **force** – 1/True/true or 0/False/false, default false -- **noprune** – 1/True/true or 0/False/false, default false - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com). - -> **Note**: -> The response keys have changed from API v1.6 to reflect the JSON -> sent by the registry server to the docker daemon's request. - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "wma55/u1210sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "jdswinbank/sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "vgauthier/sshd", - "star_count": 0 - } - ... - ] - -Query Parameters: - -- **term** – term to search - -Status Codes: - -- **200** – no error -- **500** – server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"stream": "Step 1..."} - {"stream": "..."} - {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - - The archive must include a file called `Dockerfile` - at its root. It may include any number of other files, - which will be accessible in the build context (See the [*ADD build - command*](../../reference/builder.md#dockerbuilder)). - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – git or HTTP/HTTPS URI build source -- **q** – suppress verbose build output -- **nocache** – do not use the cache when building the image -- **rm** - remove intermediate containers after a successful build (default behavior) -- **forcerm** - always remove intermediate containers (includes rm) - - Request Headers: - -- **Content-type** – should be set to `"application/tar"`. -- **X-Registry-Config** – base64-encoded ConfigFile object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers": 11, - "Images": 16, - "Driver": "btrfs", - "ExecutionDriver": "native-0.1", - "KernelVersion": "3.12.0-1-amd64" - "Debug": false, - "NFd": 11, - "NGoroutines": 21, - "NEventsListener": 0, - "InitPath": "/usr/bin/docker", - "IndexServerAddress": ["https://index.docker.io/v1/"], - "MemoryLimit": true, - "SwapLimit": false, - "IPv4Forwarding": true - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "ApiVersion": "1.12", - "Version": "0.2.2", - "GitCommit": "5a2a5cc+CHANGES", - "GoVersion": "go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Ping the docker server - -`GET /_ping` - -Ping the docker server - -**Example request**: - - GET /_ping HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - OK - -Status Codes: - -- **200** - no error -- **500** - server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Hostname": "", - "Domainname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Volumes": { - "/tmp": {} - }, - "WorkingDir": "", - "NetworkDisabled": false, - "ExposedPorts": { - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - {"Id": "596069db4bf5"} - -Json Parameters: - -- **config** - the container's configuration - -Query Parameters: - -- **container** – source container -- **repo** – repository -- **tag** – tag -- **comment** – commit message -- **author** – author (e.g., "John Hannibal Smith - <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get container events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} - {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling -- **until** – timestamp used for polling - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images in a repository - -`GET /images/(name)/get` - -Get a tarball containing all images and metadata for the repository specified -by `name`. - -If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image -(and its parents) are returned. If `name` is an image ID, similarly only that -image (and its parents) are returned, but with the exclusion of the -'repositories' file in the tarball, as there were no image names referenced. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/ubuntu/get - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images. - -`GET /images/get` - -Get a tarball containing all images and metadata for one or more repositories. - -For each value of the `names` parameter: if it is a specific name and tag (e.g. -ubuntu:latest), then only that image (and its parents) are returned; if it is -an image ID, similarly only that image (and its parents) are returned and there -would be no names referenced in the 'repositories' file for this image ID. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/get?names=myname%2Fmyapp%3Alatest&names=busybox - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Load a tarball with a set of images and tags into docker - -`POST /images/load` - -Load a set of images and tags into the docker repository. -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - POST /images/load - - Tarball in body - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **500** – server error - -### Image tarball format - -An image tarball contains one directory per image layer (named using its long ID), -each containing three files: - -1. `VERSION`: currently `1.0` - the file format version -2. `json`: detailed layer information, similar to `docker inspect layer_id` -3. `layer.tar`: A tarfile containing the filesystem changes in this layer - -The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories -for storing attribute changes and deletions. - -If the tarball defines a repository, there will also be a `repositories` file at -the root that contains a list of repository and tag names mapped to layer IDs. - -``` -{"hello-world": - {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} -} -``` - -### Exec Create - -`POST /containers/(id or name)/exec` - -Sets up an exec instance in a running container `id` - -**Example request**: - - POST /containers/e90e34656806/exec HTTP/1.1 - Content-Type: application/json - - { - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "Tty": false, - "Cmd": [ - "date" - ], - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id": "f90e34656806" - } - -Json Parameters: - -- **AttachStdin** - Boolean value, attaches to stdin of the exec command. -- **AttachStdout** - Boolean value, attaches to stdout of the exec command. -- **AttachStderr** - Boolean value, attaches to stderr of the exec command. -- **Tty** - Boolean value to allocate a pseudo-TTY -- **Cmd** - Command to run specified as a string or an array of strings. - - -Status Codes: - -- **201** – no error -- **404** – no such container - -### Exec Start - -`POST /exec/(id)/start` - -Starts a previously set up exec instance `id`. If `detach` is true, this API -returns after starting the `exec` command. Otherwise, this API sets up an -interactive session with the `exec` command. - -**Example request**: - - POST /exec/e90e34656806/start HTTP/1.1 - Content-Type: application/json - - { - "Detach": false, - "Tty": false, - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Json Parameters: - -- **Detach** - Detach from the exec command -- **Tty** - Boolean value to allocate a pseudo-TTY - -Status Codes: - -- **200** – no error -- **404** – no such exec instance - - **Stream details**: - Similar to the stream behavior of `POST /containers/(id or name)/attach` API - -### Exec Resize - -`POST /exec/(id)/resize` - -Resizes the tty session used by the exec command `id`. -This API is valid only if `tty` was specified as part of creating and starting the exec command. - -**Example request**: - - POST /exec/e90e34656806/resize HTTP/1.1 - Content-Type: plain/text - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: plain/text - -Query Parameters: - -- **h** – height of tty session -- **w** – width - -Status Codes: - -- **201** – no error -- **404** – no such exec instance - -# 3. Going further - -## 3.1 Inside `docker run` - -As an example, the `docker run` command line makes the following API calls: - -- Create the container - -- If the status code is 404, it means the image doesn't exist: - - Try to pull it - - Then retry to create the container - -- Start the container - -- If you are not in detached mode: -- Attach to the container, using logs=1 (to have stdout and - stderr from the container's start) and stream=1 - -- If in detached mode or only stdin is attached: -- Display the container's id - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -stdout and stderr on the same socket. This might change in the future. - -## 3.3 CORS Requests - -To enable cross origin requests to the remote api add the flag -"--api-enable-cors" when running docker in daemon mode. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.16.md b/docs/reference/api/docker_remote_api_v1.16.md deleted file mode 100644 index f6e768ce0c..0000000000 --- a/docs/reference/api/docker_remote_api_v1.16.md +++ /dev/null @@ -1,1833 +0,0 @@ - - -# Docker Remote API v1.16 - -## 1. Brief introduction - - - The Remote API has replaced `rcli`. - - The daemon listens on `unix:///var/run/docker.sock` but you can - [Bind Docker to another host/port or a Unix socket](../../quickstart.md#bind-docker-to-another-host-port-or-a-unix-socket). - - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `STDOUT`, - `STDIN` and `STDERR`. - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Names":["/boring_feynman"], - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "9cd87474be90", - "Names":["/coolName"], - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "3176a2479c92", - "Names":["/sleep_dog"], - "Image": "ubuntu:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Names":["/running_cat"], - "Image": "ubuntu:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - } - ] - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by default (i.e., this defaults to false) -- **limit** – Show `limit` last created - containers, include non-running ones. -- **since** – Show only containers created since Id, include - non-running ones. -- **before** – Show only containers created before Id, include - non-running ones. -- **size** – 1/True/true or 0/False/false, Show the containers - sizes -- **filters** - a json encoded value of the filters (a map[string][]string) to process on the containers list. Available filters: - - exited=<int> -- containers with exit code of <int> - - status=(restarting|running|paused|exited) - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname": "", - "Domainname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": [ - "FOO=bar", - "BAZ=quux" - ], - "Cmd": [ - "date" - ], - "Entrypoint": "", - "Image": "ubuntu", - "Volumes": { - "/tmp": {} - }, - "WorkingDir": "", - "NetworkDisabled": false, - "MacAddress": "12:34:56:78:9a:bc", - "ExposedPorts": { - "22/tcp": {} - }, - "SecurityOpt": [], - "HostConfig": { - "Binds": ["/tmp:/tmp"], - "Links": ["redis3:redis"], - "LxcConf": {"lxc.utsname":"docker"}, - "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] }, - "PublishAllPorts": false, - "Privileged": false, - "Dns": ["8.8.8.8"], - "DnsSearch": [""], - "ExtraHosts": null, - "VolumesFrom": ["parent", "other:ro"], - "CapAdd": ["NET_ADMIN"], - "CapDrop": ["MKNOD"], - "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 }, - "NetworkMode": "bridge", - "Devices": [] - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -- **Hostname** - A string value containing the desired hostname to use for the - container. -- **Domainname** - A string value containing the desired domain name to use - for the container. -- **User** - A string value containing the user to use inside the container. -- **Memory** - Memory limit in bytes. -- **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap. -- **CpuShares** - An integer value containing the CPU Shares for container - (ie. the relative weight vs other containers). - **CpuSet** - String value containing the cgroups Cpuset to use. -- **AttachStdin** - Boolean value, attaches to stdin. -- **AttachStdout** - Boolean value, attaches to stdout. -- **AttachStderr** - Boolean value, attaches to stderr. -- **Tty** - Boolean value, Attach standard streams to a tty, including stdin if it is not closed. -- **OpenStdin** - Boolean value, opens stdin, -- **StdinOnce** - Boolean value, close stdin after the 1 attached client disconnects. -- **Env** - A list of environment variables in the form of `["VAR=value"[,"VAR2=value2"]]` -- **Cmd** - Command to run specified as a string or an array of strings. -- **Entrypoint** - Set the entrypoint for the container a string or an array - of strings -- **Image** - String value containing the image name to use for the container -- **Volumes** – An object mapping mountpoint paths (strings) inside the - container to empty objects. -- **WorkingDir** - A string value containing the working dir for commands to - run in. -- **NetworkDisabled** - Boolean value, when true disables networking for the - container -- **ExposedPorts** - An object mapping ports to an empty object in the form of: - `"ExposedPorts": { "/: {}" }` -- **SecurityOpt**: A list of string values to customize labels for MLS - systems, such as SELinux. -- **HostConfig** - - **Binds** – A list of volume bindings for this container. Each volume - binding is a string of the form `container_path` (to create a new - volume for the container), `host_path:container_path` (to bind-mount - a host path into the container), or `host_path:container_path:ro` - (to make the bind-mount read-only inside the container). - - **Links** - A list of links for the container. Each link entry should be - in the form of "container_name:alias". - - **LxcConf** - LXC specific configurations. These configurations will only - work when using the `lxc` execution driver. - - **PortBindings** - A map of exposed container ports and the host port they - should map to. It should be specified in the form - `{ /: [{ "HostPort": "" }] }` - Take note that `port` is specified as a string and not an integer value. - - **PublishAllPorts** - Allocates a random host port for all of a container's - exposed ports. Specified as a boolean value. - - **Privileged** - Gives the container full access to the host. Specified as - a boolean value. - - **Dns** - A list of dns servers for the container to use. - - **DnsSearch** - A list of DNS search domains - - **ExtraHosts** - A list of hostnames/IP mappings to be added to the - container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`. - - **VolumesFrom** - A list of volumes to inherit from another container. - Specified in the form `[:]` - - **CapAdd** - A list of kernel capabilities to add to the container. - - **Capdrop** - A list of kernel capabilities to drop from the container. - - **RestartPolicy** – The behavior to apply when the container exits. The - value is an object with a `Name` property of either `"always"` to - always restart or `"on-failure"` to restart only when the container - exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` - controls the number of times to retry before giving up. - The default is not to restart. (optional) - An ever increasing delay (double the previous delay, starting at 100mS) - is added before each restart to prevent flooding the server. - - **NetworkMode** - Sets the networking mode for the container. Supported - values are: `bridge`, `host`, `none`, and `container:` - - **Devices** - A list of devices to add to the container specified in the - form - `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}` - -Query Parameters: - -- **name** – Assign the specified name to the container. Must - match `/?[a-zA-Z0-9_-]+`. - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id or name)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "ubuntu", - "Volumes": {}, - "VolumesFrom": "", - "WorkingDir": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {}, - "HostConfig": { - "Binds": null, - "ContainerIDFile": "", - "LxcConf": [], - "Privileged": false, - "PortBindings": { - "80/tcp": [ - { - "HostIp": "0.0.0.0", - "HostPort": "49153" - } - ] - }, - "Links": ["/name:alias"], - "PublishAllPorts": false, - "CapAdd": ["NET_ADMIN"], - "CapDrop": ["MKNOD"] - } - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id or name)/top` - -List processes running inside the container `id`. On Unix systems this -is done by running the `ps` command. This endpoint is not -supported on Windows. - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles" : [ - "UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD" - ], - "Processes" : [ - [ - "root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash" - ], - [ - "root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10" - ] - ] - } - -**Example request**: - - GET /containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles" : [ - "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND" - ] - "Processes" : [ - [ - "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash" - ], - [ - "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10" - ] - ], - } - -Query Parameters: - -- **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef` - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Get container logs - -`GET /containers/(id or name)/logs` - -Get stdout and stderr logs from the container ``id`` - -**Example request**: - - GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Query Parameters: - -- **follow** – 1/True/true or 0/False/false, return stream. Default false -- **stdout** – 1/True/true or 0/False/false, show stdout log. Default false -- **stderr** – 1/True/true or 0/False/false, show stderr log. Default false -- **timestamps** – 1/True/true or 0/False/false, print timestamps for - every log line. Default false -- **tail** – Output specified number of lines at the end of logs: `all` or ``. Default all - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id or name)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id or name)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Resize a container TTY - -`POST /containers/(id or name)/resize?h=&w=` - -Resize the TTY for container with `id`. The container must be restarted for the resize to take effect. - -**Example request**: - - POST /containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Length: 0 - Content-Type: text/plain; charset=utf-8 - -Status Codes: - -- **200** – no error -- **404** – No such container -- **500** – Cannot resize container - -### Start a container - -`POST /containers/(id or name)/start` - -Start the container `id` - -> **Note**: -> For backwards compatibility, this endpoint accepts a `HostConfig` as JSON-encoded request body. -> See [create a container](#create-a-container) for details. - -**Example request**: - - POST /containers/e90e34656806/start HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **304** – container already started -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id or name)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **304** – container already stopped -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id or name)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id or name)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters - -- **signal** - Signal to send to the container: integer or string like "SIGINT". - When not set, SIGKILL is assumed and the call will waits for the container to exit. - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Pause a container - -`POST /containers/(id or name)/pause` - -Pause the container `id` - -**Example request**: - - POST /containers/e90e34656806/pause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Unpause a container - -`POST /containers/(id or name)/unpause` - -Unpause the container `id` - -**Example request**: - - POST /containers/e90e34656806/unpause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id or name)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Query Parameters: - -- **logs** – 1/True/true or 0/False/false, return logs. Default false -- **stream** – 1/True/true or 0/False/false, return stream. - Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach - to stdin. Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - - **Stream details**: - - When using the TTY setting is enabled in - [`POST /containers/create` - ](#create-a-container), - the stream is the raw data from the process PTY and client's stdin. - When the TTY is disabled, then the stream is multiplexed to separate - stdout and stderr. - - The format is a **Header** and a **Payload** (frame). - - **HEADER** - - The header will contain the information on which stream write the - stream (stdout or stderr). It also contain the size of the - associated frame encoded on the last 4 bytes (uint32). - - It is encoded on the first 8 bytes like this: - - header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} - - `STREAM_TYPE` can be: - -- 0: stdin (will be written on stdout) -- 1: stdout -- 2: stderr - - `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of - the uint32 size encoded as big endian. - - **PAYLOAD** - - The payload is the raw stream. - - **IMPLEMENTATION** - - The simplest way to implement the Attach protocol is the following: - - 1. Read 8 bytes - 2. chose stdout or stderr depending on the first byte - 3. Extract the frame size from the last 4 bytes - 4. Read the extracted size and output it on the correct output - 5. Goto 1 - -### Attach to a container (websocket) - -`GET /containers/(id or name)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **logs** – 1/True/true or 0/False/false, return logs. Default false -- **stream** – 1/True/true or 0/False/false, return stream. - Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach - to stdin. Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id or name)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id or name)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **v** – 1/True/true or 0/False/false, Remove the volumes - associated to the container. Default false -- **force** - 1/True/true or 0/False/false, Kill then remove the container. - Default false - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id or name)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/json` - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "RepoTags": [ - "ubuntu:12.04", - "ubuntu:precise", - "ubuntu:latest" - ], - "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", - "Created": 1365714795, - "Size": 131506275, - "VirtualSize": 131506275 - }, - { - "RepoTags": [ - "ubuntu:12.10", - "ubuntu:quantal" - ], - "ParentId": "27cf784147099545", - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Created": 1364102658, - "Size": 24653, - "VirtualSize": 180116135 - } - ] - - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, default false -- **filters** – a json encoded value of the filters (a map[string][]string) to process on the images list. Available filters: - - dangling=true -- **filter** - only return images with the specified name - -### Create an image - -`POST /images/create` - -Create an image, either by pulling it from the registry or by importing it - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pulling..."} - {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} - {"error": "Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -Query Parameters: - -- **fromImage** – name of the image to pull -- **fromSrc** – source to import. The value may be a URL from which the image - can be retrieved or `-` to read the image from the request body. -- **repo** – repository -- **tag** – tag - - Request Headers: - -- **X-Registry-Auth** – base64-encoded AuthConfig object - -Status Codes: - -- **200** – no error -- **500** – server error - - - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/ubuntu/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Created": "2013-03-23T22:24:18.818426-07:00", - "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "ContainerConfig": - { - "Hostname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": false, - "AttachStderr": false, - "PortSpecs": null, - "Tty": true, - "OpenStdin": true, - "StdinOnce": false, - "Env": null, - "Cmd": ["/bin/bash"], - "Dns": null, - "Image": "ubuntu", - "Volumes": null, - "VolumesFrom": "", - "WorkingDir": "" - }, - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Parent": "27cf784147099545", - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/ubuntu/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pushing..."} - {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} - {"error": "Invalid..."} - ... - - If you wish to push an image on to a private registry, that image must already have been tagged - into a repository which references that registry host name and port. This repository name should - then be used in the URL. This mirrors the flow of the CLI. - -**Example request**: - - POST /images/registry.acme.com:5000/test/push HTTP/1.1 - - -Query Parameters: - -- **tag** – the tag to associate with the image on the registry, optional - -Request Headers: - -- **X-Registry-Auth** – include a base64-encoded AuthConfig - object. - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 Created - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Query Parameters: - -- **force** – 1/True/true or 0/False/false, default false -- **noprune** – 1/True/true or 0/False/false, default false - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com). - -> **Note**: -> The response keys have changed from API v1.6 to reflect the JSON -> sent by the registry server to the docker daemon's request. - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "wma55/u1210sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "jdswinbank/sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "vgauthier/sshd", - "star_count": 0 - } - ... - ] - -Query Parameters: - -- **term** – term to search - -Status Codes: - -- **200** – no error -- **500** – server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"stream": "Step 1..."} - {"stream": "..."} - {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - - The archive must include a file called `Dockerfile` - at its root. It may include any number of other files, - which will be accessible in the build context (See the [*ADD build - command*](../../reference/builder.md#dockerbuilder)). - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – git or HTTP/HTTPS URI build source -- **q** – suppress verbose build output -- **nocache** – do not use the cache when building the image -- **pull** - attempt to pull the image even if an older image exists locally -- **rm** - remove intermediate containers after a successful build (default behavior) -- **forcerm** - always remove intermediate containers (includes rm) - - Request Headers: - -- **Content-type** – should be set to `"application/tar"`. -- **X-Registry-Config** – base64-encoded ConfigFile object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers":11, - "Images":16, - "Driver":"btrfs", - "DriverStatus": [[""]], - "ExecutionDriver":"native-0.1", - "KernelVersion":"3.12.0-1-amd64" - "NCPU":1, - "MemTotal":2099236864, - "Name":"prod-server-42", - "ID":"7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS", - "Debug":false, - "NFd": 11, - "NGoroutines":21, - "NEventsListener":0, - "InitPath":"/usr/bin/docker", - "InitSha1":"", - "IndexServerAddress":["https://index.docker.io/v1/"], - "MemoryLimit":true, - "SwapLimit":false, - "IPv4Forwarding":true, - "Labels":["storage=ssd"], - "DockerRootDir": "/var/lib/docker", - "OperatingSystem": "Boot2Docker", - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "ApiVersion": "1.12", - "Version": "0.2.2", - "GitCommit": "5a2a5cc+CHANGES", - "GoVersion": "go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Ping the docker server - -`GET /_ping` - -Ping the docker server - -**Example request**: - - GET /_ping HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - OK - -Status Codes: - -- **200** - no error -- **500** - server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Hostname": "", - "Domainname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Volumes": { - "/tmp": {} - }, - "WorkingDir": "", - "NetworkDisabled": false, - "ExposedPorts": { - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - {"Id": "596069db4bf5"} - -Json Parameters: - -- **config** - the container's configuration - -Query Parameters: - -- **container** – source container -- **repo** – repository -- **tag** – tag -- **comment** – commit message -- **author** – author (e.g., "John Hannibal Smith - <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get container events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} - {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling -- **until** – timestamp used for polling -- **filters** – a json encoded value of the filters (a map[string][]string) to process on the event list. Available filters: - - event=<string> -- event to filter - - image=<string> -- image to filter - - container=<string> -- container to filter - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images in a repository - -`GET /images/(name)/get` - -Get a tarball containing all images and metadata for the repository specified -by `name`. - -If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image -(and its parents) are returned. If `name` is an image ID, similarly only that -image (and its parents) are returned, but with the exclusion of the -'repositories' file in the tarball, as there were no image names referenced. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/ubuntu/get - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images. - -`GET /images/get` - -Get a tarball containing all images and metadata for one or more repositories. - -For each value of the `names` parameter: if it is a specific name and tag (e.g. -ubuntu:latest), then only that image (and its parents) are returned; if it is -an image ID, similarly only that image (and its parents) are returned and there -would be no names referenced in the 'repositories' file for this image ID. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/get?names=myname%2Fmyapp%3Alatest&names=busybox - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Load a tarball with a set of images and tags into docker - -`POST /images/load` - -Load a set of images and tags into the docker repository. -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - POST /images/load - - Tarball in body - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **500** – server error - -### Image tarball format - -An image tarball contains one directory per image layer (named using its long ID), -each containing three files: - -1. `VERSION`: currently `1.0` - the file format version -2. `json`: detailed layer information, similar to `docker inspect layer_id` -3. `layer.tar`: A tarfile containing the filesystem changes in this layer - -The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories -for storing attribute changes and deletions. - -If the tarball defines a repository, there will also be a `repositories` file at -the root that contains a list of repository and tag names mapped to layer IDs. - -``` -{"hello-world": - {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} -} -``` - -### Exec Create - -`POST /containers/(id or name)/exec` - -Sets up an exec instance in a running container `id` - -**Example request**: - - POST /containers/e90e34656806/exec HTTP/1.1 - Content-Type: application/json - - { - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "Tty": false, - "Cmd": [ - "date" - ], - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id": "f90e34656806" - } - -Json Parameters: - -- **AttachStdin** - Boolean value, attaches to stdin of the exec command. -- **AttachStdout** - Boolean value, attaches to stdout of the exec command. -- **AttachStderr** - Boolean value, attaches to stderr of the exec command. -- **Tty** - Boolean value to allocate a pseudo-TTY -- **Cmd** - Command to run specified as a string or an array of strings. - - -Status Codes: - -- **201** – no error -- **404** – no such container - -### Exec Start - -`POST /exec/(id)/start` - -Starts a previously set up exec instance `id`. If `detach` is true, this API -returns after starting the `exec` command. Otherwise, this API sets up an -interactive session with the `exec` command. - -**Example request**: - - POST /exec/e90e34656806/start HTTP/1.1 - Content-Type: application/json - - { - "Detach": false, - "Tty": false, - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Json Parameters: - -- **Detach** - Detach from the exec command -- **Tty** - Boolean value to allocate a pseudo-TTY - -Status Codes: - -- **200** – no error -- **404** – no such exec instance - - **Stream details**: - Similar to the stream behavior of `POST /containers/(id or name)/attach` API - -### Exec Resize - -`POST /exec/(id)/resize` - -Resizes the tty session used by the exec command `id`. -This API is valid only if `tty` was specified as part of creating and starting the exec command. - -**Example request**: - - POST /exec/e90e34656806/resize HTTP/1.1 - Content-Type: plain/text - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: plain/text - -Query Parameters: - -- **h** – height of tty session -- **w** – width - -Status Codes: - -- **201** – no error -- **404** – no such exec instance - -### Exec Inspect - -`GET /exec/(id)/json` - -Return low-level information about the exec command `id`. - -**Example request**: - - GET /exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: plain/text - - { - "ID" : "11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39", - "Running" : false, - "ExitCode" : 2, - "ProcessConfig" : { - "privileged" : false, - "user" : "", - "tty" : false, - "entrypoint" : "sh", - "arguments" : [ - "-c", - "exit 2" - ] - }, - "OpenStdin" : false, - "OpenStderr" : false, - "OpenStdout" : false, - "Container" : { - "State" : { - "Running" : true, - "Paused" : false, - "Restarting" : false, - "OOMKilled" : false, - "Pid" : 3650, - "ExitCode" : 0, - "Error" : "", - "StartedAt" : "2014-11-17T22:26:03.717657531Z", - "FinishedAt" : "0001-01-01T00:00:00Z" - }, - "ID" : "8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c", - "Created" : "2014-11-17T22:26:03.626304998Z", - "Path" : "date", - "Args" : [], - "Config" : { - "Hostname" : "8f177a186b97", - "Domainname" : "", - "User" : "", - "Memory" : 0, - "MemorySwap" : 0, - "CpuShares" : 0, - "Cpuset" : "", - "AttachStdin" : false, - "AttachStdout" : false, - "AttachStderr" : false, - "PortSpecs" : null, - "ExposedPorts" : null, - "Tty" : false, - "OpenStdin" : false, - "StdinOnce" : false, - "Env" : [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ], - "Cmd" : [ - "date" - ], - "Image" : "ubuntu", - "Volumes" : null, - "WorkingDir" : "", - "Entrypoint" : null, - "NetworkDisabled" : false, - "MacAddress" : "", - "OnBuild" : null, - "SecurityOpt" : null - }, - "Image" : "5506de2b643be1e6febbf3b8a240760c6843244c41e12aa2f60ccbb7153d17f5", - "NetworkSettings" : { - "IPAddress" : "172.17.0.2", - "IPPrefixLen" : 16, - "MacAddress" : "02:42:ac:11:00:02", - "Gateway" : "172.17.42.1", - "Bridge" : "docker0", - "PortMapping" : null, - "Ports" : {} - }, - "ResolvConfPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/resolv.conf", - "HostnamePath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hostname", - "HostsPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hosts", - "Name" : "/test", - "Driver" : "aufs", - "ExecDriver" : "native-0.2", - "MountLabel" : "", - "ProcessLabel" : "", - "AppArmorProfile" : "", - "RestartCount" : 0, - "Volumes" : {}, - "VolumesRW" : {} - } - } - -Status Codes: - -- **200** – no error -- **404** – no such exec instance -- **500** - server error - -# 3. Going further - -## 3.1 Inside `docker run` - -As an example, the `docker run` command line makes the following API calls: - -- Create the container - -- If the status code is 404, it means the image doesn't exist: - - Try to pull it - - Then retry to create the container - -- Start the container - -- If you are not in detached mode: -- Attach to the container, using logs=1 (to have stdout and - stderr from the container's start) and stream=1 - -- If in detached mode or only stdin is attached: -- Display the container's id - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -stdout and stderr on the same socket. This might change in the future. - -## 3.3 CORS Requests - -To enable cross origin requests to the remote api add the flag -"--api-enable-cors" when running docker in daemon mode. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.17.md b/docs/reference/api/docker_remote_api_v1.17.md deleted file mode 100644 index 147b05f89f..0000000000 --- a/docs/reference/api/docker_remote_api_v1.17.md +++ /dev/null @@ -1,2007 +0,0 @@ - - -# Docker Remote API v1.17 - -## 1. Brief introduction - - - The Remote API has replaced `rcli`. - - The daemon listens on `unix:///var/run/docker.sock` but you can - [Bind Docker to another host/port or a Unix socket](../../quickstart.md#bind-docker-to-another-host-port-or-a-unix-socket). - - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `STDOUT`, - `STDIN` and `STDERR`. - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Names":["/boring_feynman"], - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "9cd87474be90", - "Names":["/coolName"], - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "3176a2479c92", - "Names":["/sleepy_dog"], - "Image": "ubuntu:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Names":["/running_cat"], - "Image": "ubuntu:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - } - ] - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by default (i.e., this defaults to false) -- **limit** – Show `limit` last created - containers, include non-running ones. -- **since** – Show only containers created since Id, include - non-running ones. -- **before** – Show only containers created before Id, include - non-running ones. -- **size** – 1/True/true or 0/False/false, Show the containers - sizes -- **filters** - a json encoded value of the filters (a map[string][]string) to process on the containers list. Available filters: - - exited=<int> -- containers with exit code of <int> - - status=(restarting|running|paused|exited) - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname": "", - "Domainname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": [ - "FOO=bar", - "BAZ=quux" - ], - "Cmd": [ - "date" - ], - "Entrypoint": "", - "Image": "ubuntu", - "Volumes": { - "/tmp": {} - }, - "WorkingDir": "", - "NetworkDisabled": false, - "MacAddress": "12:34:56:78:9a:bc", - "ExposedPorts": { - "22/tcp": {} - }, - "HostConfig": { - "Binds": ["/tmp:/tmp"], - "Links": ["redis3:redis"], - "LxcConf": {"lxc.utsname":"docker"}, - "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] }, - "PublishAllPorts": false, - "Privileged": false, - "ReadonlyRootfs": false, - "Dns": ["8.8.8.8"], - "DnsSearch": [""], - "ExtraHosts": null, - "VolumesFrom": ["parent", "other:ro"], - "CapAdd": ["NET_ADMIN"], - "CapDrop": ["MKNOD"], - "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 }, - "NetworkMode": "bridge", - "Devices": [], - "SecurityOpt": [] - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806", - "Warnings":[] - } - -Json Parameters: - -- **Hostname** - A string value containing the desired hostname to use for the - container. -- **Domainname** - A string value containing the desired domain name to use - for the container. -- **User** - A string value containing the user to use inside the container. -- **Memory** - Memory limit in bytes. -- **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap. - You must use this with `memory` and make the swap value larger than `memory`. -- **CpuShares** - An integer value containing the CPU Shares for container - (ie. the relative weight vs other containers). - **CpuSet** - String value containing the cgroups Cpuset to use. -- **AttachStdin** - Boolean value, attaches to stdin. -- **AttachStdout** - Boolean value, attaches to stdout. -- **AttachStderr** - Boolean value, attaches to stderr. -- **Tty** - Boolean value, Attach standard streams to a tty, including stdin if it is not closed. -- **OpenStdin** - Boolean value, opens stdin, -- **StdinOnce** - Boolean value, close stdin after the 1 attached client disconnects. -- **Env** - A list of environment variables in the form of `["VAR=value"[,"VAR2=value2"]]` -- **Cmd** - Command to run specified as a string or an array of strings. -- **Entrypoint** - Set the entrypoint for the container a string or an array - of strings -- **Image** - String value containing the image name to use for the container -- **Volumes** – An object mapping mountpoint paths (strings) inside the - container to empty objects. -- **WorkingDir** - A string value containing the working dir for commands to - run in. -- **NetworkDisabled** - Boolean value, when true disables networking for the - container -- **ExposedPorts** - An object mapping ports to an empty object in the form of: - `"ExposedPorts": { "/: {}" }` -- **HostConfig** - - **Binds** – A list of volume bindings for this container. Each volume - binding is a string of the form `container_path` (to create a new - volume for the container), `host_path:container_path` (to bind-mount - a host path into the container), or `host_path:container_path:ro` - (to make the bind-mount read-only inside the container). - - **Links** - A list of links for the container. Each link entry should be - in the form of "container_name:alias". - - **LxcConf** - LXC specific configurations. These configurations will only - work when using the `lxc` execution driver. - - **PortBindings** - A map of exposed container ports and the host port they - should map to. It should be specified in the form - `{ /: [{ "HostPort": "" }] }` - Take note that `port` is specified as a string and not an integer value. - - **PublishAllPorts** - Allocates a random host port for all of a container's - exposed ports. Specified as a boolean value. - - **Privileged** - Gives the container full access to the host. Specified as - a boolean value. - - **ReadonlyRootfs** - Mount the container's root filesystem as read only. - Specified as a boolean value. - - **Dns** - A list of dns servers for the container to use. - - **DnsSearch** - A list of DNS search domains - - **ExtraHosts** - A list of hostnames/IP mappings to be added to the - container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`. - - **VolumesFrom** - A list of volumes to inherit from another container. - Specified in the form `[:]` - - **CapAdd** - A list of kernel capabilities to add to the container. - - **Capdrop** - A list of kernel capabilities to drop from the container. - - **RestartPolicy** – The behavior to apply when the container exits. The - value is an object with a `Name` property of either `"always"` to - always restart or `"on-failure"` to restart only when the container - exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` - controls the number of times to retry before giving up. - The default is not to restart. (optional) - An ever increasing delay (double the previous delay, starting at 100mS) - is added before each restart to prevent flooding the server. - - **NetworkMode** - Sets the networking mode for the container. Supported - values are: `bridge`, `host`, `none`, and `container:` - - **Devices** - A list of devices to add to the container specified in the - form - `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}` - - **SecurityOpt**: A list of string values to customize labels for MLS - systems, such as SELinux. - -Query Parameters: - -- **name** – Assign the specified name to the container. Must - match `/?[a-zA-Z0-9_-]+`. - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id or name)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "AppArmorProfile": "", - "Args": [ - "-c", - "exit 9" - ], - "Config": { - "AttachStderr": true, - "AttachStdin": false, - "AttachStdout": true, - "Cmd": [ - "/bin/sh", - "-c", - "exit 9" - ], - "CpuShares": 0, - "Cpuset": "", - "Domainname": "", - "Entrypoint": null, - "Env": [ - "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" - ], - "ExposedPorts": null, - "Hostname": "ba033ac44011", - "Image": "ubuntu", - "MacAddress": "", - "Memory": 0, - "MemorySwap": 0, - "NetworkDisabled": false, - "OnBuild": null, - "OpenStdin": false, - "PortSpecs": null, - "StdinOnce": false, - "Tty": false, - "User": "", - "Volumes": null, - "WorkingDir": "" - }, - "Created": "2015-01-06T15:47:31.485331387Z", - "Driver": "devicemapper", - "ExecDriver": "native-0.2", - "ExecIDs": null, - "HostConfig": { - "Binds": null, - "CapAdd": null, - "CapDrop": null, - "ContainerIDFile": "", - "Devices": [], - "Dns": null, - "DnsSearch": null, - "ExtraHosts": null, - "IpcMode": "", - "Links": null, - "LxcConf": [], - "NetworkMode": "bridge", - "PortBindings": {}, - "Privileged": false, - "ReadonlyRootfs": false, - "PublishAllPorts": false, - "RestartPolicy": { - "MaximumRetryCount": 2, - "Name": "on-failure" - }, - "SecurityOpt": null, - "VolumesFrom": null - }, - "HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname", - "HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts", - "Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39", - "Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2", - "MountLabel": "", - "Name": "/boring_euclid", - "NetworkSettings": { - "Bridge": "", - "Gateway": "", - "IPAddress": "", - "IPPrefixLen": 0, - "MacAddress": "", - "PortMapping": null, - "Ports": null - }, - "Path": "/bin/sh", - "ProcessLabel": "", - "ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf", - "RestartCount": 1, - "State": { - "Error": "", - "ExitCode": 9, - "FinishedAt": "2015-01-06T15:47:32.080254511Z", - "OOMKilled": false, - "Paused": false, - "Pid": 0, - "Restarting": false, - "Running": false, - "StartedAt": "2015-01-06T15:47:32.072697474Z" - }, - "Volumes": {}, - "VolumesRW": {} - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id or name)/top` - -List processes running inside the container `id`. On Unix systems this -is done by running the `ps` command. This endpoint is not -supported on Windows. - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles" : [ - "UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD" - ], - "Processes" : [ - [ - "root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash" - ], - [ - "root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10" - ] - ] - } - -**Example request**: - - GET /containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles" : [ - "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND" - ] - "Processes" : [ - [ - "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash" - ], - [ - "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10" - ] - ], - } - -Query Parameters: - -- **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef` - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Get container logs - -`GET /containers/(id or name)/logs` - -Get stdout and stderr logs from the container ``id`` - -**Example request**: - - GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10 HTTP/1.1 - -**Example response**: - - HTTP/1.1 101 UPGRADED - Content-Type: application/vnd.docker.raw-stream - Connection: Upgrade - Upgrade: tcp - - {{ STREAM }} - -Query Parameters: - -- **follow** – 1/True/true or 0/False/false, return stream. Default false -- **stdout** – 1/True/true or 0/False/false, show stdout log. Default false -- **stderr** – 1/True/true or 0/False/false, show stderr log. Default false -- **timestamps** – 1/True/true or 0/False/false, print timestamps for - every log line. Default false -- **tail** – Output specified number of lines at the end of logs: `all` or ``. Default all - -Status Codes: - -- **101** – no error, hints proxy about hijacking -- **200** – no error, no upgrade header found -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id or name)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id or name)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Get container stats based on resource usage - -`GET /containers/(id or name)/stats` - -This endpoint returns a live stream of a container's resource usage statistics. - -**Example request**: - - GET /containers/redis1/stats HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "read" : "2015-01-08T22:57:31.547920715Z", - "network" : { - "rx_dropped" : 0, - "rx_bytes" : 648, - "rx_errors" : 0, - "tx_packets" : 8, - "tx_dropped" : 0, - "rx_packets" : 8, - "tx_errors" : 0, - "tx_bytes" : 648 - }, - "memory_stats" : { - "stats" : { - "total_pgmajfault" : 0, - "cache" : 0, - "mapped_file" : 0, - "total_inactive_file" : 0, - "pgpgout" : 414, - "rss" : 6537216, - "total_mapped_file" : 0, - "writeback" : 0, - "unevictable" : 0, - "pgpgin" : 477, - "total_unevictable" : 0, - "pgmajfault" : 0, - "total_rss" : 6537216, - "total_rss_huge" : 6291456, - "total_writeback" : 0, - "total_inactive_anon" : 0, - "rss_huge" : 6291456, - "hierarchical_memory_limit" : 67108864, - "total_pgfault" : 964, - "total_active_file" : 0, - "active_anon" : 6537216, - "total_active_anon" : 6537216, - "total_pgpgout" : 414, - "total_cache" : 0, - "inactive_anon" : 0, - "active_file" : 0, - "pgfault" : 964, - "inactive_file" : 0, - "total_pgpgin" : 477 - }, - "max_usage" : 6651904, - "usage" : 6537216, - "failcnt" : 0, - "limit" : 67108864 - }, - "blkio_stats" : {}, - "cpu_stats" : { - "cpu_usage" : { - "percpu_usage" : [ - 16970827, - 1839451, - 7107380, - 10571290 - ], - "usage_in_usermode" : 10000000, - "total_usage" : 36488948, - "usage_in_kernelmode" : 20000000 - }, - "system_cpu_usage" : 20091722000000000, - "throttling_data" : {} - } - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Resize a container TTY - -`POST /containers/(id or name)/resize?h=&w=` - -Resize the TTY for container with `id`. The container must be restarted for the resize to take effect. - -**Example request**: - - POST /containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Length: 0 - Content-Type: text/plain; charset=utf-8 - -Status Codes: - -- **200** – no error -- **404** – No such container -- **500** – Cannot resize container - -### Start a container - -`POST /containers/(id or name)/start` - -Start the container `id` - -> **Note**: -> For backwards compatibility, this endpoint accepts a `HostConfig` as JSON-encoded request body. -> See [create a container](#create-a-container) for details. - -**Example request**: - - POST /containers/e90e34656806/start HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **304** – container already started -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id or name)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **304** – container already stopped -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id or name)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id or name)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters - -- **signal** - Signal to send to the container: integer or string like "SIGINT". - When not set, SIGKILL is assumed and the call will waits for the container to exit. - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Rename a container - -`POST /containers/(id or name)/rename` - -Rename the container `id` to a `new_name` - -**Example request**: - - POST /containers/e90e34656806/rename?name=new_name HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **name** – new name for the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **409** - conflict name already assigned -- **500** – server error - -### Pause a container - -`POST /containers/(id or name)/pause` - -Pause the container `id` - -**Example request**: - - POST /containers/e90e34656806/pause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Unpause a container - -`POST /containers/(id or name)/unpause` - -Unpause the container `id` - -**Example request**: - - POST /containers/e90e34656806/unpause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id or name)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 101 UPGRADED - Content-Type: application/vnd.docker.raw-stream - Connection: Upgrade - Upgrade: tcp - - {{ STREAM }} - -Query Parameters: - -- **logs** – 1/True/true or 0/False/false, return logs. Default false -- **stream** – 1/True/true or 0/False/false, return stream. - Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach - to stdin. Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **101** – no error, hints proxy about hijacking -- **200** – no error, no upgrade header found -- **400** – bad parameter -- **404** – no such container -- **500** – server error - - **Stream details**: - - When using the TTY setting is enabled in - [`POST /containers/create` - ](#create-a-container), - the stream is the raw data from the process PTY and client's stdin. - When the TTY is disabled, then the stream is multiplexed to separate - stdout and stderr. - - The format is a **Header** and a **Payload** (frame). - - **HEADER** - - The header will contain the information on which stream write the - stream (stdout or stderr). It also contain the size of the - associated frame encoded on the last 4 bytes (uint32). - - It is encoded on the first 8 bytes like this: - - header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} - - `STREAM_TYPE` can be: - -- 0: stdin (will be written on stdout) -- 1: stdout -- 2: stderr - - `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of - the uint32 size encoded as big endian. - - **PAYLOAD** - - The payload is the raw stream. - - **IMPLEMENTATION** - - The simplest way to implement the Attach protocol is the following: - - 1. Read 8 bytes - 2. chose stdout or stderr depending on the first byte - 3. Extract the frame size from the last 4 bytes - 4. Read the extracted size and output it on the correct output - 5. Goto 1 - -### Attach to a container (websocket) - -`GET /containers/(id or name)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **logs** – 1/True/true or 0/False/false, return logs. Default false -- **stream** – 1/True/true or 0/False/false, return stream. - Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach - to stdin. Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id or name)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id or name)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **v** – 1/True/true or 0/False/false, Remove the volumes - associated to the container. Default false -- **force** - 1/True/true or 0/False/false, Kill then remove the container. - Default false - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id or name)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/json` - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "RepoTags": [ - "ubuntu:12.04", - "ubuntu:precise", - "ubuntu:latest" - ], - "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", - "Created": 1365714795, - "Size": 131506275, - "VirtualSize": 131506275 - }, - { - "RepoTags": [ - "ubuntu:12.10", - "ubuntu:quantal" - ], - "ParentId": "27cf784147099545", - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Created": 1364102658, - "Size": 24653, - "VirtualSize": 180116135 - } - ] - - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, default false -- **filters** – a json encoded value of the filters (a map[string][]string) to process on the images list. Available filters: - - dangling=true -- **filter** - only return images with the specified name - -### Build image from a Dockerfile - -`POST /build` - -Build an image from a Dockerfile - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"stream": "Step 1..."} - {"stream": "..."} - {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} - -The input stream must be a tar archive compressed with one of the -following algorithms: identity (no compression), gzip, bzip2, xz. - -The archive must include a build instructions file, typically called -`Dockerfile` at the root of the archive. The `dockerfile` parameter may be -used to specify a different build instructions file by having its value be -the path to the alternate build instructions file to use. - -The archive may include any number of other files, -which will be accessible in the build context (See the [*ADD build -command*](../../reference/builder.md#dockerbuilder)). - -Query Parameters: - -- **dockerfile** - path within the build context to the Dockerfile -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – git or HTTP/HTTPS URI build source -- **q** – suppress verbose build output -- **nocache** – do not use the cache when building the image -- **pull** - attempt to pull the image even if an older image exists locally -- **rm** - remove intermediate containers after a successful build (default behavior) -- **forcerm** - always remove intermediate containers (includes rm) - - Request Headers: - -- **Content-type** – should be set to `"application/tar"`. -- **X-Registry-Config** – base64-encoded ConfigFile object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Create an image - -`POST /images/create` - -Create an image, either by pulling it from the registry or by importing it - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pulling..."} - {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} - {"error": "Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -Query Parameters: - -- **fromImage** – name of the image to pull -- **fromSrc** – source to import. The value may be a URL from which the image - can be retrieved or `-` to read the image from the request body. -- **repo** – repository -- **tag** – tag - - Request Headers: - -- **X-Registry-Auth** – base64-encoded AuthConfig object - -Status Codes: - -- **200** – no error -- **500** – server error - - - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/ubuntu/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Created": "2013-03-23T22:24:18.818426-07:00", - "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "ContainerConfig": - { - "Hostname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": false, - "AttachStderr": false, - "PortSpecs": null, - "Tty": true, - "OpenStdin": true, - "StdinOnce": false, - "Env": null, - "Cmd": ["/bin/bash"], - "Dns": null, - "Image": "ubuntu", - "Volumes": null, - "VolumesFrom": "", - "WorkingDir": "" - }, - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Parent": "27cf784147099545", - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/ubuntu/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pushing..."} - {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} - {"error": "Invalid..."} - ... - - If you wish to push an image on to a private registry, that image must already have been tagged - into a repository which references that registry host name and port. This repository name should - then be used in the URL. This mirrors the flow of the CLI. - -**Example request**: - - POST /images/registry.acme.com:5000/test/push HTTP/1.1 - - -Query Parameters: - -- **tag** – the tag to associate with the image on the registry, optional - -Request Headers: - -- **X-Registry-Auth** – include a base64-encoded AuthConfig - object. - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 Created - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Query Parameters: - -- **force** – 1/True/true or 0/False/false, default false -- **noprune** – 1/True/true or 0/False/false, default false - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com). - -> **Note**: -> The response keys have changed from API v1.6 to reflect the JSON -> sent by the registry server to the docker daemon's request. - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "wma55/u1210sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "jdswinbank/sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "vgauthier/sshd", - "star_count": 0 - } - ... - ] - -Query Parameters: - -- **term** – term to search - -Status Codes: - -- **200** – no error -- **500** – server error - -## 2.3 Misc - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers":11, - "Images":16, - "Driver":"btrfs", - "DriverStatus": [[""]], - "ExecutionDriver":"native-0.1", - "KernelVersion":"3.12.0-1-amd64" - "NCPU":1, - "MemTotal":2099236864, - "Name":"prod-server-42", - "ID":"7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS", - "Debug":false, - "NFd": 11, - "NGoroutines":21, - "NEventsListener":0, - "InitPath":"/usr/bin/docker", - "InitSha1":"", - "IndexServerAddress":["https://index.docker.io/v1/"], - "MemoryLimit":true, - "SwapLimit":false, - "IPv4Forwarding":true, - "Labels":["storage=ssd"], - "DockerRootDir": "/var/lib/docker", - "OperatingSystem": "Boot2Docker", - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "ApiVersion": "1.12", - "Version": "0.2.2", - "GitCommit": "5a2a5cc+CHANGES", - "GoVersion": "go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Ping the docker server - -`GET /_ping` - -Ping the docker server - -**Example request**: - - GET /_ping HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - OK - -Status Codes: - -- **200** - no error -- **500** - server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Hostname": "", - "Domainname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Volumes": { - "/tmp": {} - }, - "WorkingDir": "", - "NetworkDisabled": false, - "ExposedPorts": { - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - {"Id": "596069db4bf5"} - -Json Parameters: - -- **config** - the container's configuration - -Query Parameters: - -- **container** – source container -- **repo** – repository -- **tag** – tag -- **comment** – commit message -- **author** – author (e.g., "John Hannibal Smith - <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get container events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, exec_create, exec_start, export, kill, oom, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} - {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling -- **until** – timestamp used for polling -- **filters** – a json encoded value of the filters (a map[string][]string) to process on the event list. Available filters: - - event=<string> -- event to filter - - image=<string> -- image to filter - - container=<string> -- container to filter - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images in a repository - -`GET /images/(name)/get` - -Get a tarball containing all images and metadata for the repository specified -by `name`. - -If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image -(and its parents) are returned. If `name` is an image ID, similarly only that -image (and its parents) are returned, but with the exclusion of the -'repositories' file in the tarball, as there were no image names referenced. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/ubuntu/get - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images. - -`GET /images/get` - -Get a tarball containing all images and metadata for one or more repositories. - -For each value of the `names` parameter: if it is a specific name and tag (e.g. -ubuntu:latest), then only that image (and its parents) are returned; if it is -an image ID, similarly only that image (and its parents) are returned and there -would be no names referenced in the 'repositories' file for this image ID. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/get?names=myname%2Fmyapp%3Alatest&names=busybox - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Load a tarball with a set of images and tags into docker - -`POST /images/load` - -Load a set of images and tags into the docker repository. -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - POST /images/load - - Tarball in body - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **500** – server error - -### Image tarball format - -An image tarball contains one directory per image layer (named using its long ID), -each containing three files: - -1. `VERSION`: currently `1.0` - the file format version -2. `json`: detailed layer information, similar to `docker inspect layer_id` -3. `layer.tar`: A tarfile containing the filesystem changes in this layer - -The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories -for storing attribute changes and deletions. - -If the tarball defines a repository, there will also be a `repositories` file at -the root that contains a list of repository and tag names mapped to layer IDs. - -``` -{"hello-world": - {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} -} -``` - -### Exec Create - -`POST /containers/(id or name)/exec` - -Sets up an exec instance in a running container `id` - -**Example request**: - - POST /containers/e90e34656806/exec HTTP/1.1 - Content-Type: application/json - - { - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "Tty": false, - "Cmd": [ - "date" - ], - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id": "f90e34656806" - } - -Json Parameters: - -- **AttachStdin** - Boolean value, attaches to stdin of the exec command. -- **AttachStdout** - Boolean value, attaches to stdout of the exec command. -- **AttachStderr** - Boolean value, attaches to stderr of the exec command. -- **Tty** - Boolean value to allocate a pseudo-TTY -- **Cmd** - Command to run specified as a string or an array of strings. - - -Status Codes: - -- **201** – no error -- **404** – no such container - -### Exec Start - -`POST /exec/(id)/start` - -Starts a previously set up exec instance `id`. If `detach` is true, this API -returns after starting the `exec` command. Otherwise, this API sets up an -interactive session with the `exec` command. - -**Example request**: - - POST /exec/e90e34656806/start HTTP/1.1 - Content-Type: application/json - - { - "Detach": false, - "Tty": false, - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Json Parameters: - -- **Detach** - Detach from the exec command -- **Tty** - Boolean value to allocate a pseudo-TTY - -Status Codes: - -- **200** – no error -- **404** – no such exec instance - - **Stream details**: - Similar to the stream behavior of `POST /containers/(id or name)/attach` API - -### Exec Resize - -`POST /exec/(id)/resize` - -Resizes the tty session used by the exec command `id`. -This API is valid only if `tty` was specified as part of creating and starting the exec command. - -**Example request**: - - POST /exec/e90e34656806/resize HTTP/1.1 - Content-Type: text/plain - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: text/plain - -Query Parameters: - -- **h** – height of tty session -- **w** – width - -Status Codes: - -- **201** – no error -- **404** – no such exec instance - -### Exec Inspect - -`GET /exec/(id)/json` - -Return low-level information about the exec command `id`. - -**Example request**: - - GET /exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: plain/text - - { - "ID" : "11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39", - "Running" : false, - "ExitCode" : 2, - "ProcessConfig" : { - "privileged" : false, - "user" : "", - "tty" : false, - "entrypoint" : "sh", - "arguments" : [ - "-c", - "exit 2" - ] - }, - "OpenStdin" : false, - "OpenStderr" : false, - "OpenStdout" : false, - "Container" : { - "State" : { - "Running" : true, - "Paused" : false, - "Restarting" : false, - "OOMKilled" : false, - "Pid" : 3650, - "ExitCode" : 0, - "Error" : "", - "StartedAt" : "2014-11-17T22:26:03.717657531Z", - "FinishedAt" : "0001-01-01T00:00:00Z" - }, - "ID" : "8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c", - "Created" : "2014-11-17T22:26:03.626304998Z", - "Path" : "date", - "Args" : [], - "Config" : { - "Hostname" : "8f177a186b97", - "Domainname" : "", - "User" : "", - "Memory" : 0, - "MemorySwap" : 0, - "CpuShares" : 0, - "Cpuset" : "", - "AttachStdin" : false, - "AttachStdout" : false, - "AttachStderr" : false, - "PortSpecs" : null, - "ExposedPorts" : null, - "Tty" : false, - "OpenStdin" : false, - "StdinOnce" : false, - "Env" : [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ], - "Cmd" : [ - "date" - ], - "Image" : "ubuntu", - "Volumes" : null, - "WorkingDir" : "", - "Entrypoint" : null, - "NetworkDisabled" : false, - "MacAddress" : "", - "OnBuild" : null, - "SecurityOpt" : null - }, - "Image" : "5506de2b643be1e6febbf3b8a240760c6843244c41e12aa2f60ccbb7153d17f5", - "NetworkSettings" : { - "IPAddress" : "172.17.0.2", - "IPPrefixLen" : 16, - "MacAddress" : "02:42:ac:11:00:02", - "Gateway" : "172.17.42.1", - "Bridge" : "docker0", - "PortMapping" : null, - "Ports" : {} - }, - "ResolvConfPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/resolv.conf", - "HostnamePath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hostname", - "HostsPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hosts", - "Name" : "/test", - "Driver" : "aufs", - "ExecDriver" : "native-0.2", - "MountLabel" : "", - "ProcessLabel" : "", - "AppArmorProfile" : "", - "RestartCount" : 0, - "Volumes" : {}, - "VolumesRW" : {} - } - } - -Status Codes: - -- **200** – no error -- **404** – no such exec instance -- **500** - server error - -# 3. Going further - -## 3.1 Inside `docker run` - -As an example, the `docker run` command line makes the following API calls: - -- Create the container - -- If the status code is 404, it means the image doesn't exist: - - Try to pull it - - Then retry to create the container - -- Start the container - -- If you are not in detached mode: -- Attach to the container, using logs=1 (to have stdout and - stderr from the container's start) and stream=1 - -- If in detached mode or only stdin is attached: -- Display the container's id - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -stdout and stderr on the same socket. - -To hint potential proxies about connection hijacking, Docker client sends -connection upgrade headers similarly to websocket. - - Upgrade: tcp - Connection: Upgrade - -When Docker daemon detects the `Upgrade` header, it will switch its status code -from **200 OK** to **101 UPGRADED** and resend the same headers. - -This might change in the future. - -## 3.3 CORS Requests - -To set cross origin requests to the remote api, please add flag "--api-enable-cors" -when running docker in daemon mode. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors