.nh
.TH skopeo-copy(1)
.SH NAME
skopeo-copy \- Copy an image (manifest, filesystem layers, signatures) from one location to another.

.SH SYNOPSIS
\fBskopeo copy\fP [\fIoptions\fP] \fIsource-image\fP \fIdestination-image\fP

.SH DESCRIPTION
Copy an image (manifest, filesystem layers, signatures) from one location to another.

.PP
Uses the system's trust policy to validate images, rejects images not trusted by the policy.

.PP
\fIsource-image\fP use the "image name" format described above

.PP
\fIdestination-image\fP use the "image name" format described above

.PP
\fIsource-image\fP and \fIdestination-image\fP are interpreted completely independently; e.g. the destination name does not
automatically inherit any parts of the source name.

.SH OPTIONS
See also skopeo(1) for options placed before the subcommand name.

.PP
\fB--additional-tag\fP=\fIstrings\fP

.PP
Additional tags (supports docker-archive).

.PP
\fB--all\fP, \fB-a\fP

.PP
If \fIsource-image\fP refers to a list of images, instead of copying just the image which matches the current OS and
architecture (subject to the use of the global --override-os, --override-arch and --override-variant options), attempt to copy all of
the images in the list, and the list itself.

.PP
\fB--authfile\fP \fIpath\fP

.PP
Path of the primary registry credentials file. On Linux, the default is ${XDG_RUNTIME_DIR}/containers/auth.json.
See \fBcontainers-auth.json\fP(5) for more details about the credential search mechanism and defaults on other platforms.

.PP
Use \fBskopeo login\fR to manage the credentials.

.PP
The default value of this option is read from the \fBREGISTRY\\_AUTH\\_FILE\fR environment variable.

.PP
\fB--src-authfile\fP \fIpath\fP

.PP
Path of the primary registry credentials file for the source registry. Uses path given by \fB--authfile\fR, if not provided.

.PP
\fB--dest-authfile\fP \fIpath\fP

.PP
Path of the primary registry credentials file for the destination registry. Uses path given by \fB--authfile\fR, if not provided.

.PP
\fB--dest-shared-blob-dir\fP \fIdirectory\fP

.PP
Directory to use to share blobs across OCI repositories.

.PP
\fB--digestfile\fP \fIpath\fP

.PP
After copying the image, write the digest of the resulting image to the file.

.PP
\fB--preserve-digests\fP

.PP
Preserve the digests during copying. Fail if the digest cannot be preserved.

.PP
This option does not change what will be copied; consider using \fB--all\fR at the same time.

.PP
\fB--encrypt-layer\fP \fIints\fP

.PP
\fIExperimental\fP the 0-indexed layer indices, with support for negative indexing (e.g. 0 is the first layer, -1 is the last layer)

.PP
\fB--format\fP, \fB-f\fP \fImanifest-type\fP

.PP
MANIFEST TYPE (oci, v2s1, or v2s2) to use in the destination (default is manifest type of source, with fallbacks)

.PP
\fB--help\fP, \fB-h\fP

.PP
Print usage statement

.PP
\fB--multi-arch\fP \fIoption\fP

.PP
Control what is copied if \fIsource-image\fP refers to a multi-architecture image. Default is system.

.PP
Options:
- system: Copy only the image that matches the system architecture
- all: Copy the full multi-architecture image
- index-only: Copy only the index
- \fIplatform-list\fP: Copy only specific platforms (comma-separated list of OS/Architecture pairs, e.g., \fBlinux/amd64,linux/arm64\fR)

.PP
The index-only option and platform-list both create sparse manifest lists, which usually fail unless the referenced per-architecture images are already present in the destination, or the target registry supports sparse indexes.

.PP
When specifying a platform list, all compression variants and other variations for each platform are copied.

.PP
\fB--quiet\fP, \fB-q\fP

.PP
Suppress output information when copying images.

.PP
\fB--remove-signatures\fP

.PP
Do not copy signatures, if any, from \fIsource-image\fP\&. Necessary when copying a signed image to a destination which does not support signatures.

.PP
\fB--remove-list-signatures\fP

.PP
Do not copy the manifest list signature while preserving per-instance signatures. This provides more granular control than \fB--remove-signatures\fP, which removes all signatures.

.PP
\fB--strip-removed-platforms\fP

.PP
When copying only a subset of platforms from a multi-architecture image (using \fB--multi-arch\fP with a platform list), write a manifest list containing only the copied platforms, instead of leaving entries that refer to per-platform images not present in the destination. This is useful for registries that reject manifest lists containing references to missing images.

.PP
Note: This option requires signatures to be removed using either \fB--remove-signatures\fP or \fB--remove-list-signatures\fP, as stripping instances invalidates the manifest list signature and changes the manifest list digest. The operation will fail if signatures are present and not explicitly removed.

.PP
\fB--sign-by\fP \fIkey-id\fP

.PP
Add a “simple signing” signature using that key ID for an image name corresponding to \fIdestination-image\fP

.PP
\fB--sign-by-sigstore\fP \fIparam-file\fP

.PP
Add a sigstore signature based on the options in the specified containers sigstore signing parameter file, \fIparam-file\fP\&.
See containers-sigstore-signing-params.yaml(5) for details about the file format.

.PP
\fB--sign-by-sigstore-private-key\fP \fIpath\fP

.PP
Add a sigstore signature using a private key at \fIpath\fP for an image name corresponding to \fIdestination-image\fP

.PP
\fB--sign-by-sq-fingerprint\fP \fIfingerprint\fP

.PP
Add a “simple signing” signature using a Sequoia-PGP key with the specified \fIfingerprint\fP\&.

.PP
\fB--sign-passphrase-file\fP \fIpath\fP

.PP
The passphrase to use when signing with \fB--sign-by\fR, \fB--sign-by-sigstore-private-key\fR or \fB--sign-by-sq-fingerprint\fR\&.
Only the first line will be read. A passphrase stored in a file is of questionable security if other users can read this file. Do not use this option if at all avoidable.

.PP
\fB--sign-identity\fP \fIreference\fP

.PP
The identity to use when signing the image. The identity must be a fully specified docker reference. If the identity is not specified, the target docker reference will be used.

.PP
\fB--src-shared-blob-dir\fP \fIdirectory\fP

.PP
Directory to use to share blobs across OCI repositories.

.PP
\fB--encryption-key\fP \fIprotocol:keyfile\fP

.PP
Specifies the encryption protocol, which can be JWE (RFC7516), PGP (RFC4880), and PKCS7 (RFC2315) and the key material required for image encryption. For instance, jwe:/path/to/key.pem or pgp:admin@example.com or pkcs7:/path/to/x509-file.

.PP
\fB--decryption-key\fP \fIkey[:passphrase]\fP

.PP
Key to be used for decryption of images. Key can point to keys and/or certificates. Decryption will be tried with all keys. If the key is protected by a passphrase, it is required to be passed in the argument and omitted otherwise.

.PP
\fB--src-creds\fP \fIusername[:password]\fP

.PP
Credentials for accessing the source registry.

.PP
\fB--dest-compress\fP

.PP
Compress tarball image layers when saving to directory using the 'dir' transport. (default is same compression type as source).

.PP
\fB--dest-decompress\fP

.PP
Decompress tarball image layers when saving to directory using the 'dir' transport. (default is same compression type as source).

.PP
\fB--dest-oci-accept-uncompressed-layers\fP

.PP
Allow uncompressed image layers when saving to an OCI image using the 'oci' transport. (default is to compress things that aren't compressed).

.PP
\fB--dest-creds\fP \fIusername[:password]\fP

.PP
Credentials for accessing the destination registry.

.PP
\fB--src-cert-dir\fP \fIpath\fP

.PP
Use certificates at \fIpath\fP (*.crt, *.cert, *.key) to connect to the source registry or daemon.

.PP
\fB--src-no-creds\fP

.PP
Access the registry anonymously.

.PP
\fB--src-tls-verify\fP=\fIbool\fP

.PP
Require HTTPS and verify certificates when talking to container source registry or daemon. Default to source registry setting.

.PP
\fB--dest-cert-dir\fP \fIpath\fP

.PP
Use certificates at \fIpath\fP (*.crt, *.cert, *.key) to connect to the destination registry or daemon.

.PP
\fB--dest-no-creds\fP

.PP
Access the registry anonymously.

.PP
\fB--dest-tls-verify\fP=\fIbool\fP

.PP
Require HTTPS and verify certificates when talking to container destination registry or daemon. Default to destination registry setting.

.PP
\fB--src-daemon-host\fP \fIhost\fP

.PP
Copy from docker daemon at \fIhost\fP\&. If \fIhost\fP starts with \fBtcp://\fR, HTTPS is enabled by default. To use plain HTTP, use the form \fBhttp://\fR (default is \fBunix:///var/run/docker.sock\fR).

.PP
\fB--dest-daemon-host\fP \fIhost\fP

.PP
Copy to docker daemon at \fIhost\fP\&. If \fIhost\fP starts with \fBtcp://\fR, HTTPS is enabled by default. To use plain HTTP, use the form \fBhttp://\fR (default is \fBunix:///var/run/docker.sock\fR).

.PP
\fB--dest-compress-format\fP \fIformat\fP

.PP
Specifies the compression format to use.  Supported values are: \fBgzip\fR, \fBzstd\fR and \fBzstd:chunked\fR\&.
\fBzstd:chunked\fR is incompatible with encrypting images,
and will be treated as \fBzstd\fR with a warning in that case.

.PP
\fB--dest-compress-level\fP \fIformat\fP

.PP
Specifies the compression level to use.  The value is specific to the compression algorithm used, e.g. for zstd the accepted values are in the range 1-20 (inclusive), while for gzip it is 1-9 (inclusive).

.PP
\fB--dest-force-compress-format\fP

.PP
Ensures that the compression algorithm set in --dest-compress-format is used exclusively.

.PP
\fB--src-registry-token\fP \fItoken\fP

.PP
Bearer token for accessing the source registry.

.PP
\fB--dest-registry-token\fP \fItoken\fP

.PP
Bearer token for accessing the destination registry.

.PP
\fB--dest-precompute-digests\fP

.PP
Precompute digests to ensure layers are not uploaded that already exist on the destination registry. Layers with initially unknown digests (ex. compressing "on the fly") will be temporarily streamed to disk.

.PP
\fB--retry-times\fP

.PP
The number of times to retry. By default, no retries are attempted.

.PP
\fB--retry-delay\fP

.PP
Fixed delay between retries. If not set (or set to 0s), retry wait time will be exponentially increased based on the number of failed attempts.

.PP
\fB--src-username\fP

.PP
The username to access the source registry.

.PP
\fB--src-password\fP

.PP
The password to access the source registry.

.PP
\fB--dest-username\fP

.PP
The username to access the destination registry.

.PP
\fB--dest-password\fP

.PP
The password to access the destination registry.

.PP
\fB--image-parallel-copies\fP \fIn\fP

.PP
Maximum number of image layers to be copied (pulled/pushed) simultaneously. Not setting this field will fall back to containers/image defaults.

.SH EXAMPLES
To just copy an image from one registry to another:

.EX
$ skopeo copy docker://quay.io/skopeo/stable:latest docker://registry.example.com/skopeo:latest
.EE

.PP
To copy the layers of the docker.io busybox image to a local directory:

.EX
$ mkdir -p /var/lib/images/busybox
$ skopeo copy docker://busybox:latest dir:/var/lib/images/busybox
$ ls /var/lib/images/busybox/*
  /tmp/busybox/2b8fd9751c4c0f5dd266fcae00707e67a2545ef34f9a29354585f93dac906749.tar
  /tmp/busybox/manifest.json
  /tmp/busybox/8ddc19f16526912237dd8af81971d5e4dd0587907234be2b83e249518d5b673f.tar
.EE

.PP
To create an archive consumable by \fBdocker load\fR (but note that using a registry is almost always more efficient):

.EX
$ skopeo copy docker://busybox:latest docker-archive:archive-file.tar:busybox:latest
.EE

.PP
To copy and sign an image:

.EX
$ skopeo copy --sign-by dev@example.com containers-storage:example/busybox:streaming docker://example/busybox:gold
.EE

.PP
To copy only specific platforms from a multi-architecture image (creates a sparse manifest list):

.EX
$ skopeo copy --multi-arch=linux/amd64,linux/arm64 docker://quay.io/skopeo/stable:latest docker://registry.example.com/skopeo:latest
.EE

.PP
To copy specific platforms and strip the sparse manifest list (for registries that don't support sparse lists):

.EX
$ skopeo copy --multi-arch=linux/amd64,linux/arm64 --strip-removed-platforms --remove-list-signatures docker://quay.io/skopeo/stable:latest docker://registry.example.com/skopeo:latest
.EE

.PP
To encrypt an image:

.EX
$ skopeo copy docker://docker.io/library/nginx:1.17.8 oci:local_nginx:1.17.8

$ openssl genrsa -out private.key 1024
$ openssl rsa -in private.key -pubout > public.key

$ skopeo copy --encryption-key jwe:./public.key oci:local_nginx:1.17.8 oci:try-encrypt:encrypted
.EE

.PP
To decrypt an image:

.EX
$ skopeo copy --decryption-key ./private.key oci:try-encrypt:encrypted oci:try-decrypt:decrypted
.EE

.PP
To copy encrypted image without decryption:

.EX
$ skopeo copy oci:try-encrypt:encrypted oci:try-encrypt-copy:encrypted
.EE

.PP
To decrypt an image that requires more than one key:

.EX
$ skopeo copy --decryption-key ./private1.key --decryption-key ./private2.key --decryption-key ./private3.key oci:try-encrypt:encrypted oci:try-decrypt:decrypted
.EE

.PP
Container images can also be partially encrypted by specifying the index of the layer. Layers are 0-indexed indices, with support for negative indexing. i.e. 0 is the first layer, -1 is the last layer.

.PP
Let's say out of 3 layers that the image \fBdocker.io/library/nginx:1.17.8\fR is made up of, we only want to encrypt the 2nd layer,

.EX
$ skopeo copy --encryption-key jwe:./public.key --encrypt-layer 1 oci:local_nginx:1.17.8 oci:try-encrypt:encrypted
.EE

.SH SEE ALSO
skopeo(1), skopeo-login(1), docker-login(1), containers-auth.json(5), containers-policy.json(5), containers-transports(5), containers-signature(5)

.SH AUTHORS
Antonio Murdaca runcom@redhat.com
\[la]mailto:runcom@redhat.com\[ra], Miloslav Trmac mitr@redhat.com
\[la]mailto:mitr@redhat.com\[ra], Jhon Honce jhonce@redhat.com
\[la]mailto:jhonce@redhat.com\[ra]