diff --git a/docs/reference/api/docker_remote_api_v1.24.md b/docs/reference/api/docker_remote_api_v1.24.md index 0c93778f3b..f5b3ae208c 100644 --- a/docs/reference/api/docker_remote_api_v1.24.md +++ b/docs/reference/api/docker_remote_api_v1.24.md @@ -11,7 +11,7 @@ weight=-5 # Docker Remote API v1.24 -## 1. Brief introduction +# 1. Brief introduction - The Remote API has replaced `rcli`. - The daemon listens on `unix:///var/run/docker.sock` but you can @@ -212,7 +212,7 @@ List containers } ] -Query Parameters: +**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) @@ -235,7 +235,7 @@ Query Parameters: - `volume`=(`` or ``) - `network`=(`` or ``) -Status Codes: +**Status codes:** - **200** – no error - **400** – bad parameter @@ -357,7 +357,7 @@ Create a container "Warnings":[] } -Json Parameters: +**JSON parameters:** - **Hostname** - A string value containing the hostname to use for the container. @@ -473,12 +473,12 @@ Json Parameters: - **VolumeDriver** - Driver that this container users to mount volumes. - **ShmSize** - Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB. -Query Parameters: +**Query parameters:** - **name** – Assign the specified name to the container. Must match `/?[a-zA-Z0-9_-]+`. -Status Codes: +**Status codes:** - **201** – no error - **400** – bad parameter @@ -683,11 +683,11 @@ Return low-level information on the container `id` .... } -Query Parameters: +**Query parameters:** - **size** – 1/True/true or 0/False/false, return container size information. Default is `false`. -Status Codes: +**Status codes:** - **200** – no error - **404** – no such container @@ -747,11 +747,11 @@ supported on Windows. ], } -Query Parameters: +**Query parameters:** - **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef` -Status Codes: +**Status codes:** - **200** – no error - **404** – no such container @@ -779,7 +779,7 @@ Get `stdout` and `stderr` logs from the container ``id`` {{ STREAM }} -Query Parameters: +**Query parameters:** - **details** - 1/True/true or 0/False/flase, Show extra details provided to logs. Default `false`. - **follow** – 1/True/true or 0/False/false, return stream. Default `false`. @@ -791,7 +791,7 @@ Query Parameters: every log line. Default `false`. - **tail** – Output specified number of lines at the end of logs: `all` or ``. Default all. -Status Codes: +**Status codes:** - **101** – no error, hints proxy about hijacking - **200** – no error, no upgrade header found @@ -834,7 +834,7 @@ Values for `Kind`: - `1`: Add - `2`: Delete -Status Codes: +**Status codes:** - **200** – no error - **404** – no such container @@ -857,7 +857,7 @@ Export the contents of container `id` {{ TAR STREAM }} -Status Codes: +**Status codes:** - **200** – no error - **404** – no such container @@ -977,11 +977,11 @@ This endpoint returns a live stream of a container's resource usage statistics. The precpu_stats is the cpu statistic of last read, which is used for calculating the cpu usage percent. It is not the exact copy of the “cpu_stats” field. -Query Parameters: +**Query parameters:** - **stream** – 1/True/true or 0/False/false, pull stats once then disconnect. Default `true`. -Status Codes: +**Status codes:** - **200** – no error - **404** – no such container @@ -1003,12 +1003,12 @@ Resize the TTY for container with `id`. The unit is number of characters. You m Content-Length: 0 Content-Type: text/plain; charset=utf-8 -Query Parameters: +**Query parameters:** - **h** – height of `tty` session - **w** – width -Status Codes: +**Status codes:** - **200** – no error - **404** – No such container @@ -1028,13 +1028,13 @@ Start the container `id` HTTP/1.1 204 No Content -Query Parameters: +**Query parameters:** - **detachKeys** – Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-` where `` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. -Status Codes: +**Status codes:** - **204** – no error - **304** – container already started @@ -1055,11 +1055,11 @@ Stop the container `id` HTTP/1.1 204 No Content -Query Parameters: +**Query parameters:** - **t** – number of seconds to wait before killing the container -Status Codes: +**Status codes:** - **204** – no error - **304** – container already stopped @@ -1080,11 +1080,11 @@ Restart the container `id` HTTP/1.1 204 No Content -Query Parameters: +**Query parameters:** - **t** – number of seconds to wait before killing the container -Status Codes: +**Status codes:** - **204** – no error - **404** – no such container @@ -1109,7 +1109,7 @@ Query Parameters - **signal** - Signal to send to the container: integer or string like `SIGINT`. When not set, `SIGKILL` is assumed and the call waits for the container to exit. -Status Codes: +**Status codes:** - **204** – no error - **404** – no such container @@ -1152,7 +1152,7 @@ Update configuration of one or more containers. "Warnings": [] } -Status Codes: +**Status codes:** - **200** – no error - **400** – bad parameter @@ -1173,11 +1173,11 @@ Rename the container `id` to a `new_name` HTTP/1.1 204 No Content -Query Parameters: +**Query parameters:** - **name** – new name for the container -Status Codes: +**Status codes:** - **204** – no error - **404** – no such container @@ -1198,7 +1198,7 @@ Pause the container `id` HTTP/1.1 204 No Content -Status Codes: +**Status codes:** - **204** – no error - **404** – no such container @@ -1218,7 +1218,7 @@ Unpause the container `id` HTTP/1.1 204 No Content -Status Codes: +**Status codes:** - **204** – no error - **404** – no such container @@ -1243,7 +1243,7 @@ Attach to the container `id` {{ STREAM }} -Query Parameters: +**Query parameters:** - **detachKeys** – Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-` @@ -1258,7 +1258,7 @@ Query Parameters: - **stderr** – 1/True/true or 0/False/false, if `logs=true`, return `stderr` log, if `stream=true`, attach to `stderr`. Default `false`. -Status Codes: +**Status codes:** - **101** – no error, hints proxy about hijacking - **200** – no error, no upgrade header found @@ -1326,7 +1326,7 @@ Implements websocket protocol handshake according to [RFC 6455](http://tools.iet {{ STREAM }} -Query Parameters: +**Query parameters:** - **detachKeys** – Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-` @@ -1341,7 +1341,7 @@ Query Parameters: - **stderr** – 1/True/true or 0/False/false, if `logs=true`, return `stderr` log, if `stream=true`, attach to `stderr`. Default `false`. -Status Codes: +**Status codes:** - **200** – no error - **400** – bad parameter @@ -1365,7 +1365,7 @@ Block until container `id` stops, then returns the exit code {"StatusCode": 0} -Status Codes: +**Status codes:** - **200** – no error - **404** – no such container @@ -1385,14 +1385,14 @@ Remove the container `id` from the filesystem HTTP/1.1 204 No Content -Query Parameters: +**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: +**Status codes:** - **204** – no error - **400** – bad parameter @@ -1412,7 +1412,7 @@ following section. Get a tar archive of a resource in the filesystem of container `id`. -Query Parameters: +**Query parameters:** - **path** - resource in the container's filesystem to archive. Required. @@ -1423,39 +1423,41 @@ Query Parameters: indicates that only the contents of the **path** directory should be copied. A symlink is always resolved to its target. - **Note**: It is not possible to copy certain system files such as resources - under `/proc`, `/sys`, `/dev`, and mounts created by the user in the - container. + > **Note**: It is not possible to copy certain system files such as resources + > under `/proc`, `/sys`, `/dev`, and mounts created by the user in the + > container. **Example request**: - GET /containers/8cce319429b2/archive?path=/root HTTP/1.1 + GET /containers/8cce319429b2/archive?path=/root HTTP/1.1 **Example response**: - HTTP/1.1 200 OK - Content-Type: application/x-tar - X-Docker-Container-Path-Stat: eyJuYW1lIjoicm9vdCIsInNpemUiOjQwOTYsIm1vZGUiOjIxNDc0ODQwOTYsIm10aW1lIjoiMjAxNC0wMi0yN1QyMDo1MToyM1oiLCJsaW5rVGFyZ2V0IjoiIn0= + HTTP/1.1 200 OK + Content-Type: application/x-tar + X-Docker-Container-Path-Stat: eyJuYW1lIjoicm9vdCIsInNpemUiOjQwOTYsIm1vZGUiOjIxNDc0ODQwOTYsIm10aW1lIjoiMjAxNC0wMi0yN1QyMDo1MToyM1oiLCJsaW5rVGFyZ2V0IjoiIn0= - {{ TAR STREAM }} + {{ TAR STREAM }} On success, a response header `X-Docker-Container-Path-Stat` will be set to a base64-encoded JSON object containing some filesystem header information about the archived resource. The above example value would decode to the following JSON object (whitespace added for readability): - { - "name": "root", - "size": 4096, - "mode": 2147484096, - "mtime": "2014-02-27T20:51:23Z", - "linkTarget": "" - } +```json +{ + "name": "root", + "size": 4096, + "mode": 2147484096, + "mtime": "2014-02-27T20:51:23Z", + "linkTarget": "" +} +``` A `HEAD` request can also be made to this endpoint if only this information is desired. -Status Codes: +**Status codes:** - **200** - success, returns archive of copied resource - **400** - client error, bad parameter, details in JSON response body, one of: @@ -1474,7 +1476,7 @@ Status Codes: Upload a tar archive to be extracted to a path in the filesystem of container `id`. -Query Parameters: +**Query parameters:** - **path** - path to a directory in the container to extract the archive's contents into. Required. @@ -1496,7 +1498,7 @@ Query Parameters: HTTP/1.1 200 OK -Status Codes: +**Status codes:** - **200** – the content was extracted successfully - **400** - client error, bad parameter, details in JSON response body, one of: @@ -1598,7 +1600,7 @@ digest. You can reference this digest using the value: See the `docker run` and `docker build` commands for examples of digest and tag references on the command line. -Query Parameters: +**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: @@ -1644,7 +1646,7 @@ command*](../../reference/builder.md#dockerbuilder)). The build is canceled if the client drops the connection by quitting or being killed. -Query Parameters: +**Query parameters:** - **dockerfile** - Path within the build context to the Dockerfile. This is ignored if `remote` is specified and points to an individual filename. @@ -1699,7 +1701,7 @@ Query Parameters: be specified with both a "https://" prefix and a "/v1/" suffix even though Docker will prefer to use the v2 registry API. -Status Codes: +**Status codes:** - **200** – no error - **500** – server error @@ -1728,7 +1730,7 @@ 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: +**Query parameters:** - **fromImage** – Name of the image to pull. The name may include a tag or digest. This parameter may only be used when pulling an image. @@ -1762,7 +1764,7 @@ Query Parameters: } ``` -Status Codes: +**Status codes:** - **200** – no error - **500** – server error @@ -1881,7 +1883,7 @@ Return low-level information on the image `name` } } -Status Codes: +**Status codes:** - **200** – no error - **404** – no such image @@ -1935,7 +1937,7 @@ Return the history of the image `name` } ] -Status Codes: +**Status codes:** - **200** – no error - **404** – no such image @@ -1972,7 +1974,7 @@ The push is cancelled if the HTTP connection is closed. POST /images/registry.acme.com:5000/test/push HTTP/1.1 -Query Parameters: +**Query parameters:** - **tag** – The tag to associate with the image on the registry. This is optional. @@ -1997,7 +1999,7 @@ Request Headers: } ``` -Status Codes: +**Status codes:** - **200** – no error - **404** – no such image @@ -2017,12 +2019,12 @@ Tag the image `name` into a repository HTTP/1.1 201 Created -Query Parameters: +**Query parameters:** - **repo** – The repository to tag in - **tag** - The new tag name -Status Codes: +**Status codes:** - **201** – no error - **400** – bad parameter @@ -2051,12 +2053,12 @@ Remove the image `name` from the filesystem {"Deleted": "53b4f83ac9"} ] -Query Parameters: +**Query parameters:** - **force** – 1/True/true or 0/False/false, default false - **noprune** – 1/True/true or 0/False/false, default false -Status Codes: +**Status codes:** - **200** – no error - **404** – no such image @@ -2107,7 +2109,7 @@ Search for an image on [Docker Hub](https://hub.docker.com). ... ] -Query Parameters: +**Query parameters:** - **term** – term to search - **limit** – maximum returned search results @@ -2116,7 +2118,7 @@ Query Parameters: - `is-automated=(true|false)` - `is-official=(true|false)` -Status Codes: +**Status codes:** - **200** – no error - **500** – server error @@ -2150,7 +2152,7 @@ if available, for accessing the registry without password. "IdentityToken": "9cbaf023786cd7..." } -Status Codes: +**Status codes:** - **200** – no error - **204** – no error @@ -2245,7 +2247,7 @@ Display system-wide information "SystemTime": "2015-03-10T11:11:23.730591467-07:00" } -Status Codes: +**Status codes:** - **200** – no error - **500** – server error @@ -2277,7 +2279,7 @@ Show the docker version information "Experimental": true } -Status Codes: +**Status codes:** - **200** – no error - **500** – server error @@ -2299,7 +2301,7 @@ Ping the docker server OK -Status Codes: +**Status codes:** - **200** - no error - **500** - server error @@ -2355,11 +2357,11 @@ Create a new image from a container's changes {"Id": "596069db4bf5"} -Json Parameters: +**JSON parameters:** - **config** - the container's configuration -Query Parameters: +**Query parameters:** - **container** – source container - **repo** – repository @@ -2370,7 +2372,7 @@ Query Parameters: - **pause** – 1/True/true or 0/False/false, whether to pause the container before committing - **changes** – Dockerfile instructions to apply while committing -Status Codes: +**Status codes:** - **201** – no error - **404** – no such container @@ -2562,7 +2564,7 @@ Docker daemon report the following event: "timeNano": 1461943105338056026 } -Query Parameters: +**Query parameters:** - **since** – Timestamp used for polling - **until** – Timestamp used for polling @@ -2576,7 +2578,7 @@ Query Parameters: - `network=`; -- network to filter - `daemon=`; -- daemon name or id to filter -Status Codes: +**Status codes:** - **200** – no error - **500** – server error @@ -2606,12 +2608,12 @@ See the [image tarball format](#image-tarball-format) for more details. Binary data stream -Status Codes: +**Status codes:** - **200** – no error - **500** – server error -### Get a tarball containing all images. +### Get a tarball containing all images `GET /images/get` @@ -2635,7 +2637,7 @@ See the [image tarball format](#image-tarball-format) for more details. Binary data stream -Status Codes: +**Status codes:** - **200** – no error - **500** – server error @@ -2657,7 +2659,7 @@ See the [image tarball format](#image-tarball-format) for more details. HTTP/1.1 200 OK -Status Codes: +**Status codes:** - **200** – no error - **500** – server error @@ -2715,7 +2717,7 @@ Sets up an exec instance in a running container `id` "Warnings":[] } -Json Parameters: +**JSON parameters:** - **AttachStdin** - Boolean value, attaches to `stdin` of the `exec` command. - **AttachStdout** - Boolean value, attaches to `stdout` of the `exec` command. @@ -2727,7 +2729,7 @@ Json Parameters: - **Cmd** - Command to run specified as a string or an array of strings. -Status Codes: +**Status codes:** - **201** – no error - **404** – no such container @@ -2759,12 +2761,12 @@ interactive session with the `exec` command. {{ STREAM }} -Json Parameters: +**JSON parameters:** - **Detach** - Detach from the `exec` command. - **Tty** - Boolean value to allocate a pseudo-TTY. -Status Codes: +**Status codes:** - **200** – no error - **404** – no such exec instance @@ -2790,12 +2792,12 @@ This API is valid only if `tty` was specified as part of creating and starting t HTTP/1.1 201 Created Content-Type: text/plain -Query Parameters: +**Query parameters:** - **h** – height of `tty` session - **w** – width -Status Codes: +**Status codes:** - **201** – no error - **404** – no such exec instance @@ -2837,7 +2839,7 @@ Return low-level information about the `exec` command `id`. "Running": false } -Status Codes: +**Status codes:** - **200** – no error - **404** – no such exec instance @@ -2869,14 +2871,14 @@ Status Codes: "Warnings": [] } -Query Parameters: +**Query parameters:** - **filters** - JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. Available filters: - `name=` Matches all or part of a volume name. - `dangling=` When set to `true` (or `1`), returns all volumes that are "dangling" (not in use by a container). When set to `false` (or `0`), only volumes that are in use by one or more containers are returned. - `driver=` Matches all or part of a volume driver name. -Status Codes: +**Status codes:** - **200** - no error - **500** - server error @@ -2916,12 +2918,12 @@ Create a volume }, } -Status Codes: +**Status codes:** - **201** - no error - **500** - server error -JSON Parameters: +**JSON parameters:** - **Name** - The new volume's name. If not specified, Docker generates a name. - **Driver** - Name of the volume driver to use. Defaults to `local` for the name. @@ -2954,7 +2956,7 @@ Return low-level information on the volume `name` } } -Status Codes: +**Status codes:** - **200** - no error - **404** - no such volume @@ -3061,7 +3063,7 @@ Content-Type: application/json ] ``` -Query Parameters: +**Query parameters:** - **filters** - JSON encoded network list filter. The filter value is one of: - `driver=` Matches a network's driver. @@ -3070,7 +3072,7 @@ Query Parameters: - `name=` Matches all or part of a network name. - `type=["custom"|"builtin"]` Filters networks by type. The `custom` keyword returns all user-defined networks. -Status Codes: +**Status codes:** - **200** - no error - **500** - server error @@ -3132,7 +3134,7 @@ Content-Type: application/json } ``` -Status Codes: +**Status codes:** - **200** - no error - **404** - network not found @@ -3198,13 +3200,13 @@ Content-Type: application/json } ``` -Status Codes: +**Status codes:** - **201** - no error - **404** - plugin not found - **500** - server error -JSON Parameters: +**JSON parameters:** - **Name** - The new network's name. this is a mandatory field - **CheckDuplicate** - Requests daemon to check for networks with same name @@ -3242,13 +3244,13 @@ Content-Type: application/json HTTP/1.1 200 OK -Status Codes: +**Status codes:** - **200** - no error - **404** - network or container is not found - **500** - Internal Server Error -JSON Parameters: +**JSON parameters:** - **container** - container-id/name to be connected to the network @@ -3274,13 +3276,13 @@ Content-Type: application/json HTTP/1.1 200 OK -Status Codes: +**Status codes:** - **200** - no error - **404** - network or container not found - **500** - Internal Server Error -JSON Parameters: +**JSON parameters:** - **Container** - container-id/name to be disconnected from a network - **Force** - Force the container to disconnect from a network