From f0e8640755569ba7da803f7c8f4589953939fad0 Mon Sep 17 00:00:00 2001 From: Ed Santiago Date: Tue, 16 Aug 2022 07:35:18 -0600 Subject: Man pages: refactor common options: authfile Refactor the --authfile option. My suggestion for review: 1) run hack/markdown-preprocess-review and immediately Ctrl-Q to quit out of diffuse, which is completely unusable for this many files; then 2) cd /tmp/markdown-preprocess-review.diffs/authfile - this is the directory created by the review script 3) rm podman-image-sign* podman-log* podman-search.1.md.in - because they're essentially identical to podman-create 4) rm podman-manifest-* podman-push.* - because they're 100% identical to podman-kube-play 5) rm podman-kube-play* - because it's apart-from-whitespace identical to podman-build (use "wdiff" to confirm) 6) rm podman-auto-update* - because that's the one I chose (hence == zzz-chosen.md) (You should obviously run your own diff/cmp before rm, to confirm my assertions about which files are identical). After all that, you have a manageable number of files which you can scan, read, diff against zzz-chosen.md, even run diffuse. This option is IMHO the poster child for why we need this kind of man page refactoring. Signed-off-by: Ed Santiago --- docs/source/markdown/.gitignore | 9 ++ docs/source/markdown/options/authfile.md | 6 + docs/source/markdown/podman-auto-update.1.md | 143 ----------------- docs/source/markdown/podman-auto-update.1.md.in | 139 +++++++++++++++++ docs/source/markdown/podman-build.1.md.in | 11 +- .../source/markdown/podman-container-runlabel.1.md | 93 ------------ .../markdown/podman-container-runlabel.1.md.in | 90 +++++++++++ docs/source/markdown/podman-create.1.md.in | 7 +- docs/source/markdown/podman-image-sign.1.md | 76 --------- docs/source/markdown/podman-image-sign.1.md.in | 71 +++++++++ docs/source/markdown/podman-kube-play.1.md.in | 8 +- docs/source/markdown/podman-login.1.md | 126 --------------- docs/source/markdown/podman-login.1.md.in | 121 +++++++++++++++ docs/source/markdown/podman-logout.1.md | 60 -------- docs/source/markdown/podman-logout.1.md.in | 55 +++++++ docs/source/markdown/podman-manifest-add.1.md | 135 ---------------- docs/source/markdown/podman-manifest-add.1.md.in | 129 ++++++++++++++++ docs/source/markdown/podman-manifest-push.1.md | 122 --------------- docs/source/markdown/podman-manifest-push.1.md.in | 116 ++++++++++++++ docs/source/markdown/podman-pull.1.md.in | 8 +- docs/source/markdown/podman-push.1.md | 169 --------------------- docs/source/markdown/podman-push.1.md.in | 163 ++++++++++++++++++++ docs/source/markdown/podman-run.1.md.in | 7 +- docs/source/markdown/podman-search.1.md | 150 ------------------ docs/source/markdown/podman-search.1.md.in | 145 ++++++++++++++++++ 25 files changed, 1049 insertions(+), 1110 deletions(-) create mode 100644 docs/source/markdown/options/authfile.md delete mode 100644 docs/source/markdown/podman-auto-update.1.md create mode 100644 docs/source/markdown/podman-auto-update.1.md.in delete mode 100644 docs/source/markdown/podman-container-runlabel.1.md create mode 100644 docs/source/markdown/podman-container-runlabel.1.md.in delete mode 100644 docs/source/markdown/podman-image-sign.1.md create mode 100644 docs/source/markdown/podman-image-sign.1.md.in delete mode 100644 docs/source/markdown/podman-login.1.md create mode 100644 docs/source/markdown/podman-login.1.md.in delete mode 100644 docs/source/markdown/podman-logout.1.md create mode 100644 docs/source/markdown/podman-logout.1.md.in delete mode 100644 docs/source/markdown/podman-manifest-add.1.md create mode 100644 docs/source/markdown/podman-manifest-add.1.md.in delete mode 100644 docs/source/markdown/podman-manifest-push.1.md create mode 100644 docs/source/markdown/podman-manifest-push.1.md.in delete mode 100644 docs/source/markdown/podman-push.1.md create mode 100644 docs/source/markdown/podman-push.1.md.in delete mode 100644 docs/source/markdown/podman-search.1.md create mode 100644 docs/source/markdown/podman-search.1.md.in (limited to 'docs/source') diff --git a/docs/source/markdown/.gitignore b/docs/source/markdown/.gitignore index 6689b5b71..70f1c2bd7 100644 --- a/docs/source/markdown/.gitignore +++ b/docs/source/markdown/.gitignore @@ -1,8 +1,17 @@ +podman-auto-update.1.md podman-build.1.md podman-container-clone.1.md +podman-container-runlabel.1.md podman-create.1.md +podman-image-sign.1.md podman-kube-play.1.md +podman-login.1.md +podman-logout.1.md +podman-manifest-add.1.md +podman-manifest-push.1.md podman-pod-clone.1.md podman-pod-create.1.md podman-pull.1.md +podman-push.1.md podman-run.1.md +podman-search.1.md diff --git a/docs/source/markdown/options/authfile.md b/docs/source/markdown/options/authfile.md new file mode 100644 index 000000000..d6198aa24 --- /dev/null +++ b/docs/source/markdown/options/authfile.md @@ -0,0 +1,6 @@ +#### **--authfile**=*path* + +Path of the authentication file. Default is `${XDG_RUNTIME_DIR}/containers/auth.json`, which is set using **[podman login](podman-login.1.md)**. +If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using **docker login**. + +Note: There is also the option to override the default path of the authentication file by setting the `REGISTRY_AUTH_FILE` environment variable. This can be done with **export REGISTRY_AUTH_FILE=_path_**. diff --git a/docs/source/markdown/podman-auto-update.1.md b/docs/source/markdown/podman-auto-update.1.md deleted file mode 100644 index 992c87432..000000000 --- a/docs/source/markdown/podman-auto-update.1.md +++ /dev/null @@ -1,143 +0,0 @@ -% podman-auto-update(1) - -## NAME -podman\-auto-update - Auto update containers according to their auto-update policy - -## SYNOPSIS -**podman auto-update** [*options*] - -## DESCRIPTION -**podman auto-update** looks up containers with a specified `io.containers.autoupdate` label (i.e., the auto-update policy). - -If the label is present and set to `registry`, Podman reaches out to the corresponding registry to check if the image has been updated. The label `image` is an alternative to `registry` maintained for backwards compatibility. -An image is considered updated if the digest in the local storage is different than the one of the remote image. -If an image must be updated, Podman pulls it down and restarts the systemd unit executing the container. - -The registry policy requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. -This enforcement is necessary to know which image to actually check and pull. -If an image ID was used, Podman would not know which image to check/pull anymore. - -Alternatively, if the autoupdate label is set to `local`, Podman will compare the image a container is using to the image with its raw name in local storage. -If an image is updated locally, Podman simply restarts the systemd unit executing the container. - -If `io.containers.autoupdate.authfile` label is present, Podman reaches out to the corresponding authfile when pulling images. - -At container-creation time, Podman looks up the `PODMAN_SYSTEMD_UNIT` environment variable and stores it verbatim in the container's label. -This variable is now set by all systemd units generated by **[podman-generate-systemd](podman-generate-systemd.1.md)** and is set to `%n` (i.e., the name of systemd unit starting the container). -This data is then being used in the auto-update sequence to instruct systemd (via DBUS) to restart the unit and hence to restart the container. - -Note that **podman auto-update** relies on systemd. The systemd units are expected to be generated with **[podman-generate-systemd --new](podman-generate-systemd.1.md#--new)**, or similar units that create new containers in order to run the updated images. -Systemd units that start and stop a container cannot run a new image. - -### Systemd Unit and Timer - -Podman ships with a `podman-auto-update.service` systemd unit. This unit is triggered daily at midnight by the `podman-auto-update.timer` systemd timer. The timer can be altered for custom time-based updates if desired. The unit can further be invoked by other systemd units (e.g., via the dependency tree) or manually via **systemctl start podman-auto-update.service**. - -## OPTIONS -#### **--authfile**=*path* - -Path of the authentication file. Default is `${XDG_RUNTIME_DIR}/containers/auth.json`, which is set using **[podman login](podman-login.1.md)**. -If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using **docker login**. - -Note: There is also the option to override the default path of the authentication file by setting the `REGISTRY_AUTH_FILE` environment variable. This can be done with **export REGISTRY_AUTH_FILE=_path_**. - -#### **--dry-run** - -Check for the availability of new images but do not perform any pull operation or restart any service or container. -The `UPDATED` field indicates the availability of a new image with "pending". - -#### **--format**=*format* - -Change the default output format. This can be of a supported type like 'json' or a Go template. -Valid placeholders for the Go template are listed below: - -| **Placeholder** | **Description** | -| --------------- | -------------------------------------- | -| .Unit | Name of the systemd unit | -| .ContainerName | Name of the container | -| .ContainerID | ID of the container | -| .Container | ID and name of the container | -| .Image | Name of the image | -| .Policy | Auto-update policy of the container | -| .Updated | Update status: true,false,failed | - -#### **--rollback** - -If restarting a systemd unit after updating the image has failed, rollback to using the previous image and restart the unit another time. Default is true. - -Please note that detecting if a systemd unit has failed is best done by the container sending the READY message via SDNOTIFY. This way, restarting the unit will wait until having received the message or a timeout kicked in. Without that, restarting the systemd unit may succeed even if the container has failed shortly after. - -For a container to send the READY message via SDNOTIFY it must be created with the `--sdnotify=container` option (see podman-run(1)). The application running inside the container can then execute `systemd-notify --ready` when ready or use the sdnotify bindings of the specific programming language (e.g., sd_notify(3)). - - -## EXAMPLES -Autoupdate with registry policy - -``` -### Start a container -$ podman run --label "io.containers.autoupdate=registry" \ - --label "io.containers.autoupdate.authfile=/some/authfile.json" \ - -d --name=test registry.fedoraproject.org/fedora:latest sleep infinity -bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d - -### Generate a systemd unit for this container -$ podman generate systemd --new --files bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d -/home/user/container-bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d.service - -### Load the new systemd unit and start it -$ mv ./container-bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d.service ~/.config/systemd/user/container-test.service -$ systemctl --user daemon-reload - -### If the previously created containers or pods are using shared resources, such as ports, make sure to remove them before starting the generated systemd units. -$ podman stop bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d -$ podman rm bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d - -$ systemctl --user start container-test.service - -### Check if a newer image is available -$ podman auto-update --dry-run --format "{{.Image}} {{.Updated}}" -registry.fedoraproject.org/fedora:latest pending - -### Autoupdate the services -$ podman auto-update -UNIT CONTAINER IMAGE POLICY UPDATED -container-test.service 08fd34e533fd (test) registry.fedoraproject.org/fedora:latest registry false -``` - -Autoupdate with local policy - -``` -### Start a container -$ podman run --label "io.containers.autoupdate=local" \ - -d busybox:latest top -be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338 - -### Generate a systemd unit for this container -$ podman generate systemd --new --files be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338 -/home/user/container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service - -### Load the new systemd unit and start it -$ mv ./container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service ~/.config/systemd/user -$ systemctl --user daemon-reload - -### If the previously created containers or pods are using shared resources, such as ports, make sure to remove them before starting the generated systemd units. -$ podman stop be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338 -$ podman rm be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338 - -$ systemctl --user start container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service - -### Get the name of the container -$ podman ps -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -01f5c8113e84 docker.io/library/busybox:latest top 2 seconds ago Up 3 seconds ago inspiring_galileo - -### Modify the image -$ podman commit --change CMD=/bin/bash inspiring_galileo busybox:latest - -### Auto-update the container -$ podman auto-update -[...] -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-run(1)](podman-run.1.md)**, **sd_notify(3)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)** diff --git a/docs/source/markdown/podman-auto-update.1.md.in b/docs/source/markdown/podman-auto-update.1.md.in new file mode 100644 index 000000000..bc92d6165 --- /dev/null +++ b/docs/source/markdown/podman-auto-update.1.md.in @@ -0,0 +1,139 @@ +% podman-auto-update(1) + +## NAME +podman\-auto-update - Auto update containers according to their auto-update policy + +## SYNOPSIS +**podman auto-update** [*options*] + +## DESCRIPTION +**podman auto-update** looks up containers with a specified `io.containers.autoupdate` label (i.e., the auto-update policy). + +If the label is present and set to `registry`, Podman reaches out to the corresponding registry to check if the image has been updated. The label `image` is an alternative to `registry` maintained for backwards compatibility. +An image is considered updated if the digest in the local storage is different than the one of the remote image. +If an image must be updated, Podman pulls it down and restarts the systemd unit executing the container. + +The registry policy requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. +This enforcement is necessary to know which image to actually check and pull. +If an image ID was used, Podman would not know which image to check/pull anymore. + +Alternatively, if the autoupdate label is set to `local`, Podman will compare the image a container is using to the image with its raw name in local storage. +If an image is updated locally, Podman simply restarts the systemd unit executing the container. + +If `io.containers.autoupdate.authfile` label is present, Podman reaches out to the corresponding authfile when pulling images. + +At container-creation time, Podman looks up the `PODMAN_SYSTEMD_UNIT` environment variable and stores it verbatim in the container's label. +This variable is now set by all systemd units generated by **[podman-generate-systemd](podman-generate-systemd.1.md)** and is set to `%n` (i.e., the name of systemd unit starting the container). +This data is then being used in the auto-update sequence to instruct systemd (via DBUS) to restart the unit and hence to restart the container. + +Note that **podman auto-update** relies on systemd. The systemd units are expected to be generated with **[podman-generate-systemd --new](podman-generate-systemd.1.md#--new)**, or similar units that create new containers in order to run the updated images. +Systemd units that start and stop a container cannot run a new image. + +### Systemd Unit and Timer + +Podman ships with a `podman-auto-update.service` systemd unit. This unit is triggered daily at midnight by the `podman-auto-update.timer` systemd timer. The timer can be altered for custom time-based updates if desired. The unit can further be invoked by other systemd units (e.g., via the dependency tree) or manually via **systemctl start podman-auto-update.service**. + +## OPTIONS + +@@option authfile + +#### **--dry-run** + +Check for the availability of new images but do not perform any pull operation or restart any service or container. +The `UPDATED` field indicates the availability of a new image with "pending". + +#### **--format**=*format* + +Change the default output format. This can be of a supported type like 'json' or a Go template. +Valid placeholders for the Go template are listed below: + +| **Placeholder** | **Description** | +| --------------- | -------------------------------------- | +| .Unit | Name of the systemd unit | +| .ContainerName | Name of the container | +| .ContainerID | ID of the container | +| .Container | ID and name of the container | +| .Image | Name of the image | +| .Policy | Auto-update policy of the container | +| .Updated | Update status: true,false,failed | + +#### **--rollback** + +If restarting a systemd unit after updating the image has failed, rollback to using the previous image and restart the unit another time. Default is true. + +Please note that detecting if a systemd unit has failed is best done by the container sending the READY message via SDNOTIFY. This way, restarting the unit will wait until having received the message or a timeout kicked in. Without that, restarting the systemd unit may succeed even if the container has failed shortly after. + +For a container to send the READY message via SDNOTIFY it must be created with the `--sdnotify=container` option (see podman-run(1)). The application running inside the container can then execute `systemd-notify --ready` when ready or use the sdnotify bindings of the specific programming language (e.g., sd_notify(3)). + + +## EXAMPLES +Autoupdate with registry policy + +``` +### Start a container +$ podman run --label "io.containers.autoupdate=registry" \ + --label "io.containers.autoupdate.authfile=/some/authfile.json" \ + -d --name=test registry.fedoraproject.org/fedora:latest sleep infinity +bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d + +### Generate a systemd unit for this container +$ podman generate systemd --new --files bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d +/home/user/container-bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d.service + +### Load the new systemd unit and start it +$ mv ./container-bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d.service ~/.config/systemd/user/container-test.service +$ systemctl --user daemon-reload + +### If the previously created containers or pods are using shared resources, such as ports, make sure to remove them before starting the generated systemd units. +$ podman stop bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d +$ podman rm bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d + +$ systemctl --user start container-test.service + +### Check if a newer image is available +$ podman auto-update --dry-run --format "{{.Image}} {{.Updated}}" +registry.fedoraproject.org/fedora:latest pending + +### Autoupdate the services +$ podman auto-update +UNIT CONTAINER IMAGE POLICY UPDATED +container-test.service 08fd34e533fd (test) registry.fedoraproject.org/fedora:latest registry false +``` + +Autoupdate with local policy + +``` +### Start a container +$ podman run --label "io.containers.autoupdate=local" \ + -d busybox:latest top +be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338 + +### Generate a systemd unit for this container +$ podman generate systemd --new --files be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338 +/home/user/container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service + +### Load the new systemd unit and start it +$ mv ./container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service ~/.config/systemd/user +$ systemctl --user daemon-reload + +### If the previously created containers or pods are using shared resources, such as ports, make sure to remove them before starting the generated systemd units. +$ podman stop be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338 +$ podman rm be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338 + +$ systemctl --user start container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service + +### Get the name of the container +$ podman ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +01f5c8113e84 docker.io/library/busybox:latest top 2 seconds ago Up 3 seconds ago inspiring_galileo + +### Modify the image +$ podman commit --change CMD=/bin/bash inspiring_galileo busybox:latest + +### Auto-update the container +$ podman auto-update +[...] +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-generate-systemd(1)](podman-generate-systemd.1.md)**, **[podman-run(1)](podman-run.1.md)**, **sd_notify(3)**, **[systemd.unit(5)](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)** diff --git a/docs/source/markdown/podman-build.1.md.in b/docs/source/markdown/podman-build.1.md.in index c0cf08f3c..b49beb3bf 100644 --- a/docs/source/markdown/podman-build.1.md.in +++ b/docs/source/markdown/podman-build.1.md.in @@ -68,16 +68,7 @@ pulled, if the build uses one, to the provided value instead of using the architecture of the build host. (Examples: arm, arm64, 386, amd64, ppc64le, s390x) -#### **--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`. - -Note: You can also override the default path of the authentication file by -setting the REGISTRY\_AUTH\_FILE environment variable. -`export REGISTRY_AUTH_FILE=path` +@@option authfile #### **--build-arg**=*arg=value* diff --git a/docs/source/markdown/podman-container-runlabel.1.md b/docs/source/markdown/podman-container-runlabel.1.md deleted file mode 100644 index 40e5392ce..000000000 --- a/docs/source/markdown/podman-container-runlabel.1.md +++ /dev/null @@ -1,93 +0,0 @@ -% podman-container-runlabel(1) - -## NAME -podman-container-runlabel - Executes a command as described by a container-image label - -## SYNOPSIS -**podman container runlabel** [*options*] *label* *image* [*arg...*] - -## DESCRIPTION -**podman container runlabel** reads the specified `label` of the `image` and executes it as command on the host. If the label does not exist, Podman will exit with an error. Additional arguments will be appended to the command. - -Historically, container images describe the contents (e.g., layers) and how a container runtime (e.g., crun(1) or runc(1)) should execute the container. For instance, an image may set the environment and the command in its configuration. However, a container image cannot directly specify how a container engine such as Podman should execute it. For instance, an image configuration does not include information about log drivers, namespaces or which capabilities it needs to run correctly. - -`podman container runlabel` addresses the limitation of container images in a simple yet efficient way. Podman will read the contents of the label and interpret it as a command that will be executed on the host. This way an image can describe exactly how it should be executed by Podman. For instance, a label with the content `/usr/bin/podman run -d --pid=host --privileged \${IMAGE}` instructs the image to be executed in a detached, privileged container that is using the PID namespace of the host. This lifts the self-description of a container image from "what" to "how". - -Please note that the `runlabel` command is intended to be run in trusted environments exclusively. Using the command on untrusted images is not recommended. - -## VARIABLES - -The contents of a label may refer to the following variables which will be substituted while processing the label. - -**IMAGE** -The name of the image. When executing `podman container runlabel label fedora` the `IMAGE` variable will be replaced with `fedora`. Valid formats are `IMAGE`, `$IMAGE`, `${IMAGE}` and `=IMAGE`. - -**NAME** -As specified by the `--name` option. The format is identical to the one of the IMAGE attribute. - -**PWD** -Will be replaced with the current working directory. - -## OPTIONS -#### **--authfile**=*path* - -Path of the containers-auth.json(5) 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`. - -Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` - -#### **--cert-dir**=*path* - -Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d) -Please refer to containers-certs.d(5) for details. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--creds**=*[username[:password]]* - -The [username[:password]] to use to authenticate with the registry if required. If one or both values are not supplied, a command line prompt will appear and the value can be entered. The password is entered without echo. - -#### **--display** - -Display the label's value of the image having populated its environment variables. The runlabel command will not execute if --display is specified. - -#### **--help**, **-h** -Print usage statement - -#### **--name**, **-n**=*name* - -Use this name for creating content for the container. If not specified, name defaults to the name of the image. - -#### **--quiet**, **-q** - -Suppress output information when pulling images - -#### **--replace** - -If a container exists of the default or given name, as needed it will be stopped, deleted and a new container will be created from this image. - -#### **--tls-verify** - -Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, TLS verification will be used unless the target registry is listed as an insecure registry in containers-registries.conf(5). - -## EXAMPLES - -Execute the `run` label of an image called foobar. -``` -$ podman container runlabel run foobar -``` - -Execute the `install` label of an image called foobar with additional arguments. -``` -$ podman container runlabel install foobar apples oranges -``` - -Display the contents of the `run` label of image foobar. -``` -$ podman container runlabel --display run foobar -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[crun(1)](https://github.com/containers/crun/blob/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/master/man/runc.8.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-auth.json(5)](https://github.com/containers/image/blob/main/docs/containers-auth.json.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)** - -## HISTORY -August 2021, Refinements by Valentin Rothberg (rothberg at redhat dot com) - -September 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) diff --git a/docs/source/markdown/podman-container-runlabel.1.md.in b/docs/source/markdown/podman-container-runlabel.1.md.in new file mode 100644 index 000000000..7f462bf70 --- /dev/null +++ b/docs/source/markdown/podman-container-runlabel.1.md.in @@ -0,0 +1,90 @@ +% podman-container-runlabel(1) + +## NAME +podman-container-runlabel - Executes a command as described by a container-image label + +## SYNOPSIS +**podman container runlabel** [*options*] *label* *image* [*arg...*] + +## DESCRIPTION +**podman container runlabel** reads the specified `label` of the `image` and executes it as command on the host. If the label does not exist, Podman will exit with an error. Additional arguments will be appended to the command. + +Historically, container images describe the contents (e.g., layers) and how a container runtime (e.g., crun(1) or runc(1)) should execute the container. For instance, an image may set the environment and the command in its configuration. However, a container image cannot directly specify how a container engine such as Podman should execute it. For instance, an image configuration does not include information about log drivers, namespaces or which capabilities it needs to run correctly. + +`podman container runlabel` addresses the limitation of container images in a simple yet efficient way. Podman will read the contents of the label and interpret it as a command that will be executed on the host. This way an image can describe exactly how it should be executed by Podman. For instance, a label with the content `/usr/bin/podman run -d --pid=host --privileged \${IMAGE}` instructs the image to be executed in a detached, privileged container that is using the PID namespace of the host. This lifts the self-description of a container image from "what" to "how". + +Please note that the `runlabel` command is intended to be run in trusted environments exclusively. Using the command on untrusted images is not recommended. + +## VARIABLES + +The contents of a label may refer to the following variables which will be substituted while processing the label. + +**IMAGE** +The name of the image. When executing `podman container runlabel label fedora` the `IMAGE` variable will be replaced with `fedora`. Valid formats are `IMAGE`, `$IMAGE`, `${IMAGE}` and `=IMAGE`. + +**NAME** +As specified by the `--name` option. The format is identical to the one of the IMAGE attribute. + +**PWD** +Will be replaced with the current working directory. + +## OPTIONS + +@@option authfile + +#### **--cert-dir**=*path* + +Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d) +Please refer to containers-certs.d(5) for details. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--creds**=*[username[:password]]* + +The [username[:password]] to use to authenticate with the registry if required. If one or both values are not supplied, a command line prompt will appear and the value can be entered. The password is entered without echo. + +#### **--display** + +Display the label's value of the image having populated its environment variables. The runlabel command will not execute if --display is specified. + +#### **--help**, **-h** +Print usage statement + +#### **--name**, **-n**=*name* + +Use this name for creating content for the container. If not specified, name defaults to the name of the image. + +#### **--quiet**, **-q** + +Suppress output information when pulling images + +#### **--replace** + +If a container exists of the default or given name, as needed it will be stopped, deleted and a new container will be created from this image. + +#### **--tls-verify** + +Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, TLS verification will be used unless the target registry is listed as an insecure registry in containers-registries.conf(5). + +## EXAMPLES + +Execute the `run` label of an image called foobar. +``` +$ podman container runlabel run foobar +``` + +Execute the `install` label of an image called foobar with additional arguments. +``` +$ podman container runlabel install foobar apples oranges +``` + +Display the contents of the `run` label of image foobar. +``` +$ podman container runlabel --display run foobar +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[crun(1)](https://github.com/containers/crun/blob/main/crun.1.md)**, **[runc(8)](https://github.com/opencontainers/runc/blob/master/man/runc.8.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-auth.json(5)](https://github.com/containers/image/blob/main/docs/containers-auth.json.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)** + +## HISTORY +August 2021, Refinements by Valentin Rothberg (rothberg at redhat dot com) + +September 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) diff --git a/docs/source/markdown/podman-create.1.md.in b/docs/source/markdown/podman-create.1.md.in index f5301c60a..3e6b07225 100644 --- a/docs/source/markdown/podman-create.1.md.in +++ b/docs/source/markdown/podman-create.1.md.in @@ -83,12 +83,7 @@ error. It can even pretend to be a TTY (this is what most command line executables expect) and pass along signals. The **-a** option can be set for each of stdin, stdout, and stderr. -#### **--authfile**=*path* - -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json - -Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE -environment variable. `export REGISTRY_AUTH_FILE=path` +@@option authfile @@option blkio-weight diff --git a/docs/source/markdown/podman-image-sign.1.md b/docs/source/markdown/podman-image-sign.1.md deleted file mode 100644 index 035e10743..000000000 --- a/docs/source/markdown/podman-image-sign.1.md +++ /dev/null @@ -1,76 +0,0 @@ -% podman-image-sign(1) - -## NAME -podman-image-sign - Create a signature for an image - -## SYNOPSIS -**podman image sign** [*options*] *image* [*image* ...] - -## DESCRIPTION -**podman image sign** will create a local signature for one or more local images that have -been pulled from a registry. The signature will be written to a directory -derived from the registry configuration files in `$HOME/.config/containers/registries.d` if it exists, -otherwise `/etc/containers/registries.d` (unless overridden at compile-time), see **containers-registries.d(5)** for more information. -By default, the signature will be written into `/var/lib/containers/sigstore` for root and `$HOME/.local/share/containers/sigstore` for non-root users - -## OPTIONS - -#### **--all**, **-a** - -Sign all the manifests of the multi-architecture image (default false). - -#### **--authfile**=*path* - -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json - -Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE -environment variable. `export REGISTRY_AUTH_FILE=path` - -#### **--cert-dir**=*path* - -Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d) -Please refer to containers-certs.d(5) for details. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--directory**, **-d**=*dir* - -Store the signatures in the specified directory. Default: /var/lib/containers/sigstore - -#### **--help**, **-h** - -Print usage statement. - -#### **--sign-by**=*identity* - -Override the default identity of the signature. - -## EXAMPLES -Sign the busybox image with the identity of foo@bar.com with a user's keyring and save the signature in /tmp/signatures/. - - sudo podman image sign --sign-by foo@bar.com --directory /tmp/signatures docker://privateregistry.example.com/foobar - - sudo podman image sign --authfile=/tmp/foobar.json --sign-by foo@bar.com --directory /tmp/signatures docker://privateregistry.example.com/foobar - -## RELATED CONFIGURATION - -The write (and read) location for signatures is defined in YAML-based -configuration files in /etc/containers/registries.d/ for root, -or $HOME/.config/containers/registries.d for non-root users. When you sign -an image, Podman will use those configuration files to determine -where to write the signature based on the name of the originating -registry or a default storage value unless overridden with the --directory -option. For example, consider the following configuration file. - -docker: - privateregistry.example.com: - sigstore: file:///var/lib/containers/sigstore - -When signing an image preceded with the registry name 'privateregistry.example.com', -the signature will be written into sub-directories of -/var/lib/containers/sigstore/privateregistry.example.com. The use of 'sigstore' also means -the signature will be 'read' from that same location on a pull-related function. - -## SEE ALSO -**[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-registries.d(5)](https://github.com/containers/image/blob/main/docs/containers-registries.d.5.md)** - -## HISTORY -November 2018, Originally compiled by Qi Wang (qiwan at redhat dot com) diff --git a/docs/source/markdown/podman-image-sign.1.md.in b/docs/source/markdown/podman-image-sign.1.md.in new file mode 100644 index 000000000..340cdbd21 --- /dev/null +++ b/docs/source/markdown/podman-image-sign.1.md.in @@ -0,0 +1,71 @@ +% podman-image-sign(1) + +## NAME +podman-image-sign - Create a signature for an image + +## SYNOPSIS +**podman image sign** [*options*] *image* [*image* ...] + +## DESCRIPTION +**podman image sign** will create a local signature for one or more local images that have +been pulled from a registry. The signature will be written to a directory +derived from the registry configuration files in `$HOME/.config/containers/registries.d` if it exists, +otherwise `/etc/containers/registries.d` (unless overridden at compile-time), see **containers-registries.d(5)** for more information. +By default, the signature will be written into `/var/lib/containers/sigstore` for root and `$HOME/.local/share/containers/sigstore` for non-root users + +## OPTIONS + +#### **--all**, **-a** + +Sign all the manifests of the multi-architecture image (default false). + +@@option authfile + +#### **--cert-dir**=*path* + +Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d) +Please refer to containers-certs.d(5) for details. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--directory**, **-d**=*dir* + +Store the signatures in the specified directory. Default: /var/lib/containers/sigstore + +#### **--help**, **-h** + +Print usage statement. + +#### **--sign-by**=*identity* + +Override the default identity of the signature. + +## EXAMPLES +Sign the busybox image with the identity of foo@bar.com with a user's keyring and save the signature in /tmp/signatures/. + + sudo podman image sign --sign-by foo@bar.com --directory /tmp/signatures docker://privateregistry.example.com/foobar + + sudo podman image sign --authfile=/tmp/foobar.json --sign-by foo@bar.com --directory /tmp/signatures docker://privateregistry.example.com/foobar + +## RELATED CONFIGURATION + +The write (and read) location for signatures is defined in YAML-based +configuration files in /etc/containers/registries.d/ for root, +or $HOME/.config/containers/registries.d for non-root users. When you sign +an image, Podman will use those configuration files to determine +where to write the signature based on the name of the originating +registry or a default storage value unless overridden with the --directory +option. For example, consider the following configuration file. + +docker: + privateregistry.example.com: + sigstore: file:///var/lib/containers/sigstore + +When signing an image preceded with the registry name 'privateregistry.example.com', +the signature will be written into sub-directories of +/var/lib/containers/sigstore/privateregistry.example.com. The use of 'sigstore' also means +the signature will be 'read' from that same location on a pull-related function. + +## SEE ALSO +**[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-registries.d(5)](https://github.com/containers/image/blob/main/docs/containers-registries.d.5.md)** + +## HISTORY +November 2018, Originally compiled by Qi Wang (qiwan at redhat dot com) diff --git a/docs/source/markdown/podman-kube-play.1.md.in b/docs/source/markdown/podman-kube-play.1.md.in index 5fc183ee2..83b9f9904 100644 --- a/docs/source/markdown/podman-kube-play.1.md.in +++ b/docs/source/markdown/podman-kube-play.1.md.in @@ -112,13 +112,7 @@ and as a result environment variable `FOO` will be set to `bar` for container `c @@option annotation.container -#### **--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`. - -Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE -environment variable. `export REGISTRY_AUTH_FILE=path` +@@option authfile #### **--build** diff --git a/docs/source/markdown/podman-login.1.md b/docs/source/markdown/podman-login.1.md deleted file mode 100644 index c84b0cc99..000000000 --- a/docs/source/markdown/podman-login.1.md +++ /dev/null @@ -1,126 +0,0 @@ -% podman-login(1) - -## NAME -podman\-login - Login to a container registry - -## SYNOPSIS -**podman login** [*options*] [*registry*] - -## DESCRIPTION -**podman login** logs into a specified registry server with the correct username -and password. If the registry is not specified, the first registry under [registries.search] -from registries.conf will be used. **podman login** reads in the username and password from STDIN. -The username and password can also be set using the **username** and **password** flags. -The path of the authentication file can be specified by the user by setting the **authfile** -flag. The default path for reading and writing credentials is **${XDG\_RUNTIME\_DIR}/containers/auth.json**. -Podman will use existing credentials if the user does not pass in a username. -Podman will first search for the username and password in the **${XDG\_RUNTIME\_DIR}/containers/auth.json**, if they are not valid, -Podman will then use any existing credentials found in **$HOME/.docker/config.json**. -If those credentials are not present, Podman will create **${XDG\_RUNTIME\_DIR}/containers/auth.json** (if the file does not exist) and -will then store the username and password from STDIN as a base64 encoded string in it. -For more details about format and configurations of the auth.json file, please refer to containers-auth.json(5) - -**podman [GLOBAL OPTIONS]** - -**podman login [GLOBAL OPTIONS]** - -**podman login [OPTIONS] [REGISTRY] [GLOBAL OPTIONS]** - -## OPTIONS - -#### **--authfile**=*path* - -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json. - -Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE -environment variable. `export REGISTRY_AUTH_FILE=path` - -#### **--cert-dir**=*path* - -Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d) -Please refer to containers-certs.d(5) for details. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--get-login** - -Return the logged-in user for the registry. Return error if no login is found. - -#### **--help**, **-h** - -Print usage statement - -#### **--password**, **-p**=*password* - -Password for registry - -#### **--password-stdin** - -Take the password from stdin - -#### **--tls-verify** - -Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, -then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, -TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. - -#### **--username**, **-u**=*username* - -Username for registry - -#### **--verbose**, **-v** - -print detailed information about credential store - -## EXAMPLES - -``` -$ podman login docker.io -Username: umohnani -Password: -Login Succeeded! -``` - -``` -$ podman login -u testuser -p testpassword localhost:5000 -Login Succeeded! -``` - -``` -$ podman login --authfile authdir/myauths.json docker.io -Username: umohnani -Password: -Login Succeeded! -``` - -``` -$ podman login --tls-verify=false -u test -p test localhost:5000 -Login Succeeded! -``` - -``` -$ podman login --cert-dir /etc/containers/certs.d/ -u foo -p bar localhost:5000 -Login Succeeded! -``` - -``` -$ podman login -u testuser --password-stdin < testpassword.txt docker.io -Login Succeeded! -``` - -``` -$ echo $testpassword | podman login -u testuser --password-stdin docker.io -Login Succeeded! -``` - -``` -$ podman login quay.io --verbose -Username: myusername -Password: -Used: /run/user/1000/containers/auth.json -Login Succeeded! -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-logout(1)](podman-logout.1.md)**, **[containers-auth.json(5)](https://github.com/containers/image/blob/main/docs/containers-auth.json.5.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)** - -## HISTORY -August 2017, Originally compiled by Urvashi Mohnani diff --git a/docs/source/markdown/podman-login.1.md.in b/docs/source/markdown/podman-login.1.md.in new file mode 100644 index 000000000..6ec207a1e --- /dev/null +++ b/docs/source/markdown/podman-login.1.md.in @@ -0,0 +1,121 @@ +% podman-login(1) + +## NAME +podman\-login - Login to a container registry + +## SYNOPSIS +**podman login** [*options*] [*registry*] + +## DESCRIPTION +**podman login** logs into a specified registry server with the correct username +and password. If the registry is not specified, the first registry under [registries.search] +from registries.conf will be used. **podman login** reads in the username and password from STDIN. +The username and password can also be set using the **username** and **password** flags. +The path of the authentication file can be specified by the user by setting the **authfile** +flag. The default path for reading and writing credentials is **${XDG\_RUNTIME\_DIR}/containers/auth.json**. +Podman will use existing credentials if the user does not pass in a username. +Podman will first search for the username and password in the **${XDG\_RUNTIME\_DIR}/containers/auth.json**, if they are not valid, +Podman will then use any existing credentials found in **$HOME/.docker/config.json**. +If those credentials are not present, Podman will create **${XDG\_RUNTIME\_DIR}/containers/auth.json** (if the file does not exist) and +will then store the username and password from STDIN as a base64 encoded string in it. +For more details about format and configurations of the auth.json file, please refer to containers-auth.json(5) + +**podman [GLOBAL OPTIONS]** + +**podman login [GLOBAL OPTIONS]** + +**podman login [OPTIONS] [REGISTRY] [GLOBAL OPTIONS]** + +## OPTIONS + +@@option authfile + +#### **--cert-dir**=*path* + +Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d) +Please refer to containers-certs.d(5) for details. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--get-login** + +Return the logged-in user for the registry. Return error if no login is found. + +#### **--help**, **-h** + +Print usage statement + +#### **--password**, **-p**=*password* + +Password for registry + +#### **--password-stdin** + +Take the password from stdin + +#### **--tls-verify** + +Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, +then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, +TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. + +#### **--username**, **-u**=*username* + +Username for registry + +#### **--verbose**, **-v** + +print detailed information about credential store + +## EXAMPLES + +``` +$ podman login docker.io +Username: umohnani +Password: +Login Succeeded! +``` + +``` +$ podman login -u testuser -p testpassword localhost:5000 +Login Succeeded! +``` + +``` +$ podman login --authfile authdir/myauths.json docker.io +Username: umohnani +Password: +Login Succeeded! +``` + +``` +$ podman login --tls-verify=false -u test -p test localhost:5000 +Login Succeeded! +``` + +``` +$ podman login --cert-dir /etc/containers/certs.d/ -u foo -p bar localhost:5000 +Login Succeeded! +``` + +``` +$ podman login -u testuser --password-stdin < testpassword.txt docker.io +Login Succeeded! +``` + +``` +$ echo $testpassword | podman login -u testuser --password-stdin docker.io +Login Succeeded! +``` + +``` +$ podman login quay.io --verbose +Username: myusername +Password: +Used: /run/user/1000/containers/auth.json +Login Succeeded! +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-logout(1)](podman-logout.1.md)**, **[containers-auth.json(5)](https://github.com/containers/image/blob/main/docs/containers-auth.json.5.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)** + +## HISTORY +August 2017, Originally compiled by Urvashi Mohnani diff --git a/docs/source/markdown/podman-logout.1.md b/docs/source/markdown/podman-logout.1.md deleted file mode 100644 index 96ac98f35..000000000 --- a/docs/source/markdown/podman-logout.1.md +++ /dev/null @@ -1,60 +0,0 @@ -% podman-logout(1) - -## NAME -podman\-logout - Logout of a container registry - -## SYNOPSIS -**podman logout** [*options*] *registry* - -## DESCRIPTION -**podman logout** logs out of a specified registry server by deleting the cached credentials -stored in the **auth.json** file. If the registry is not specified, the first registry under [registries.search] -from registries.conf will be used. The path of the authentication file can be overridden by the user by setting the **authfile** flag. -The default path used is **${XDG\_RUNTIME\_DIR}/containers/auth.json**. For more details about format and configurations of the auth,json file, please refer to containers-auth.json(5) -All the cached credentials can be removed by setting the **all** flag. - -**podman [GLOBAL OPTIONS]** - -**podman logout [GLOBAL OPTIONS]** - -**podman logout [OPTIONS] REGISTRY [GLOBAL OPTIONS]** - -## OPTIONS - -#### **--all**, **-a** - -Remove the cached credentials for all registries in the auth file - -#### **--authfile**=*path* - -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json. - -Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE -environment variable. `export REGISTRY_AUTH_FILE=path` - -#### **--help**, **-h** - -Print usage statement - -## EXAMPLES - -``` -$ podman logout docker.io -Remove login credentials for https://registry-1.docker.io/v2/ -``` - -``` -$ podman logout --authfile authdir/myauths.json docker.io -Remove login credentials for https://registry-1.docker.io/v2/ -``` - -``` -$ podman logout --all -Remove login credentials for all registries -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-login(1)](podman-login.1.md)**, **[containers-auth.json(5)](https://github.com/containers/image/blob/main/docs/containers-auth.json.5.md)** - -## HISTORY -August 2017, Originally compiled by Urvashi Mohnani diff --git a/docs/source/markdown/podman-logout.1.md.in b/docs/source/markdown/podman-logout.1.md.in new file mode 100644 index 000000000..6997bb36e --- /dev/null +++ b/docs/source/markdown/podman-logout.1.md.in @@ -0,0 +1,55 @@ +% podman-logout(1) + +## NAME +podman\-logout - Logout of a container registry + +## SYNOPSIS +**podman logout** [*options*] *registry* + +## DESCRIPTION +**podman logout** logs out of a specified registry server by deleting the cached credentials +stored in the **auth.json** file. If the registry is not specified, the first registry under [registries.search] +from registries.conf will be used. The path of the authentication file can be overridden by the user by setting the **authfile** flag. +The default path used is **${XDG\_RUNTIME\_DIR}/containers/auth.json**. For more details about format and configurations of the auth,json file, please refer to containers-auth.json(5) +All the cached credentials can be removed by setting the **all** flag. + +**podman [GLOBAL OPTIONS]** + +**podman logout [GLOBAL OPTIONS]** + +**podman logout [OPTIONS] REGISTRY [GLOBAL OPTIONS]** + +## OPTIONS + +#### **--all**, **-a** + +Remove the cached credentials for all registries in the auth file + +@@option authfile + +#### **--help**, **-h** + +Print usage statement + +## EXAMPLES + +``` +$ podman logout docker.io +Remove login credentials for https://registry-1.docker.io/v2/ +``` + +``` +$ podman logout --authfile authdir/myauths.json docker.io +Remove login credentials for https://registry-1.docker.io/v2/ +``` + +``` +$ podman logout --all +Remove login credentials for all registries +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-login(1)](podman-login.1.md)**, **[containers-auth.json(5)](https://github.com/containers/image/blob/main/docs/containers-auth.json.5.md)** + +## HISTORY +August 2017, Originally compiled by Urvashi Mohnani diff --git a/docs/source/markdown/podman-manifest-add.1.md b/docs/source/markdown/podman-manifest-add.1.md deleted file mode 100644 index 5aa7f8341..000000000 --- a/docs/source/markdown/podman-manifest-add.1.md +++ /dev/null @@ -1,135 +0,0 @@ -% podman-manifest-add(1) - -## NAME -podman\-manifest\-add - Add an image to a manifest list or image index - -## SYNOPSIS -**podman manifest add** [*options*] *listnameorindexname* [*transport*]:*imagename* - -## DESCRIPTION - -Adds the specified image to the specified manifest list or image index. - -## RETURN VALUE -The list image's ID. - -## OPTIONS - -#### **--all** - -If the image which should be added to the list or index is itself a list or -index, add all of the contents to the local list. By default, only one image -from such a list or index will be added to the list or index. Combining -*--all* with any of the other options described below is NOT recommended. - -#### **--annotation**=*annotation=value* - -Set an annotation on the entry for the newly-added image. - -#### **--arch** - -Override the architecture which the list or index records as a requirement for -the image. If *imageName* refers to a manifest list or image index, the -architecture information will be retrieved from it. Otherwise, it will be -retrieved from the image's configuration information. - -#### **--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`. - -Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE -environment variable. `export REGISTRY_AUTH_FILE=path` - -#### **--cert-dir**=*path* - -Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d) -Please refer to containers-certs.d(5) for details. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--creds**=*creds* - -The [username[:password]] to use to authenticate with the registry if required. -If one or both values are not supplied, a command line prompt will appear and the -value can be entered. The password is entered without echo. - -#### **--features** - -Specify the features list which the list or index records as requirements for -the image. This option is rarely used. - -#### **--os** - -Override the OS which the list or index records as a requirement for the image. -If *imagename* refers to a manifest list or image index, the OS information -will be retrieved from it. Otherwise, it will be retrieved from the image's -configuration information. - -#### **--os-version** - -Specify the OS version which the list or index records as a requirement for the -image. This option is rarely used. - -#### **--tls-verify** - -Require HTTPS and verify certificates when talking to container registries (defaults to true). - -#### **--variant** - -Specify the variant which the list or index records for the image. This option -is typically used to distinguish between multiple entries which share the same -architecture value, but which expect different versions of its instruction set. - -## Transport - - Multiple transports are supported: - - **docker://**_docker-reference_ _(default)_ - An image in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in `$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)`. - - $ podman manifest add mylist:v1.11 docker://quay.io/username/myimage - - **containers-storage:**_oci-reference_ - An image in _oci-reference_ format stored in the local container storage. _oci-reference_ must contain a tag. - - $ podman manifest add mylist:v1.11 containers-storage:quay.io/username/myimage - - **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. - - $ podman manifest add dir:/tmp/myimage - - **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. - - $ podman manifest add docker-archive:/tmp/myimage - - **docker-daemon:**_docker-reference_ - An image in _docker-reference_ format stored in the docker daemon internal storage. The _docker-reference_ can also be an image ID (docker-daemon:algo:digest). - - $ sudo podman manifest add docker-daemon:docker.io/library/myimage:33 - - **oci-archive:**_path_**:**_tag_ - An image _tag_ in a directory compliant with "Open Container Image Layout Specification" at _path_. - - $ podman manifest add oci-archive:/tmp/myimage - -## EXAMPLE - -``` -podman manifest add mylist:v1.11 docker://fedora -71c201d10fffdcac52968a000d85a0a016ca1c7d5473948000d3131c1773d965 -``` - -``` -podman manifest add --all mylist:v1.11 docker://fedora -71c201d10fffdcac52968a000d85a0a016ca1c7d5473948000d3131c1773d965 -``` - -``` -podman manifest add --arch arm64 --variant v8 mylist:v1.11 docker://71c201d10fffdcac52968a000d85a0a016ca1c7d5473948000d3131c1773d965 -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-manifest(1)](podman-manifest.1.md)** diff --git a/docs/source/markdown/podman-manifest-add.1.md.in b/docs/source/markdown/podman-manifest-add.1.md.in new file mode 100644 index 000000000..a1c498e4f --- /dev/null +++ b/docs/source/markdown/podman-manifest-add.1.md.in @@ -0,0 +1,129 @@ +% podman-manifest-add(1) + +## NAME +podman\-manifest\-add - Add an image to a manifest list or image index + +## SYNOPSIS +**podman manifest add** [*options*] *listnameorindexname* [*transport*]:*imagename* + +## DESCRIPTION + +Adds the specified image to the specified manifest list or image index. + +## RETURN VALUE +The list image's ID. + +## OPTIONS + +#### **--all** + +If the image which should be added to the list or index is itself a list or +index, add all of the contents to the local list. By default, only one image +from such a list or index will be added to the list or index. Combining +*--all* with any of the other options described below is NOT recommended. + +#### **--annotation**=*annotation=value* + +Set an annotation on the entry for the newly-added image. + +#### **--arch** + +Override the architecture which the list or index records as a requirement for +the image. If *imageName* refers to a manifest list or image index, the +architecture information will be retrieved from it. Otherwise, it will be +retrieved from the image's configuration information. + +@@option authfile + +#### **--cert-dir**=*path* + +Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d) +Please refer to containers-certs.d(5) for details. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--creds**=*creds* + +The [username[:password]] to use to authenticate with the registry if required. +If one or both values are not supplied, a command line prompt will appear and the +value can be entered. The password is entered without echo. + +#### **--features** + +Specify the features list which the list or index records as requirements for +the image. This option is rarely used. + +#### **--os** + +Override the OS which the list or index records as a requirement for the image. +If *imagename* refers to a manifest list or image index, the OS information +will be retrieved from it. Otherwise, it will be retrieved from the image's +configuration information. + +#### **--os-version** + +Specify the OS version which the list or index records as a requirement for the +image. This option is rarely used. + +#### **--tls-verify** + +Require HTTPS and verify certificates when talking to container registries (defaults to true). + +#### **--variant** + +Specify the variant which the list or index records for the image. This option +is typically used to distinguish between multiple entries which share the same +architecture value, but which expect different versions of its instruction set. + +## Transport + + Multiple transports are supported: + + **docker://**_docker-reference_ _(default)_ + An image in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in `$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)`. + + $ podman manifest add mylist:v1.11 docker://quay.io/username/myimage + + **containers-storage:**_oci-reference_ + An image in _oci-reference_ format stored in the local container storage. _oci-reference_ must contain a tag. + + $ podman manifest add mylist:v1.11 containers-storage:quay.io/username/myimage + + **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. + + $ podman manifest add dir:/tmp/myimage + + **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. + + $ podman manifest add docker-archive:/tmp/myimage + + **docker-daemon:**_docker-reference_ + An image in _docker-reference_ format stored in the docker daemon internal storage. The _docker-reference_ can also be an image ID (docker-daemon:algo:digest). + + $ sudo podman manifest add docker-daemon:docker.io/library/myimage:33 + + **oci-archive:**_path_**:**_tag_ + An image _tag_ in a directory compliant with "Open Container Image Layout Specification" at _path_. + + $ podman manifest add oci-archive:/tmp/myimage + +## EXAMPLE + +``` +podman manifest add mylist:v1.11 docker://fedora +71c201d10fffdcac52968a000d85a0a016ca1c7d5473948000d3131c1773d965 +``` + +``` +podman manifest add --all mylist:v1.11 docker://fedora +71c201d10fffdcac52968a000d85a0a016ca1c7d5473948000d3131c1773d965 +``` + +``` +podman manifest add --arch arm64 --variant v8 mylist:v1.11 docker://71c201d10fffdcac52968a000d85a0a016ca1c7d5473948000d3131c1773d965 +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-manifest(1)](podman-manifest.1.md)** diff --git a/docs/source/markdown/podman-manifest-push.1.md b/docs/source/markdown/podman-manifest-push.1.md deleted file mode 100644 index cfe2b9230..000000000 --- a/docs/source/markdown/podman-manifest-push.1.md +++ /dev/null @@ -1,122 +0,0 @@ -% podman-manifest-push(1) - -## NAME -podman\-manifest\-push - Push a manifest list or image index to a registry - -## SYNOPSIS -**podman manifest push** [*options*] *listnameorindexname* [*destination*] - -## DESCRIPTION -Pushes a manifest list or image index to a registry. - -## RETURN VALUE -The list image's ID and the digest of the image's manifest. - -## OPTIONS - -#### **--all** - -Push the images mentioned in the manifest list or image index, in addition to -the list or index itself. (Default true) - -#### **--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`. - -Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE -environment variable. `export REGISTRY_AUTH_FILE=path` - -#### **--cert-dir**=*path* - -Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d) -Please refer to containers-certs.d(5) for details. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--compression-format**=**gzip** | *zstd* | *zstd:chunked* - -Specifies the compression format to use. Supported values are: `gzip`, `zstd` and `zstd:chunked`. The default is `gzip` unless overridden in the containers.conf file. - -#### **--creds**=*creds* - -The [username[:password]] to use to authenticate with the registry if required. -If one or both values are not supplied, a command line prompt will appear and the -value can be entered. The password is entered without echo. - -#### **--digestfile**=*Digestfile* - -After copying the image, write the digest of the resulting image to the file. - -#### **--format**, **-f**=*format* - -Manifest list type (oci or v2s2) to use when pushing the list (default is oci). - -#### **--quiet**, **-q** - -When writing the manifest, suppress progress output - -#### **--remove-signatures** - -Don't copy signatures when pushing images. - -#### **--rm** - -Delete the manifest list or image index from local storage if pushing succeeds. - -#### **--sign-by**=*fingerprint* - -Sign the pushed images with a “simple signing” signature using the specified key. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--sign-by-sigstore-private-key**=*path* - -Sign the pushed images with a sigstore signature using a private key at the specified path. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--sign-passphrase-file**=*path* - -If signing the image (using either **--sign-by** or **--sign-by-sigstore-private-key**), read the passphrase to use from the specified path. - -#### **--tls-verify** - -Require HTTPS and verify certificates when talking to container registries. (defaults to true) - -## DESTINATION - - The DESTINATION is a location to store container images - The Image "DESTINATION" uses a "transport":"details" format. - If a transport is not given, podman push will attempt to push - to a registry. - - Multiple transports are supported: - - **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. - - $ podman manifest push mylist:v1.11 dir:/tmp/mylist - - **docker://**_docker-reference_ - An image in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in `$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)`. - - $ podman manifest push mylist:v1.11 docker://registry.example.org/mylist:v1.11 - - **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. - - $ podman manifest push mylist:v1.11 docker-archive:/tmp/mylist - - **docker-daemon:**_docker-reference_ - An image in _docker-reference_ format stored in the docker daemon internal storage. _docker-reference_ must contain a tag. - - $ podman manifest push mylist:v1.11 docker-daemon:registry.example.org/mylist:v1.11 - - **oci-archive:**_path_**:**_tag_ - An image _tag_ in a directory compliant with "Open Container Image Layout Specification" at _path_. - - $ podman manifest push mylist:v1.11 oci-archive:/tmp/mylist - -## EXAMPLE - -``` -podman manifest push mylist:v1.11 docker://registry.example.org/mylist:v1.11 -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-manifest(1)](podman-manifest.1.md)** diff --git a/docs/source/markdown/podman-manifest-push.1.md.in b/docs/source/markdown/podman-manifest-push.1.md.in new file mode 100644 index 000000000..631ead376 --- /dev/null +++ b/docs/source/markdown/podman-manifest-push.1.md.in @@ -0,0 +1,116 @@ +% podman-manifest-push(1) + +## NAME +podman\-manifest\-push - Push a manifest list or image index to a registry + +## SYNOPSIS +**podman manifest push** [*options*] *listnameorindexname* [*destination*] + +## DESCRIPTION +Pushes a manifest list or image index to a registry. + +## RETURN VALUE +The list image's ID and the digest of the image's manifest. + +## OPTIONS + +#### **--all** + +Push the images mentioned in the manifest list or image index, in addition to +the list or index itself. (Default true) + +@@option authfile + +#### **--cert-dir**=*path* + +Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d) +Please refer to containers-certs.d(5) for details. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--compression-format**=**gzip** | *zstd* | *zstd:chunked* + +Specifies the compression format to use. Supported values are: `gzip`, `zstd` and `zstd:chunked`. The default is `gzip` unless overridden in the containers.conf file. + +#### **--creds**=*creds* + +The [username[:password]] to use to authenticate with the registry if required. +If one or both values are not supplied, a command line prompt will appear and the +value can be entered. The password is entered without echo. + +#### **--digestfile**=*Digestfile* + +After copying the image, write the digest of the resulting image to the file. + +#### **--format**, **-f**=*format* + +Manifest list type (oci or v2s2) to use when pushing the list (default is oci). + +#### **--quiet**, **-q** + +When writing the manifest, suppress progress output + +#### **--remove-signatures** + +Don't copy signatures when pushing images. + +#### **--rm** + +Delete the manifest list or image index from local storage if pushing succeeds. + +#### **--sign-by**=*fingerprint* + +Sign the pushed images with a “simple signing” signature using the specified key. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--sign-by-sigstore-private-key**=*path* + +Sign the pushed images with a sigstore signature using a private key at the specified path. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--sign-passphrase-file**=*path* + +If signing the image (using either **--sign-by** or **--sign-by-sigstore-private-key**), read the passphrase to use from the specified path. + +#### **--tls-verify** + +Require HTTPS and verify certificates when talking to container registries. (defaults to true) + +## DESTINATION + + The DESTINATION is a location to store container images + The Image "DESTINATION" uses a "transport":"details" format. + If a transport is not given, podman push will attempt to push + to a registry. + + Multiple transports are supported: + + **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. + + $ podman manifest push mylist:v1.11 dir:/tmp/mylist + + **docker://**_docker-reference_ + An image in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in `$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)`. + + $ podman manifest push mylist:v1.11 docker://registry.example.org/mylist:v1.11 + + **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. + + $ podman manifest push mylist:v1.11 docker-archive:/tmp/mylist + + **docker-daemon:**_docker-reference_ + An image in _docker-reference_ format stored in the docker daemon internal storage. _docker-reference_ must contain a tag. + + $ podman manifest push mylist:v1.11 docker-daemon:registry.example.org/mylist:v1.11 + + **oci-archive:**_path_**:**_tag_ + An image _tag_ in a directory compliant with "Open Container Image Layout Specification" at _path_. + + $ podman manifest push mylist:v1.11 oci-archive:/tmp/mylist + +## EXAMPLE + +``` +podman manifest push mylist:v1.11 docker://registry.example.org/mylist:v1.11 +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-manifest(1)](podman-manifest.1.md)** diff --git a/docs/source/markdown/podman-pull.1.md.in b/docs/source/markdown/podman-pull.1.md.in index 29c4f865d..cf06cc6a8 100644 --- a/docs/source/markdown/podman-pull.1.md.in +++ b/docs/source/markdown/podman-pull.1.md.in @@ -51,13 +51,7 @@ All tagged images in the repository will be pulled. @@option arch -#### **--authfile**=*path* - -Path of the authentication file. If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using `docker login`. - -Default is `${XDG\_RUNTIME\_DIR}/containers/auth.json`, which is set using `podman login`. - -*IMPORTANT: The default path of the authentication file can be overwritten by setting the `REGISTRY\_AUTH\_FILE` environment variable. `export REGISTRY_AUTH_FILE=path`* +@@option authfile #### **--cert-dir**=*path* diff --git a/docs/source/markdown/podman-push.1.md b/docs/source/markdown/podman-push.1.md deleted file mode 100644 index d674975b0..000000000 --- a/docs/source/markdown/podman-push.1.md +++ /dev/null @@ -1,169 +0,0 @@ -% podman-push(1) - -## NAME -podman\-push - Push an image, manifest list or image index from local storage to elsewhere - -## SYNOPSIS -**podman push** [*options*] *image* [*destination*] - -**podman image push** [*options*] *image* [*destination*] - -## DESCRIPTION -Pushes an image, manifest list or image index from local storage to a specified -destination. Push is mainly used to push images to registries, however -**podman push** can be used to save images to tarballs and directories using the -following transports: -**dir:**, **docker-archive:**, **docker-daemon:** and **oci-archive:**. - -## Image storage -Images are pushed from those stored in local image storage. - -## DESTINATION - - DESTINATION is the location the container image is pushed to. It supports all transports from `containers-transports(5)`. If no transport is specified, the `docker` (i.e., container registry) transport is used. For remote clients, including Mac and Windows (excluding WSL2) machines, `docker` is the only supported transport. - -``` -# Push to a container registry -$ podman push quay.io/podman/stable - -# Push to a container registry via the docker transport -$ podman push docker://quay.io/podman/stable - -# Push to a container registry with another tag -$ podman push myimage quay.io/username/myimage - -# Push to a local directory -$ podman push myimage dir:/tmp/myimage - -# Push to a tarball in the docker-archive format -$ podman push myimage docker-archive:/tmp/myimage - -# Push to a local docker daemon -$ sudo podman push myimage docker-daemon:docker.io/library/myimage:33 - -# Push to a tarball in the OCI format -$ podman push myimage oci-archive:/tmp/myimage -``` - -## 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`. - -Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE -environment variable. `export REGISTRY_AUTH_FILE=path` - -#### **--cert-dir**=*path* - -Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d) -Please refer to containers-certs.d(5) for details. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--compress** - -Compress tarball image layers when pushing to a directory using the 'dir' transport. (default is same compression type, compressed or uncompressed, as source) -Note: This flag can only be set when using the **dir** transport - -#### **--compression-format**=**gzip** | *zstd* | *zstd:chunked* - -Specifies the compression format to use. Supported values are: `gzip`, `zstd` and `zstd:chunked`. The default is `gzip` unless overridden in the containers.conf file. - -#### **--creds**=*[username[:password]]* - -The [username[:password]] to use to authenticate with the registry if required. -If one or both values are not supplied, a command line prompt will appear and the -value can be entered. The password is entered without echo. - -#### **--digestfile**=*Digestfile* - -After copying the image, write the digest of the resulting image to the file. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--disable-content-trust** - -This is a Docker specific option to disable image verification to a Docker -registry and is not supported by Podman. This flag is a NOOP and provided -solely for scripting compatibility. - -#### **--format**, **-f**=*format* - -Manifest Type (oci, v2s2, or v2s1) to use when pushing an image. - -#### **--quiet**, **-q** - -When writing the output image, suppress progress output - -#### **--remove-signatures** - -Discard any pre-existing signatures in the image. - -#### **--sign-by**=*key* - -Add a “simple signing” signature at the destination using the specified key. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--sign-by-sigstore-private-key**=*path* - -Add a sigstore signature at the destination using a private key at the specified path. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) - -#### **--sign-passphrase-file**=*path* - -If signing the image (using either **--sign-by** or **--sign-by-sigstore-private-key**), read the passphrase to use from the specified path. - -#### **--tls-verify** - -Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, -then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, -TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. - -## EXAMPLE - -This example pushes the image specified by the imageID to a local directory in docker format. - - `# podman push imageID dir:/path/to/image` - -This example pushes the image specified by the imageID to a local directory in oci format. - - `# podman push imageID oci-archive:/path/to/layout:image:tag` - -This example pushes the image specified by the imageID to a container registry named registry.example.com - - `# podman push imageID docker://registry.example.com/repository:tag` - -This example pushes the image specified by the imageID to a container registry named registry.example.com and saves the digest in the specified digestfile. - - `# podman push --digestfile=/tmp/mydigest imageID docker://registry.example.com/repository:tag` - -This example pushes the image specified by the imageID and puts it into the local docker container store - - `# podman push imageID docker-daemon:image:tag` - -This example pushes the alpine image to umohnani/alpine on dockerhub and reads the creds from -the path given to --authfile - -``` -# podman push --authfile temp-auths/myauths.json alpine docker://docker.io/umohnani/alpine -Getting image source signatures -Copying blob sha256:5bef08742407efd622d243692b79ba0055383bbce12900324f75e56f589aedb0 - 4.03 MB / 4.03 MB [========================================================] 1s -Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156 - 1.41 KB / 1.41 KB [========================================================] 1s -Writing manifest to image destination -Storing signatures -``` - -This example pushes the rhel7 image to rhel7-dir with the "oci" manifest type -``` -# podman push --format oci registry.access.redhat.com/rhel7 dir:rhel7-dir -Getting image source signatures -Copying blob sha256:9cadd93b16ff2a0c51ac967ea2abfadfac50cfa3af8b5bf983d89b8f8647f3e4 - 71.41 MB / 71.41 MB [======================================================] 9s -Copying blob sha256:4aa565ad8b7a87248163ce7dba1dd3894821aac97e846b932ff6b8ef9a8a508a - 1.21 KB / 1.21 KB [========================================================] 0s -Copying config sha256:f1b09a81455c351eaa484b61aacd048ab613c08e4c5d1da80c4c46301b03cf3b - 3.01 KB / 3.01 KB [========================================================] 0s -Writing manifest to image destination -Storing signatures -``` - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[podman-pull(1)](podman-pull.1.md)**, **[podman-login(1)](podman-login.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[containers-transports(5)](https://github.com/containers/image/blob/main/docs/containers-transports.5.md)** diff --git a/docs/source/markdown/podman-push.1.md.in b/docs/source/markdown/podman-push.1.md.in new file mode 100644 index 000000000..1c936cd66 --- /dev/null +++ b/docs/source/markdown/podman-push.1.md.in @@ -0,0 +1,163 @@ +% podman-push(1) + +## NAME +podman\-push - Push an image, manifest list or image index from local storage to elsewhere + +## SYNOPSIS +**podman push** [*options*] *image* [*destination*] + +**podman image push** [*options*] *image* [*destination*] + +## DESCRIPTION +Pushes an image, manifest list or image index from local storage to a specified +destination. Push is mainly used to push images to registries, however +**podman push** can be used to save images to tarballs and directories using the +following transports: +**dir:**, **docker-archive:**, **docker-daemon:** and **oci-archive:**. + +## Image storage +Images are pushed from those stored in local image storage. + +## DESTINATION + + DESTINATION is the location the container image is pushed to. It supports all transports from `containers-transports(5)`. If no transport is specified, the `docker` (i.e., container registry) transport is used. For remote clients, including Mac and Windows (excluding WSL2) machines, `docker` is the only supported transport. + +``` +# Push to a container registry +$ podman push quay.io/podman/stable + +# Push to a container registry via the docker transport +$ podman push docker://quay.io/podman/stable + +# Push to a container registry with another tag +$ podman push myimage quay.io/username/myimage + +# Push to a local directory +$ podman push myimage dir:/tmp/myimage + +# Push to a tarball in the docker-archive format +$ podman push myimage docker-archive:/tmp/myimage + +# Push to a local docker daemon +$ sudo podman push myimage docker-daemon:docker.io/library/myimage:33 + +# Push to a tarball in the OCI format +$ podman push myimage oci-archive:/tmp/myimage +``` + +## OPTIONS + +@@option authfile + +#### **--cert-dir**=*path* + +Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. (Default: /etc/containers/certs.d) +Please refer to containers-certs.d(5) for details. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--compress** + +Compress tarball image layers when pushing to a directory using the 'dir' transport. (default is same compression type, compressed or uncompressed, as source) +Note: This flag can only be set when using the **dir** transport + +#### **--compression-format**=**gzip** | *zstd* | *zstd:chunked* + +Specifies the compression format to use. Supported values are: `gzip`, `zstd` and `zstd:chunked`. The default is `gzip` unless overridden in the containers.conf file. + +#### **--creds**=*[username[:password]]* + +The [username[:password]] to use to authenticate with the registry if required. +If one or both values are not supplied, a command line prompt will appear and the +value can be entered. The password is entered without echo. + +#### **--digestfile**=*Digestfile* + +After copying the image, write the digest of the resulting image to the file. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--disable-content-trust** + +This is a Docker specific option to disable image verification to a Docker +registry and is not supported by Podman. This flag is a NOOP and provided +solely for scripting compatibility. + +#### **--format**, **-f**=*format* + +Manifest Type (oci, v2s2, or v2s1) to use when pushing an image. + +#### **--quiet**, **-q** + +When writing the output image, suppress progress output + +#### **--remove-signatures** + +Discard any pre-existing signatures in the image. + +#### **--sign-by**=*key* + +Add a “simple signing” signature at the destination using the specified key. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--sign-by-sigstore-private-key**=*path* + +Add a sigstore signature at the destination using a private key at the specified path. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) + +#### **--sign-passphrase-file**=*path* + +If signing the image (using either **--sign-by** or **--sign-by-sigstore-private-key**), read the passphrase to use from the specified path. + +#### **--tls-verify** + +Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, +then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, +TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. + +## EXAMPLE + +This example pushes the image specified by the imageID to a local directory in docker format. + + `# podman push imageID dir:/path/to/image` + +This example pushes the image specified by the imageID to a local directory in oci format. + + `# podman push imageID oci-archive:/path/to/layout:image:tag` + +This example pushes the image specified by the imageID to a container registry named registry.example.com + + `# podman push imageID docker://registry.example.com/repository:tag` + +This example pushes the image specified by the imageID to a container registry named registry.example.com and saves the digest in the specified digestfile. + + `# podman push --digestfile=/tmp/mydigest imageID docker://registry.example.com/repository:tag` + +This example pushes the image specified by the imageID and puts it into the local docker container store + + `# podman push imageID docker-daemon:image:tag` + +This example pushes the alpine image to umohnani/alpine on dockerhub and reads the creds from +the path given to --authfile + +``` +# podman push --authfile temp-auths/myauths.json alpine docker://docker.io/umohnani/alpine +Getting image source signatures +Copying blob sha256:5bef08742407efd622d243692b79ba0055383bbce12900324f75e56f589aedb0 + 4.03 MB / 4.03 MB [========================================================] 1s +Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156 + 1.41 KB / 1.41 KB [========================================================] 1s +Writing manifest to image destination +Storing signatures +``` + +This example pushes the rhel7 image to rhel7-dir with the "oci" manifest type +``` +# podman push --format oci registry.access.redhat.com/rhel7 dir:rhel7-dir +Getting image source signatures +Copying blob sha256:9cadd93b16ff2a0c51ac967ea2abfadfac50cfa3af8b5bf983d89b8f8647f3e4 + 71.41 MB / 71.41 MB [======================================================] 9s +Copying blob sha256:4aa565ad8b7a87248163ce7dba1dd3894821aac97e846b932ff6b8ef9a8a508a + 1.21 KB / 1.21 KB [========================================================] 0s +Copying config sha256:f1b09a81455c351eaa484b61aacd048ab613c08e4c5d1da80c4c46301b03cf3b + 3.01 KB / 3.01 KB [========================================================] 0s +Writing manifest to image destination +Storing signatures +``` + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[podman-pull(1)](podman-pull.1.md)**, **[podman-login(1)](podman-login.1.md)**, **[containers-certs.d(5)](https://github.com/containers/image/blob/main/docs/containers-certs.d.5.md)**, **[containers-registries.conf(5)](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md)**, **[containers-transports(5)](https://github.com/containers/image/blob/main/docs/containers-transports.5.md)** diff --git a/docs/source/markdown/podman-run.1.md.in b/docs/source/markdown/podman-run.1.md.in index 81b635bc8..1c02eafe9 100644 --- a/docs/source/markdown/podman-run.1.md.in +++ b/docs/source/markdown/podman-run.1.md.in @@ -100,12 +100,7 @@ error. It can even pretend to be a TTY (this is what most commandline executables expect) and pass along signals. The **-a** option can be set for each of **stdin**, **stdout**, and **stderr**. -#### **--authfile**=*[path]* - -Path to the authentication file. Default is *${XDG_RUNTIME_DIR}/containers/auth.json*. - -Note: You can also override the default path of the authentication file by setting the **REGISTRY_AUTH_FILE** -environment variable. +@@option authfile @@option blkio-weight diff --git a/docs/source/markdown/podman-search.1.md b/docs/source/markdown/podman-search.1.md deleted file mode 100644 index 5b49d7f8e..000000000 --- a/docs/source/markdown/podman-search.1.md +++ /dev/null @@ -1,150 +0,0 @@ -% podman-search(1) - -## NAME -podman\-search - Search a registry for an image - -## SYNOPSIS -**podman search** [*options*] *term* - -## DESCRIPTION -**podman search** 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., **registry.fedoraproject.org/fedora**). By default, all -unqualified-search registries in `containers-registries.conf(5)` are used. - -The default number of results is 25. The number of results can be limited using the **--limit** flag. -If more than one registry is being searched, the limit will be applied to each registry. The output can be filtered -using the **--filter** 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 **registry.fedoraproject.org/**). - -Note that **podman search** 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 will only work for registries that implement the v2 API. - -**podman [GLOBAL OPTIONS]** - -**podman search [GLOBAL OPTIONS]** - -**podman search [OPTIONS] TERM** - -## OPTIONS - -#### **--authfile**=*path* - -Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json - -Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE -environment variable. `export REGISTRY_AUTH_FILE=path` - -#### **--compatible** - -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. - -#### **--filter**, **-f**=*filter* - -Filter output based on conditions provided (default []) - -Supported filters are: - -* stars (int - number of stars the image has) -* is-automated (boolean - true | false) - is the image automated or not -* is-official (boolean - true | false) - is the image official or not - -#### **--format**=*format* - -Change the output format to a Go template - -Valid placeholders for the Go template are listed below: - -| **Placeholder** | **Description** | -| --------------- | ---------------------------- | -| .Index | Registry | -| .Name | Image name | -| .Description | Image description | -| .Stars | Star count of image | -| .Official | "[OK]" if image is official | -| .Automated | "[OK]" if image is automated | -| .Tag | Repository tag | - -Note: use .Tag only if the --list-tags is set. - -#### **--help**, **-h** - -Print usage statement - -#### **--limit**=*limit* - -Limit the number of results (default 25). -Note: The results from each registry will be limited to this value. -Example if limit is 10 and two registries are being searched, the total -number of results will be 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. - -#### **--list-tags** - -List the available tags in the repository for the specified image. -**Note:** --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. - -#### **--no-trunc** - -Do not truncate the output (default *false*). - -#### **--tls-verify** - -Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, -then TLS verification will be used. If set to false, then TLS verification will not be used if needed. If not specified, -default registries will be searched through (in /etc/containers/registries.conf), and TLS will be skipped if a default -registry is listed in the insecure registries. - -## EXAMPLES - -``` -$ podman search --limit 3 fedora -NAME DESCRIPTION -registry.centos.org/centos -registry.centos.org/cdrage/mosh-centos7 -registry.centos.org/centos/bind -docker.io/library/centos The official build of CentOS. -docker.io/jdeathe/centos-ssh OpenSSH / Supervisor / EPEL/IUS/SCL Repos - ... -docker.io/ansible/centos7-ansible Ansible on Centos7 -quay.io/centos/centos The official CentOS base containers. -quay.io/ukhomeofficedigital/centos-base -quay.io/quarkus/centos-quarkus-maven Quarkus.io builder image for building Quarku... -``` - -Note that the Stars, Official and Automated descriptors are only available on Docker Hub and are hence not displayed by default. -``` -$ 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 -``` - -``` -$ 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 - -``` -Note: This works only with registries that implement the v2 API. If tried with a v1 registry an error will be returned. - -## FILES - -**registries.conf** (`/etc/containers/registries.conf`) - -registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion. - -## SEE ALSO -**[podman(1)](podman.1.md)**, **[containers-registries(5)](https://github.com/containers/image/blob/main/docs/containers-registries.5.md)** - -## HISTORY -January 2018, Originally compiled by Urvashi Mohnani diff --git a/docs/source/markdown/podman-search.1.md.in b/docs/source/markdown/podman-search.1.md.in new file mode 100644 index 000000000..9dd8cebf8 --- /dev/null +++ b/docs/source/markdown/podman-search.1.md.in @@ -0,0 +1,145 @@ +% podman-search(1) + +## NAME +podman\-search - Search a registry for an image + +## SYNOPSIS +**podman search** [*options*] *term* + +## DESCRIPTION +**podman search** 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., **registry.fedoraproject.org/fedora**). By default, all +unqualified-search registries in `containers-registries.conf(5)` are used. + +The default number of results is 25. The number of results can be limited using the **--limit** flag. +If more than one registry is being searched, the limit will be applied to each registry. The output can be filtered +using the **--filter** 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 **registry.fedoraproject.org/**). + +Note that **podman search** 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 will only work for registries that implement the v2 API. + +**podman [GLOBAL OPTIONS]** + +**podman search [GLOBAL OPTIONS]** + +**podman search [OPTIONS] TERM** + +## OPTIONS + +@@option authfile + +#### **--compatible** + +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. + +#### **--filter**, **-f**=*filter* + +Filter output based on conditions provided (default []) + +Supported filters are: + +* stars (int - number of stars the image has) +* is-automated (boolean - true | false) - is the image automated or not +* is-official (boolean - true | false) - is the image official or not + +#### **--format**=*format* + +Change the output format to a Go template + +Valid placeholders for the Go template are listed below: + +| **Placeholder** | **Description** | +| --------------- | ---------------------------- | +| .Index | Registry | +| .Name | Image name | +| .Description | Image description | +| .Stars | Star count of image | +| .Official | "[OK]" if image is official | +| .Automated | "[OK]" if image is automated | +| .Tag | Repository tag | + +Note: use .Tag only if the --list-tags is set. + +#### **--help**, **-h** + +Print usage statement + +#### **--limit**=*limit* + +Limit the number of results (default 25). +Note: The results from each registry will be limited to this value. +Example if limit is 10 and two registries are being searched, the total +number of results will be 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. + +#### **--list-tags** + +List the available tags in the repository for the specified image. +**Note:** --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. + +#### **--no-trunc** + +Do not truncate the output (default *false*). + +#### **--tls-verify** + +Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, +then TLS verification will be used. If set to false, then TLS verification will not be used if needed. If not specified, +default registries will be searched through (in /etc/containers/registries.conf), and TLS will be skipped if a default +registry is listed in the insecure registries. + +## EXAMPLES + +``` +$ podman search --limit 3 fedora +NAME DESCRIPTION +registry.centos.org/centos +registry.centos.org/cdrage/mosh-centos7 +registry.centos.org/centos/bind +docker.io/library/centos The official build of CentOS. +docker.io/jdeathe/centos-ssh OpenSSH / Supervisor / EPEL/IUS/SCL Repos - ... +docker.io/ansible/centos7-ansible Ansible on Centos7 +quay.io/centos/centos The official CentOS base containers. +quay.io/ukhomeofficedigital/centos-base +quay.io/quarkus/centos-quarkus-maven Quarkus.io builder image for building Quarku... +``` + +Note that the Stars, Official and Automated descriptors are only available on Docker Hub and are hence not displayed by default. +``` +$ 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 +``` + +``` +$ 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 + +``` +Note: This works only with registries that implement the v2 API. If tried with a v1 registry an error will be returned. + +## FILES + +**registries.conf** (`/etc/containers/registries.conf`) + +registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion. + +## SEE ALSO +**[podman(1)](podman.1.md)**, **[containers-registries(5)](https://github.com/containers/image/blob/main/docs/containers-registries.5.md)** + +## HISTORY +January 2018, Originally compiled by Urvashi Mohnani -- cgit v1.2.3-54-g00ecf