diff --git a/Makefile b/Makefile index f2650467..6744f31a 100644 --- a/Makefile +++ b/Makefile @@ -7,6 +7,7 @@ INSTALLDIR=${PREFIX}/bin MANINSTALLDIR=${PREFIX}/share/man # TODO(runcom) #BASHINSTALLDIR=${PREFIX}/share/bash-completion/completions +GO_MD2MAN ?= /usr/bin/go-md2man GIT_BRANCH := $(shell git rev-parse --abbrev-ref HEAD 2>/dev/null) DOCKER_IMAGE := skopeo-dev$(if $(GIT_BRANCH),:$(GIT_BRANCH)) @@ -23,7 +24,9 @@ DOCKER_RUN_DOCKER := $(DOCKER_FLAGS) "$(DOCKER_IMAGE)" GIT_COMMIT := $(shell git rev-parse HEAD 2> /dev/null || true) -all: binary +MANPAGES_MD = $(wildcard docs/*.md) + +all: binary docs binary: skopeo @@ -41,11 +44,16 @@ binary-local: build-container: docker build ${DOCKER_BUILD_ARGS} -t "$(DOCKER_IMAGE)" . -clean: - rm -f skopeo +docs/%.1: docs/%.1.md + $(GO_MD2MAN) -in $< -out $@.tmp && touch $@.tmp && mv $@.tmp $@ -install: install-binary - install -m 644 man1/skopeo.1 ${MANINSTALLDIR}/man1/ +.PHONY: docs +docs: $(MANPAGES_MD:%.md=%) + +clean: + rm -f skopeo docs/*.1 + +install: install-binary install-docs # TODO(runcom) #install -m 644 completion/bash/skopeo ${BASHINSTALLDIR}/ @@ -53,6 +61,9 @@ install-binary: install -d -m 0755 ${INSTALLDIR} install -m 755 skopeo ${INSTALLDIR} +install-docs: + install -d -m 0755 ${MANINSTALLDIR}/man1 + install -m 644 docs/skopeo.1 ${MANINSTALLDIR}/man1/ shell: build-container $(DOCKER_RUN_DOCKER) bash @@ -70,7 +81,7 @@ test-unit: build-container validate: build-container $(DOCKER_RUN_DOCKER) hack/make.sh validate-git-marks validate-gofmt validate-lint validate-vet -# This target is only intended for development, e.g. executing it from an IDE. Use (make test) for CI or pre-release testing. +# This target is only intended for development, e.g. executing it from an IDE. Use (make test) for CI or pre-release testing. test-all-local: validate-local test-unit-local validate-local: diff --git a/docs/skopeo.1.md b/docs/skopeo.1.md new file mode 100644 index 00000000..aff3b8ca --- /dev/null +++ b/docs/skopeo.1.md @@ -0,0 +1,203 @@ +% SKOPEO(1) Skopeo Man Pages +% Jhon Honce +% August 2016 +# NAME +skopeo -- Various operations with container images images and container image registries +# SYNOPSIS +**skopeo** [_global options_] _command_ [_command options_] +# DESCRIPTION +`skopeo` is a command line utility providing various operations with container images and container image registries. For example, it is able to inspect a repository on a Docker registry and fetch image. It fetches the repository's manifest and it is able to show you a `docker inspect`-like json output about a whole repository or a tag. This tool, in contrast to `docker inspect`, helps you gather useful information about a repository or a tag without requiring you to run `docker pull` - e.g. - which tags are available for the given repository? which labels the image has? + +It also allows you to copy container images between various registries, possibly converting them as necessary, and to sign and verify images. +## IMAGE NAMES +Most commands refer to container images, using a _transport_`:`_details_ format. The following formats are supported: + + **atomic:**_namespace_**/**_stream_**:**_tag_ + An image in the current project of the current default Atomic + Registry. The current project and Atomic Registry instance are by + default read from `$HOME/.kube/config`, which is set e.g. using + `(oc login)`. + + **dir:**_path_ + 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 `$HOME/.docker/config.json`, + which is set e.g. using `(docker login)`. + + **oci:**_path_**:**_tag_ + An image _tag_ in a directory compliant with "Open Container Image + Layout Specification" at _path_. + +# OPTIONS + + **--debug** enable debug output + + **--username** _username_ for accessing the registry + + **--password** _password_ for accessing the registry + + **--cert-path** _path_ Use certificates at _path_ (cert.pem, key.pem) to connect to the registry + + **--tls-verify** _bool-value_ Verify certificates + + **--help**|**-h** Show help + + **--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. + + _source-image_ use the "image name" format described above + + _destination-image_ use the "image name" format described above + + **--sign-by=**_key-id_ add a signature using that key ID for an image name corresponding to _destination-image_ + +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 need to execute the docker registry garabage collector. E.g., + +```sh +$ docker exec -it registry bin/registry garbage-collect /etc/docker/registry/config.yml +``` + +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 + +## skopeo layers +**skopeo layers** _image-name_ + +Get image layers of _image-name_ + + _image-name_ name of the image to retrieve layers + +## 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` + +# 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 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 +``` + +# AUTHORS + +Antonio Murdaca , Miloslav Trmac , Jhon Honce + diff --git a/man1/skopeo.1 b/man1/skopeo.1 deleted file mode 100644 index a0530589..00000000 --- a/man1/skopeo.1 +++ /dev/null @@ -1,167 +0,0 @@ -.\" To review this file formatted -.\" groff -man -Tascii skopeo.1 -.\" -.de FN -\fI\|\\$1\|\fP -.. -.TH "skopeo" "1" "2016-04-21" "Linux" "Linux Programmer's Manual" -.SH NAME -skopeo \(em Various operations with container images images and container image registries -.SH SYNOPSIS -\fBskopeo\fP [\fIglobal options\fP] \fIcommand\fP [\fIcommand options\fP] -.SH DESCRIPTION -\fBskopeo\fR is a command line utility providing various operations with container images and container image registries. - -For example, it is able to inspect a repository on a Docker registry and fetch image -layers. It fetches the repository's manifest and it is able to show you a \fBdocker inspect\fR-like json output about a -whole repository or a tag. This tool, in contrast to \fBdocker inspect\fR, helps you gather useful information about a -repository or a tag without requiring you to run \fBdocker pull\fR - e.g. - which tags are available for the given -repository? which labels the image has? - -It also allows you to copy container images between various registries, possibly converting them as necessary, -and to sign and verify images. -.SH GLOBAL OPTIONS -.TP -.B "--debug" -Enable debug output -.TP -\fB--username\fP \fIusername\fP -Use \fIusername\fP for accessing the registry -.TP -\fB--password\fP \fIpassword\fP -Use \fIpassword\fP for accessing the registry -.TP -\fB--cert-path\fP \fIpath\fP -Use certificates at \fIpath\fP (cert.pem, key.pem) to connect to the registry -.TP -\fB--tls-verify\fP \fIbool-value\fP -Verify certificates -.TP -.B "--help, -h" -Show help -.TP -.B "--version, -v" -print the version number -.SH IMAGE NAMES -Most commands refer to container images, using a \fItransport\fP\fB:\fP\fIdetails\fP format. -The following formats are supported: -.TP -\fBatomic:\fP\fInamespace\fP\fB/\fP\fIstream\fP\fB:\fP\fItag\fP -An image in the current project of the current default Atomic Registry. -The current project and Atomic Registry instance are by default read from \fB~/.kube/config\fP, -which is set e.g. using \fB(oc login)\fP. -.TP -\fBdir:\fP\fIpath\fP -An existing local directory \fIpath\fP -storing the manifest, layer tarballs and signatures as individual files. -This is a non-standardized format, primarily useful for debugging or noninvasive container inspection. -.TP -\fBdocker://\fP\fIdocker-reference\fP -An image in a registry implementing the “Docker Registry HTTP API V2”. -By default, uses the authorization state in \fB~/.docker/config.json\fP, -which is set e.g. using \fB(docker login)\fP. -.TP -\fBoci:\fP\fIpath\fP\fB:\fP\fItag\fP -An image \fItag\fP in a directory compliant with “Open Container Image Image Layout Specification” -at \fIpath\fP. - - -.SH COMMANDS -.\" ========== skopeo copy ========== -.TP -\fBskopeo copy\fP [\fB--sign-by=\fP\fIkey-ID\fP] \fIsource-image\fP \fIdestination-image\fP -Copy an image (manifest, filesystem layers, signatures) from one location to another. -.I source-image -and -.I destination-image -use the “image name” format described above . - -With \fB--sign-by=\fP\fIkey-ID\fP, -add a signature using that key ID for an image name corresponding to \fBdestination-image\fR. - -Existing signatures, if any, are preserved as well. - - -.\" ========== skopeo delete ========== -.TP -\fBskopeo delete\fP \fIimage-name\fP -Mark image \fIimage-name\fP for deletion. You must then run docker registry garabage collection to recover the disk space. E.g., -.sp -\fBdocker exec -it registry bin/registry \\ -.br -garbage-collect /etc/docker/registry/config.yml\fR -.sp 2 -Additionally, the registry must allow deletions by setting \fB\%REGISTRY_STORAGE_DELETE_ENABLED=true\fR -for the registry daemon. - - -.\" ========== skopeo inspect ========== -.TP -\fBskopeo inspect\fP [\fB--raw\fP] \fIimage-name\fP -Return low-level information about \fIimage-name\fP in a registry. - -.B "--raw" -output raw manifest, default is to format in JSON. - - -.\" ========== skopeo layers ========== -.TP -\fBskopeo layers\fP \fIimage-name\fP -Get layers of \fIimage-name\fP. - - -.\" ========== skopeo standalone-sign ========== -.TP -\fBskopeo standalone-sign\fP \fImanifest\fP \fIdocker-reference\fP \fIkey-fingerprint\fP \%\fB--output\fP|\fB-o\fP \fIsignature\fP -Create a signature using local files. -This is primarily a debugging tool, or useful for special cases, -and usually should not be a part of your normal operational workflow; -use \fB(skopeo copy --sign-by)\fP instead to publish and sign an image in one step. - -.I manifest -Path to a file containing the image manifest -.br -.I docker-reference -A docker reference to identify the image with -.br -.I key-fingerprint -Key identity to use for signing -.br -.I signature -Output file - - -.\" ========== skopeo standalone-verify ========== -.TP -\fBskopeo standalone-verify\fP \fImanifest\fP \fIdocker-reference\fP \fIkey-fingerprint\fP \%\fIsignature\fP -Verify a signature using local files, digest will be printed on success. -This is primarily a debugging tool and should not be part of your normal operational workflow. - -\fINote\fP: 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. - -.I manifest -Path to a file containing the image manifest -.br -.I docker-reference -A docker reference expected to identify the image in the signature -.br -.I key-fingerprint -Expected identity of the signing key. -.br -.I signature -Path to the signature file - - -.\" ========== skopeo help ========== -.TP -\fBskopeo help\fR [\fIcommand\fP] -Show help for \fBskopeo\fR - - -.SH AUTHORS -Antonio Murdaca -.br -Miloslav Trmac -.br -Jhon Honce -