From a83b9f102be036f31829af2b911fb00f43e54419 Mon Sep 17 00:00:00 2001 From: Phil Estes Date: Wed, 23 Aug 2017 09:22:23 -0700 Subject: [PATCH] Add docs for Dockerfile ADD/COPY --chown flag Document the new `--chown` flag added to the ADD and COPY commands in the Dockerfile format. Signed-off-by: Phil Estes --- docs/reference/builder.md | 75 +++++++++++++++++++++++++++++++++------ 1 file changed, 64 insertions(+), 11 deletions(-) diff --git a/docs/reference/builder.md b/docs/reference/builder.md index cf4f79faea..215c3f3b9b 100644 --- a/docs/reference/builder.md +++ b/docs/reference/builder.md @@ -817,16 +817,23 @@ change them using `docker run --env =`. ADD has two forms: -- `ADD ... ` -- `ADD ["",... ""]` (this form is required for paths containing +- `ADD [--chown=:] ... ` +- `ADD [--chown=:] ["",... ""]` (this form is required for paths containing whitespace) +> **Note**: +> The `--chown` feature is only supported on Dockerfiles used to build Linux containers, +> and will not work on Windows containers. Since user and group ownership concepts do +> not translate between Linux and Windows, the use of `/etc/passwd` and `/etc/group` for +> translating user and group names to IDs restricts this feature to only be viable for +> for Linux OS-based containers. + The `ADD` instruction copies new files, directories or remote file URLs from `` and adds them to the filesystem of the image at the path ``. -Multiple `` resource may be specified but if they are files or -directories then they must be relative to the source directory that is -being built (the context of the build). +Multiple `` resources may be specified but if they are files or +directories, their paths are interpreted as relative to the source of +the context of the build. Each `` may contain wildcards and matching will be done using Go's [filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. For example: @@ -848,7 +855,26 @@ named `arr[0].txt`, use the following; ADD arr[[]0].txt /mydir/ # copy a file named "arr[0].txt" to /mydir/ -All new files and directories are created with a UID and GID of 0. +All new files and directories are created with a UID and GID of 0, unless the +optional `--chown` flag specifies a given username, groupname, or UID/GID +combination to request specific ownership of the content added. The +format of the `--chown` flag allows for either username and groupname strings +or direct integer UID and GID in any combination. Providing a username without +groupname or a UID without GID will use the same numeric UID as the GID. If a +username or groupname is provided, the container's root filesystem +`/etc/passwd` and `/etc/group` files will be used to perform the translation +from name to integer UID or GID respectively. The following examples show +valid definitions for the `--chown` flag: + + ADD --chown=55:mygroup files* /somedir/ + ADD --chown=bin files* /somedir/ + ADD --chown=1 files* /somedir/ + ADD --chown=10:11 files* /somedir/ + +If the container root filesystem does not contain either `/etc/passwd` or +`/etc/group` files and either user or group names are used in the `--chown` +flag, the build will fail on the `ADD` operation. Using numeric IDs requires +no lookup and will not depend on container root filesystem content. In the case where `` is a remote file URL, the destination will have permissions of 600. If the remote file being retrieved has an HTTP @@ -938,15 +964,23 @@ guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practi COPY has two forms: -- `COPY ... ` -- `COPY ["",... ""]` (this form is required for paths containing +- `COPY [--chown=:] ... ` +- `COPY [--chown=:] ["",... ""]` (this form is required for paths containing whitespace) +> **Note**: +> The `--chown` feature is only supported on Dockerfiles used to build Linux containers, +> and will not work on Windows containers. Since user and group ownership concepts do +> not translate between Linux and Windows, the use of `/etc/passwd` and `/etc/group` for +> translating user and group names to IDs restricts this feature to only be viable for +> for Linux OS-based containers. + The `COPY` instruction copies new files or directories from `` and adds them to the filesystem of the container at the path ``. -Multiple `` resource may be specified but they must be relative -to the source directory that is being built (the context of the build). +Multiple `` resources may be specified but the paths of files and +directories will be interpreted as relative to the source of the context +of the build. Each `` may contain wildcards and matching will be done using Go's [filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. For example: @@ -968,7 +1002,26 @@ named `arr[0].txt`, use the following; COPY arr[[]0].txt /mydir/ # copy a file named "arr[0].txt" to /mydir/ -All new files and directories are created with a UID and GID of 0. +All new files and directories are created with a UID and GID of 0, unless the +optional `--chown` flag specifies a given username, groupname, or UID/GID +combination to request specific ownership of the copied content. The +format of the `--chown` flag allows for either username and groupname strings +or direct integer UID and GID in any combination. Providing a username without +groupname or a UID without GID will use the same numeric UID as the GID. If a +username or groupname is provided, the container's root filesystem +`/etc/passwd` and `/etc/group` files will be used to perform the translation +from name to integer UID or GID respectively. The following examples show +valid definitions for the `--chown` flag: + + COPY --chown=55:mygroup files* /somedir/ + COPY --chown=bin files* /somedir/ + COPY --chown=1 files* /somedir/ + COPY --chown=10:11 files* /somedir/ + +If the container root filesystem does not contain either `/etc/passwd` or +`/etc/group` files and either user or group names are used in the `--chown` +flag, the build will fail on the `COPY` operation. Using numeric IDs requires +no lookup and will not depend on container root filesystem content. > **Note**: > If you build using STDIN (`docker build - < somefile`), there is no