diff --git a/Makefile b/Makefile index 9d3b132cb6..a73762a6be 100644 --- a/Makefile +++ b/Makefile @@ -22,9 +22,9 @@ CONTAINERSSYSCONFIGDIR=${DESTDIR}/etc/containers REGISTRIESDDIR=${CONTAINERSSYSCONFIGDIR}/registries.d SIGSTOREDIR=${DESTDIR}/var/lib/atomic/sigstore BASHINSTALLDIR=${PREFIX}/share/bash-completion/completions -GO_MD2MAN ?= go-md2man GO ?= go CONTAINER_RUNTIME := $(shell command -v podman 2> /dev/null || echo docker) +GOMD2MAN ?= $(shell command -v go-md2man || echo '$(GOBIN)/go-md2man') ifeq ($(DEBUG), 1) override GOGCFLAGS += -N -l @@ -90,7 +90,7 @@ build-container: ${CONTAINER_RUNTIME} build ${BUILD_ARGS} -t "$(IMAGE)" . docs/%.1: docs/%.1.md - $(GO_MD2MAN) -in $< -out $@.tmp && touch $@.tmp && mv $@.tmp $@ + @sed -e 's/\((skopeo.*\.md)\)//' -e 's/\[\(skopeo.*\)\]/\1/' $< | $(GOMD2MAN) -in /dev/stdin -out $@ docs: $(MANPAGES_MD:%.md=%) diff --git a/docs/skopeo-copy.1.md b/docs/skopeo-copy.1.md new file mode 100644 index 0000000000..dc3552e3af --- /dev/null +++ b/docs/skopeo-copy.1.md @@ -0,0 +1,79 @@ +% skopeo-copy(1) + +## NAME +skopeo\-copy - Copy an image (manifest, filesystem layers, signatures) from one location to another. + +## SYNOPSIS +**skopeo copy** [**--sign-by=**_key-ID_] _source-image destination-image_ + +## DESCRIPTION +Copy an image (manifest, filesystem layers, signatures) from one location to another. + +Uses the system's trust policy to validate images, rejects images not trusted by the policy. + + _source-image_ use the "image name" format described above + + _destination-image_ use the "image name" format described above + +## OPTIONS + +**--authfile** _path_ + +Path of the authentication file. Default is ${XDG_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. +If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. + +**--format, -f** _manifest-type_ Manifest type (oci, v2s1, or v2s2) to use when saving image to directory using the 'dir:' transport (default is manifest type of source) + +**--quiet, -q** suppress output information when copying images + +**--remove-signatures** do not copy signatures, if any, from _source-image_. Necessary when copying a signed image to a destination which does not support signatures. + +**--sign-by=**_key-id_ add a signature using that key ID for an image name corresponding to _destination-image_ + +**--src-creds** _username[:password]_ for accessing the source registry + +**--dest-compress** _bool-value_ Compress tarball image layers when saving to directory using the 'dir' transport. (default is same compression type as source) + +**--dest-creds** _username[:password]_ for accessing the destination registry + +**--src-cert-dir** _path_ Use certificates at _path_ (*.crt, *.cert, *.key) to connect to the source registry or daemon + +**--src-tls-verify** _bool-value_ Require HTTPS and verify certificates when talking to container source registry or daemon (defaults to true) + +**--dest-cert-dir** _path_ Use certificates at _path_ (*.crt, *.cert, *.key) to connect to the destination registry or daemon + +**--dest-ostree-tmp-dir** _path_ Directory to use for OSTree temporary files. + +**--dest-tls-verify** _bool-value_ Require HTTPS and verify certificates when talking to container destination registry or daemon (defaults to true) + +**--src-daemon-host** _host_ Copy from docker daemon at _host_. If _host_ starts with `tcp://`, HTTPS is enabled by default. To use plain HTTP, use the form `http://` (default is `unix:///var/run/docker.sock`). + +**--dest-daemon-host** _host_ Copy to docker daemon at _host_. If _host_ starts with `tcp://`, HTTPS is enabled by default. To use plain HTTP, use the form `http://` (default is `unix:///var/run/docker.sock`). + +Existing signatures, if any, are preserved as well. + +## EXAMPLES + +To copy the layers of the docker.io busybox image to a local directory: +```sh +$ 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 +``` + +To copy and sign an image: + +```sh +$ skopeo copy --sign-by dev@example.com atomic:example/busybox:streaming atomic:example/busybox:gold +``` + +## SEE ALSO +skopeo(1), podman-login(1), docker-login(1) + +## AUTHORS + +Antonio Murdaca , Miloslav Trmac , Jhon Honce + diff --git a/docs/skopeo-delete.1.md b/docs/skopeo-delete.1.md new file mode 100644 index 0000000000..bbd348ceea --- /dev/null +++ b/docs/skopeo-delete.1.md @@ -0,0 +1,50 @@ +% skopeo-delete(1) + +## NAME +skopeo\-delete - Mark _image-name_ for deletion. + +## SYNOPSIS +**skopeo delete** _image-name_ + +Mark _image-name_ for deletion. To release the allocated disk space, you must login to the container registry server and execute the container registry garbage collector. E.g., + +``` +/usr/bin/registry garbage-collect /etc/docker-distribution/registry/config.yml + +Note: sometimes the config.yml is stored in /etc/docker/registry/config.yml + +If you are running the container registry inside of a container you would execute something like: + +$ docker exec -it registry /usr/bin/registry garbage-collect /etc/docker-distribution/registry/config.yml + +``` + +**--authfile** _path_ + + Path of the authentication file. Default is ${XDG_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. + If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. + +**--creds** _username[:password]_ for accessing the registry + +**--cert-dir** _path_ Use certificates at _path_ (*.crt, *.cert, *.key) to connect to the registry + +**--tls-verify** _bool-value_ Require HTTPS and verify certificates when talking to container registries (defaults to true) + +Additionally, the registry must allow deletions by setting `REGISTRY_STORAGE_DELETE_ENABLED=true` for the registry daemon. + +## EXAMPLES + +Mark image example/pause for deletion from the registry.example.com registry: +```sh +$ skopeo delete --force docker://registry.example.com/example/pause:latest +``` +See above for additional details on using the command **delete**. + + +## SEE ALSO +skopeo(1), podman-login(1), docker-login(1) + +## AUTHORS + +Antonio Murdaca , Miloslav Trmac , Jhon Honce + diff --git a/docs/skopeo-inspect.1.md b/docs/skopeo-inspect.1.md new file mode 100644 index 0000000000..4c7d94c554 --- /dev/null +++ b/docs/skopeo-inspect.1.md @@ -0,0 +1,61 @@ +% skopeo-inspect(1) + +## NAME +skopeo\-inspect - Return low-level information about _image-name_ in a registry + +## SYNOPSIS +**skopeo inspect** [**--raw**] _image-name_ + +Return low-level information about _image-name_ in a registry + + **--raw** output raw manifest, default is to format in JSON + + _image-name_ name of image to retrieve information about + + **--authfile** _path_ + + Path of the authentication file. Default is ${XDG_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. + If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. + + **--creds** _username[:password]_ for accessing the registry + + **--cert-dir** _path_ Use certificates at _path_ (*.crt, *.cert, *.key) to connect to the registry + + **--tls-verify** _bool-value_ Require HTTPS and verify certificates when talking to container registries (defaults to true) + +## EXAMPLES + +To review information for the image fedora from the docker.io registry: +```sh +$ skopeo inspect docker://docker.io/fedora +{ + "Name": "docker.io/library/fedora", + "Digest": "sha256:a97914edb6ba15deb5c5acf87bd6bd5b6b0408c96f48a5cbd450b5b04509bb7d", + "RepoTags": [ + "20", + "21", + "22", + "23", + "24", + "heisenbug", + "latest", + "rawhide" + ], + "Created": "2016-06-20T19:33:43.220526898Z", + "DockerVersion": "1.10.3", + "Labels": {}, + "Architecture": "amd64", + "Os": "linux", + "Layers": [ + "sha256:7c91a140e7a1025c3bc3aace4c80c0d9933ac4ee24b8630a6b0b5d8b9ce6b9d4" + ] +} +``` + +# SEE ALSO +skopeo(1), podman-login(1), docker-login(1) + +## AUTHORS + +Antonio Murdaca , Miloslav Trmac , Jhon Honce + diff --git a/docs/skopeo-manifest-digest.1.md b/docs/skopeo-manifest-digest.1.md new file mode 100644 index 0000000000..d3c2a66954 --- /dev/null +++ b/docs/skopeo-manifest-digest.1.md @@ -0,0 +1,26 @@ +% skopeo-manifest-digest(1) + +## NAME +skopeo\-manifest\-digest -Compute a manifest digest of manifest-file and write it to standard output. + +## SYNOPSIS +**skopeo manifest-digest** _manifest-file_ + +## DESCRIPTION + +Compute a manifest digest of _manifest-file_ and write it to standard output. + +## EXAMPLES + +```sh +$ skopeo manifest-digest manifest.json +sha256:a59906e33509d14c036c8678d687bd4eec81ed7c4b8ce907b888c607f6a1e0e6 +``` + +## SEE ALSO +skopeo(1) + +## AUTHORS + +Antonio Murdaca , Miloslav Trmac , Jhon Honce + diff --git a/docs/skopeo-standalone-sign.1.md b/docs/skopeo-standalone-sign.1.md new file mode 100644 index 0000000000..568e93836d --- /dev/null +++ b/docs/skopeo-standalone-sign.1.md @@ -0,0 +1,34 @@ +% skopeo-standalone-sign(1) + +## NAME +skopeo\-standalone-sign - Simple Sign an image + +## SYNOPSIS +**skopeo standalone-sign** _manifest docker-reference key-fingerprint_ **--output**|**-o** _signature_ + +## DESCRIPTION +This is primarily a debugging tool, or useful for special cases, +and usually should not be a part of your normal operational workflow; use `skopeo copy --sign-by` instead to publish and sign an image in one step. + + _manifest_ Path to a file containing the image manifest + + _docker-reference_ A docker reference to identify the image with + + _key-fingerprint_ Key identity to use for signing + + **--output**|**-o** output file + +## EXAMPLES + +```sh +$ skopeo standalone-sign busybox-manifest.json registry.example.com/example/busybox 1D8230F6CDB6A06716E414C1DB72F2188BB46CC8 --output busybox.signature +$ +``` + +## SEE ALSO +skopeo(1), skopeo-copy(1) + +## AUTHORS + +Antonio Murdaca , Miloslav Trmac , Jhon Honce + diff --git a/docs/skopeo-standalone-verify.1.md b/docs/skopeo-standalone-verify.1.md new file mode 100644 index 0000000000..893fb54f88 --- /dev/null +++ b/docs/skopeo-standalone-verify.1.md @@ -0,0 +1,36 @@ +% skopeo-standalone-verify(1) + +## NAME +skopeo\-standalone\-verify - Verify an image signature + +## SYNOPSIS +**skopeo standalone-verify** _manifest docker-reference key-fingerprint signature_ + +## DESCRIPTION + +Verify a signature using local files, digest will be printed on success. + + _manifest_ Path to a file containing the image manifest + + _docker-reference_ A docker reference expected to identify the image in the signature + + _key-fingerprint_ Expected identity of the signing key + + _signature_ Path to signature file + +**Note:** If you do use this, make sure that the image can not be changed at the source location between the times of its verification and use. + +## EXAMPLES + +```sh +$ skopeo standalone-verify busybox-manifest.json registry.example.com/example/busybox 1D8230F6CDB6A06716E414C1DB72F2188BB46CC8 busybox.signature +Signature verified, digest sha256:20bf21ed457b390829cdbeec8795a7bea1626991fda603e0d01b4e7f60427e55 +``` + +## SEE ALSO +skopeo(1) + +## AUTHORS + +Antonio Murdaca , Miloslav Trmac , Jhon Honce + diff --git a/docs/skopeo.1.md b/docs/skopeo.1.md index 4a25abcb3d..d995a6e7cf 100644 --- a/docs/skopeo.1.md +++ b/docs/skopeo.1.md @@ -1,11 +1,13 @@ % SKOPEO(1) Skopeo Man Pages % Jhon Honce % August 2016 -# NAME +## NAME skopeo -- Command line utility used to interact with local and remote container images and container image registries -# SYNOPSIS + +## SYNOPSIS **skopeo** [_global options_] _command_ [_command options_] -# DESCRIPTION + +## DESCRIPTION `skopeo` is a command line utility providing various operations with container images and container image registries. `skopeo` can copy container images between various containers image stores, converting them as necessary. For example you can use `skopeo` to copy container images from one container registry to another. @@ -31,7 +33,7 @@ Most commands refer to container images, using a _transport_`:`_details_ format. An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files. This is a non-standardized format, primarily useful for debugging or noninvasive container inspection. **docker://**_docker-reference_ - An image in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in either `$XDG_RUNTIME_DIR/containers/auth.json`, which is set using `(kpod login)`. If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using `(docker login)`. + An image in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in either `$XDG_RUNTIME_DIR/containers/auth.json`, which is set using `(podman login)`. If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using `(docker login)`. **docker-archive:**_path_[**:**_docker-reference_] An image is stored in the `docker save` formatted file. _docker-reference_ is only used when creating such a file, and it must not contain a digest. @@ -45,7 +47,7 @@ Most commands refer to container images, using a _transport_`:`_details_ format. **ostree:**_image_[**@**_/absolute/repo/path_] An image in local OSTree repository. _/absolute/repo/path_ defaults to _/ostree/repo_. -# OPTIONS +## OPTIONS **--debug** enable debug output @@ -65,140 +67,18 @@ Most commands refer to container images, using a _transport_`:`_details_ format. **--version**|**-v** print the version number -# COMMANDS - -## skopeo copy -**skopeo copy** [**--sign-by=**_key-ID_] _source-image destination-image_ - -Copy an image (manifest, filesystem layers, signatures) from one location to another. - -Uses the system's trust policy to validate images, rejects images not trusted by the policy. - - _source-image_ use the "image name" format described above - - _destination-image_ use the "image name" format described above - - **--authfile** _path_ - - Path of the authentication file. Default is ${XDG_RUNTIME\_DIR}/containers/auth.json, which is set using `kpod login`. - If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. - - **--format, -f** _manifest-type_ Manifest type (oci, v2s1, or v2s2) to use when saving image to directory using the 'dir:' transport (default is manifest type of source) - - **--quiet, -q** suppress output information when copying images - **--remove-signatures** do not copy signatures, if any, from _source-image_. Necessary when copying a signed image to a destination which does not support signatures. - - **--sign-by=**_key-id_ add a signature using that key ID for an image name corresponding to _destination-image_ - - **--src-creds** _username[:password]_ for accessing the source registry - - **--dest-compress** _bool-value_ Compress tarball image layers when saving to directory using the 'dir' transport. (default is same compression type as source) - - **--dest-creds** _username[:password]_ for accessing the destination registry - - **--src-cert-dir** _path_ Use certificates at _path_ (*.crt, *.cert, *.key) to connect to the source registry or daemon - - **--src-tls-verify** _bool-value_ Require HTTPS and verify certificates when talking to container source registry or daemon (defaults to true) - - **--dest-cert-dir** _path_ Use certificates at _path_ (*.crt, *.cert, *.key) to connect to the destination registry or daemon - - **--dest-ostree-tmp-dir** _path_ Directory to use for OSTree temporary files. - - **--dest-tls-verify** _bool-value_ Require HTTPS and verify certificates when talking to container destination registry or daemon (defaults to true) - - **--src-daemon-host** _host_ Copy from docker daemon at _host_. If _host_ starts with `tcp://`, HTTPS is enabled by default. To use plain HTTP, use the form `http://` (default is `unix:///var/run/docker.sock`). - - **--dest-daemon-host** _host_ Copy to docker daemon at _host_. If _host_ starts with `tcp://`, HTTPS is enabled by default. To use plain HTTP, use the form `http://` (default is `unix:///var/run/docker.sock`). - -Existing signatures, if any, are preserved as well. - -## skopeo delete -**skopeo delete** _image-name_ - -Mark _image-name_ for deletion. To release the allocated disk space, you must login to the container registry server and execute the container registry garbage collector. E.g., - -``` -/usr/bin/registry garbage-collect /etc/docker-distribution/registry/config.yml - -Note: sometimes the config.yml is stored in /etc/docker/registry/config.yml - -If you are running the container registry inside of a container you would execute something like: - -$ docker exec -it registry /usr/bin/registry garbage-collect /etc/docker-distribution/registry/config.yml - -``` - - **--authfile** _path_ +## COMMANDS - Path of the authentication file. Default is ${XDG_RUNTIME\_DIR}/containers/auth.json, which is set using `kpod login`. - If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. +| Command | Description | +| ----------------------------------------- | ------------------------------------------------------------------------------ | +| [skopeo-copy(1)](skopeo-copy.1.md) | Copy an image (manifest, filesystem layers, signatures) from one location to another. | +| [skopeo-delete(1)](skopeo-delete.1.md) | Mark image-name for deletion. | +| [skopeo-inspect(1)](skopeo-inspect.1.md) | Return low-level information about image-name in a registry. | +| [skopeo-manifest-digest(1)](skopeo-manifest-digest.1.md) | Compute a manifest digest of manifest-file and write it to standard output.| +| [skopeo-standalone-sign(1)](skopeo-standalone-sign.1.md) | Sign an image. | +| [skopeo-standalone-verify(1)](skopeo-standalone-verify.1.md)| Verity an image. | - **--creds** _username[:password]_ for accessing the registry - - **--cert-dir** _path_ Use certificates at _path_ (*.crt, *.cert, *.key) to connect to the registry - - **--tls-verify** _bool-value_ Require HTTPS and verify certificates when talking to container registries (defaults to true) - -Additionally, the registry must allow deletions by setting `REGISTRY_STORAGE_DELETE_ENABLED=true` for the registry daemon. - -## skopeo inspect -**skopeo inspect** [**--raw**] _image-name_ - -Return low-level information about _image-name_ in a registry - - **--raw** output raw manifest, default is to format in JSON - - _image-name_ name of image to retrieve information about - - **--authfile** _path_ - - Path of the authentication file. Default is ${XDG_RUNTIME\_DIR}/containers/auth.json, which is set using `kpod login`. - If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. - - **--creds** _username[:password]_ for accessing the registry - - **--cert-dir** _path_ Use certificates at _path_ (*.crt, *.cert, *.key) to connect to the registry - - **--tls-verify** _bool-value_ Require HTTPS and verify certificates when talking to container registries (defaults to true) - -## skopeo manifest-digest -**skopeo manifest-digest** _manifest-file_ - -Compute a manifest digest of _manifest-file_ and write it to standard output. - -## skopeo standalone-sign -**skopeo standalone-sign** _manifest docker-reference key-fingerprint_ **--output**|**-o** _signature_ - -This is primarily a debugging tool, or useful for special cases, -and usually should not be a part of your normal operational workflow; use `skopeo copy --sign-by` instead to publish and sign an image in one step. - - _manifest_ Path to a file containing the image manifest - - _docker-reference_ A docker reference to identify the image with - - _key-fingerprint_ Key identity to use for signing - - **--output**|**-o** output file - -## skopeo standalone-verify -**skopeo standalone-verify** _manifest docker-reference key-fingerprint signature_ - -Verify a signature using local files, digest will be printed on success. - - _manifest_ Path to a file containing the image manifest - - _docker-reference_ A docker reference expected to identify the image in the signature - - _key-fingerprint_ Expected identity of the signing key - - _signature_ Path to signature file - -**Note:** If you do use this, make sure that the image can not be changed at the source location between the times of its verification and use. - -## skopeo help -show help for `skopeo` - -# FILES +## FILES **/etc/containers/policy.json** Default trust policy file, if **--policy** is not specified. The policy format is documented in https://github.com/containers/image/blob/master/docs/policy.json.md . @@ -207,89 +87,9 @@ show help for `skopeo` Default directory containing registry configuration, if **--registries.d** is not specified. The contents of this directory are documented in https://github.com/containers/image/blob/master/docs/registries.d.md . -# EXAMPLES - -## skopeo copy -To copy the layers of the docker.io busybox image to a local directory: -```sh -$ 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 -``` - -To copy and sign an image: - -```sh -$ skopeo copy --sign-by dev@example.com atomic:example/busybox:streaming atomic:example/busybox:gold -``` -## skopeo delete -Mark image example/pause for deletion from the registry.example.com registry: -```sh -$ skopeo delete --force docker://registry.example.com/example/pause:latest -``` -See above for additional details on using the command **delete**. - -## skopeo inspect -To review information for the image fedora from the docker.io registry: -```sh -$ skopeo inspect docker://docker.io/fedora -{ - "Name": "docker.io/library/fedora", - "Digest": "sha256:a97914edb6ba15deb5c5acf87bd6bd5b6b0408c96f48a5cbd450b5b04509bb7d", - "RepoTags": [ - "20", - "21", - "22", - "23", - "24", - "heisenbug", - "latest", - "rawhide" - ], - "Created": "2016-06-20T19:33:43.220526898Z", - "DockerVersion": "1.10.3", - "Labels": {}, - "Architecture": "amd64", - "Os": "linux", - "Layers": [ - "sha256:7c91a140e7a1025c3bc3aace4c80c0d9933ac4ee24b8630a6b0b5d8b9ce6b9d4" - ] -} -``` -## skopeo layers -Another method to retrieve the layers for the busybox image from the docker.io registry: -```sh -$ skopeo layers docker://busybox -$ ls layers-500650331/ - 8ddc19f16526912237dd8af81971d5e4dd0587907234be2b83e249518d5b673f.tar - manifest.json - a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4.tar -``` -## skopeo manifest-digest -```sh -$ skopeo manifest-digest manifest.json -sha256:a59906e33509d14c036c8678d687bd4eec81ed7c4b8ce907b888c607f6a1e0e6 -``` -## skopeo standalone-sign -```sh -$ skopeo standalone-sign busybox-manifest.json registry.example.com/example/busybox 1D8230F6CDB6A06716E414C1DB72F2188BB46CC8 --output busybox.signature -$ -``` - -See `skopeo copy` above for the preferred method of signing images. -## skopeo standalone-verify -```sh -$ skopeo standalone-verify busybox-manifest.json registry.example.com/example/busybox 1D8230F6CDB6A06716E414C1DB72F2188BB46CC8 busybox.signature -Signature verified, digest sha256:20bf21ed457b390829cdbeec8795a7bea1626991fda603e0d01b4e7f60427e55 -``` - -# SEE ALSO -kpod-login(1), docker-login(1) - -# AUTHORS +## SEE ALSO +podman-login(1), docker-login(1) -Antonio Murdaca , Miloslav Trmac , Jhon Honce +## AUTHORS +Antonio Murdaca , Miloslav Trmac , Jhon Honce