@@ -18,7 +18,7 @@ import (

 // Common constants for daemon and client.

 const (

 	// Version of Current REST API

-	Version version.Version = "1.21"

+	Version version.Version = "1.22"

 	// MinVersion represents Minimun REST API version supported

 	MinVersion version.Version = "1.12"

@@ -23,14 +23,15 @@ client must have `root` access to interact with the daemon. If a group named

 `docker` exists on your system, `docker` applies ownership of the socket to the

 group.

-The current version of the API is v1.21 which means calling `/info` is the same

-as calling `/v1.21/info`. To call an older version of the API use

-`/v1.20/info`.

+The current version of the API is v1.22 which means calling `/info` is the same

+as calling `/v1.22/info`. To call an older version of the API use

+`/v1.21/info`.

 Use the table below to find the API version for a Docker version:

 Docker version  | API version                                     | Changes

 ----------------|-------------------------------------------------|-----------------------------

+1.10.x          | [1.22](/reference/api/docker_remote_api_v1.22/) | [API changes](/reference/api/docker_remote_api/#v1-22-api-changes)

 1.9.x           | [1.21](/reference/api/docker_remote_api_v1.21/) | [API changes](/reference/api/docker_remote_api/#v1-21-api-changes)

 1.8.x           | [1.20](/reference/api/docker_remote_api_v1.20/) | [API changes](/reference/api/docker_remote_api/#v1-20-api-changes)

 1.7.x           | [1.19](/reference/api/docker_remote_api_v1.19/) | [API changes](/reference/api/docker_remote_api/#v1-19-api-changes)

@@ -89,6 +90,11 @@ Running `docker rmi` emits an **untag** event when removing an image name.  The

 This section lists each version from latest to oldest.  Each listing includes a link to the full documentation set and the changes relevant in that release.

+### v1.22 API changes

+

+[Docker Remote API v1.22](docker_remote_api_v1.22.md) documentation

+

+

 ### v1.21 API changes

 [Docker Remote API v1.21](docker_remote_api_v1.21.md) documentation

new file mode 100644

@@ -0,0 +1,2771 @@

+<!--[metadata]>

+title = "Remote API v1.22"

+description = "API Documentation for Docker"

+keywords = ["API, Docker, rcli, REST,  documentation"]

+[menu.main]

+parent="smn_remoteapi"

+weight = 0

+<![end-metadata]-->

+

+# Docker Remote API v1.22

+

+## 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](../../articles/basics.md#bind-docker-to-another-hostport-or-a-unix-socket).

+ - The API tends to be REST. However, for some complex commands, like `attach`

+   or `pull`, the HTTP connection is hijacked to transport `stdout`,

+   `stdin` and `stderr`.

+ - When the client API version is newer than the daemon's, these calls return an HTTP

+   `400 Bad Request` error message.

+

+# 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",

+		 "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",

+                 "Command": "echo 1",

+                 "Created": 1367854155,

+                 "Status": "Exit 0",

+                 "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}],

+                 "Labels": {

+                         "com.example.vendor": "Acme",

+                         "com.example.license": "GPL",

+                         "com.example.version": "1.0"

+                 },

+                 "SizeRw": 12288,

+                 "SizeRootFs": 0

+         },

+         {

+                 "Id": "9cd87474be90",

+                 "Names":["/coolName"],

+                 "Image": "ubuntu:latest",

+		 "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",

+                 "Command": "echo 222222",

+                 "Created": 1367854155,

+                 "Status": "Exit 0",

+                 "Ports": [],

+                 "Labels": {},

+                 "SizeRw": 12288,

+                 "SizeRootFs": 0

+         },

+         {

+                 "Id": "3176a2479c92",

+                 "Names":["/sleepy_dog"],

+                 "Image": "ubuntu:latest",

+		 "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",

+                 "Command": "echo 3333333333333333",

+                 "Created": 1367854154,

+                 "Status": "Exit 0",

+                 "Ports":[],

+                 "Labels": {},

+                 "SizeRw":12288,

+                 "SizeRootFs":0

+         },

+         {

+                 "Id": "4cb07b47f9fb",

+                 "Names":["/running_cat"],

+                 "Image": "ubuntu:latest",

+		 "ImageID": "d74508fb6632491cea586a1fd7d748dfc5274cd6fdfedee309ecdcbc2bf5cb82",

+                 "Command": "echo 444444444444444444444444444444444",

+                 "Created": 1367854152,

+                 "Status": "Exit 0",

+                 "Ports": [],

+                 "Labels": {},

+                 "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=`(`created`|`restarting`|`running`|`paused`|`exited`)

+  -   `label=key` or `label="key=value"` of a container label

+

+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": "",

+           "AttachStdin": false,

+           "AttachStdout": true,

+           "AttachStderr": true,

+           "Tty": false,

+           "OpenStdin": false,

+           "StdinOnce": false,

+           "Env": null,

+           "Cmd": [

+                   "date"

+           ],

+           "Entrypoint": "",

+           "Image": "ubuntu",

+           "Labels": {

+                   "com.example.vendor": "Acme",

+                   "com.example.license": "GPL",

+                   "com.example.version": "1.0"

+           },

+           "Mounts": [

+             {

+               "Source": "/data",

+               "Destination": "/data",

+               "Mode": "ro,Z",

+               "RW": false

+             }

+           ],

+           "WorkingDir": "",

+           "NetworkDisabled": false,

+           "MacAddress": "12:34:56:78:9a:bc",

+           "ExposedPorts": {

+                   "22/tcp": {}

+           },

+           "StopSignal": "SIGTERM",

+           "HostConfig": {

+             "Binds": ["/tmp:/tmp"],

+             "Links": ["redis3:redis"],

+             "LxcConf": {"lxc.utsname":"docker"},

+             "Memory": 0,

+             "MemorySwap": 0,

+             "MemoryReservation": 0,

+             "KernelMemory": 0,

+             "CpuShares": 512,

+             "CpuPeriod": 100000,

+             "CpuQuota": 50000,

+             "CpusetCpus": "0,1",

+             "CpusetMems": "0,1",

+             "BlkioWeight": 300,

+             "MemorySwappiness": 60,

+             "OomKillDisable": false,

+             "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] },

+             "PublishAllPorts": false,

+             "Privileged": false,

+             "ReadonlyRootfs": false,

+             "Dns": ["8.8.8.8"],

+             "DnsOptions": [""],

+             "DnsSearch": [""],

+             "ExtraHosts": null,

+             "VolumesFrom": ["parent", "other:ro"],

+             "CapAdd": ["NET_ADMIN"],

+             "CapDrop": ["MKNOD"],

+             "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 },

+             "NetworkMode": "bridge",

+             "Devices": [],

+             "Ulimits": [{}],

+             "LogConfig": { "Type": "json-file", "Config": {} },

+             "SecurityOpt": [""],

+             "CgroupParent": "",

+	      "VolumeDriver": ""

+          }

+      }

+

+**Example response**:

+

+      HTTP/1.1 201 Created

+      Content-Type: application/json

+

+      {

+           "Id":"e90e34656806",

+           "Warnings":[]

+      }

+

+Json Parameters:

+

+-   **Hostname** - A string value containing the hostname to use for the

+      container.

+-   **Domainname** - A string value containing the domain name to use

+      for the container.

+-   **User** - A string value specifying the user inside the container.

+-   **Memory** - Memory limit in bytes.

+-   **MemorySwap** - Total memory limit (memory + swap); set `-1` to disable swap

+      You must use this with `memory` and make the swap value larger than `memory`.

+-   **MemoryReservation** - Memory soft limit in bytes.

+-   **KernelMemory** - Kernel memory limit in bytes.

+-   **CpuShares** - An integer value containing the container's CPU Shares

+      (ie. the relative weight vs other containers).

+-   **CpuPeriod** - The length of a CPU period in microseconds.

+-   **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period.

+-   **Cpuset** - Deprecated please don't use. Use `CpusetCpus` instead.

+-   **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use.

+-   **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.

+-   **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000.

+-   **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.

+-   **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not.

+-   **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`

+-   **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value"[,"key2":"value2"]}`

+-   **Cmd** - Command to run specified as a string or an array of strings.

+-   **Entrypoint** - Set the entry point for the container as a string or an array

+      of strings.

+-   **Image** - A string specifying the image name to use for the container.

+-   **Mounts** - An array of mount points in the container.

+-   **WorkingDir** - A string specifying the working directory 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": { "<port>/<tcp|udp>: {}" }`

+-   **StopSignal** - Signal to stop a container as a string or unsigned integer. `SIGTERM` by default.

+-   **HostConfig**

+    -   **Binds** – A list of volume bindings for this container. Each volume binding is a string in one of these forms:

+           + `container_path` to create a new volume for the container

+           + `host_path:container_path` to bind-mount a host path into the container

+           + `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 only

+          work when using the `lxc` execution driver.

+    -   **PortBindings** - A map of exposed container ports and the host port they

+          should map to. A JSON object in the form

+          `{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`

+          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.

+    -   **DnsOptions** - A list of DNS options

+    -   **DnsSearch** - A list of DNS search domains

+    -   **ExtraHosts** - A list of hostnames/IP mappings to add 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 `<container name>[:<ro|rw>]`

+    -   **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, `"unless-stopped"` to restart always except when

+            user has manually stopped the container 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`, and `container:<name|id>`

+    -   **Devices** - A list of devices to add to the container specified as a JSON object in the

+      form

+          `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}`

+    -   **Ulimits** - A list of ulimits to set in the container, specified as

+          `{ "Name": <name>, "Soft": <soft limit>, "Hard": <hard limit> }`, for example:

+          `Ulimits: { "Name": "nofile", "Soft": 1024, "Hard": 2048 }`

+    -   **SecurityOpt**: A list of string values to customize labels for MLS

+        systems, such as SELinux.

+    -   **LogConfig** - Log configuration for the container, specified as a JSON object in the form

+          `{ "Type": "<driver_name>", "Config": {"key1": "val1"}}`.

+          Available types: `json-file`, `syslog`, `journald`, `gelf`, `awslogs`, `none`.

+          `json-file` logging driver.

+    -   **CgroupParent** - Path to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist.

+    -   **VolumeDriver** - Driver that this container users to mount volumes.

+

+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)/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"

+			],

+			"Domainname": "",

+			"Entrypoint": null,

+			"Env": [

+				"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"

+			],

+			"ExposedPorts": null,

+			"Hostname": "ba033ac44011",

+			"Image": "ubuntu",

+			"Labels": {

+				"com.example.vendor": "Acme",

+				"com.example.license": "GPL",

+				"com.example.version": "1.0"

+			},

+			"MacAddress": "",

+			"NetworkDisabled": false,

+			"OnBuild": null,

+			"OpenStdin": false,

+			"StdinOnce": false,

+			"Tty": false,

+			"User": "",

+			"Volumes": null,

+			"WorkingDir": "",

+			"StopSignal": "SIGTERM"

+		},

+		"Created": "2015-01-06T15:47:31.485331387Z",

+		"Driver": "devicemapper",

+		"ExecDriver": "native-0.2",

+		"ExecIDs": null,

+		"HostConfig": {

+			"Binds": null,

+			"BlkioWeight": 0,

+			"CapAdd": null,

+			"CapDrop": null,

+			"ContainerIDFile": "",

+			"CpusetCpus": "",

+			"CpusetMems": "",

+			"CpuShares": 0,

+			"CpuPeriod": 100000,

+			"Devices": [],

+			"Dns": null,

+			"DnsOptions": null,

+			"DnsSearch": null,

+			"ExtraHosts": null,

+			"IpcMode": "",

+			"Links": null,

+			"LxcConf": [],

+			"Memory": 0,

+			"MemorySwap": 0,

+			"MemoryReservation": 0,

+			"KernelMemory": 0,

+			"OomKillDisable": false,

+			"NetworkMode": "bridge",

+			"PortBindings": {},

+			"Privileged": false,

+			"ReadonlyRootfs": false,

+			"PublishAllPorts": false,

+			"RestartPolicy": {

+				"MaximumRetryCount": 2,

+				"Name": "on-failure"

+			},

+			"LogConfig": {

+				"Config": null,

+				"Type": "json-file"

+			},

+			"SecurityOpt": null,

+			"VolumesFrom": null,

+			"Ulimits": [{}],

+			"VolumeDriver": ""

+		},

+		"HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname",

+		"HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts",

+		"LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",

+		"Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39",

+		"Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2",

+		"MountLabel": "",

+		"Name": "/boring_euclid",

+		"NetworkSettings": {

+			"Bridge": "",

+			"Gateway": "",

+			"IPAddress": "",

+			"IPPrefixLen": 0,

+			"MacAddress": "",

+			"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": true,

+			"StartedAt": "2015-01-06T15:47:32.072697474Z",

+			"Status": "running"

+		},

+		"Mounts": [

+			{

+				"Source": "/data",

+				"Destination": "/data",

+				"Mode": "ro,Z",

+				"RW": false

+			}

+		]

+	}

+

+**Example request, with size information**:

+

+    GET /containers/4fa6e0f0c678/json?size=1 HTTP/1.1

+

+**Example response, with size information**:

+

+    HTTP/1.1 200 OK

+    Content-Type: application/json

+

+    {

+    ....

+    "SizeRw": 0,

+    "SizeRootFs": 972,

+    ....

+    }

+

+Query Parameters:

+

+-   **size** – 1/True/true or 0/False/false, return container size information. Default is `false`.

+

+Status Codes:

+

+-   **200** – no error

+-   **404** – no such container

+-   **500** – server error

+

+### List processes running inside a container

+

+`GET /containers/(id)/top`

+

+List processes running inside the container `id`

+

+**Example request**:

+

+    GET /containers/4fa6e0f0c678/top 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","20147","0.0","0.1","18060","1864","pts/4","S","10:06","0:00","bash"],

+                 ["root","20271","0.0","0.0","4312","352","pts/4","S+","10:07","0:00","sleep","10"]

+         ]

+    }

+

+Query Parameters:

+

+-   **ps_args** – ps arguments to use (e.g., aux)

+

+Status Codes:

+

+-   **200** – no error

+-   **404** – no such container

+-   **500** – server error

+

+### Get container logs

+

+`GET /containers/(id)/logs`

+

+Get `stdout` and `stderr` logs from the container ``id``

+

+> **Note**:

+> This endpoint works only for containers with `json-file` logging driver.

+

+**Example request**:

+

+     GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1&timestamps=1&follow=1&tail=10&since=1428990821 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`.

+-   **since** – UNIX timestamp (integer) to filter logs. Specifying a timestamp

+    will only output log-entries since that timestamp. Default: 0 (unfiltered)

+-   **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 `<number>`. 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)/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

+         }

+    ]

+

+Values for `Kind`:

+

+- `0`: Modify

+- `1`: Add

+- `2`: Delete

+

+Status Codes:

+

+-   **200** – no error

+-   **404** – no such container

+-   **500** – server error

+

+### Export a container

+

+`GET /containers/(id)/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)/stats`

+

+This endpoint returns a live stream of a container's resource usage statistics.

+

+> **Note**: this functionality currently only works when using the *libcontainer* exec-driver.

+

+**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": {

+                 "eth0": {

+                     "rx_bytes": 5338,

+                     "rx_dropped": 0,

+                     "rx_errors": 0,

+                     "rx_packets": 36,

+                     "tx_bytes": 648,

+                     "tx_dropped": 0,

+                     "tx_errors": 0,

+                     "tx_packets": 8

+                 },

+                 "eth5": {

+                     "rx_bytes": 4641,

+                     "rx_dropped": 0,

+                     "rx_errors": 0,

+                     "rx_packets": 26,

+                     "tx_bytes": 690,

+                     "tx_dropped": 0,

+                     "tx_errors": 0,

+                     "tx_packets": 9

+                 }

+         },

+         "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" : {}

+         }

+      }

+

+Query Parameters:

+

+-   **stream** – 1/True/true or 0/False/false, pull stats once then disconnect. Default `true`.

+

+Status Codes:

+

+-   **200** – no error

+-   **404** – no such container

+-   **500** – server error

+

+### Resize a container TTY

+

+`POST /containers/(id)/resize`

+

+Resize the TTY for container with  `id`. The unit is number of characters. You must restart the container 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

+

+Query Parameters:

+

+-   **h** – height of `tty` session

+-   **w** – width

+

+Status Codes:

+

+-   **200** – no error

+-   **404** – No such container

+-   **500** – Cannot resize container

+

+### Start a container

+

+`POST /containers/(id)/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/(id)/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)/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)/restart`

+

+Restart the container `id`

+

+**Example request**:

+

+    POST /containers/e90e34656806/restart?t=5 HTTP/1.1

+

+**Example response**:

+

+    HTTP/1.1 204 No Content