Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docs for Dockerfile ADD/COPY --chown flag #467

Merged
merged 1 commit into from
Nov 29, 2017
Merged

Add docs for Dockerfile ADD/COPY --chown flag #467

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 64 additions & 11 deletions docs/reference/builder.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -817,16 +817,23 @@ change them using `docker run --env <key>=<value>`.

ADD has two forms:

- `ADD <src>... <dest>`
- `ADD ["<src>",... "<dest>"]` (this form is required for paths containing
- `ADD [--chown=<user>:<group>] <src>... <dest>`
- `ADD [--chown=<user>:<group>] ["<src>",... "<dest>"]` (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 `<src>`
and adds them to the filesystem of the image at the path `<dest>`.

Multiple `<src>` 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 `<src>` 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 `<src>` may contain wildcards and matching will be done using Go's
[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. For example:
Expand All @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How do the concepts of UID and GID 0 map to Windows?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They do not apply/map at all.. I assume we need a note about that :) A Dockerfile with the --chown flag on an ADD or COPY command will fail during docker build if it is built on a Windows Docker daemon.

This was discussed in the PR for the feature implementation itself--the other option was to "ignore" the flag on Windows but today this is not the way it is implemented.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps we should add a header above this section; both for easier linking (anchor), and an introduction "This is a Linux-only feature". Also, the sections for COPY and ADD for this feature could then be combined if we think that's a good idea ("All new files and directories that are added through ADD or COPY ...."). (I'm sure @mstanleyjones has better suggestions 😄)

What is actually the owner of the files on Windows? (@johnstep?)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@estesp What I've seen is that passing --chown succeeds on Windows, if a number is supplied, but fails for a name since the code attempts to resolve the name by looking in \etc\passwd on Windows, which does not make sense.

Failing outright probably makes more sense, or at least warning, but I would prefer a more deliberate check and message. We have an issue on adding a warning, but it needs some more details: moby/moby#35026

@thaJeztah We'll look into how the owner is set on Windows. From a quick test, it seems to be set differently based on which directory a file is copied to, but we need to verify.

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 `<src>` is a remote file URL, the destination will
have permissions of 600. If the remote file being retrieved has an HTTP
Expand Down Expand Up @@ -938,15 +964,23 @@ guide](https://docs.docker.com/engine/userguide/eng-image/dockerfile_best-practi

COPY has two forms:

- `COPY <src>... <dest>`
- `COPY ["<src>",... "<dest>"]` (this form is required for paths containing
- `COPY [--chown=<user>:<group>] <src>... <dest>`
- `COPY [--chown=<user>:<group>] ["<src>",... "<dest>"]` (this form is required for paths containing
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lol, this will be a bit confusing as the first square brackets are to indicate "it's optional" and the second are literal brackets for JSON.

Don't have a better suggestion at this point though (other than having an example perhaps) - I'm okay with adding that in a follow up

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 `<src>`
and adds them to the filesystem of the container at the path `<dest>`.

Multiple `<src>` resource may be specified but they must be relative
to the source directory that is being built (the context of the build).
Multiple `<src>` 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 `<src>` may contain wildcards and matching will be done using Go's
[filepath.Match](http://golang.org/pkg/path/filepath#Match) rules. For example:
Expand All @@ -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
Expand Down