зеркало из https://github.com/microsoft/docker.git
docs: Updated for docker cp and its API changes
Documented changes to API to enable new `docker cp` behavior. Added documentation on `docker cp` usage and behavior. Docker-DCO-1.1-Signed-off-by: Josh Hawn <josh.hawn@docker.com> (github: jlhawn)
This commit is contained in:
Josh Hawn
Родитель
418135e7ea
Коммит
e54b1e081a
|
|
@ -68,6 +68,23 @@ Running `docker rmi` emits an **untag** event when removing an image name. The
|
|||
|
||||
### What's new
|
||||
|
||||
`GET /containers/(id)/archive`
|
||||
|
||||
**New!**
|
||||
Get an archive of filesystem content from a container.
|
||||
|
||||
`PUT /containers/(id)/archive`
|
||||
|
||||
**New!**
|
||||
Upload an archive of content to be extracted to an
|
||||
existing directory inside a container's filesystem.
|
||||
|
||||
`POST /containers/(id)/copy`
|
||||
|
||||
**Deprecated!**
|
||||
This copy endpoint has been deprecated in favor of the above `archive` endpoint
|
||||
which can be used to download files and directories from a container.
|
||||
|
||||
**New!**
|
||||
The `hostConfig` option now accepts the field `GroupAdd`, which specifies a list of additional
|
||||
groups that the container process will run as.
|
||||
|
|
|
|||
|
|
@ -1039,6 +1039,8 @@ Status Codes:
|
|||
|
||||
Copy files or folders of container `id`
|
||||
|
||||
**Deprecated** in favor of the `archive` endpoint below.
|
||||
|
||||
**Example request**:
|
||||
|
||||
POST /containers/4fa6e0f0c678/copy HTTP/1.1
|
||||
|
|
@ -1061,6 +1063,120 @@ Status Codes:
|
|||
- **404** – no such container
|
||||
- **500** – server error
|
||||
|
||||
### Retrieving information about files and folders in a container
|
||||
|
||||
`HEAD /containers/(id)/archive`
|
||||
|
||||
See the description of the `X-Docker-Container-Path-Stat` header in the
|
||||
folowing section.
|
||||
|
||||
### Get an archive of a filesystem resource in a container
|
||||
|
||||
`GET /containers/(id)/archive`
|
||||
|
||||
Get an tar archive of a resource in the filesystem of container `id`.
|
||||
|
||||
Query Parameters:
|
||||
|
||||
- **path** - resource in the container's filesystem to archive. Required.
|
||||
|
||||
If not an absolute path, it is relative to the container's root directory.
|
||||
The resource specified by **path** must exist. To assert that the resource
|
||||
is expected to be a directory, **path** should end in `/` or `/.`
|
||||
(assuming a path separator of `/`). If **path** ends in `/.` then this
|
||||
indicates that only the contents of the **path** directory should be
|
||||
copied. A symlink is always resolved to its target.
|
||||
|
||||
**Note**: It is not possible to copy certain system files such as resources
|
||||
under `/proc`, `/sys`, `/dev`, and mounts created by the user in the
|
||||
container.
|
||||
|
||||
**Example request**:
|
||||
|
||||
GET /containers/8cce319429b2/archive?path=/root HTTP/1.1
|
||||
|
||||
**Example response**:
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/x-tar
|
||||
X-Docker-Container-Path-Stat: eyJuYW1lIjoicm9vdCIsInBhdGgiOiIvcm9vdCIsInNpemUiOjQwOTYsIm1vZGUiOjIxNDc0ODQwOTYsIm10aW1lIjoiMjAxNC0wMi0yN1QyMDo1MToyM1oifQ==
|
||||
|
||||
{{ TAR STREAM }}
|
||||
|
||||
On success, a response header `X-Docker-Container-Path-Stat` will be set to a
|
||||
base64-encoded JSON object containing some filesystem header information about
|
||||
the archived resource. The above example value would decode to the following
|
||||
JSON object (whitespace added for readability):
|
||||
|
||||
{
|
||||
"name": "root",
|
||||
"path": "/root",
|
||||
"size": 4096,
|
||||
"mode": 2147484096,
|
||||
"mtime": "2014-02-27T20:51:23Z"
|
||||
}
|
||||
|
||||
A `HEAD` request can also be made to this endpoint if only this information is
|
||||
desired.
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** - success, returns archive of copied resource
|
||||
- **400** - client error, bad parameter, details in JSON response body, one of:
|
||||
- must specify path parameter (**path** cannot be empty)
|
||||
- not a directory (**path** was asserted to be a directory but exists as a
|
||||
file)
|
||||
- **404** - client error, resource not found, one of:
|
||||
– no such container (container `id` does not exist)
|
||||
- no such file or directory (**path** does not exist)
|
||||
- **500** - server error
|
||||
|
||||
### Extract an archive of files or folders to a directory in a container
|
||||
|
||||
`PUT /containers/(id)/archive`
|
||||
|
||||
Upload a tar archive to be extracted to a path in the filesystem of container
|
||||
`id`.
|
||||
|
||||
Query Parameters:
|
||||
|
||||
- **path** - path to a directory in the container
|
||||
to extract the archive's contents into. Required.
|
||||
|
||||
If not an absolute path, it is relative to the container's root directory.
|
||||
The **path** resource must exist.
|
||||
- **noOverwriteDirNonDir** - If "1", "true", or "True" then it will be an error
|
||||
if unpacking the given content would cause an existing directory to be
|
||||
replaced with a non-directory and vice versa.
|
||||
|
||||
**Example request**:
|
||||
|
||||
PUT /containers/8cce319429b2/archive?path=/vol1 HTTP/1.1
|
||||
Content-Type: application/x-tar
|
||||
|
||||
{{ TAR STREAM }}
|
||||
|
||||
**Example response**:
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
|
||||
Status Codes:
|
||||
|
||||
- **200** – the content was extracted successfully
|
||||
- **400** - client error, bad parameter, details in JSON response body, one of:
|
||||
- must specify path parameter (**path** cannot be empty)
|
||||
- not a directory (**path** should be a directory but exists as a file)
|
||||
- unable to overwrite existing directory with non-directory
|
||||
(if **noOverwriteDirNonDir**)
|
||||
- unable to overwrite existing non-directory with directory
|
||||
(if **noOverwriteDirNonDir**)
|
||||
- **403** - client error, permission denied, the volume
|
||||
or container rootfs is marked as read-only.
|
||||
- **404** - client error, resource not found, one of:
|
||||
– no such container (container `id` does not exist)
|
||||
- no such file or directory (**path** resource does not exist)
|
||||
- **500** – server error
|
||||
|
||||
## 2.2 Images
|
||||
|
||||
### List Images
|
||||
|
|
|
|||
|
|
@ -11,12 +11,81 @@ weight=1
|
|||
|
||||
# cp
|
||||
|
||||
Usage: docker cp CONTAINER:PATH HOSTDIR|-
|
||||
Copy files/folders between a container and the local filesystem.
|
||||
|
||||
Copy files/folders from the PATH to the HOSTDIR.
|
||||
Usage: docker cp [options] CONTAINER:PATH LOCALPATH|-
|
||||
docker cp [options] LOCALPATH|- CONTAINER:PATH
|
||||
|
||||
Copy files or folders from a container's filesystem to the directory on the
|
||||
host. Use '-' to write the data as a tar file to `STDOUT`. `CONTAINER:PATH` is
|
||||
relative to the root of the container's filesystem.
|
||||
--help Print usage statement
|
||||
|
||||
In the first synopsis form, the `docker cp` utility copies the contents of
|
||||
`PATH` from the filesystem of `CONTAINER` to the `LOCALPATH` (or stream as
|
||||
a tar archive to `STDOUT` if `-` is specified).
|
||||
|
||||
In the second synopsis form, the contents of `LOCALPATH` (or a tar archive
|
||||
streamed from `STDIN` if `-` is specified) are copied from the local machine to
|
||||
`PATH` in the filesystem of `CONTAINER`.
|
||||
|
||||
You can copy to or from either a running or stopped container. The `PATH` can
|
||||
be a file or directory. The `docker cp` command assumes all `CONTAINER:PATH`
|
||||
values are relative to the `/` (root) directory of the container. This means
|
||||
supplying the initial forward slash is optional; The command sees
|
||||
`compassionate_darwin:/tmp/foo/myfile.txt` and
|
||||
`compassionate_darwin:tmp/foo/myfile.txt` as identical. If a `LOCALPATH` value
|
||||
is not absolute, is it considered relative to the current working directory.
|
||||
|
||||
Behavior is similar to the common Unix utility `cp -a` in that directories are
|
||||
copied recursively with permissions preserved if possible. Ownership is set to
|
||||
the user and primary group on the receiving end of the transfer. For example,
|
||||
files copied to a container will be created with `UID:GID` of the root user.
|
||||
Files copied to the local machine will be created with the `UID:GID` of the
|
||||
user which invoked the `docker cp` command.
|
||||
|
||||
Assuming a path separator of `/`, a first argument of `SRC_PATH` and second
|
||||
argument of `DST_PATH`, the behavior is as follows:
|
||||
|
||||
- `SRC_PATH` specifies a file
|
||||
- `DST_PATH` does not exist
|
||||
- the file is saved to a file created at `DST_PATH`
|
||||
- `DST_PATH` does not exist and ends with `/`
|
||||
- Error condition: the destination directory must exist.
|
||||
- `DST_PATH` exists and is a file
|
||||
- the destination is overwritten with the contents of the source file
|
||||
- `DST_PATH` exists and is a directory
|
||||
- the file is copied into this directory using the basename from
|
||||
`SRC_PATH`
|
||||
- `SRC_PATH` specifies a directory
|
||||
- `DST_PATH` does not exist
|
||||
- `DST_PATH` is created as a directory and the *contents* of the source
|
||||
directory are copied into this directory
|
||||
- `DST_PATH` exists and is a file
|
||||
- Error condition: cannot copy a directory to a file
|
||||
- `DST_PATH` exists and is a directory
|
||||
- `SRC_PATH` does not end with `/.`
|
||||
- the source directory is copied into this directory
|
||||
- `SRC_PAPTH` does end with `/.`
|
||||
- the *content* of the source directory is copied into this
|
||||
directory
|
||||
|
||||
The command requires `SRC_PATH` and `DST_PATH` to exist according to the above
|
||||
rules. If `SRC_PATH` is local and is a symbolic link, the symbolic link, not
|
||||
the target, is copied.
|
||||
|
||||
A colon (`:`) is used as a delimiter between `CONTAINER` and `PATH`, but `:`
|
||||
could also be in a valid `LOCALPATH`, like `file:name.txt`. This ambiguity is
|
||||
resolved by requiring a `LOCALPATH` with a `:` to be made explicit with a
|
||||
relative or absolute path, for example:
|
||||
|
||||
`/path/to/file:name.txt` or `./file:name.txt`
|
||||
|
||||
It is not possible to copy certain system files such as resources under
|
||||
`/proc`, `/sys`, `/dev`, and mounts created by the user in the container.
|
||||
|
||||
Using `-` as the first argument in place of a `LOCALPATH` will stream the
|
||||
contents of `STDIN` as a tar archive which will be extracted to the `PATH` in
|
||||
the filesystem of the destination container. In this case, `PATH` must specify
|
||||
a directory.
|
||||
|
||||
Using `-` as the second argument in place of a `LOCALPATH` will stream the
|
||||
contents of the resource from the source container as a tar archive to
|
||||
`STDOUT`.
|
||||
|
|
|
|||
|
|
@ -2,69 +2,150 @@
|
|||
% Docker Community
|
||||
% JUNE 2014
|
||||
# NAME
|
||||
docker-cp - Copy files or folders from a container's PATH to a HOSTDIR
|
||||
or to STDOUT.
|
||||
docker-cp - Copy files/folders between a container and the local filesystem.
|
||||
|
||||
# SYNOPSIS
|
||||
**docker cp**
|
||||
[**--help**]
|
||||
CONTAINER:PATH HOSTDIR|-
|
||||
CONTAINER:PATH LOCALPATH|-
|
||||
LOCALPATH|- CONTAINER:PATH
|
||||
|
||||
# DESCRIPTION
|
||||
|
||||
Copy files or folders from a `CONTAINER:PATH` to the `HOSTDIR` or to `STDOUT`.
|
||||
The `CONTAINER:PATH` is relative to the root of the container's filesystem. You
|
||||
can copy from either a running or stopped container.
|
||||
In the first synopsis form, the `docker cp` utility copies the contents of
|
||||
`PATH` from the filesystem of `CONTAINER` to the `LOCALPATH` (or stream as
|
||||
a tar archive to `STDOUT` if `-` is specified).
|
||||
|
||||
The `PATH` can be a file or directory. The `docker cp` command assumes all
|
||||
`PATH` values start at the `/` (root) directory. This means supplying the
|
||||
initial forward slash is optional; The command sees
|
||||
In the second synopsis form, the contents of `LOCALPATH` (or a tar archive
|
||||
streamed from `STDIN` if `-` is specified) are copied from the local machine to
|
||||
`PATH` in the filesystem of `CONTAINER`.
|
||||
|
||||
You can copy to or from either a running or stopped container. The `PATH` can
|
||||
be a file or directory. The `docker cp` command assumes all `CONTAINER:PATH`
|
||||
values are relative to the `/` (root) directory of the container. This means
|
||||
supplying the initial forward slash is optional; The command sees
|
||||
`compassionate_darwin:/tmp/foo/myfile.txt` and
|
||||
`compassionate_darwin:tmp/foo/myfile.txt` as identical.
|
||||
`compassionate_darwin:tmp/foo/myfile.txt` as identical. If a `LOCALPATH` value
|
||||
is not absolute, is it considered relative to the current working directory.
|
||||
|
||||
The `HOSTDIR` refers to a directory on the host. If you do not specify an
|
||||
absolute path for your `HOSTDIR` value, Docker creates the directory relative to
|
||||
where you run the `docker cp` command. For example, suppose you want to copy the
|
||||
`/tmp/foo` directory from a container to the `/tmp` directory on your host. If
|
||||
you run `docker cp` in your `~` (home) directory on the host:
|
||||
Behavior is similar to the common Unix utility `cp -a` in that directories are
|
||||
copied recursively with permissions preserved if possible. Ownership is set to
|
||||
the user and primary group on the receiving end of the transfer. For example,
|
||||
files copied to a container will be created with `UID:GID` of the root user.
|
||||
Files copied to the local machine will be created with the `UID:GID` of the
|
||||
user which invoked the `docker cp` command.
|
||||
|
||||
$ docker cp compassionate_darwin:tmp/foo /tmp
|
||||
Assuming a path separator of `/`, a first argument of `SRC_PATH` and second
|
||||
argument of `DST_PATH`, the behavior is as follows:
|
||||
|
||||
Docker creates a `/tmp/foo` directory on your host. Alternatively, you can omit
|
||||
the leading slash in the command. If you execute this command from your home directory:
|
||||
- `SRC_PATH` specifies a file
|
||||
- `DST_PATH` does not exist
|
||||
- the file is saved to a file created at `DST_PATH`
|
||||
- `DST_PATH` does not exist and ends with `/`
|
||||
- Error condition: the destination directory must exist.
|
||||
- `DST_PATH` exists and is a file
|
||||
- the destination is overwritten with the contents of the source file
|
||||
- `DST_PATH` exists and is a directory
|
||||
- the file is copied into this directory using the basename from
|
||||
`SRC_PATH`
|
||||
- `SRC_PATH` specifies a directory
|
||||
- `DST_PATH` does not exist
|
||||
- `DST_PATH` is created as a directory and the *contents* of the source
|
||||
directory are copied into this directory
|
||||
- `DST_PATH` exists and is a file
|
||||
- Error condition: cannot copy a directory to a file
|
||||
- `DST_PATH` exists and is a directory
|
||||
- `SRC_PATH` does not end with `/.`
|
||||
- the source directory is copied into this directory
|
||||
- `SRC_PAPTH` does end with `/.`
|
||||
- the *content* of the source directory is copied into this
|
||||
directory
|
||||
|
||||
$ docker cp compassionate_darwin:tmp/foo tmp
|
||||
The command requires `SRC_PATH` and `DST_PATH` to exist according to the above
|
||||
rules. If `SRC_PATH` is local and is a symbolic link, the symbolic link, not
|
||||
the target, is copied.
|
||||
|
||||
Docker creates a `~/tmp/foo` subdirectory.
|
||||
A colon (`:`) is used as a delimiter between `CONTAINER` and `PATH`, but `:`
|
||||
could also be in a valid `LOCALPATH`, like `file:name.txt`. This ambiguity is
|
||||
resolved by requiring a `LOCALPATH` with a `:` to be made explicit with a
|
||||
relative or absolute path, for example:
|
||||
|
||||
When copying files to an existing `HOSTDIR`, the `cp` command adds the new files to
|
||||
the directory. For example, this command:
|
||||
`/path/to/file:name.txt` or `./file:name.txt`
|
||||
|
||||
$ docker cp sharp_ptolemy:/tmp/foo/myfile.txt /tmp
|
||||
It is not possible to copy certain system files such as resources under
|
||||
`/proc`, `/sys`, `/dev`, and mounts created by the user in the container.
|
||||
|
||||
Creates a `/tmp/foo` directory on the host containing the `myfile.txt` file. If
|
||||
you repeat the command but change the filename:
|
||||
Using `-` as the first argument in place of a `LOCALPATH` will stream the
|
||||
contents of `STDIN` as a tar archive which will be extracted to the `PATH` in
|
||||
the filesystem of the destination container. In this case, `PATH` must specify
|
||||
a directory.
|
||||
|
||||
$ docker cp sharp_ptolemy:/tmp/foo/secondfile.txt /tmp
|
||||
|
||||
Your host's `/tmp/foo` directory will contain both files:
|
||||
|
||||
$ ls /tmp/foo
|
||||
myfile.txt secondfile.txt
|
||||
|
||||
Finally, use '-' to write the data as a `tar` file to STDOUT.
|
||||
Using `-` as the second argument in place of a `LOCALPATH` will stream the
|
||||
contents of the resource from the source container as a tar archive to
|
||||
`STDOUT`.
|
||||
|
||||
# OPTIONS
|
||||
**--help**
|
||||
Print usage statement
|
||||
|
||||
# EXAMPLES
|
||||
An important shell script file, created in a bash shell, is copied from
|
||||
the exited container to the current dir on the host:
|
||||
|
||||
# docker cp c071f3c3ee81:setup.sh .
|
||||
Suppose a container has finished producing some output as a file it saves
|
||||
to somewhere in its filesystem. This could be the output of a build job or
|
||||
some other computation. You can copy these outputs from the container to a
|
||||
location on your local host.
|
||||
|
||||
If you want to copy the `/tmp/foo` directory from a container to the
|
||||
existing `/tmp` directory on your host. If you run `docker cp` in your `~`
|
||||
(home) directory on the local host:
|
||||
|
||||
$ docker cp compassionate_darwin:tmp/foo /tmp
|
||||
|
||||
Docker creates a `/tmp/foo` directory on your host. Alternatively, you can omit
|
||||
the leading slash in the command. If you execute this command from your home
|
||||
directory:
|
||||
|
||||
$ docker cp compassionate_darwin:tmp/foo tmp
|
||||
|
||||
If `~/tmp` does not exist, Docker will create it and copy the contents of
|
||||
`/tmp/foo` from the container into this new directory. If `~/tmp` already
|
||||
exists as a directory, then Docker will copy the contents of `/tmp/foo` from
|
||||
the container into a directory at `~/tmp/foo`.
|
||||
|
||||
When copying a single file to an existing `LOCALPATH`, the `docker cp` command
|
||||
will either overwrite the contents of `LOCALPATH` if it is a file or place it
|
||||
into `LOCALPATH` if it is a directory, overwriting an existing file of the same
|
||||
name if one exists. For example, this command:
|
||||
|
||||
$ docker cp sharp_ptolemy:/tmp/foo/myfile.txt /test
|
||||
|
||||
If `/test` does not exist on the local machine, it will be created as a file
|
||||
with the contents of `/tmp/foo/myfile.txt` from the container. If `/test`
|
||||
exists as a file, it will be overwritten. Lastly, if `/tmp` exists as a
|
||||
directory, the file will be copied to `/test/myfile.txt`.
|
||||
|
||||
Next, suppose you want to copy a file or folder into a container. For example,
|
||||
this could be a configuration file or some other input to a long running
|
||||
computation that you would like to place into a created container before it
|
||||
starts. This is useful because it does not require the configuration file or
|
||||
other input to exist in the container image.
|
||||
|
||||
If you have a file, `config.yml`, in the current directory on your local host
|
||||
and wish to copy it to an existing directory at `/etc/my-app.d` in a container,
|
||||
this command can be used:
|
||||
|
||||
$ docker cp config.yml myappcontainer:/etc/my-app.d
|
||||
|
||||
If you have several files in a local directory `/config` which you need to copy
|
||||
to a directory `/etc/my-app.d` in a container:
|
||||
|
||||
$ docker cp /config/. myappcontainer:/etc/my-app.d
|
||||
|
||||
The above command will copy the contents of the local `/config` directory into
|
||||
the directory `/etc/my-app.d` in the container.
|
||||
|
||||
# HISTORY
|
||||
April 2014, Originally compiled by William Henry (whenry at redhat dot com)
|
||||
based on docker.com source material and internal work.
|
||||
June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
|
||||
May 2015, updated by Josh Hawn <josh.hawn@docker.com>
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче