2016-10-14 22:30:36 +00:00
---
2016-11-15 19:45:20 +00:00
title: "Engine API v1.18"
2016-10-14 22:30:36 +00:00
description: "API Documentation for Docker"
2016-11-03 22:48:30 +00:00
keywords: "API, Docker, rcli, REST, documentation"
2016-11-21 15:30:57 +00:00
redirect_from:
- /engine/reference/api/docker_remote_api_v1.18/
- /reference/api/docker_remote_api_v1.18/
2016-10-14 22:30:36 +00:00
---
2015-02-10 18:48:54 +00:00
2017-10-04 16:38:09 +00:00
<!-- This file is maintained within the moby/moby GitHub
repository at https://github.com/moby/moby/. Make all
2016-10-19 17:25:45 +00:00
pull requests against that repo. If you see this file in
another repository, consider it read-only there, as it will
periodically be overwritten by the definitive file. Pull
requests which include edits to this file in other repositories
will be rejected.
-->
2016-11-25 10:30:03 +00:00
## 1. Brief introduction
2015-02-10 18:48:54 +00:00
- The daemon listens on `unix:///var/run/docker.sock` but you can
2020-04-09 11:44:51 +00:00
[Bind Docker to another host/port or a Unix socket ](https://docs.docker.com/engine/reference/commandline/dockerd/#bind-docker-to-another-host-port-or-a-unix-socket ).
2015-02-10 18:48:54 +00:00
- The API tends to be REST, but for some complex commands, like `attach`
2016-12-19 05:05:11 +00:00
or `pull` , the HTTP connection is hijacked to transport `stdout` ,
`stdin` and `stderr` .
2017-10-08 17:48:55 +00:00
- A `Content-Length` header should be present in `POST` requests to endpoints
that expect a body.
Return 400 error if API client is too new
Commit e98e4a71110fd33852bb755a9b8b4ebc9df904db implemented API version
negotiation using the `/_ping` endpoint. In that change, URL validation for the
maximum supported API version was removed from the API server (validation for
the _minimum_ version was kept in place).
With this feature, clients that support version negotiation would negotiate the
maximum version supported by the daemon, and downgrade to an older API version
if the client's default API version is not supported.
However, clients that do _not_ support version negotiation can call API versions
that are higher than the maximum supported version. Due to the missing version
check, this is silently ignored, and the daemon's default API version is used.
This is a problem, because the actual API version in use is non-deterministic;
for example, calling `/v9999.9999/version` on a daemon that runs API v1.34 will
use API v1.34, but calling the same URL on an older daemon may use API version
v1.24.
This patch reverts the removal of the API check for maximum supported versions.
The documentation has been updated accordingly
Before this patch is applied, the daemon returns a 200 (success):
$ curl -v --unix-socket /var/run/docker.sock http://localhost/v9999.9999/version
* Trying /var/run/docker.sock...
* Connected to localhost (/Users/sebastiaan/Library/Containers/com.dock) port 80 (#0)
> GET /v9999.9999/version HTTP/1.1
> Host: localhost
> User-Agent: curl/7.54.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Api-Version: 1.32
< Content-Length: 240
< Content-Type: application/json
< Date: Tue, 10 Oct 2017 09:11:29 GMT
< Docker-Experimental: true
< Ostype: linux
< Server: Docker/17.09.0-ce (linux)
<
{"Version":"17.09.0-ce","ApiVersion":"1.32","MinAPIVersion":"1.12","GitCommit":"afdb6d4","GoVersion":"go1.8.3","Os":"linux","Arch":"amd64","KernelVersion":"4.9.49-moby","Experimental":true,"BuildTime":"2017-09-26T22:45:38.000000000+00:00"}
* Connection #0 to host localhost left intact
After this patch is applied, a 400 (Bad Request) is returned:
$ curl -v --unix-socket /var/run/docker.sock http://localhost/v9999.9999/version
* Trying /var/run/docker.sock...
* Connected to localhost (/var/run/docker.sock) port 80 (#0)
> GET /v9999.9999/info HTTP/1.1
> Host: localhost
> User-Agent: curl/7.52.1
> Accept: */*
>
< HTTP/1.1 400 Bad Request
< Content-Type: application/json
< Date: Tue, 10 Oct 2017 08:08:34 GMT
< Content-Length: 89
<
{"message":"client version 9999.9999 is too new. Maximim supported API version is 1.34"}
* Curl_http_done: called premature == 0
* Connection #0 to host localhost left intact
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
2017-10-10 08:28:46 +00:00
- To lock to a specific version of the API, you prefix the URL with the version
of the API to use. For example, `/v1.18/info` . If no version is included in
the URL, the maximum supported API version is used.
- If the API version specified in the URL is not supported by the daemon, a HTTP
`400 Bad Request` error message is returned.
2015-02-10 18:48:54 +00:00
2016-11-25 10:30:03 +00:00
## 2. Endpoints
2015-02-10 18:48:54 +00:00
2016-11-25 10:30:03 +00:00
### 2.1 Containers
2015-02-10 18:48:54 +00:00
2016-11-25 10:30:03 +00:00
#### List containers
2015-02-10 18:48:54 +00:00
`GET /containers/json`
List containers
**Example request**:
2016-10-27 16:59:59 +00:00
GET /v1.18/containers/json?all=1& before=8dfafdbc3a40& size=1 HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
[
{
"Id": "8dfafdbc3a40",
"Names":["/boring_feynman"],
"Image": "ubuntu:latest",
"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",
"Command": "echo 222222",
"Created": 1367854155,
"Status": "Exit 0",
"Ports": [],
"Labels": {},
"SizeRw": 12288,
"SizeRootFs": 0
},
{
"Id": "3176a2479c92",
"Names":["/sleepy_dog"],
"Image": "ubuntu:latest",
"Command": "echo 3333333333333333",
"Created": 1367854154,
"Status": "Exit 0",
"Ports":[],
"Labels": {},
"SizeRw":12288,
"SizeRootFs":0
},
{
"Id": "4cb07b47f9fb",
"Names":["/running_cat"],
"Image": "ubuntu:latest",
"Command": "echo 444444444444444444444444444444444",
"Created": 1367854152,
"Status": "Exit 0",
"Ports": [],
"Labels": {},
"SizeRw": 12288,
"SizeRootFs": 0
}
]
**Query parameters**:
2015-02-10 18:48:54 +00:00
- **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
2016-08-04 13:12:57 +00:00
- **filters** - a JSON encoded value of the filters (a `map[string][]string` ) to process on the containers list. Available filters:
- `exited=<int>` ; -- containers with exit code of `<int>` ;
- `status=` (`restarting`|`running`|`paused`|`exited`)
- `label=key` or `label="key=value"` of a container label
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **400** – bad parameter
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Create a container
2015-02-10 18:48:54 +00:00
`POST /containers/create`
Create a container
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/containers/create HTTP/1.1
2016-08-14 00:08:05 +00:00
Content-Type: application/json
2017-10-08 17:48:55 +00:00
Content-Length: 12345
2015-02-10 18:48:54 +00:00
2016-08-14 00:08:05 +00:00
{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"FOO=bar",
"BAZ=quux"
],
"Cmd": [
"date"
],
"Entrypoint": null,
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": {
"/volumes/data": {}
},
"WorkingDir": "",
"NetworkDisabled": false,
"MacAddress": "12:34:56:78:9a:bc",
"ExposedPorts": {
"22/tcp": {}
},
"HostConfig": {
"Binds": ["/tmp:/tmp"],
"Links": ["redis3:redis"],
"LxcConf": {"lxc.utsname":"docker"},
"Memory": 0,
"MemorySwap": 0,
"CpuShares": 512,
"CpusetCpus": "0,1",
"PidMode": "",
"PortBindings": { "22/tcp": [{ "HostPort": "11022" }] },
"PublishAllPorts": false,
"Privileged": false,
"ReadonlyRootfs": false,
"Dns": ["8.8.8.8"],
"DnsSearch": [""],
"ExtraHosts": null,
"VolumesFrom": ["parent", "other:ro"],
"CapAdd": ["NET_ADMIN"],
"CapDrop": ["MKNOD"],
"RestartPolicy": { "Name": "", "MaximumRetryCount": 0 },
"NetworkMode": "bridge",
"Devices": [],
"Ulimits": [{}],
"LogConfig": { "Type": "json-file", "Config": {} },
"SecurityOpt": [],
"CgroupParent": ""
}
}
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-14 00:08:05 +00:00
HTTP/1.1 201 Created
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-08-14 00:08:05 +00:00
{
"Id":"e90e34656806",
"Warnings":[]
}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**JSON parameters**:
2015-02-10 18:48:54 +00:00
2016-08-14 00:08:05 +00:00
- **Hostname** - A string value containing the hostname to use for the
2015-02-10 18:48:54 +00:00
container.
2016-08-14 00:08:05 +00:00
- **Domainname** - A string value containing the domain name to use
2015-02-10 18:48:54 +00:00
for the container.
2016-08-14 00:08:05 +00:00
- **User** - A string value specifying the user inside the container.
- **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.
2016-10-17 02:22:42 +00:00
- **Env** - A list of environment variables in the form of `["VAR=value", ...]`
2016-10-17 02:54:08 +00:00
- **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value", ... }`
2015-02-10 18:48:54 +00:00
- **Cmd** - Command to run specified as a string or an array of strings.
2016-08-14 00:08:05 +00:00
- **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.
- **Volumes** - An object mapping mount point paths (strings) inside the
move resources from Config to HostConfig
Cgroup resources are host dependent, they should be in hostConfig.
For backward compatibility, we just copy it to hostConfig, and leave it in
Config for now, so there is no regressions, but the right way to use this
throught json is to put it in HostConfig, like:
{
"Hostname": "",
...
"HostConfig": {
"CpuShares": 512,
"Memory": 314572800,
...
}
}
As we will add CpusetMems, CpusetCpus is definitely a better name, but some
users are already using Cpuset in their http APIs, we also make it compatible.
The main idea is keep using Cpuset in Config Struct, and make it has the same
value as CpusetCpus, but not always, some scenarios:
- Users use --cpuset in docker command, it can setup cpuset.cpus and can
get Cpuset field from docker inspect or other http API which will get
config info.
- Users use --cpuset-cpus in docker command, ditto.
- Users use Cpuset field in their http APIs, ditto.
- Users use CpusetCpus field in their http APIs, they won't get Cpuset field
in Config info, because by then, they should already know what happens
to Cpuset.
Signed-off-by: Qiang Huang <h.huangqiang@huawei.com>
2015-03-11 01:31:18 +00:00
container to empty objects.
2016-08-14 00:08:05 +00:00
- **WorkingDir** - A string specifying the working directory for commands to
2015-02-10 18:48:54 +00:00
run in.
2015-04-11 10:11:49 +00:00
- **NetworkDisabled** - Boolean value, when true disables networking for the
2015-02-10 18:48:54 +00:00
container
- **ExposedPorts** - An object mapping ports to an empty object in the form of:
`"ExposedPorts": { "<port>/<tcp|udp>: {}" }`
- **HostConfig**
2017-08-19 14:23:38 +00:00
- **Binds** – A list of bind mounts for this container. Each item is a string in one of these forms:
2016-09-15 13:43:26 +00:00
+ `host-src:container-dest` to bind-mount a host path into the
container. Both `host-src` , and `container-dest` must be an
_absolute_ path.
2017-08-19 14:23:38 +00:00
+ `host-src:container-dest:ro` to make the bind mount read-only
2016-09-15 13:43:26 +00:00
inside the container. Both `host-src` , and `container-dest` must be
an _absolute_ path.
2015-05-06 18:56:12 +00:00
- **Links** - A list of links for the container. Each link entry should be
in the form of `container_name:alias` .
2016-08-14 00:08:05 +00:00
- **LxcConf** - LXC specific configurations. These configurations only
2015-04-09 03:07:03 +00:00
work when using the `lxc` execution driver.
2016-04-19 04:15:33 +00:00
- **Memory** - Memory limit in bytes.
- **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap.
You must use this with `memory` and make the swap value larger than `memory` .
2016-08-14 00:08:05 +00:00
- **CpuShares** - An integer value containing the container's CPU Shares
2016-04-19 04:15:33 +00:00
(ie. the relative weight vs other containers).
2016-08-14 00:08:05 +00:00
- **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use.
2016-07-11 23:52:42 +00:00
- **PidMode** - Set the PID (Process) Namespace mode for the container;
`"container:<name|id>"` : joins another container's PID namespace
`"host"` : use the host's PID namespace inside the container
2015-04-09 03:07:03 +00:00
- **PortBindings** - A map of exposed container ports and the host port they
2016-08-14 00:08:05 +00:00
should map to. A JSON object in the form
2015-04-09 03:07:03 +00:00
`{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
Take note that `port` is specified as a string and not an integer value.
2017-10-05 20:57:11 +00:00
- **PublishAllPorts** - Allocates an ephemeral host port for all of a container's
2015-04-09 03:07:03 +00:00
exposed ports. Specified as a boolean value.
2017-10-05 20:57:11 +00:00
Ports are de-allocated when the container stops and allocated when the container starts.
The allocated port might be changed when restarting the container.
The port is selected from the ephemeral port range that depends on the kernel.
For example, on Linux the range is defined by `/proc/sys/net/ipv4/ip_local_port_range` .
2015-04-09 03:07:03 +00:00
- **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.
2016-08-14 00:08:05 +00:00
- **Dns** - A list of DNS servers for the container to use.
2015-04-09 03:07:03 +00:00
- **DnsSearch** - A list of DNS search domains
2016-08-14 00:08:05 +00:00
- **ExtraHosts** - A list of hostnames/IP mappings to add to the
2015-04-09 03:07:03 +00:00
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>]`
2015-04-11 10:11:49 +00:00
- **CapAdd** - A list of kernel capabilities to add to the container.
- **Capdrop** - A list of kernel capabilities to drop from the container.
2015-04-09 03:07:03 +00:00
- **RestartPolicy** – The behavior to apply when the container exits. The
value is an object with a `Name` property of either `"always"` to
always restart or `"on-failure"` to restart only when the container
exit code is non-zero. If `on-failure` is used, `MaximumRetryCount`
controls the number of times to retry before giving up.
The default is not to restart. (optional)
An ever increasing delay (double the previous delay, starting at 100mS)
is added before each restart to prevent flooding the server.
- **NetworkMode** - Sets the networking mode for the container. Supported
2016-02-12 17:23:46 +00:00
values are: `bridge` , `host` , `none` , and `container:<name|id>`
2016-08-14 00:08:05 +00:00
- **Devices** - A list of devices to add to the container specified as a JSON object in the
form
2015-04-09 03:07:03 +00:00
`{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}`
2016-08-14 00:08:05 +00:00
- **Ulimits** - A list of ulimits to set in the container, specified as
2015-04-09 03:07:03 +00:00
`{ "Name": <name>, "Soft": <soft limit>, "Hard": <hard limit> }` , for example:
2015-09-13 22:35:56 +00:00
`Ulimits: { "Name": "nofile", "Soft": 1024, "Hard": 2048 }`
2015-04-09 03:07:03 +00:00
- **SecurityOpt** : A list of string values to customize labels for MLS
systems, such as SELinux.
2016-08-14 00:08:05 +00:00
- **LogConfig** - Log configuration for the container, specified as a JSON object in the form
2015-04-09 03:07:03 +00:00
`{ "Type": "<driver_name>", "Config": {"key1": "val1"}}` .
Add log reading to the journald log driver
If a logdriver doesn't register a callback function to validate log
options, it won't be usable. Fix the journald driver by adding a dummy
validator.
Teach the client and the daemon's "logs" logic that the server can also
supply "logs" data via the "journald" driver. Update documentation and
tests that depend on error messages.
Add support for reading log data from the systemd journal to the
journald log driver. The internal logic uses a goroutine to scan the
journal for matching entries after any specified cutoff time, formats
the messages from those entries as JSONLog messages, and stuffs the
results down a pipe whose reading end we hand back to the caller.
If we are missing any of the 'linux', 'cgo', or 'journald' build tags,
however, we don't implement a reader, so the 'logs' endpoint will still
return an error.
Make the necessary changes to the build setup to ensure that support for
reading container logs from the systemd journal is built.
Rename the Jmap member of the journald logdriver's struct to "vars" to
make it non-public, and to make it easier to tell that it's just there
to hold additional variable values that we want journald to record along
with log data that we're sending to it.
In the client, don't assume that we know which logdrivers the server
implements, and remove the check that looks at the server. It's
redundant because the server already knows, and the check also makes
using older clients with newer servers (which may have new logdrivers in
them) unnecessarily hard.
When we try to "logs" and have to report that the container's logdriver
doesn't support reading, send the error message through the
might-be-a-multiplexer so that clients which are expecting multiplexed
data will be able to properly display the error, instead of tripping
over the data and printing a less helpful "Unrecognized input header"
error.
Signed-off-by: Nalin Dahyabhai <nalin@redhat.com> (github: nalind)
2015-07-23 15:02:56 +00:00
Available types: `json-file` , `syslog` , `journald` , `none` .
2015-04-09 03:07:03 +00:00
`json-file` logging driver.
2016-08-14 00:08:05 +00:00
- **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.
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
- **name** – Assign the specified name to the container. Must
match `/?[a-zA-Z0-9_-]+` .
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **201** – no error
2016-05-16 09:15:45 +00:00
- **400** – bad parameter
2021-07-03 19:30:47 +00:00
- **404** – no such image
2015-02-10 18:48:54 +00:00
- **406** – impossible to attach (container not running)
2016-07-14 09:21:05 +00:00
- **409** – conflict
2015-02-10 18:48:54 +00:00
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Inspect a container
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`GET /containers/(id or name)/json`
2015-02-10 18:48:54 +00:00
Return low-level information on the container `id`
**Example request**:
2016-10-27 16:59:59 +00:00
GET /v1.18/containers/4fa6e0f0c678/json HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
2015-02-10 18:48:54 +00:00
{
"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",
2015-03-13 16:38:41 +00:00
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
2015-02-10 18:48:54 +00:00
"MacAddress": "",
"NetworkDisabled": false,
"OnBuild": null,
"OpenStdin": false,
"PortSpecs": null,
"StdinOnce": false,
"Tty": false,
"User": "",
"Volumes": null,
"WorkingDir": ""
},
"Created": "2015-01-06T15:47:31.485331387Z",
"Driver": "devicemapper",
"ExecDriver": "native-0.2",
"ExecIDs": null,
"HostConfig": {
"Binds": null,
"CapAdd": null,
"CapDrop": null,
"ContainerIDFile": "",
move resources from Config to HostConfig
Cgroup resources are host dependent, they should be in hostConfig.
For backward compatibility, we just copy it to hostConfig, and leave it in
Config for now, so there is no regressions, but the right way to use this
throught json is to put it in HostConfig, like:
{
"Hostname": "",
...
"HostConfig": {
"CpuShares": 512,
"Memory": 314572800,
...
}
}
As we will add CpusetMems, CpusetCpus is definitely a better name, but some
users are already using Cpuset in their http APIs, we also make it compatible.
The main idea is keep using Cpuset in Config Struct, and make it has the same
value as CpusetCpus, but not always, some scenarios:
- Users use --cpuset in docker command, it can setup cpuset.cpus and can
get Cpuset field from docker inspect or other http API which will get
config info.
- Users use --cpuset-cpus in docker command, ditto.
- Users use Cpuset field in their http APIs, ditto.
- Users use CpusetCpus field in their http APIs, they won't get Cpuset field
in Config info, because by then, they should already know what happens
to Cpuset.
Signed-off-by: Qiang Huang <h.huangqiang@huawei.com>
2015-03-11 01:31:18 +00:00
"CpusetCpus": "",
"CpuShares": 0,
2015-02-10 18:48:54 +00:00
"Devices": [],
"Dns": null,
"DnsSearch": null,
"ExtraHosts": null,
"IpcMode": "",
"Links": null,
"LxcConf": [],
move resources from Config to HostConfig
Cgroup resources are host dependent, they should be in hostConfig.
For backward compatibility, we just copy it to hostConfig, and leave it in
Config for now, so there is no regressions, but the right way to use this
throught json is to put it in HostConfig, like:
{
"Hostname": "",
...
"HostConfig": {
"CpuShares": 512,
"Memory": 314572800,
...
}
}
As we will add CpusetMems, CpusetCpus is definitely a better name, but some
users are already using Cpuset in their http APIs, we also make it compatible.
The main idea is keep using Cpuset in Config Struct, and make it has the same
value as CpusetCpus, but not always, some scenarios:
- Users use --cpuset in docker command, it can setup cpuset.cpus and can
get Cpuset field from docker inspect or other http API which will get
config info.
- Users use --cpuset-cpus in docker command, ditto.
- Users use Cpuset field in their http APIs, ditto.
- Users use CpusetCpus field in their http APIs, they won't get Cpuset field
in Config info, because by then, they should already know what happens
to Cpuset.
Signed-off-by: Qiang Huang <h.huangqiang@huawei.com>
2015-03-11 01:31:18 +00:00
"Memory": 0,
"MemorySwap": 0,
2015-02-10 18:48:54 +00:00
"NetworkMode": "bridge",
2016-07-11 23:52:42 +00:00
"PidMode": "",
2015-02-10 18:48:54 +00:00
"PortBindings": {},
"Privileged": false,
"ReadonlyRootfs": false,
"PublishAllPorts": false,
"RestartPolicy": {
"MaximumRetryCount": 2,
"Name": "on-failure"
},
2015-04-15 03:15:50 +00:00
"LogConfig": {
"Config": null,
"Type": "json-file"
},
2015-02-10 18:48:54 +00:00
"SecurityOpt": null,
2015-02-11 19:21:38 +00:00
"VolumesFrom": null,
"Ulimits": [{}]
2015-02-10 18:48:54 +00:00
},
"HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname",
"HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts",
2015-02-06 17:25:42 +00:00
"LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
2015-02-10 18:48:54 +00:00
"Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39",
"Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2",
"MountLabel": "",
"Name": "/boring_euclid",
"NetworkSettings": {
"Bridge": "",
"Gateway": "",
"IPAddress": "",
"IPPrefixLen": 0,
"MacAddress": "",
"PortMapping": null,
"Ports": null
},
"Path": "/bin/sh",
"ProcessLabel": "",
"ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf",
"RestartCount": 1,
"State": {
"Error": "",
"ExitCode": 9,
"FinishedAt": "2015-01-06T15:47:32.080254511Z",
"OOMKilled": false,
"Paused": false,
"Pid": 0,
"Restarting": false,
2016-08-14 00:08:05 +00:00
"Running": true,
2015-02-10 18:48:54 +00:00
"StartedAt": "2015-01-06T15:47:32.072697474Z"
},
"Volumes": {},
"VolumesRW": {}
}
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **404** – no such container
- **500** – server error
2016-11-25 10:30:03 +00:00
#### List processes running inside a container
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`GET /containers/(id or name)/top`
2015-02-10 18:48:54 +00:00
2015-11-23 17:23:52 +00:00
List processes running inside the container `id` . On Unix systems this
is done by running the `ps` command. This endpoint is not
supported on Windows.
2015-02-10 18:48:54 +00:00
**Example request**:
2016-10-27 16:59:59 +00:00
GET /v1.18/containers/4fa6e0f0c678/top HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2015-11-23 17:23:52 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
{
"Titles" : [
"UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD"
],
"Processes" : [
[
"root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash"
],
[
"root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10"
]
]
}
2015-02-10 18:48:54 +00:00
2015-11-23 17:23:52 +00:00
**Example request**:
2016-10-27 16:59:59 +00:00
GET /v1.18/containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1
2015-11-23 17:23:52 +00:00
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{
"Titles" : [
"USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND"
]
"Processes" : [
[
"root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash"
],
[
"root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10"
]
],
}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
2015-11-23 17:23:52 +00:00
- **ps_args** – `ps` arguments to use (e.g., `aux` ), defaults to `-ef`
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **404** – no such container
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Get container logs
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`GET /containers/(id or name)/logs`
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
Get `stdout` and `stderr` logs from the container ``id``
2015-02-10 18:48:54 +00:00
2015-02-06 00:24:47 +00:00
> **Note**:
Add log reading to the journald log driver
If a logdriver doesn't register a callback function to validate log
options, it won't be usable. Fix the journald driver by adding a dummy
validator.
Teach the client and the daemon's "logs" logic that the server can also
supply "logs" data via the "journald" driver. Update documentation and
tests that depend on error messages.
Add support for reading log data from the systemd journal to the
journald log driver. The internal logic uses a goroutine to scan the
journal for matching entries after any specified cutoff time, formats
the messages from those entries as JSONLog messages, and stuffs the
results down a pipe whose reading end we hand back to the caller.
If we are missing any of the 'linux', 'cgo', or 'journald' build tags,
however, we don't implement a reader, so the 'logs' endpoint will still
return an error.
Make the necessary changes to the build setup to ensure that support for
reading container logs from the systemd journal is built.
Rename the Jmap member of the journald logdriver's struct to "vars" to
make it non-public, and to make it easier to tell that it's just there
to hold additional variable values that we want journald to record along
with log data that we're sending to it.
In the client, don't assume that we know which logdrivers the server
implements, and remove the check that looks at the server. It's
redundant because the server already knows, and the check also makes
using older clients with newer servers (which may have new logdrivers in
them) unnecessarily hard.
When we try to "logs" and have to report that the container's logdriver
doesn't support reading, send the error message through the
might-be-a-multiplexer so that clients which are expecting multiplexed
data will be able to properly display the error, instead of tripping
over the data and printing a less helpful "Unrecognized input header"
error.
Signed-off-by: Nalin Dahyabhai <nalin@redhat.com> (github: nalind)
2015-07-23 15:02:56 +00:00
> This endpoint works only for containers with the `json-file` or `journald` logging drivers.
2015-02-06 00:24:47 +00:00
2015-02-10 18:48:54 +00:00
**Example request**:
2016-10-27 16:59:59 +00:00
GET /v1.18/containers/4fa6e0f0c678/logs?stderr=1& stdout=1& timestamps=1& follow=1& tail=10 HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp
2015-02-10 18:48:54 +00:00
2016-10-19 17:25:45 +00:00
{% raw %}
2016-08-04 13:12:57 +00:00
{{ STREAM }}
2016-10-19 17:25:45 +00:00
{% endraw %}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
2016-08-14 00:08:05 +00:00
- **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` .
2015-02-10 18:48:54 +00:00
- **timestamps** – 1/True/true or 0/False/false, print timestamps for
2016-08-14 00:08:05 +00:00
every log line. Default `false` .
- **tail** – Output specified number of lines at the end of logs: `all` or `<number>` . Default all.
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **101** – no error, hints proxy about hijacking
- **200** – no error, no upgrade header found
- **404** – no such container
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Inspect changes on a container's filesystem
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`GET /containers/(id or name)/changes`
2015-02-10 18:48:54 +00:00
Inspect changes on container `id` 's filesystem
**Example request**:
2016-10-27 16:59:59 +00:00
GET /v1.18/containers/4fa6e0f0c678/changes HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
[
{
"Path": "/dev",
"Kind": 0
},
{
"Path": "/dev/kmsg",
"Kind": 1
},
{
"Path": "/test",
"Kind": 1
}
]
2015-02-10 18:48:54 +00:00
2015-03-06 03:36:56 +00:00
Values for `Kind` :
- `0` : Modify
- `1` : Add
- `2` : Delete
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **404** – no such container
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Export a container
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`GET /containers/(id or name)/export`
2015-02-10 18:48:54 +00:00
Export the contents of container `id`
**Example request**:
2016-10-27 16:59:59 +00:00
GET /v1.18/containers/4fa6e0f0c678/export HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/octet-stream
2015-02-10 18:48:54 +00:00
2016-10-19 17:25:45 +00:00
{% raw %}
2016-08-04 13:12:57 +00:00
{{ TAR STREAM }}
2016-10-19 17:25:45 +00:00
{% endraw %}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **404** – no such container
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Get container stats based on resource usage
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`GET /containers/(id or name)/stats`
2015-02-10 18:48:54 +00:00
This endpoint returns a live stream of a container's resource usage statistics.
**Example request**:
2016-10-27 16:59:59 +00:00
GET /v1.18/containers/redis1/stats HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-14 00:08:05 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-08-14 00:08:05 +00:00
{
"read" : "2015-01-08T22:57:31.547920715Z",
"network" : {
"rx_dropped" : 0,
"rx_bytes" : 648,
"rx_errors" : 0,
"tx_packets" : 8,
"tx_dropped" : 0,
"rx_packets" : 8,
"tx_errors" : 0,
"tx_bytes" : 648
},
"memory_stats" : {
"stats" : {
"total_pgmajfault" : 0,
"cache" : 0,
"mapped_file" : 0,
"total_inactive_file" : 0,
"pgpgout" : 414,
"rss" : 6537216,
"total_mapped_file" : 0,
"writeback" : 0,
"unevictable" : 0,
"pgpgin" : 477,
"total_unevictable" : 0,
"pgmajfault" : 0,
"total_rss" : 6537216,
"total_rss_huge" : 6291456,
"total_writeback" : 0,
"total_inactive_anon" : 0,
"rss_huge" : 6291456,
"hierarchical_memory_limit" : 67108864,
"total_pgfault" : 964,
"total_active_file" : 0,
"active_anon" : 6537216,
"total_active_anon" : 6537216,
"total_pgpgout" : 414,
"total_cache" : 0,
"inactive_anon" : 0,
"active_file" : 0,
"pgfault" : 964,
"inactive_file" : 0,
"total_pgpgin" : 477
},
"max_usage" : 6651904,
"usage" : 6537216,
"failcnt" : 0,
"limit" : 67108864
},
"blkio_stats" : {},
"cpu_stats" : {
"cpu_usage" : {
"percpu_usage" : [
16970827,
1839451,
7107380,
10571290
],
"usage_in_usermode" : 10000000,
"total_usage" : 36488948,
"usage_in_kernelmode" : 20000000
},
"system_cpu_usage" : 20091722000000000,
"throttling_data" : {}
}
}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **404** – no such container
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Resize a container TTY
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`POST /containers/(id or name)/resize?h=<height>&w=<width>`
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
Resize the TTY for container with `id` . You must restart the container for the resize to take effect.
2015-02-10 18:48:54 +00:00
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/containers/4fa6e0f0c678/resize?h=40& w=80 HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: text/plain; charset=utf-8
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
- **h** – height of `tty` session
- **w** – width
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **404** – No such container
- **500** – Cannot resize container
2016-11-25 10:30:03 +00:00
#### Start a container
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`POST /containers/(id or name)/start`
2015-02-10 18:48:54 +00:00
Start the container `id`
2015-05-30 21:19:59 +00:00
> **Note**:
> For backwards compatibility, this endpoint accepts a `HostConfig` as JSON-encoded request body.
> See [create a container](#create-a-container) for details.
2015-02-10 18:48:54 +00:00
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/containers/e90e34656806/start HTTP/1.1
2015-04-09 03:07:03 +00:00
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 204 No Content
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **204** – no error
- **304** – container already started
- **404** – no such container
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Stop a container
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`POST /containers/(id or name)/stop`
2015-02-10 18:48:54 +00:00
Stop the container `id`
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/containers/e90e34656806/stop?t=5 HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 204 No Content
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
- **t** – number of seconds to wait before killing the container
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **204** – no error
- **304** – container already stopped
- **404** – no such container
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Restart a container
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`POST /containers/(id or name)/restart`
2015-02-10 18:48:54 +00:00
Restart the container `id`
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/containers/e90e34656806/restart?t=5 HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 204 No Content
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
- **t** – number of seconds to wait before killing the container
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **204** – no error
- **404** – no such container
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Kill a container
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`POST /containers/(id or name)/kill`
2015-02-10 18:48:54 +00:00
Kill the container `id`
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/containers/e90e34656806/kill HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 204 No Content
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
- **signal** - Signal to send to the container: integer or string like `SIGINT` .
When not set, `SIGKILL` is assumed and the call waits for the container to exit.
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **204** – no error
- **404** – no such container
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Rename a container
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`POST /containers/(id or name)/rename`
2015-02-10 18:48:54 +00:00
Rename the container `id` to a `new_name`
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/containers/e90e34656806/rename?name=new_name HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 204 No Content
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
- **name** – new name for the container
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **204** – no error
- **404** – no such container
- **409** - conflict name already assigned
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Pause a container
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`POST /containers/(id or name)/pause`
2015-02-10 18:48:54 +00:00
Pause the container `id`
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/containers/e90e34656806/pause HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 204 No Content
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **204** – no error
- **404** – no such container
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Unpause a container
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`POST /containers/(id or name)/unpause`
2015-02-10 18:48:54 +00:00
Unpause the container `id`
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/containers/e90e34656806/unpause HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 204 No Content
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **204** – no error
- **404** – no such container
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Attach to a container
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`POST /containers/(id or name)/attach`
2015-02-10 18:48:54 +00:00
Attach to the container `id`
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/containers/16253994b7c4/attach?logs=1& stream=0& stdout=1 HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.docker.raw-stream
Connection: Upgrade
Upgrade: tcp
2015-02-10 18:48:54 +00:00
2016-10-19 17:25:45 +00:00
{% raw %}
2016-08-04 13:12:57 +00:00
{{ STREAM }}
2016-10-19 17:25:45 +00:00
{% endraw %}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
- **logs** – 1/True/true or 0/False/false, return logs. Default `false` .
2015-02-10 18:48:54 +00:00
- **stream** – 1/True/true or 0/False/false, return stream.
2016-08-04 13:12:57 +00:00
Default `false` .
- **stdin** – 1/True/true or 0/False/false, if `stream=true` , attach
to `stdin` . Default `false` .
- **stdout** – 1/True/true or 0/False/false, if `logs=true` , return
`stdout` log, if `stream=true` , attach to `stdout` . Default `false` .
- **stderr** – 1/True/true or 0/False/false, if `logs=true` , return
`stderr` log, if `stream=true` , attach to `stderr` . Default `false` .
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **101** – no error, hints proxy about hijacking
- **200** – no error, no upgrade header found
- **400** – bad parameter
- **404** – no such container
- **500** – server error
2016-09-17 01:02:12 +00:00
**Stream details**:
2015-02-10 18:48:54 +00:00
2016-09-17 01:02:12 +00:00
When using the TTY setting is enabled in
[`POST /containers/create`
](#create-a-container),
the stream is the raw data from the process PTY and client's `stdin` .
When the TTY is disabled, then the stream is multiplexed to separate
`stdout` and `stderr` .
2015-02-10 18:48:54 +00:00
2016-09-17 01:02:12 +00:00
The format is a **Header** and a **Payload** (frame).
2015-02-10 18:48:54 +00:00
2016-09-17 01:02:12 +00:00
**HEADER**
2015-02-10 18:48:54 +00:00
2016-09-17 01:02:12 +00:00
The header contains the information which the stream writes (`stdout` or
`stderr` ). It also contains the size of the associated frame encoded in the
last four bytes (`uint32`).
2015-02-10 18:48:54 +00:00
2016-09-17 01:02:12 +00:00
It is encoded on the first eight bytes like this:
2015-02-10 18:48:54 +00:00
2016-09-17 01:02:12 +00:00
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
2015-02-10 18:48:54 +00:00
2016-09-17 01:02:12 +00:00
`STREAM_TYPE` can be:
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
- 0: `stdin` (is written on `stdout` )
- 1: `stdout`
- 2: `stderr`
2015-02-10 18:48:54 +00:00
2016-09-17 01:02:12 +00:00
`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of
the `uint32` size encoded as big endian.
2015-02-10 18:48:54 +00:00
2016-09-17 01:02:12 +00:00
**PAYLOAD**
2015-02-10 18:48:54 +00:00
2016-09-17 01:02:12 +00:00
The payload is the raw stream.
2015-02-10 18:48:54 +00:00
2016-09-17 01:02:12 +00:00
**IMPLEMENTATION**
2015-02-10 18:48:54 +00:00
2016-09-17 01:02:12 +00:00
The simplest way to implement the Attach protocol is the following:
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
1. Read eight bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.
2015-02-10 18:48:54 +00:00
2016-11-25 10:30:03 +00:00
#### Attach to a container (websocket)
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`GET /containers/(id or name)/attach/ws`
2015-02-10 18:48:54 +00:00
Attach to the container `id` via websocket
Implements websocket protocol handshake according to [RFC 6455 ](http://tools.ietf.org/html/rfc6455 )
**Example request**
2016-10-27 16:59:59 +00:00
GET /v1.18/containers/e90e34656806/attach/ws?logs=0& stream=1& stdin=1& stdout=1& stderr=1 HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**
2016-10-19 17:25:45 +00:00
{% raw %}
2016-08-04 13:12:57 +00:00
{{ STREAM }}
2016-10-19 17:25:45 +00:00
{% endraw %}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
- **logs** – 1/True/true or 0/False/false, return logs. Default `false` .
2015-02-10 18:48:54 +00:00
- **stream** – 1/True/true or 0/False/false, return stream.
2016-08-04 13:12:57 +00:00
Default `false` .
- **stdin** – 1/True/true or 0/False/false, if `stream=true` , attach
to `stdin` . Default `false` .
- **stdout** – 1/True/true or 0/False/false, if `logs=true` , return
`stdout` log, if `stream=true` , attach to `stdout` . Default `false` .
- **stderr** – 1/True/true or 0/False/false, if `logs=true` , return
`stderr` log, if `stream=true` , attach to `stderr` . Default `false` .
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **400** – bad parameter
- **404** – no such container
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Wait a container
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`POST /containers/(id or name)/wait`
2015-02-10 18:48:54 +00:00
Block until container `id` stops, then returns the exit code
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/containers/16253994b7c4/wait HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
{"StatusCode": 0}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **404** – no such container
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Remove a container
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`DELETE /containers/(id or name)`
2015-02-10 18:48:54 +00:00
Remove the container `id` from the filesystem
**Example request**:
2016-11-12 21:09:08 +00:00
DELETE /v1.18/containers/16253994b7c4?v=1 HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 204 No Content
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
- **v** – 1/True/true or 0/False/false, Remove the volumes
2016-08-04 13:12:57 +00:00
associated to the container. Default `false` .
2015-02-10 18:48:54 +00:00
- **force** - 1/True/true or 0/False/false, Kill then remove the container.
2016-08-04 13:12:57 +00:00
Default `false` .
2017-02-10 04:56:40 +00:00
- **link** - 1/True/true or 0/False/false, Remove the specified
link associated to the container. Default `false` .
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **204** – no error
- **400** – bad parameter
- **404** – no such container
2016-07-14 09:21:05 +00:00
- **409** – conflict
2015-02-10 18:48:54 +00:00
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Copy files or folders from a container
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`POST /containers/(id or name)/copy`
2015-02-10 18:48:54 +00:00
Copy files or folders of container `id`
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/containers/4fa6e0f0c678/copy HTTP/1.1
2016-08-04 13:12:57 +00:00
Content-Type: application/json
2017-10-08 17:48:55 +00:00
Content-Length: 12345
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
{
"Resource": "test.txt"
}
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/x-tar
2015-02-10 18:48:54 +00:00
2016-10-19 17:25:45 +00:00
{% raw %}
2016-08-04 13:12:57 +00:00
{{ TAR STREAM }}
2016-10-19 17:25:45 +00:00
{% endraw %}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **404** – no such container
- **500** – server error
2016-11-25 10:30:03 +00:00
### 2.2 Images
2015-02-10 18:48:54 +00:00
2016-11-25 10:30:03 +00:00
#### List Images
2015-02-10 18:48:54 +00:00
`GET /images/json`
**Example request**:
2016-10-27 16:59:59 +00:00
GET /v1.18/images/json?all=0 HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
[
{
"RepoTags": [
"ubuntu:12.04",
"ubuntu:precise",
"ubuntu:latest"
],
"Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c",
"Created": 1365714795,
"Size": 131506275,
"VirtualSize": 131506275
},
{
"RepoTags": [
"ubuntu:12.10",
"ubuntu:quantal"
],
"ParentId": "27cf784147099545",
"Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
"Created": 1364102658,
"Size": 24653,
"VirtualSize": 180116135
}
]
2015-02-10 18:48:54 +00:00
2015-02-27 02:23:50 +00:00
**Example request, with digest information**:
2016-10-27 16:59:59 +00:00
GET /v1.18/images/json?digests=1 HTTP/1.1
2015-02-27 02:23:50 +00:00
**Example response, with digest information**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
2015-02-27 02:23:50 +00:00
2016-08-04 13:12:57 +00:00
[
{
"Created": 1420064636,
"Id": "4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125",
"ParentId": "ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2",
"RepoDigests": [
"localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d422812b6a5adff7dfee951d8fa2e4a98caa0382cfbdbf"
],
"RepoTags": [
"localhost:5000/test/busybox:latest",
"playdate:latest"
],
"Size": 0,
"VirtualSize": 2429728
}
]
2015-02-27 02:23:50 +00:00
The response shows a single image `Id` associated with two repositories
(`RepoTags`): `localhost:5000/test/busybox` : and `playdate` . A caller can use
either of the `RepoTags` values `localhost:5000/test/busybox:latest` or
`playdate:latest` to reference the image.
You can also use `RepoDigests` values to reference an image. In this response,
the array has only one reference and that is to the
`localhost:5000/test/busybox` repository; the `playdate` repository has no
digest. You can reference this digest using the value:
`localhost:5000/test/busybox@sha256:cbbf2f9a99b47fc460d...`
See the `docker run` and `docker build` commands for examples of digest and tag
references on the command line.
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
- **all** – 1/True/true or 0/False/false, default false
2016-08-04 13:12:57 +00:00
- **filters** – a JSON encoded value of the filters (a map[string][]string) to process on the images list. Available filters:
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
2015-07-23 12:29:09 +00:00
- **filter** - only return images with the specified name
2015-02-10 18:48:54 +00:00
2016-11-25 10:30:03 +00:00
#### Build image from a Dockerfile
2015-02-10 18:48:54 +00:00
`POST /build`
Build an image from a Dockerfile
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/build HTTP/1.1
2016-12-06 21:15:27 +00:00
Content-Type: application/x-tar
2015-02-10 18:48:54 +00:00
2016-10-19 17:25:45 +00:00
{% raw %}
2016-08-04 13:12:57 +00:00
{{ TAR STREAM }}
2016-10-19 17:25:45 +00:00
{% endraw %}
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-11-06 02:05:19 +00:00
{"stream": "Step 1/5..."}
2016-08-04 13:12:57 +00:00
{"stream": "..."}
{"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
The input stream must be a `tar` archive compressed with one of the
following algorithms: `identity` (no compression), `gzip` , `bzip2` , `xz` .
2015-02-10 18:48:54 +00:00
The archive must include a build instructions file, typically called
2016-08-04 13:12:57 +00:00
`Dockerfile` at the archive's root. The `dockerfile` parameter may be
used to specify a different build instructions file. To do this, its value must be
2015-02-10 18:48:54 +00:00
the path to the alternate build instructions file to use.
The archive may include any number of other files,
2016-08-04 13:12:57 +00:00
which are accessible in the build context (See the [*ADD build
2020-04-09 11:44:51 +00:00
command*](https://docs.docker.com/engine/reference/builder/#add)).
2015-02-10 18:48:54 +00:00
2016-09-22 00:42:53 +00:00
The Docker daemon performs a preliminary validation of the `Dockerfile` before
starting the build, and returns an error if the syntax is incorrect. After that,
each instruction is run one-by-one until the ID of the new image is output.
2016-08-04 13:12:57 +00:00
The build is canceled if the client drops the connection by quitting
2015-03-10 22:10:00 +00:00
or being killed.
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
- **dockerfile** - Path within the build context to the Dockerfile. This is
2015-02-17 18:25:36 +00:00
ignored if `remote` is specified and points to an individual filename.
2016-08-14 00:08:05 +00:00
- **t** – A name and optional tag to apply to the image in the `name:tag` format.
If you omit the `tag` the default `latest` value is assumed.
- **remote** – A Git repository URI or HTTP/HTTPS context URI. If the
URI points to a single text file, the file's contents are placed into
a file called `Dockerfile` and the image is built from that file.
- **q** – Suppress verbose build output.
- **nocache** – Do not use the cache when building the image.
- **pull** - Attempt to pull the image even if an older image exists locally.
- **rm** - Remove intermediate containers after a successful build (default behavior).
- **forcerm** - Always remove intermediate containers (includes `rm` ).
- **memory** - Set memory limit for build.
2016-02-02 13:49:14 +00:00
- **memswap** - Total memory (memory + swap), `-1` to enable unlimited swap.
2016-08-14 00:08:05 +00:00
- **cpushares** - CPU shares (relative weight).
- **cpusetcpus** - CPUs in which to allow execution (e.g., `0-3` , `0,1` ).
2015-02-10 18:48:54 +00:00
2016-08-14 00:08:05 +00:00
**Request Headers**:
2015-02-10 18:48:54 +00:00
2016-12-06 21:15:27 +00:00
- **Content-type** – Set to `"application/x-tar"` .
2015-04-25 18:57:01 +00:00
- **X-Registry-Config** – base64-encoded ConfigFile object
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Create an image
2015-02-10 18:48:54 +00:00
`POST /images/create`
2016-08-14 00:08:05 +00:00
Create an image either by pulling it from the registry or by importing it
2015-02-10 18:48:54 +00:00
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/images/create?fromImage=busybox& tag=latest HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
{"status": "Pulling..."}
{"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}}
{"error": "Invalid..."}
...
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
When using this endpoint to pull an image from the registry, the
`X-Registry-Auth` header can be used to include
a base64-encoded AuthConfig object.
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
- **fromImage** – Name of the image to pull.
- **fromSrc** – Source to import. The value may be a URL from which the image
2015-02-10 18:48:54 +00:00
can be retrieved or `-` to read the image from the request body.
2016-08-04 13:12:57 +00:00
- **repo** – Repository name.
2016-09-16 09:02:08 +00:00
- **tag** – Tag. If empty when pulling an image, this causes all tags
for the given image to be pulled.
2015-02-10 18:48:54 +00:00
2016-08-14 00:08:05 +00:00
**Request Headers**:
2015-02-10 18:48:54 +00:00
- **X-Registry-Auth** – base64-encoded AuthConfig object
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
2016-12-02 09:05:03 +00:00
- **404** - repository does not exist or no read access
2015-02-10 18:48:54 +00:00
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Inspect an image
2015-02-10 18:48:54 +00:00
`GET /images/(name)/json`
Return low-level information on the image `name`
**Example request**:
2016-10-27 16:59:59 +00:00
GET /v1.18/images/ubuntu/json HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
{
2016-08-14 00:08:05 +00:00
"Created": "2013-03-23T22:24:18.818426-07:00",
"Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0",
"ContainerConfig": {
"Hostname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": false,
"AttachStderr": false,
"Tty": true,
"OpenStdin": true,
"StdinOnce": false,
"Env": null,
"Cmd": ["/bin/bash"],
"Dns": null,
"Image": "ubuntu",
"Labels": {
"com.example.vendor": "Acme",
"com.example.license": "GPL",
"com.example.version": "1.0"
},
"Volumes": null,
"VolumesFrom": "",
"WorkingDir": ""
},
"Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc",
"Parent": "27cf784147099545",
"Size": 6824592
2016-08-04 13:12:57 +00:00
}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **404** – no such image
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Get the history of an image
2015-02-10 18:48:54 +00:00
`GET /images/(name)/history`
Return the history of the image `name`
**Example request**:
2016-10-27 16:59:59 +00:00
GET /v1.18/images/ubuntu/history HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
[
2016-08-14 00:08:05 +00:00
{
"Id": "b750fe79269d",
"Created": 1364102658,
"CreatedBy": "/bin/bash"
},
{
"Id": "27cf78414709",
"Created": 1364068391,
"CreatedBy": ""
}
2016-08-04 13:12:57 +00:00
]
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **404** – no such image
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Push an image on the registry
2015-02-10 18:48:54 +00:00
`POST /images/(name)/push`
Push the image `name` on the registry
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/images/test/push HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
{"status": "Pushing..."}
{"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}}
{"error": "Invalid..."}
...
2015-02-10 18:48:54 +00:00
2016-08-14 00:08:05 +00:00
If you wish to push an image on to a private registry, that image must already have a tag
into a repository which references that registry `hostname` and `port` . This repository name should
then be used in the URL. This duplicates the command line's flow.
2015-02-10 18:48:54 +00:00
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/images/registry.acme.com:5000/test/push HTTP/1.1
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
- **tag** – The tag to associate with the image on the registry. This is optional.
2015-02-10 18:48:54 +00:00
2016-08-14 00:08:05 +00:00
**Request Headers**:
2015-02-10 18:48:54 +00:00
2016-08-14 00:08:05 +00:00
- **X-Registry-Auth** – base64-encoded AuthConfig object.
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **404** – no such image
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Tag an image into a repository
2015-02-10 18:48:54 +00:00
`POST /images/(name)/tag`
Tag the image `name` into a repository
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/images/test/tag?repo=myrepo& force=0& tag=v42 HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 201 Created
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
- **repo** – The repository to tag in
- **force** – 1/True/true or 0/False/false, default false
- **tag** - The new tag name
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **201** – no error
- **400** – bad parameter
- **404** – no such image
- **409** – conflict
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Remove an image
2015-02-10 18:48:54 +00:00
`DELETE /images/(name)`
Remove the image `name` from the filesystem
**Example request**:
2016-11-12 21:09:08 +00:00
DELETE /v1.18/images/test HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-type: application/json
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
[
{"Untagged": "3e2f21a89f"},
{"Deleted": "3e2f21a89f"},
{"Deleted": "53b4f83ac9"}
]
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
- **force** – 1/True/true or 0/False/false, default false
- **noprune** – 1/True/true or 0/False/false, default false
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **404** – no such image
- **409** – conflict
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Search images
2015-02-10 18:48:54 +00:00
`GET /images/search`
Search for an image on [Docker Hub ](https://hub.docker.com ).
> **Note**:
> The response keys have changed from API v1.6 to reflect the JSON
> sent by the registry server to the docker daemon's request.
**Example request**:
2016-10-27 16:59:59 +00:00
GET /v1.18/images/search?term=sshd HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
[
{
2016-08-14 00:08:05 +00:00
"star_count": 12,
2016-08-04 13:12:57 +00:00
"is_official": false,
"name": "wma55/u1210sshd",
2016-08-14 00:08:05 +00:00
"is_automated": false,
"description": ""
2016-08-04 13:12:57 +00:00
},
{
2016-08-14 00:08:05 +00:00
"star_count": 10,
2016-08-04 13:12:57 +00:00
"is_official": false,
"name": "jdswinbank/sshd",
2016-08-14 00:08:05 +00:00
"is_automated": false,
"description": ""
2016-08-04 13:12:57 +00:00
},
{
2016-08-14 00:08:05 +00:00
"star_count": 18,
2016-08-04 13:12:57 +00:00
"is_official": false,
"name": "vgauthier/sshd",
2016-08-14 00:08:05 +00:00
"is_automated": false,
"description": ""
2016-08-04 13:12:57 +00:00
}
...
]
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
- **term** – term to search
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **500** – server error
2016-11-25 10:30:03 +00:00
### 2.3 Misc
2015-02-10 18:48:54 +00:00
2016-11-25 10:30:03 +00:00
#### Check auth configuration
2015-02-10 18:48:54 +00:00
`POST /auth`
Get the default username and email
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/auth HTTP/1.1
2016-08-04 13:12:57 +00:00
Content-Type: application/json
2017-10-08 17:48:55 +00:00
Content-Length: 12345
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
{
2016-08-14 00:08:05 +00:00
"username": "hannibal",
"password": "xxxx",
2016-08-04 13:12:57 +00:00
"email": "hannibal@a-team.com",
"serveraddress": "https://index.docker.io/v1/"
}
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **204** – no error
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Display system-wide information
2015-02-10 18:48:54 +00:00
`GET /info`
Display system-wide information
**Example request**:
2016-10-27 16:59:59 +00:00
GET /v1.18/info HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
{
"Containers": 11,
"Debug": 0,
"DockerRootDir": "/var/lib/docker",
"Driver": "btrfs",
"DriverStatus": [[""]],
"ExecutionDriver": "native-0.1",
"HttpProxy": "http://test:test@localhost:8080",
"HttpsProxy": "https://test:test@localhost:8080",
"ID": "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS",
"IPv4Forwarding": 1,
"Images": 16,
"IndexServerAddress": "https://index.docker.io/v1/",
"InitPath": "/usr/bin/docker",
"InitSha1": "",
"KernelVersion": "3.12.0-1-amd64",
"Labels": [
"storage=ssd"
],
"MemTotal": 2099236864,
"MemoryLimit": 1,
"NCPU": 1,
"NEventsListener": 0,
"NFd": 11,
"NGoroutines": 21,
"Name": "prod-server-42",
"NoProxy": "9.81.1.160",
"OperatingSystem": "Boot2Docker",
"RegistryConfig": {
"IndexConfigs": {
"docker.io": {
"Mirrors": null,
"Name": "docker.io",
"Official": true,
"Secure": true
}
2015-05-18 17:43:02 +00:00
},
2016-08-04 13:12:57 +00:00
"InsecureRegistryCIDRs": [
"127.0.0.0/8"
]
},
"SwapLimit": 0,
"SystemTime": "2015-03-10T11:11:23.730591467-07:00"
}
2016-02-21 02:28:07 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Show the docker version information
2015-02-10 18:48:54 +00:00
`GET /version`
Show the docker version information
**Example request**:
2016-10-27 16:59:59 +00:00
GET /v1.18/version HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
{
"Version": "1.5.0",
"Os": "linux",
"KernelVersion": "3.18.5-tinycore64",
"GoVersion": "go1.4.1",
"GitCommit": "a8a31ef",
"Arch": "amd64",
"ApiVersion": "1.18"
}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Ping the docker server
2015-02-10 18:48:54 +00:00
`GET /_ping`
Ping the docker server
**Example request**:
2016-10-27 16:59:59 +00:00
GET /v1.18/_ping HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: text/plain
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
OK
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** - no error
- **500** - server error
2016-11-25 10:30:03 +00:00
#### Create a new image from a container's changes
2015-02-10 18:48:54 +00:00
`POST /commit`
Create a new image from a container's changes
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/commit?container=44c004db4b17& comment=message& repo=myrepo HTTP/1.1
2016-08-04 13:12:57 +00:00
Content-Type: application/json
2017-10-08 17:48:55 +00:00
Content-Length: 12345
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"PortSpecs": null,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": null,
"Cmd": [
"date"
],
"Volumes": {
"/tmp": {}
},
"WorkingDir": "",
"NetworkDisabled": false,
"ExposedPorts": {
"22/tcp": {}
}
}
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 201 Created
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
{"Id": "596069db4bf5"}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**JSON parameters**:
2015-02-10 18:48:54 +00:00
- **config** - the container's configuration
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
- **container** – source container
- **repo** – repository
- **tag** – tag
- **comment** – commit message
- **author** – author (e.g., "John Hannibal Smith
< [hannibal@a-team.com](mailto:hannibal%40a-team.com)>")
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **201** – no error
- **404** – no such container
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Monitor Docker's events
2015-02-10 18:48:54 +00:00
`GET /events`
2016-08-10 20:45:25 +00:00
Get container events from docker, in real time via streaming.
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
Docker containers report the following events:
2015-02-10 18:48:54 +00:00
create, destroy, die, exec_create, exec_start, export, kill, oom, pause, restart, start, stop, unpause
2016-08-14 00:08:05 +00:00
Docker images report the following events:
2015-02-10 18:48:54 +00:00
untag, delete
**Example request**:
2016-11-12 21:09:08 +00:00
GET /v1.18/events?since=1374067924
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
{"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924}
{"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924}
{"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966}
{"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
2016-08-10 20:45:25 +00:00
- **since** – Timestamp. Show all events created since timestamp and then stream
- **until** – Timestamp. Show events created until given timestamp and stop streaming
2016-08-04 13:12:57 +00:00
- **filters** – A json encoded value of the filters (a map[string][]string) to process on the event list. Available filters:
- `container=<string>` ; -- container to filter
- `event=<string>` ; -- event to filter
- `image=<string>` ; -- image to filter
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Get a tarball containing all images in a repository
2015-02-10 18:48:54 +00:00
`GET /images/(name)/get`
Get a tarball containing all images and metadata for the repository specified
by `name` .
If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image
2015-04-25 18:57:01 +00:00
(and its parents) are returned. If `name` is an image ID, similarly only that
2015-02-10 18:48:54 +00:00
image (and its parents) are returned, but with the exclusion of the
'repositories' file in the tarball, as there were no image names referenced.
See the [image tarball format ](#image-tarball-format ) for more details.
**Example request**
2016-11-12 21:09:08 +00:00
GET /v1.18/images/ubuntu/get
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/x-tar
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
Binary data stream
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Get a tarball containing all images
2015-02-10 18:48:54 +00:00
`GET /images/get`
Get a tarball containing all images and metadata for one or more repositories.
For each value of the `names` parameter: if it is a specific name and tag (e.g.
2016-08-04 13:12:57 +00:00
`ubuntu:latest` ), then only that image (and its parents) are returned; if it is
2015-02-10 18:48:54 +00:00
an image ID, similarly only that image (and its parents) are returned and there
would be no names referenced in the 'repositories' file for this image ID.
See the [image tarball format ](#image-tarball-format ) for more details.
**Example request**
2016-11-12 21:09:08 +00:00
GET /v1.18/images/get?names=myname%2Fmyapp%3Alatest& names=busybox
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/x-tar
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
Binary data stream
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Load a tarball with a set of images and tags into docker
2015-02-10 18:48:54 +00:00
`POST /images/load`
2016-08-04 13:12:57 +00:00
Load a set of images and tags into a Docker repository.
2015-02-10 18:48:54 +00:00
See the [image tarball format ](#image-tarball-format ) for more details.
**Example request**
2016-11-12 21:09:08 +00:00
POST /v1.18/images/load
2016-08-09 08:56:49 +00:00
Content-Type: application/x-tar
2017-10-08 17:48:55 +00:00
Content-Length: 12345
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
Tarball in body
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **500** – server error
2016-11-25 10:30:03 +00:00
#### Image tarball format
2015-02-10 18:48:54 +00:00
An image tarball contains one directory per image layer (named using its long ID),
2016-08-04 13:12:57 +00:00
each containing these files:
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
- `VERSION` : currently `1.0` - the file format version
- `json` : detailed layer information, similar to `docker inspect layer_id`
- `layer.tar` : A tarfile containing the filesystem changes in this layer
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
The `layer.tar` file contains `aufs` style `.wh..wh.aufs` files and directories
2015-02-10 18:48:54 +00:00
for storing attribute changes and deletions.
2016-08-04 13:12:57 +00:00
If the tarball defines a repository, the tarball should also include a `repositories` file at
2015-02-10 18:48:54 +00:00
the root that contains a list of repository and tag names mapped to layer IDs.
```
{"hello-world":
{"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"}
}
```
2016-11-25 10:30:03 +00:00
#### Exec Create
2015-02-10 18:48:54 +00:00
2016-02-21 02:28:07 +00:00
`POST /containers/(id or name)/exec`
2015-02-10 18:48:54 +00:00
Sets up an exec instance in a running container `id`
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/containers/e90e34656806/exec HTTP/1.1
2016-08-04 13:12:57 +00:00
Content-Type: application/json
2017-10-08 17:48:55 +00:00
Content-Length: 12345
2015-02-10 18:48:54 +00:00
2016-09-22 21:26:49 +00:00
{
"AttachStdin": true,
"AttachStdout": true,
"AttachStderr": true,
"Cmd": ["sh"],
"Tty": true
}
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 201 Created
Content-Type: application/json
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
{
"Id": "f90e34656806",
"Warnings":[]
}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**JSON parameters**:
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
- **AttachStdin** - Boolean value, attaches to `stdin` of the `exec` command.
- **AttachStdout** - Boolean value, attaches to `stdout` of the `exec` command.
- **AttachStderr** - Boolean value, attaches to `stderr` of the `exec` command.
- **Tty** - Boolean value to allocate a pseudo-TTY.
2015-02-10 18:48:54 +00:00
- **Cmd** - Command to run specified as a string or an array of strings.
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **201** – no error
- **404** – no such container
2016-11-25 10:30:03 +00:00
#### Exec Start
2015-02-10 18:48:54 +00:00
`POST /exec/(id)/start`
2016-08-04 13:12:57 +00:00
Starts a previously set up `exec` instance `id` . If `detach` is true, this API
2015-02-10 18:48:54 +00:00
returns after starting the `exec` command. Otherwise, this API sets up an
interactive session with the `exec` command.
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/exec/e90e34656806/start HTTP/1.1
2016-08-04 13:12:57 +00:00
Content-Type: application/json
2017-10-08 17:48:55 +00:00
Content-Length: 12345
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
{
"Detach": false,
"Tty": false
}
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: application/vnd.docker.raw-stream
2015-02-10 18:48:54 +00:00
2016-10-19 17:25:45 +00:00
{% raw %}
2016-08-04 13:12:57 +00:00
{{ STREAM }}
2016-10-19 17:25:45 +00:00
{% endraw %}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**JSON parameters**:
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
- **Detach** - Detach from the `exec` command.
- **Tty** - Boolean value to allocate a pseudo-TTY.
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
2015-09-12 02:50:21 +00:00
- **200** – no error
2015-02-10 18:48:54 +00:00
- **404** – no such exec instance
2016-09-17 01:02:12 +00:00
**Stream details**:
Similar to the stream behavior of `POST /containers/(id or name)/attach` API
2015-02-10 18:48:54 +00:00
2016-11-25 10:30:03 +00:00
#### Exec Resize
2015-02-10 18:48:54 +00:00
`POST /exec/(id)/resize`
2016-08-04 13:12:57 +00:00
Resizes the `tty` session used by the `exec` command `id` . The unit is number of characters.
This API is valid only if `tty` was specified as part of creating and starting the `exec` command.
2015-02-10 18:48:54 +00:00
**Example request**:
2016-10-27 16:59:59 +00:00
POST /v1.18/exec/e90e34656806/resize?h=40& w=80 HTTP/1.1
2016-08-04 13:12:57 +00:00
Content-Type: text/plain
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 201 Created
Content-Type: text/plain
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Query parameters**:
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
- **h** – height of `tty` session
2015-02-10 18:48:54 +00:00
- **w** – width
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **201** – no error
- **404** – no such exec instance
2016-11-25 10:30:03 +00:00
#### Exec Inspect
2015-02-10 18:48:54 +00:00
`GET /exec/(id)/json`
2016-08-04 13:12:57 +00:00
Return low-level information about the `exec` command `id` .
2015-02-10 18:48:54 +00:00
**Example request**:
2016-10-27 16:59:59 +00:00
GET /v1.18/exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1
2015-02-10 18:48:54 +00:00
**Example response**:
2016-08-04 13:12:57 +00:00
HTTP/1.1 200 OK
Content-Type: plain/text
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
{
"ID" : "11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39",
"Running" : false,
"ExitCode" : 2,
"ProcessConfig" : {
"privileged" : false,
"user" : "",
"tty" : false,
"entrypoint" : "sh",
"arguments" : [
"-c",
"exit 2"
]
},
"OpenStdin" : false,
"OpenStderr" : false,
"OpenStdout" : false,
"Container" : {
"State" : {
"Running" : true,
"Paused" : false,
"Restarting" : false,
"OOMKilled" : false,
"Pid" : 3650,
"ExitCode" : 0,
"Error" : "",
"StartedAt" : "2014-11-17T22:26:03.717657531Z",
"FinishedAt" : "0001-01-01T00:00:00Z"
},
"ID" : "8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c",
"Created" : "2014-11-17T22:26:03.626304998Z",
"Path" : "date",
"Args" : [],
"Config" : {
"Hostname" : "8f177a186b97",
"Domainname" : "",
"User" : "",
"AttachStdin" : false,
"AttachStdout" : false,
"AttachStderr" : false,
"PortSpecs": null,
"ExposedPorts" : null,
"Tty" : false,
2015-02-10 18:48:54 +00:00
"OpenStdin" : false,
2016-08-04 13:12:57 +00:00
"StdinOnce" : false,
"Env" : [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ],
"Cmd" : [
"date"
],
"Image" : "ubuntu",
"Volumes" : null,
"WorkingDir" : "",
"Entrypoint" : null,
"NetworkDisabled" : false,
"MacAddress" : "",
"OnBuild" : null,
"SecurityOpt" : null
},
"Image" : "5506de2b643be1e6febbf3b8a240760c6843244c41e12aa2f60ccbb7153d17f5",
"NetworkSettings" : {
"IPAddress" : "172.17.0.2",
"IPPrefixLen" : 16,
"MacAddress" : "02:42:ac:11:00:02",
"Gateway" : "172.17.42.1",
"Bridge" : "docker0",
"PortMapping" : null,
"Ports" : {}
},
"ResolvConfPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/resolv.conf",
"HostnamePath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hostname",
"HostsPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hosts",
"LogPath": "/var/lib/docker/containers/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b/1eb5fabf5a03807136561b3c00adcd2992b535d624d5e18b6cdc6a6844d9767b-json.log",
"Name" : "/test",
"Driver" : "aufs",
"ExecDriver" : "native-0.2",
"MountLabel" : "",
"ProcessLabel" : "",
"AppArmorProfile" : "",
"RestartCount" : 0,
"Volumes" : {},
"VolumesRW" : {}
}
}
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
**Status codes**:
2015-02-10 18:48:54 +00:00
- **200** – no error
- **404** – no such exec instance
- **500** - server error
2016-11-25 10:30:03 +00:00
## 3. Going further
2015-02-10 18:48:54 +00:00
2016-11-25 10:30:03 +00:00
### 3.1 Inside `docker run`
2015-02-10 18:48:54 +00:00
As an example, the `docker run` command line makes the following API calls:
- Create the container
- If the status code is 404, it means the image doesn't exist:
2016-08-04 13:12:57 +00:00
- Try to pull it.
- Then, retry to create the container.
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
- Start the container.
2015-02-10 18:48:54 +00:00
- If you are not in detached mode:
2016-08-04 13:12:57 +00:00
- Attach to the container, using `logs=1` (to have `stdout` and
`stderr` from the container's start) and `stream=1`
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
- If in detached mode or only `stdin` is attached, display the container's id.
2015-02-10 18:48:54 +00:00
2016-11-25 10:30:03 +00:00
### 3.2 Hijacking
2015-02-10 18:48:54 +00:00
2016-08-04 13:12:57 +00:00
In this version of the API, `/attach` , uses hijacking to transport `stdin` ,
`stdout` , and `stderr` on the same socket.
2015-02-10 18:48:54 +00:00
To hint potential proxies about connection hijacking, Docker client sends
connection upgrade headers similarly to websocket.
Upgrade: tcp
Connection: Upgrade
2016-08-04 13:12:57 +00:00
When Docker daemon detects the `Upgrade` header, it switches its status code
from **200 OK** to **101 UPGRADED** and resends the same headers.
2015-02-10 18:48:54 +00:00
This might change in the future.
2016-11-25 10:30:03 +00:00
### 3.3 CORS Requests
2015-02-10 18:48:54 +00:00
2016-11-15 19:45:20 +00:00
To set cross origin requests to the Engine API please give values to
2016-08-04 13:12:57 +00:00
`--api-cors-header` when running Docker in daemon mode. Set * (asterisk) allows all,
2015-02-27 05:38:16 +00:00
default or blank means CORS disabled
2015-02-10 18:48:54 +00:00
2015-02-27 05:38:16 +00:00
$ docker -d -H="192.168.1.9:2375" --api-cors-header="http://foo.bar"