mirror of
https://github.com/containers/skopeo.git
synced 2025-09-15 22:39:41 +00:00
Comprehensively rework the man page
Among other minor changes: - Do not duplicate synopses of the subcommands; use a generic synopsis at the top, and detailed subcommand synopses only when documenting the subcommands. - Use the conventions documented in man-pages(7), in particular using italic for replaceable values. - Add a section documenting the transport:details reference format, and list the supported transports. - Relax the warning about standalone-sign.
This commit is contained in:
Miloslav Trmač
189
man1/skopeo.1
189
man1/skopeo.1
@@ -6,64 +6,86 @@
|
||||
..
|
||||
.TH "skopeo" "1" "2016-04-21" "Linux" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
skopeo \(em Inspect Docker images and repositories on registries
|
||||
skopeo \(em Various operations with container images images and container image registries
|
||||
.SH SYNOPSIS
|
||||
\fBskopeo copy\fR [\fB--sign-by=\fRkey-ID] source-location destination-location
|
||||
.PP
|
||||
\fBskopeo delete\fR source-location
|
||||
.PP
|
||||
\fBskopeo inspect\fR image-name [\fB--raw\fR]
|
||||
.PP
|
||||
\fBskopeo layers\fR image-name
|
||||
.PP
|
||||
\fBskopeo standalone-sign\fR manifest docker-reference key-fingerprint \%\fB--output\fR|\fB-o\fR signature
|
||||
.PP
|
||||
\fBskopeo standalone-verify\fR manifest docker-reference key-fingerprint \%signature
|
||||
.PP
|
||||
\fBskopeo help\fR [command]
|
||||
\fBskopeo\fP [\fIglobal options\fP] \fIcommand\fP [\fIcommand options\fP]
|
||||
.SH DESCRIPTION
|
||||
\fBskopeo\fR is a command line utility which is able to inspect a repository on a Docker registry and fetch images
|
||||
\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?
|
||||
.SH OPTIONS
|
||||
|
||||
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
|
||||
.PP
|
||||
.B "--username"
|
||||
Username to use to authenicate to the given registry
|
||||
.PP
|
||||
.B --password
|
||||
Password to use to authenicate to the given registry
|
||||
.PP
|
||||
.B "--cert-path"
|
||||
Path to certificates to use to authenicate to the given registry (cert.pem, key.pem)
|
||||
.PP
|
||||
.B "--tls-verify"
|
||||
Whether to verify certificates or not
|
||||
.PP
|
||||
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
|
||||
.PP
|
||||
.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
|
||||
.B copy
|
||||
\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.
|
||||
.sp
|
||||
.B source-location
|
||||
.I source-image
|
||||
and
|
||||
.B destination-location
|
||||
can be \fB\%docker://\fRdocker-reference, \fBdir:\fRlocal-path, or \fBatomic:\fRimagestream-name\fB:\fRtag .
|
||||
.sp
|
||||
\fB\-\-sign\-by=\fRkey-id
|
||||
Add a signature by the specified key ID for image name corresponding to \fBdestination-location\fR.
|
||||
.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
|
||||
.B delete
|
||||
Mark an image for deletion. You must then run docker registry garabage collection to recover the disk space. E.g.,
|
||||
\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
|
||||
@@ -71,56 +93,71 @@ 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
|
||||
.B inspect
|
||||
Return low-level information on images in a registry
|
||||
.sp
|
||||
.B image-name
|
||||
name of image to retrieve information about
|
||||
.br
|
||||
\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
|
||||
output raw manifest, default is to format in JSON.
|
||||
|
||||
|
||||
.\" ========== skopeo layers ==========
|
||||
.TP
|
||||
.B layers
|
||||
Get image layers
|
||||
.sp
|
||||
.B image-name
|
||||
name of the image to retrieve layers
|
||||
\fBskopeo layers\fP \fIimage-name\fP
|
||||
Get layers of \fIimage-name\fP.
|
||||
|
||||
|
||||
.\" ========== skopeo standalone-sign ==========
|
||||
.TP
|
||||
.B standalone-sign
|
||||
\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 and should not be part of your normal operational workflow.
|
||||
.sp
|
||||
.B manifest
|
||||
path to file containing manifest of image
|
||||
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
|
||||
.B docker-reference
|
||||
docker reference of blob to be signed
|
||||
.I docker-reference
|
||||
A docker reference to identify the image with
|
||||
.br
|
||||
.B key-fingerprint
|
||||
key identity to use for signing
|
||||
.I key-fingerprint
|
||||
Key identity to use for signing
|
||||
.br
|
||||
.B ""--output, -o"
|
||||
write signature to given file
|
||||
.I signature
|
||||
Output file
|
||||
|
||||
|
||||
.\" ========== skopeo standalone-verify ==========
|
||||
.TP
|
||||
.B standalone-verify
|
||||
\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.
|
||||
.sp
|
||||
.B manifest
|
||||
Path to file containing manifest of image
|
||||
|
||||
\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
|
||||
.B docker-reference
|
||||
docker reference of signed blob
|
||||
.I docker-reference
|
||||
A docker reference expected to identify the image in the signature
|
||||
.br
|
||||
.B key-fingerprint
|
||||
key identity to use for verification
|
||||
.I key-fingerprint
|
||||
Expected identity of the signing key.
|
||||
.br
|
||||
.B signature
|
||||
Path to file containing signature
|
||||
.I signature
|
||||
Path to the signature file
|
||||
|
||||
|
||||
.\" ========== skopeo help ==========
|
||||
.TP
|
||||
.B help
|
||||
show help for \fBskopeo\fR
|
||||
\fBskopeo help\fR [\fIcommand\fP]
|
||||
Show help for \fBskopeo\fR
|
||||
|
||||
|
||||
.SH AUTHORS
|
||||
Antonio Murdaca <runcom@redhat.com>
|
||||
.br
|
||||
|
||||
Reference in New Issue
Block a user