From 4858230a073ea5c3c8609f29020c23ac4e012b01 Mon Sep 17 00:00:00 2001 From: Chun Chen Date: Tue, 5 Apr 2016 15:35:24 +0800 Subject: [PATCH 01/25] Add docs about how to extend devicemapper thin pool Signed-off-by: Chun Chen (cherry picked from commit b21d90c28faaa9f906c4e3b2145ddf661a19e994) Signed-off-by: Sebastiaan van Stijn --- contrib/docker-device-tool/README.md | 14 ++ .../storagedriver/device-mapper-driver.md | 166 ++++++++++++++++++ 2 files changed, 180 insertions(+) create mode 100644 contrib/docker-device-tool/README.md diff --git a/contrib/docker-device-tool/README.md b/contrib/docker-device-tool/README.md new file mode 100644 index 0000000000..1bf11d202c --- /dev/null +++ b/contrib/docker-device-tool/README.md @@ -0,0 +1,14 @@ +Docker device tool for devicemapper storage driver backend +=================== + +The ./contrib/docker-device-tool contains a tool to manipulate devicemapper thin-pool. + +Compile +======== + + $ make shell + ## inside build container + $ go build contrib/docker-device-tool/device_tool.go + + # if devicemapper version is old and compliation fails, compile with `libdm_no_deferred_remove` tag + $ go build -tags libdm_no_deferred_remove contrib/docker-device-tool/device_tool.go diff --git a/docs/userguide/storagedriver/device-mapper-driver.md b/docs/userguide/storagedriver/device-mapper-driver.md index 4b7b664d1b..1802d10167 100644 --- a/docs/userguide/storagedriver/device-mapper-driver.md +++ b/docs/userguide/storagedriver/device-mapper-driver.md @@ -397,6 +397,172 @@ there are two key directories. The `/var/lib/docker/devicemapper/mnt` directory image layer and container snapshot. The files contain metadata about each snapshot in JSON format. +## Increase capacity on a running device + +You can increase the capacity of the pool on a running thin-pool device. This is +useful if the data's logical volume is full and the volume group is at full +capacity. + +### For a loop-lvm configuration + +In this scenario, the thin pool is configured to use `loop-lvm` mode. To show the specifics of the existing configuration use `docker info`: + +```bash +$ sudo docker info +Containers: 0 + Running: 0 + Paused: 0 + Stopped: 0 +Images: 2 +Server Version: 1.11.0-rc2 +Storage Driver: devicemapper + Pool Name: docker-8:1-123141-pool + Pool Blocksize: 65.54 kB + Base Device Size: 10.74 GB + Backing Filesystem: ext4 + Data file: /dev/loop0 + Metadata file: /dev/loop1 + Data Space Used: 1.202 GB + Data Space Total: 107.4 GB + Data Space Available: 4.506 GB + Metadata Space Used: 1.729 MB + Metadata Space Total: 2.147 GB + Metadata Space Available: 2.146 GB + Udev Sync Supported: true + Deferred Removal Enabled: false + Deferred Deletion Enabled: false + Deferred Deleted Device Count: 0 + Data loop file: /var/lib/docker/devicemapper/devicemapper/data + WARNING: Usage of loopback devices is strongly discouraged for production use. Either use `--storage-opt dm.thinpooldev` or use `--storage-opt dm.no_warn_on_loop_devices=true` to suppress this warning. + Metadata loop file: /var/lib/docker/devicemapper/devicemapper/metadata + Library Version: 1.02.90 (2014-09-01) +Logging Driver: json-file +[...] +``` + +The `Data Space` values show that the pool is 100GiB total. This example extends the pool to 200GiB. + +1. List the sizes of the devices. + + ```bash + $ sudo ls -lh /var/lib/docker/devicemapper/devicemapper/ + total 1.2G + -rw------- 1 root root 100G Apr 14 08:47 data + -rw------- 1 root root 2.0G Apr 19 13:27 metadata + ``` + +2. Truncate `data` file to 200GiB. + + ```bash + $ sudo truncate -s 214748364800 /var/lib/docker/devicemapper/devicemapper/data + ``` + +3. Verify the file size changed. + + ```bash + $ sudo ls -lh /var/lib/docker/devicemapper/devicemapper/ + total 1.2G + -rw------- 1 root root 200G Apr 14 08:47 data + -rw------- 1 root root 2.0G Apr 19 13:27 metadata + ``` + +4. Reload data loop device + + ```bash + $ sudo blockdev --getsize64 /dev/loop0 + 107374182400 + $ sudo losetup -c /dev/loop0 + $ sudo blockdev --getsize64 /dev/loop0 + 214748364800 + ``` + +5. Reload devicemapper thin pool. + + a. Get the pool name first. + + $ sudo dmsetup status | grep pool + docker-8:1-123141-pool: 0 209715200 thin-pool 91 422/524288 18338/1638400 - rw discard_passdown queue_if_no_space - + + The name is the string before the colon. + + b. Dump the device mapper table first. + + $ sudo dmsetup table docker-8:1-123141-pool + 0 209715200 thin-pool 7:1 7:0 128 32768 1 skip_block_zeroing + + c. Calculate the real total sectors of the thin pool now. + + Change the second number of the table info (i.e. the number of sectors) to reflect the new number of 512 byte sectors in the disk. For example, as the new loop size is 200GiB, change the second number to 419430400. + + d. Reload the thin pool with the new sector number + + $ sudo dmsetup suspend docker-8:1-123141-pool && sudo dmsetup reload docker-8:1-123141-pool --table '0 419430400 thin-pool 7:1 7:0 128 32768 1 skip_block_zeroing' && sudo dmsetup resume docker-8:1-123141-pool + +#### The device_tool + +The Docker's projects `contrib` directory contains not part of the core +distribution. These tools that are often useful but can also be out-of-date. In this directory, is the `device_tool.go` +which you can also resize the loop-lvm thin pool. + +To use the tool, compile it first. Then, do the following to resize the pool: + +```bash +$ ./device_tool resize 200GB +``` + +### For a direct-lvm mode configuration + +In this example, you extend the capacity of a running device that uses the +`direct-lvm` configuration. This example assumes you are using the `/dev/sdh1` +disk partition. + +1. Extend the volume group (VG) `vg-docker`. + + ```bash + $ sudo vgextend vg-docker /dev/sdh1 + Volume group "vg-docker" successfully extended + ``` + + Your volume group may use a different name. + +2. Extend the `data` logical volume(LV) `vg-docker/data` + + ```bash + $ sudo lvextend -l+100%FREE -n vg-docker/data + Extending logical volume data to 200 GiB + Logical volume data successfully resized + ``` + +3. Reload devicemapper thin pool. + + a. Get the pool name. + + $ sudo dmsetup status | grep pool + docker-253:17-1835016-pool: 0 96460800 thin-pool 51593 6270/1048576 701943/753600 - rw no_discard_passdown queue_if_no_space + + The name is the string before the colon. + + b. Dump the device mapper table. + + $ sudo dmsetup table docker-253:17-1835016-pool + 0 96460800 thin-pool 252:0 252:1 128 32768 1 skip_block_zeroing + + c. Calculate the real total sectors of the thin pool now. we can use `blockdev` to get the real size of data lv. + + Change the second number of the table info (i.e. the number of sectors) to + reflect the new number of 512 byte sectors in the disk. For example, as the + new data `lv` size is `264132100096` bytes, change the second number to + `515883008`. + + $ sudo blockdev --getsize64 /dev/vg-docker/data + 264132100096 + + d. Then reload the thin pool with the new sector number. + + $ sudo dmsetup suspend docker-253:17-1835016-pool && sudo dmsetup reload docker-253:17-1835016-pool --table '0 515883008 thin-pool 252:0 252:1 128 32768 1 skip_block_zeroing' && sudo dmsetup resume docker-253:17-1835016-pool + + ## Device Mapper and Docker performance It is important to understand the impact that allocate-on-demand and From 8d2798c37ee0a2f56b3ec085f07d59d948908625 Mon Sep 17 00:00:00 2001 From: Jess Frazelle Date: Thu, 7 Apr 2016 12:05:16 -0700 Subject: [PATCH 02/25] Add example to apparmor docs Signed-off-by: Jess Frazelle (cherry picked from commit 80d63e2e112c75b1cc492ce52bdc0c61ef3c234c) Signed-off-by: Sebastiaan van Stijn --- docs/security/apparmor.md | 181 +++++++++++++++++++++++++++++++++----- 1 file changed, 158 insertions(+), 23 deletions(-) diff --git a/docs/security/apparmor.md b/docs/security/apparmor.md index b0998f84c7..bc80a24509 100644 --- a/docs/security/apparmor.md +++ b/docs/security/apparmor.md @@ -20,8 +20,8 @@ Docker automatically loads container profiles. The Docker binary installs a `docker-default` profile in the `/etc/apparmor.d/docker` file. This profile is used on containers, _not_ on the Docker Daemon. -A profile for the Docker Engine Daemon exists but it is not currently installed -with the deb packages. If you are interested in the source for the Daemon +A profile for the Docker Engine daemon exists but it is not currently installed +with the `deb` packages. If you are interested in the source for the daemon profile, it is located in [contrib/apparmor](https://github.com/docker/docker/tree/master/contrib/apparmor) in the Docker Engine source repository. @@ -72,15 +72,15 @@ explicitly specifies the default policy: $ docker run --rm -it --security-opt apparmor=docker-default hello-world ``` -## Loading and Unloading Profiles +## Load and unload profiles -To load a new profile into AppArmor, for use with containers: +To load a new profile into AppArmor for use with containers: -``` +```bash $ apparmor_parser -r -W /path/to/your_profile ``` -Then you can run the custom profile with `--security-opt` like so: +Then, run the custom profile with `--security-opt` like so: ```bash $ docker run --rm -it --security-opt apparmor=your_profile hello-world @@ -97,39 +97,174 @@ $ apparmor_parser -R /path/to/profile $ /etc/init.d/apparmor start ``` -## Debugging AppArmor +### Resources for writing profiles -### Using `dmesg` +The syntax for file globbing in AppArmor is a bit different than some other +globbing implementations. It is highly suggested you take a look at some of the +below resources with regard to AppArmor profile syntax. + +- [Quick Profile Language](http://wiki.apparmor.net/index.php/QuickProfileLanguage) +- [Globbing Syntax](http://wiki.apparmor.net/index.php/AppArmor_Core_Policy_Reference#AppArmor_globbing_syntax) + +## Nginx example profile + +In this example, you create a custom AppArmor profile for Nginx. Below is the +custom profile. + +``` +#include + + +profile docker-nginx flags=(attach_disconnected,mediate_deleted) { + #include + + network inet tcp, + network inet udp, + network inet icmp, + + deny network raw, + + deny network packet, + + file, + umount, + + deny /bin/** wl, + deny /boot/** wl, + deny /dev/** wl, + deny /etc/** wl, + deny /home/** wl, + deny /lib/** wl, + deny /lib64/** wl, + deny /media/** wl, + deny /mnt/** wl, + deny /opt/** wl, + deny /proc/** wl, + deny /root/** wl, + deny /sbin/** wl, + deny /srv/** wl, + deny /tmp/** wl, + deny /sys/** wl, + deny /usr/** wl, + + audit /** w, + + /var/run/nginx.pid w, + + /usr/sbin/nginx ix, + + deny /bin/dash mrwklx, + deny /bin/sh mrwklx, + deny /usr/bin/top mrwklx, + + + capability chown, + capability dac_override, + capability setuid, + capability setgid, + capability net_bind_service, + + deny @{PROC}/{*,**^[0-9*],sys/kernel/shm*} wkx, + deny @{PROC}/sysrq-trigger rwklx, + deny @{PROC}/mem rwklx, + deny @{PROC}/kmem rwklx, + deny @{PROC}/kcore rwklx, + deny mount, + deny /sys/[^f]*/** wklx, + deny /sys/f[^s]*/** wklx, + deny /sys/fs/[^c]*/** wklx, + deny /sys/fs/c[^g]*/** wklx, + deny /sys/fs/cg[^r]*/** wklx, + deny /sys/firmware/efi/efivars/** rwklx, + deny /sys/kernel/security/** rwklx, +} +``` + +1. Save the custom profile to disk in the +`/etc/apparmor.d/containers/docker-nginx` file. + + The file path in this example is not a requirement. In production, you could + use another. + +2. Load the profile. + + ```bash + $ sudo apparmor_parser -r -W /etc/apparmor.d/containers/docker-nginx + ``` + +3. Run a container with the profile. + + To run nginx in detached mode: + + ```bash + $ docker run --security-opt "apparmor=docker-nginx" \ + -p 80:80 -d --name apparmor-nginx nginx + ``` + +4. Exec into the running container + + ```bash + $ docker exec -it apparmor-nginx bash + ``` + +5. Try some operations to test the profile. + + ```bash + root@6da5a2a930b9:~# ping 8.8.8.8 + ping: Lacking privilege for raw socket. + + root@6da5a2a930b9:/# top + bash: /usr/bin/top: Permission denied + + root@6da5a2a930b9:~# touch ~/thing + touch: cannot touch 'thing': Permission denied + + root@6da5a2a930b9:/# sh + bash: /bin/sh: Permission denied + + root@6da5a2a930b9:/# dash + bash: /bin/dash: Permission denied + ``` + + +Congrats! You just deployed a container secured with a custom apparmor profile! + + +## Debug AppArmor + +You can use `demsg` to debug problems and `aa-status` check the loaded profiles. + +### Use dmesg Here are some helpful tips for debugging any problems you might be facing with regard to AppArmor. AppArmor sends quite verbose messaging to `dmesg`. Usually an AppArmor line -will look like the following: +looks like the following: ``` [ 5442.864673] audit: type=1400 audit(1453830992.845:37): apparmor="ALLOWED" operation="open" profile="/usr/bin/docker" name="/home/jessie/docker/man/man1/docker-attach.1" pid=10923 comm="docker" requested_mask="r" denied_mask="r" fsuid=1000 ouid=0 ``` -In the above example, the you can see `profile=/usr/bin/docker`. This means the +In the above example, you can see `profile=/usr/bin/docker`. This means the user has the `docker-engine` (Docker Engine Daemon) profile loaded. > **Note:** On version of Ubuntu > 14.04 this is all fine and well, but Trusty > users might run into some issues when trying to `docker exec`. -Let's look at another log line: +Look at another log line: ``` [ 3256.689120] type=1400 audit(1405454041.341:73): apparmor="DENIED" operation="ptrace" profile="docker-default" pid=17651 comm="docker" requested_mask="receive" denied_mask="receive" ``` This time the profile is `docker-default`, which is run on containers by -default unless in `privileged` mode. It is telling us, that apparmor has denied -`ptrace` in the container. This is great. +default unless in `privileged` mode. This line shows that apparmor has denied +`ptrace` in the container. This is exactly as expected. -### Using `aa-status` +### Use aa-status -If you need to check which profiles are loaded you can use `aa-status`. The +If you need to check which profiles are loaded, you can use `aa-status`. The output looks like: ```bash @@ -162,17 +297,17 @@ apparmor module is loaded. 0 processes are unconfined but have a profile defined. ``` -In the above output you can tell that the `docker-default` profile running on -various container PIDs is in `enforce` mode. This means AppArmor will actively -block and audit in `dmesg` anything outside the bounds of the `docker-default` +The above output shows that the `docker-default` profile running on various +container PIDs is in `enforce` mode. This means AppArmor is actively blocking +and auditing in `dmesg` anything outside the bounds of the `docker-default` profile. -The output above also shows the `/usr/bin/docker` (Docker Engine Daemon) -profile is running in `complain` mode. This means AppArmor will _only_ log to -`dmesg` activity outside the bounds of the profile. (Except in the case of -Ubuntu Trusty, where we have seen some interesting behaviors being enforced.) +The output above also shows the `/usr/bin/docker` (Docker Engine daemon) profile +is running in `complain` mode. This means AppArmor _only_ logs to `dmesg` +activity outside the bounds of the profile. (Except in the case of Ubuntu +Trusty, where some interesting behaviors are enforced.) -## Contributing to AppArmor code in Docker +## Contribute Docker's AppArmor code Advanced users and package managers can find a profile for `/usr/bin/docker` (Docker Engine Daemon) underneath From 9af185e3d013a5444f57aa09f83f4c07bfc8f56e Mon Sep 17 00:00:00 2001 From: Robin Naundorf Date: Thu, 14 Apr 2016 15:21:07 +0200 Subject: [PATCH 03/25] closes #11703 closes #11560 Signed-off-by: Robin Naundorf (cherry picked from commit 297d6c04a31f39ff24fcebad8d82c43e0bcf6900) Signed-off-by: Sebastiaan van Stijn --- docs/admin/cfengine_process_management.md | 150 ---------------------- 1 file changed, 150 deletions(-) delete mode 100644 docs/admin/cfengine_process_management.md diff --git a/docs/admin/cfengine_process_management.md b/docs/admin/cfengine_process_management.md deleted file mode 100644 index be62e410c2..0000000000 --- a/docs/admin/cfengine_process_management.md +++ /dev/null @@ -1,150 +0,0 @@ - - -# Process management with CFEngine - -Create Docker containers with managed processes. - -Docker monitors one process in each running container and the container -lives or dies with that process. By introducing CFEngine inside Docker -containers, we can alleviate a few of the issues that may arise: - - - It is possible to easily start multiple processes within a - container, all of which will be managed automatically, with the - normal `docker run` command. - - If a managed process dies or crashes, CFEngine will start it again - within 1 minute. - - The container itself will live as long as the CFEngine scheduling - daemon (cf-execd) lives. With CFEngine, we are able to decouple the - life of the container from the uptime of the service it provides. - -## How it works - -CFEngine, together with the cfe-docker integration policies, are -installed as part of the Dockerfile. This builds CFEngine into our -Docker image. - -The Dockerfile's `ENTRYPOINT` takes an arbitrary -amount of commands (with any desired arguments) as parameters. When we -run the Docker container these parameters get written to CFEngine -policies and CFEngine takes over to ensure that the desired processes -are running in the container. - -CFEngine scans the process table for the `basename` of the commands given -to the `ENTRYPOINT` and runs the command to start the process if the `basename` -is not found. For example, if we start the container with -`docker run "/path/to/my/application parameters"`, CFEngine will look for a -process named `application` and run the command. If an entry for `application` -is not found in the process table at any point in time, CFEngine will execute -`/path/to/my/application parameters` to start the application once again. The -check on the process table happens every minute. - -Note that it is therefore important that the command to start your -application leaves a process with the basename of the command. This can -be made more flexible by making some minor adjustments to the CFEngine -policies, if desired. - -## Usage - -This example assumes you have Docker installed and working. We will -install and manage `apache2` and `sshd` -in a single container. - -There are three steps: - -1. Install CFEngine into the container. -2. Copy the CFEngine Docker process management policy into the - containerized CFEngine installation. -3. Start your application processes as part of the `docker run` command. - -### Building the image - -The first two steps can be done as part of a Dockerfile, as follows. - - FROM ubuntu - MAINTAINER Eystein Måløy Stenberg - - RUN apt-get update && apt-get install -y wget lsb-release unzip ca-certificates - - # install latest CFEngine - RUN wget -qO- http://cfengine.com/pub/gpg.key | apt-key add - - RUN echo "deb http://cfengine.com/pub/apt $(lsb_release -cs) main" > /etc/apt/sources.list.d/cfengine-community.list - RUN apt-get update && apt-get install -y cfengine-community - - # install cfe-docker process management policy - RUN wget https://github.com/estenberg/cfe-docker/archive/master.zip -P /tmp/ && unzip /tmp/master.zip -d /tmp/ - RUN cp /tmp/cfe-docker-master/cfengine/bin/* /var/cfengine/bin/ - RUN cp /tmp/cfe-docker-master/cfengine/inputs/* /var/cfengine/inputs/ - RUN rm -rf /tmp/cfe-docker-master /tmp/master.zip - - # apache2 and openssh are just for testing purposes, install your own apps here - RUN apt-get update && apt-get install -y openssh-server apache2 - RUN mkdir -p /var/run/sshd - RUN echo "root:password" | chpasswd # need a password for ssh - - ENTRYPOINT ["/var/cfengine/bin/docker_processes_run.sh"] - -By saving this file as Dockerfile to a working directory, you can then build -your image with the docker build command, e.g., -`docker build -t managed_image`. - -### Testing the container - -Start the container with `apache2` and `sshd` running and managed, forwarding -a port to our SSH instance: - - $ docker run -p 127.0.0.1:222:22 -d managed_image "/usr/sbin/sshd" "/etc/init.d/apache2 start" - -We now clearly see one of the benefits of the cfe-docker integration: it -allows to start several processes as part of a normal `docker run` command. - -We can now log in to our new container and see that both `apache2` and `sshd` -are running. We have set the root password to "password" in the Dockerfile -above and can use that to log in with ssh: - - ssh -p222 root@127.0.0.1 - - ps -ef - UID PID PPID C STIME TTY TIME CMD - root 1 0 0 07:48 ? 00:00:00 /bin/bash /var/cfengine/bin/docker_processes_run.sh /usr/sbin/sshd /etc/init.d/apache2 start - root 18 1 0 07:48 ? 00:00:00 /var/cfengine/bin/cf-execd -F - root 20 1 0 07:48 ? 00:00:00 /usr/sbin/sshd - root 32 1 0 07:48 ? 00:00:00 /usr/sbin/apache2 -k start - www-data 34 32 0 07:48 ? 00:00:00 /usr/sbin/apache2 -k start - www-data 35 32 0 07:48 ? 00:00:00 /usr/sbin/apache2 -k start - www-data 36 32 0 07:48 ? 00:00:00 /usr/sbin/apache2 -k start - root 93 20 0 07:48 ? 00:00:00 sshd: root@pts/0 - root 105 93 0 07:48 pts/0 00:00:00 -bash - root 112 105 0 07:49 pts/0 00:00:00 ps -ef - -If we stop apache2, it will be started again within a minute by -CFEngine. - - service apache2 status - Apache2 is running (pid 32). - service apache2 stop - * Stopping web server apache2 ... waiting [ OK ] - service apache2 status - Apache2 is NOT running. - # ... wait up to 1 minute... - service apache2 status - Apache2 is running (pid 173). - -## Adapting to your applications - -To make sure your applications get managed in the same manner, there are -just two things you need to adjust from the above example: - - - In the Dockerfile used above, install your applications instead of - `apache2` and `sshd`. - - When you start the container with `docker run`, - specify the command line arguments to your applications rather than - `apache2` and `sshd`. From d9cf30d7de4cdf0acc41217a1b5349303f6a15ce Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 14 Apr 2016 15:04:33 +0200 Subject: [PATCH 04/25] docs: update API for features added in 1.11 Docker 1.11 added a feature to set labels on volumes, networks and images (during build), but these changes were not documented in the API documentation. This adds the new features to the documentation. Also fixes some minor formatting, and options that were not used in the examples. Signed-off-by: Sebastiaan van Stijn (cherry picked from commit ba353f37870fdeb8b875a79e1aec54dc3d1aedc4) Signed-off-by: Sebastiaan van Stijn --- docs/reference/api/docker_remote_api_v1.23.md | 54 +++++++++++++++---- 1 file changed, 43 insertions(+), 11 deletions(-) diff --git a/docs/reference/api/docker_remote_api_v1.23.md b/docs/reference/api/docker_remote_api_v1.23.md index 8b43f82bb8..30f556255c 100644 --- a/docs/reference/api/docker_remote_api_v1.23.md +++ b/docs/reference/api/docker_remote_api_v1.23.md @@ -517,8 +517,8 @@ Return low-level information on the container `id` "Tty": false, "User": "", "Volumes": { - "/volumes/data": {} - }, + "/volumes/data": {} + }, "WorkingDir": "", "StopSignal": "SIGTERM" }, @@ -1660,7 +1660,7 @@ Query Parameters: 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`. + 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. @@ -1678,6 +1678,7 @@ Query Parameters: variable expansion in other Dockerfile instructions. This is not meant for 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. +- **labels** – JSON map of string pairs for labels to set on the image. Request Headers: @@ -2639,7 +2640,7 @@ interactive session with the `exec` command. **Example response**: HTTP/1.1 200 OK - Content-Type: vnd.docker.raw-stream + Content-Type: application/vnd.docker.raw-stream {{ STREAM }} @@ -2774,7 +2775,11 @@ Create a volume Content-Type: application/json { - "Name": "tardis" + "Name": "tardis", + "Labels": { + "com.example.some-label": "some-value", + "com.example.some-other-label": "some-other-value" + }, } **Example response**: @@ -2785,7 +2790,11 @@ Create a volume { "Name": "tardis", "Driver": "local", - "Mountpoint": "/var/lib/docker/volumes/tardis" + "Mountpoint": "/var/lib/docker/volumes/tardis", + "Labels": { + "com.example.some-label": "some-value", + "com.example.some-other-label": "some-other-value" + }, } Status Codes: @@ -2799,6 +2808,7 @@ JSON Parameters: - **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"]}` ### Inspect a volume @@ -2816,9 +2826,13 @@ Return low-level information on the volume `name` Content-Type: application/json { - "Name": "tardis", - "Driver": "local", - "Mountpoint": "/var/lib/docker/volumes/tardis" + "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: @@ -2989,6 +3003,10 @@ Content-Type: application/json "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", "com.docker.network.bridge.name": "docker0", "com.docker.network.driver.mtu": "1500" + }, + "Labels": { + "com.example.some-label": "some-value", + "com.example.some-other-label": "some-other-value" } } ``` @@ -3012,6 +3030,7 @@ Content-Type: application/json { "Name":"isolated_nw", + "CheckDuplicate":false, "Driver":"bridge", "EnableIPv6": true, "IPAM":{ @@ -3030,7 +3049,19 @@ Content-Type: application/json "foo": "bar" } }, - "Internal":true + "Internal":true, + "Options": { + "com.docker.network.bridge.default_bridge": "true", + "com.docker.network.bridge.enable_icc": "true", + "com.docker.network.bridge.enable_ip_masquerade": "true", + "com.docker.network.bridge.host_binding_ipv4": "0.0.0.0", + "com.docker.network.bridge.name": "docker0", + "com.docker.network.driver.mtu": "1500" + }, + "Labels": { + "com.example.some-label": "some-value", + "com.example.some-other-label": "some-other-value" + } } ``` @@ -3055,12 +3086,13 @@ Status Codes: JSON Parameters: - **Name** - The new network's name. this is a mandatory field +- **CheckDuplicate** - Requests daemon to check for networks with same name - **Driver** - Name of the network driver plugin to use. Defaults to `bridge` driver - **Internal** - Restrict external access to the network - **IPAM** - Optional custom IP scheme for the network - **EnableIPv6** - Enable IPv6 on the network - **Options** - Network specific options to be used by the drivers -- **CheckDuplicate** - Requests daemon to check for networks with same name +- **Labels** - Labels to set on the network, specified as a map: `{"key":"value" [,"key2":"value2"]}` ### Connect a container to a network From cde2df6db9b255533b2bb011c399910cdddb7ac7 Mon Sep 17 00:00:00 2001 From: Thomas Grainger Date: Fri, 15 Apr 2016 11:27:09 +0100 Subject: [PATCH 05/25] Fix security documentation, XSS -> CSRF Signed-off-by: Thomas Grainger (cherry picked from commit ea8f9c972393e0929e643190573412410bf39c6a) Signed-off-by: Sebastiaan van Stijn --- docs/security/security.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/security/security.md b/docs/security/security.md index b9738a3ce8..88b5b3f09a 100644 --- a/docs/security/security.md +++ b/docs/security/security.md @@ -106,7 +106,7 @@ arbitrary containers. For this reason, the REST API endpoint (used by the Docker CLI to communicate with the Docker daemon) changed in Docker 0.5.2, and now uses a UNIX socket instead of a TCP socket bound on 127.0.0.1 (the -latter being prone to cross-site-scripting attacks if you happen to run +latter being prone to cross-site request forgery attacks if you happen to run Docker directly on your local machine, outside of a VM). You can then use traditional UNIX permission checks to limit access to the control socket. From 6bbe5722aa5af242052c15b422d6969472e59219 Mon Sep 17 00:00:00 2001 From: Yong Tang Date: Fri, 15 Apr 2016 11:08:15 -0700 Subject: [PATCH 06/25] Fix incorrect docs in remote API for the option of `SecurityOpt` This fix tries to fix the issue in remote API docs for v1.15 (Docker 1.3.x) and v1.16 (Docker 1.4.x) where `SecurityOpts` was used but the actual field should be `SecurityOpt`. This `SecurityOpt` field is verified through the source code in v1.3.0 and v1.4.0: https://github.com/docker/docker/blob/v1.3.0/runconfig/config.go#L35 https://github.com/docker/docker/blob/v1.4.0/runconfig/hostconfig.go#L98 Signed-off-by: Yong Tang (cherry picked from commit f3f981624bc9329740e9a1c52e71471ca38d8171) Signed-off-by: Sebastiaan van Stijn --- docs/reference/api/docker_remote_api_v1.15.md | 4 ++-- docs/reference/api/docker_remote_api_v1.16.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference/api/docker_remote_api_v1.15.md b/docs/reference/api/docker_remote_api_v1.15.md index f6a860a4f9..5625eee56e 100644 --- a/docs/reference/api/docker_remote_api_v1.15.md +++ b/docs/reference/api/docker_remote_api_v1.15.md @@ -151,7 +151,7 @@ Create a container "ExposedPorts": { "22/tcp": {} }, - "SecurityOpts": [], + "SecurityOpt": [], "HostConfig": { "Binds": ["/tmp:/tmp"], "Links": ["redis3:redis"], @@ -212,7 +212,7 @@ Json Parameters: container - **ExposedPorts** - An object mapping ports to an empty object in the form of: `"ExposedPorts": { "/: {}" }` -- **SecurityOpts**: A list of string values to customize labels for MLS +- **SecurityOpt**: A list of string values to customize labels for MLS systems, such as SELinux. - **HostConfig** - **Binds** – A list of volume bindings for this container. Each volume diff --git a/docs/reference/api/docker_remote_api_v1.16.md b/docs/reference/api/docker_remote_api_v1.16.md index 630da70144..ef9bca0e83 100644 --- a/docs/reference/api/docker_remote_api_v1.16.md +++ b/docs/reference/api/docker_remote_api_v1.16.md @@ -151,7 +151,7 @@ Create a container "ExposedPorts": { "22/tcp": {} }, - "SecurityOpts": [], + "SecurityOpt": [], "HostConfig": { "Binds": ["/tmp:/tmp"], "Links": ["redis3:redis"], @@ -212,7 +212,7 @@ Json Parameters: container - **ExposedPorts** - An object mapping ports to an empty object in the form of: `"ExposedPorts": { "/: {}" }` -- **SecurityOpts**: A list of string values to customize labels for MLS +- **SecurityOpt**: A list of string values to customize labels for MLS systems, such as SELinux. - **HostConfig** - **Binds** – A list of volume bindings for this container. Each volume From ce9bc253f69517bbbffc1f8795306d6192037d1b Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Sat, 16 Apr 2016 02:09:58 +0200 Subject: [PATCH 07/25] docs: remove unused "registry" parameter The "registry" query-param was in added 10c0e990371e065d4fc1c9b680f03a46e5bacc5e, and removed in docker 0.5.0 via 66a9d06d9fa7a382c6852cf047e1448e0d3e1782. Aparently, it was never removed from the documentation, and included in all versions of the API docs. This removes it from the documentation. Signed-off-by: Sebastiaan van Stijn (cherry picked from commit e035a86c1d981d5e2ade303a9152ee36125a4cb9) Signed-off-by: Sebastiaan van Stijn --- docs/reference/api/docker_remote_api_v1.14.md | 1 - docs/reference/api/docker_remote_api_v1.15.md | 1 - docs/reference/api/docker_remote_api_v1.16.md | 1 - docs/reference/api/docker_remote_api_v1.17.md | 1 - docs/reference/api/docker_remote_api_v1.18.md | 1 - docs/reference/api/docker_remote_api_v1.19.md | 1 - docs/reference/api/docker_remote_api_v1.20.md | 1 - 7 files changed, 7 deletions(-) diff --git a/docs/reference/api/docker_remote_api_v1.14.md b/docs/reference/api/docker_remote_api_v1.14.md index e7c8fde635..673ed84437 100644 --- a/docs/reference/api/docker_remote_api_v1.14.md +++ b/docs/reference/api/docker_remote_api_v1.14.md @@ -844,7 +844,6 @@ Query Parameters: - **fromSrc** – source to import, - means stdin - **repo** – repository - **tag** – tag -- **registry** – the registry to pull from Request Headers: diff --git a/docs/reference/api/docker_remote_api_v1.15.md b/docs/reference/api/docker_remote_api_v1.15.md index 5625eee56e..e5f3ca6348 100644 --- a/docs/reference/api/docker_remote_api_v1.15.md +++ b/docs/reference/api/docker_remote_api_v1.15.md @@ -994,7 +994,6 @@ Query Parameters: can be retrieved or `-` to read the image from the request body. - **repo** – repository - **tag** – tag -- **registry** – the registry to pull from Request Headers: diff --git a/docs/reference/api/docker_remote_api_v1.16.md b/docs/reference/api/docker_remote_api_v1.16.md index ef9bca0e83..f6e768ce0c 100644 --- a/docs/reference/api/docker_remote_api_v1.16.md +++ b/docs/reference/api/docker_remote_api_v1.16.md @@ -942,7 +942,6 @@ Query Parameters: can be retrieved or `-` to read the image from the request body. - **repo** – repository - **tag** – tag -- **registry** – the registry to pull from Request Headers: diff --git a/docs/reference/api/docker_remote_api_v1.17.md b/docs/reference/api/docker_remote_api_v1.17.md index 9baa758cc5..147b05f89f 100644 --- a/docs/reference/api/docker_remote_api_v1.17.md +++ b/docs/reference/api/docker_remote_api_v1.17.md @@ -1155,7 +1155,6 @@ Query Parameters: can be retrieved or `-` to read the image from the request body. - **repo** – repository - **tag** – tag -- **registry** – the registry to pull from Request Headers: diff --git a/docs/reference/api/docker_remote_api_v1.18.md b/docs/reference/api/docker_remote_api_v1.18.md index 9de2cc6cf1..dc122aabf0 100644 --- a/docs/reference/api/docker_remote_api_v1.18.md +++ b/docs/reference/api/docker_remote_api_v1.18.md @@ -1252,7 +1252,6 @@ Query Parameters: can be retrieved or `-` to read the image from the request body. - **repo** – repository - **tag** – tag -- **registry** – the registry to pull from Request Headers: diff --git a/docs/reference/api/docker_remote_api_v1.19.md b/docs/reference/api/docker_remote_api_v1.19.md index e049dbe7c4..16995d93e5 100644 --- a/docs/reference/api/docker_remote_api_v1.19.md +++ b/docs/reference/api/docker_remote_api_v1.19.md @@ -1301,7 +1301,6 @@ Query Parameters: can be retrieved or `-` to read the image from the request body. - **repo** – Repository name. - **tag** – Tag. -- **registry** – The registry to pull from. Request Headers: diff --git a/docs/reference/api/docker_remote_api_v1.20.md b/docs/reference/api/docker_remote_api_v1.20.md index dd47ff7f1f..fbc56988ca 100644 --- a/docs/reference/api/docker_remote_api_v1.20.md +++ b/docs/reference/api/docker_remote_api_v1.20.md @@ -1443,7 +1443,6 @@ Query Parameters: can be retrieved or `-` to read the image from the request body. - **repo** – Repository name. - **tag** – Tag. -- **registry** – The registry to pull from. Request Headers: From b9f11557afa20e1acc584949bf2ea74b2ab49033 Mon Sep 17 00:00:00 2001 From: Alessandro Boch Date: Fri, 15 Apr 2016 17:15:18 -0700 Subject: [PATCH 08/25] Clarify container external connectivity in multi-network scenario Signed-off-by: Alessandro Boch (cherry picked from commit c2e088e13488904a6747809a689eac5d72a4618e) Signed-off-by: Sebastiaan van Stijn --- docs/userguide/networking/dockernetworks.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/userguide/networking/dockernetworks.md b/docs/userguide/networking/dockernetworks.md index 1848e7a7a9..5adb1b3c05 100644 --- a/docs/userguide/networking/dockernetworks.md +++ b/docs/userguide/networking/dockernetworks.md @@ -293,7 +293,9 @@ specifications. You can create multiple networks. You can add containers to more than one network. Containers can only communicate within networks but not across networks. A container attached to two networks can communicate with member -containers in either network. +containers in either network. When a container is connected to multiple +networks, its external connectivity is provided via the first non-internal +network, in lexical order. The next few sections describe each of Docker's built-in network drivers in greater detail. From 3eaabe025763466ee2221be7aef19d3ca4247e58 Mon Sep 17 00:00:00 2001 From: yorkie Date: Mon, 18 Apr 2016 23:38:41 +0800 Subject: [PATCH 09/25] doc: fix typo Signed-off-by: yorkie (cherry picked from commit d2c5bf23f16a98ca6f603f7fe2b5a31c70d4c8db) Signed-off-by: Sebastiaan van Stijn --- docs/userguide/networking/dockernetworks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/userguide/networking/dockernetworks.md b/docs/userguide/networking/dockernetworks.md index 5adb1b3c05..dd84872693 100644 --- a/docs/userguide/networking/dockernetworks.md +++ b/docs/userguide/networking/dockernetworks.md @@ -18,7 +18,7 @@ applications run on. Docker container networks give you that control. This section provides an overview of the default networking behavior that Docker Engine delivers natively. It describes the type of networks created by default -and how to create your own, user--defined networks. It also describes the +and how to create your own, user-defined networks. It also describes the resources required to create networks on a single host or across a cluster of hosts. From 2d532738b523e94a8781a2598d8e9d980652f55d Mon Sep 17 00:00:00 2001 From: Florian Date: Mon, 18 Apr 2016 23:33:40 +0200 Subject: [PATCH 10/25] Remove outdated Node.js example - include a link to the new guide later! As recommended by @moxiegirl and squashed. Signed-off-by: FWirtz (cherry picked from commit d9c0d67b51fc135b2dbf54a152105d124100eb5e) Signed-off-by: Sebastiaan van Stijn --- docs/examples/index.md | 1 - docs/examples/nodejs_web_app.md | 199 -------------------------------- 2 files changed, 200 deletions(-) delete mode 100644 docs/examples/nodejs_web_app.md diff --git a/docs/examples/index.md b/docs/examples/index.md index 87dd2b3fd9..c3c67f7330 100644 --- a/docs/examples/index.md +++ b/docs/examples/index.md @@ -17,7 +17,6 @@ This section contains the following: * [Dockerizing MongoDB](mongodb.md) * [Dockerizing PostgreSQL](postgresql_service.md) * [Dockerizing a CouchDB service](couchdb_data_volumes.md) -* [Dockerizing a Node.js web app](nodejs_web_app.md) * [Dockerizing a Redis service](running_redis_service.md) * [Dockerizing an apt-cacher-ng service](apt-cacher-ng.md) * [Dockerizing applications: A 'Hello world'](../userguide/containers/dockerizing.md) diff --git a/docs/examples/nodejs_web_app.md b/docs/examples/nodejs_web_app.md deleted file mode 100644 index 149f5b47e4..0000000000 --- a/docs/examples/nodejs_web_app.md +++ /dev/null @@ -1,199 +0,0 @@ - - -# Dockerizing a Node.js web app - -> **Note**: -> - **If you don't like sudo** then see [*Giving non-root -> access*](../installation/binaries.md#giving-non-root-access) - -The goal of this example is to show you how you can build your own -Docker images from a parent image using a `Dockerfile` -. We will do that by making a simple Node.js hello world web -application running on CentOS. You can get the full source code at[https://github.com/enokd/docker-node-hello/](https://github.com/enokd/docker-node-hello/). - -## Create Node.js app - -First, create a directory `src` where all the files -would live. Then create a `package.json` file that -describes your app and its dependencies: - - { - "name": "docker-centos-hello", - "private": true, - "version": "0.0.1", - "description": "Node.js Hello world app on CentOS using docker", - "author": "Daniel Gasienica ", - "dependencies": { - "express": "3.2.4" - } - } - -Then, create an `index.js` file that defines a web -app using the [Express.js](http://expressjs.com/) framework: - - var express = require('express'); - - // Constants - var PORT = 8080; - - // App - var app = express(); - app.get('/', function (req, res) { - res.send('Hello world\n'); - }); - - app.listen(PORT); - console.log('Running on http://localhost:' + PORT); - -In the next steps, we'll look at how you can run this app inside a -CentOS container using Docker. First, you'll need to build a Docker -image of your app. - -## Creating a Dockerfile - -Create an empty file called `Dockerfile`: - - touch Dockerfile - -Open the `Dockerfile` in your favorite text editor - -Define the parent image you want to use to build your own image on -top of. Here, we'll use -[CentOS](https://hub.docker.com/_/centos/) (tag: `centos6`) -available on the [Docker Hub](https://hub.docker.com/): - - FROM centos:centos6 - -Since we're building a Node.js app, you'll have to install Node.js as -well as npm on your CentOS image. Node.js is required to run your app -and npm is required to install your app's dependencies defined in -`package.json`. To install the right package for -CentOS, we'll use the instructions from the [Node.js wiki]( -https://github.com/joyent/node/wiki/Installing-Node.js- -via-package-manager#rhelcentosscientific-linux-6): - - # Enable Extra Packages for Enterprise Linux (EPEL) for CentOS - RUN yum install -y epel-release - # Install Node.js and npm - RUN yum install -y nodejs npm - -Install your app dependencies using the `npm` binary: - - # Install app dependencies - COPY package.json /src/package.json - RUN cd /src; npm install --production - -To bundle your app's source code inside the Docker image, use the `COPY` -instruction: - - # Bundle app source - COPY . /src - -Your app binds to port `8080` so you'll use the `EXPOSE` instruction to have -it mapped by the `docker` daemon: - - EXPOSE 8080 - -Last but not least, define the command to run your app using `CMD` which -defines your runtime, i.e. `node`, and the path to our app, i.e. `src/index.js` -(see the step where we added the source to the container): - - CMD ["node", "/src/index.js"] - -Your `Dockerfile` should now look like this: - - FROM centos:centos6 - - # Enable Extra Packages for Enterprise Linux (EPEL) for CentOS - RUN yum install -y epel-release - # Install Node.js and npm - RUN yum install -y nodejs npm - - # Install app dependencies - COPY package.json /src/package.json - RUN cd /src; npm install --production - - # Bundle app source - COPY . /src - - EXPOSE 8080 - CMD ["node", "/src/index.js"] - -## Building your image - -Go to the directory that has your `Dockerfile` and run the following command -to build a Docker image. The `-t` flag lets you tag your image so it's easier -to find later using the `docker images` command: - - $ docker build -t /centos-node-hello . - -Your image will now be listed by Docker: - - $ docker images - - # Example - REPOSITORY TAG ID CREATED - centos centos6 539c0211cd76 8 weeks ago - /centos-node-hello latest d64d3505b0d2 2 hours ago - -## Run the image - -Running your image with `-d` runs the container in detached mode, leaving the -container running in the background. The `-p` flag redirects a public port to -a private port in the container. Run the image you previously built: - - $ docker run -p 49160:8080 -d /centos-node-hello - -Print the output of your app: - - # Get container ID - $ docker ps - - # Print app output - $ docker logs - - # Example - Running on http://localhost:8080 - -## Test - -To test your app, get the port of your app that Docker mapped: - - $ docker ps - - # Example - ID IMAGE COMMAND ... PORTS - ecce33b30ebf /centos-node-hello:latest node /src/index.js 49160->8080 - -In the example above, Docker mapped the `8080` port of the container to `49160`. - -Now you can call your app using `curl` (install if needed via: -`sudo apt-get install curl`): - - $ curl -i localhost:49160 - - HTTP/1.1 200 OK - X-Powered-By: Express - Content-Type: text/html; charset=utf-8 - Content-Length: 12 - Date: Sun, 02 Jun 2013 03:53:22 GMT - Connection: keep-alive - - Hello world - -If you use Docker Machine on OS X, the port is actually mapped to the Docker -host VM, and you should use the following command: - - $ curl $(docker-machine ip VM_NAME):49160 - -We hope this tutorial helped you get up and running with Node.js and -CentOS on Docker. You can get the full source code at -[https://github.com/enokd/docker-node-hello/](https://github.com/enokd/docker-node-hello/). From 97a505519860bc3bcb6263423f0d92be7891e84a Mon Sep 17 00:00:00 2001 From: Yong Tang Date: Mon, 18 Apr 2016 21:15:33 -0700 Subject: [PATCH 11/25] Docs: Container creation param descriptions not under HostConfig This fix tries to fix issues mentioned in #22100 for incorrect description of remote API's container creation params. Several issues have been fixed: 1. CPU and memory related params (e.g., `MemorySwap`, `CpuShares`, etc.) were incorrectly placed under the top level instead of under the HostConfig. (v1.18-v1.24) 2. The param `Cpuset` has been deprecated but was never removed. (v1.18-v1.24) 3. The param `PidsLimit` was not added even though the description has been added. (v1.23-v1.24) This fix fixes #22100 Signed-off-by: Yong Tang (cherry picked from commit 332e3b545b0c0e825364c0f09315f82546c791f0) Signed-off-by: Sebastiaan van Stijn --- docs/reference/api/docker_remote_api_v1.18.md | 13 +++-- docs/reference/api/docker_remote_api_v1.19.md | 23 ++++---- docs/reference/api/docker_remote_api_v1.20.md | 25 +++++---- docs/reference/api/docker_remote_api_v1.21.md | 29 +++++------ docs/reference/api/docker_remote_api_v1.22.md | 49 +++++++++-------- docs/reference/api/docker_remote_api_v1.23.md | 52 +++++++++---------- 6 files changed, 93 insertions(+), 98 deletions(-) diff --git a/docs/reference/api/docker_remote_api_v1.18.md b/docs/reference/api/docker_remote_api_v1.18.md index dc122aabf0..b4b8970c59 100644 --- a/docs/reference/api/docker_remote_api_v1.18.md +++ b/docs/reference/api/docker_remote_api_v1.18.md @@ -206,13 +206,6 @@ Json Parameters: - **Domainname** - A string value containing the desired domain name to use for the container. - **User** - A string value containing the user to use inside the container. -- **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 - (ie. the relative weight vs other containers). -- **Cpuset** - The same as CpusetCpus, but deprecated, please don't use. -- **CpusetCpus** - String value containing the cgroups CpusetCpus to use. - **AttachStdin** - Boolean value, attaches to stdin. - **AttachStdout** - Boolean value, attaches to stdout. - **AttachStderr** - Boolean value, attaches to stderr. @@ -243,6 +236,12 @@ Json Parameters: in the form of `container_name:alias`. - **LxcConf** - LXC specific configurations. These configurations will 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 + (ie. the relative weight vs other containers). + - **CpusetCpus** - String value containing the cgroups CpusetCpus to use. - **PortBindings** - A map of exposed container ports and the host port they should map to. It should be specified in the form `{ /: [{ "HostPort": "" }] }` diff --git a/docs/reference/api/docker_remote_api_v1.19.md b/docs/reference/api/docker_remote_api_v1.19.md index 16995d93e5..3d44813a31 100644 --- a/docs/reference/api/docker_remote_api_v1.19.md +++ b/docs/reference/api/docker_remote_api_v1.19.md @@ -213,18 +213,6 @@ Json Parameters: - **Domainname** - A string value containing the domain name to use for the container. - **User** - A string value specifying the user inside the container. -- **Memory** - Memory limit in bytes. -- **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap. - You must use this with `memory` and make the swap value larger than `memory`. -- **CpuShares** - An integer value containing the container's CPU Shares - (ie. the relative weight vs other containers). -- **CpuPeriod** - The length of a CPU period in microseconds. -- **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period. -- **Cpuset** - Deprecated please don't use. Use `CpusetCpus` instead. -- **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use. -- **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. -- **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000. -- **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. - **AttachStdin** - Boolean value, attaches to `stdin`. - **AttachStdout** - Boolean value, attaches to `stdout`. - **AttachStderr** - Boolean value, attaches to `stderr`. @@ -254,6 +242,17 @@ Json Parameters: in the form of `container_name:alias`. - **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 container's CPU Shares + (ie. the relative weight vs other containers). + - **CpuPeriod** - The length of a CPU period in microseconds. + - **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period. + - **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use. + - **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. + - **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000. + - **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. - **PortBindings** - A map of exposed container ports and the host port they should map to. A JSON object in the form `{ /: [{ "HostPort": "" }] }` diff --git a/docs/reference/api/docker_remote_api_v1.20.md b/docs/reference/api/docker_remote_api_v1.20.md index fbc56988ca..cb15ad51cf 100644 --- a/docs/reference/api/docker_remote_api_v1.20.md +++ b/docs/reference/api/docker_remote_api_v1.20.md @@ -215,19 +215,6 @@ Json Parameters: - **Domainname** - A string value containing the domain name to use for the container. - **User** - A string value specifying the user inside the container. -- **Memory** - Memory limit in bytes. -- **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap. - You must use this with `memory` and make the swap value larger than `memory`. -- **CpuShares** - An integer value containing the container's CPU Shares - (ie. the relative weight vs other containers). -- **CpuPeriod** - The length of a CPU period in microseconds. -- **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period. -- **Cpuset** - Deprecated please don't use. Use `CpusetCpus` instead. -- **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use. -- **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. -- **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000. -- **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. -- **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. - **AttachStdin** - Boolean value, attaches to `stdin`. - **AttachStdout** - Boolean value, attaches to `stdout`. - **AttachStderr** - Boolean value, attaches to `stderr`. @@ -257,6 +244,18 @@ Json Parameters: in the form of `container_name:alias`. - **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 container's CPU Shares + (ie. the relative weight vs other containers). + - **CpuPeriod** - The length of a CPU period in microseconds. + - **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period. + - **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use. + - **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. + - **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000. + - **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. + - **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. - **PortBindings** - A map of exposed container ports and the host port they should map to. A JSON object in the form `{ /: [{ "HostPort": "" }] }` diff --git a/docs/reference/api/docker_remote_api_v1.21.md b/docs/reference/api/docker_remote_api_v1.21.md index 7cdfd0f3f3..2279d2fc0b 100644 --- a/docs/reference/api/docker_remote_api_v1.21.md +++ b/docs/reference/api/docker_remote_api_v1.21.md @@ -224,21 +224,6 @@ Json Parameters: - **Domainname** - A string value containing the domain name to use for the container. - **User** - A string value specifying the user inside the container. -- **Memory** - Memory limit in bytes. -- **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap. - You must use this with `memory` and make the swap value larger than `memory`. -- **MemoryReservation** - Memory soft limit in bytes. -- **KernelMemory** - Kernel memory limit in bytes. -- **CpuShares** - An integer value containing the container's CPU Shares - (ie. the relative weight vs other containers). -- **CpuPeriod** - The length of a CPU period in microseconds. -- **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period. -- **Cpuset** - Deprecated please don't use. Use `CpusetCpus` instead. -- **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use. -- **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. -- **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000. -- **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. -- **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. - **AttachStdin** - Boolean value, attaches to `stdin`. - **AttachStdout** - Boolean value, attaches to `stdout`. - **AttachStderr** - Boolean value, attaches to `stderr`. @@ -271,6 +256,20 @@ Json Parameters: in the form of `container_name:alias`. - **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`. + - **MemoryReservation** - Memory soft limit in bytes. + - **KernelMemory** - Kernel memory limit in bytes. + - **CpuShares** - An integer value containing the container's CPU Shares + (ie. the relative weight vs other containers). + - **CpuPeriod** - The length of a CPU period in microseconds. + - **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period. + - **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use. + - **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. + - **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000. + - **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. + - **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. - **PortBindings** - A map of exposed container ports and the host port they should map to. A JSON object in the form `{ /: [{ "HostPort": "" }] }` diff --git a/docs/reference/api/docker_remote_api_v1.22.md b/docs/reference/api/docker_remote_api_v1.22.md index 5d3e1166bc..c0f7f21335 100644 --- a/docs/reference/api/docker_remote_api_v1.22.md +++ b/docs/reference/api/docker_remote_api_v1.22.md @@ -329,31 +329,6 @@ Json Parameters: - **Domainname** - A string value containing the domain name to use for the container. - **User** - A string value specifying the user inside the container. -- **Memory** - Memory limit in bytes. -- **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap. - You must use this with `memory` and make the swap value larger than `memory`. -- **MemoryReservation** - Memory soft limit in bytes. -- **KernelMemory** - Kernel memory limit in bytes. -- **CpuShares** - An integer value containing the container's CPU Shares - (ie. the relative weight vs other containers). -- **CpuPeriod** - The length of a CPU period in microseconds. -- **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period. -- **Cpuset** - Deprecated please don't use. Use `CpusetCpus` instead. -- **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use. -- **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. -- **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000. -- **BlkioWeightDevice** - Block IO weight (relative device weight) in the form of: `"BlkioWeightDevice": [{"Path": "device_path", "Weight": weight}]` -- **BlkioDeviceReadBps** - Limit read rate (bytes per second) from a device in the form of: `"BlkioDeviceReadBps": [{"Path": "device_path", "Rate": rate}]`, for example: - `"BlkioDeviceReadBps": [{"Path": "/dev/sda", "Rate": "1024"}]"` -- **BlkioDeviceWriteBps** - Limit write rate (bytes per second) to a device in the form of: `"BlkioDeviceWriteBps": [{"Path": "device_path", "Rate": rate}]`, for example: - `"BlkioDeviceWriteBps": [{"Path": "/dev/sda", "Rate": "1024"}]"` -- **BlkioDeviceReadIOps** - Limit read rate (IO per second) from a device in the form of: `"BlkioDeviceReadIOps": [{"Path": "device_path", "Rate": rate}]`, for example: - `"BlkioDeviceReadIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` -- **BlkioDeviceWiiteIOps** - Limit write rate (IO per second) to a device in the form of: `"BlkioDeviceWriteIOps": [{"Path": "device_path", "Rate": rate}]`, for example: - `"BlkioDeviceWriteIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` -- **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. -- **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. -- **OomScoreAdj** - An integer value containing the score given to the container in order to tune OOM killer preferences. - **AttachStdin** - Boolean value, attaches to `stdin`. - **AttachStdout** - Boolean value, attaches to `stdout`. - **AttachStderr** - Boolean value, attaches to `stderr`. @@ -383,6 +358,30 @@ Json Parameters: + `volume_name: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`. + - **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`. + - **MemoryReservation** - Memory soft limit in bytes. + - **KernelMemory** - Kernel memory limit in bytes. + - **CpuShares** - An integer value containing the container's CPU Shares + (ie. the relative weight vs other containers). + - **CpuPeriod** - The length of a CPU period in microseconds. + - **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period. + - **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use. + - **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. + - **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000. + - **BlkioWeightDevice** - Block IO weight (relative device weight) in the form of: `"BlkioWeightDevice": [{"Path": "device_path", "Weight": weight}]` + - **BlkioDeviceReadBps** - Limit read rate (bytes per second) from a device in the form of: `"BlkioDeviceReadBps": [{"Path": "device_path", "Rate": rate}]`, for example: + `"BlkioDeviceReadBps": [{"Path": "/dev/sda", "Rate": "1024"}]"` + - **BlkioDeviceWriteBps** - Limit write rate (bytes per second) to a device in the form of: `"BlkioDeviceWriteBps": [{"Path": "device_path", "Rate": rate}]`, for example: + `"BlkioDeviceWriteBps": [{"Path": "/dev/sda", "Rate": "1024"}]"` + - **BlkioDeviceReadIOps** - Limit read rate (IO per second) from a device in the form of: `"BlkioDeviceReadIOps": [{"Path": "device_path", "Rate": rate}]`, for example: + `"BlkioDeviceReadIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` + - **BlkioDeviceWiiteIOps** - Limit write rate (IO per second) to a device in the form of: `"BlkioDeviceWriteIOps": [{"Path": "device_path", "Rate": rate}]`, for example: + `"BlkioDeviceWriteIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` + - **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. + - **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. + - **OomScoreAdj** - An integer value containing the score given to the container in order to tune OOM killer preferences. - **PortBindings** - A map of exposed container ports and the host port they should map to. A JSON object in the form `{ /: [{ "HostPort": "" }] }` diff --git a/docs/reference/api/docker_remote_api_v1.23.md b/docs/reference/api/docker_remote_api_v1.23.md index 30f556255c..dfeaa927f2 100644 --- a/docs/reference/api/docker_remote_api_v1.23.md +++ b/docs/reference/api/docker_remote_api_v1.23.md @@ -296,6 +296,7 @@ Create a container "MemorySwappiness": 60, "OomKillDisable": false, "OomScoreAdj": 500, + "PidsLimit": -1, "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] }, "PublishAllPorts": false, "Privileged": false, @@ -348,32 +349,6 @@ Json Parameters: - **Domainname** - A string value containing the domain name to use for the container. - **User** - A string value specifying the user inside the container. -- **Memory** - Memory limit in bytes. -- **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap. - You must use this with `memory` and make the swap value larger than `memory`. -- **MemoryReservation** - Memory soft limit in bytes. -- **KernelMemory** - Kernel memory limit in bytes. -- **CpuShares** - An integer value containing the container's CPU Shares - (ie. the relative weight vs other containers). -- **CpuPeriod** - The length of a CPU period in microseconds. -- **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period. -- **Cpuset** - Deprecated please don't use. Use `CpusetCpus` instead. -- **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use. -- **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. -- **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000. -- **BlkioWeightDevice** - Block IO weight (relative device weight) in the form of: `"BlkioWeightDevice": [{"Path": "device_path", "Weight": weight}]` -- **BlkioDeviceReadBps** - Limit read rate (bytes per second) from a device in the form of: `"BlkioDeviceReadBps": [{"Path": "device_path", "Rate": rate}]`, for example: - `"BlkioDeviceReadBps": [{"Path": "/dev/sda", "Rate": "1024"}]"` -- **BlkioDeviceWriteBps** - Limit write rate (bytes per second) to a device in the form of: `"BlkioDeviceWriteBps": [{"Path": "device_path", "Rate": rate}]`, for example: - `"BlkioDeviceWriteBps": [{"Path": "/dev/sda", "Rate": "1024"}]"` -- **BlkioDeviceReadIOps** - Limit read rate (IO per second) from a device in the form of: `"BlkioDeviceReadIOps": [{"Path": "device_path", "Rate": rate}]`, for example: - `"BlkioDeviceReadIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` -- **BlkioDeviceWiiteIOps** - Limit write rate (IO per second) to a device in the form of: `"BlkioDeviceWriteIOps": [{"Path": "device_path", "Rate": rate}]`, for example: - `"BlkioDeviceWriteIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` -- **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. -- **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. -- **OomScoreAdj** - An integer value containing the score given to the container in order to tune OOM killer preferences. -- **PidsLimit** - Tune a container's pids limit. Set -1 for unlimited. - **AttachStdin** - Boolean value, attaches to `stdin`. - **AttachStdout** - Boolean value, attaches to `stdout`. - **AttachStderr** - Boolean value, attaches to `stderr`. @@ -403,6 +378,31 @@ Json Parameters: + `volume_name: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`. + - **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`. + - **MemoryReservation** - Memory soft limit in bytes. + - **KernelMemory** - Kernel memory limit in bytes. + - **CpuShares** - An integer value containing the container's CPU Shares + (ie. the relative weight vs other containers). + - **CpuPeriod** - The length of a CPU period in microseconds. + - **CpuQuota** - Microseconds of CPU time that the container can get in a CPU period. + - **CpusetCpus** - String value containing the `cgroups CpusetCpus` to use. + - **CpusetMems** - Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. + - **BlkioWeight** - Block IO weight (relative weight) accepts a weight value between 10 and 1000. + - **BlkioWeightDevice** - Block IO weight (relative device weight) in the form of: `"BlkioWeightDevice": [{"Path": "device_path", "Weight": weight}]` + - **BlkioDeviceReadBps** - Limit read rate (bytes per second) from a device in the form of: `"BlkioDeviceReadBps": [{"Path": "device_path", "Rate": rate}]`, for example: + `"BlkioDeviceReadBps": [{"Path": "/dev/sda", "Rate": "1024"}]"` + - **BlkioDeviceWriteBps** - Limit write rate (bytes per second) to a device in the form of: `"BlkioDeviceWriteBps": [{"Path": "device_path", "Rate": rate}]`, for example: + `"BlkioDeviceWriteBps": [{"Path": "/dev/sda", "Rate": "1024"}]"` + - **BlkioDeviceReadIOps** - Limit read rate (IO per second) from a device in the form of: `"BlkioDeviceReadIOps": [{"Path": "device_path", "Rate": rate}]`, for example: + `"BlkioDeviceReadIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` + - **BlkioDeviceWiiteIOps** - Limit write rate (IO per second) to a device in the form of: `"BlkioDeviceWriteIOps": [{"Path": "device_path", "Rate": rate}]`, for example: + `"BlkioDeviceWriteIOps": [{"Path": "/dev/sda", "Rate": "1000"}]` + - **MemorySwappiness** - Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. + - **OomKillDisable** - Boolean value, whether to disable OOM Killer for the container or not. + - **OomScoreAdj** - An integer value containing the score given to the container in order to tune OOM killer preferences. + - **PidsLimit** - Tune a container's pids limit. Set -1 for unlimited. - **PortBindings** - A map of exposed container ports and the host port they should map to. A JSON object in the form `{ /: [{ "HostPort": "" }] }` From 71c0acf1ca672bf1791a32f31ff70ab4ca11822e Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Tue, 19 Apr 2016 14:39:14 +0200 Subject: [PATCH 12/25] Remove API versions 1.17 and older from documentation Docker 1.5 and older is no longer supported by Docker Hub, so there's not much need to document the API for those versions. Documentation is still available on GitHub, and through the older versions of the documentation for those that really need it. Signed-off-by: Sebastiaan van Stijn (cherry picked from commit 68f9a45440c1d87316ec5106f942a8cae9113ca0) Signed-off-by: Sebastiaan van Stijn --- docs/reference/api/docker_remote_api.md | 58 +- docs/reference/api/docker_remote_api_v1.14.md | 1469 ------------ docs/reference/api/docker_remote_api_v1.15.md | 1763 --------------- docs/reference/api/docker_remote_api_v1.16.md | 1833 --------------- docs/reference/api/docker_remote_api_v1.17.md | 2007 ----------------- 5 files changed, 2 insertions(+), 7128 deletions(-) delete mode 100644 docs/reference/api/docker_remote_api_v1.14.md delete mode 100644 docs/reference/api/docker_remote_api_v1.15.md delete mode 100644 docs/reference/api/docker_remote_api_v1.16.md delete mode 100644 docs/reference/api/docker_remote_api_v1.17.md diff --git a/docs/reference/api/docker_remote_api.md b/docs/reference/api/docker_remote_api.md index 34914c4ebd..97e9def599 100644 --- a/docs/reference/api/docker_remote_api.md +++ b/docs/reference/api/docker_remote_api.md @@ -49,10 +49,6 @@ Docker version | API version | Changes 1.8.x | [1.20](docker_remote_api_v1.20.md) | [API changes](docker_remote_api.md#v1-20-api-changes) 1.7.x | [1.19](docker_remote_api_v1.19.md) | [API changes](docker_remote_api.md#v1-19-api-changes) 1.6.x | [1.18](docker_remote_api_v1.18.md) | [API changes](docker_remote_api.md#v1-18-api-changes) -1.5.x | [1.17](docker_remote_api_v1.17.md) | [API changes](docker_remote_api.md#v1-17-api-changes) -1.4.x | [1.16](docker_remote_api_v1.16.md) | [API changes](docker_remote_api.md#v1-16-api-changes) -1.3.x | [1.15](docker_remote_api_v1.15.md) | [API changes](docker_remote_api.md#v1-15-api-changes) -1.2.x | [1.14](docker_remote_api_v1.14.md) | [API changes](docker_remote_api.md#v1-14-api-changes) Refer to the [GitHub repository]( https://github.com/docker/docker/tree/master/docs/reference/api) for @@ -60,12 +56,12 @@ older releases. ## Authentication -Since API version 1.2, the auth configuration is now handled client side, so the +Authentication configuration is handled client side, so the client has to send the `authConfig` as a `POST` in `/images/(name)/push`. The `authConfig`, set as the `X-Registry-Auth` header, is currently a Base64 encoded (JSON) string with the following structure: -``` +```JSON {"username": "string", "password": "string", "email": "string", "serveraddress" : "string", "auth": ""} ``` @@ -239,53 +235,3 @@ end point now returns the new boolean fields `CpuCfsPeriod`, `CpuCfsQuota`, and * `POST /build` closing the HTTP request cancels the build * `POST /containers/(id)/exec` includes `Warnings` field to response. -### v1.17 API changes - -[Docker Remote API v1.17](docker_remote_api_v1.17.md) documentation - -* The build supports `LABEL` command. Use this to add metadata to an image. For -example you could add data describing the content of an image. `LABEL -"com.example.vendor"="ACME Incorporated"` -* `POST /containers/(id)/attach` and `POST /exec/(id)/start` -* The Docker client now hints potential proxies about connection hijacking using HTTP Upgrade headers. -* `POST /containers/create` sets labels on container create describing the container. -* `GET /containers/json` returns the labels associated with the containers (`Labels`). -* `GET /containers/(id)/json` returns the list current execs associated with the -container (`ExecIDs`). This endpoint now returns the container labels -(`Config.Labels`). -* `POST /containers/(id)/rename` renames a container `id` to a new name.* -* `POST /containers/create` and `POST /containers/(id)/start` callers can pass -`ReadonlyRootfs` in the host config to mount the container's root filesystem as -read only. -* `GET /containers/(id)/stats` returns a live stream of a container's resource usage statistics. -* `GET /images/json` returns the labels associated with each image (`Labels`). - - -### v1.16 API changes - -[Docker Remote API v1.16](docker_remote_api_v1.16.md) - -* `GET /info` returns the number of CPUs available on the machine (`NCPU`), -total memory available (`MemTotal`), a user-friendly name describing the running Docker daemon (`Name`), a unique ID identifying the daemon (`ID`), and -a list of daemon labels (`Labels`). -* `POST /containers/create` callers can set the new container's MAC address explicitly. -* Volumes are now initialized when the container is created. -* `POST /containers/(id)/copy` copies data which is contained in a volume. - -### v1.15 API changes - -[Docker Remote API v1.15](docker_remote_api_v1.15.md) documentation - -`POST /containers/create` you can set a container's `HostConfig` when creating a -container. Previously this was only available when starting a container. - -### v1.14 API changes - -[Docker Remote API v1.14](docker_remote_api_v1.14.md) documentation - -* `DELETE /containers/(id)` when using `force`, the container will be immediately killed with SIGKILL. -* `POST /containers/(id)/start` the `HostConfig` option accepts the field `CapAdd`, which specifies a list of capabilities -to add, and the field `CapDrop`, which specifies a list of capabilities to drop. -* `POST /images/create` th `fromImage` and `repo` parameters support the -`repo:tag` format. Consequently, the `tag` parameter is now obsolete. Using the -new format and the `tag` parameter at the same time will return an error. diff --git a/docs/reference/api/docker_remote_api_v1.14.md b/docs/reference/api/docker_remote_api_v1.14.md deleted file mode 100644 index 673ed84437..0000000000 --- a/docs/reference/api/docker_remote_api_v1.14.md +++ /dev/null @@ -1,1469 +0,0 @@ - - -# Docker Remote API v1.14 - -## 1. Brief introduction - - - The Remote API has replaced `rcli`. - - The daemon listens on `unix:///var/run/docker.sock` but you can - [Bind Docker to another host/port or a Unix socket](../../quickstart.md#bind-docker-to-another-host-port-or-a-unix-socket). - - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `STDOUT`, - `STDIN` and `STDERR`. - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "9cd87474be90", - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "3176a2479c92", - "Image": "ubuntu:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Image": "ubuntu:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - } - ] - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by default (i.e., this defaults to false) -- **limit** – Show `limit` last created containers, include non-running ones. -- **since** – Show only containers created since Id, include non-running ones. -- **before** – Show only containers created before Id, include non-running ones. -- **size** – 1/True/true or 0/False/false, Show the containers sizes -- **filters** - a json encoded value of the filters (a map[string][]string) to process on the containers list. Available filters: - - exited=<int> -- containers with exit code of <int> - - status=(restarting|running|paused|exited) - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname":"", - "Domainname": "", - "User":"", - "Memory":0, - "MemorySwap":0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin":false, - "AttachStdout":true, - "AttachStderr":true, - "PortSpecs":null, - "Tty":false, - "OpenStdin":false, - "StdinOnce":false, - "Env": [ - "FOO=bar", - "BAZ=quux" - ], - "Cmd":[ - "date" - ], - "Image":"ubuntu", - "Volumes":{ - "/tmp": {} - }, - "WorkingDir":"", - "NetworkDisabled": false, - "ExposedPorts":{ - "22/tcp": {} - }, - "RestartPolicy": { "Name": "always" } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -- **RestartPolicy** – The behavior to apply when the container exits. The - value is an object with a `Name` property of either `"always"` to - always restart or `"on-failure"` to restart only when the container - exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` - controls the number of times to retry before giving up. - The default is not to restart. (optional) - An ever increasing delay (double the previous delay, starting at 100mS) - is added before each restart to prevent flooding the server. -- **config** – the container's configuration - -Query Parameters: - -- **name** – Assign the specified name to the container. Must match `/?[a-zA-Z0-9_-]+`. - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id or name)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "ubuntu", - "Volumes": {}, - "VolumesFrom": "", - "WorkingDir": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {}, - "HostConfig": { - "Binds": null, - "ContainerIDFile": "", - "LxcConf": [], - "Privileged": false, - "PortBindings": { - "80/tcp": [ - { - "HostIp": "0.0.0.0", - "HostPort": "49153" - } - ] - }, - "Links": ["/name:alias"], - "PublishAllPorts": false, - "CapAdd": ["NET_ADMIN"], - "CapDrop": ["MKNOD"] - } - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id or name)/top` - -List processes running inside the container `id`. On Unix systems this -is done by running the `ps` command. This endpoint is not -supported on Windows. - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles" : [ - "UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD" - ], - "Processes" : [ - [ - "root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash" - ], - [ - "root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10" - ] - ] - } - -**Example request**: - - GET /containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles" : [ - "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND" - ] - "Processes" : [ - [ - "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash" - ], - [ - "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10" - ] - ], - } - -Query Parameters: - -- **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef` - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Get container logs - -`GET /containers/(id or name)/logs` - -Get stdout and stderr logs from the container ``id`` - -**Example request**: - - GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Query Parameters: - -- **follow** – 1/True/true or 0/False/false, return stream. Default false -- **stdout** – 1/True/true or 0/False/false, show stdout log. Default false -- **stderr** – 1/True/true or 0/False/false, show stderr log. Default false -- **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 - ``. Default all - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id or name)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id or name)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Start a container - -`POST /containers/(id or name)/start` - -Start the container `id` - -**Example request**: - - POST /containers/e90e34656806/start HTTP/1.1 - Content-Type: application/json - - { - "Binds":["/tmp:/tmp"], - "Links":["redis3:redis"], - "LxcConf":[{"Key":"lxc.utsname","Value":"docker"}], - "PortBindings":{ "22/tcp": [{ "HostPort": "11022" }] }, - "PublishAllPorts":false, - "Privileged":false, - "Dns": ["8.8.8.8"], - "VolumesFrom": ["parent", "other:ro"], - "CapAdd": ["NET_ADMIN"], - "CapDrop": ["MKNOD"] - } - -**Example response**: - - HTTP/1.1 204 No Content - -Json Parameters: - -- **hostConfig** – the container's host configuration (optional) - -Status Codes: - -- **204** – no error -- **304** – container already started -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id or name)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **304** – container already stopped -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id or name)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id or name)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters - -- **signal** - Signal to send to the container: integer or string like "SIGINT". - When not set, SIGKILL is assumed and the call will wait for the container to exit. - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Pause a container - -`POST /containers/(id or name)/pause` - -Pause the container `id` - -**Example request**: - - POST /containers/e90e34656806/pause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Unpause a container - -`POST /containers/(id or name)/unpause` - -Unpause the container `id` - -**Example request**: - - POST /containers/e90e34656806/unpause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id or name)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Query Parameters: - -- **logs** – 1/True/true or 0/False/false, return logs. Default false -- **stream** – 1/True/true or 0/False/false, return stream. Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach to stdin. - Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - - **Stream details**: - - When using the TTY setting is enabled in - [`POST /containers/create`](#create-a-container), - the stream is the raw data from the process PTY and client's stdin. - When the TTY is disabled, then the stream is multiplexed to separate - stdout and stderr. - - The format is a **Header** and a **Payload** (frame). - - **HEADER** - - The header will contain the information on which stream write the - stream (stdout or stderr). It also contain the size of the - associated frame encoded on the last 4 bytes (uint32). - - It is encoded on the first 8 bytes like this: - - header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} - - `STREAM_TYPE` can be: - -- 0: stdin (will be written on stdout) -- 1: stdout -- 2: stderr - - `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of - the uint32 size encoded as big endian. - - **PAYLOAD** - - The payload is the raw stream. - - **IMPLEMENTATION** - - The simplest way to implement the Attach protocol is the following: - - 1. Read 8 bytes - 2. chose stdout or stderr depending on the first byte - 3. Extract the frame size from the last 4 bytes - 4. Read the extracted size and output it on the correct output - 5. Goto 1 - -### Attach to a container (websocket) - -`GET /containers/(id or name)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **logs** – 1/True/true or 0/False/false, return logs. Default false -- **stream** – 1/True/true or 0/False/false, return stream. - Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach - to stdin. Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id or name)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id or name)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **v** – 1/True/true or 0/False/false, Remove the volumes - associated to the container. Default false -- **force** - 1/True/true or 0/False/false, Kill then remove the container. - Default false - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id or name)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/json` - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "RepoTags": [ - "ubuntu:12.04", - "ubuntu:precise", - "ubuntu:latest" - ], - "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", - "Created": 1365714795, - "Size": 131506275, - "VirtualSize": 131506275 - }, - { - "RepoTags": [ - "ubuntu:12.10", - "ubuntu:quantal" - ], - "ParentId": "27cf784147099545", - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Created": 1364102658, - "Size": 24653, - "VirtualSize": 180116135 - } - ] - - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, default false -- **filters** – a json encoded value of the filters (a map[string][]string) to process on the images list. Available filters: - - dangling=true -- **filter** - only return images with the specified name - -### Create an image - -`POST /images/create` - -Create an image, either by pulling it from the registry or by importing it - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pulling..."} - {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} - {"error": "Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -Query Parameters: - -- **fromImage** – name of the image to pull -- **fromSrc** – source to import, - means stdin -- **repo** – repository -- **tag** – tag - -Request Headers: - -- **X-Registry-Auth** – base64-encoded AuthConfig object - -Status Codes: - -- **200** – no error -- **500** – server error - - - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/ubuntu/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Created": "2013-03-23T22:24:18.818426-07:00", - "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "ContainerConfig": - { - "Hostname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": false, - "AttachStderr": false, - "PortSpecs": null, - "Tty": true, - "OpenStdin": true, - "StdinOnce": false, - "Env": null, - "Cmd": ["/bin/bash"], - "Dns": null, - "Image": "ubuntu", - "Volumes": null, - "VolumesFrom": "", - "WorkingDir": "" - }, - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Parent": "27cf784147099545", - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/ubuntu/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pushing..."} - {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} - {"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. - -**Example request**: - - POST /images/registry.acme.com:5000/test/push HTTP/1.1 - - -Query Parameters: - -- **tag** – the tag to associate with the image on the registry, optional - -Request Headers: - -- **X-Registry-Auth** – include a base64-encoded AuthConfig object. - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 Created - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Query Parameters: - -- **force** – 1/True/true or 0/False/false, default false -- **noprune** – 1/True/true or 0/False/false, default false - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com). - -> **Note**: -> The response keys have changed from API v1.6 to reflect the JSON -> sent by the registry server to the docker daemon's request. - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "wma55/u1210sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "jdswinbank/sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "vgauthier/sshd", - "star_count": 0 - } - ... - ] - -Query Parameters: - -- **term** – term to search - -Status Codes: - -- **200** – no error -- **500** – server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"stream": "Step 1..."} - {"stream": "..."} - {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - - The archive must include a file called `Dockerfile` - at its root. It may include any number of other files, - which will be accessible in the build context (See the [*ADD build - command*](../../reference/builder.md#dockerbuilder)). - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – git or HTTP/HTTPS URI build source -- **q** – suppress verbose build output -- **nocache** – do not use the cache when building the image -- **rm** - remove intermediate containers after a successful build (default behavior) -- **forcerm** - always remove intermediate containers (includes rm) - - Request Headers: - -- **Content-type** – should be set to `"application/tar"`. -- **X-Registry-Config** – base64-encoded ConfigFile object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers": 11, - "Images": 16, - "Driver": "btrfs", - "ExecutionDriver": "native-0.1", - "KernelVersion": "3.12.0-1-amd64" - "Debug": false, - "NFd": 11, - "NGoroutines": 21, - "NEventsListener": 0, - "InitPath": "/usr/bin/docker", - "IndexServerAddress": ["https://index.docker.io/v1/"], - "MemoryLimit": true, - "SwapLimit": false, - "IPv4Forwarding": true - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "ApiVersion": "1.12", - "Version": "0.2.2", - "GitCommit": "5a2a5cc+CHANGES", - "GoVersion": "go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Ping the docker server - -`GET /_ping` - -Ping the docker server - -**Example request**: - - GET /_ping HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - OK - -Status Codes: - -- **200** - no error -- **500** - server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Hostname": "", - "Domainname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Volumes": { - "/tmp": {} - }, - "WorkingDir": "", - "NetworkDisabled": false, - "ExposedPorts": { - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - {"Id": "596069db4bf5"} - -Json Parameters: - -- **config** - the container's configuration - -Query Parameters: - -- **container** – source container -- **repo** – repository -- **tag** – tag -- **comment** – commit message -- **author** – author (e.g., "John Hannibal Smith - <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get container events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} - {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling -- **until** – timestamp used for polling - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images and tags in a repository - -`GET /images/(name)/get` - -Get a tarball containing all images and metadata for the repository -specified by `name`. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/ubuntu/get - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Load a tarball with a set of images and tags into docker - -`POST /images/load` - -Load a set of images and tags into the docker repository. -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - POST /images/load - - Tarball in body - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **500** – server error - -### Image tarball format - -An image tarball contains one directory per image layer (named using its long ID), -each containing three files: - -1. `VERSION`: currently `1.0` - the file format version -2. `json`: detailed layer information, similar to `docker inspect layer_id` -3. `layer.tar`: A tarfile containing the filesystem changes in this layer - -The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories -for storing attribute changes and deletions. - -If the tarball defines a repository, there will also be a `repositories` file at -the root that contains a list of repository and tag names mapped to layer IDs. - -``` -{"hello-world": - {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} -} -``` - -# 3. Going further - -## 3.1 Inside `docker run` - -As an example, the `docker run` command line makes the following API calls: - -- Create the container - -- If the status code is 404, it means the image doesn't exist: - - Try to pull it - - Then retry to create the container - -- Start the container - -- If you are not in detached mode: - - Attach to the container, using logs=1 (to have stdout and - stderr from the container's start) and stream=1 - -- If in detached mode or only stdin is attached: - - Display the container's id - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -stdout and stderr on the same socket. This might change in the future. - -## 3.3 CORS Requests - -To enable cross origin requests to the remote api add the flag -"--api-enable-cors" when running docker in daemon mode. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.15.md b/docs/reference/api/docker_remote_api_v1.15.md deleted file mode 100644 index e5f3ca6348..0000000000 --- a/docs/reference/api/docker_remote_api_v1.15.md +++ /dev/null @@ -1,1763 +0,0 @@ - - -# Docker Remote API v1.15 - -## 1. Brief introduction - - - The Remote API has replaced `rcli`. - - The daemon listens on `unix:///var/run/docker.sock` but you can - [Bind Docker to another host/port or a Unix socket](../../quickstart.md#bind-docker-to-another-host-port-or-a-unix-socket). - - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `STDOUT`, - `STDIN` and `STDERR`. - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Names":["/boring_feynman"], - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "9cd87474be90", - "Names":["/coolName"], - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "3176a2479c92", - "Names":["/sleepy_dog"], - "Image": "ubuntu:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Names":["/running_cat"], - "Image": "ubuntu:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - } - ] - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by default (i.e., this defaults to false) -- **limit** – Show `limit` last created - containers, include non-running ones. -- **since** – Show only containers created since Id, include - non-running ones. -- **before** – Show only containers created before Id, include - non-running ones. -- **size** – 1/True/true or 0/False/false, Show the containers - sizes -- **filters** - a json encoded value of the filters (a map[string][]string) to process on the containers list. Available filters: - - exited=<int> -- containers with exit code of <int> - - status=(restarting|running|paused|exited) - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname": "", - "Domainname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": [ - "FOO=bar", - "BAZ=quux" - ], - "Cmd": [ - "date" - ], - "Entrypoint": "", - "Image": "ubuntu", - "Volumes": { - "/tmp": {} - }, - "WorkingDir": "", - "NetworkDisabled": false, - "MacAddress": "12:34:56:78:9a:bc", - "ExposedPorts": { - "22/tcp": {} - }, - "SecurityOpt": [], - "HostConfig": { - "Binds": ["/tmp:/tmp"], - "Links": ["redis3:redis"], - "LxcConf": {"lxc.utsname":"docker"}, - "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] }, - "PublishAllPorts": false, - "Privileged": 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": [] - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id": "f91ddc4b01e079c4481a8340bbbeca4dbd33d6e4a10662e499f8eacbb5bf252b" - "Warnings": [] - } - -Json Parameters: - -- **Hostname** - A string value containing the desired hostname to use for the - container. -- **Domainname** - A string value containing the desired domain name to use - for the container. -- **User** - A string value containing the user to use inside the container. -- **Memory** - Memory limit in bytes. -- **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap. -- **CpuShares** - An integer value containing the CPU Shares for container - (ie. the relative weight vs other containers). - **CpuSet** - String value containing the cgroups Cpuset to use. -- **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"]]` -- **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 - container to empty objects. -- **WorkingDir** - A string value containing the working dir 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": { "/: {}" }` -- **SecurityOpt**: A list of string values to customize labels for MLS - systems, such as SELinux. -- **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). - - **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 - work when using the `lxc` execution driver. - - **PortBindings** - A map of exposed container ports and the host port they - should map to. It should be specified in the form - `{ /: [{ "HostPort": "" }] }` - Take note that `port` is specified as a string and not an integer value. - - **PublishAllPorts** - Allocates a random host port for all of a container's - exposed ports. Specified as a boolean value. - - **Privileged** - Gives the container full access to the host. Specified as - a boolean value. - - **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 - 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 `[:]` - - **CapAdd** - A list of kernel capabilities to add to the container. - - **Capdrop** - A list of kernel capabilities to drop from the container. - - **RestartPolicy** – The behavior to apply when the container exits. The - value is an object with a `Name` property of either `"always"` to - always restart or `"on-failure"` to restart only when the container - exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` - controls the number of times to retry before giving up. - The default is not to restart. (optional) - An ever increasing delay (double the previous delay, starting at 100mS) - is added before each restart to prevent flooding the server. - - **NetworkMode** - Sets the networking mode for the container. Supported - values are: `bridge`, `host`, `none`, and `container:` - - **Devices** - A list of devices to add to the container specified in the - form - `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}` - -Query Parameters: - -- **name** – Assign the specified name to the container. Must - match `/?[a-zA-Z0-9_-]+`. - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id or name)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "ubuntu", - "Volumes": {}, - "VolumesFrom": "", - "WorkingDir": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {}, - "HostConfig": { - "Binds": null, - "ContainerIDFile": "", - "LxcConf": [], - "Privileged": false, - "PortBindings": { - "80/tcp": [ - { - "HostIp": "0.0.0.0", - "HostPort": "49153" - } - ] - }, - "Links": ["/name:alias"], - "PublishAllPorts": false, - "CapAdd": ["NET_ADMIN"], - "CapDrop": ["MKNOD"] - } - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id or name)/top` - -List processes running inside the container `id`. On Unix systems this -is done by running the `ps` command. This endpoint is not -supported on Windows. - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles" : [ - "UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD" - ], - "Processes" : [ - [ - "root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash" - ], - [ - "root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10" - ] - ] - } - -**Example request**: - - GET /containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles" : [ - "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND" - ] - "Processes" : [ - [ - "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash" - ], - [ - "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10" - ] - ], - } - -Query Parameters: - -- **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef` - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Get container logs - -`GET /containers/(id or name)/logs` - -Get stdout and stderr logs from the container ``id`` - -**Example request**: - - GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Query Parameters: - -- **follow** – 1/True/true or 0/False/false, return stream. Default false -- **stdout** – 1/True/true or 0/False/false, show stdout log. Default false -- **stderr** – 1/True/true or 0/False/false, show stderr log. Default false -- **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 ``. Default all - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id or name)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id or name)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Resize a container TTY - -`GET /containers/(id or name)/resize?h=&w=` - -Resize the TTY of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Length: 0 - Content-Type: text/plain; charset=utf-8 - -Status Codes: - -- **200** – no error -- **404** – No such container -- **500** – bad file descriptor - -### Start a container - -`POST /containers/(id or name)/start` - -Start the container `id` - -**Example request**: - - POST /containers/e90e34656806/start HTTP/1.1 - Content-Type: application/json - - { - "Binds": ["/tmp:/tmp"], - "Links": ["redis3:redis"], - "LxcConf": {"lxc.utsname":"docker"}, - "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] }, - "PublishAllPorts": false, - "Privileged": false, - "Dns": ["8.8.8.8"], - "DnsSearch": [""], - "VolumesFrom": ["parent", "other:ro"], - "CapAdd": ["NET_ADMIN"], - "CapDrop": ["MKNOD"], - "RestartPolicy": { "Name": "", "MaximumRetryCount": 0 }, - "NetworkMode": "bridge", - "Devices": [] - } - -**Example response**: - - HTTP/1.1 204 No Content - -Json Parameters: - -- **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). -- **Links** - A list of links for the container. Each link entry should be of - of the form "container_name:alias". -- **LxcConf** - LXC specific configurations. These configurations will only - work when using the `lxc` execution driver. -- **PortBindings** - A map of exposed container ports and the host port they - should map to. It should be specified in the form - `{ /: [{ "HostPort": "" }] }` - Take note that `port` is specified as a string and not an integer value. -- **PublishAllPorts** - Allocates a random host port for all of a container's - exposed ports. Specified as a boolean value. -- **Privileged** - Gives the container full access to the host. Specified as - a boolean value. -- **Dns** - A list of dns servers for the container to use. -- **DnsSearch** - A list of DNS search domains -- **VolumesFrom** - A list of volumes to inherit from another container. - Specified in the form `[:]` -- **CapAdd** - A list of kernel capabilities to add to the container. -- **Capdrop** - A list of kernel capabilities to drop from the container. -- **RestartPolicy** – The behavior to apply when the container exits. The - value is an object with a `Name` property of either `"always"` to - always restart or `"on-failure"` to restart only when the container - exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` - controls the number of times to retry before giving up. - The default is not to restart. (optional) - An ever increasing delay (double the previous delay, starting at 100mS) - is added before each restart to prevent flooding the server. -- **NetworkMode** - Sets the networking mode for the container. Supported - values are: `bridge`, `host`, `none`, and `container:` -- **Devices** - A list of devices to add to the container specified in the - form - `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}` - -Status Codes: - -- **204** – no error -- **304** – container already started -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id or name)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **304** – container already stopped -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id or name)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id or name)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters - -- **signal** - Signal to send to the container: integer or string like "SIGINT". - When not set, SIGKILL is assumed and the call will waits for the container to exit. - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Pause a container - -`POST /containers/(id or name)/pause` - -Pause the container `id` - -**Example request**: - - POST /containers/e90e34656806/pause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Unpause a container - -`POST /containers/(id or name)/unpause` - -Unpause the container `id` - -**Example request**: - - POST /containers/e90e34656806/unpause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id or name)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Query Parameters: - -- **logs** – 1/True/true or 0/False/false, return logs. Default false -- **stream** – 1/True/true or 0/False/false, return stream. - Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach - to stdin. Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - - **Stream details**: - - When using the TTY setting is enabled in - [`POST /containers/create`](#create-a-container), - the stream is the raw data from the process PTY and client's stdin. - When the TTY is disabled, then the stream is multiplexed to separate - stdout and stderr. - - The format is a **Header** and a **Payload** (frame). - - **HEADER** - - The header will contain the information on which stream write the - stream (stdout or stderr). It also contain the size of the - associated frame encoded on the last 4 bytes (uint32). - - It is encoded on the first 8 bytes like this: - - header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} - - `STREAM_TYPE` can be: - -- 0: stdin (will be written on stdout) -- 1: stdout -- 2: stderr - - `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of - the uint32 size encoded as big endian. - - **PAYLOAD** - - The payload is the raw stream. - - **IMPLEMENTATION** - - The simplest way to implement the Attach protocol is the following: - - 1. Read 8 bytes - 2. chose stdout or stderr depending on the first byte - 3. Extract the frame size from the last 4 bytes - 4. Read the extracted size and output it on the correct output - 5. Goto 1 - -### Attach to a container (websocket) - -`GET /containers/(id or name)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **logs** – 1/True/true or 0/False/false, return logs. Default false -- **stream** – 1/True/true or 0/False/false, return stream. - Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach - to stdin. Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id or name)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id or name)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **v** – 1/True/true or 0/False/false, Remove the volumes - associated to the container. Default false -- **force** - 1/True/true or 0/False/false, Kill then remove the container. - Default false - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id or name)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/json` - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "RepoTags": [ - "ubuntu:12.04", - "ubuntu:precise", - "ubuntu:latest" - ], - "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", - "Created": 1365714795, - "Size": 131506275, - "VirtualSize": 131506275 - }, - { - "RepoTags": [ - "ubuntu:12.10", - "ubuntu:quantal" - ], - "ParentId": "27cf784147099545", - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Created": 1364102658, - "Size": 24653, - "VirtualSize": 180116135 - } - ] - - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, default false -- **filters** – a json encoded value of the filters (a map[string][]string) to process on the images list. Available filters: - - dangling=true -- **filter** - only return images with the specified name - -### Create an image - -`POST /images/create` - -Create an image, either by pulling it from the registry or by importing it - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pulling..."} - {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} - {"error": "Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -Query Parameters: - -- **fromImage** – name of the image to pull -- **fromSrc** – source to import. The value may be a URL from which the image - can be retrieved or `-` to read the image from the request body. -- **repo** – repository -- **tag** – tag - - Request Headers: - -- **X-Registry-Auth** – base64-encoded AuthConfig object - -Status Codes: - -- **200** – no error -- **500** – server error - - - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/ubuntu/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Created": "2013-03-23T22:24:18.818426-07:00", - "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "ContainerConfig": - { - "Hostname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": false, - "AttachStderr": false, - "PortSpecs": null, - "Tty": true, - "OpenStdin": true, - "StdinOnce": false, - "Env": null, - "Cmd": ["/bin/bash"], - "Dns": null, - "Image": "ubuntu", - "Volumes": null, - "VolumesFrom": "", - "WorkingDir": "" - }, - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Parent": "27cf784147099545", - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/ubuntu/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pushing..."} - {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} - {"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. - -**Example request**: - - POST /images/registry.acme.com:5000/test/push HTTP/1.1 - - -Query Parameters: - -- **tag** – the tag to associate with the image on the registry, optional - -Request Headers: - -- **X-Registry-Auth** – include a base64-encoded AuthConfig - object. - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 Created - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Query Parameters: - -- **force** – 1/True/true or 0/False/false, default false -- **noprune** – 1/True/true or 0/False/false, default false - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com). - -> **Note**: -> The response keys have changed from API v1.6 to reflect the JSON -> sent by the registry server to the docker daemon's request. - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "wma55/u1210sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "jdswinbank/sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "vgauthier/sshd", - "star_count": 0 - } - ... - ] - -Query Parameters: - -- **term** – term to search - -Status Codes: - -- **200** – no error -- **500** – server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"stream": "Step 1..."} - {"stream": "..."} - {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - - The archive must include a file called `Dockerfile` - at its root. It may include any number of other files, - which will be accessible in the build context (See the [*ADD build - command*](../../reference/builder.md#dockerbuilder)). - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – git or HTTP/HTTPS URI build source -- **q** – suppress verbose build output -- **nocache** – do not use the cache when building the image -- **rm** - remove intermediate containers after a successful build (default behavior) -- **forcerm** - always remove intermediate containers (includes rm) - - Request Headers: - -- **Content-type** – should be set to `"application/tar"`. -- **X-Registry-Config** – base64-encoded ConfigFile object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers": 11, - "Images": 16, - "Driver": "btrfs", - "ExecutionDriver": "native-0.1", - "KernelVersion": "3.12.0-1-amd64" - "Debug": false, - "NFd": 11, - "NGoroutines": 21, - "NEventsListener": 0, - "InitPath": "/usr/bin/docker", - "IndexServerAddress": ["https://index.docker.io/v1/"], - "MemoryLimit": true, - "SwapLimit": false, - "IPv4Forwarding": true - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "ApiVersion": "1.12", - "Version": "0.2.2", - "GitCommit": "5a2a5cc+CHANGES", - "GoVersion": "go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Ping the docker server - -`GET /_ping` - -Ping the docker server - -**Example request**: - - GET /_ping HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - OK - -Status Codes: - -- **200** - no error -- **500** - server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Hostname": "", - "Domainname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Volumes": { - "/tmp": {} - }, - "WorkingDir": "", - "NetworkDisabled": false, - "ExposedPorts": { - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - {"Id": "596069db4bf5"} - -Json Parameters: - -- **config** - the container's configuration - -Query Parameters: - -- **container** – source container -- **repo** – repository -- **tag** – tag -- **comment** – commit message -- **author** – author (e.g., "John Hannibal Smith - <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get container events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} - {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling -- **until** – timestamp used for polling - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images in a repository - -`GET /images/(name)/get` - -Get a tarball containing all images and metadata for the repository specified -by `name`. - -If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image -(and its parents) are returned. If `name` is an image ID, similarly only that -image (and its parents) are returned, but with the exclusion of the -'repositories' file in the tarball, as there were no image names referenced. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/ubuntu/get - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images. - -`GET /images/get` - -Get a tarball containing all images and metadata for one or more repositories. - -For each value of the `names` parameter: if it is a specific name and tag (e.g. -ubuntu:latest), then only that image (and its parents) are returned; if it is -an image ID, similarly only that image (and its parents) are returned and there -would be no names referenced in the 'repositories' file for this image ID. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/get?names=myname%2Fmyapp%3Alatest&names=busybox - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Load a tarball with a set of images and tags into docker - -`POST /images/load` - -Load a set of images and tags into the docker repository. -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - POST /images/load - - Tarball in body - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **500** – server error - -### Image tarball format - -An image tarball contains one directory per image layer (named using its long ID), -each containing three files: - -1. `VERSION`: currently `1.0` - the file format version -2. `json`: detailed layer information, similar to `docker inspect layer_id` -3. `layer.tar`: A tarfile containing the filesystem changes in this layer - -The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories -for storing attribute changes and deletions. - -If the tarball defines a repository, there will also be a `repositories` file at -the root that contains a list of repository and tag names mapped to layer IDs. - -``` -{"hello-world": - {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} -} -``` - -### Exec Create - -`POST /containers/(id or name)/exec` - -Sets up an exec instance in a running container `id` - -**Example request**: - - POST /containers/e90e34656806/exec HTTP/1.1 - Content-Type: application/json - - { - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "Tty": false, - "Cmd": [ - "date" - ], - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id": "f90e34656806" - } - -Json Parameters: - -- **AttachStdin** - Boolean value, attaches to stdin of the exec command. -- **AttachStdout** - Boolean value, attaches to stdout of the exec command. -- **AttachStderr** - Boolean value, attaches to stderr of the exec command. -- **Tty** - Boolean value to allocate a pseudo-TTY -- **Cmd** - Command to run specified as a string or an array of strings. - - -Status Codes: - -- **201** – no error -- **404** – no such container - -### Exec Start - -`POST /exec/(id)/start` - -Starts a previously set up exec instance `id`. If `detach` is true, this API -returns after starting the `exec` command. Otherwise, this API sets up an -interactive session with the `exec` command. - -**Example request**: - - POST /exec/e90e34656806/start HTTP/1.1 - Content-Type: application/json - - { - "Detach": false, - "Tty": false, - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Json Parameters: - -- **Detach** - Detach from the exec command -- **Tty** - Boolean value to allocate a pseudo-TTY - -Status Codes: - -- **200** – no error -- **404** – no such exec instance - - **Stream details**: - Similar to the stream behavior of `POST /containers/(id or name)/attach` API - -### Exec Resize - -`POST /exec/(id)/resize` - -Resizes the tty session used by the exec command `id`. -This API is valid only if `tty` was specified as part of creating and starting the exec command. - -**Example request**: - - POST /exec/e90e34656806/resize HTTP/1.1 - Content-Type: plain/text - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: plain/text - -Query Parameters: - -- **h** – height of tty session -- **w** – width - -Status Codes: - -- **201** – no error -- **404** – no such exec instance - -# 3. Going further - -## 3.1 Inside `docker run` - -As an example, the `docker run` command line makes the following API calls: - -- Create the container - -- If the status code is 404, it means the image doesn't exist: - - Try to pull it - - Then retry to create the container - -- Start the container - -- If you are not in detached mode: -- Attach to the container, using logs=1 (to have stdout and - stderr from the container's start) and stream=1 - -- If in detached mode or only stdin is attached: -- Display the container's id - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -stdout and stderr on the same socket. This might change in the future. - -## 3.3 CORS Requests - -To enable cross origin requests to the remote api add the flag -"--api-enable-cors" when running docker in daemon mode. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.16.md b/docs/reference/api/docker_remote_api_v1.16.md deleted file mode 100644 index f6e768ce0c..0000000000 --- a/docs/reference/api/docker_remote_api_v1.16.md +++ /dev/null @@ -1,1833 +0,0 @@ - - -# Docker Remote API v1.16 - -## 1. Brief introduction - - - The Remote API has replaced `rcli`. - - The daemon listens on `unix:///var/run/docker.sock` but you can - [Bind Docker to another host/port or a Unix socket](../../quickstart.md#bind-docker-to-another-host-port-or-a-unix-socket). - - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `STDOUT`, - `STDIN` and `STDERR`. - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Names":["/boring_feynman"], - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "9cd87474be90", - "Names":["/coolName"], - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "3176a2479c92", - "Names":["/sleep_dog"], - "Image": "ubuntu:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Names":["/running_cat"], - "Image": "ubuntu:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - } - ] - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by default (i.e., this defaults to false) -- **limit** – Show `limit` last created - containers, include non-running ones. -- **since** – Show only containers created since Id, include - non-running ones. -- **before** – Show only containers created before Id, include - non-running ones. -- **size** – 1/True/true or 0/False/false, Show the containers - sizes -- **filters** - a json encoded value of the filters (a map[string][]string) to process on the containers list. Available filters: - - exited=<int> -- containers with exit code of <int> - - status=(restarting|running|paused|exited) - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname": "", - "Domainname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": [ - "FOO=bar", - "BAZ=quux" - ], - "Cmd": [ - "date" - ], - "Entrypoint": "", - "Image": "ubuntu", - "Volumes": { - "/tmp": {} - }, - "WorkingDir": "", - "NetworkDisabled": false, - "MacAddress": "12:34:56:78:9a:bc", - "ExposedPorts": { - "22/tcp": {} - }, - "SecurityOpt": [], - "HostConfig": { - "Binds": ["/tmp:/tmp"], - "Links": ["redis3:redis"], - "LxcConf": {"lxc.utsname":"docker"}, - "PortBindings": { "22/tcp": [{ "HostPort": "11022" }] }, - "PublishAllPorts": false, - "Privileged": 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": [] - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806" - "Warnings":[] - } - -Json Parameters: - -- **Hostname** - A string value containing the desired hostname to use for the - container. -- **Domainname** - A string value containing the desired domain name to use - for the container. -- **User** - A string value containing the user to use inside the container. -- **Memory** - Memory limit in bytes. -- **MemorySwap** - Total memory limit (memory + swap); set `-1` to enable unlimited swap. -- **CpuShares** - An integer value containing the CPU Shares for container - (ie. the relative weight vs other containers). - **CpuSet** - String value containing the cgroups Cpuset to use. -- **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"]]` -- **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 - container to empty objects. -- **WorkingDir** - A string value containing the working dir 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": { "/: {}" }` -- **SecurityOpt**: A list of string values to customize labels for MLS - systems, such as SELinux. -- **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). - - **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 - work when using the `lxc` execution driver. - - **PortBindings** - A map of exposed container ports and the host port they - should map to. It should be specified in the form - `{ /: [{ "HostPort": "" }] }` - Take note that `port` is specified as a string and not an integer value. - - **PublishAllPorts** - Allocates a random host port for all of a container's - exposed ports. Specified as a boolean value. - - **Privileged** - Gives the container full access to the host. Specified as - a boolean value. - - **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 - 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 `[:]` - - **CapAdd** - A list of kernel capabilities to add to the container. - - **Capdrop** - A list of kernel capabilities to drop from the container. - - **RestartPolicy** – The behavior to apply when the container exits. The - value is an object with a `Name` property of either `"always"` to - always restart or `"on-failure"` to restart only when the container - exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` - controls the number of times to retry before giving up. - The default is not to restart. (optional) - An ever increasing delay (double the previous delay, starting at 100mS) - is added before each restart to prevent flooding the server. - - **NetworkMode** - Sets the networking mode for the container. Supported - values are: `bridge`, `host`, `none`, and `container:` - - **Devices** - A list of devices to add to the container specified in the - form - `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}` - -Query Parameters: - -- **name** – Assign the specified name to the container. Must - match `/?[a-zA-Z0-9_-]+`. - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id or name)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Id": "4fa6e0f0c6786287e131c3852c58a2e01cc697a68231826813597e4994f1d6e2", - "Created": "2013-05-07T14:51:42.041847+02:00", - "Path": "date", - "Args": [], - "Config": { - "Hostname": "4fa6e0f0c678", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Dns": null, - "Image": "ubuntu", - "Volumes": {}, - "VolumesFrom": "", - "WorkingDir": "" - }, - "State": { - "Running": false, - "Pid": 0, - "ExitCode": 0, - "StartedAt": "2013-05-07T14:51:42.087658+02:01360", - "Ghost": false - }, - "Image": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "NetworkSettings": { - "IpAddress": "", - "IpPrefixLen": 0, - "Gateway": "", - "Bridge": "", - "PortMapping": null - }, - "SysInitPath": "/home/kitty/go/src/github.com/docker/docker/bin/docker", - "ResolvConfPath": "/etc/resolv.conf", - "Volumes": {}, - "HostConfig": { - "Binds": null, - "ContainerIDFile": "", - "LxcConf": [], - "Privileged": false, - "PortBindings": { - "80/tcp": [ - { - "HostIp": "0.0.0.0", - "HostPort": "49153" - } - ] - }, - "Links": ["/name:alias"], - "PublishAllPorts": false, - "CapAdd": ["NET_ADMIN"], - "CapDrop": ["MKNOD"] - } - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id or name)/top` - -List processes running inside the container `id`. On Unix systems this -is done by running the `ps` command. This endpoint is not -supported on Windows. - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles" : [ - "UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD" - ], - "Processes" : [ - [ - "root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash" - ], - [ - "root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10" - ] - ] - } - -**Example request**: - - GET /containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles" : [ - "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND" - ] - "Processes" : [ - [ - "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash" - ], - [ - "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10" - ] - ], - } - -Query Parameters: - -- **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef` - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Get container logs - -`GET /containers/(id or name)/logs` - -Get stdout and stderr logs from the container ``id`` - -**Example request**: - - GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Query Parameters: - -- **follow** – 1/True/true or 0/False/false, return stream. Default false -- **stdout** – 1/True/true or 0/False/false, show stdout log. Default false -- **stderr** – 1/True/true or 0/False/false, show stderr log. Default false -- **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 ``. Default all - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id or name)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id or name)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Resize a container TTY - -`POST /containers/(id or name)/resize?h=&w=` - -Resize the TTY for container with `id`. The container must be restarted for the resize to take effect. - -**Example request**: - - POST /containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Length: 0 - Content-Type: text/plain; charset=utf-8 - -Status Codes: - -- **200** – no error -- **404** – No such container -- **500** – Cannot resize container - -### Start a container - -`POST /containers/(id or name)/start` - -Start the container `id` - -> **Note**: -> For backwards compatibility, this endpoint accepts a `HostConfig` as JSON-encoded request body. -> See [create a container](#create-a-container) for details. - -**Example request**: - - POST /containers/e90e34656806/start HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **304** – container already started -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id or name)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **304** – container already stopped -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id or name)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id or name)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters - -- **signal** - Signal to send to the container: integer or string like "SIGINT". - When not set, SIGKILL is assumed and the call will waits for the container to exit. - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Pause a container - -`POST /containers/(id or name)/pause` - -Pause the container `id` - -**Example request**: - - POST /containers/e90e34656806/pause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Unpause a container - -`POST /containers/(id or name)/unpause` - -Unpause the container `id` - -**Example request**: - - POST /containers/e90e34656806/unpause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id or name)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Query Parameters: - -- **logs** – 1/True/true or 0/False/false, return logs. Default false -- **stream** – 1/True/true or 0/False/false, return stream. - Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach - to stdin. Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - - **Stream details**: - - When using the TTY setting is enabled in - [`POST /containers/create` - ](#create-a-container), - the stream is the raw data from the process PTY and client's stdin. - When the TTY is disabled, then the stream is multiplexed to separate - stdout and stderr. - - The format is a **Header** and a **Payload** (frame). - - **HEADER** - - The header will contain the information on which stream write the - stream (stdout or stderr). It also contain the size of the - associated frame encoded on the last 4 bytes (uint32). - - It is encoded on the first 8 bytes like this: - - header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} - - `STREAM_TYPE` can be: - -- 0: stdin (will be written on stdout) -- 1: stdout -- 2: stderr - - `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of - the uint32 size encoded as big endian. - - **PAYLOAD** - - The payload is the raw stream. - - **IMPLEMENTATION** - - The simplest way to implement the Attach protocol is the following: - - 1. Read 8 bytes - 2. chose stdout or stderr depending on the first byte - 3. Extract the frame size from the last 4 bytes - 4. Read the extracted size and output it on the correct output - 5. Goto 1 - -### Attach to a container (websocket) - -`GET /containers/(id or name)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **logs** – 1/True/true or 0/False/false, return logs. Default false -- **stream** – 1/True/true or 0/False/false, return stream. - Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach - to stdin. Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id or name)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id or name)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **v** – 1/True/true or 0/False/false, Remove the volumes - associated to the container. Default false -- **force** - 1/True/true or 0/False/false, Kill then remove the container. - Default false - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id or name)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/json` - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "RepoTags": [ - "ubuntu:12.04", - "ubuntu:precise", - "ubuntu:latest" - ], - "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", - "Created": 1365714795, - "Size": 131506275, - "VirtualSize": 131506275 - }, - { - "RepoTags": [ - "ubuntu:12.10", - "ubuntu:quantal" - ], - "ParentId": "27cf784147099545", - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Created": 1364102658, - "Size": 24653, - "VirtualSize": 180116135 - } - ] - - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, default false -- **filters** – a json encoded value of the filters (a map[string][]string) to process on the images list. Available filters: - - dangling=true -- **filter** - only return images with the specified name - -### Create an image - -`POST /images/create` - -Create an image, either by pulling it from the registry or by importing it - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pulling..."} - {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} - {"error": "Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -Query Parameters: - -- **fromImage** – name of the image to pull -- **fromSrc** – source to import. The value may be a URL from which the image - can be retrieved or `-` to read the image from the request body. -- **repo** – repository -- **tag** – tag - - Request Headers: - -- **X-Registry-Auth** – base64-encoded AuthConfig object - -Status Codes: - -- **200** – no error -- **500** – server error - - - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/ubuntu/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Created": "2013-03-23T22:24:18.818426-07:00", - "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "ContainerConfig": - { - "Hostname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": false, - "AttachStderr": false, - "PortSpecs": null, - "Tty": true, - "OpenStdin": true, - "StdinOnce": false, - "Env": null, - "Cmd": ["/bin/bash"], - "Dns": null, - "Image": "ubuntu", - "Volumes": null, - "VolumesFrom": "", - "WorkingDir": "" - }, - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Parent": "27cf784147099545", - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/ubuntu/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pushing..."} - {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} - {"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. - -**Example request**: - - POST /images/registry.acme.com:5000/test/push HTTP/1.1 - - -Query Parameters: - -- **tag** – the tag to associate with the image on the registry, optional - -Request Headers: - -- **X-Registry-Auth** – include a base64-encoded AuthConfig - object. - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 Created - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Query Parameters: - -- **force** – 1/True/true or 0/False/false, default false -- **noprune** – 1/True/true or 0/False/false, default false - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com). - -> **Note**: -> The response keys have changed from API v1.6 to reflect the JSON -> sent by the registry server to the docker daemon's request. - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "wma55/u1210sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "jdswinbank/sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "vgauthier/sshd", - "star_count": 0 - } - ... - ] - -Query Parameters: - -- **term** – term to search - -Status Codes: - -- **200** – no error -- **500** – server error - -## 2.3 Misc - -### Build an image from Dockerfile via stdin - -`POST /build` - -Build an image from Dockerfile via stdin - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"stream": "Step 1..."} - {"stream": "..."} - {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} - - The stream must be a tar archive compressed with one of the - following algorithms: identity (no compression), gzip, bzip2, xz. - - The archive must include a file called `Dockerfile` - at its root. It may include any number of other files, - which will be accessible in the build context (See the [*ADD build - command*](../../reference/builder.md#dockerbuilder)). - -Query Parameters: - -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – git or HTTP/HTTPS URI build source -- **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) - - Request Headers: - -- **Content-type** – should be set to `"application/tar"`. -- **X-Registry-Config** – base64-encoded ConfigFile object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers":11, - "Images":16, - "Driver":"btrfs", - "DriverStatus": [[""]], - "ExecutionDriver":"native-0.1", - "KernelVersion":"3.12.0-1-amd64" - "NCPU":1, - "MemTotal":2099236864, - "Name":"prod-server-42", - "ID":"7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS", - "Debug":false, - "NFd": 11, - "NGoroutines":21, - "NEventsListener":0, - "InitPath":"/usr/bin/docker", - "InitSha1":"", - "IndexServerAddress":["https://index.docker.io/v1/"], - "MemoryLimit":true, - "SwapLimit":false, - "IPv4Forwarding":true, - "Labels":["storage=ssd"], - "DockerRootDir": "/var/lib/docker", - "OperatingSystem": "Boot2Docker", - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "ApiVersion": "1.12", - "Version": "0.2.2", - "GitCommit": "5a2a5cc+CHANGES", - "GoVersion": "go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Ping the docker server - -`GET /_ping` - -Ping the docker server - -**Example request**: - - GET /_ping HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - OK - -Status Codes: - -- **200** - no error -- **500** - server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Hostname": "", - "Domainname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Volumes": { - "/tmp": {} - }, - "WorkingDir": "", - "NetworkDisabled": false, - "ExposedPorts": { - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - {"Id": "596069db4bf5"} - -Json Parameters: - -- **config** - the container's configuration - -Query Parameters: - -- **container** – source container -- **repo** – repository -- **tag** – tag -- **comment** – commit message -- **author** – author (e.g., "John Hannibal Smith - <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get container events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, export, kill, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} - {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling -- **until** – timestamp used for polling -- **filters** – a json encoded value of the filters (a map[string][]string) to process on the event list. Available filters: - - event=<string> -- event to filter - - image=<string> -- image to filter - - container=<string> -- container to filter - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images in a repository - -`GET /images/(name)/get` - -Get a tarball containing all images and metadata for the repository specified -by `name`. - -If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image -(and its parents) are returned. If `name` is an image ID, similarly only that -image (and its parents) are returned, but with the exclusion of the -'repositories' file in the tarball, as there were no image names referenced. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/ubuntu/get - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images. - -`GET /images/get` - -Get a tarball containing all images and metadata for one or more repositories. - -For each value of the `names` parameter: if it is a specific name and tag (e.g. -ubuntu:latest), then only that image (and its parents) are returned; if it is -an image ID, similarly only that image (and its parents) are returned and there -would be no names referenced in the 'repositories' file for this image ID. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/get?names=myname%2Fmyapp%3Alatest&names=busybox - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Load a tarball with a set of images and tags into docker - -`POST /images/load` - -Load a set of images and tags into the docker repository. -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - POST /images/load - - Tarball in body - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **500** – server error - -### Image tarball format - -An image tarball contains one directory per image layer (named using its long ID), -each containing three files: - -1. `VERSION`: currently `1.0` - the file format version -2. `json`: detailed layer information, similar to `docker inspect layer_id` -3. `layer.tar`: A tarfile containing the filesystem changes in this layer - -The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories -for storing attribute changes and deletions. - -If the tarball defines a repository, there will also be a `repositories` file at -the root that contains a list of repository and tag names mapped to layer IDs. - -``` -{"hello-world": - {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} -} -``` - -### Exec Create - -`POST /containers/(id or name)/exec` - -Sets up an exec instance in a running container `id` - -**Example request**: - - POST /containers/e90e34656806/exec HTTP/1.1 - Content-Type: application/json - - { - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "Tty": false, - "Cmd": [ - "date" - ], - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id": "f90e34656806" - } - -Json Parameters: - -- **AttachStdin** - Boolean value, attaches to stdin of the exec command. -- **AttachStdout** - Boolean value, attaches to stdout of the exec command. -- **AttachStderr** - Boolean value, attaches to stderr of the exec command. -- **Tty** - Boolean value to allocate a pseudo-TTY -- **Cmd** - Command to run specified as a string or an array of strings. - - -Status Codes: - -- **201** – no error -- **404** – no such container - -### Exec Start - -`POST /exec/(id)/start` - -Starts a previously set up exec instance `id`. If `detach` is true, this API -returns after starting the `exec` command. Otherwise, this API sets up an -interactive session with the `exec` command. - -**Example request**: - - POST /exec/e90e34656806/start HTTP/1.1 - Content-Type: application/json - - { - "Detach": false, - "Tty": false, - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Json Parameters: - -- **Detach** - Detach from the exec command -- **Tty** - Boolean value to allocate a pseudo-TTY - -Status Codes: - -- **200** – no error -- **404** – no such exec instance - - **Stream details**: - Similar to the stream behavior of `POST /containers/(id or name)/attach` API - -### Exec Resize - -`POST /exec/(id)/resize` - -Resizes the tty session used by the exec command `id`. -This API is valid only if `tty` was specified as part of creating and starting the exec command. - -**Example request**: - - POST /exec/e90e34656806/resize HTTP/1.1 - Content-Type: plain/text - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: plain/text - -Query Parameters: - -- **h** – height of tty session -- **w** – width - -Status Codes: - -- **201** – no error -- **404** – no such exec instance - -### Exec Inspect - -`GET /exec/(id)/json` - -Return low-level information about the exec command `id`. - -**Example request**: - - GET /exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: plain/text - - { - "ID" : "11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39", - "Running" : false, - "ExitCode" : 2, - "ProcessConfig" : { - "privileged" : false, - "user" : "", - "tty" : false, - "entrypoint" : "sh", - "arguments" : [ - "-c", - "exit 2" - ] - }, - "OpenStdin" : false, - "OpenStderr" : false, - "OpenStdout" : false, - "Container" : { - "State" : { - "Running" : true, - "Paused" : false, - "Restarting" : false, - "OOMKilled" : false, - "Pid" : 3650, - "ExitCode" : 0, - "Error" : "", - "StartedAt" : "2014-11-17T22:26:03.717657531Z", - "FinishedAt" : "0001-01-01T00:00:00Z" - }, - "ID" : "8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c", - "Created" : "2014-11-17T22:26:03.626304998Z", - "Path" : "date", - "Args" : [], - "Config" : { - "Hostname" : "8f177a186b97", - "Domainname" : "", - "User" : "", - "Memory" : 0, - "MemorySwap" : 0, - "CpuShares" : 0, - "Cpuset" : "", - "AttachStdin" : false, - "AttachStdout" : false, - "AttachStderr" : false, - "PortSpecs" : null, - "ExposedPorts" : null, - "Tty" : false, - "OpenStdin" : false, - "StdinOnce" : false, - "Env" : [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ], - "Cmd" : [ - "date" - ], - "Image" : "ubuntu", - "Volumes" : null, - "WorkingDir" : "", - "Entrypoint" : null, - "NetworkDisabled" : false, - "MacAddress" : "", - "OnBuild" : null, - "SecurityOpt" : null - }, - "Image" : "5506de2b643be1e6febbf3b8a240760c6843244c41e12aa2f60ccbb7153d17f5", - "NetworkSettings" : { - "IPAddress" : "172.17.0.2", - "IPPrefixLen" : 16, - "MacAddress" : "02:42:ac:11:00:02", - "Gateway" : "172.17.42.1", - "Bridge" : "docker0", - "PortMapping" : null, - "Ports" : {} - }, - "ResolvConfPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/resolv.conf", - "HostnamePath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hostname", - "HostsPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hosts", - "Name" : "/test", - "Driver" : "aufs", - "ExecDriver" : "native-0.2", - "MountLabel" : "", - "ProcessLabel" : "", - "AppArmorProfile" : "", - "RestartCount" : 0, - "Volumes" : {}, - "VolumesRW" : {} - } - } - -Status Codes: - -- **200** – no error -- **404** – no such exec instance -- **500** - server error - -# 3. Going further - -## 3.1 Inside `docker run` - -As an example, the `docker run` command line makes the following API calls: - -- Create the container - -- If the status code is 404, it means the image doesn't exist: - - Try to pull it - - Then retry to create the container - -- Start the container - -- If you are not in detached mode: -- Attach to the container, using logs=1 (to have stdout and - stderr from the container's start) and stream=1 - -- If in detached mode or only stdin is attached: -- Display the container's id - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -stdout and stderr on the same socket. This might change in the future. - -## 3.3 CORS Requests - -To enable cross origin requests to the remote api add the flag -"--api-enable-cors" when running docker in daemon mode. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors diff --git a/docs/reference/api/docker_remote_api_v1.17.md b/docs/reference/api/docker_remote_api_v1.17.md deleted file mode 100644 index 147b05f89f..0000000000 --- a/docs/reference/api/docker_remote_api_v1.17.md +++ /dev/null @@ -1,2007 +0,0 @@ - - -# Docker Remote API v1.17 - -## 1. Brief introduction - - - The Remote API has replaced `rcli`. - - The daemon listens on `unix:///var/run/docker.sock` but you can - [Bind Docker to another host/port or a Unix socket](../../quickstart.md#bind-docker-to-another-host-port-or-a-unix-socket). - - The API tends to be REST, but for some complex commands, like `attach` - or `pull`, the HTTP connection is hijacked to transport `STDOUT`, - `STDIN` and `STDERR`. - -# 2. Endpoints - -## 2.1 Containers - -### List containers - -`GET /containers/json` - -List containers - -**Example request**: - - GET /containers/json?all=1&before=8dfafdbc3a40&size=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "8dfafdbc3a40", - "Names":["/boring_feynman"], - "Image": "ubuntu:latest", - "Command": "echo 1", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [{"PrivatePort": 2222, "PublicPort": 3333, "Type": "tcp"}], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "9cd87474be90", - "Names":["/coolName"], - "Image": "ubuntu:latest", - "Command": "echo 222222", - "Created": 1367854155, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - }, - { - "Id": "3176a2479c92", - "Names":["/sleepy_dog"], - "Image": "ubuntu:latest", - "Command": "echo 3333333333333333", - "Created": 1367854154, - "Status": "Exit 0", - "Ports":[], - "SizeRw":12288, - "SizeRootFs":0 - }, - { - "Id": "4cb07b47f9fb", - "Names":["/running_cat"], - "Image": "ubuntu:latest", - "Command": "echo 444444444444444444444444444444444", - "Created": 1367854152, - "Status": "Exit 0", - "Ports": [], - "SizeRw": 12288, - "SizeRootFs": 0 - } - ] - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, Show all containers. - Only running containers are shown by default (i.e., this defaults to false) -- **limit** – Show `limit` last created - containers, include non-running ones. -- **since** – Show only containers created since Id, include - non-running ones. -- **before** – Show only containers created before Id, include - non-running ones. -- **size** – 1/True/true or 0/False/false, Show the containers - sizes -- **filters** - a json encoded value of the filters (a map[string][]string) to process on the containers list. Available filters: - - exited=<int> -- containers with exit code of <int> - - status=(restarting|running|paused|exited) - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **500** – server error - -### Create a container - -`POST /containers/create` - -Create a container - -**Example request**: - - POST /containers/create HTTP/1.1 - Content-Type: application/json - - { - "Hostname": "", - "Domainname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": [ - "FOO=bar", - "BAZ=quux" - ], - "Cmd": [ - "date" - ], - "Entrypoint": "", - "Image": "ubuntu", - "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"}, - "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": [], - "SecurityOpt": [] - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id":"e90e34656806", - "Warnings":[] - } - -Json Parameters: - -- **Hostname** - A string value containing the desired hostname to use for the - container. -- **Domainname** - A string value containing the desired domain name to use - for the container. -- **User** - A string value containing the user to use inside the container. -- **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 - (ie. the relative weight vs other containers). - **CpuSet** - String value containing the cgroups Cpuset to use. -- **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"]]` -- **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 - container to empty objects. -- **WorkingDir** - A string value containing the working dir 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": { "/: {}" }` -- **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). - - **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 - work when using the `lxc` execution driver. - - **PortBindings** - A map of exposed container ports and the host port they - should map to. It should be specified in the form - `{ /: [{ "HostPort": "" }] }` - Take note that `port` is specified as a string and not an integer value. - - **PublishAllPorts** - Allocates a random host port for all of a container's - exposed ports. Specified as a boolean value. - - **Privileged** - Gives the container full access to the host. Specified as - a boolean value. - - **ReadonlyRootfs** - Mount the container's root filesystem as read only. - Specified as a boolean value. - - **Dns** - A list of dns servers for the container to use. - - **DnsSearch** - A list of DNS search domains - - **ExtraHosts** - A list of hostnames/IP mappings to be added 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 `[:]` - - **CapAdd** - A list of kernel capabilities to add to the container. - - **Capdrop** - A list of kernel capabilities to drop from the container. - - **RestartPolicy** – The behavior to apply when the container exits. The - value is an object with a `Name` property of either `"always"` to - always restart or `"on-failure"` to restart only when the container - exit code is non-zero. If `on-failure` is used, `MaximumRetryCount` - controls the number of times to retry before giving up. - The default is not to restart. (optional) - An ever increasing delay (double the previous delay, starting at 100mS) - is added before each restart to prevent flooding the server. - - **NetworkMode** - Sets the networking mode for the container. Supported - values are: `bridge`, `host`, `none`, and `container:` - - **Devices** - A list of devices to add to the container specified in the - form - `{ "PathOnHost": "/dev/deviceName", "PathInContainer": "/dev/deviceName", "CgroupPermissions": "mrw"}` - - **SecurityOpt**: A list of string values to customize labels for MLS - systems, such as SELinux. - -Query Parameters: - -- **name** – Assign the specified name to the container. Must - match `/?[a-zA-Z0-9_-]+`. - -Status Codes: - -- **201** – no error -- **404** – no such container -- **406** – impossible to attach (container not running) -- **500** – server error - -### Inspect a container - -`GET /containers/(id or name)/json` - -Return low-level information on the container `id` - - -**Example request**: - - GET /containers/4fa6e0f0c678/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "AppArmorProfile": "", - "Args": [ - "-c", - "exit 9" - ], - "Config": { - "AttachStderr": true, - "AttachStdin": false, - "AttachStdout": true, - "Cmd": [ - "/bin/sh", - "-c", - "exit 9" - ], - "CpuShares": 0, - "Cpuset": "", - "Domainname": "", - "Entrypoint": null, - "Env": [ - "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" - ], - "ExposedPorts": null, - "Hostname": "ba033ac44011", - "Image": "ubuntu", - "MacAddress": "", - "Memory": 0, - "MemorySwap": 0, - "NetworkDisabled": false, - "OnBuild": null, - "OpenStdin": false, - "PortSpecs": null, - "StdinOnce": false, - "Tty": false, - "User": "", - "Volumes": null, - "WorkingDir": "" - }, - "Created": "2015-01-06T15:47:31.485331387Z", - "Driver": "devicemapper", - "ExecDriver": "native-0.2", - "ExecIDs": null, - "HostConfig": { - "Binds": null, - "CapAdd": null, - "CapDrop": null, - "ContainerIDFile": "", - "Devices": [], - "Dns": null, - "DnsSearch": null, - "ExtraHosts": null, - "IpcMode": "", - "Links": null, - "LxcConf": [], - "NetworkMode": "bridge", - "PortBindings": {}, - "Privileged": false, - "ReadonlyRootfs": false, - "PublishAllPorts": false, - "RestartPolicy": { - "MaximumRetryCount": 2, - "Name": "on-failure" - }, - "SecurityOpt": null, - "VolumesFrom": null - }, - "HostnamePath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hostname", - "HostsPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/hosts", - "Id": "ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39", - "Image": "04c5d3b7b0656168630d3ba35d8889bd0e9caafcaeb3004d2bfbc47e7c5d35d2", - "MountLabel": "", - "Name": "/boring_euclid", - "NetworkSettings": { - "Bridge": "", - "Gateway": "", - "IPAddress": "", - "IPPrefixLen": 0, - "MacAddress": "", - "PortMapping": null, - "Ports": null - }, - "Path": "/bin/sh", - "ProcessLabel": "", - "ResolvConfPath": "/var/lib/docker/containers/ba033ac4401106a3b513bc9d639eee123ad78ca3616b921167cd74b20e25ed39/resolv.conf", - "RestartCount": 1, - "State": { - "Error": "", - "ExitCode": 9, - "FinishedAt": "2015-01-06T15:47:32.080254511Z", - "OOMKilled": false, - "Paused": false, - "Pid": 0, - "Restarting": false, - "Running": false, - "StartedAt": "2015-01-06T15:47:32.072697474Z" - }, - "Volumes": {}, - "VolumesRW": {} - } - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### List processes running inside a container - -`GET /containers/(id or name)/top` - -List processes running inside the container `id`. On Unix systems this -is done by running the `ps` command. This endpoint is not -supported on Windows. - -**Example request**: - - GET /containers/4fa6e0f0c678/top HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles" : [ - "UID", "PID", "PPID", "C", "STIME", "TTY", "TIME", "CMD" - ], - "Processes" : [ - [ - "root", "13642", "882", "0", "17:03", "pts/0", "00:00:00", "/bin/bash" - ], - [ - "root", "13735", "13642", "0", "17:06", "pts/0", "00:00:00", "sleep 10" - ] - ] - } - -**Example request**: - - GET /containers/4fa6e0f0c678/top?ps_args=aux HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Titles" : [ - "USER","PID","%CPU","%MEM","VSZ","RSS","TTY","STAT","START","TIME","COMMAND" - ] - "Processes" : [ - [ - "root","13642","0.0","0.1","18172","3184","pts/0","Ss","17:03","0:00","/bin/bash" - ], - [ - "root","13895","0.0","0.0","4348","692","pts/0","S+","17:15","0:00","sleep 10" - ] - ], - } - -Query Parameters: - -- **ps_args** – `ps` arguments to use (e.g., `aux`), defaults to `-ef` - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Get container logs - -`GET /containers/(id or name)/logs` - -Get stdout and stderr logs from the container ``id`` - -**Example request**: - - GET /containers/4fa6e0f0c678/logs?stderr=1&stdout=1×tamps=1&follow=1&tail=10 HTTP/1.1 - -**Example response**: - - HTTP/1.1 101 UPGRADED - Content-Type: application/vnd.docker.raw-stream - Connection: Upgrade - Upgrade: tcp - - {{ STREAM }} - -Query Parameters: - -- **follow** – 1/True/true or 0/False/false, return stream. Default false -- **stdout** – 1/True/true or 0/False/false, show stdout log. Default false -- **stderr** – 1/True/true or 0/False/false, show stderr log. Default false -- **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 ``. Default all - -Status Codes: - -- **101** – no error, hints proxy about hijacking -- **200** – no error, no upgrade header found -- **404** – no such container -- **500** – server error - -### Inspect changes on a container's filesystem - -`GET /containers/(id or name)/changes` - -Inspect changes on container `id`'s filesystem - -**Example request**: - - GET /containers/4fa6e0f0c678/changes HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Path": "/dev", - "Kind": 0 - }, - { - "Path": "/dev/kmsg", - "Kind": 1 - }, - { - "Path": "/test", - "Kind": 1 - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Export a container - -`GET /containers/(id or name)/export` - -Export the contents of container `id` - -**Example request**: - - GET /containers/4fa6e0f0c678/export HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Get container stats based on resource usage - -`GET /containers/(id or name)/stats` - -This endpoint returns a live stream of a container's resource usage statistics. - -**Example request**: - - GET /containers/redis1/stats HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "read" : "2015-01-08T22:57:31.547920715Z", - "network" : { - "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: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Resize a container TTY - -`POST /containers/(id or name)/resize?h=&w=` - -Resize the TTY for container with `id`. The container must be restarted for the resize to take effect. - -**Example request**: - - POST /containers/4fa6e0f0c678/resize?h=40&w=80 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Length: 0 - Content-Type: text/plain; charset=utf-8 - -Status Codes: - -- **200** – no error -- **404** – No such container -- **500** – Cannot resize container - -### Start a container - -`POST /containers/(id or name)/start` - -Start the container `id` - -> **Note**: -> For backwards compatibility, this endpoint accepts a `HostConfig` as JSON-encoded request body. -> See [create a container](#create-a-container) for details. - -**Example request**: - - POST /containers/e90e34656806/start HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **304** – container already started -- **404** – no such container -- **500** – server error - -### Stop a container - -`POST /containers/(id or name)/stop` - -Stop the container `id` - -**Example request**: - - POST /containers/e90e34656806/stop?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **304** – container already stopped -- **404** – no such container -- **500** – server error - -### Restart a container - -`POST /containers/(id or name)/restart` - -Restart the container `id` - -**Example request**: - - POST /containers/e90e34656806/restart?t=5 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **t** – number of seconds to wait before killing the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Kill a container - -`POST /containers/(id or name)/kill` - -Kill the container `id` - -**Example request**: - - POST /containers/e90e34656806/kill HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters - -- **signal** - Signal to send to the container: integer or string like "SIGINT". - When not set, SIGKILL is assumed and the call will waits for the container to exit. - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Rename a container - -`POST /containers/(id or name)/rename` - -Rename the container `id` to a `new_name` - -**Example request**: - - POST /containers/e90e34656806/rename?name=new_name HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **name** – new name for the container - -Status Codes: - -- **204** – no error -- **404** – no such container -- **409** - conflict name already assigned -- **500** – server error - -### Pause a container - -`POST /containers/(id or name)/pause` - -Pause the container `id` - -**Example request**: - - POST /containers/e90e34656806/pause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Unpause a container - -`POST /containers/(id or name)/unpause` - -Unpause the container `id` - -**Example request**: - - POST /containers/e90e34656806/unpause HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Status Codes: - -- **204** – no error -- **404** – no such container -- **500** – server error - -### Attach to a container - -`POST /containers/(id or name)/attach` - -Attach to the container `id` - -**Example request**: - - POST /containers/16253994b7c4/attach?logs=1&stream=0&stdout=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 101 UPGRADED - Content-Type: application/vnd.docker.raw-stream - Connection: Upgrade - Upgrade: tcp - - {{ STREAM }} - -Query Parameters: - -- **logs** – 1/True/true or 0/False/false, return logs. Default false -- **stream** – 1/True/true or 0/False/false, return stream. - Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach - to stdin. Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **101** – no error, hints proxy about hijacking -- **200** – no error, no upgrade header found -- **400** – bad parameter -- **404** – no such container -- **500** – server error - - **Stream details**: - - When using the TTY setting is enabled in - [`POST /containers/create` - ](#create-a-container), - the stream is the raw data from the process PTY and client's stdin. - When the TTY is disabled, then the stream is multiplexed to separate - stdout and stderr. - - The format is a **Header** and a **Payload** (frame). - - **HEADER** - - The header will contain the information on which stream write the - stream (stdout or stderr). It also contain the size of the - associated frame encoded on the last 4 bytes (uint32). - - It is encoded on the first 8 bytes like this: - - header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4} - - `STREAM_TYPE` can be: - -- 0: stdin (will be written on stdout) -- 1: stdout -- 2: stderr - - `SIZE1, SIZE2, SIZE3, SIZE4` are the 4 bytes of - the uint32 size encoded as big endian. - - **PAYLOAD** - - The payload is the raw stream. - - **IMPLEMENTATION** - - The simplest way to implement the Attach protocol is the following: - - 1. Read 8 bytes - 2. chose stdout or stderr depending on the first byte - 3. Extract the frame size from the last 4 bytes - 4. Read the extracted size and output it on the correct output - 5. Goto 1 - -### Attach to a container (websocket) - -`GET /containers/(id or name)/attach/ws` - -Attach to the container `id` via websocket - -Implements websocket protocol handshake according to [RFC 6455](http://tools.ietf.org/html/rfc6455) - -**Example request** - - GET /containers/e90e34656806/attach/ws?logs=0&stream=1&stdin=1&stdout=1&stderr=1 HTTP/1.1 - -**Example response** - - {{ STREAM }} - -Query Parameters: - -- **logs** – 1/True/true or 0/False/false, return logs. Default false -- **stream** – 1/True/true or 0/False/false, return stream. - Default false -- **stdin** – 1/True/true or 0/False/false, if stream=true, attach - to stdin. Default false -- **stdout** – 1/True/true or 0/False/false, if logs=true, return - stdout log, if stream=true, attach to stdout. Default false -- **stderr** – 1/True/true or 0/False/false, if logs=true, return - stderr log, if stream=true, attach to stderr. Default false - -Status Codes: - -- **200** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Wait a container - -`POST /containers/(id or name)/wait` - -Block until container `id` stops, then returns the exit code - -**Example request**: - - POST /containers/16253994b7c4/wait HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"StatusCode": 0} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -### Remove a container - -`DELETE /containers/(id or name)` - -Remove the container `id` from the filesystem - -**Example request**: - - DELETE /containers/16253994b7c4?v=1 HTTP/1.1 - -**Example response**: - - HTTP/1.1 204 No Content - -Query Parameters: - -- **v** – 1/True/true or 0/False/false, Remove the volumes - associated to the container. Default false -- **force** - 1/True/true or 0/False/false, Kill then remove the container. - Default false - -Status Codes: - -- **204** – no error -- **400** – bad parameter -- **404** – no such container -- **500** – server error - -### Copy files or folders from a container - -`POST /containers/(id or name)/copy` - -Copy files or folders of container `id` - -**Example request**: - - POST /containers/4fa6e0f0c678/copy HTTP/1.1 - Content-Type: application/json - - { - "Resource": "test.txt" - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - {{ TAR STREAM }} - -Status Codes: - -- **200** – no error -- **404** – no such container -- **500** – server error - -## 2.2 Images - -### List Images - -`GET /images/json` - -**Example request**: - - GET /images/json?all=0 HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "RepoTags": [ - "ubuntu:12.04", - "ubuntu:precise", - "ubuntu:latest" - ], - "Id": "8dbd9e392a964056420e5d58ca5cc376ef18e2de93b5cc90e868a1bbc8318c1c", - "Created": 1365714795, - "Size": 131506275, - "VirtualSize": 131506275 - }, - { - "RepoTags": [ - "ubuntu:12.10", - "ubuntu:quantal" - ], - "ParentId": "27cf784147099545", - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Created": 1364102658, - "Size": 24653, - "VirtualSize": 180116135 - } - ] - - -Query Parameters: - -- **all** – 1/True/true or 0/False/false, default false -- **filters** – a json encoded value of the filters (a map[string][]string) to process on the images list. Available filters: - - dangling=true -- **filter** - only return images with the specified name - -### Build image from a Dockerfile - -`POST /build` - -Build an image from a Dockerfile - -**Example request**: - - POST /build HTTP/1.1 - - {{ TAR STREAM }} - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"stream": "Step 1..."} - {"stream": "..."} - {"error": "Error...", "errorDetail": {"code": 123, "message": "Error..."}} - -The input stream must be a tar archive compressed with one of the -following algorithms: identity (no compression), gzip, bzip2, xz. - -The archive must include a build instructions file, typically called -`Dockerfile` at the root of the archive. The `dockerfile` parameter may be -used to specify a different build instructions file by having its value be -the path to the alternate build instructions file to use. - -The archive may include any number of other files, -which will be accessible in the build context (See the [*ADD build -command*](../../reference/builder.md#dockerbuilder)). - -Query Parameters: - -- **dockerfile** - path within the build context to the Dockerfile -- **t** – repository name (and optionally a tag) to be applied to - the resulting image in case of success -- **remote** – git or HTTP/HTTPS URI build source -- **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) - - Request Headers: - -- **Content-type** – should be set to `"application/tar"`. -- **X-Registry-Config** – base64-encoded ConfigFile object - -Status Codes: - -- **200** – no error -- **500** – server error - -### Create an image - -`POST /images/create` - -Create an image, either by pulling it from the registry or by importing it - -**Example request**: - - POST /images/create?fromImage=ubuntu HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pulling..."} - {"status": "Pulling", "progress": "1 B/ 100 B", "progressDetail": {"current": 1, "total": 100}} - {"error": "Invalid..."} - ... - - When using this endpoint to pull an image from the registry, the - `X-Registry-Auth` header can be used to include - a base64-encoded AuthConfig object. - -Query Parameters: - -- **fromImage** – name of the image to pull -- **fromSrc** – source to import. The value may be a URL from which the image - can be retrieved or `-` to read the image from the request body. -- **repo** – repository -- **tag** – tag - - Request Headers: - -- **X-Registry-Auth** – base64-encoded AuthConfig object - -Status Codes: - -- **200** – no error -- **500** – server error - - - -### Inspect an image - -`GET /images/(name)/json` - -Return low-level information on the image `name` - -**Example request**: - - GET /images/ubuntu/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Created": "2013-03-23T22:24:18.818426-07:00", - "Container": "3d67245a8d72ecf13f33dffac9f79dcdf70f75acb84d308770391510e0c23ad0", - "ContainerConfig": - { - "Hostname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "AttachStdin": false, - "AttachStdout": false, - "AttachStderr": false, - "PortSpecs": null, - "Tty": true, - "OpenStdin": true, - "StdinOnce": false, - "Env": null, - "Cmd": ["/bin/bash"], - "Dns": null, - "Image": "ubuntu", - "Volumes": null, - "VolumesFrom": "", - "WorkingDir": "" - }, - "Id": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc", - "Parent": "27cf784147099545", - "Size": 6824592 - } - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Get the history of an image - -`GET /images/(name)/history` - -Return the history of the image `name` - -**Example request**: - - GET /images/ubuntu/history HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "Id": "b750fe79269d", - "Created": 1364102658, - "CreatedBy": "/bin/bash" - }, - { - "Id": "27cf78414709", - "Created": 1364068391, - "CreatedBy": "" - } - ] - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Push an image on the registry - -`POST /images/(name)/push` - -Push the image `name` on the registry - -**Example request**: - - POST /images/test/push HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "Pushing..."} - {"status": "Pushing", "progress": "1/? (n/a)", "progressDetail": {"current": 1}}} - {"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. - -**Example request**: - - POST /images/registry.acme.com:5000/test/push HTTP/1.1 - - -Query Parameters: - -- **tag** – the tag to associate with the image on the registry, optional - -Request Headers: - -- **X-Registry-Auth** – include a base64-encoded AuthConfig - object. - -Status Codes: - -- **200** – no error -- **404** – no such image -- **500** – server error - -### Tag an image into a repository - -`POST /images/(name)/tag` - -Tag the image `name` into a repository - -**Example request**: - - POST /images/test/tag?repo=myrepo&force=0&tag=v42 HTTP/1.1 - -**Example response**: - - HTTP/1.1 201 Created - -Query Parameters: - -- **repo** – The repository to tag in -- **force** – 1/True/true or 0/False/false, default false -- **tag** - The new tag name - -Status Codes: - -- **201** – no error -- **400** – bad parameter -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Remove an image - -`DELETE /images/(name)` - -Remove the image `name` from the filesystem - -**Example request**: - - DELETE /images/test HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-type: application/json - - [ - {"Untagged": "3e2f21a89f"}, - {"Deleted": "3e2f21a89f"}, - {"Deleted": "53b4f83ac9"} - ] - -Query Parameters: - -- **force** – 1/True/true or 0/False/false, default false -- **noprune** – 1/True/true or 0/False/false, default false - -Status Codes: - -- **200** – no error -- **404** – no such image -- **409** – conflict -- **500** – server error - -### Search images - -`GET /images/search` - -Search for an image on [Docker Hub](https://hub.docker.com). - -> **Note**: -> The response keys have changed from API v1.6 to reflect the JSON -> sent by the registry server to the docker daemon's request. - -**Example request**: - - GET /images/search?term=sshd HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - [ - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "wma55/u1210sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "jdswinbank/sshd", - "star_count": 0 - }, - { - "description": "", - "is_official": false, - "is_automated": false, - "name": "vgauthier/sshd", - "star_count": 0 - } - ... - ] - -Query Parameters: - -- **term** – term to search - -Status Codes: - -- **200** – no error -- **500** – server error - -## 2.3 Misc - -### Check auth configuration - -`POST /auth` - -Get the default username and email - -**Example request**: - - POST /auth HTTP/1.1 - Content-Type: application/json - - { - "username":" hannibal", - "password: "xxxx", - "email": "hannibal@a-team.com", - "serveraddress": "https://index.docker.io/v1/" - } - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **204** – no error -- **500** – server error - -### Display system-wide information - -`GET /info` - -Display system-wide information - -**Example request**: - - GET /info HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "Containers":11, - "Images":16, - "Driver":"btrfs", - "DriverStatus": [[""]], - "ExecutionDriver":"native-0.1", - "KernelVersion":"3.12.0-1-amd64" - "NCPU":1, - "MemTotal":2099236864, - "Name":"prod-server-42", - "ID":"7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS", - "Debug":false, - "NFd": 11, - "NGoroutines":21, - "NEventsListener":0, - "InitPath":"/usr/bin/docker", - "InitSha1":"", - "IndexServerAddress":["https://index.docker.io/v1/"], - "MemoryLimit":true, - "SwapLimit":false, - "IPv4Forwarding":true, - "Labels":["storage=ssd"], - "DockerRootDir": "/var/lib/docker", - "OperatingSystem": "Boot2Docker", - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Show the docker version information - -`GET /version` - -Show the docker version information - -**Example request**: - - GET /version HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "ApiVersion": "1.12", - "Version": "0.2.2", - "GitCommit": "5a2a5cc+CHANGES", - "GoVersion": "go1.0.3" - } - -Status Codes: - -- **200** – no error -- **500** – server error - -### Ping the docker server - -`GET /_ping` - -Ping the docker server - -**Example request**: - - GET /_ping HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: text/plain - - OK - -Status Codes: - -- **200** - no error -- **500** - server error - -### Create a new image from a container's changes - -`POST /commit` - -Create a new image from a container's changes - -**Example request**: - - POST /commit?container=44c004db4b17&comment=message&repo=myrepo HTTP/1.1 - Content-Type: application/json - - { - "Hostname": "", - "Domainname": "", - "User": "", - "Memory": 0, - "MemorySwap": 0, - "CpuShares": 512, - "Cpuset": "0,1", - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "PortSpecs": null, - "Tty": false, - "OpenStdin": false, - "StdinOnce": false, - "Env": null, - "Cmd": [ - "date" - ], - "Volumes": { - "/tmp": {} - }, - "WorkingDir": "", - "NetworkDisabled": false, - "ExposedPorts": { - "22/tcp": {} - } - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - {"Id": "596069db4bf5"} - -Json Parameters: - -- **config** - the container's configuration - -Query Parameters: - -- **container** – source container -- **repo** – repository -- **tag** – tag -- **comment** – commit message -- **author** – author (e.g., "John Hannibal Smith - <[hannibal@a-team.com](mailto:hannibal%40a-team.com)>") - -Status Codes: - -- **201** – no error -- **404** – no such container -- **500** – server error - -### Monitor Docker's events - -`GET /events` - -Get container events from docker, either in real time via streaming, or via -polling (using since). - -Docker containers will report the following events: - - create, destroy, die, exec_create, exec_start, export, kill, oom, pause, restart, start, stop, unpause - -and Docker images will report: - - untag, delete - -**Example request**: - - GET /events?since=1374067924 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/json - - {"status": "create", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "start", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067924} - {"status": "stop", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067966} - {"status": "destroy", "id": "dfdf82bd3881","from": "ubuntu:latest", "time":1374067970} - -Query Parameters: - -- **since** – timestamp used for polling -- **until** – timestamp used for polling -- **filters** – a json encoded value of the filters (a map[string][]string) to process on the event list. Available filters: - - event=<string> -- event to filter - - image=<string> -- image to filter - - container=<string> -- container to filter - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images in a repository - -`GET /images/(name)/get` - -Get a tarball containing all images and metadata for the repository specified -by `name`. - -If `name` is a specific name and tag (e.g. ubuntu:latest), then only that image -(and its parents) are returned. If `name` is an image ID, similarly only that -image (and its parents) are returned, but with the exclusion of the -'repositories' file in the tarball, as there were no image names referenced. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/ubuntu/get - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Get a tarball containing all images. - -`GET /images/get` - -Get a tarball containing all images and metadata for one or more repositories. - -For each value of the `names` parameter: if it is a specific name and tag (e.g. -ubuntu:latest), then only that image (and its parents) are returned; if it is -an image ID, similarly only that image (and its parents) are returned and there -would be no names referenced in the 'repositories' file for this image ID. - -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - GET /images/get?names=myname%2Fmyapp%3Alatest&names=busybox - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/x-tar - - Binary data stream - -Status Codes: - -- **200** – no error -- **500** – server error - -### Load a tarball with a set of images and tags into docker - -`POST /images/load` - -Load a set of images and tags into the docker repository. -See the [image tarball format](#image-tarball-format) for more details. - -**Example request** - - POST /images/load - - Tarball in body - -**Example response**: - - HTTP/1.1 200 OK - -Status Codes: - -- **200** – no error -- **500** – server error - -### Image tarball format - -An image tarball contains one directory per image layer (named using its long ID), -each containing three files: - -1. `VERSION`: currently `1.0` - the file format version -2. `json`: detailed layer information, similar to `docker inspect layer_id` -3. `layer.tar`: A tarfile containing the filesystem changes in this layer - -The `layer.tar` file will contain `aufs` style `.wh..wh.aufs` files and directories -for storing attribute changes and deletions. - -If the tarball defines a repository, there will also be a `repositories` file at -the root that contains a list of repository and tag names mapped to layer IDs. - -``` -{"hello-world": - {"latest": "565a9d68a73f6706862bfe8409a7f659776d4d60a8d096eb4a3cbce6999cc2a1"} -} -``` - -### Exec Create - -`POST /containers/(id or name)/exec` - -Sets up an exec instance in a running container `id` - -**Example request**: - - POST /containers/e90e34656806/exec HTTP/1.1 - Content-Type: application/json - - { - "AttachStdin": false, - "AttachStdout": true, - "AttachStderr": true, - "Tty": false, - "Cmd": [ - "date" - ], - } - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "Id": "f90e34656806" - } - -Json Parameters: - -- **AttachStdin** - Boolean value, attaches to stdin of the exec command. -- **AttachStdout** - Boolean value, attaches to stdout of the exec command. -- **AttachStderr** - Boolean value, attaches to stderr of the exec command. -- **Tty** - Boolean value to allocate a pseudo-TTY -- **Cmd** - Command to run specified as a string or an array of strings. - - -Status Codes: - -- **201** – no error -- **404** – no such container - -### Exec Start - -`POST /exec/(id)/start` - -Starts a previously set up exec instance `id`. If `detach` is true, this API -returns after starting the `exec` command. Otherwise, this API sets up an -interactive session with the `exec` command. - -**Example request**: - - POST /exec/e90e34656806/start HTTP/1.1 - Content-Type: application/json - - { - "Detach": false, - "Tty": false, - } - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: application/vnd.docker.raw-stream - - {{ STREAM }} - -Json Parameters: - -- **Detach** - Detach from the exec command -- **Tty** - Boolean value to allocate a pseudo-TTY - -Status Codes: - -- **200** – no error -- **404** – no such exec instance - - **Stream details**: - Similar to the stream behavior of `POST /containers/(id or name)/attach` API - -### Exec Resize - -`POST /exec/(id)/resize` - -Resizes the tty session used by the exec command `id`. -This API is valid only if `tty` was specified as part of creating and starting the exec command. - -**Example request**: - - POST /exec/e90e34656806/resize HTTP/1.1 - Content-Type: text/plain - -**Example response**: - - HTTP/1.1 201 Created - Content-Type: text/plain - -Query Parameters: - -- **h** – height of tty session -- **w** – width - -Status Codes: - -- **201** – no error -- **404** – no such exec instance - -### Exec Inspect - -`GET /exec/(id)/json` - -Return low-level information about the exec command `id`. - -**Example request**: - - GET /exec/11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39/json HTTP/1.1 - -**Example response**: - - HTTP/1.1 200 OK - Content-Type: plain/text - - { - "ID" : "11fb006128e8ceb3942e7c58d77750f24210e35f879dd204ac975c184b820b39", - "Running" : false, - "ExitCode" : 2, - "ProcessConfig" : { - "privileged" : false, - "user" : "", - "tty" : false, - "entrypoint" : "sh", - "arguments" : [ - "-c", - "exit 2" - ] - }, - "OpenStdin" : false, - "OpenStderr" : false, - "OpenStdout" : false, - "Container" : { - "State" : { - "Running" : true, - "Paused" : false, - "Restarting" : false, - "OOMKilled" : false, - "Pid" : 3650, - "ExitCode" : 0, - "Error" : "", - "StartedAt" : "2014-11-17T22:26:03.717657531Z", - "FinishedAt" : "0001-01-01T00:00:00Z" - }, - "ID" : "8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c", - "Created" : "2014-11-17T22:26:03.626304998Z", - "Path" : "date", - "Args" : [], - "Config" : { - "Hostname" : "8f177a186b97", - "Domainname" : "", - "User" : "", - "Memory" : 0, - "MemorySwap" : 0, - "CpuShares" : 0, - "Cpuset" : "", - "AttachStdin" : false, - "AttachStdout" : false, - "AttachStderr" : false, - "PortSpecs" : null, - "ExposedPorts" : null, - "Tty" : false, - "OpenStdin" : false, - "StdinOnce" : false, - "Env" : [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" ], - "Cmd" : [ - "date" - ], - "Image" : "ubuntu", - "Volumes" : null, - "WorkingDir" : "", - "Entrypoint" : null, - "NetworkDisabled" : false, - "MacAddress" : "", - "OnBuild" : null, - "SecurityOpt" : null - }, - "Image" : "5506de2b643be1e6febbf3b8a240760c6843244c41e12aa2f60ccbb7153d17f5", - "NetworkSettings" : { - "IPAddress" : "172.17.0.2", - "IPPrefixLen" : 16, - "MacAddress" : "02:42:ac:11:00:02", - "Gateway" : "172.17.42.1", - "Bridge" : "docker0", - "PortMapping" : null, - "Ports" : {} - }, - "ResolvConfPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/resolv.conf", - "HostnamePath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hostname", - "HostsPath" : "/var/lib/docker/containers/8f177a186b977fb451136e0fdf182abff5599a08b3c7f6ef0d36a55aaf89634c/hosts", - "Name" : "/test", - "Driver" : "aufs", - "ExecDriver" : "native-0.2", - "MountLabel" : "", - "ProcessLabel" : "", - "AppArmorProfile" : "", - "RestartCount" : 0, - "Volumes" : {}, - "VolumesRW" : {} - } - } - -Status Codes: - -- **200** – no error -- **404** – no such exec instance -- **500** - server error - -# 3. Going further - -## 3.1 Inside `docker run` - -As an example, the `docker run` command line makes the following API calls: - -- Create the container - -- If the status code is 404, it means the image doesn't exist: - - Try to pull it - - Then retry to create the container - -- Start the container - -- If you are not in detached mode: -- Attach to the container, using logs=1 (to have stdout and - stderr from the container's start) and stream=1 - -- If in detached mode or only stdin is attached: -- Display the container's id - -## 3.2 Hijacking - -In this version of the API, /attach, uses hijacking to transport stdin, -stdout and stderr on the same socket. - -To hint potential proxies about connection hijacking, Docker client sends -connection upgrade headers similarly to websocket. - - Upgrade: tcp - Connection: Upgrade - -When Docker daemon detects the `Upgrade` header, it will switch its status code -from **200 OK** to **101 UPGRADED** and resend the same headers. - -This might change in the future. - -## 3.3 CORS Requests - -To set cross origin requests to the remote api, please add flag "--api-enable-cors" -when running docker in daemon mode. - - $ docker -d -H="192.168.1.9:2375" --api-enable-cors From ae4c7b14938b70eb224f6620fc084049585409c3 Mon Sep 17 00:00:00 2001 From: Jared Hocutt Date: Tue, 19 Apr 2016 11:05:05 -0400 Subject: [PATCH 13/25] Add the NetApp Docker Volume Plugin to the documentation Signed-off-by: Jared Hocutt (cherry picked from commit f310fd14a9a99362635198cd5b1517a053813c92) Signed-off-by: Sebastiaan van Stijn --- docs/extend/plugins.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/extend/plugins.md b/docs/extend/plugins.md index da46a16ed7..df3e9e48f4 100644 --- a/docs/extend/plugins.md +++ b/docs/extend/plugins.md @@ -104,6 +104,12 @@ The following plugins exist: a mountpoint anywhere on the host, which enables the files to *always persist*, even if the volume is removed via `docker volume rm`. +* The [NetApp Plugin](https://github.com/NetApp/netappdvp) (nDVP) provides + direct integration with the Docker ecosystem for the NetApp storage portfolio. + The nDVP package supports the provisioning and management of + storage resources from the storage platform to Docker hosts, with a robust + framework for adding additional platforms in the future. + ## Troubleshooting a plugin If you are having problems with Docker after loading a plugin, ask the authors From 53b4fd1d816f69afd2dd0337934c412c88ed0d53 Mon Sep 17 00:00:00 2001 From: Wen Cheng Ma Date: Wed, 20 Apr 2016 11:14:47 +0800 Subject: [PATCH 14/25] Fix asa Signed-off-by: Wen Cheng Ma (cherry picked from commit 6d4e7b67be77e3f290d4048c3da5d0f6540f1704) Signed-off-by: Sebastiaan van Stijn --- docs/extend/plugins_network.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/extend/plugins_network.md b/docs/extend/plugins_network.md index ac07273219..aad01ba29a 100644 --- a/docs/extend/plugins_network.md +++ b/docs/extend/plugins_network.md @@ -13,7 +13,7 @@ parent = "engine_extend" Docker Engine network plugins enable Engine deployments to be extended to support a wide range of networking technologies, such as VXLAN, IPVLAN, MACVLAN or something completely different. Network driver plugins are supported via the -LibNetwork project. Each plugin is implemented asa "remote driver" for +LibNetwork project. Each plugin is implemented as a "remote driver" for LibNetwork, which shares plugin infrastructure with Engine. Effectively, network driver plugins are activated in the same way as other plugins, and use the same kind of protocol. From ac9b38b60daee5f266f8912db694e8cb75e63f86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A1ximo=20Cuadros?= Date: Thu, 31 Mar 2016 15:14:42 +0200 Subject: [PATCH 15/25] documentation: adding gce-docker plugin to plugins.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Máximo Cuadros (cherry picked from commit c018018b69771ce1becc71d82e2f912ad55dcde5) Signed-off-by: Sebastiaan van Stijn --- docs/extend/plugins.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/extend/plugins.md b/docs/extend/plugins.md index df3e9e48f4..9c6854ef84 100644 --- a/docs/extend/plugins.md +++ b/docs/extend/plugins.md @@ -68,6 +68,8 @@ The following plugins exist: * The [Netshare plugin](https://github.com/gondor/docker-volume-netshare) is a volume plugin that provides volume management for NFS 3/4, AWS EFS and CIFS file systems. +* The [gce-docker plugin](https://github.com/mcuadros/gce-docker) is a volume plugin able to attach, format and mount Google Compute [persistent-disks](https://cloud.google.com/compute/docs/disks/persistent-disks). + * The [OpenStorage Plugin](https://github.com/libopenstorage/openstorage) is a cluster aware volume plugin that provides volume management for file and block storage solutions. It implements a vendor neutral specification for implementing extensions such as CoS, encryption, and snapshots. It has example drivers based on FUSE, NFS, NBD and EBS to name a few. * The [Quobyte Volume Plugin](https://github.com/quobyte/docker-volume) connects Docker to [Quobyte](http://www.quobyte.com/containers)'s data center file system, a general-purpose scalable and fault-tolerant storage platform. From 21223f8873845cfdf255f2ac58c58d7cfc3cfffa Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 20 Apr 2016 13:43:33 +0200 Subject: [PATCH 16/25] docs: use tables for available plugins Signed-off-by: Sebastiaan van Stijn (cherry picked from commit 79351caec1b413c9da1080fceff49eb994323734) Signed-off-by: Sebastiaan van Stijn --- docs/extend/plugins.md | 102 +++++++++++------------------------------ 1 file changed, 28 insertions(+), 74 deletions(-) diff --git a/docs/extend/plugins.md b/docs/extend/plugins.md index 9c6854ef84..7eec419c97 100644 --- a/docs/extend/plugins.md +++ b/docs/extend/plugins.md @@ -31,86 +31,40 @@ Follow the instructions in the plugin's documentation. ## Finding a plugin -The following plugins exist: +The sections below provide an inexhaustive overview of available plugins. -* The [Blockbridge plugin](https://github.com/blockbridge/blockbridge-docker-volume) - is a volume plugin that provides access to an extensible set of - container-based persistent storage options. It supports single and multi-host Docker - environments with features that include tenant isolation, automated - provisioning, encryption, secure deletion, snapshots and QoS. + -* The [Convoy plugin](https://github.com/rancher/convoy) is a volume plugin for a - variety of storage back-ends including device mapper and NFS. It's a simple standalone - executable written in Go and provides the framework to support vendor-specific extensions - such as snapshots, backups and restore. +### Network plugins -* The [Flocker plugin](https://clusterhq.com/docker-plugin/) is a volume plugin - which provides multi-host portable volumes for Docker, enabling you to run - databases and other stateful containers and move them around across a cluster - of machines. +Plugin | Description +----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- +[Contiv Networking](https://github.com/contiv/netplugin) | An open source network plugin to provide infrastructure and security policies for a multi-tenant micro services deployment, while providing an integration to physical network for non-container workload. Contiv Networking implements the remote driver and IPAM APIs available in Docker 1.9 onwards. +[Kuryr Network Plugin](https://github.com/openstack/kuryr) | A network plugin is developed as part of the OpenStack Kuryr project and implements the Docker networking (libnetwork) remote driver API by utilizing Neutron, the OpenStack networking service. It includes an IPAM driver as well. +[Weave Network Plugin](http://docs.weave.works/weave/latest_release/plugin.html) | A network plugin that creates a virtual network that connects your Docker containers - across multiple hosts or clouds and enables automatic discovery of applications. Weave networks are resilient, partition tolerant, secure and work in partially connected networks, and other adverse environments - all configured with delightful simplicity. -* The [GlusterFS plugin](https://github.com/calavera/docker-volume-glusterfs) is - another volume plugin that provides multi-host volumes management for Docker - using GlusterFS. +### Volume plugins -* The [Horcrux Volume Plugin](https://github.com/muthu-r/horcrux) allows on-demand, - version controlled access to your data. Horcrux is an open-source plugin, - written in Go, and supports SCP, [Minio](https://www.minio.io) and Amazon S3. +Plugin | Description +----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- +[Blockbridge plugin](https://github.com/blockbridge/blockbridge-docker-volume) | A volume plugin that provides access to an extensible set of container-based persistent storage options. It supports single and multi-host Docker environments with features that include tenant isolation, automated provisioning, encryption, secure deletion, snapshots and QoS. +[Contiv Volume Plugin](https://github.com/contiv/volplugin) | An open source volume plugin that provides multi-tenant, persistent, distributed storage with intent based consumption using ceph underneath. +[Convoy plugin](https://github.com/rancher/convoy) | A volume plugin for a variety of storage back-ends including device mapper and NFS. It's a simple standalone executable written in Go and provides the framework to support vendor-specific extensions such as snapshots, backups and restore. +[Flocker plugin](https://clusterhq.com/docker-plugin/) | A volume plugin that provides multi-host portable volumes for Docker, enabling you to run databases and other stateful containers and move them around across a cluster of machines. +[gce-docker plugin](https://github.com/mcuadros/gce-docker) | A volume plugin able to attach, format and mount Google Compute [persistent-disks](https://cloud.google.com/compute/docs/disks/persistent-disks). +[GlusterFS plugin](https://github.com/calavera/docker-volume-glusterfs) | A volume plugin that provides multi-host volumes management for Docker using GlusterFS. +[Horcrux Volume Plugin](https://github.com/muthu-r/horcrux) | A volume plugin that allows on-demand, version controlled access to your data. Horcrux is an open-source plugin, written in Go, and supports SCP, [Minio](https://www.minio.io) and Amazon S3. +[IPFS Volume Plugin](http://github.com/vdemeester/docker-volume-ipfs) | An open source volume plugin that allows using an [ipfs](https://ipfs.io/) filesystem as a volume. +[Keywhiz plugin](https://github.com/calavera/docker-volume-keywhiz) | A plugin that provides credentials and secret management using Keywhiz as a central repository. +[Local Persist Plugin](https://github.com/CWSpear/local-persist) | A volume plugin that extends the default `local` driver's functionality by allowing you specify a mountpoint anywhere on the host, which enables the files to *always persist*, even if the volume is removed via `docker volume rm`. +[NetApp Plugin](https://github.com/NetApp/netappdvp) (nDVP) | A volume plugin that provides direct integration with the Docker ecosystem for the NetApp storage portfolio. The nDVP package supports the provisioning and management of storage resources from the storage platform to Docker hosts, with a robust framework for adding additional platforms in the future. +[Netshare plugin](https://github.com/gondor/docker-volume-netshare) | A volume plugin that provides volume management for NFS 3/4, AWS EFS and CIFS file systems. +[OpenStorage Plugin](https://github.com/libopenstorage/openstorage) | A cluster-aware volume plugin that provides volume management for file and block storage solutions. It implements a vendor neutral specification for implementing extensions such as CoS, encryption, and snapshots. It has example drivers based on FUSE, NFS, NBD and EBS to name a few. +[Quobyte Volume Plugin](https://github.com/quobyte/docker-volume) | A volume plugin that connects Docker to [Quobyte](http://www.quobyte.com/containers)'s data center file system, a general-purpose scalable and fault-tolerant storage platform. +[REX-Ray plugin](https://github.com/emccode/rexray) | A volume plugin which is written in Go and provides advanced storage functionality for many platforms including VirtualBox, EC2, Google Compute Engine, OpenStack, and EMC. -* The [IPFS Volume Plugin](http://github.com/vdemeester/docker-volume-ipfs) - is an open source volume plugin that allows using an - [ipfs](https://ipfs.io/) filesystem as a volume. - -* The [Keywhiz plugin](https://github.com/calavera/docker-volume-keywhiz) is - a plugin that provides credentials and secret management using Keywhiz as - a central repository. - -* The [Netshare plugin](https://github.com/gondor/docker-volume-netshare) is a volume plugin - that provides volume management for NFS 3/4, AWS EFS and CIFS file systems. - -* The [gce-docker plugin](https://github.com/mcuadros/gce-docker) is a volume plugin able to attach, format and mount Google Compute [persistent-disks](https://cloud.google.com/compute/docs/disks/persistent-disks). - -* The [OpenStorage Plugin](https://github.com/libopenstorage/openstorage) is a cluster aware volume plugin that provides volume management for file and block storage solutions. It implements a vendor neutral specification for implementing extensions such as CoS, encryption, and snapshots. It has example drivers based on FUSE, NFS, NBD and EBS to name a few. - -* The [Quobyte Volume Plugin](https://github.com/quobyte/docker-volume) connects Docker to [Quobyte](http://www.quobyte.com/containers)'s data center file system, a general-purpose scalable and fault-tolerant storage platform. - -* The [REX-Ray plugin](https://github.com/emccode/rexray) is a volume plugin - which is written in Go and provides advanced storage functionality for many - platforms including VirtualBox, EC2, Google Compute Engine, OpenStack, and EMC. - -* The [Contiv Volume Plugin](https://github.com/contiv/volplugin) is an open - source volume plugin that provides multi-tenant, persistent, distributed storage - with intent based consumption using ceph underneath. - -* The [Contiv Networking](https://github.com/contiv/netplugin) is an open source - libnetwork plugin to provide infrastructure and security policies for a - multi-tenant micro services deployment, while providing an integration to - physical network for non-container workload. Contiv Networking implements the - remote driver and IPAM APIs available in Docker 1.9 onwards. - -* The [Weave Network Plugin](http://docs.weave.works/weave/latest_release/plugin.html) - creates a virtual network that connects your Docker containers - - across multiple hosts or clouds and enables automatic discovery of - applications. Weave networks are resilient, partition tolerant, - secure and work in partially connected networks, and other adverse - environments - all configured with delightful simplicity. - -* The [Kuryr Network Plugin](https://github.com/openstack/kuryr) is - developed as part of the OpenStack Kuryr project and implements the - Docker networking (libnetwork) remote driver API by utilizing - Neutron, the OpenStack networking service. It includes an IPAM - driver as well. - -* The [Local Persist Plugin](https://github.com/CWSpear/local-persist) - extends the default `local` driver's functionality by allowing you specify - a mountpoint anywhere on the host, which enables the files to *always persist*, - even if the volume is removed via `docker volume rm`. - -* The [NetApp Plugin](https://github.com/NetApp/netappdvp) (nDVP) provides - direct integration with the Docker ecosystem for the NetApp storage portfolio. - The nDVP package supports the provisioning and management of - storage resources from the storage platform to Docker hosts, with a robust - framework for adding additional platforms in the future. ## Troubleshooting a plugin From 895569df9dacc8116c67f604d261020fc8b01a54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=90=8F=E9=80=9A?= Date: Thu, 21 Apr 2016 09:34:28 +0800 Subject: [PATCH 17/25] optimise docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 搏通 (cherry picked from commit 9abf304c255cb3194b932e92f2b87bfabaab88c9) Signed-off-by: Sebastiaan van Stijn --- docs/userguide/networking/dockernetworks.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/userguide/networking/dockernetworks.md b/docs/userguide/networking/dockernetworks.md index dd84872693..465470e737 100644 --- a/docs/userguide/networking/dockernetworks.md +++ b/docs/userguide/networking/dockernetworks.md @@ -138,7 +138,7 @@ $ docker run -itd --name=container2 busybox 94447ca479852d29aeddca75c28f7104df3c3196d7b6d83061879e339946805c ``` -Inspecting the `bridge` network again after starting two containers shows both newly launched containers in the network. Their ids show up in the container +Inspecting the `bridge` network again after starting two containers shows both newly launched containers in the network. Their ids show up in the "Containers" section of `docker network inspect`: ``` $ docker network inspect bridge From 84314e09aba69c107cd9435d50b81f083bc5b1cf Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 20 Apr 2016 16:45:43 +0200 Subject: [PATCH 18/25] docs: add note about MAC addresses not being unique Signed-off-by: Sebastiaan van Stijn (cherry picked from commit 763aceeb733cdd927eb2de6232f0257267b6f71e) Signed-off-by: Sebastiaan van Stijn --- docs/reference/run.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index b37dd5ae80..f885e56d8c 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -291,7 +291,8 @@ you can override this with `--dns`. By default, the MAC address is generated using the IP address allocated to the container. You can set the container's MAC address explicitly by providing a -MAC address via the `--mac-address` parameter (format:`12:34:56:78:9a:bc`). +MAC address via the `--mac-address` parameter (format:`12:34:56:78:9a:bc`).Be +aware that Docker does not check if manually specified MAC addresses are unique. Supported networks : From fc4f927588ea67315fc3b607a6dc672de19b36e2 Mon Sep 17 00:00:00 2001 From: "Kai Qiang Wu(Kennan)" Date: Thu, 21 Apr 2016 03:24:10 +0000 Subject: [PATCH 19/25] Fix the old exit status example Signed-off-by: Kai Qiang Wu(Kennan) (cherry picked from commit 896ebb1ca2a6ae23d7511678aaab1d4e32c54ff9) Signed-off-by: Sebastiaan van Stijn --- docs/reference/run.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index f885e56d8c..11503b2a8e 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -563,20 +563,18 @@ the exit codes follow the `chroot` standard, see below: **_126_** if the **_contained command_** cannot be invoked $ docker run busybox /etc; echo $? - # exec: "/etc": permission denied - docker: Error response from daemon: Contained command could not be invoked + # docker: Error response from daemon: Container command '/etc' could not be invoked. 126 **_127_** if the **_contained command_** cannot be found $ docker run busybox foo; echo $? - # exec: "foo": executable file not found in $PATH - docker: Error response from daemon: Contained command not found or does not exist + # docker: Error response from daemon: Container command 'foo' not found or does not exist. 127 **_Exit code_** of **_contained command_** otherwise - $ docker run busybox /bin/sh -c 'exit 3' + $ docker run busybox /bin/sh -c 'exit 3'; echo $? # 3 ## Clean up (--rm) From f264a73afdf886d9b74ed65f46dd56dd512cda04 Mon Sep 17 00:00:00 2001 From: Dimitry Andric Date: Wed, 20 Apr 2016 17:30:44 +0200 Subject: [PATCH 20/25] The daemon.json storage-opts settings is actually a list. Signed-off-by: Dimitry Andric (cherry picked from commit e3eb24fc21fa6f6002eef081278333f9e5e16614) Signed-off-by: Sebastiaan van Stijn --- docs/reference/commandline/daemon.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/commandline/daemon.md b/docs/reference/commandline/daemon.md index 796a04c3fd..36df746501 100644 --- a/docs/reference/commandline/daemon.md +++ b/docs/reference/commandline/daemon.md @@ -888,7 +888,7 @@ This is a full example of the allowed configuration options in the file: "exec-opts": [], "exec-root": "", "storage-driver": "", - "storage-opts": "", + "storage-opts": [], "labels": [], "log-driver": "", "log-opts": [], From 5b1136ba8de44928626eacebd6f9d5e326ceb963 Mon Sep 17 00:00:00 2001 From: Riyaz Faizullabhoy Date: Wed, 20 Apr 2016 23:05:44 -0700 Subject: [PATCH 21/25] Update DCT docs with 1.11 info, fix typos Signed-off-by: Riyaz Faizullabhoy (cherry picked from commit 77da3bcb72ba4f936c428cb2b912c007a94cb87a) Signed-off-by: Sebastiaan van Stijn --- docs/security/trust/content_trust.md | 21 +++++++++------------ docs/security/trust/deploying_notary.md | 2 +- docs/security/trust/trust_automation.md | 4 ++-- docs/security/trust/trust_delegation.md | 4 ++-- docs/security/trust/trust_key_mng.md | 12 +++++++++++- 5 files changed, 25 insertions(+), 18 deletions(-) diff --git a/docs/security/trust/content_trust.md b/docs/security/trust/content_trust.md index f11e4e6ef7..98b06fdd77 100644 --- a/docs/security/trust/content_trust.md +++ b/docs/security/trust/content_trust.md @@ -13,15 +13,11 @@ weight=-1 When transferring data among networked systems, *trust* is a central concern. In particular, when communicating over an untrusted medium such as the internet, it -is critical to ensure the integrity and publisher of all the data a system -operates on. You use Docker to push and pull images (data) to a registry. Content trust -gives you the ability to both verify the integrity and the publisher of all the +is critical to ensure the integrity and the publisher of all the data a system +operates on. You use Docker Engine to push and pull images (data) to a public or private registry. Content trust +gives you the ability to verify both the integrity and the publisher of all the data received from a registry over any channel. -Content trust is currently only available for users of the public Docker Hub. It -is currently not available for the Docker Trusted Registry or for private -registries. - ## Understand trust in Docker Content trust allows operations with a remote Docker registry to enforce @@ -82,7 +78,7 @@ desirable, unsigned image tags are "invisible" to them. ![Trust view](images/trust_view.png) -To the consumer who does not enabled content trust, nothing about how they +To the consumer who has not enabled content trust, nothing about how they work with Docker images changes. Every image is visible regardless of whether it is signed or not. @@ -127,7 +123,7 @@ The following image depicts the various signing keys and their relationships: >tag from this repository prior to the loss. You should backup the root key somewhere safe. Given that it is only required -to create new repositories, it is a good idea to store it offline. +to create new repositories, it is a good idea to store it offline in hardware. For details on securing, and backing up your keys, make sure you read how to [manage keys for content trust](trust_key_mng.md). @@ -198,11 +194,12 @@ When you push your first tagged image with content trust enabled, the `docker` client recognizes this is your first push and: - alerts you that it will create a new root key - - requests a passphrase for the key + - requests a passphrase for the root key - generates a root key in the `~/.docker/trust` directory + - requests a passphrase for the repository key - generates a repository key for in the `~/.docker/trust` directory -The passphrase you chose for both the root key and your content key-pair +The passphrase you chose for both the root key and your repository key-pair should be randomly generated and stored in a *password manager*. > **NOTE**: If you omit the `latest` tag, content trust is skipped. This is true @@ -267,7 +264,7 @@ Because the tag `docker/cliffs:latest` is not trusted, the `pull` fails. ### Disable content trust for specific operations -A user that wants to disable content trust for a particular operation can use the +A user who wants to disable content trust for a particular operation can use the `--disable-content-trust` flag. **Warning: this flag disables content trust for this operation**. With this flag, Docker will ignore content-trust and allow all operations to be done without verifying any signatures. If we wanted the diff --git a/docs/security/trust/deploying_notary.md b/docs/security/trust/deploying_notary.md index 68e57fb794..9da685f42e 100644 --- a/docs/security/trust/deploying_notary.md +++ b/docs/security/trust/deploying_notary.md @@ -21,7 +21,7 @@ The easiest way to deploy Notary Server is by using Docker Compose. To follow th docker-compose up -d - For more detailed documentation about how to deploy Notary Server see https://github.com/docker/notary. + For more detailed documentation about how to deploy Notary Server see the [instructions to run a Notary service](/notary/running_a_service.md) as well as https://github.com/docker/notary for more information. 3. Make sure that your Docker or Notary client trusts Notary Server's certificate before you try to interact with the Notary server. See the instructions for [Docker](../../reference/commandline/cli.md#notary) or diff --git a/docs/security/trust/trust_automation.md b/docs/security/trust/trust_automation.md index 1b3d4564f0..74c17f5cfb 100644 --- a/docs/security/trust/trust_automation.md +++ b/docs/security/trust/trust_automation.md @@ -10,7 +10,7 @@ parent= "smn_content_trust" # Automation with content trust -Your automation systems that pull or build images can also work with trust. Any automation environment must set `DOCKER_TRUST_ENABLED` either manually or in in a scripted fashion before processing images. +Your automation systems that pull or build images can also work with trust. Any automation environment must set `DOCKER_TRUST_ENABLED` either manually or in a scripted fashion before processing images. ## Bypass requests for passphrases @@ -43,7 +43,7 @@ Signing and pushing trust metadata ## Building with content trust -You can also build with content trust. Before running the `docker build` command, you should set the environment variable `DOCKER_CONTENT_TRUST` either manually or in in a scripted fashion. Consider the simple Dockerfile below. +You can also build with content trust. Before running the `docker build` command, you should set the environment variable `DOCKER_CONTENT_TRUST` either manually or in a scripted fashion. Consider the simple Dockerfile below. ```Dockerfile FROM docker/trusttest:latest diff --git a/docs/security/trust/trust_delegation.md b/docs/security/trust/trust_delegation.md index ac803bc9f1..050d14e67e 100644 --- a/docs/security/trust/trust_delegation.md +++ b/docs/security/trust/trust_delegation.md @@ -18,7 +18,7 @@ sharing your repository key (a combination of your targets and snapshot keys - please see "[Manage keys for content trust](trust_key_mng.md)" for more information). A collaborator can keep their own delegation key private. -The `targest/releases` delegation is currently an optional feature - in order +The `targets/releases` delegation is currently an optional feature - in order to set up delegations, you must use the Notary CLI: 1. [Download the client](https://github.com/docker/notary/releases) and ensure that it is @@ -40,7 +40,7 @@ available on your path For more detailed information about how to use Notary outside of the default Docker Content Trust use cases, please refer to the -[the Notary CLI documentation](https://docs.docker.com/notary/getting_started/). +[the Notary CLI documentation](/notary/getting_started.md). Note that when publishing and listing delegation changes using the Notary client, your Docker Hub credentials are required. diff --git a/docs/security/trust/trust_key_mng.md b/docs/security/trust/trust_key_mng.md index c15b84bacc..b74feadebf 100644 --- a/docs/security/trust/trust_key_mng.md +++ b/docs/security/trust/trust_key_mng.md @@ -37,7 +37,7 @@ workflow. They need to be Note: Prior to Docker Engine 1.11, the snapshot key was also generated and stored locally client-side. [Use the Notary CLI to manage your snapshot key locally -again](https://docs.docker.com/notary/advanced_usage/#rotate-keys) for +again](/notary/advanced_usage.md#rotate-keys) for repositories created with newer versions of Docker. ## Choosing a passphrase @@ -64,6 +64,16 @@ Before backing them up, you should `tar` them into an archive: $ umask 077; tar -zcvf private_keys_backup.tar.gz ~/.docker/trust/private; umask 022 ``` +## Hardware storage and signing + +Docker Content Trust can store and sign with root keys from a Yubikey 4. The +Yubikey is prioritized over keys stored in the filesystem. When you initialize a +new repository with content trust, Docker Engine looks for a root key locally. If a +key is not found and the Yubikey 4 exists, Docker Engine creates a root key in the +Yubikey 4. Please consult the [Notary documentation](/notary/advanced_usage.md#use-a-yubikey) for more details. + +Prior to Docker Engine 1.11, this feature was only in the experimental branch. + ## Lost keys If a publisher loses keys it means losing the ability to sign trusted content for From 4bf3f74126e2dec74263bca7d2faa8f12437b835 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Mon, 25 Apr 2016 23:16:49 +0200 Subject: [PATCH 22/25] docs: remove duplicate line in "Understand the architecture" Signed-off-by: Sebastiaan van Stijn (cherry picked from commit 00e84ca4d20ef35ab1bdc83889afbf3374ee9745) Signed-off-by: Sebastiaan van Stijn --- docs/understanding-docker.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/understanding-docker.md b/docs/understanding-docker.md index 1dba248e0b..9aa13a9b81 100644 --- a/docs/understanding-docker.md +++ b/docs/understanding-docker.md @@ -214,8 +214,7 @@ In order, Docker Engine does the following: - **Pulls the `ubuntu` image:** Docker Engine checks for the presence of the `ubuntu` image. If the image already exists, then Docker Engine uses it for the new container. If it doesn't exist locally on the host, then Docker Engine pulls it from -[Docker Hub](https://hub.docker.com). If the image already exists, then Docker Engine -uses it for the new container. +[Docker Hub](https://hub.docker.com). - **Creates a new container:** Once Docker Engine has the image, it uses it to create a container. - **Allocates a filesystem and mounts a read-write _layer_:** The container is created in From 4703824f00486531ef8ae0a8426e0f969078843f Mon Sep 17 00:00:00 2001 From: Sven Dowideit Date: Tue, 26 Apr 2016 10:29:31 +0000 Subject: [PATCH 23/25] Small API formating fix. Signed-off-by: Sven Dowideit (cherry picked from commit 204a52c689204a4d9506d500955673f7b5361d1d) Signed-off-by: Sebastiaan van Stijn --- docs/reference/api/docker_remote_api_v1.20.md | 16 ++++++++-------- docs/reference/api/docker_remote_api_v1.21.md | 16 ++++++++-------- docs/reference/api/docker_remote_api_v1.22.md | 16 ++++++++-------- docs/reference/api/docker_remote_api_v1.23.md | 16 ++++++++-------- 4 files changed, 32 insertions(+), 32 deletions(-) diff --git a/docs/reference/api/docker_remote_api_v1.20.md b/docs/reference/api/docker_remote_api_v1.20.md index cb15ad51cf..b669ce22c4 100644 --- a/docs/reference/api/docker_remote_api_v1.20.md +++ b/docs/reference/api/docker_remote_api_v1.20.md @@ -1397,14 +1397,14 @@ Query Parameters: } } - This object maps the hostname of a registry to an object containing the - "username" and "password" for that registry. Multiple registries may - be specified as the build may be based on an image requiring - authentication to pull from any arbitrary registry. Only the registry - domain name (and port if not the default "443") are required. However - (for legacy reasons) the "official" Docker, Inc. hosted registry must - be specified with both a "https://" prefix and a "/v1/" suffix even - though Docker will prefer to use the v2 registry API. + This object maps the hostname of a registry to an object containing the + "username" and "password" for that registry. Multiple registries may + be specified as the build may be based on an image requiring + authentication to pull from any arbitrary registry. Only the registry + domain name (and port if not the default "443") are required. However + (for legacy reasons) the "official" Docker, Inc. hosted registry must + be specified with both a "https://" prefix and a "/v1/" suffix even + though Docker will prefer to use the v2 registry API. Status Codes: diff --git a/docs/reference/api/docker_remote_api_v1.21.md b/docs/reference/api/docker_remote_api_v1.21.md index 2279d2fc0b..8a463bad65 100644 --- a/docs/reference/api/docker_remote_api_v1.21.md +++ b/docs/reference/api/docker_remote_api_v1.21.md @@ -1486,14 +1486,14 @@ Query Parameters: } } - This object maps the hostname of a registry to an object containing the - "username" and "password" for that registry. Multiple registries may - be specified as the build may be based on an image requiring - authentication to pull from any arbitrary registry. Only the registry - domain name (and port if not the default "443") are required. However - (for legacy reasons) the "official" Docker, Inc. hosted registry must - be specified with both a "https://" prefix and a "/v1/" suffix even - though Docker will prefer to use the v2 registry API. + This object maps the hostname of a registry to an object containing the + "username" and "password" for that registry. Multiple registries may + be specified as the build may be based on an image requiring + authentication to pull from any arbitrary registry. Only the registry + domain name (and port if not the default "443") are required. However + (for legacy reasons) the "official" Docker, Inc. hosted registry must + be specified with both a "https://" prefix and a "/v1/" suffix even + though Docker will prefer to use the v2 registry API. Status Codes: diff --git a/docs/reference/api/docker_remote_api_v1.22.md b/docs/reference/api/docker_remote_api_v1.22.md index c0f7f21335..4a28423a3f 100644 --- a/docs/reference/api/docker_remote_api_v1.22.md +++ b/docs/reference/api/docker_remote_api_v1.22.md @@ -1666,14 +1666,14 @@ Query Parameters: } } - This object maps the hostname of a registry to an object containing the - "username" and "password" for that registry. Multiple registries may - be specified as the build may be based on an image requiring - authentication to pull from any arbitrary registry. Only the registry - domain name (and port if not the default "443") are required. However - (for legacy reasons) the "official" Docker, Inc. hosted registry must - be specified with both a "https://" prefix and a "/v1/" suffix even - though Docker will prefer to use the v2 registry API. + This object maps the hostname of a registry to an object containing the + "username" and "password" for that registry. Multiple registries may + be specified as the build may be based on an image requiring + authentication to pull from any arbitrary registry. Only the registry + domain name (and port if not the default "443") are required. However + (for legacy reasons) the "official" Docker, Inc. hosted registry must + be specified with both a "https://" prefix and a "/v1/" suffix even + though Docker will prefer to use the v2 registry API. Status Codes: diff --git a/docs/reference/api/docker_remote_api_v1.23.md b/docs/reference/api/docker_remote_api_v1.23.md index dfeaa927f2..06fa2603b8 100644 --- a/docs/reference/api/docker_remote_api_v1.23.md +++ b/docs/reference/api/docker_remote_api_v1.23.md @@ -1697,14 +1697,14 @@ Query Parameters: } } - This object maps the hostname of a registry to an object containing the - "username" and "password" for that registry. Multiple registries may - be specified as the build may be based on an image requiring - authentication to pull from any arbitrary registry. Only the registry - domain name (and port if not the default "443") are required. However - (for legacy reasons) the "official" Docker, Inc. hosted registry must - be specified with both a "https://" prefix and a "/v1/" suffix even - though Docker will prefer to use the v2 registry API. + This object maps the hostname of a registry to an object containing the + "username" and "password" for that registry. Multiple registries may + be specified as the build may be based on an image requiring + authentication to pull from any arbitrary registry. Only the registry + domain name (and port if not the default "443") are required. However + (for legacy reasons) the "official" Docker, Inc. hosted registry must + be specified with both a "https://" prefix and a "/v1/" suffix even + though Docker will prefer to use the v2 registry API. Status Codes: From c2bea5ba260846e10cafbac75c4c7c8915865812 Mon Sep 17 00:00:00 2001 From: Hao Zhang <21521210@zju.edu.cn> Date: Wed, 27 Apr 2016 08:50:46 -0400 Subject: [PATCH 24/25] update cgroup link in doc of run Signed-off-by: Hao Zhang <21521210@zju.edu.cn> (cherry picked from commit 8fec7c26d4e831481674bcab7a0539affc91da29) Signed-off-by: Sebastiaan van Stijn --- docs/reference/run.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/run.md b/docs/reference/run.md index 11503b2a8e..d135aa9965 100644 --- a/docs/reference/run.md +++ b/docs/reference/run.md @@ -1083,7 +1083,7 @@ By default, Docker containers are "unprivileged" and cannot, for example, run a Docker daemon inside a Docker container. This is because by default a container is not allowed to access any devices, but a "privileged" container is given access to all devices (see -the documentation on [cgroups devices](https://www.kernel.org/doc/Documentation/cgroups/devices.txt)). +the documentation on [cgroups devices](https://www.kernel.org/doc/Documentation/cgroup-v1/devices.txt)). When the operator executes `docker run --privileged`, Docker will enable to access to all devices on the host as well as set some configuration From 5901eda4f7d343f5006a20e153bbde9b9d445f9e Mon Sep 17 00:00:00 2001 From: Sylvain Bellemare Date: Thu, 28 Apr 2016 15:15:08 +0200 Subject: [PATCH 25/25] Fix typo Signed-off-by: Sylvain Bellemare (cherry picked from commit 63aa03ce0a9d2390f684da3403c1cd0e004592d1) Signed-off-by: Sebastiaan van Stijn --- docs/userguide/storagedriver/imagesandcontainers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/userguide/storagedriver/imagesandcontainers.md b/docs/userguide/storagedriver/imagesandcontainers.md index 3f2594d3f6..627729595c 100644 --- a/docs/userguide/storagedriver/imagesandcontainers.md +++ b/docs/userguide/storagedriver/imagesandcontainers.md @@ -70,7 +70,7 @@ first time you start an updated Docker daemon. After the migration is complete, all images and tags will have brand new secure IDs. Although the migration is automatic and transparent, it is computationally -intensive. This means it and can take time if you have lots of image data. +intensive. This means it can take time if you have lots of image data. During this time your Docker daemon will not respond to other requests. A migration tool exists that allows you to migrate existing images to the new