github.com/brahmaroutu/docker@v1.2.1-0.20160809185609-eb28dde01f16/docs/reference/api/docker_remote_api_v1.20.md (about)

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