0ct0pu5/moby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #26064 from sfsmithcha/updates_to_v1.12.1_docs

Browse source 
author merge: Updates to v1.12.1 docs
This commit is contained in:
Charles Smith 2016-08-29 10:02:01 -07:00 • committed by GitHub
commit f1bcb5f10e
23 changed files with 6818 additions and 617 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

63
docs/installation/linux/ubuntulinux.md
View file

@ -142,27 +142,48 @@ For Ubuntu Precise, Docker requires the 3.13 kernel version. If your kernel
version is older than 3.13, you must upgrade it. Refer to this table to see
which packages are required for your environment:
<style type="text/css"> .tg {border-collapse:collapse;border-spacing:0;} .tg
td{font-size:14px;padding:10px
5px;border-style:solid;border-width:1px;overflow:hidden;word-break:normal;}
.tg-031{width:275px;font-family:monospace} </style> <table class="tg"> <tr> <td
class="tg-031">linux-image-generic-lts-trusty</td> <td class="tg-031e">Generic
Linux kernel image. This kernel has AUFS built in. This is required to run
Docker.</td> </tr> <tr> <td class="tg-031">linux-headers-generic-lts-trusty</td>
<td class="tg-031e">Allows packages such as ZFS and VirtualBox guest additions
which depend on them. If you didn't install the headers for your existing
kernel, then you can skip these headers for the"trusty" kernel. If you're
unsure, you should include this package for safety.</td> </tr> <tr> <td
class="tg-031">xserver-xorg-lts-trusty</td> <td class="tg-031e"
rowspan="2">Optional in non-graphical environments without Unity/Xorg.
<b>Required</b> when running Docker on machine with a graphical environment.
<br>
<br>To learn more about the reasons for these packages, read the installation
instructions for backported kernels, specifically the <a
href="https://wiki.ubuntu.com/Kernel/LTSEnablementStack" target="_blank">LTS
Enablement Stack</a> &mdash; refer to note 5 under each version.
</td> </tr>
<tr> <td class="tg-031">libgl1-mesa-glx-lts-trusty</td> </tr> </table> &nbsp;
<table>
<thead>
<tr>
<th>Package</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><b style="white-space: nowrap">linux-image-generic-lts-trusty</b></td>
<td>
Generic Linux kernel image. This kernel has AUFS built in. This is
required to run Docker.
</td>
</tr>
<tr>
<td><b style="white-space: nowrap">linux-headers-generic-lts-trusty</b></td>
<td>
Allows packages such as ZFS and VirtualBox guest additions which depend
on them. If you didn't install the headers for your existing kernel, then
you can skip these headers for the"trusty" kernel. If you're unsure, you
should include this package for safety.
</td>
</tr>
<tr>
<td><b style="white-space: nowrap">xserver-xorg-lts-trusty</b></td>
<td rowspan="2">
Optional in non-graphical environments without Unity/Xorg.
<b>Required</b> when running Docker on machine with a graphical
environment.<br /><br />
To learn more about the reasons for these packages, read the installation
instructions for backported kernels, specifically the <a
href="https://wiki.ubuntu.com/Kernel/LTSEnablementStack"
target="_blank">LTS Enablement Stack</a> &mdash; refer to note 5 under each
version.
</td>
</tr>
<tr>
<td><b style="white-space: nowrap">libgl1-mesa-glx-lts-trusty</b></td>
</tr>
</tbody>
</table>
To upgrade your kernel and install the additional packages, do the following:

494
docs/reference/api/docker_remote_api_v1.18.md
View file

@ -127,129 +127,128 @@ Create a container
**Example request**:
POST /containers/create HTTP/1.1
Content-Type: application/json
POST /containers/create HTTP/1.1
Content-Type: application/json
{
"Hostname": "",
"Domainname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": true,
"AttachStderr": true,
"Tty": false,
"OpenStdin": false,
"StdinOnce": false,
"Env": [
"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": {
"/tmp": {}
},
"WorkingDir": "",
"NetworkDisabled": false,
"MacAddress": "12:34:56:78:9a:bc",
"ExposedPorts": {
"22/tcp": {}
},
"HostConfig": {
"Binds": ["/tmp:/tmp"],
"Links": ["redis3:redis"],
"LxcConf": {"lxc.utsname":"docker"},
"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": ""
}
}
{
"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": ""
}
}
**Example response**:
HTTP/1.1 201 Created
Content-Type: application/json
HTTP/1.1 201 Created
Content-Type: application/json
{
"Id":"e90e34656806",
"Warnings":[]
}
{
"Id":"e90e34656806",
"Warnings":[]
}
**JSON parameters**:
- **Hostname** - A string value containing the desired hostname to use for the
- **Hostname** - A string value containing the hostname to use for the
container.
- **Domainname** - A string value containing the desired domain name to use
- **Domainname** - A string value containing the domain name to use
for the container.
- **User** - A string value containing the user to use 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.
- **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.
- **Env** - A list of environment variables in the form of `["VAR=value"[,"VAR2=value2"]]`
- **Labels** - Adds a map of labels that to a container. To specify a map: `{"key":"value"[,"key2":"value2"]}`
- **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value"[,"key2":"value2"]}`
- **Cmd** - Command to run specified as a string or an array of strings.
- **Entrypoint** - Set the entrypoint for the container a string or an array
of strings
- **Image** - String value containing the image name to use for the container
- **Volumes** – An object mapping mountpoint paths (strings) inside the
- **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
container to empty objects.
- **WorkingDir** - A string value containing the working dir for commands to
- **WorkingDir** - A string specifying the working directory for commands to
run in.
- **NetworkDisabled** - Boolean value, when true disables networking for the
container
- **ExposedPorts** - An object mapping ports to an empty object in the form of:
`"ExposedPorts": { "<port>/<tcp|udp>: {}" }`
- **HostConfig**
- **Binds** – A list of volume bindings for this container. Each volume
binding is a string of the form `container_path` (to create a new
volume for the container), `host_path:container_path` (to bind-mount
a host path into the container), or `host_path:container_path:ro`
(to make the bind-mount read-only inside the container).
- **Binds** – A list of volume bindings for this container. Each volume binding is a string in one of these forms:
+ `container_path` to create a new volume for the container
+ `host_path:container_path` to bind-mount a host path into the container
+ `host_path:container_path:ro` to make the bind-mount read-only inside the container.
- **Links** - A list of links for the container. Each link entry should be
in the form of `container_name:alias`.
- **LxcConf** - LXC specific configurations. These configurations will only
- **LxcConf** - LXC specific configurations. These configurations only
work when using the `lxc` execution driver.
- **Memory** - Memory limit in bytes.
- **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap.
You must use this with `memory` and make the swap value larger than `memory`.
- **CpuShares** - An integer value containing the CPU Shares for container
- **CpuShares** - An integer value containing the container's CPU Shares
(ie. the relative weight vs other containers).
- **CpusetCpus** - String value containing the cgroups CpusetCpus to use.
- **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use.
- **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
- **PortBindings** - A map of exposed container ports and the host port they
should map to. It should be specified in the form
should map to. A JSON object in the form
`{ <port>/<protocol>: [{ "HostPort": "<port>" }] }`
Take note that `port` is specified as a string and not an integer value.
- **PublishAllPorts** - Allocates a random host port for all of a container's
@ -258,9 +257,9 @@ Create a container
a boolean value.
- **ReadonlyRootfs** - Mount the container's root filesystem as read only.
Specified as a boolean value.
- **Dns** - A list of dns servers for the container to use.
- **Dns** - A list of DNS servers for the container to use.
- **DnsSearch** - A list of DNS search domains
- **ExtraHosts** - A list of hostnames/IP mappings to be added to the
- **ExtraHosts** - A list of hostnames/IP mappings to add to the
container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`.
- **VolumesFrom** - A list of volumes to inherit from another container.
Specified in the form `<container name>[:<ro|rw>]`
@ -276,19 +275,19 @@ Create a container
is added before each restart to prevent flooding the server.
- **NetworkMode** - Sets the networking mode for the container. Supported
values are: `bridge`, `host`, `none`, and `container:<name|id>`
- **Devices** - A list of devices to add to the container specified in the
form
- **Devices** - A list of devices to add to the container specified as a JSON object in the
form
`{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}`
- **Ulimits** - A list of ulimits to be set in the container, specified as
- **Ulimits** - A list of ulimits to set in the container, specified as
`{ "Name": <name>, "Soft": <soft limit>, "Hard": <hard limit> }`, for example:
`Ulimits: { "Name": "nofile", "Soft": 1024, "Hard": 2048 }`
- **SecurityOpt**: A list of string values to customize labels for MLS
systems, such as SELinux.
- **LogConfig** - Log configuration for the container, specified as
- **LogConfig** - Log configuration for the container, specified as a JSON object in the form
`{ "Type": "<driver_name>", "Config": {"key1": "val1"}}`.
Available types: `json-file`, `syslog`, `journald`, `none`.
`json-file` logging driver.
- **CgroupParent** - Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist.
- **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.
**Query parameters**:
@ -424,7 +423,7 @@ Return low-level information on the container `id`
"Paused": false,
"Pid": 0,
"Restarting": false,
"Running": false,
"Running": true,
"StartedAt": "2015-01-06T15:47:32.072697474Z"
},
"Volumes": {},
@ -525,12 +524,12 @@ Get `stdout` and `stderr` logs from the container ``id``
**Query parameters**:
- **follow** – 1/True/true or 0/False/false, return stream. Default false
- **stdout** – 1/True/true or 0/False/false, show stdout log. Default false
- **stderr** – 1/True/true or 0/False/false, show stderr log. Default false
- **follow** – 1/True/true or 0/False/false, return stream. Default `false`.
- **stdout** – 1/True/true or 0/False/false, show `stdout` log. Default `false`.
- **stderr** – 1/True/true or 0/False/false, show `stderr` log. Default `false`.
- **timestamps** – 1/True/true or 0/False/false, print timestamps for
every log line. Default false
- **tail** – Output specified number of lines at the end of logs: `all` or `<number>`. Default all
every log line. Default `false`.
- **tail** – Output specified number of lines at the end of logs: `all` or `<number>`. Default all.
**Status codes**:
@ -612,79 +611,79 @@ This endpoint returns a live stream of a container's resource usage statistics.
**Example request**:
GET /containers/redis1/stats HTTP/1.1
GET /containers/redis1/stats HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"read" : "2015-01-08T22:57:31.547920715Z",
"network" : {
"rx_dropped" : 0,
"rx_bytes" : 648,
"rx_errors" : 0,
"tx_packets" : 8,
"tx_dropped" : 0,
"rx_packets" : 8,
"tx_errors" : 0,
"tx_bytes" : 648
},
"memory_stats" : {
"stats" : {
"total_pgmajfault" : 0,
"cache" : 0,
"mapped_file" : 0,
"total_inactive_file" : 0,
"pgpgout" : 414,
"rss" : 6537216,
"total_mapped_file" : 0,
"writeback" : 0,
"unevictable" : 0,
"pgpgin" : 477,
"total_unevictable" : 0,
"pgmajfault" : 0,
"total_rss" : 6537216,
"total_rss_huge" : 6291456,
"total_writeback" : 0,
"total_inactive_anon" : 0,
"rss_huge" : 6291456,
"hierarchical_memory_limit" : 67108864,
"total_pgfault" : 964,
"total_active_file" : 0,
"active_anon" : 6537216,
"total_active_anon" : 6537216,
"total_pgpgout" : 414,
"total_cache" : 0,
"inactive_anon" : 0,
"active_file" : 0,
"pgfault" : 964,
"inactive_file" : 0,
"total_pgpgin" : 477
},
"max_usage" : 6651904,
"usage" : 6537216,
"failcnt" : 0,
"limit" : 67108864
},
"blkio_stats" : {},
"cpu_stats" : {
"cpu_usage" : {
"percpu_usage" : [
16970827,
1839451,
7107380,
10571290
],
"usage_in_usermode" : 10000000,
"total_usage" : 36488948,
"usage_in_kernelmode" : 20000000
},
"system_cpu_usage" : 20091722000000000,
"throttling_data" : {}
}
}
{
"read" : "2015-01-08T22:57:31.547920715Z",
"network" : {
"rx_dropped" : 0,
"rx_bytes" : 648,
"rx_errors" : 0,
"tx_packets" : 8,
"tx_dropped" : 0,
"rx_packets" : 8,
"tx_errors" : 0,
"tx_bytes" : 648
},
"memory_stats" : {
"stats" : {
"total_pgmajfault" : 0,
"cache" : 0,
"mapped_file" : 0,
"total_inactive_file" : 0,
"pgpgout" : 414,
"rss" : 6537216,
"total_mapped_file" : 0,
"writeback" : 0,
"unevictable" : 0,
"pgpgin" : 477,
"total_unevictable" : 0,
"pgmajfault" : 0,
"total_rss" : 6537216,
"total_rss_huge" : 6291456,
"total_writeback" : 0,
"total_inactive_anon" : 0,
"rss_huge" : 6291456,
"hierarchical_memory_limit" : 67108864,
"total_pgfault" : 964,
"total_active_file" : 0,
"active_anon" : 6537216,
"total_active_anon" : 6537216,
"total_pgpgout" : 414,
"total_cache" : 0,
"inactive_anon" : 0,
"active_file" : 0,
"pgfault" : 964,
"inactive_file" : 0,
"total_pgpgin" : 477
},
"max_usage" : 6651904,
"usage" : 6537216,
"failcnt" : 0,
"limit" : 67108864
},
"blkio_stats" : {},
"cpu_stats" : {
"cpu_usage" : {
"percpu_usage" : [
16970827,
1839451,
7107380,
10571290
],
"usage_in_usermode" : 10000000,
"total_usage" : 36488948,
"usage_in_kernelmode" : 20000000
},
"system_cpu_usage" : 20091722000000000,
"throttling_data" : {}
}
}
**Status codes**:
@ -1209,22 +1208,22 @@ or being killed.
- **dockerfile** - Path within the build context to the Dockerfile. This is
ignored if `remote` is specified and points to an individual filename.
- **t** – repository name (and optionally a tag) to be applied to
the resulting image in case of success
- **remote** – A Git repository URI or HTTP/HTTPS URI build source. If the
URI specifies a filename, the file's contents are placed into a file
called `Dockerfile`.
- **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
- **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.
- **memswap** - Total memory (memory + swap), `-1` to enable unlimited swap.
- **cpushares** - CPU shares (relative weight)
- **cpusetcpus** - CPUs in which to allow execution, e.g., `0-3`, `0,1`
- **cpushares** - CPU shares (relative weight).
- **cpusetcpus** - CPUs in which to allow execution (e.g., `0-3`, `0,1`).
Request Headers:
**Request Headers**:
- **Content-type** – Set to `"application/tar"`.
- **X-Registry-Config** – base64-encoded ConfigFile object
@ -1238,7 +1237,7 @@ or being killed.
`POST /images/create`
Create an image, either by pulling it from the registry or by importing it
Create an image either by pulling it from the registry or by importing it
**Example request**:
@ -1266,7 +1265,7 @@ a base64-encoded AuthConfig object.
- **repo** – Repository name.
- **tag** – Tag.
Request Headers:
**Request Headers**:
- **X-Registry-Auth** – base64-encoded AuthConfig object
@ -1293,35 +1292,33 @@ Return low-level information on the image `name`
Content-Type: application/json
{
"Created": "2013-03-23T22:24:18.818426-07:00",
"Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0",
"ContainerConfig":
{
"Hostname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": false,
"AttachStderr": false,
"PortSpecs": null,
"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
"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
}
**Status codes**:
@ -1346,16 +1343,16 @@ Return the history of the image `name`
Content-Type: application/json
[
{
"Id": "b750fe79269d",
"Created": 1364102658,
"CreatedBy": "/bin/bash"
},
{
"Id": "27cf78414709",
"Created": 1364068391,
"CreatedBy": ""
}
{
"Id": "b750fe79269d",
"Created": 1364102658,
"CreatedBy": "/bin/bash"
},
{
"Id": "27cf78414709",
"Created": 1364068391,
"CreatedBy": ""
}
]
**Status codes**:
@ -1384,9 +1381,9 @@ Push the image `name` on the registry
{"error": "Invalid..."}
...
If you wish to push an image on to a private registry, that image must already have been tagged
into a repository which references that registry host name and port. This repository name should
then be used in the URL. This mirrors the flow of the CLI.
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.
**Example request**:
@ -1397,10 +1394,9 @@ then be used in the URL. This mirrors the flow of the CLI.
- **tag** – The tag to associate with the image on the registry. This is optional.
Request Headers:
**Request Headers**:
- **X-Registry-Auth** – Include a base64-encoded AuthConfig.
object.
- **X-Registry-Auth** – base64-encoded AuthConfig object.
**Status codes**:
@ -1490,25 +1486,25 @@ Search for an image on [Docker Hub](https://hub.docker.com).
[
{
"description": "",
"star_count": 12,
"is_official": false,
"is_automated": false,
"name": "wma55/u1210sshd",
"star_count": 0
"is_automated": false,
"description": ""
},
{
"description": "",
"star_count": 10,
"is_official": false,
"is_automated": false,
"name": "jdswinbank/sshd",
"star_count": 0
"is_automated": false,
"description": ""
},
{
"description": "",
"star_count": 18,
"is_official": false,
"is_automated": false,
"name": "vgauthier/sshd",
"star_count": 0
"is_automated": false,
"description": ""
}
...
]
@ -1536,8 +1532,8 @@ Get the default username and email
Content-Type: application/json
{
"username":" hannibal",
"password: "xxxx",
"username": "hannibal",
"password": "xxxx",
"email": "hannibal@a-team.com",
"serveraddress": "https://index.docker.io/v1/"
}
@ -1741,7 +1737,7 @@ Docker containers report the following events:
create, destroy, die, exec_create, exec_start, export, kill, oom, pause, restart, start, stop, unpause
and Docker images report:
Docker images report the following events:
untag, delete
@ -1803,7 +1799,7 @@ See the [image tarball format](#image-tarball-format) for more details.
- **200** – no error
- **500** – server error
### Get a tarball containing all images.
### Get a tarball containing all images
`GET /images/get`

99
docs/reference/api/docker_remote_api_v1.19.md
View file

@ -218,7 +218,7 @@ Create a container
- **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,
- **OpenStdin** - Boolean value, opens `stdin`,
- **StdinOnce** - Boolean value, close `stdin` after the 1 attached client disconnects.
- **Env** - A list of environment variables in the form of `["VAR=value"[,"VAR2=value2"]]`
- **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value"[,"key2":"value2"]}`
@ -328,7 +328,7 @@ Return low-level information on the container `id`
HTTP/1.1 200 OK
Content-Type: application/json
{
{
"AppArmorProfile": "",
"Args": [
"-c",
@ -437,7 +437,7 @@ Return low-level information on the container `id`
"Paused": false,
"Pid": 0,
"Restarting": false,
"Running": false,
"Running": true,
"StartedAt": "2015-01-06T15:47:32.072697474Z"
},
"Volumes": {},
@ -1250,15 +1250,11 @@ or being killed.
- **dockerfile** - Path within the build context to the Dockerfile. This is
ignored if `remote` is specified and points to an individual filename.
- **t** – Repository name (and optionally a tag) to be applied to
the resulting image in case of success.
- **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. If
the URI points to a tarball, the file is downloaded by the daemon and
the contents therein used as the context for the build. If the URI
points to a tarball and the `dockerfile` parameter is also specified,
there must be a file with the corresponding path inside the tarball.
- **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 URI build source. If the
URI specifies a filename, the file's contents are placed into a file
called `Dockerfile`.
- **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.
@ -1271,7 +1267,7 @@ or being killed.
- **cpuperiod** - The length of a CPU period in microseconds.
- **cpuquota** - Microseconds of CPU time that the container can get in a CPU period.
Request Headers:
**Request Headers**:
- **Content-type** – Set to `"application/tar"`.
- **X-Registry-Config** – base64-encoded ConfigFile object
@ -1313,7 +1309,7 @@ a base64-encoded AuthConfig object.
- **repo** – Repository name.
- **tag** – Tag.
Request Headers:
**Request Headers**:
- **X-Registry-Auth** – base64-encoded AuthConfig object
@ -1340,35 +1336,33 @@ Return low-level information on the image `name`
Content-Type: application/json
{
"Created": "2013-03-23T22:24:18.818426-07:00",
"Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0",
"ContainerConfig":
{
"Hostname": "",
"User": "",
"AttachStdin": false,
"AttachStdout": false,
"AttachStderr": false,
"PortSpecs": null,
"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
"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
}
**Status codes**:
@ -1464,10 +1458,9 @@ then be used in the URL. This duplicates the command line's flow.
- **tag** – The tag to associate with the image on the registry. This is optional.
Request Headers:
**Request Headers**:
- **X-Registry-Auth** – Include a base64-encoded AuthConfig.
object.
- **X-Registry-Auth** – base64-encoded AuthConfig object.
**Status codes**:
@ -1565,7 +1558,7 @@ be deprecated and replaced by the `is_automated` property.
"name": "wma55/u1210sshd",
"is_trusted": false,
"is_automated": false,
"description": "",
"description": ""
},
{
"star_count": 10,
@ -1573,7 +1566,7 @@ be deprecated and replaced by the `is_automated` property.
"name": "jdswinbank/sshd",
"is_trusted": false,
"is_automated": false,
"description": "",
"description": ""
},
{
"star_count": 18,
@ -1581,7 +1574,7 @@ be deprecated and replaced by the `is_automated` property.
"name": "vgauthier/sshd",
"is_trusted": false,
"is_automated": false,
"description": "",
"description": ""
}
...
]
@ -1609,8 +1602,8 @@ Get the default username and email
Content-Type: application/json
{
"username":" hannibal",
"password: "xxxx",
"username": "hannibal",
"password": "xxxx",
"email": "hannibal@a-team.com",
"serveraddress": "https://index.docker.io/v1/"
}
@ -1822,7 +1815,7 @@ Docker containers report the following events:
attach, commit, copy, create, destroy, die, exec_create, exec_start, export, kill, oom, pause, rename, resize, restart, start, stop, top, unpause
and Docker images report:
Docker images report the following events:
untag, delete
@ -1884,7 +1877,7 @@ See the [image tarball format](#image-tarball-format) for more details.
- **200** – no error
- **500** – server error
### Get a tarball containing all images.
### Get a tarball containing all images
`GET /images/get`

96
docs/reference/api/docker_remote_api_v1.20.md
View file

@ -220,7 +220,7 @@ Create a container
- **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,
- **OpenStdin** - Boolean value, opens `stdin`,
- **StdinOnce** - Boolean value, close `stdin` after the 1 attached client disconnects.
- **Env** - A list of environment variables in the form of `["VAR=value"[,"VAR2=value2"]]`
- **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value"[,"key2":"value2"]}`
@ -332,7 +332,7 @@ Return low-level information on the container `id`
HTTP/1.1 200 OK
Content-Type: application/json
{
{
"AppArmorProfile": "",
"Args": [
"-c",
@ -440,7 +440,7 @@ Return low-level information on the container `id`
"Paused": false,
"Pid": 0,
"Restarting": false,
"Running": false,
"Running": true,
"StartedAt": "2015-01-06T15:47:32.072697474Z"
},
"Mounts": [
@ -1375,13 +1375,17 @@ or being killed.
**Query parameters**:
- **dockerfile** - Path within the build context to the Dockerfile. This is
ignored if `remote` is specified and points to an individual filename.
- **t** – A repository name (and optionally a tag) to apply to
the resulting image in case of success.
- **remote** – A Git repository URI or HTTP/HTTPS URI build source. If the
URI specifies a filename, the file's contents are placed into a file
called `Dockerfile`.
- **dockerfile** - Path within the build context to the `Dockerfile`. This is
ignored if `remote` is specified and points to an external `Dockerfile`.
- **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. If
the URI points to a tarball, the file is downloaded by the daemon and
the contents therein used as the context for the build. If the URI
points to a tarball and the `dockerfile` parameter is also specified,
there must be a file with the corresponding path inside the tarball.
- **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.
@ -1394,7 +1398,7 @@ or being killed.
- **cpuperiod** - The length of a CPU period in microseconds.
- **cpuquota** - Microseconds of CPU time that the container can get in a CPU period.
Request Headers:
**Request Headers**:
- **Content-type** – Set to `"application/tar"`.
- **X-Registry-Config** – A base64-url-safe-encoded Registry Auth Config JSON
@ -1457,7 +1461,7 @@ a base64-encoded AuthConfig object.
- **repo** – Repository name.
- **tag** – Tag.
Request Headers:
**Request Headers**:
- **X-Registry-Auth** – base64-encoded AuthConfig object
@ -1484,34 +1488,33 @@ Return low-level information on the image `name`
Content-Type: application/json
{
"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
"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
}
**Status codes**:
@ -1607,10 +1610,9 @@ then be used in the URL. This duplicates the command line's flow.
- **tag** – The tag to associate with the image on the registry. This is optional.
Request Headers:
**Request Headers**:
- **X-Registry-Auth** – Include a base64-encoded AuthConfig.
object.
- **X-Registry-Auth** – base64-encoded AuthConfig object.
**Status codes**:
@ -1746,8 +1748,8 @@ Get the default username and email
Content-Type: application/json
{
"username":" hannibal",
"password: "xxxx",
"username": "hannibal",
"password": "xxxx",
"email": "hannibal@a-team.com",
"serveraddress": "https://index.docker.io/v1/"
}
@ -1966,7 +1968,7 @@ Docker containers report the following events:
attach, commit, copy, create, destroy, die, exec_create, exec_start, export, kill, oom, pause, rename, resize, restart, start, stop, top, unpause
and Docker images report:
Docker images report the following events:
delete, import, pull, push, tag, untag
@ -2028,7 +2030,7 @@ See the [image tarball format](#image-tarball-format) for more details.
- **200** – no error
- **500** – server error
### Get a tarball containing all images.
### Get a tarball containing all images
`GET /images/get`

116
docs/reference/api/docker_remote_api_v1.21.md
View file

@ -229,7 +229,7 @@ Create a container
- **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,
- **OpenStdin** - Boolean value, opens `stdin`,
- **StdinOnce** - Boolean value, close `stdin` after the 1 attached client disconnects.
- **Env** - A list of environment variables in the form of `["VAR=value"[,"VAR2=value2"]]`
- **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value"[,"key2":"value2"]}`
@ -350,7 +350,7 @@ Return low-level information on the container `id`
HTTP/1.1 200 OK
Content-Type: application/json
{
{
"AppArmorProfile": "",
"Args": [
"-c",
@ -462,14 +462,14 @@ Return low-level information on the container `id`
"MacAddress": "",
"Networks": {
"bridge": {
"EndpointID": "",
"Gateway": "",
"IPAddress": "",
"IPPrefixLen": 0,
"EndpointID": "7587b82f0dada3656fda26588aee72630c6fab1536d36e394b2bfbcf898c971d",
"Gateway": "172.17.0.1",
"IPAddress": "172.17.0.2",
"IPPrefixLen": 16,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": ""
"MacAddress": "02:42:ac:12:00:02"
}
}
},
@ -1453,14 +1453,18 @@ or being killed.
**Query parameters**:
- **dockerfile** - Path within the build context to the Dockerfile. This is
ignored if `remote` is specified and points to an individual filename.
- **dockerfile** - Path within the build context to the `Dockerfile`. This is
ignored if `remote` is specified and points to an external `Dockerfile`.
- **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.
You can provide one or more `t` parameters.
- **remote** – A Git repository URI or HTTP/HTTPS URI build source. If the
URI specifies a filename, the file's contents are placed into a file
called `Dockerfile`.
- **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. If
the URI points to a tarball, the file is downloaded by the daemon and
the contents therein used as the context for the build. If the URI
points to a tarball and the `dockerfile` parameter is also specified,
there must be a file with the corresponding path inside the tarball.
- **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.
@ -1478,7 +1482,7 @@ or being killed.
variable expansion in other Dockerfile instructions. This is not meant for
passing secret values. [Read more about the buildargs instruction](../../reference/builder.md#arg)
Request Headers:
**Request Headers**:
- **Content-type** – Set to `"application/tar"`.
- **X-Registry-Config** – A base64-url-safe-encoded Registry Auth Config JSON
@ -1545,7 +1549,7 @@ a base64-encoded AuthConfig object.
an image.
- **tag** – Tag or digest.
Request Headers:
**Request Headers**:
- **X-Registry-Auth** – base64-encoded AuthConfig object
@ -1754,10 +1758,9 @@ then be used in the URL. This duplicates the command line's flow.
- **tag** – The tag to associate with the image on the registry. This is optional.
Request Headers:
**Request Headers**:
- **X-Registry-Auth** – Include a base64-encoded AuthConfig.
object.
- **X-Registry-Auth** – base64-encoded AuthConfig object.
**Status codes**:
@ -1893,8 +1896,8 @@ Get the default username and email
Content-Type: application/json
{
"username":" hannibal",
"password: "xxxx",
"username": "hannibal",
"password": "xxxx",
"email": "hannibal@a-team.com",
"serveraddress": "https://index.docker.io/v1/"
}
@ -2115,7 +2118,7 @@ Docker containers report the following events:
attach, commit, copy, create, destroy, die, exec_create, exec_start, export, kill, oom, pause, rename, resize, restart, start, stop, top, unpause
and Docker images report:
Docker images report the following events:
delete, import, pull, push, tag, untag
@ -2178,7 +2181,7 @@ See the [image tarball format](#image-tarball-format) for more details.
- **200** – no error
- **500** – server error
### Get a tarball containing all images.
### Get a tarball containing all images
`GET /images/get`
@ -2438,36 +2441,36 @@ Return low-level information about the `exec` command `id`.
"SecurityOpt" : null
},
"Image" : "5506de2b643be1e6febbf3b8a240760c6843244c41e12aa2f60ccbb7153d17f5",
"NetworkSettings": {
"Bridge": "",
"SandboxID": "",
"HairpinMode": false,
"LinkLocalIPv6Address": "",
"LinkLocalIPv6PrefixLen": 0,
"Ports": null,
"SandboxKey": "",
"SecondaryIPAddresses": null,
"SecondaryIPv6Addresses": null,
"EndpointID": "",
"Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"IPAddress": "",
"IPPrefixLen": 0,
"IPv6Gateway": "",
"MacAddress": "",
"Networks": {
"bridge": {
"EndpointID": "",
"Gateway": "",
"IPAddress": "",
"IPPrefixLen": 0,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": ""
}
"NetworkSettings" : {
"Bridge": "",
"SandboxID": "",
"HairpinMode": false,
"LinkLocalIPv6Address": "",
"LinkLocalIPv6PrefixLen": 0,
"Ports": null,
"SandboxKey": "",
"SecondaryIPAddresses": null,
"SecondaryIPv6Addresses": null,
"EndpointID": "",
"Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"IPAddress": "",
"IPPrefixLen": 0,
"IPv6Gateway": "",
"MacAddress": "",
"Networks": {
"bridge": {
"EndpointID": "",
"Gateway": "",
"IPAddress": "",
"IPPrefixLen": 0,
"IPv6Gateway": "",
"GlobalIPv6Address": "",
"GlobalIPv6PrefixLen": 0,
"MacAddress": ""
}
}
},
"ResolvConfPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/resolv.conf",
"HostnamePath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hostname",
@ -2760,11 +2763,14 @@ Content-Type: application/json
"Name":"isolated_nw",
"Driver":"bridge",
"IPAM":{
"Config":[{
"Subnet":"172.20.0.0/16",
"IPRange":"172.20.10.0/24",
"Gateway":"172.20.10.11"
}]
"Config":[
{
"Subnet":"172.20.0.0/16",
"IPRange":"172.20.10.0/24",
"Gateway":"172.20.10.11"
}
]
}
}
```

91
docs/reference/api/docker_remote_api_v1.22.md
View file

@ -113,7 +113,6 @@ List containers
}
}
}
},
{
"Id": "3176a2479c92",
@ -148,7 +147,6 @@ List containers
}
}
}
},
{
"Id": "4cb07b47f9fb",
@ -183,7 +181,6 @@ List containers
}
}
}
}
]
@ -335,7 +332,7 @@ Create a container
- **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,
- **OpenStdin** - Boolean value, opens `stdin`,
- **StdinOnce** - Boolean value, close `stdin` after the 1 attached client disconnects.
- **Env** - A list of environment variables in the form of `["VAR=value"[,"VAR2=value2"]]`
- **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value"[,"key2":"value2"]}`
@ -464,7 +461,7 @@ Return low-level information on the container `id`
HTTP/1.1 200 OK
Content-Type: application/json
{
{
"AppArmorProfile": "",
"Args": [
"-c",
@ -1633,14 +1630,18 @@ or being killed.
**Query parameters**:
- **dockerfile** - Path within the build context to the Dockerfile. This is
ignored if `remote` is specified and points to an individual filename.
- **dockerfile** - Path within the build context to the `Dockerfile`. This is
ignored if `remote` is specified and points to an external `Dockerfile`.
- **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.
You can provide one or more `t` parameters.
- **remote** – A Git repository URI or HTTP/HTTPS URI build source. If the
URI specifies a filename, the file's contents are placed into a file
called `Dockerfile`.
- **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. If
the URI points to a tarball, the file is downloaded by the daemon and
the contents therein used as the context for the build. If the URI
points to a tarball and the `dockerfile` parameter is also specified,
there must be a file with the corresponding path inside the tarball.
- **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.
@ -1659,7 +1660,7 @@ or being killed.
passing secret values. [Read more about the buildargs instruction](../../reference/builder.md#arg)
- **shmsize** - Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.
Request Headers:
**Request Headers**:
- **Content-type** – Set to `"application/tar"`.
- **X-Registry-Config** – A base64-url-safe-encoded Registry Auth Config JSON
@ -1727,7 +1728,7 @@ a base64-encoded AuthConfig object.
an image.
- **tag** – Tag or digest.
Request Headers:
**Request Headers**:
- **X-Registry-Auth** – base64-encoded AuthConfig object, containing either login information, or a token
- Credential based login:
@ -1955,7 +1956,7 @@ The push is cancelled if the HTTP connection is closed.
- **tag** – The tag to associate with the image on the registry. This is optional.
Request Headers:
**Request Headers**:
- **X-Registry-Auth** – base64-encoded AuthConfig object, containing either login information, or a token
- Credential based login:
@ -2110,8 +2111,8 @@ Get the default username and email
Content-Type: application/json
{
"username":" hannibal",
"password: "xxxx",
"username": "hannibal",
"password": "xxxx",
"email": "hannibal@a-team.com",
"serveraddress": "https://index.docker.io/v1/"
}
@ -2229,7 +2230,7 @@ Show the docker version information
Content-Type: application/json
{
"Version": "1.10.0-dev",
"Version": "1.10.0",
"Os": "linux",
"KernelVersion": "3.19.0-23-generic",
"GoVersion": "go1.4.2",
@ -2775,25 +2776,25 @@ Return low-level information about the `exec` command `id`.
Content-Type: application/json
{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false
}
**Status codes**:
@ -3082,18 +3083,18 @@ Content-Type: application/json
"Driver":"bridge",
"IPAM":{
"Config":[
{
"Subnet":"172.20.0.0/16",
"IPRange":"172.20.10.0/24",
"Gateway":"172.20.10.11"
},
{
"Subnet":"2001:db8:abcd::/64",
"Gateway":"2001:db8:abcd::1011"
}
{
"Subnet":"172.20.0.0/16",
"IPRange":"172.20.10.0/24",
"Gateway":"172.20.10.11"
},
{
"Subnet":"2001:db8:abcd::/64",
"Gateway":"2001:db8:abcd::1011"
}
],
"Options": {
"foo": "bar"
"foo": "bar"
}
},
"Internal":true

104
docs/reference/api/docker_remote_api_v1.23.md
View file

@ -355,7 +355,7 @@ Create a container
- **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,
- **OpenStdin** - Boolean value, opens `stdin`,
- **StdinOnce** - Boolean value, close `stdin` after the 1 attached client disconnects.
- **Env** - A list of environment variables in the form of `["VAR=value"[,"VAR2=value2"]]`
- **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value"[,"key2":"value2"]}`
@ -487,7 +487,7 @@ Return low-level information on the container `id`
HTTP/1.1 200 OK
Content-Type: application/json
{
{
"AppArmorProfile": "",
"Args": [
"-c",
@ -1663,14 +1663,18 @@ or being killed.
**Query parameters**:
- **dockerfile** - Path within the build context to the Dockerfile. This is
ignored if `remote` is specified and points to an individual filename.
- **dockerfile** - Path within the build context to the `Dockerfile`. This is
ignored if `remote` is specified and points to an external `Dockerfile`.
- **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.
You can provide one or more `t` parameters.
- **remote** – A Git repository URI or HTTP/HTTPS URI build source. If the
URI specifies a filename, the file's contents are placed into a file
called `Dockerfile`.
- **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. If
the URI points to a tarball, the file is downloaded by the daemon and
the contents therein used as the context for the build. If the URI
points to a tarball and the `dockerfile` parameter is also specified,
there must be a file with the corresponding path inside the tarball.
- **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.
@ -1690,7 +1694,7 @@ or being killed.
- **shmsize** - Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.
- **labels** – JSON map of string pairs for labels to set on the image.
Request Headers:
**Request Headers**:
- **Content-type** – Set to `"application/tar"`.
- **X-Registry-Config** – A base64-url-safe-encoded Registry Auth Config JSON
@ -1758,7 +1762,7 @@ a base64-encoded AuthConfig object.
an image.
- **tag** – Tag or digest.
Request Headers:
**Request Headers**:
- **X-Registry-Auth** – base64-encoded AuthConfig object, containing either login information, or a token
- Credential based login:
@ -1993,7 +1997,7 @@ The push is cancelled if the HTTP connection is closed.
- **tag** – The tag to associate with the image on the registry. This is optional.
Request Headers:
**Request Headers**:
- **X-Registry-Auth** – base64-encoded AuthConfig object, containing either login information, or a token
- Credential based login:
@ -2274,7 +2278,7 @@ Show the docker version information
Content-Type: application/json
{
"Version": "1.10.0-dev",
"Version": "1.10.0",
"Os": "linux",
"KernelVersion": "3.19.0-23-generic",
"GoVersion": "go1.4.2",
@ -2846,25 +2850,25 @@ Return low-level information about the `exec` command `id`.
Content-Type: application/json
{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false
}
**Status codes**:
@ -2924,7 +2928,7 @@ Create a volume
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
}
}
**Example response**:
@ -2939,7 +2943,7 @@ Create a volume
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
}
}
**Status codes**:
@ -2953,7 +2957,7 @@ Create a volume
- **Driver** - Name of the volume driver to use. Defaults to `local` for the name.
- **DriverOpts** - A mapping of driver options and values. These options are
passed directly to the driver and are driver specific.
- **Labels** - Labels to set on the volume, specified as a map: `{"key":"value" [,"key2":"value2"]}`
- **Labels** - Labels to set on the volume, specified as a map: `{"key":"value","key2":"value2"}`
### Inspect a volume
@ -2971,13 +2975,13 @@ Return low-level information on the volume `name`
Content-Type: application/json
{
"Name": "tardis",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/tardis/_data",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
"Name": "tardis",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/tardis/_data",
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
}
}
**Status codes**:
@ -3180,18 +3184,18 @@ Content-Type: application/json
"EnableIPv6": true,
"IPAM":{
"Config":[
{
"Subnet":"172.20.0.0/16",
"IPRange":"172.20.10.0/24",
"Gateway":"172.20.10.11"
},
{
"Subnet":"2001:db8:abcd::/64",
"Gateway":"2001:db8:abcd::1011"
}
{
"Subnet":"172.20.0.0/16",
"IPRange":"172.20.10.0/24",
"Gateway":"172.20.10.11"
},
{
"Subnet":"2001:db8:abcd::/64",
"Gateway":"2001:db8:abcd::1011"
}
],
"Options": {
"foo": "bar"
"foo": "bar"
}
},
"Internal":true,

118
docs/reference/api/docker_remote_api_v1.24.md
View file

@ -372,7 +372,7 @@ Create a container
- **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,
- **OpenStdin** - Boolean value, opens `stdin`,
- **StdinOnce** - Boolean value, close `stdin` after the 1 attached client disconnects.
- **Env** - A list of environment variables in the form of `["VAR=value"[,"VAR2=value2"]]`
- **Labels** - Adds a map of labels to a container. To specify a map: `{"key":"value"[,"key2":"value2"]}`
@ -512,7 +512,7 @@ Return low-level information on the container `id`
HTTP/1.1 200 OK
Content-Type: application/json
{
{
"AppArmorProfile": "",
"Args": [
"-c",
@ -1664,14 +1664,18 @@ or being killed.
**Query parameters**:
- **dockerfile** - Path within the build context to the Dockerfile. This is
ignored if `remote` is specified and points to an individual filename.
- **dockerfile** - Path within the build context to the `Dockerfile`. This is
ignored if `remote` is specified and points to an external `Dockerfile`.
- **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.
You can provide one or more `t` parameters.
- **remote** – A Git repository URI or HTTP/HTTPS URI build source. If the
URI specifies a filename, the file's contents are placed into a file
called `Dockerfile`.
- **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. If
the URI points to a tarball, the file is downloaded by the daemon and
the contents therein used as the context for the build. If the URI
points to a tarball and the `dockerfile` parameter is also specified,
there must be a file with the corresponding path inside the tarball.
- **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.
@ -1691,7 +1695,7 @@ or being killed.
- **shmsize** - Size of `/dev/shm` in bytes. The size must be greater than 0. If omitted the system uses 64MB.
- **labels** – JSON map of string pairs for labels to set on the image.
Request Headers:
**Request Headers**:
- **Content-type** – Set to `"application/tar"`.
- **X-Registry-Config** – A base64-url-safe-encoded Registry Auth Config JSON
@ -1759,7 +1763,7 @@ a base64-encoded AuthConfig object.
an image.
- **tag** – Tag or digest.
Request Headers:
**Request Headers**:
- **X-Registry-Auth** – base64-encoded AuthConfig object, containing either login information, or a token
- Credential based login:
@ -1994,7 +1998,7 @@ The push is cancelled if the HTTP connection is closed.
- **tag** – The tag to associate with the image on the registry. This is optional.
Request Headers:
**Request Headers**:
- **X-Registry-Auth** – base64-encoded AuthConfig object, containing either login information, or a token
- Credential based login:
@ -2427,7 +2431,7 @@ Docker daemon report the following event:
HTTP/1.1 200 OK
Content-Type: application/json
Server: Docker/1.10.0 (linux)
Server: Docker/1.11.0 (linux)
Date: Fri, 29 Apr 2016 15:18:06 GMT
Transfer-Encoding: chunked
@ -2860,25 +2864,25 @@ Return low-level information about the `exec` command `id`.
Content-Type: application/json
{
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false
"CanRemove": false,
"ContainerID": "b53ee82b53a40c7dca428523e34f741f3abc51d9f297a14ff874bf761b995126",
"DetachKeys": "",
"ExitCode": 2,
"ID": "f33bbfb39f5b142420f4759b2348913bd4a8d1a6d7fd56499cb41a1bb91d7b3b",
"OpenStderr": true,
"OpenStdin": true,
"OpenStdout": true,
"ProcessConfig": {
"arguments": [
"-c",
"exit 2"
],
"entrypoint": "sh",
"privileged": false,
"tty": true,
"user": "1000"
},
"Running": false
}
**Status codes**:
@ -2983,7 +2987,7 @@ Create a volume
Refer to the [inspect a volume](#inspect-a-volume) section or details about the
JSON fields returned in the response.
### Inspect a volume
`GET /volumes/(name)`
@ -3000,17 +3004,17 @@ Return low-level information on the volume `name`
Content-Type: application/json
{
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis/_data",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local"
"Name": "tardis",
"Driver": "custom",
"Mountpoint": "/var/lib/docker/volumes/tardis/_data",
"Status": {
"hello": "world"
},
"Labels": {
"com.example.some-label": "some-value",
"com.example.some-other-label": "some-other-value"
},
"Scope": "local"
}
**Status codes**:
@ -3232,18 +3236,18 @@ Content-Type: application/json
"EnableIPv6": true,
"IPAM":{
"Config":[
{
"Subnet":"172.20.0.0/16",
"IPRange":"172.20.10.0/24",
"Gateway":"172.20.10.11"
},
{
"Subnet":"2001:db8:abcd::/64",
"Gateway":"2001:db8:abcd::1011"
}
{
"Subnet":"172.20.0.0/16",
"IPRange":"172.20.10.0/24",
"Gateway":"172.20.10.11"
},
{
"Subnet":"2001:db8:abcd::/64",
"Gateway":"2001:db8:abcd::1011"
}
],
"Options": {
"foo": "bar"
"foo": "bar"
}
},
"Internal":true,
@ -4449,7 +4453,6 @@ List services
### Create a service
`POST /services/create`
Create a service. When using this endpoint to create a service using a private
@ -4544,7 +4547,7 @@ image](#create-an-image) section for more details.
- **406** – server error or node is not part of a swarm
- **409** – name conflicts with an existing object
JSON Parameters:
**JSON Parameters**:
- **Name** – User-defined name for the service.
- **Labels** – A map of labels to associate with the service (e.g., `{"key":"value"[,"key2":"value2"]}`).
@ -4722,7 +4725,6 @@ Return information on the service `id`.
### Update a service
`POST /services/(id or name)/update`
Update a service. When using this endpoint to create a service using a
@ -4770,9 +4772,9 @@ image](#create-an-image) section for more details.
**Example response**:
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: text/plain; charset=utf-8
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: text/plain; charset=utf-8
**JSON Parameters**:

5284
docs/reference/api/docker_remote_api_v1.25.md Normal file
View file

File diff suppressed because it is too large Load diff

13
docs/reference/builder.md
View file

@ -120,7 +120,7 @@ instruction must be \`FROM\`** in order to specify the [*Base
Image*](glossary.md#base-image) from which you are building.
Docker treats lines that *begin* with `#` as a comment, unless the line is
a valid [parser directive](builder.md#parser directives). A `#` marker anywhere
a valid [parser directive](builder.md#parser-directives). A `#` marker anywhere
else in a line is treated as an argument. This allows statements like:
```Dockerfile
@ -541,6 +541,9 @@ RUN /bin/bash -c 'source $HOME/.bashrc ; echo $HOME'
> `RUN [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`.
> If you want shell processing then either use the *shell* form or execute
> a shell directly, for example: `RUN [ "sh", "-c", "echo $HOME" ]`.
> When using the exec form and executing a shell directly, as in the case for
> the shell form, it is the shell that is doing the environment variable
> expansion, not docker.
>
> **Note**:
> In the *JSON* form, it is necessary to escape backslashes. This is
@ -607,6 +610,9 @@ instruction as well.
> `CMD [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`.
> If you want shell processing then either use the *shell* form or execute
> a shell directly, for example: `CMD [ "sh", "-c", "echo $HOME" ]`.
> When using the exec form and executing a shell directly, as in the case for
> the shell form, it is the shell that is doing the environment variable
> expansion, not docker.
When used in the shell or exec formats, the `CMD` instruction sets the command
to be executed when running the image.
@ -1075,8 +1081,9 @@ sys 0m 0.03s
> `ENTRYPOINT [ "echo", "$HOME" ]` will not do variable substitution on `$HOME`.
> If you want shell processing then either use the *shell* form or execute
> a shell directly, for example: `ENTRYPOINT [ "sh", "-c", "echo $HOME" ]`.
> Variables that are defined in the `Dockerfile`using `ENV`, will be substituted by
> the `Dockerfile` parser.
> When using the exec form and executing a shell directly, as in the case for
> the shell form, it is the shell that is doing the environment variable
> expansion, not docker.
### Shell form ENTRYPOINT example

78
docs/reference/commandline/build.md
View file

@ -49,13 +49,18 @@ to any of the files in the context. For example, your build can use an
[*ADD*](../builder.md#add) instruction to reference a file in the
context.
The `URL` parameter can specify the location of a Git repository; the repository
acts as the build context. The system recursively clones the repository and its
submodules using a `git clone --depth 1 --recursive` command. This command runs
in a temporary directory on your local host. After the command succeeds, the
directory is sent to the Docker daemon as the context. Local clones give you the
ability to access private repositories using local user credentials, VPNs, and
so forth.
The `URL` parameter can refer to three kinds of resources: Git repositories,
pre-packaged tarball contexts and plain text files.
### Git repositories
When the `URL` parameter points to the location of a Git repository, the
repository acts as the build context. The system recursively clones the
repository and its submodules using a `git clone --depth 1 --recursive`
command. This command runs in a temporary directory on your local host. After
the command succeeds, the directory is sent to the Docker daemon as the
context. Local clones give you the ability to access private repositories using
local user credentials, VPN's, and so forth.
Git URLs accept context configuration in their fragment section, separated by a
colon `:`. The first part represents the reference that Git will check out,
@ -84,9 +89,29 @@ Build Syntax Suffix | Commit Used | Build Context Used
`myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder`
`myrepo.git#abcdef:myfolder` | `sha1 = abcdef` | `/myfolder`
### Tarball contexts
If you pass an URL to a remote tarball, the URL itself is sent to the daemon:
Instead of specifying a context, you can pass a single Dockerfile in the `URL`
or pipe the file in via `STDIN`. To pipe a Dockerfile from `STDIN`:
```bash
$ docker build http://server/context.tar.gz
The download operation will be performed on the host the Docker daemon is
running on, which is not necessarily the same host from which the build command
is being issued. The Docker daemon will fetch `context.tar.gz` and use it as the
build context. Tarball contexts must be tar archives conforming to the standard
`tar` UNIX format and can be compressed with any one of the 'xz', 'bzip2',
'gzip' or 'identity' (no compression) formats.
### Text files
Instead of specifying a context, you can pass a single `Dockerfile` in the
`URL` or pipe the file in via `STDIN`. To pipe a `Dockerfile` from `STDIN`:
```bash
$ docker build - < Dockerfile
```
@ -97,16 +122,16 @@ With Powershell on Windows, you can run:
Get-Content Dockerfile | docker build -
```
If you use STDIN or specify a `URL`, the system places the contents into a file
called `Dockerfile`, and any `-f`, `--file` option is ignored. In this
scenario, there is no context.
If you use `STDIN` or specify a `URL` pointing to a plain text file, the system
places the contents into a file called `Dockerfile`, and any `-f`, `--file`
option is ignored. In this scenario, there is no context.
By default the `docker build` command will look for a `Dockerfile` at the root
of the build context. The `-f`, `--file`, option lets you specify the path to
an alternative file to use instead. This is useful in cases where the same set
of files are used for multiple builds. The path must be to a file within the
build context. If a relative path is specified then it must to be relative to
the current directory.
build context. If a relative path is specified then it is interpreted as
relative to the root of the context.
In most cases, it's best to put each Dockerfile in an empty directory. Then,
add to that directory only the files needed for building the Dockerfile. To
@ -199,9 +224,32 @@ $ docker build github.com/creack/docker-firefox
```
This will clone the GitHub repository and use the cloned repository as context.
The Dockerfile at the root of the repository is used as Dockerfile. Note that
you can specify an arbitrary Git repository by using the `git://` or `git@`
scheme.
The Dockerfile at the root of the repository is used as Dockerfile. You can
specify an arbitrary Git repository by using the `git://` or `git@` scheme.
```bash
$ docker build -f ctx/Dockerfile http://server/ctx.tar.gz
Downloading context: http://server/ctx.tar.gz [===================>] 240 B/240 B
Step 0 : FROM busybox
---> 8c2e06607696
Step 1 : ADD ctx/container.cfg /
---> e7829950cee3
Removing intermediate container b35224abf821
Step 2 : CMD /bin/ls
---> Running in fbc63d321d73
---> 3286931702ad
Removing intermediate container fbc63d321d73
Successfully built 377c409b35e4
```
This sends the URL `http://server/ctx.tar.gz` to the Docker daemon, which
downloads and extracts the referenced tarball. The `-f ctx/Dockerfile`
parameter specifies a path inside `ctx.tar.gz` to the `Dockerfile` that is used
to build the image. Any `ADD` commands in that `Dockerfile` that refer to local
paths must be relative to the root of the contents inside `ctx.tar.gz`. In the
example above, the tarball contains a directory `ctx/`, so the `ADD
ctx/container.cfg /` operation works as expected.
### Build with -

2
docs/reference/commandline/swarm_leave.md
View file

@ -33,7 +33,7 @@ dkp8vy1dq1kxleu9g4u78tlag worker1 Ready Active Reachable
dvfxp4zseq4s0rih1selh0d20 * manager1 Ready Active Leader
```
On a worker node:
On a worker node, worker2 in the following example:
```bash
$ docker swarm leave
Node left the default swarm.

38
docs/reference/run.md
View file

@ -1138,11 +1138,30 @@ This can be overridden using a third `:rwm` set of options to each `--device` fl
In addition to `--privileged`, the operator can have fine grain control over the
capabilities using `--cap-add` and `--cap-drop`. By default, Docker has a default
list of capabilities that are kept. The following table lists the Linux capability options which can be added or dropped.
list of capabilities that are kept. The following table lists the Linux capability
options which are allowed by default and can be dropped.
| Capability Key | Capability Description |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| SETPCAP | Modify process capabilities. |
| MKNOD | Create special files using mknod(2). |
| AUDIT_WRITE | Write records to kernel auditing log. |
| CHOWN | Make arbitrary changes to file UIDs and GIDs (see chown(2)). |
| NET_RAW | Use RAW and PACKET sockets. |
| DAC_OVERRIDE | Bypass file read, write, and execute permission checks. |
| FOWNER | Bypass permission checks on operations that normally require the file system UID of the process to match the UID of the file. |
| FSETID | Don't clear set-user-ID and set-group-ID permission bits when a file is modified. |
| KILL | Bypass permission checks for sending signals. |
| SETGID | Make arbitrary manipulations of process GIDs and supplementary GID list. |
| SETUID | Make arbitrary manipulations of process UIDs. |
| NET_BIND_SERVICE | Bind a socket to internet domain privileged ports (port numbers less than 1024). |
| SYS_CHROOT | Use chroot(2), change root directory. |
| SETFCAP | Set file capabilities. |
The next table shows the capabilities which are not granted by default and may be added.
| Capability Key | Capability Description |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| SYS_MODULE | Load and unload kernel modules. |
| SYS_RAWIO | Perform I/O port operations (iopl(2) and ioperm(2)). |
| SYS_PACCT | Use acct(2), switch process accounting on or off. |
@ -1151,36 +1170,23 @@ list of capabilities that are kept. The following table lists the Linux capabili
| SYS_RESOURCE | Override resource Limits. |
| SYS_TIME | Set system clock (settimeofday(2), stime(2), adjtimex(2)); set real-time (hardware) clock. |
| SYS_TTY_CONFIG | Use vhangup(2); employ various privileged ioctl(2) operations on virtual terminals. |
| MKNOD | Create special files using mknod(2). |
| AUDIT_WRITE | Write records to kernel auditing log. |
| AUDIT_CONTROL | Enable and disable kernel auditing; change auditing filter rules; retrieve auditing status and filtering rules. |
| MAC_OVERRIDE | Allow MAC configuration or state changes. Implemented for the Smack LSM. |
| MAC_ADMIN | Override Mandatory Access Control (MAC). Implemented for the Smack Linux Security Module (LSM). |
| NET_ADMIN | Perform various network-related operations. |
| SYSLOG | Perform privileged syslog(2) operations. |
| CHOWN | Make arbitrary changes to file UIDs and GIDs (see chown(2)). |
| NET_RAW | Use RAW and PACKET sockets. |
| DAC_OVERRIDE | Bypass file read, write, and execute permission checks. |
| FOWNER | Bypass permission checks on operations that normally require the file system UID of the process to match the UID of the file. |
| DAC_READ_SEARCH | Bypass file read permission checks and directory read and execute permission checks. |
| FSETID | Don't clear set-user-ID and set-group-ID permission bits when a file is modified. |
| KILL | Bypass permission checks for sending signals. |
| SETGID | Make arbitrary manipulations of process GIDs and supplementary GID list. |
| SETUID | Make arbitrary manipulations of process UIDs. |
| LINUX_IMMUTABLE | Set the FS_APPEND_FL and FS_IMMUTABLE_FL i-node flags. |
| NET_BIND_SERVICE | Bind a socket to internet domain privileged ports (port numbers less than 1024). |
| NET_BROADCAST | Make socket broadcasts, and listen to multicasts. |
| IPC_LOCK | Lock memory (mlock(2), mlockall(2), mmap(2), shmctl(2)). |
| IPC_OWNER | Bypass permission checks for operations on System V IPC objects. |
| SYS_CHROOT | Use chroot(2), change root directory. |
| SYS_PTRACE | Trace arbitrary processes using ptrace(2). |
| SYS_BOOT | Use reboot(2) and kexec_load(2), reboot and load a new kernel for later execution. |
| LEASE | Establish leases on arbitrary files (see fcntl(2)). |
| SETFCAP | Set file capabilities. |
| WAKE_ALARM | Trigger something that will wake up the system. |
| BLOCK_SUSPEND | Employ features that can block system suspend.
| BLOCK_SUSPEND | Employ features that can block system suspend. |
Further reference information is available on the [capabilities(7) - Linux man page](http://linux.die.net/man/7/capabilities)
Further reference information is available on the [capabilities(7) - Linux man page](http://man7.org/linux/man-pages/man7/capabilities.7.html)
Both flags support the value `ALL`, so if the
operator wants to have all capabilities but `MKNOD` they could use:

1
docs/swarm/how-swarm-mode-works/menu.md
View file

@ -15,3 +15,4 @@ weight=11
## TOC
* [How nodes work](nodes.md)
* [How services work](services.md)

BIN
docs/swarm/images/ingress-lb.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 137 KiB

BIN
docs/swarm/images/ingress-routing-mesh.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 116 KiB

1
docs/swarm/images/src/ingress-lb.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 170 KiB

1
docs/swarm/images/src/ingress-routing-mesh.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 152 KiB

4
docs/swarm/index.md
View file

@ -34,7 +34,7 @@ a swarm.
* **Decentralized design:** Instead of handling differentiation between node
roles at deployment time, the Docker Engine handles any specialization at
runtime. You can deploy both kinds of nodes, managers and workers, using the
Docker Engine. This means you can build an entire Swarm from a single disk
Docker Engine. This means you can build an entire swarm from a single disk
image.
* **Declarative service model:** Docker Engine uses a declarative approach to
@ -50,7 +50,7 @@ adding or removing tasks to maintain the desired state.
the cluster state and reconciles any differences between the actual state your
expressed desired state. For example, if you set up a service to run 10
replicas of a container, and a worker machine hosting two of those replicas
crashes, the manager will create two new replicas to replace the ones that
crashes, the manager will create two new replicas to replace the replicas that
crashed. The swarm manager assigns the new replicas to workers that are
running and available.

132
docs/swarm/ingress.md Normal file
View file

@ -0,0 +1,132 @@
<!--[metadata]>
+++
title = "Use swarm mode routing mesh"
description = "Use the routing mesh to publish services externally to a swarm"
keywords = ["guide", "swarm mode", "swarm", "network", "ingress", "routing mesh"]
[menu.main]
identifier="ingress-guide"
parent="engine_swarm"
weight=17
+++
<![end-metadata]-->
# Use swarm mode routing mesh
Docker Engine swarm mode makes it easy to publish ports for services to make
them available to resources outside the swarm. All nodes participate in an
ingress **routing mesh**. The routing mesh enables each node in the swarm to
accept connections on published ports for any service running in the swarm, even
if there's no task running on the node. The routing mesh routes all
incoming requests to published ports on available nodes to an active container.
In order to use the ingress network in the swarm, you need to have the following
ports open between the swarm nodes before you enable swarm mode:
* Port `7946` TCP/UDP for container network discovery.
* Port `4789` UDP for the container ingress network.
You must also open the published port between the swarm nodes and any external
resources, such as an external load balancer, that require access to the port.
## Publish a port for a service
Use the `--publish` flag to publish a port when you create a service:
```bash
$ docker service create \
--name <SERVICE-NAME> \
--publish <PUBLISHED-PORT>:<TARGET-PORT> \
<IMAGE>
```
The `<TARGET-PORT>` is the port where the container listens.
The `<PUBLISHED-PORT>` is the port where the swarm makes the service available.
For example, the following command publishes port 80 in the nginx container to
port 8080 for any node in the swarm:
```bash
$ docker service create \
--name my-web \
--publish 8080:80 \
--replicas 2 \
nginx
```
When you access port 8080 on any node, the swarm load balancer routes your
request to an active container.
The routing mesh listens on the published port for any IP address assigned to
the node. For externally routable IP addresses, the port is available from
outside the host. For all other IP addresses the access is only available from
within the host.
![service ingress image](images/ingress-routing-mesh.png)
You can publish a port for an existing service using the following command:
```bash
$ docker service update \
--publish-add <PUBLISHED-PORT>:<TARGET-PORT> \
<SERVICE>
```
You can use `docker service inspect` to view the service's published port. For
instance:
```bash
$ docker service inspect --format="{{json .Endpoint.Spec.Ports}}" my-web
[{"Protocol":"tcp","TargetPort":80,"PublishedPort":8080}]
```
The output shows the `<TARGET-PORT>` from the containers and the
`<PUBLISHED-PORT>` where nodes listen for requests for the service.
## Configure an external load balancer
You can configure an external load balancer to route requests to a swarm
service. For example, you could configure [HAProxy](http://www.haproxy.org) to
balance requests to an nginx service published to port 8080.
![ingress with external load balancer image](images/ingress-lb.png)
In this case, port 8080 must be open between the load balancer and the nodes in
the swarm. The swarm nodes can reside on a private network that is accessible to
the proxy server, but that is not publicly accessible.
You can configure the load balancer to balance requests between every node in
the swarm even if the there are no tasks scheduled on the node. For example, you
could have the following HAProxy configuration in `/etc/haproxy/haproxy.cfg`:
```bash
global
log /dev/log local0
log /dev/log local1 notice
...snip...
# Configure HAProxy to listen on port 80
frontend http_front
bind *:80
stats uri /haproxy?stats
default_backend http_back
# Configure HAProxy to route requests to swarm nodes on port 8080
backend http_back
balance roundrobin
server node1 192.168.99.100:8080 check
server node2 192.168.99.101:8080 check
server node3 192.168.99.102:8080 check
```
When you access the HAProxy load balancer on port 80, it forwards requests to
nodes in the swarm. The swarm routing mesh routes the request to an active task.
If, for any reason the swarm scheduler dispatches tasks to different nodes, you
don't need to reconfigure the load balancer.
You can configure any type of load balancer to route requests to swarm nodes.
To learn more about HAProxy, see the [HAProxy documentation](https://cbonte.github.io/haproxy-dconv/).
## Learn more
* [Deploy services to a swarm](services.md)

2
docs/swarm/swarm-tutorial/delete-service.md
View file

@ -33,7 +33,7 @@ removed the service. The CLI returns a message that the service is not found:
```
$ docker service inspect helloworld
[]
Error: no such service or task: helloworld
Error: no such service: helloworld
```
## What's next?

2
hack/install.sh
View file

@ -421,7 +421,7 @@ do_install() {
if command -v apparmor_parser >/dev/null 2>&1; then
echo 'apparmor is enabled in the kernel and apparmor utils were already installed'
else
echo 'apparmor is enabled in the kernel, but apparmor_parser missing'
echo 'apparmor is enabled in the kernel, but apparmor_parser is missing. Trying to install it..'
apt_get_update
( set -x; $sh_c 'sleep 3; apt-get install -y -q apparmor' )
fi

696
image/spec/v1.2.md Normal file
View file

@ -0,0 +1,696 @@
# Docker Image Specification v1.2.0
An *Image* is an ordered collection of root filesystem changes and the
corresponding execution parameters for use within a container runtime. This
specification outlines the format of these filesystem changes and corresponding
parameters and describes how to create and use them for use with a container
runtime and execution tool.
This version of the image specification was adopted starting in Docker 1.12.
## Terminology
This specification uses the following terms:
<dl>
<dt>
Layer
</dt>
<dd>
Images are composed of <i>layers</i>. Each layer is a set of filesystem
changes. Layers do not have configuration metadata such as environment
variables or default arguments - these are properties of the image as a
whole rather than any particular layer.
</dd>
<dt>
Image JSON
</dt>
<dd>
Each image has an associated JSON structure which describes some
basic information about the image such as date created, author, and the
ID of its parent image as well as execution/runtime configuration like
its entry point, default arguments, CPU/memory shares, networking, and
volumes. The JSON structure also references a cryptographic hash of
each layer used by the image, and provides history information for
those layers. This JSON is considered to be immutable, because changing
it would change the computed ImageID. Changing it means creating a new
derived image, instead of changing the existing image.
</dd>
<dt>
Image Filesystem Changeset
</dt>
<dd>
Each layer has an archive of the files which have been added, changed,
or deleted relative to its parent layer. Using a layer-based or union
filesystem such as AUFS, or by computing the diff from filesystem
snapshots, the filesystem changeset can be used to present a series of
image layers as if they were one cohesive filesystem.
</dd>
<dt>
Layer DiffID
</dt>
<dd>
Layers are referenced by cryptographic hashes of their serialized
representation. This is a SHA256 digest over the tar archive used to
transport the layer, represented as a hexadecimal encoding of 256 bits, e.g.,
<code>sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9</code>.
Layers must be packed and unpacked reproducibly to avoid changing the
layer ID, for example by using tar-split to save the tar headers. Note
that the digest used as the layer ID is taken over an uncompressed
version of the tar.
</dd>
<dt>
Layer ChainID
</dt>
<dd>
For convenience, it is sometimes useful to refer to a stack of layers
with a single identifier. This is called a <code>ChainID</code>. For a
single layer (or the layer at the bottom of a stack), the
<code>ChainID</code> is equal to the layer's <code>DiffID</code>.
Otherwise the <code>ChainID</code> is given by the formula:
<code>ChainID(layerN) = SHA256hex(ChainID(layerN-1) + " " + DiffID(layerN))</code>.
</dd>
<dt>
ImageID <a name="id_desc"></a>
</dt>
<dd>
Each image's ID is given by the SHA256 hash of its configuration JSON. It is
represented as a hexadecimal encoding of 256 bits, e.g.,
<code>sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9</code>.
Since the configuration JSON that gets hashed references hashes of each
layer in the image, this formulation of the ImageID makes images
content-addresable.
</dd>
<dt>
Tag
</dt>
<dd>
A tag serves to map a descriptive, user-given name to any single image
ID. Tag values are limited to the set of characters
<code>[a-zA-Z0-9_.-]</code>, except they may not start with a <code>.</code>
or <code>-</code> character. Tags are limited to 127 characters.
</dd>
<dt>
Repository
</dt>
<dd>
A collection of tags grouped under a common prefix (the name component
before <code>:</code>). For example, in an image tagged with the name
<code>my-app:3.1.4</code>, <code>my-app</code> is the <i>Repository</i>
component of the name. A repository name is made up of slash-separated
name components, optionally prefixed by a DNS hostname. The hostname
must follow comply with standard DNS rules, but may not contain
<code>_</code> characters. If a hostname is present, it may optionally
be followed by a port number in the format <code>:8080</code>.
Name components may contain lowercase characters, digits, and
separators. A separator is defined as a period, one or two underscores,
or one or more dashes. A name component may not start or end with
a separator.
</dd>
</dl>
## Image JSON Description
Here is an example image JSON file:
```
{
"created": "2015-10-31T22:22:56.015925234Z",
"author": "Alyssa P. Hacker &ltalyspdev@example.com&gt",
"architecture": "amd64",
"os": "linux",
"config": {
"User": "alice",
"Memory": 2048,
"MemorySwap": 4096,
"CpuShares": 8,
"ExposedPorts": {
"8080/tcp": {}
},
"Env": [
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
"FOO=docker_is_a_really",
"BAR=great_tool_you_know"
],
"Entrypoint": [
"/bin/my-app-binary"
],
"Cmd": [
"--foreground",
"--config",
"/etc/my-app.d/default.cfg"
],
"Volumes": {
"/var/job-result-data": {},
"/var/log/my-app-logs": {},
},
"WorkingDir": "/home/alice",
},
"rootfs": {
"diff_ids": [
"sha256:c6f988f4874bb0add23a778f753c65efe992244e148a1d2ec2a8b664fb66bbd1",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
],
"type": "layers"
},
"history": [
{
"created": "2015-10-31T22:22:54.690851953Z",
"created_by": "/bin/sh -c #(nop) ADD file:a3bc1e842b69636f9df5256c49c5374fb4eef1e281fe3f282c65fb853ee171c5 in /"
},
{
"created": "2015-10-31T22:22:55.613815829Z",
"created_by": "/bin/sh -c #(nop) CMD [\"sh\"]",
"empty_layer": true
}
]
}
```
Note that image JSON files produced by Docker don't contain formatting
whitespace. It has been added to this example for clarity.
### Image JSON Field Descriptions
<dl>
<dt>
created <code>string</code>
</dt>
<dd>
ISO-8601 formatted combined date and time at which the image was
created.
</dd>
<dt>
author <code>string</code>
</dt>
<dd>
Gives the name and/or email address of the person or entity which
created and is responsible for maintaining the image.
</dd>
<dt>
architecture <code>string</code>
</dt>
<dd>
The CPU architecture which the binaries in this image are built to run
on. Possible values include:
<ul>
<li>386</li>
<li>amd64</li>
<li>arm</li>
</ul>
More values may be supported in the future and any of these may or may
not be supported by a given container runtime implementation.
</dd>
<dt>
os <code>string</code>
</dt>
<dd>
The name of the operating system which the image is built to run on.
Possible values include:
<ul>
<li>darwin</li>
<li>freebsd</li>
<li>linux</li>
</ul>
More values may be supported in the future and any of these may or may
not be supported by a given container runtime implementation.
</dd>
<dt>
config <code>struct</code>
</dt>
<dd>
The execution parameters which should be used as a base when running a
container using the image. This field can be <code>null</code>, in
which case any execution parameters should be specified at creation of
the container.
<h4>Container RunConfig Field Descriptions</h4>
<dl>
<dt>
User <code>string</code>
</dt>
<dd>
<p>The username or UID which the process in the container should
run as. This acts as a default value to use when the value is
not specified when creating a container.</p>
<p>All of the following are valid:</p>
<ul>
<li><code>user</code></li>
<li><code>uid</code></li>
<li><code>user:group</code></li>
<li><code>uid:gid</code></li>
<li><code>uid:group</code></li>
<li><code>user:gid</code></li>
</ul>
<p>If <code>group</code>/<code>gid</code> is not specified, the
default group and supplementary groups of the given
<code>user</code>/<code>uid</code> in <code>/etc/passwd</code>
from the container are applied.</p>
</dd>
<dt>
Memory <code>integer</code>
</dt>
<dd>
Memory limit (in bytes). This acts as a default value to use
when the value is not specified when creating a container.
</dd>
<dt>
MemorySwap <code>integer</code>
</dt>
<dd>
Total memory usage (memory + swap); set to <code>-1</code> to
disable swap. This acts as a default value to use when the
value is not specified when creating a container.
</dd>
<dt>
CpuShares <code>integer</code>
</dt>
<dd>
CPU shares (relative weight vs. other containers). This acts as
a default value to use when the value is not specified when
creating a container.
</dd>
<dt>
ExposedPorts <code>struct</code>
</dt>
<dd>
A set of ports to expose from a container running this image.
This JSON structure value is unusual because it is a direct
JSON serialization of the Go type
<code>map[string]struct{}</code> and is represented in JSON as
an object mapping its keys to an empty object. Here is an
example:
<pre>{
"8080": {},
"53/udp": {},
"2356/tcp": {}
}</pre>
Its keys can be in the format of:
<ul>
<li>
<code>"port/tcp"</code>
</li>
<li>
<code>"port/udp"</code>
</li>
<li>
<code>"port"</code>
</li>
</ul>
with the default protocol being <code>"tcp"</code> if not
specified.
These values act as defaults and are merged with any specified
when creating a container.
</dd>
<dt>
Env <code>array of strings</code>
</dt>
<dd>
Entries are in the format of <code>VARNAME="var value"</code>.
These values act as defaults and are merged with any specified
when creating a container.
</dd>
<dt>
Entrypoint <code>array of strings</code>
</dt>
<dd>
A list of arguments to use as the command to execute when the
container starts. This value acts as a default and is replaced
by an entrypoint specified when creating a container.
</dd>
<dt>
Cmd <code>array of strings</code>
</dt>
<dd>
Default arguments to the entry point of the container. These
values act as defaults and are replaced with any specified when
creating a container. If an <code>Entrypoint</code> value is
not specified, then the first entry of the <code>Cmd</code>
array should be interpreted as the executable to run.
</dd>
<dt>
Healthcheck <code>struct</code>
</dt>
<dd>
A test to perform to determine whether the container is healthy.
Here is an example:
<pre>{
"Test": [
"CMD-SHELL",
"/usr/bin/check-health localhost"
],
"Interval": 30000000000,
"Timeout": 10000000000,
"Retries": 3
}</pre>
The object has the following fields.
<dl>
<dt>
Test <code>array of strings</code>
</dt>
<dd>
The test to perform to check that the container is healthy.
The options are:
<ul>
<li><code>[]</code> : inherit healthcheck from base image</li>
<li><code>["NONE"]</code> : disable healthcheck</li>
<li><code>["CMD", arg1, arg2, ...]</code> : exec arguments directly</li>
<li><code>["CMD-SHELL", command]</code> : run command with system's default shell</li>
</ul>
The test command should exit with a status of 0 if the container is healthy,
or with 1 if it is unhealthy.
</dd>
<dt>
Interval <code>integer</code>
</dt>
<dd>
Number of nanoseconds to wait between probe attempts.
</dd>
<dt>
Timeout <code>integer</code>
</dt>
<dd>
Number of nanoseconds to wait before considering the check to have hung.
</dd>
<dt>
Retries <code>integer</code>
<dt>
<dd>
The number of consecutive failures needed to consider a container as unhealthy.
</dd>
</dl>
In each case, the field can be omitted to indicate that the
value should be inherited from the base layer.
These values act as defaults and are merged with any specified
when creating a container.
</dd>
<dt>
Volumes <code>struct</code>
</dt>
<dd>
A set of directories which should be created as data volumes in
a container running this image. This JSON structure value is
unusual because it is a direct JSON serialization of the Go
type <code>map[string]struct{}</code> and is represented in
JSON as an object mapping its keys to an empty object. Here is
an example:
<pre>{
"/var/my-app-data/": {},
"/etc/some-config.d/": {},
}</pre>
</dd>
<dt>
WorkingDir <code>string</code>
</dt>
<dd>
Sets the current working directory of the entry point process
in the container. This value acts as a default and is replaced
by a working directory specified when creating a container.
</dd>
</dl>
</dd>
<dt>
rootfs <code>struct</code>
</dt>
<dd>
The rootfs key references the layer content addresses used by the
image. This makes the image config hash depend on the filesystem hash.
rootfs has two subkeys:
<ul>
<li>
<code>type</code> is usually set to <code>layers</code>.
</li>
<li>
<code>diff_ids</code> is an array of layer content hashes (<code>DiffIDs</code>), in order from bottom-most to top-most.
</li>
</ul>
Here is an example rootfs section:
<pre>"rootfs": {
"diff_ids": [
"sha256:c6f988f4874bb0add23a778f753c65efe992244e148a1d2ec2a8b664fb66bbd1",
"sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
"sha256:13f53e08df5a220ab6d13c58b2bf83a59cbdc2e04d0a3f041ddf4b0ba4112d49"
],
"type": "layers"
}</pre>
</dd>
<dt>
history <code>struct</code>
</dt>
<dd>
<code>history</code> is an array of objects describing the history of
each layer. The array is ordered from bottom-most layer to top-most
layer. The object has the following fields.
<ul>
<li>
<code>created</code>: Creation time, expressed as a ISO-8601 formatted
combined date and time
</li>
<li>
<code>author</code>: The author of the build point
</li>
<li>
<code>created_by</code>: The command which created the layer
</li>
<li>
<code>comment</code>: A custom message set when creating the layer
</li>
<li>
<code>empty_layer</code>: This field is used to mark if the history
item created a filesystem diff. It is set to true if this history
item doesn't correspond to an actual layer in the rootfs section
(for example, a command like ENV which results in no change to the
filesystem).
</li>
</ul>
Here is an example history section:
<pre>"history": [
{
"created": "2015-10-31T22:22:54.690851953Z",
"created_by": "/bin/sh -c #(nop) ADD file:a3bc1e842b69636f9df5256c49c5374fb4eef1e281fe3f282c65fb853ee171c5 in /"
},
{
"created": "2015-10-31T22:22:55.613815829Z",
"created_by": "/bin/sh -c #(nop) CMD [\"sh\"]",
"empty_layer": true
}
]</pre>
</dd>
</dl>
Any extra fields in the Image JSON struct are considered implementation
specific and should be ignored by any implementations which are unable to
interpret them.
## Creating an Image Filesystem Changeset
An example of creating an Image Filesystem Changeset follows.
An image root filesystem is first created as an empty directory. Here is the
initial empty directory structure for the a changeset using the
randomly-generated directory name `c3167915dc9d` ([actual layer DiffIDs are
generated based on the content](#id_desc)).
```
c3167915dc9d/
```
Files and directories are then created:
```
c3167915dc9d/
etc/
my-app-config
bin/
my-app-binary
my-app-tools
```
The `c3167915dc9d` directory is then committed as a plain Tar archive with
entries for the following files:
```
etc/my-app-config
bin/my-app-binary
bin/my-app-tools
```
To make changes to the filesystem of this container image, create a new
directory, such as `f60c56784b83`, and initialize it with a snapshot of the
parent image's root filesystem, so that the directory is identical to that
of `c3167915dc9d`. NOTE: a copy-on-write or union filesystem can make this very
efficient:
```
f60c56784b83/
etc/
my-app-config
bin/
my-app-binary
my-app-tools
```
This example change is going add a configuration directory at `/etc/my-app.d`
which contains a default config file. There's also a change to the
`my-app-tools` binary to handle the config layout change. The `f60c56784b83`
directory then looks like this:
```
f60c56784b83/
etc/
my-app.d/
default.cfg
bin/
my-app-binary
my-app-tools
```
This reflects the removal of `/etc/my-app-config` and creation of a file and
directory at `/etc/my-app.d/default.cfg`. `/bin/my-app-tools` has also been
replaced with an updated version. Before committing this directory to a
changeset, because it has a parent image, it is first compared with the
directory tree of the parent snapshot, `f60c56784b83`, looking for files and
directories that have been added, modified, or removed. The following changeset
is found:
```
Added: /etc/my-app.d/default.cfg
Modified: /bin/my-app-tools
Deleted: /etc/my-app-config
```
A Tar Archive is then created which contains *only* this changeset: The added
and modified files and directories in their entirety, and for each deleted item
an entry for an empty file at the same location but with the basename of the
deleted file or directory prefixed with `.wh.`. The filenames prefixed with
`.wh.` are known as "whiteout" files. NOTE: For this reason, it is not possible
to create an image root filesystem which contains a file or directory with a
name beginning with `.wh.`. The resulting Tar archive for `f60c56784b83` has
the following entries:
```
/etc/my-app.d/default.cfg
/bin/my-app-tools
/etc/.wh.my-app-config
```
Any given image is likely to be composed of several of these Image Filesystem
Changeset tar archives.
## Combined Image JSON + Filesystem Changeset Format
There is also a format for a single archive which contains complete information
about an image, including:
- repository names/tags
- image configuration JSON file
- all tar archives of each layer filesystem changesets
For example, here's what the full archive of `library/busybox` is (displayed in
`tree` format):
```
.
├── 47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb.json
├── 5f29f704785248ddb9d06b90a11b5ea36c534865e9035e4022bb2e71d4ecbb9a
│   ├── VERSION
│   ├── json
│   └── layer.tar
├── a65da33792c5187473faa80fa3e1b975acba06712852d1dea860692ccddf3198
│   ├── VERSION
│   ├── json
│   └── layer.tar
├── manifest.json
└── repositories
```
There is a directory for each layer in the image. Each directory is named with
a 64 character hex name that is deterministically generated from the layer
information. These names are not necessarily layer DiffIDs or ChainIDs. Each of
these directories contains 3 files:
* `VERSION` - The schema version of the `json` file
* `json` - The legacy JSON metadata for an image layer. In this version of
the image specification, layers don't have JSON metadata, but in
[version 1](v1.md), they did. A file is created for each layer in the
v1 format for backward compatibility.
* `layer.tar` - The Tar archive of the filesystem changeset for an image
layer.
Note that this directory layout is only important for backward compatibility.
Current implementations use the paths specified in `manifest.json`.
The content of the `VERSION` files is simply the semantic version of the JSON
metadata schema:
```
1.0
```
The `repositories` file is another JSON file which describes names/tags:
```
{
"busybox":{
"latest":"5f29f704785248ddb9d06b90a11b5ea36c534865e9035e4022bb2e71d4ecbb9a"
}
}
```
Every key in this object is the name of a repository, and maps to a collection
of tag suffixes. Each tag maps to the ID of the image represented by that tag.
This file is only used for backwards compatibility. Current implementations use
the `manifest.json` file instead.
The `manifest.json` file provides the image JSON for the top-level image, and
optionally for parent images that this image was derived from. It consists of
an array of metadata entries:
```
[
{
"Config": "47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb.json",
"RepoTags": ["busybox:latest"],
"Layers": [
"a65da33792c5187473faa80fa3e1b975acba06712852d1dea860692ccddf3198/layer.tar",
"5f29f704785248ddb9d06b90a11b5ea36c534865e9035e4022bb2e71d4ecbb9a/layer.tar"
]
}
]
```
There is an entry in the array for each image.
The `Config` field references another file in the tar which includes the image
JSON for this image.
The `RepoTags` field lists references pointing to this image.
The `Layers` field points to the filesystem changeset tars.
An optional `Parent` field references the imageID of the parent image. This
parent must be part of the same `manifest.json` file.
This file shouldn't be confused with the distribution manifest, used to push
and pull images.
Generally, implementations that support this version of the spec will use
the `manifest.json` file if available, and older implementations will use the
legacy `*/json` files and `repositories`.