mirror of
https://github.com/containers/skopeo.git
synced 2025-07-30 22:20:20 +00:00
Merge pull request #153 from jwhonce/wip/issue-151
Convert man page to markdown format
This commit is contained in:
Miloslav Trmač
GitHub
commit
43273caab1
23
Makefile
23
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:
|
||||
|
||||
203
docs/skopeo.1.md
Normal file
203
docs/skopeo.1.md
Normal file
@ -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 <runcom@redhat.com>, Miloslav Trmac <mitr@redhat.com>, Jhon Honce <jhonce@redhat.com>
|
||||
|
||||
167
man1/skopeo.1
167
man1/skopeo.1
@ -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 <runcom@redhat.com>
|
||||
.br
|
||||
Miloslav Trmac <mitr@redhat.com>
|
||||
.br
|
||||
Jhon Honce <jhonce@redhat.com>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user