168 lines
6.6 KiB
Groff
168 lines
6.6 KiB
Groff
.nh
|
|
.TH podman-cp 1
|
|
.SH NAME
|
|
podman-cp \- Copy files/folders between a container and the local filesystem
|
|
|
|
.SH SYNOPSIS
|
|
\fBpodman cp\fP [\fIoptions\fP] [\fIcontainer\fP:]\fIsrc_path\fP [\fIcontainer\fP:]\fIdest_path\fP
|
|
|
|
.PP
|
|
\fBpodman container cp\fP [\fIoptions\fP] [\fIcontainer\fP:]\fIsrc_path\fP [\fIcontainer\fP:]\fIdest_path\fP
|
|
|
|
.SH DESCRIPTION
|
|
\fBpodman cp\fP allows copying the contents of \fBsrc_path\fP to the \fBdest_path\fP\&. Files can be copied from a container to the local machine and vice versa or between two containers.
|
|
If \fB-\fR is specified for either the \fBSRC_PATH\fR or \fBDEST_PATH\fR, one can also stream a tar archive from \fBSTDIN\fR or to \fBSTDOUT\fR\&.
|
|
|
|
.PP
|
|
The containers can be either running or stopped and the \fIsrc_path\fP or \fIdest_path\fP can be a file or directory.
|
|
|
|
.PP
|
|
*IMPORTANT: The \fBpodman cp\fP command assumes container paths are relative to the container's root directory (\fB/\fR), which means supplying the initial forward slash is optional and therefore sees \fBcompassionate_darwin:/tmp/foo/myfile.txt\fR and \fBcompassionate_darwin:tmp/foo/myfile.txt\fR as identical.*
|
|
|
|
.PP
|
|
Local machine paths can be an absolute or relative value.
|
|
The command interprets a local machine's relative paths as relative to the current working directory where \fBpodman cp\fP is run.
|
|
|
|
.PP
|
|
Assuming a path separator of \fB/\fR, a first argument of \fBsrc_path\fP and second argument of \fBdest_path\fP, the behavior is as follows:
|
|
|
|
.PP
|
|
\fBsrc_path\fP specifies a file:
|
|
- \fBdest_path\fP does not exist
|
|
- the file is saved to a file created at \fBdest_path\fP (note that parent directory must exist).
|
|
- \fBdest_path\fP exists and is a file
|
|
- the destination is overwritten with the source file's contents.
|
|
- \fBdest_path\fP exists and is a directory
|
|
- the file is copied into this directory using the base name from \fBsrc_path\fP\&.
|
|
|
|
.PP
|
|
\fBsrc_path\fP specifies a directory:
|
|
- \fBdest_path\fP does not exist
|
|
- \fBdest_path\fP is created as a directory and the contents of the source directory are copied into this directory.
|
|
- \fBdest_path\fP exists and is a file
|
|
- Error condition: cannot copy a directory to a file.
|
|
- \fBdest_path\fP exists and is a directory
|
|
- \fBsrc_path\fP ends with \fB/\fR
|
|
- the source directory is copied into this directory.
|
|
- \fBsrc_path\fP ends with \fB/.\fR (i.e., slash followed by dot)
|
|
- the content of the source directory is copied into this directory.
|
|
|
|
.PP
|
|
The command requires \fBsrc_path\fP and \fBdest_path\fP to exist according to the above rules.
|
|
|
|
.PP
|
|
If \fBsrc_path\fP is local and is a symbolic link, the symbolic target, is copied by default.
|
|
|
|
.PP
|
|
A \fIcolon\fP ( : ) is used as a delimiter between a container and its path, it can also be used when specifying paths to a \fBsrc_path\fP or \fBdest_path\fP on a local machine, for example, \fBfile:name.txt\fR\&.
|
|
|
|
.PP
|
|
*IMPORTANT: while using a \fIcolon\fP ( : ) in a local machine path, one must be explicit with a relative or absolute path, for example: \fB/path/to/file:name.txt\fR or \fB\&./file:name.txt\fR*
|
|
|
|
.PP
|
|
Using \fB-\fR as the \fBsrc_path\fP streams the contents of \fBSTDIN\fR as a tar archive. The command extracts the content of the tar to the \fBDEST_PATH\fR in the container. In this case, \fBdest_path\fP must specify a directory. Using \fB-\fR as the \fBdest_path\fP streams the contents of the resource (can be a directory) as a tar archive to \fBSTDOUT\fR\&.
|
|
|
|
.PP
|
|
Note that \fBpodman cp\fR ignores permission errors when copying from a running rootless container. The TTY devices inside a rootless container are owned by the host's root user and hence cannot be read inside the container's user namespace.
|
|
|
|
.PP
|
|
Further note that \fBpodman cp\fR does not support globbing (e.g., \fBcp dir/*.txt\fR). To copy multiple files from the host to the container use xargs(1) or find(1) (or similar tools for chaining commands) in conjunction with \fBpodman cp\fR\&. To copy multiple files from the container to the host, use \fBpodman mount CONTAINER\fR and operate on the returned mount point instead (see ALTERNATIVES below).
|
|
|
|
.SH OPTIONS
|
|
.SS \fB--archive\fP, \fB-a\fP
|
|
Archive mode (copy all UID/GID information).
|
|
When set to true, files copied to a container have changed ownership to the primary UID/GID of the container.
|
|
When set to false, maintain UID/GID from archive sources instead of changing them to the primary UID/GID of the destination container.
|
|
The default is \fBtrue\fP\&.
|
|
|
|
.SS \fB--overwrite\fP
|
|
Allow directories to be overwritten with non-directories and vice versa. By default, \fBpodman cp\fR errors out when attempting to overwrite, for instance, a regular file with a directory.
|
|
|
|
.SH ALTERNATIVES
|
|
Podman has much stronger capabilities than just \fBpodman cp\fR to achieve copying files between the host and containers.
|
|
|
|
.PP
|
|
Using standard \fBpodman-mount(1)\fP and \fBpodman-unmount(1)\fP takes advantage of the entire Linux tool chain, rather than just \fBcp\fR\&.
|
|
|
|
.PP
|
|
Copying contents out of a container or into a container can be achieved with a few simple commands. For example:
|
|
|
|
.PP
|
|
To copy the \fB/etc/foobar\fR directory out of a container and onto \fB/tmp\fR on the host, the following commands can be executed:
|
|
|
|
.EX
|
|
mnt=$(podman mount CONTAINERID)
|
|
cp -R ${mnt}/etc/foobar /tmp
|
|
podman umount CONTAINERID
|
|
.EE
|
|
|
|
.PP
|
|
To untar a tar ball into a container, following commands can be executed:
|
|
|
|
.EX
|
|
mnt=$(podman mount CONTAINERID)
|
|
tar xf content.tgz -C ${mnt}
|
|
podman umount CONTAINERID
|
|
.EE
|
|
|
|
.PP
|
|
To install a package into a container that
|
|
does not have dnf installed, following commands can be executed:
|
|
|
|
.EX
|
|
mnt=$(podman mount CONTAINERID)
|
|
dnf install --installroot=${mnt} httpd
|
|
chroot ${mnt} rm -rf /var/log/dnf /var/cache/dnf
|
|
podman umount CONTAINERID
|
|
.EE
|
|
|
|
.PP
|
|
By using \fBpodman mount\fR and \fBpodman unmount\fR, one can use all of the
|
|
standard Linux tools for moving files into and out of containers, not just
|
|
the \fBcp\fR command.
|
|
|
|
.SH EXAMPLES
|
|
Copy a file from the host to a container:
|
|
|
|
.EX
|
|
podman cp /myapp/app.conf containerID:/myapp/app.conf
|
|
.EE
|
|
|
|
.PP
|
|
Copy a file from a container to a directory on another container:
|
|
|
|
.EX
|
|
podman cp containerID1:/myfile.txt containerID2:/tmp
|
|
.EE
|
|
|
|
.PP
|
|
Copy a directory on a container to a directory on the host:
|
|
|
|
.EX
|
|
podman cp containerID:/myapp/ /myapp/
|
|
.EE
|
|
|
|
.PP
|
|
Copy the contents of a directory on a container to a directory on the host:
|
|
|
|
.EX
|
|
podman cp containerID:/home/myuser/. /home/myuser/
|
|
.EE
|
|
|
|
.PP
|
|
Copy a directory on a container into a directory on another:
|
|
|
|
.EX
|
|
podman cp containerA:/myapp containerB:/newapp
|
|
.EE
|
|
|
|
.PP
|
|
Stream a tar archive from \fBSTDIN\fR to a container:
|
|
|
|
.EX
|
|
podman cp - containerID:/myfiles.tar.gz < myfiles.tar.gz
|
|
.EE
|
|
|
|
.SH SEE ALSO
|
|
\fBpodman(1)\fP, \fBpodman-mount(1)\fP, \fBpodman-unmount(1)\fP
|