182 lines
7.1 KiB
Groff
182 lines
7.1 KiB
Groff
'\" t
|
|
.nh
|
|
.TH podman-search 1
|
|
.SH NAME
|
|
podman-search \- Search a registry for an image
|
|
|
|
.SH SYNOPSIS
|
|
\fBpodman search\fP [\fIoptions\fP] \fIterm\fP
|
|
|
|
.SH DESCRIPTION
|
|
\fBpodman search\fP searches a registry or a list of registries for a matching image.
|
|
The user can specify which registry to search by prefixing the registry in the search term
|
|
(e.g., \fBregistry.fedoraproject.org/fedora\fP). By default, all
|
|
unqualified-search registries in \fBcontainers-registries.conf(5)\fR are used.
|
|
|
|
.PP
|
|
The default number of results is 25. The number of results can be limited using the \fB--limit\fP flag.
|
|
If more than one registry is being searched, the limit is applied to each registry. The output can be filtered
|
|
using the \fB--filter\fP flag. To get all available images in a registry without a specific
|
|
search term, the user can just enter the registry name with a trailing "/" (example \fBregistry.fedoraproject.org/\fP).
|
|
|
|
.PP
|
|
Note that \fBpodman search\fP is not a reliable way to determine the presence or existence of an image.
|
|
The search behavior of the v1 and v2 Docker distribution API is specific to the implementation of each registry.
|
|
Some registries may not support searching at all.
|
|
Further note that searching without a search term only works for registries that implement the v2 API.
|
|
|
|
.PP
|
|
\fBpodman [GLOBAL OPTIONS]\fP
|
|
|
|
.PP
|
|
\fBpodman search [GLOBAL OPTIONS]\fP
|
|
|
|
.PP
|
|
\fBpodman search [OPTIONS] TERM\fP
|
|
|
|
.SH OPTIONS
|
|
.SS \fB--authfile\fP=\fIpath\fP
|
|
Path of the authentication file. Default is \fB${XDG_RUNTIME_DIR}/containers/auth.json\fR on Linux, and \fB$HOME/.config/containers/auth.json\fR on Windows/macOS.
|
|
The file is created by \fBpodman login\fP\&. If the authorization state is not found there, \fB$HOME/.docker/config.json\fR is checked, which is set using \fBdocker login\fP\&.
|
|
|
|
.PP
|
|
Note: There is also the option to override the default path of the authentication file by setting the \fBREGISTRY_AUTH_FILE\fR environment variable. This can be done with \fBexport REGISTRY_AUTH_FILE=\fIpath\fP\fP\&.
|
|
|
|
.SS \fB--cert-dir\fP=\fIpath\fP
|
|
Use certificates at \fIpath\fP (*\&.crt, *\&.cert, *\&.key) to connect to the registry. (Default: /etc/containers/certs.d)
|
|
For details, see \fBcontainers-certs.d(5)\fP\&.
|
|
(This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines)
|
|
|
|
.SS \fB--compatible\fP
|
|
After the name and the description, also show the stars, official and automated descriptors as Docker does.
|
|
Podman does not show these descriptors by default since they are not supported by most public container registries.
|
|
|
|
.SS \fB--creds\fP=\fI[username[:password]]\fP
|
|
The [username[:password]] to use to authenticate with the registry, if required.
|
|
If one or both values are not supplied, a command line prompt appears and the
|
|
value can be entered. The password is entered without echo.
|
|
|
|
.PP
|
|
Note that the specified credentials are only used to authenticate against
|
|
target registries. They are not used for mirrors or when the registry gets
|
|
rewritten (see \fBcontainers-registries.conf(5)\fR); to authenticate against those
|
|
consider using a \fBcontainers-auth.json(5)\fR file.
|
|
|
|
.SS \fB--filter\fP, \fB-f\fP=\fIfilter\fP
|
|
Filter output based on conditions provided (default [])
|
|
|
|
.PP
|
|
Supported filters are:
|
|
.IP \(bu 2
|
|
stars (int) - minimum number of stars required for images to show
|
|
.IP \(bu 2
|
|
is-automated (boolean - true | false) - is the image automated or not
|
|
.IP \(bu 2
|
|
is-official (boolean - true | false) - is the image official or not
|
|
|
|
.SS \fB--format\fP=\fIformat\fP
|
|
Change the output format to a Go template
|
|
|
|
.PP
|
|
Valid placeholders for the Go template are listed below:
|
|
|
|
.TS
|
|
allbox;
|
|
l l
|
|
l l .
|
|
\fB\fBPlaceholder\fP\fP \fB\fBDescription\fP\fP
|
|
\&.Automated "[OK]" if image is automated
|
|
\&.Description Image description
|
|
\&.Index Registry
|
|
\&.Name Image name
|
|
\&.Official "[OK]" if image is official
|
|
\&.Stars Star count of image
|
|
\&.Tag Repository tag
|
|
.TE
|
|
|
|
.PP
|
|
Note: use .Tag only if the --list-tags is set.
|
|
|
|
.SS \fB--help\fP, \fB-h\fP
|
|
Print usage statement
|
|
|
|
.SS \fB--limit\fP=\fIlimit\fP
|
|
Limit the number of results (default 25).
|
|
Note: The results from each registry is limited to this value.
|
|
Example if limit is 10 and two registries are being searched, the total
|
|
number of results is 20, 10 from each (if there are at least 10 matches in each).
|
|
The order of the search results is the order in which the API endpoint returns the results.
|
|
|
|
.SS \fB--list-tags\fP
|
|
List the available tags in the repository for the specified image.
|
|
\fBNote:\fP --list-tags requires the search term to be a fully specified image name.
|
|
The result contains the Image name and its tag, one line for every tag associated with the image.
|
|
|
|
.SS \fB--no-trunc\fP
|
|
Do not truncate the output (default \fIfalse\fP).
|
|
|
|
.SS \fB--tls-verify\fP
|
|
Require HTTPS and verify certificates when contacting registries (default: \fBtrue\fP).
|
|
If explicitly set to \fBtrue\fP, TLS verification is used.
|
|
If set to \fBfalse\fP, TLS verification is not used.
|
|
If not specified, TLS verification is used unless the target registry
|
|
is listed as an insecure registry in \fBcontainers-registries.conf(5)\fP
|
|
|
|
.SH EXAMPLES
|
|
Search for images containing the specified name, returning the first three images from each defined registry.
|
|
|
|
.EX
|
|
$ podman search --limit 3 fedora
|
|
NAME DESCRIPTION
|
|
registry.fedoraproject.org/f29/fedora-toolbox
|
|
registry.fedoraproject.org/f30/fedora-toolbox
|
|
registry.fedoraproject.org/f31/fedora-toolbox
|
|
docker.io/library/fedora Official Docker builds of Fedora
|
|
docker.io/kasmweb/fedora-37-desktop Fedora 37 desktop for Kasm Workspaces
|
|
docker.io/kasmweb/fedora-38-desktop Fedora 38 desktop for Kasm Workspaces
|
|
quay.io/fedora/fedora
|
|
quay.io/containerdisks/fedora # Fedora Containerdisk Images <img src="htt...
|
|
quay.io/fedora/fedora-minimal
|
|
.EE
|
|
|
|
.PP
|
|
Note that the Stars, Official and Automated descriptors are only available on Docker Hub and are hence not displayed by default.
|
|
|
|
.EX
|
|
$ podman search --format "{{.Name}}\\t{{.Stars}}\\t{{.Official}}" alpine --limit 3
|
|
docker.io/library/alpine 7956 [OK]
|
|
docker.io/alpine/git 192
|
|
docker.io/anapsix/alpine-java 474
|
|
quay.io/libpod/alpine 0
|
|
quay.io/vqcomms/alpine-tools 0
|
|
quay.io/wire/alpine-deps 0
|
|
.EE
|
|
|
|
.PP
|
|
Search and list tags for the specified image returning the first four images from each defined registry.
|
|
|
|
.EX
|
|
$ podman search --list-tags registry.access.redhat.com/ubi8 --limit 4
|
|
NAME TAG
|
|
registry.access.redhat.com/ubi8 8.4-211
|
|
registry.access.redhat.com/ubi8 8.4-206.1626828523-source
|
|
registry.access.redhat.com/ubi8 8.4-199
|
|
registry.access.redhat.com/ubi8 8.4-211-source
|
|
.EE
|
|
|
|
.PP
|
|
Note: This works only with registries that implement the v2 API. If tried with a v1 registry an error is returned.
|
|
|
|
.SH FILES
|
|
\fBregistries.conf\fP (\fB/etc/containers/registries.conf\fR)
|
|
|
|
.PP
|
|
registries.conf is the configuration file which specifies which container registries is consulted when completing image names which do not include a registry or domain portion.
|
|
|
|
.SH SEE ALSO
|
|
\fBpodman(1)\fP, \fBcontainers-registries(5)\fP
|
|
|
|
.SH HISTORY
|
|
January 2018, Originally compiled by Urvashi Mohnani umohnani@redhat.com
|
|
\[la]mailto:umohnani@redhat.com\[ra]
|